musica 0.11.1.1__cp312-cp312-win_amd64.whl → 0.14.2__cp312-cp312-win_amd64.whl

musica/mechanism_configuration/mechanism.py

@@ -0,0 +1,93 @@
+# Copyright (C) 2025 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+#
+# This file is part of the musica Python package.
+# For more information, see the LICENSE file in the top-level directory of this distribution.
+import os
+import json
+import yaml
+from typing import Optional, Any, Dict, List
+from .. import backend
+
+from .species import Species
+from .phase import Phase
+from .reactions import Reactions
+from .ancillary import Version
+
+_backend = backend.get_backend()
+Mechanism = _backend._mechanism_configuration._Mechanism
+
+original_init = Mechanism.__init__
+
+
+def export(self, file_path: str) -> None:
+    directory, file = os.path.split(file_path)
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+
+    dictionary = self.serialize()
+
+    _, file_ext = os.path.splitext(file)
+    file_ext = file_ext.lower()
+    if file_ext in ['.yaml', '.yml']:
+        with open(file_path, 'w') as file:
+            yaml.dump(dictionary, file)
+    elif '.json' == file_ext:
+        json_str = json.dumps(dictionary, indent=4)
+        with open(file_path, 'w') as file:
+            file.write(json_str)
+    else:
+        raise ValueError(
+            'Allowable write formats are .json, .yaml, and .yml')
+
+
+def __init__(
+    self,
+    name: Optional[str] = None,
+    reactions: Optional[List[Any]] = None,
+    species: Optional[List[Species]] = None,
+    phases: Optional[List[Phase]] = None,
+    version: Optional[Version] = None,
+):
+    """
+    Initializes the Mechanism object with the given parameters.
+
+    Args:
+        name (str): The name of the mechanism.
+        reactions (List[]): A list of reactions in the mechanism.
+        species (List[Species]): A list of species in the mechanism.
+        phases (List[Phase]): A list of phases in the mechanism.
+        version (Version): The version of the mechanism.
+    """
+    original_init(self)
+    self.name = name
+    self.species = species if species is not None else []
+    self.phases = phases if phases is not None else []
+    self.reactions = Reactions(reactions=reactions if reactions is not None else [])
+    self.version = version if version is not None else Version()
+
+
+def serialize(self) -> Dict:
+    return {
+        "name": self.name,
+        "reactions": [r.serialize() for r in self.reactions],
+        "species": [s.serialize() for s in self.species],
+        "phases": [p.serialize() for p in self.phases],
+        "version": self.version.to_string(),
+    }
+
+
+Mechanism.__doc__ = """
+    A class representing a chemical mechanism.
+
+    Attributes:
+        name (str): The name of the mechanism.
+        reactions (List[Reaction]): A list of reactions in the mechanism.
+        species (List[Species]): A list of species in the mechanism.
+        phases (List[Phase]): A list of phases in the mechanism.
+        version (Version): The version of the mechanism.
+    """
+
+Mechanism.__init__ = __init__
+Mechanism.serialize = serialize
+Mechanism.export = export

musica/mechanism_configuration/phase.py

@@ -0,0 +1,58 @@
+from typing import Optional, Any, Dict, List, Union
+from .. import backend
+from .species import Species
+from .phase_species import PhaseSpecies
+from .utils import _add_other_properties, _remove_empty_keys
+
+_backend = backend.get_backend()
+Phase = _backend._mechanism_configuration._Phase
+Phase.__doc__ = """
+    A class representing a phase in a chemical mechanism.
+
+    Attributes:
+        name (str): The name of the phase.
+        species (List[Species]): A list of species in the phase.
+        other_properties (Dict[str, Any]): A dictionary of other properties of the phase.
+    """
+
+original_init = Phase.__init__
+
+
+def init(
+    self,
+    name: Optional[str] = None,
+    species: Optional[Union[List[Species], List[PhaseSpecies]]] = None,
+    other_properties: Optional[Dict[str, Any]] = None,
+):
+    """
+    Initializes the Phase object with the given parameters.
+
+    Args:
+        name (str): The name of the phase.
+        species (List[Species]): A list of species in the phase.
+        other_properties (Dict[str, Any]): A dictionary of other properties of the phase.
+    """
+    original_init(self)
+    self.name = name if name is not None else self.name
+    converted_species = []
+    if species is not None:
+        for s in species:
+            if isinstance(s, PhaseSpecies):
+                converted_species.append(s)
+            elif isinstance(s, Species):
+                converted_species.append(PhaseSpecies(name=s.name))
+    self.species = converted_species
+    self.other_properties = other_properties if other_properties is not None else self.other_properties
+
+
+def serialize(instance):
+    serialize_dict = {
+        "name": instance.name,
+        "species": [s.serialize() for s in instance.species],
+    }
+    _add_other_properties(serialize_dict, instance.other_properties)
+    return _remove_empty_keys(serialize_dict)
+
+
+Phase.__init__ = init
+Phase.serialize = serialize

