uclchem.makerates ================= .. py:module:: uclchem.makerates .. autoapi-nested-parse:: UCLCHEM MakeRates Module. Chemical network builder for UCLCHEM. MakeRates is UCLCHEM's system for building custom chemical networks from reaction databases (UMIST, KIDA) and user-defined reactions. It generates all files needed to compile UCLCHEM with your network. **Key Components:** - :class:`MakeratesConfig` - Configure network generation settings - :class:`Network` - Chemical network container - :class:`Reaction` - Individual reaction object - :class:`Species` - Chemical species object - :func:`build_network` - Build network from reaction databases - :func:`run_makerates` - Execute the full MakeRates workflow **Quick Example:** >>> from uclchem.makerates.config import MakeratesConfig >>> from uclchem.makerates import run_makerates >>> >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> makerates_dir = UCLCHEM_ROOT_DIR / "../../Makerates/data" >>> >>> # Configure network builder >>> config = MakeratesConfig( ... species_file = makerates_dir / "default/default_species.csv", ... database_reaction_file = makerates_dir / "databases/umist22.csv", ... database_reaction_type = "UMIST", ... custom_reaction_file = makerates_dir/"default/default_grain_network.csv", ... custom_reaction_type = "UCL", ... output_directory = "./network_files/", ... ) >>> >>> # Generate network, write all necessary Fortran files >>> network = run_makerates(config) >>> print(f"Reactions: {len(network.get_reaction_list())}") Reactions: ... **Workflow:** 1. **Configure**: Create :class:`MakeratesConfig` with input files 2. **Build**: Use :func:`build_network` or :func:`run_makerates` 3. **Validate**: Check for missing species, duplicate reactions 4. **Export**: Generate Fortran source files for compilation **Network Databases:** MakeRates can read reactions from: - **UMIST Database**: Gas-phase astrochemical reactions - **KIDA Database**: Kinetics Database for Astrochemistry - **Custom CSV files**: User-defined reactions **Reaction Format:** Reactions are typically defined in CSV with columns: - Reactants (R1, R2) - Products (P1, P2, P3, P4) - Reaction type code - Rate coefficients (alpha, beta, gamma) **Species Format:** Species defined in CSV with: - Name (chemical formula) - Mass (amu) - Binding energy (K) - Enthalpy of formation (K) **Advanced Features:** - Three-phase chemistry (gas, surface, bulk ice) - Surface reaction types (Langmuir-Hinshelwood, Eley-Rideal) - Thermal and non-thermal desorption - Freeze-out and grain surface reactions - Network optimization and validation **Example - Adding Custom Reactions:** >>> from uclchem.makerates.network import Network, load_network_from_csv >>> from uclchem.makerates.reaction import Reaction >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> >>> # Load existing network >>> network = load_network_from_csv( ... UCLCHEM_ROOT_DIR / "species.csv", ... UCLCHEM_ROOT_DIR / "reactions.csv", ... ) >>> >>> # Add custom reaction >>> alpha = 1.0e-10 >>> beta = 0.0 >>> gamma = 0.0 >>> templow = 0.0 >>> temphigh = 10000.0 >>> custom_reaction = Reaction( ... ["H", "CO", "NAN", "HCO", "NAN", "NAN", "NAN", alpha, beta, gamma, templow, temphigh], ... ) >>> network.add_reactions(custom_reaction) >>> >>> # Export modified network >>> io_functions.write_reactions("custom_reactions.csv", network.get_reaction_list()) **Configuration Files:** MakeRates uses YAML configuration: .. code-block:: yaml # user_settings.yaml reaction_files: - grain_reactions.csv - umist12_reactions.csv species_file: species.csv output_dir: ./output freeze_out_reactions: True three_phase: True **See Also:** - User guide for complete MakeRates documentation - GitHub repository for example networks - UMIST/KIDA database documentation **Note:** Each UCLCHEM installation compiles one network. To change networks, rebuild UCLCHEM with different MakeRates output. Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 cli/index.rst config/index.rst heating/index.rst io_functions/index.rst makerates/index.rst network/index.rst network_builder/index.rst network_compat/index.rst reaction/index.rst species/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: uclchem.makerates.BaseNetwork uclchem.makerates.MakeratesConfig uclchem.makerates.MutableNetworkABC uclchem.makerates.Network uclchem.makerates.NetworkABC uclchem.makerates.Reaction uclchem.makerates.Species Functions ~~~~~~~~~ .. autoapisummary:: uclchem.makerates.build_network uclchem.makerates.create_network uclchem.makerates.load_network_from_csv uclchem.makerates.run_makerates .. py:class:: BaseNetwork Bases: :py:obj:`NetworkABC` Base implementation providing common network operations. Implements all read and query operations that are common between Network and RuntimeNetwork. Both classes store data in _species_dict and _reactions_dict, so this base class can implement all the shared logic. Subclasses only need to: 1. Initialize _species_dict and _reactions_dict 2. Implement modification methods (change_binding_energy, change_reaction_barrier) 3. Optionally implement add/remove operations (MutableNetworkABC) .. py:method:: find_similar_reactions(reaction: uclchem.makerates.reaction.Reaction) -> dict[int, uclchem.makerates.reaction.Reaction] Find reactions with same reactants and products. :param reaction: Reaction to find similar reactions for :type reaction: Reaction :returns: Dictionary of {index: Reaction} for matching reactions :rtype: dict[int, Reaction] .. py:method:: get_reaction(reaction_idx: int) -> uclchem.makerates.reaction.Reaction Get a reaction by index (copy). :param reaction_idx: Index of the reaction :type reaction_idx: int :returns: copy of reaction with index reaction_idx. :rtype: Reaction .. py:method:: get_reaction_dict() -> dict[int, uclchem.makerates.reaction.Reaction] Get reactions dictionary (copy). :returns: copy of reaction dictionary, with keys of the indices and values of the reactions. :rtype: dict[int, Reaction] .. py:method:: get_reaction_index(reaction: uclchem.makerates.reaction.Reaction) -> int Get the index of a reaction in the network. :param reaction: Reaction to find :type reaction: Reaction :returns: Index of the reaction :rtype: int :raises ValueError: If reaction not found or multiple matches exist .. py:method:: get_reaction_list() -> list[uclchem.makerates.reaction.Reaction] Get all reactions as a list. :returns: list of all reactions in the Network. :rtype: list[Reaction] .. py:method:: get_reactions_by_types(reaction_type: str | list[str]) -> list[uclchem.makerates.reaction.Reaction] Get all reactions of specific type(s). :param reaction_type: Single type or list of types to filter by :type reaction_type: str | list[str] :returns: List of reactions matching the type(s) :rtype: list[Reaction] .. py:method:: get_specie(specie_name: str) -> uclchem.makerates.species.Species Get a species by name (copy). :param specie_name: species name :type specie_name: str :returns: copy of Species instance. :rtype: Species .. py:method:: get_species_dict() -> dict[str, uclchem.makerates.species.Species] Get species dictionary (copy). :returns: copy of species dictionary, with keys of the names of the species, and values their Species instances. :rtype: dict[str, Species] .. py:method:: get_species_list() -> list[uclchem.makerates.species.Species] Get all species as a list. :returns: list of all species in the Network. :rtype: list[Species] .. py:property:: reactions :type: dict[int, uclchem.makerates.reaction.Reaction] Get reactions dictionary. :returns: Ordered dict of reactions in the network, keyed by index. :rtype: dict[int, Reaction] .. py:property:: species :type: dict[str, uclchem.makerates.species.Species] Get species dictionary. :returns: Ordered dict of species in the network, keyed by name. :rtype: dict[str, Species] .. py:class:: MakeratesConfig(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Configuration for UCLCHEM Makerates chemical network generation. This class validates all configuration parameters and provides sensible defaults where appropriate. All file paths are resolved relative to the configuration file location. .. rubric:: Examples >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> config = MakeratesConfig.from_yaml(UCLCHEM_ROOT_DIR/ "../../Makerates/user_settings.yaml") >>> print(config.species_file) data/default/default_species.csv Create a new model by parsing and validating input data from keyword arguments. Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model. `self` is explicitly positional-only to allow `self` as a field name. .. py:method:: auto_enable_rates_storage() -> MakeratesConfig Automatically enable rates storage if needed for exothermicity. :returns: validated MakeratesConfig. :rtype: MakeratesConfig .. py:method:: check_three_phase_deprecation() -> MakeratesConfig Raise error if ``three_phase`` is explicitly set to False. :returns: validated MakeratesConfig. :rtype: MakeratesConfig :raises ValueError: If ``three_phase`` is False. .. py:method:: from_yaml(yaml_path: str | pathlib.Path) -> MakeratesConfig :classmethod: Load and validate configuration from a YAML file. All relative paths in the config file are resolved relative to the directory containing the YAML file. :param yaml_path: Path to the YAML configuration file :type yaml_path: str | Path :returns: Validated MakeratesConfig instance :rtype: MakeratesConfig :raises FileNotFoundError: If config file doesn't exist .. py:method:: generate_template(output_path: str | pathlib.Path = 'user_settings_template.yaml') :classmethod: Generate a template configuration file with all parameters documented. :param output_path: Where to write the template file. Default = "user_settings_template.yaml" :type output_path: str | Path .. py:method:: get_all_reaction_files() -> list[pathlib.Path] Get all reaction files (database + custom) as resolved paths. :returns: **files** -- List of absolute paths to all reaction files :rtype: list[Path] .. py:method:: get_all_reaction_types() -> list[ReactionFileTypes] Get all reaction types (database + custom) in correct order. :returns: **types** -- list of reaction type strings :rtype: list[ReactionFileTypes] .. py:method:: log_configuration() -> None Log the current configuration for debugging. .. py:method:: normalize_coolants_file(v: str | pathlib.Path | None) -> pathlib.Path | None :classmethod: Normalize a single coolant file path to a Path object. :param v: string to normalize :type v: str | Path | None :returns: Path instance, or None if v is None :rtype: Path | None :raises TypeError: If coolants_file is not a string or Path instance. .. py:method:: normalize_to_list(v: str | pathlib.Path | list | None) -> list[str | pathlib.Path] | None :classmethod: Convert single values to lists for consistent handling. :param v: variable to make consistent. :type v: str | Path | list | None :returns: list of strings or paths, or None if v is None :rtype: list[str | Path] | None .. py:method:: normalize_type_to_list(v: str | list[str] | None) -> list[str] | None :classmethod: Convert single type strings to lists for consistent handling. :param v: variable to convert to list :type v: str | list[str] | None :returns: **v** -- list of string, or None if original v is None :rtype: list[str] | None .. py:method:: print_help() :classmethod: Print detailed help about all configuration parameters. .. py:method:: resolve_path(path: str | pathlib.Path) -> pathlib.Path Resolve a path relative to the configuration file directory. :param path: Path to resolve (can be absolute or relative) :type path: str | Path :returns: Resolved absolute Path :rtype: Path .. py:method:: validate_coolants(v: list[dict[str, str]] | None) -> list[dict[str, str | float]] | None :classmethod: Validate inline coolants format. :param v: variable to make consistent :type v: list[dict[str, str]] | None :returns: **validated** -- list of validated coolant dictionaries :rtype: list[dict[str, str | float]] | None :raises TypeError: If v is not a list of dictionaries. :raises KeyError: If entries in v do not contain keys 'file' and 'name' :raises ValueError: If entries in v with keys 'file' are not bare file names. .. py:method:: validate_coolants_mutual_exclusion() -> MakeratesConfig Ensure coolants and coolants_file are mutually exclusive. :returns: validated MakeratesConfig. :rtype: MakeratesConfig :raises ValueError: If both `coolants` and `coolants_file` are specified. .. py:method:: validate_reaction_files_and_types() -> MakeratesConfig Ensure reaction files and types are consistent. :returns: validated MakeratesConfig. :rtype: MakeratesConfig :raises ValueError: If the length of reaction files and reaction file types is not the same :raises ValueError: If `custom_reaction_type` is not specified but `custom_reaction_file` is. .. py:attribute:: add_crp_photo_to_grain :type: bool :value: None .. py:attribute:: coolant_data_dir :type: pathlib.Path | None :value: None .. py:attribute:: coolants :type: list[dict] | None :value: None .. py:attribute:: coolants_file :type: pathlib.Path | None :value: None .. py:attribute:: custom_reaction_file :type: pathlib.Path | list[pathlib.Path] | None :value: None .. py:attribute:: custom_reaction_type :type: ReactionFileTypes | list[ReactionFileTypes] | None :value: None .. py:attribute:: database_reaction_exothermicity :type: list[pathlib.Path] | None :value: None .. py:attribute:: database_reaction_file :type: pathlib.Path | list[pathlib.Path] :value: None .. py:attribute:: database_reaction_type :type: ReactionFileTypes | list[ReactionFileTypes] :value: None .. py:attribute:: derive_reaction_exothermicity :type: bool | str | list[str] :value: None .. py:attribute:: enable_rates_storage :type: bool :value: None .. py:attribute:: gas_phase_extrapolation :type: bool :value: None .. py:attribute:: grain_assisted_recombination_file :type: pathlib.Path | None :value: None .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:attribute:: output_directory :type: pathlib.Path | None :value: None .. py:attribute:: species_file :type: pathlib.Path :value: None .. py:attribute:: three_phase :type: bool :value: None .. py:class:: MutableNetworkABC Bases: :py:obj:`NetworkABC` Extended interface for networks that support full CRUD operations. Adds add/remove/set operations for species and reactions on top of the base NetworkABC interface. Used by the Network class for build-time and analysis-time operations. NOT implemented by RuntimeNetwork since the Fortran-backed network is read directly from the fortran files, only allowing for the editing of existing reaction and species parameters. .. py:method:: add_reactions(reactions: uclchem.makerates.reaction.Reaction | list) -> None :abstractmethod: Add one or more reactions to the network. :param reactions: Reactions to add to the network. :type reactions: Reaction | list .. py:method:: add_species(species: uclchem.makerates.species.Species | list) -> None :abstractmethod: Add one or more species to the network. :param species: Species instance or list of species to add. :type species: Species | list .. py:method:: remove_reaction(reaction: uclchem.makerates.reaction.Reaction) -> None :abstractmethod: Remove a reaction from the network. :param reaction: Reaction instance to look up or modify. :type reaction: Reaction .. py:method:: remove_reaction_by_index(reaction_idx: int) -> None :abstractmethod: Remove a reaction by its index. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int .. py:method:: remove_species(specie_name: str) -> None :abstractmethod: Remove a species from the network. :param specie_name: Name of the species. :type specie_name: str .. py:method:: set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) -> None :abstractmethod: Set/update a reaction at a specific index. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int :param reaction: Reaction instance to look up or modify. :type reaction: Reaction .. py:method:: set_reaction_dict(new_dict: dict[int, uclchem.makerates.reaction.Reaction]) -> None :abstractmethod: Replace the entire reaction dictionary. :param new_dict: Replacement reactions dictionary. :type new_dict: dict[int, Reaction] .. py:method:: set_specie(species_name: str, species: uclchem.makerates.species.Species) -> None :abstractmethod: Set/update a species in the network. :param species_name: Name of the species. :type species_name: str :param species: Species instance or list of species to add. :type species: Species .. py:method:: set_species_dict(new_species_dict: dict[str, uclchem.makerates.species.Species]) -> None :abstractmethod: Replace the entire species dictionary. :param new_species_dict: Replacement species dictionary. :type new_species_dict: dict[str, Species] .. py:method:: sort_reactions() -> None :abstractmethod: Sort reactions by type and reactants. .. py:method:: sort_species() -> None :abstractmethod: Sort species by type and mass. .. py:class:: Network(species_dict: dict[str, uclchem.makerates.species.Species], reaction_dict: dict[int, uclchem.makerates.reaction.Reaction]) Bases: :py:obj:`BaseNetwork`, :py:obj:`MutableNetworkABC` Universal network representation for build and analysis contexts. A single Network class that serves all use cases: - Build time: Full validation and automatic reaction generation - Analysis time: Fast loading of compiled networks from CSV The Network class can be created via: - Direct instantiation: Network(species_dict, reaction_dict) - Factory methods: from_csv(), from_lists(), build() - Factory functions: load_network_from_csv(), build_network(), etc. All creation methods produce a Network instance that implements the full NetworkABC interface, ensuring consistent access patterns. For runtime parameter modification during model execution, use RuntimeNetwork from uclchem.advanced.runtime_network instead. .. attribute:: _species_dict Internal species storage {name: Species} :type: dict[str, Species] .. attribute:: _reactions_dict Internal reaction storage {index: Reaction} :type: dict[int, Reaction] .. rubric:: Examples >>> # Load for analysis >>> network = Network.from_csv() >>> # Build with validation >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> >>> species_list, user_defined_bulk = read_species_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv" ... ) >>> reactions_list, dropped_reactions = read_reaction_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv", ... species_list, ... "UCL", ... ) >>> network = Network.build( # doctest: +SKIP ... species_list, reactions_list, gas_phase_extrapolation=True ... ) Initialize network with species and reactions. This is the low-level constructor. Most users should prefer factory methods: - Network.from_csv() for analysis - Network.from_lists() for direct instantiation - Network.build() for full build with validation Or use the module-level factory functions for clearer documentation. For runtime parameter modification, use RuntimeNetwork from uclchem.advanced.runtime_network instead. :param species_dict: Species dictionary {name: Species} :type species_dict: dict[str, Species] :param reaction_dict: Reaction dictionary {index: Reaction} :type reaction_dict: dict[int, Reaction] .. py:method:: add_reactions(reactions: uclchem.makerates.reaction.Reaction | list) -> None Add reactions to network. :param reactions: Reaction object, list of Reactions, or CSV-style entries :type reactions: Reaction | list :raises ValueError: If there is an error when converting the CSV-style entries to Reaction instances :raises TypeError: If input was not a Reaction, list of Reaction instances, or CSV-style entries. .. py:method:: add_species(species: uclchem.makerates.species.Species | list) -> None Add species to network. :param species: Species object, list of Species, or CSV-style entries :type species: Species | list :raises ValueError: If there is an error when converting the CSV-style entries to Species instances :raises TypeError: If input was not a Species, list of Species instances, or CSV-style entries. .. py:method:: build(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction], **build_options) -> Network :classmethod: Build network with full validation and automatic generation. This is the primary method for building new networks with full validation, automatic reaction generation (freeze-out, desorption, bulk), branching ratio checks, and all build-time operations. Delegates to NetworkBuilder. :param species: List of Species objects :type species: list[Species] :param reactions: List of Reaction objects :type reactions: list[Reaction] :param \*\*build_options: Options passed to NetworkBuilder: - user_defined_bulk: List of user-defined bulk species - gas_phase_extrapolation: bool (default False) - add_crp_photo_to_grain: bool (default False) - derive_reaction_exothermicity: list[str] or None - database_reaction_exothermicity: list[Union[str, Path]] or None :type \*\*build_options: dict :returns: Fully built and validated network :rtype: Network .. rubric:: Examples >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> >>> species_list, user_defined_bulk = read_species_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv" ... ) >>> reactions_list, dropped_reactions = read_reaction_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv", ... species_list, ... "UCL", ... ) >>> network = Network.build( # doctest: +SKIP ... species=species_list, ... reactions=reactions_list, ... gas_phase_extrapolation=True, ... add_crp_photo_to_grain=True ... ) .. py:method:: change_binding_energy(specie: str, new_binding_energy: float) -> None Change binding energy of a species. Handles special case of @H2O which affects other bulk species. :param specie: string representation of species :type specie: str :param new_binding_energy: new binding energy in K :type new_binding_energy: float :raises ValueError: If `specie` is not in the network. .. py:method:: change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) -> None Change activation barrier of a reaction. Looks up reaction in Network by its reactants and products. If Fortran interface is available, also updates Fortran. :param reaction: Reaction to change. :type reaction: Reaction :param barrier: New reaction barrier in K :type barrier: float :raises RuntimeError: If multiple matching reactions are found in the network. .. py:method:: from_csv(species_path: str | bytes | pathlib.Path | None = None, reactions_path: str | bytes | pathlib.Path | None = None) -> Network :classmethod: Load network from CSV files. Loads a pre-compiled network from CSV files without any validation or automatic generation. This is the primary method for loading networks for analysis purposes. :param species_path: Path to species CSV (None = use default installation) :type species_path: str | bytes | Path | None :param reactions_path: Path to reactions CSV (None = use default installation) :type reactions_path: str | bytes | Path | None :returns: Loaded network instance :rtype: Network .. rubric:: Examples >>> # Load default compiled network >>> network = Network.from_csv() >>> # Load old/custom network for analysis >>> network = Network.from_csv('old/species.csv', 'old/reactions.csv') # doctest: +SKIP .. py:method:: from_lists(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction]) -> Network :classmethod: Create network directly from lists. Direct instantiation from species and reaction lists without any validation or automatic generation. Useful for programmatic network construction or as a base for NetworkBuilder. :param species: List of Species objects :type species: list[Species] :param reactions: List of Reaction objects :type reactions: list[Reaction] :returns: Network instance :rtype: Network .. rubric:: Examples >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> >>> species_list, user_defined_bulk = read_species_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv" ... ) >>> reactions_list, dropped_reactions = read_reaction_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv", ... species_list, ... "UCL", ... ) >>> network = Network.from_lists(species_list, reactions_list) # doctest: +SKIP .. py:method:: get_all_partners(reaction: uclchem.makerates.reaction.Reaction) -> list[uclchem.makerates.reaction.Reaction] Get a list of all reactions that have ``reaction`` as their partner. :param reaction: Reaction :type reaction: Reaction :returns: **reactions_coupled_to_reaction** -- List of reactions that have ``reaction`` as their partner. :rtype: list[Reaction] :raises RuntimeError: If the partner of a :class:`CoupledReaction` instance in the network is None. .. py:method:: get_reactions_by_types(reaction_type: str | list[str]) -> list[uclchem.makerates.reaction.Reaction] Get the union of all reactions of a certain type. :param reaction_type: The reaction type to filter on :type reaction_type: str | list[str] :returns: A list of reactions of the specified type :rtype: list[Reaction] .. py:method:: remove_reaction(reaction: uclchem.makerates.reaction.Reaction) -> None Remove a reaction from network. :param reaction: Reaction to remove from the network. :type reaction: Reaction :raises RuntimeError: If multiple matching reactions are found in the network. .. py:method:: remove_reaction_by_index(reaction_idx: int) -> None Remove a reaction by its index. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int .. py:method:: remove_species(specie_name: str) -> None Remove a species from network. :param specie_name: Name of the species. :type specie_name: str .. py:method:: set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) -> None Set/update a reaction at specific index. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int :param reaction: Reaction instance to look up or modify. :type reaction: Reaction :raises AssertionError: If setting the reaction changes the total count of reactions. .. py:method:: set_reaction_dict(new_dict: dict[int, uclchem.makerates.reaction.Reaction]) -> None Replace entire reaction dictionary. :param new_dict: Replacement reactions dictionary. :type new_dict: dict[int, Reaction] .. py:method:: set_specie(species_name: str, species: uclchem.makerates.species.Species) -> None Set/update a species. :param species_name: Name of the species. :type species_name: str :param species: Species instance or list of species to add. :type species: Species .. py:method:: set_species_dict(new_species_dict: dict[str, uclchem.makerates.species.Species]) -> None Replace entire species dictionary. :param new_species_dict: Replacement species dictionary. :type new_species_dict: dict[str, Species] .. py:method:: sort_reactions() -> None Sort reactions by type and first reactant. :raises AssertionError: If sorting changes the total count of reactions. .. py:method:: sort_species() -> None Sort species by type and mass, with electron last. .. py:attribute:: add_crp_photo_to_grain :type: bool :value: False .. py:attribute:: database_reaction_exothermicity :type: list[str | pathlib.Path] | None :value: None .. py:attribute:: derive_reaction_exothermicity :type: list[str] | None :value: None .. py:attribute:: enthalpies_present :type: bool :value: False .. py:attribute:: excited_species :type: bool :value: False .. py:attribute:: important_reactions :type: dict[str, int | None] .. py:property:: species :type: dict[str, uclchem.makerates.species.Species] Get species dictionary. :returns: Ordered dict of species in the network, keyed by name. :rtype: dict[str, Species] .. py:attribute:: species_indices :type: dict[str, int] .. py:attribute:: user_defined_bulk :type: list :value: [] .. py:class:: NetworkABC Bases: :py:obj:`abc.ABC` Base abstract class defining the read-only network interface. Defines operations common to ALL network types: reading data, querying, and modifying existing parameters. Does NOT include add/remove operations since some implementations (like RuntimeNetwork) have fixed structure. This interface is implemented by: - Network: Full interactive network (via MutableNetworkABC) - RuntimeNetwork: Fortran-backed runtime network (read + parameter modification only) .. py:method:: change_binding_energy(specie: str, new_binding_energy: float) -> None :abstractmethod: Change binding energy of an existing species. :param specie: Name of the species. :type specie: str :param new_binding_energy: New binding energy in Kelvin. :type new_binding_energy: float .. py:method:: change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) -> None :abstractmethod: Change activation barrier of an existing reaction. :param reaction: Reaction instance to look up or modify. :type reaction: Reaction :param barrier: New reaction barrier in Kelvin. :type barrier: float .. py:method:: find_similar_reactions(reaction: uclchem.makerates.reaction.Reaction) -> dict[int, uclchem.makerates.reaction.Reaction] :abstractmethod: Find reactions with same reactants/products. :param reaction: Reaction instance to look up or modify. :type reaction: Reaction .. py:method:: get_reaction(reaction_idx: int) -> uclchem.makerates.reaction.Reaction :abstractmethod: Get a specific reaction by index. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int .. py:method:: get_reaction_dict() -> dict[int, uclchem.makerates.reaction.Reaction] :abstractmethod: Get the reactions dictionary. .. py:method:: get_reaction_index(reaction: uclchem.makerates.reaction.Reaction) -> int :abstractmethod: Get the unique index of a reaction. :param reaction: Reaction instance to look up or modify. :type reaction: Reaction .. py:method:: get_reaction_list() -> list[uclchem.makerates.reaction.Reaction] :abstractmethod: Get all reactions in the network. .. py:method:: get_reactions_by_types(reaction_type: str | list[str]) -> list[uclchem.makerates.reaction.Reaction] :abstractmethod: Get all reactions of specific type(s). :param reaction_type: Reaction type label to filter on (e.g. ``'MA'``, ``'DR'``). :type reaction_type: str | list[str] .. py:method:: get_specie(specie_name: str) -> uclchem.makerates.species.Species :abstractmethod: Get a specific species by name. :param specie_name: Name of the species. :type specie_name: str .. py:method:: get_species_dict() -> dict[str, uclchem.makerates.species.Species] :abstractmethod: Get the species dictionary. .. py:method:: get_species_list() -> list[uclchem.makerates.species.Species] :abstractmethod: Get all species in the network. .. py:property:: reactions :type: dict[int, uclchem.makerates.reaction.Reaction] :abstractmethod: Get the reactions collection. .. py:property:: species :type: dict[str, uclchem.makerates.species.Species] :abstractmethod: Get the species collection. .. py:class:: Reaction(input_row: list[str | float] | Reaction, reaction_source: str | None = None) Representation of reactions. Initialize a Reaction object. :param input_row: Either a Reaction object to copy, or a list/array with reaction data :type input_row: list[str | float] | Reaction :param reaction_source: Optional source identifier for the reaction. Default = None. :type reaction_source: str | None :raises ValueError: If the length of `input_row` is not long enough. .. py:method:: changes_surface_count() -> bool Check whether a grain reaction changes number of particles on the surface. 2 reactants to 2 products won't but two reactants combining to one will. :returns: whether the number of ice molecules changes by this reaction. :rtype: bool .. py:method:: changes_total_mantle() -> bool Check if the total grains on the mantle are changed by the reaction. :returns: Whether the total ice abundance is affected by this reaction. :rtype: bool .. py:method:: check_charge_conservation() -> None Check that the charge is conserved by this reaction. Grain reactions don't need to conserve charge, because grains can absorb/release electrons, so they are ignored. :raises ValueError: If charge is not conserved by the reaction. .. py:method:: check_element_conservation() -> None Check the conservation of elements. :raises ValueError: If the elements are not conserved by the reaction. .. py:method:: check_temperature_collision(other: Reaction) -> bool Check if two reactions have overlapping temperature ranges. Returning True means there is a collision. :param other: Another reaction :type other: Reaction :returns: Whether there is a collision (True), or not (False) :rtype: bool :raises NotImplementedError: If `other` is not a `Reaction` instance. Currently we can only compare against instantiated Reaction objects. .. py:method:: convert_gas_to_surf() -> None Convert the gas-phase species to surface species in place for this reaction. If any ions are produced, the ion is assumed to become neutral because it is on the surface. If any electrons are produced, they are assumed to be absorbed by the grain. .. py:method:: convert_surf_to_bulk() -> None Convert the surface species to bulk species in place for this reaction. .. py:method:: generate_ode_bit(i: int, species_names: list[str]) -> None Generate the ODE string of this reaction. :param i: index of reaction in network in python format (counting from 0) :type i: int :param species_names: List of species names so we can find index of reactants in species list :type species_names: list[str] .. py:method:: get_alpha() -> float Get the alpha parameter from the Kooij-Arrhenius equation. :returns: the alpha parameter of the reaction :rtype: float .. py:method:: get_beta() -> float Get the beta parameter from the Kooij-Arrhenius equation. :returns: the beta parameter of the reaction :rtype: float .. py:method:: get_exothermicity() -> float Get the cooling/heating for the reaction in erg s^-1. :returns: the reaction enthalpy change :rtype: float .. py:method:: get_extrapolation() -> bool Get whether extrapolation is applied for this reaction. :returns: whether extrapolation is applied. :rtype: bool .. py:method:: get_gamma() -> float Get the gamma parameter from the Kooij-Arrhenius equation. :returns: the gamma parameter of the reaction :rtype: float .. py:method:: get_products() -> list[str] Get the four products present in the reaction,. padded with NAN for nonexistent entries. :returns: The four products names :rtype: list[str] .. py:method:: get_pure_products() -> list[str] Get only the pure species that are products,. no reaction types and NAN entries. :returns: The list of produced species. :rtype: list[str] .. py:method:: get_pure_reactants() -> list[str] Get only the pure species, no reaction types and NAN entries. :returns: The list of reacting species. :rtype: list[str] .. py:method:: get_reactants() -> list[str] Get the four reactants present in the reaction,. padded with NAN for nonexistent entries. :returns: The four reactants names :rtype: list[str] .. py:method:: get_reaction_type() -> str Get the type of a reaction from the reactants. First check the third reactant for a reaction type, then the second. If there are none in there, it will be regarded as a two body reaction. :returns: reaction type :rtype: str .. py:method:: get_reduced_mass() -> float Get the reduced mass to be used to calculate tunneling rate in. atomic mass units. :returns: reduced mass of moving atoms :rtype: float .. py:method:: get_sorted_products() -> list[str] Get the four products present in the reaction,. sorted for fast comparisons. :returns: The four sorted products names :rtype: list[str] .. py:method:: get_sorted_reactants() -> list[str] Get the four reactants present in the reaction,. sorted for fast comparisons. :returns: The four sorted reactant names :rtype: list[str] .. py:method:: get_source() -> str | None Get the source of the reaction. :returns: The source of the reaction :rtype: str | None .. py:method:: get_temphigh() -> float Get the higher temperature boundary of the reaction in Kelvin. :returns: the higher temperature boundary :rtype: float .. py:method:: get_templow() -> float Get the lower temperature boundary of the reaction in Kelvin. :returns: the lower temperature boundary :rtype: float .. py:method:: is_bulk_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = False) -> bool Check whether it is a bulk reaction. Defaults to non-strict since many. important bulk reactions interact with the surface. By default it is NOT strict (strict=False); any species in the bulk returns true If strict=True; all species must be on the ice phase :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool :param include_products: Include the products. Defaults to True. :type include_products: bool :param strict: Choose between all (true) or any (false) must in the bulk. Defaults to False. :type strict: bool :returns: Is it a bulk reaction? :rtype: bool .. py:method:: is_gas_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = True) -> bool Check whether it is a gas reaction. By default it is strict - all. reactions must be in the gas-phase - if strict=False; any reaction in the gas-phase returns true. :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool :param include_products: Include the products. Defaults to True. :type include_products: bool :param strict: Choose between all (true) or any (false) must be gas phase. Defaults to True. :type strict: bool :returns: Is it a gas phase reaction? :rtype: bool .. py:method:: is_ice_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = True) -> bool Check whether it is an ice (surface OR bulk) reaction. By default it is strict (strict=True); all species must be in the ice phase If strict=False; any species in ice phase returns True :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool :param include_products: Include the products. Defaults to True. :type include_products: bool :param strict: Choose between all (true) or any (false) must be ice phase. Defaults to True. :type strict: bool :returns: Is it an ice phase reaction? :rtype: bool .. py:method:: is_surface_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = False) -> bool Check whether it is a surface reaction. Defaults to non-strict since many. important surface reactions can lead to desorption in some way. By default it is NOT strict (strict=False); any species on the surface returns true If strict=True; all species must be on the ice phase :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool :param include_products: Include the products. Defaults to True. :type include_products: bool :param strict: Choose between all (true) or any (false) must be on the surface. Defaults to False. :type strict: bool :returns: Is it a surface reaction? :rtype: bool .. py:method:: predict_reduced_mass() -> None Predict the reduced mass of the tunneling particle in this reaction. This is used in the calculation of the tunneling rates. .. rubric:: Examples >>> reaction = Reaction(["#CH3OH", "#H", "LH", "#CH3O", "#H2", "NAN", "NAN"] + [0] * 10) >>> # Setting a custom reduced mass >>> reaction.set_reduced_mass(20.0) >>> >>> # The custom reduced mass that we set. >>> reaction.get_reduced_mass() 20.0 >>> # Predicting the reduced mass of the reaction >>> reaction.predict_reduced_mass() >>> reaction.get_reduced_mass() 1.0 >>> # It is called upon Reaction instantiation >>> reaction = Reaction(["#CH3OH", "#OH", "LH", "#CH3O", "#H2O", "NAN", "NAN"] + [0] * 10) >>> reaction.get_reduced_mass() # mass of atomic hydrogen 1.0 .. py:method:: set_alpha(alpha: float) -> None Set the alpha parameter from the Kooij-Arrhenius equation. :param alpha: the alpha parameter of the reaction :type alpha: float .. py:method:: set_beta(beta: float) -> None Set the beta parameter from the Kooij-Arrhenius equation. :param beta: the beta parameter of the reaction :type beta: float .. py:method:: set_exothermicity(rate: float) -> None Set the cooling/heating for the reaction in erg s^-1. :param rate: the reaction enthalpy change :type rate: float .. py:method:: set_extrapolation(flag: bool) -> None Set whether extrapolation is applied for this reaction. :param flag: whether extrapolation is applied. :type flag: bool :raises AssertionError: If ``flag`` is not a boolean. .. py:method:: set_gamma(gamma: float) -> None Set the gamma parameter from the Kooij-Arrhenius equation. :param gamma: the gamma parameter of the reaction :type gamma: float .. py:method:: set_products(products: list[str]) -> None Set the four products present in the reaction, padded with NAN for nonexistent entries. :param products: The four products names :type products: list[str] .. py:method:: set_reactants(reactants: list[str]) -> None Set the four reactants present in the reaction,. padded with NAN for nonexistent entries. :param reactants: The four reactants names :type reactants: list[str] .. py:method:: set_reduced_mass(reduced_mass: float) -> None Set the reduced mass to be used to calculate tunneling rate in. atomic mass units. :param reduced_mass: reduced mass of moving atoms :type reduced_mass: float .. py:method:: set_source(source: str) -> None Set the source of the reaction. :param source: The source of the reaction :type source: str .. py:method:: set_temphigh(temphigh: float) -> None Set the higher temperature boundary of the reaction in Kelvin. :param temphigh: the higher temperature boundary :type temphigh: float .. py:method:: set_templow(templow: float) -> None Set the lower temperature boundary of the reaction in Kelvin. :param templow: the lower temperature boundary :type templow: float .. py:method:: to_UCL_format() -> str Convert a reaction to UCLCHEM reaction file format. :returns: string representing species :rtype: str .. py:attribute:: body_count :value: -1 .. py:attribute:: duplicate :value: False .. py:attribute:: source :value: None .. py:class:: Species(input_row: list[str | float] | pandas.Series) Species is a class that holds all the information about an individual species in the. network. It also has convenience functions to check whether the species is a gas or grain species and to help compare between species. Parse a species row. Uses the new extended order: NAME,MASS,BINDING_ENERGY,SOLID_FRACTION,MONO_FRACTION,VOLCANO_FRACTION,ENTHALPY, DESORPTION_PREF,DIFFUSION_BARRIER,DIFFUSION_PREF,Ix,Iy,Iz,SYMMETRYFACTOR Falls back to sensible defaults when fields are missing. :param input_row: Row from the species CSV, as a list of values. :type input_row: list[str | float] | pd.Series .. py:method:: add_default_freeze() -> None Add a default freezeout, which is freezing out to the species itself,. but with no ionization. .. py:method:: calculate_rotational_partition_factor() -> float Calculate 1/sigma*(SQRT(IxIyIz)) for non-linear molecules, and. 1/sigma*(SQRT(IyIz)) for linear molecules. Returns -999.0 if molecular inertia data is not available (backward compatibility). This signals that TST prefactors cannot be used for this species. :returns: Rotational partition factor scaled by 1e50, or -999.0 if unavailable :rtype: float .. py:method:: check_symmetry_factor() -> None Check the symmetry factor provided by the user. Checks if n_atoms == 2, that if its homoatomic (e.g. H2), that sigma == 2, and if it is heteroatomic, (e.g. OH), sigma == 1 .. py:method:: find_constituents(quiet: bool = False) -> collections.Counter[str] Loop through the species' name and work out what its constituent. atoms are. Then calculate mass and alert user if it doesn't match input mass. :param quiet: If ``True``, suppress warnings about unknown constituents. Defaults to ``False``. :type quiet: bool :returns: Counter of how many times each element is in the molecule. :rtype: Counter[str] :raises ValueError: If the molecular formula is not valid, for example it has an element not in the element list, has no closing bracket, or starts with a digit. .. rubric:: Examples >>> species = Species(['H2'] + [0] * 10) >>> constituents = species.find_constituents() >>> # Has the right number of H atoms >>> constituents['H'] 2 >>> # And 0 of the other atoms >>> constituents['O'] 0 >>> species = Species(['(CH3)2'] + [0] * 10) >>> constituents = species.find_constituents() >>> constituents['C'], constituents["H"] (2, 6) >>> species = Species(['C60'] + [0] * 10) >>> constituents = species.find_constituents() >>> constituents['C'] 60 .. py:method:: get_Ix() -> float Set the moment of inertia along the first principal axis. :returns: moment of inertia in amu/Angstrom^2 :rtype: float .. py:method:: get_Iy() -> float Set the moment of inertia along the second principal axis. :returns: moment of inertia in amu/Angstrom^2 :rtype: float .. py:method:: get_Iz() -> float Set the moment of inertia along the third principal axis. :returns: moment of inertia in amu/Angstrom^2 :rtype: float .. py:method:: get_binding_energy() -> float Get the binding energy of the species in K. :returns: The binding energy in K :rtype: float .. py:method:: get_charge() -> int Get the charge of the chemical species in e. Positive integer indicates positive ion, negative indicates negative ion. Assumes species are at most charged +1 or -1. :returns: The charge of the species :rtype: int .. py:method:: get_desorb_products() -> list[str] Obtain the desorbtion products of ice species. :returns: The desorption products :rtype: list[str] :raises AttributeError: If the species has no attribute `desorb_products`. This can occur if the species is a gas-phase species. .. py:method:: get_desorption_pref() -> float Get the desorption prefactor. Alias getter matching CSV column name `desorption_pref`. :returns: The desorption prefactor in s-1 :rtype: float .. py:method:: get_diffusion_barrier() -> float Get the diffusion barrier for the species. :returns: The diffusion barrier in K :rtype: float .. py:method:: get_diffusion_pref() -> float Set the diffusion prefactor. Alias getter matching CSV column name `diffusion_pref`. :returns: The diffusion prefactor in s-1 :rtype: float .. py:method:: get_enthalpy() -> float Get the ice enthalpy of the species. :returns: The ice enthalpy :rtype: float .. py:method:: get_freeze_alpha(product_list: list[str]) -> float Obtain the freeze out ratio of a species for a certain reaction. :param product_list: For a specific reaction, get the freezeout ratio :type product_list: list[str] :returns: The freezeout ratio :rtype: float .. py:method:: get_freeze_products() -> collections.abc.Iterator[tuple[list[str], float]] Obtain the product to which the species freeze out. :Yields: *tuple[list[str], float]* -- Iterator that returns all of the freeze out reactions with ratios .. py:method:: get_freeze_products_list() -> list[list[str]] Get all the freeze products without their ratios. :returns: List of freeze products :rtype: list[list[str]] .. py:method:: get_mass() -> int Get the molecular mass of the chemical species. :returns: The molecular mass in atomic mass units. :rtype: int .. py:method:: get_mono_fraction() -> float Get the monolayer fraction of the species. :returns: The monolayer fraction :rtype: float .. py:method:: get_n_atoms() -> int Get the number of atoms in the molecule. :returns: The number of atoms :rtype: int .. py:method:: get_name() -> str Get the name of the chemical species. :returns: The name :rtype: str .. py:method:: get_solid_fraction() -> float Get the solid fraction of the species. :returns: The solid fraction :rtype: float .. py:method:: get_standard_desorb_products() -> list[str] Return the 1:1 gas-phase counterpart by stripping the grain prefix. For #CH4 returns [CH4, NAN, NAN, NAN]. Always a single product — used for gasIceList construction and auto-generated THERM/DESOH2/DESCR/DEUVCR reactions when the user has not provided explicit ones. :returns: [base_gas_species, NAN, NAN, NAN] :rtype: list[str] .. py:method:: get_symmetry_factor() -> int Get the symmetry factor of the species. :returns: Symmetry factor :rtype: int .. py:method:: get_vdes() -> float Get the desorption prefactor. :returns: The desorption prefactor in s-1 :rtype: float .. py:method:: get_vdiff() -> float Get the diffusion prefactor. :returns: The diffusion prefactor in s-1 :rtype: float .. py:method:: get_volcano_fraction() -> float Get the volcano fraction of the species. :returns: The volcano fraction :rtype: float .. py:method:: is_bulk_species() -> bool Check if the species is in the bulk. :returns: True if a bulk species :rtype: bool .. py:method:: is_grain_species() -> bool Return whether the species is a species on the grain. :returns: True if it is a grain species. :rtype: bool .. py:method:: is_ice_species() -> bool Return whether the species is a species on the grain. :returns: True if it is an ice species. :rtype: bool .. py:method:: is_ion() -> bool Check if the species is ionized, either positively or negatively. :returns: True if it is ionized :rtype: bool .. py:method:: is_linear() -> bool Check if molecule is linear based on moment of inertia. For linear molecules, Ix = 0 (rotation axis along molecular axis has no inertia). :returns: True if linear, False otherwise :rtype: bool .. py:method:: is_surface_species() -> bool Check if the species is on the surface. :returns: True if a surface species :rtype: bool .. py:method:: set_Ix(Ix: float) -> None Set the moment of inertia along the first principal axis. :param Ix: desired moment of inertia (in amu/Angstrom^2) :type Ix: float .. py:method:: set_Iy(Iy: float) -> None Set the moment of inertia along the second principal axis. :param Iy: desired moment of inertia (in amu/Angstrom^2) :type Iy: float .. py:method:: set_Iz(Iz: float) -> None Set the moment of inertia along the third principal axis. :param Iz: desired moment of inertia (in amu/Angstrom^2) :type Iz: float .. py:method:: set_binding_energy(binding_energy: float) -> None Set the binding energy of the species in K. :param binding_energy: The new binding energy in K :type binding_energy: float .. py:method:: set_desorb_products(new_desorbs: list[str]) -> None Set the desorption products for species on the surface or in the bulk. It is assumed that there is only one desorption pathway. :param new_desorbs: The new desorption products :type new_desorbs: list[str] .. py:method:: set_desorption_pref(vdes: float) -> None Set the desorption prefactor. Alias setter matching CSV column name `desorption_pref`. :param vdes: The desorption prefactor in s-1 :type vdes: float .. py:method:: set_diffusion_barrier(barrier: float) -> None Set the diffusion barrier for the species. :param barrier: Diffusion barrier in K :type barrier: float .. py:method:: set_diffusion_pref(vdiff: float) -> None Set the diffusion prefactor. Alias setter matching CSV column name `diffusion_pref`. :param vdiff: The diffusion prefactor in s-1 :type vdiff: float .. py:method:: set_enthalpy(enthalpy: float) -> None Set the enthalpy of the species in kcal per mole. :param enthalpy: The new ice enthalpy :type enthalpy: float .. py:method:: set_freeze_products(product_list: list[str], freeze_alpha: float) -> None Add the freeze products of the species, one species can have. several freeze products. :param product_list: The list of freeze out products :type product_list: list[str] :param freeze_alpha: The freeze out ratio. :type freeze_alpha: float .. py:method:: set_mass(mass: int) -> None Set the molecular mass of the chemical species in atomic mass units. :param mass: The new molecular mass :type mass: int .. py:method:: set_mono_fraction(mono_fraction: float) -> None Set the monolayer fraction of the species. :param mono_fraction: The new monolayer fraction :type mono_fraction: float .. py:method:: set_n_atoms(new_n_atoms: int) -> None Set the number of atoms. :param new_n_atoms: The new number of atoms :type new_n_atoms: int .. py:method:: set_name(name: str) -> None Set the name of the chemical species. :param name: The new name for the species :type name: str .. py:method:: set_solid_fraction(solid_fraction: float) -> None Set the solid fraction of the species. :param solid_fraction: The new solid fraction :type solid_fraction: float .. py:method:: set_symmetry_factor(sym: int | str) -> None Set the symmetry factor of the species. Sets the symmetry factor to -1 if `sym` cannot be turned into an integer. :param sym: Symmetry factor :type sym: int | str .. py:method:: set_vdes(vdes: float) -> None Set the desorption prefactor. :param vdes: The desorption prefactor in s-1 :type vdes: float .. py:method:: set_vdiff(vdiff: float) -> None Set the diffusion prefactor (vdiff) for the species. :param vdiff: The diffusion prefactor in s-1 :type vdiff: float .. py:method:: set_volcano_fraction(volcano_fraction: float) -> None Set the volcano fraction of the species. :param volcano_fraction: The new volcano fraction :type volcano_fraction: float .. py:method:: to_UCL_format() -> str Serialize to the extended UCLCHEM species CSV order. Order: NAME,MASS,BINDING_ENERGY,SOLID_FRACTION,MONO_FRACTION,VOLCANO_FRACTION,ENTHALPY, DESORPTION_PREF,DIFFUSION_BARRIER,DIFFUSION_PREF,Ix,Iy,Iz,SYMMETRYFACTOR :returns: String with species values shown in format shown above. :rtype: str .. py:attribute:: diffusion_barrier :value: -1.0 .. py:attribute:: enthalpy :value: -1.0 .. py:attribute:: gains :type: str :value: '' .. py:attribute:: losses :type: str :value: '' .. py:attribute:: mass .. py:attribute:: monoFraction :value: -1.0 .. py:attribute:: name :value: '' .. py:attribute:: prefix .. py:attribute:: solidFraction :value: -1.0 .. py:attribute:: vdes :value: -1.0 .. py:attribute:: vdiff :value: -1.0 .. py:attribute:: volcFraction :value: -1.0 .. py:function:: build_network(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction], user_defined_bulk: list | None = None, gas_phase_extrapolation: bool = False, add_crp_photo_to_grain: bool = False, derive_reaction_exothermicity: list[str] | None = None, database_reaction_exothermicity: list[str | pathlib.Path] | None = None) -> Network Build a new network with full validation and automatic generation. This is a module-level factory function that provides clear documentation and intent. It calls Network.build() internally. Use this when creating new networks at build time. This performs: - Input validation and duplicate checking - Automatic freeze-out reaction generation - Automatic bulk species and reaction generation - Automatic desorption reaction generation - Branching ratio validation and correction - Temperature range collision detection - Optional gas-phase extrapolation - Optional reaction exothermicity calculation :param species: List of Species objects :type species: list[Species] :param reactions: List of Reaction objects :type reactions: list[Reaction] :param user_defined_bulk: User-specified bulk species (optional). Defaults to ``None``. :type user_defined_bulk: list | None :param gas_phase_extrapolation: Extrapolate gas-phase reactions temperatures. Defaults to ``False``. :type gas_phase_extrapolation: bool :param add_crp_photo_to_grain: Add CRP/PHOTON reactions to grain surface. Defaults to ``False``. :type add_crp_photo_to_grain: bool :param derive_reaction_exothermicity: Reaction types to calculate exothermicity for. Defaults to ``None``. :type derive_reaction_exothermicity: list[str] | None :param database_reaction_exothermicity: Custom exothermicity database files. Defaults to ``None``. :type database_reaction_exothermicity: list[str | Path] | None :returns: Fully built and validated network :rtype: Network .. rubric:: Examples >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> >>> species_list, user_defined_bulk = read_species_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv" ... ) >>> reactions_list, dropped_reactions = read_reaction_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv", ... species_list, ... "UCL", ... ) >>> # Build network with standard options >>> network = build_network( # doctest: +SKIP ... species=species_list, ... reactions=reactions_list, ... gas_phase_extrapolation=True ... ) >>> # Build with custom exothermicity >>> network = build_network( ... species=species_list, ... reactions=reactions_list, ... derive_reaction_exothermicity=['PHOTON', 'CRP'], ... database_reaction_exothermicity=['custom_heating.csv'] ... ) # doctest: +SKIP .. py:function:: create_network(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction]) -> Network Create a network directly from species and reaction lists. This is a module-level factory function that provides clear documentation and intent. It calls Network.from_lists() internally. Use this when you want direct instantiation without validation or automatic generation. Suitable for programmatic network construction or when you already have a fully prepared network. :param species: List of Species objects :type species: list[Species] :param reactions: List of Reaction objects :type reactions: list[Reaction] :returns: Network instance :rtype: Network .. rubric:: Examples >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file >>> from uclchem.utils import UCLCHEM_ROOT_DIR >>> >>> species_list, user_defined_bulk = read_species_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv" ... ) >>> reactions_list, dropped_reactions = read_reaction_file( # doctest: +SKIP ... UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv", ... species_list, ... "UCL", ... ) >>> >>> network = create_network(species_list, reactions_list) # doctest: +SKIP >>> >>> # Add some additional reactions >>> network.add_reactions(additional_reactions) # doctest: +SKIP .. py:function:: load_network_from_csv(species_path: str | pathlib.Path | None = None, reactions_path: str | pathlib.Path | None = None) -> Network Load a network from CSV files for analysis. This is a module-level factory function that provides clear documentation and intent. It calls Network.from_csv() internally. Use this when analyzing pre-compiled networks, comparing network versions, or loading old networks for analysis. :param species_path: Path to species CSV (None = use default installation) :type species_path: str | Path | None :param reactions_path: Path to reactions CSV (None = use default installation) :type reactions_path: str | Path | None :returns: Loaded network instance :rtype: Network .. rubric:: Examples >>> # Load default cmpiled network >>> network = load_network_from_csv() >>> # Load old version for comparison >>> old_network = load_network_from_csv( ... 'archive/v3.0/species.csv', ... 'archive/v3.0/reactions.csv' ... ) # doctest: +SKIP >>> print(f"Species added: {len(network.get_species_list()) - len(old_network.get_species_list())}") # doctest: +SKIP .. py:function:: run_makerates(configuration_file: str | bytes | pathlib.Path | uclchem.makerates.config.MakeratesConfig = 'user_settings.yaml', write_files: bool = True, output_directory: str | os.PathLike | None = None) -> uclchem.makerates.network.Network Run makerates. Main run wrapper for makerates. Loads and validates configuration, generates chemical network, and optionally writes output files. :param configuration_file: Path to YAML configuration file, or just a configuration. Defaults to "user_settings.yaml". :type configuration_file: str | bytes | Path | MakeratesConfig :param write_files: Whether to write fortran files to src/fortran_src. Defaults to True. :type write_files: bool :param output_directory: Optional override for the output directory where files should be written. If None, uses the 'output_directory' from the config (if present) or the package defaults. :type output_directory: str | os.PathLike | None :returns: **network** -- A validated chemical network instance. :rtype: Network :raises ValueError: If `coolants_file` is a directory, and not a path to a file.