musica/mechanism_configuration/phase_species.py

@@ -0,0 +1,58 @@
+from typing import Optional, Any, Dict
+from .. import backend
+from .utils import _add_other_properties, _remove_empty_keys
+
+_backend = backend.get_backend()
+PhaseSpecies = _backend._mechanism_configuration._PhaseSpecies
+original_init = PhaseSpecies.__init__
+
+
+def __init__(
+    self,
+    name: Optional[str] = None,
+    diffusion_coefficient_m2_s: Optional[float] = None,
+    other_properties: Optional[Dict[str, Any]] = None,
+):
+    """
+    Initializes the PhaseSpecies object with the given parameters.
+
+    Args:
+        name (str): The name of the species.
+        diffusion_coefficient_m2_s (float): Diffusion coefficient [m2 s-1]
+        other_properties (Dict[str, Any]): A dictionary of other properties of the species.
+    """
+    original_init(self)
+    self.name = name if name is not None else self.name
+    self.diffusion_coefficient_m2_s = diffusion_coefficient_m2_s if diffusion_coefficient_m2_s is not None else self.diffusion_coefficient_m2_s
+    self.other_properties = other_properties if other_properties is not None else self.other_properties
+
+
+def serialize(self) -> Dict:
+    serialize_dict = {
+        "name": self.name,
+        "diffusion coefficient [m2 s-1]": self.diffusion_coefficient_m2_s,
+    }
+    _add_other_properties(serialize_dict, self.other_properties)
+    return _remove_empty_keys(serialize_dict)
+
+
+def equals(self, other):
+    return self.name == other.name and self.diffusion_coefficient_m2_s == other.diffusion_coefficient_m2_s
+
+
+PhaseSpecies.__doc__ = """
+    Represents a chemical species within a specific phase of a mechanism,
+    including phase-specific properties such as diffusion coefficients.
+
+    This class is distinct from a regular Species class in that it models
+    properties relevant to the species' behavior in a particular phase
+    (e.g., gas, liquid, or solid), such as the diffusion coefficient.
+
+    Attributes:
+        name (str): The name of the species.
+        diffusion_coefficient_m2_s (float): Diffusion coefficient in the phase [m2 s-1].
+        other_properties (Dict[str, Any]): A dictionary of other phase-specific properties of the species.
+    """
+PhaseSpecies.__init__ = __init__
+PhaseSpecies.serialize = serialize
+PhaseSpecies.__eq__ = equals

musica/mechanism_configuration/photolysis.py

@@ -0,0 +1,98 @@
+from .utils import _add_other_properties
+from .species import Species
+from .phase import Phase
+from typing import Optional, Any, Dict, List, Union, Tuple
+from .. import backend
+from .reaction_component import ReactionComponent
+from .ancillary import ReactionType
+
+_backend = backend.get_backend()
+Photolysis = _backend._mechanism_configuration._Photolysis
+
+original_init = Photolysis.__init__
+
+
+@property
+def type(self):
+    return ReactionType.Photolysis
+
+
+def __init__(
+    self,
+    name: Optional[str] = None,
+    scaling_factor: Optional[float] = None,
+    reactants: Optional[List[Union[Species, Tuple[float, Species]]]] = None,
+    products: Optional[List[Union[Species, Tuple[float, Species]]]] = None,
+    gas_phase: Optional[Phase] = None,
+    other_properties: Optional[Dict[str, Any]] = None,
+):
+    """
+    Initializes the Photolysis object with the given parameters.
+
+    Args:
+        name (str): The name of the photolysis reaction rate constant.
+        scaling_factor (float): The scaling factor for the photolysis rate constant.
+        reactants (List[Union[Species, Tuple[float, Species]]]): A list of reactants involved in the reaction.
+        products (List[Union[Species, Tuple[float, Species]]]): A list of products formed in the reaction.
+        gas_phase (Phase): The gas phase in which the reaction occurs.
+        other_properties (Dict[str, Any]): A dictionary of other properties of the photolysis reaction rate constant.
+    """
+    original_init(self)
+    self.name = name if name is not None else self.name
+    self.scaling_factor = scaling_factor if scaling_factor is not None else self.scaling_factor
+    self.reactants = (
+        [
+            (
+                ReactionComponent(r.name)
+                if isinstance(r, Species)
+                else ReactionComponent(r[1].name, r[0])
+            )
+            for r in reactants
+        ]
+        if reactants is not None
+        else self.reactants
+    )
+    self.products = (
+        [
+            (
+                ReactionComponent(p.name)
+                if isinstance(p, Species)
+                else ReactionComponent(p[1].name, p[0])
+            )
+            for p in products
+        ]
+        if products is not None
+        else self.products
+    )
+    self.gas_phase = gas_phase.name if gas_phase is not None else self.gas_phase
+    self.other_properties = other_properties if other_properties is not None else self.other_properties
+
+
+def serialize(self) -> Dict:
+    serialize_dict = {
+        "type": "PHOTOLYSIS",
+        "name": self.name,
+        "scaling factor": self.scaling_factor,
+        "reactants": [r.serialize() for r in self.reactants],
+        "products": [r.serialize() for r in self.products],
+        "gas phase": self.gas_phase,
+    }
+    _add_other_properties(serialize_dict, self.other_properties)
+    return serialize_dict
+
+
+Photolysis.__doc__ = """
+A class representing a photolysis reaction rate constant.
+
+Attributes:
+    name (str): The name of the photolysis reaction rate constant.
+    scaling_factor (float): The scaling factor for the photolysis rate constant.
+    reactants (List[Union[Species, Tuple[float, Species]]]): A list of reactants involved in the reaction.
+    products (List[Union[Species, Tuple[float, Species]]]): A list of products formed in the reaction.
+    gas_phase (Phase): The gas phase in which the reaction occurs.
+    other_properties (Dict[str, Any]): A dictionary of other properties of the photolysis reaction rate constant.
+"""
+
+Photolysis.__init__ = __init__
+Photolysis.serialize = serialize
+Photolysis.type = type

musica/mechanism_configuration/reaction_component.py

@@ -0,0 +1,54 @@
+from typing import Optional, Any, Dict
+from .. import backend
+from .utils import _add_other_properties, _remove_empty_keys
+
+_backend = backend.get_backend()
+ReactionComponent = _backend._mechanism_configuration._ReactionComponent
+original_init = ReactionComponent.__init__
+
+
+def __init__(
+    self,
+    name: Optional[str] = None,
+    coefficient: Optional[float] = 1.0,
+    other_properties: Optional[Dict[str, Any]] = None,
+):
+    """
+    Initializes the ReactionComponent object with the given parameters.
+
+    Args:
+        name (str): The name of the species.
+        coefficient (float): The stichiometric coefficient
+        other_properties (Dict[str, Any]): A dictionary of other properties of the species.
+    """
+    original_init(self)
+    self.species_name = name if name is not None else self.species_name
+    self.coefficient = coefficient if coefficient is not None else self.coefficient
+    self.other_properties = other_properties if other_properties is not None else self.other_properties
+
+
+def serialize(self) -> Dict:
+    serialize_dict = {
+        "species name": self.species_name,
+        "coefficient": self.coefficient,
+        "other_properties": self.other_properties,
+    }
+    _add_other_properties(serialize_dict, self.other_properties)
+    return _remove_empty_keys(serialize_dict)
+
+
+ReactionComponent.__doc__ = """
+    A class representing a reaction component in a chemical reaction.
+
+    A reaction component typically consists of a chemical species, its stoichiometric coefficient in the reaction,
+    and any additional properties relevant to its role in the reaction.
+
+    Attributes:
+        species_name (str): The name of the chemical species involved in the reaction.
+        coefficient (float): The stoichiometric coefficient of the species in the reaction.
+        other_properties (Dict[str, Any]): A dictionary of other properties relevant to the reaction component.
+    """
+
+
+ReactionComponent.__init__ = __init__
+ReactionComponent.serialize = serialize

musica/mechanism_configuration/reactions.py

@@ -0,0 +1,32 @@
+from typing import Optional, Any, Dict, List, Union
+from .. import backend
+from .species import Species
+from .utils import _remove_empty_keys
+
+_backend = backend.get_backend()
+Reactions = _backend._mechanism_configuration._Reactions
+
+original_init = Reactions.__init__
+
+Reactions.__doc__ = """
+A class representing a collection of reactions in a chemical mechanism.
+
+Attributes:
+    reactions (List[Any]): A list of reactions in the mechanism.
+"""
+
+
+def __init__(
+    self,
+    reactions: Optional[List[Any]] = None,
+):
+    """
+    Initializes the Reactions object with the given parameters.
+
+    Args:
+        reactions (List[]): A list of reactions in the mechanism.
+    """
+    original_init(self, reactions)
+
+
+Reactions.__init__ = __init__

musica/mechanism_configuration/species.py

@@ -0,0 +1,65 @@
+from typing import Optional, Any, Dict
+from .. import backend
+from .utils import _add_other_properties, _remove_empty_keys
+
+_backend = backend.get_backend()
+Species = _backend._mechanism_configuration._Species
+original_init = Species.__init__
+
+
+def __init__(
+    self,
+    name: Optional[str] = None,
+    molecular_weight_kg_mol: Optional[float] = None,
+    constant_concentration_mol_m3: Optional[float] = None,
+    constant_mixing_ratio_mol_mol: Optional[float] = None,
+    is_third_body: Optional[bool] = False,
+    other_properties: Optional[Dict[str, Any]] = None,
+):
+    """
+    Initializes the Species object with the given parameters.
+
+    Args:
+        name (str): The name of the species.
+        molecular_weight_kg_mol (float): Molecular weight [kg mol-1]
+        constant_concentration_mol_m3 (float): Constant concentration of the species (mol m-3)
+        constant_mixing_ratio_mol_mol (float): Constant mixing ratio of the species (mol mol-1)
+        is_third_body (bool): Whether the species is a third body.
+        other_properties (Dict[str, Any]): A dictionary of other properties of the species.
+    """
+    original_init(self)
+    self.name = name if name is not None else self.name
+    self.molecular_weight_kg_mol = molecular_weight_kg_mol if molecular_weight_kg_mol is not None else self.molecular_weight_kg_mol
+    self.constant_concentration_mol_m3 = constant_concentration_mol_m3 if constant_concentration_mol_m3 is not None else self.constant_concentration_mol_m3
+    self.constant_mixing_ratio_mol_mol = constant_mixing_ratio_mol_mol if constant_mixing_ratio_mol_mol is not None else self.constant_mixing_ratio_mol_mol
+    self.is_third_body = is_third_body
+    self.other_properties = other_properties if other_properties is not None else self.other_properties
+
+
+def serialize(self) -> Dict:
+    serialize_dict = {
+        "name": self.name,
+        "molecular weight [kg mol-1]": self.molecular_weight_kg_mol,
+        "constant concentration [mol m-3]": self.constant_concentration_mol_m3,
+        "constant mixing ratio [mol mol-1]": self.constant_mixing_ratio_mol_mol,
+        "is third body": self.is_third_body,
+    }
+    _add_other_properties(serialize_dict, self.other_properties)
+    return _remove_empty_keys(serialize_dict)
+
+
+Species.__doc__ = """
+    A class representing a species in a chemical mechanism.
+
+    Attributes:
+        name (str): The name of the species.
+        molecular_weight_kg_mol (float): Molecular weight [kg mol-1]
+        constant_concentration_mol_m3 (float): Constant concentration of the species (mol m-3)
+        constant_mixing_ratio_mol_mol (float): Constant mixing ratio of the species (mol mol-1)
+        is_third_body (bool): Whether the species is a third body.
+        other_properties (Dict[str, Any]): A dictionary of other properties of the species.
+    """
+
+
+Species.__init__ = __init__
+Species.serialize = serialize

musica/mechanism_configuration/surface.py

@@ -0,0 +1,98 @@
+from typing import Optional, Any, Dict, List, Union, Tuple
+from .. import backend
+from .phase import Phase
+from .species import Species
+from .utils import _add_other_properties, _remove_empty_keys
+from .reaction_component import ReactionComponent
+from .ancillary import ReactionType
+
+_backend = backend.get_backend()
+Surface = _backend._mechanism_configuration._Surface
+
+original_init = Surface.__init__
+
+
+@property
+def type(self):
+    return ReactionType.Surface
+
+
+def __init__(
+    self,
+    name: Optional[str] = None,
+    reaction_probability: Optional[float] = None,
+    gas_phase_species: Optional[Union[Species,
+                                      Tuple[float, Species]]] = None,
+    gas_phase_products: Optional[
+        List[Union[Species, Tuple[float, Species]]]
+    ] = None,
+    gas_phase: Optional[Phase] = None,
+    other_properties: Optional[Dict[str, Any]] = None,
+):
+    """
+    Initializes the Surface object with the given parameters.
+
+    Args:
+        name (str): The name of the surface.
+        reaction_probability (float): The probability of a reaction occurring on the surface.
+        gas_phase_species (Union[Species, Tuple[float, Species]]): The gas phase species involved in the reaction.
+        gas_phase_products (List[Union[Species, Tuple[float, Species]]]): The gas phase products formed in the reaction.
+        gas_phase (Phase): The gas phase in which the reaction occurs.
+        other_properties (Dict[str, Any]): A dictionary of other properties of the surface.
+    """
+    original_init(self)
+    self.name = name if name is not None else self.name
+    self.reaction_probability = reaction_probability if reaction_probability is not None else self.reaction_probability
+    self.gas_phase_species = (
+        (
+            ReactionComponent(gas_phase_species.name)
+            if isinstance(gas_phase_species, Species)
+            else ReactionComponent(gas_phase_species[1].name, gas_phase_species[0])
+        )
+        if gas_phase_species is not None
+        else self.gas_phase_species
+    )
+    self.gas_phase_products = (
+        [
+            (
+                ReactionComponent(p.name)
+                if isinstance(p, Species)
+                else ReactionComponent(p[1].name, p[0])
+            )
+            for p in gas_phase_products
+        ]
+        if gas_phase_products is not None
+        else self.gas_phase_products
+    )
+    self.gas_phase = gas_phase.name if gas_phase is not None else self.gas_phase
+    self.other_properties = other_properties if other_properties is not None else self.other_properties
+
+
+def serialize(self) -> Dict:
+    serialize_dict = {
+        "type": "SURFACE",
+        "name": self.name,
+        "reaction probability": self.reaction_probability,
+        "gas-phase species": self.gas_phase_species.species_name,
+        "gas-phase products": [r.serialize() for r in self.gas_phase_products],
+        "gas phase": self.gas_phase,
+    }
+    _add_other_properties(serialize_dict, self.other_properties)
+    return _remove_empty_keys(serialize_dict)
+
+
+Surface.__doc__ = """
+A class representing a surface in a chemical mechanism.
+
+Attributes:
+    name (str): The name of the surface.
+    reaction_probability (float): The probability of a reaction occurring on the surface.
+    gas_phase_species (Union[Species, Tuple[float, Species]]): The gas phase species involved in the reaction.
+    gas_phase_products (List[Union[Species, Tuple[float, Species]]]): The gas phase products formed in the reaction.
+    gas_phase (Phase): The gas phase in which the reaction occurs.
+    other_properties (Dict[str, Any]): A dictionary of other properties of the surface.
+"""
+
+Surface.__init__ = __init__
+Surface.serialize = serialize
+Surface.type = type