uclchem.makerates#

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:

MakeratesConfig - Configure network generation settings
Network - Chemical network container
Reaction - Individual reaction object
Species - Chemical species object
build_network() - Build network from reaction databases
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:

Configure: Create MakeratesConfig with input files
Build: Use build_network() or run_makerates()
Validate: Check for missing species, duplicate reactions
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:

# 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#

Package Contents#

Classes#

`BaseNetwork`	Base implementation providing common network operations.
`MakeratesConfig`	Configuration for UCLCHEM Makerates chemical network generation.
`MutableNetworkABC`	Extended interface for networks that support full CRUD operations.
`Network`	Universal network representation for build and analysis contexts.
`NetworkABC`	Base abstract class defining the read-only network interface.
`Reaction`	Representation of reactions.
`Species`	Species is a class that holds all the information about an individual species in the.

Functions#

`build_network`(→ Network)	Build a new network with full validation and automatic generation.
`create_network`(→ Network)	Create a network directly from species and reaction lists.
`load_network_from_csv`(→ Network)	Load a network from CSV files for analysis.
`run_makerates`(→ uclchem.makerates.network.Network)	Run makerates.

class uclchem.makerates.BaseNetwork[source]#

Bases: 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)

find_similar_reactions(reaction: uclchem.makerates.reaction.Reaction) → dict[int, uclchem.makerates.reaction.Reaction][source]#

Find reactions with same reactants and products.

Parameters:: reaction (Reaction) – Reaction to find similar reactions for
Returns:: Dictionary of {index: Reaction} for matching reactions
Return type:: dict[int, Reaction]

get_reaction(reaction_idx: int) → uclchem.makerates.reaction.Reaction[source]#

Get a reaction by index (copy).

Parameters:: reaction_idx (int) – Index of the reaction
Returns:: copy of reaction with index reaction_idx.
Return type:: Reaction

get_reaction_dict() → dict[int, uclchem.makerates.reaction.Reaction][source]#

Get reactions dictionary (copy).

Returns:: copy of reaction dictionary, with keys of the indices and values of the reactions.
Return type:: dict[int, Reaction]

get_reaction_index(reaction: uclchem.makerates.reaction.Reaction) → int[source]#

Get the index of a reaction in the network.

Parameters:: reaction (Reaction) – Reaction to find
Returns:: Index of the reaction
Return type:: int
Raises:: ValueError – If reaction not found or multiple matches exist

get_reaction_list() → list[uclchem.makerates.reaction.Reaction][source]#

Get all reactions as a list.

Returns:: list of all reactions in the Network.
Return type:: list[Reaction]

get_reactions_by_types(reaction_type: str | list[str]) → list[uclchem.makerates.reaction.Reaction][source]#

Get all reactions of specific type(s).

Parameters:: reaction_type (str | list[str]) – Single type or list of types to filter by
Returns:: List of reactions matching the type(s)
Return type:: list[Reaction]

get_specie(specie_name: str) → uclchem.makerates.species.Species[source]#

Get a species by name (copy).

Parameters:: specie_name (str) – species name
Returns:: copy of Species instance.
Return type:: Species

get_species_dict() → dict[str, uclchem.makerates.species.Species][source]#

Get species dictionary (copy).

Returns:: copy of species dictionary, with keys of the names of the species, and values their Species instances.
Return type:: dict[str, Species]

get_species_list() → list[uclchem.makerates.species.Species][source]#

Get all species as a list.

Returns:: list of all species in the Network.
Return type:: list[Species]

property reactions: dict[int, uclchem.makerates.reaction.Reaction]#

Get reactions dictionary.

Returns:: Ordered dict of reactions in the network, keyed by index.
Return type:: dict[int, Reaction]

property species: dict[str, uclchem.makerates.species.Species]#

Get species dictionary.

Returns:: Ordered dict of species in the network, keyed by name.
Return type:: dict[str, Species]

class uclchem.makerates.MakeratesConfig(/, **data: Any)[source]#

Bases: 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.

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.

auto_enable_rates_storage() → MakeratesConfig[source]#

Automatically enable rates storage if needed for exothermicity.

Returns:: validated MakeratesConfig.
Return type:: MakeratesConfig

check_three_phase_deprecation() → MakeratesConfig[source]#

Raise error if three_phase is explicitly set to False.

Returns:: validated MakeratesConfig.
Return type:: MakeratesConfig
Raises:: ValueError – If three_phase is False.

classmethod from_yaml(yaml_path: str | pathlib.Path) → MakeratesConfig[source]#

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.

Parameters:: yaml_path (str | Path) – Path to the YAML configuration file
Returns:: Validated MakeratesConfig instance
Return type:: MakeratesConfig
Raises:: FileNotFoundError – If config file doesn’t exist

classmethod generate_template(output_path: str | pathlib.Path = 'user_settings_template.yaml')[source]#

Generate a template configuration file with all parameters documented.

Parameters:: output_path (str | Path) – Where to write the template file. Default = “user_settings_template.yaml”

get_all_reaction_files() → list[pathlib.Path][source]#

Get all reaction files (database + custom) as resolved paths.

Returns:: files – List of absolute paths to all reaction files
Return type:: list[Path]

get_all_reaction_types() → list[ReactionFileTypes][source]#

Get all reaction types (database + custom) in correct order.

Returns:: types – list of reaction type strings
Return type:: list[ReactionFileTypes]

log_configuration() → None[source]#: Log the current configuration for debugging.

classmethod normalize_coolants_file(v: str | pathlib.Path | None) → pathlib.Path | None[source]#

Normalize a single coolant file path to a Path object.

Parameters:: v (str | Path | None) – string to normalize
Returns:: Path instance, or None if v is None
Return type:: Path | None
Raises:: TypeError – If coolants_file is not a string or Path instance.

Convert single values to lists for consistent handling.

Parameters:: v (str | Path | list | None) – variable to make consistent.
Returns:: list of strings or paths, or None if v is None
Return type:: list[str | Path] | None

classmethod normalize_type_to_list(v: str | list[str] | None) → list[str] | None[source]#

Convert single type strings to lists for consistent handling.

Parameters:: v (str | list[str] | None) – variable to convert to list
Returns:: v – list of string, or None if original v is None
Return type:: list[str] | None

classmethod print_help()[source]#: Print detailed help about all configuration parameters.

resolve_path(path: str | pathlib.Path) → pathlib.Path[source]#

Resolve a path relative to the configuration file directory.

Parameters:: path (str | Path) – Path to resolve (can be absolute or relative)
Returns:: Resolved absolute Path
Return type:: Path

classmethod validate_coolants(v: list[dict[str, str]] | None) → list[dict[str, str | float]] | None[source]#

Validate inline coolants format.

Parameters:

v (list[dict[str, str]] | None) – variable to make consistent

Returns:

validated – list of validated coolant dictionaries

Return type:

list[dict[str, str | float]] | None

Raises:

TypeError – If v is not a list of dictionaries.
KeyError – If entries in v do not contain keys ‘file’ and ‘name’
ValueError – If entries in v with keys ‘file’ are not bare file names.

validate_coolants_mutual_exclusion() → MakeratesConfig[source]#

Ensure coolants and coolants_file are mutually exclusive.

Returns:: validated MakeratesConfig.
Return type:: MakeratesConfig
Raises:: ValueError – If both coolants and coolants_file are specified.

validate_reaction_files_and_types() → MakeratesConfig[source]#

Ensure reaction files and types are consistent.

Returns:

validated MakeratesConfig.

Return type:

MakeratesConfig

Raises:

ValueError – If the length of reaction files and reaction file types is not the same
ValueError – If custom_reaction_type is not specified but custom_reaction_file is.

add_crp_photo_to_grain: bool = None#

coolant_data_dir: pathlib.Path | None = None#

coolants: list[dict] | None = None#

coolants_file: pathlib.Path | None = None#

custom_reaction_file: pathlib.Path | list[pathlib.Path] | None = None#

custom_reaction_type: ReactionFileTypes | list[ReactionFileTypes] | None = None#

database_reaction_exothermicity: list[pathlib.Path] | None = None#

database_reaction_file: pathlib.Path | list[pathlib.Path] = None#

database_reaction_type: ReactionFileTypes | list[ReactionFileTypes] = None#

derive_reaction_exothermicity: bool | str | list[str] = None#

enable_rates_storage: bool = None#

gas_phase_extrapolation: bool = None#

grain_assisted_recombination_file: pathlib.Path | None = None#

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_directory: pathlib.Path | None = None#

species_file: pathlib.Path = None#

three_phase: bool = None#

class uclchem.makerates.MutableNetworkABC[source]#

Bases: 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.

abstractmethod add_reactions(reactions: uclchem.makerates.reaction.Reaction | list) → None[source]#

Add one or more reactions to the network.

Parameters:: reactions (Reaction | list) – Reactions to add to the network.

abstractmethod add_species(species: uclchem.makerates.species.Species | list) → None[source]#

Add one or more species to the network.

Parameters:: species (Species | list) – Species instance or list of species to add.

abstractmethod remove_reaction(reaction: uclchem.makerates.reaction.Reaction) → None[source]#

Remove a reaction from the network.

Parameters:: reaction (Reaction) – Reaction instance to look up or modify.

abstractmethod remove_reaction_by_index(reaction_idx: int) → None[source]#

Remove a reaction by its index.

Parameters:: reaction_idx (int) – Index of the reaction in the network.

abstractmethod remove_species(specie_name: str) → None[source]#

Remove a species from the network.

Parameters:: specie_name (str) – Name of the species.

abstractmethod set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) → None[source]#

Set/update a reaction at a specific index.

Parameters:

reaction_idx (int) – Index of the reaction in the network.
reaction (Reaction) – Reaction instance to look up or modify.

abstractmethod set_reaction_dict(new_dict: dict[int, uclchem.makerates.reaction.Reaction]) → None[source]#

Replace the entire reaction dictionary.

Parameters:: new_dict (dict[int, Reaction]) – Replacement reactions dictionary.

abstractmethod set_specie(species_name: str, species: uclchem.makerates.species.Species) → None[source]#

Set/update a species in the network.

Parameters:

species_name (str) – Name of the species.
species (Species) – Species instance or list of species to add.

abstractmethod set_species_dict(new_species_dict: dict[str, uclchem.makerates.species.Species]) → None[source]#

Replace the entire species dictionary.

Parameters:: new_species_dict (dict[str, Species]) – Replacement species dictionary.

abstractmethod sort_reactions() → None[source]#: Sort reactions by type and reactants.

abstractmethod sort_species() → None[source]#: Sort species by type and mass.

class uclchem.makerates.Network(species_dict: dict[str, uclchem.makerates.species.Species], reaction_dict: dict[int, uclchem.makerates.reaction.Reaction])[source]#

Bases: BaseNetwork, 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.

_species_dict#

Internal species storage {name: Species}

Type:: dict[str, Species]

_reactions_dict#

Internal reaction storage {index: Reaction}

Type:: dict[int, Reaction]

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(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv"
... )
>>> reactions_list, dropped_reactions = read_reaction_file(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv",
...     species_list,
...     "UCL",
... )
>>> network = Network.build(
...     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.

Parameters:

species_dict (dict[str, Species]) – Species dictionary {name: Species}
reaction_dict (dict[int, Reaction]) – Reaction dictionary {index: Reaction}

add_reactions(reactions: uclchem.makerates.reaction.Reaction | list) → None[source]#

Add reactions to network.

Parameters:

reactions (Reaction | list) – Reaction object, list of Reactions, or CSV-style entries

Raises:

ValueError – If there is an error when converting the CSV-style entries to Reaction instances
TypeError – If input was not a Reaction, list of Reaction instances, or CSV-style entries.

add_species(species: uclchem.makerates.species.Species | list) → None[source]#

Add species to network.

Parameters:

species (Species | list) – Species object, list of Species, or CSV-style entries

Raises:

ValueError – If there is an error when converting the CSV-style entries to Species instances
TypeError – If input was not a Species, list of Species instances, or CSV-style entries.

classmethod build(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction], **build_options) → Network[source]#

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.

Parameters:

species (list[Species]) – List of Species objects
reactions (list[Reaction]) – List of Reaction objects
**build_options (dict) – 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

Returns:

Fully built and validated network

Return type:

Network

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(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv"
... )
>>> reactions_list, dropped_reactions = read_reaction_file(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv",
...     species_list,
...     "UCL",
... )
>>> network = Network.build(
...     species=species_list,
...     reactions=reactions_list,
...     gas_phase_extrapolation=True,
...     add_crp_photo_to_grain=True
... )

change_binding_energy(specie: str, new_binding_energy: float) → None[source]#

Change binding energy of a species.

Handles special case of @H2O which affects other bulk species.

Parameters:

specie (str) – string representation of species
new_binding_energy (float) – new binding energy in K

Raises:

ValueError – If specie is not in the network.

change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) → None[source]#

Change activation barrier of a reaction.

Looks up reaction in Network by its reactants and products. If Fortran interface is available, also updates Fortran.

Parameters:

reaction (Reaction) – Reaction to change.
barrier (float) – New reaction barrier in K

Raises:

RuntimeError – If multiple matching reactions are found in the network.

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.

Parameters:

species_path (str | bytes | Path | None) – Path to species CSV (None = use default installation)
reactions_path (str | bytes | Path | None) – Path to reactions CSV (None = use default installation)

Returns:

Loaded network instance

Return type:

Network

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')

classmethod from_lists(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction]) → Network[source]#

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.

Parameters:

species (list[Species]) – List of Species objects
reactions (list[Reaction]) – List of Reaction objects

Returns:

Network instance

Return type:

Network

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(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv"
... )
>>> reactions_list, dropped_reactions = read_reaction_file(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv",
...     species_list,
...     "UCL",
... )
>>> network = Network.from_lists(species_list, reactions_list)

get_all_partners(reaction: uclchem.makerates.reaction.Reaction) → list[uclchem.makerates.reaction.Reaction][source]#

Get a list of all reactions that have reaction as their partner.

Parameters:: reaction (Reaction) – Reaction
Returns:: reactions_coupled_to_reaction – List of reactions that have reaction as their partner.
Return type:: list[Reaction]
Raises:: RuntimeError – If the partner of a CoupledReaction instance in the network is None.

get_reactions_by_types(reaction_type: str | list[str]) → list[uclchem.makerates.reaction.Reaction][source]#

Get the union of all reactions of a certain type.

Parameters:: reaction_type (str | list[str]) – The reaction type to filter on
Returns:: A list of reactions of the specified type
Return type:: list[Reaction]

remove_reaction(reaction: uclchem.makerates.reaction.Reaction) → None[source]#

Remove a reaction from network.

Parameters:: reaction (Reaction) – Reaction to remove from the network.
Raises:: RuntimeError – If multiple matching reactions are found in the network.

remove_reaction_by_index(reaction_idx: int) → None[source]#

Remove a reaction by its index.

Parameters:: reaction_idx (int) – Index of the reaction in the network.

remove_species(specie_name: str) → None[source]#

Remove a species from network.

Parameters:: specie_name (str) – Name of the species.

set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) → None[source]#

Set/update a reaction at specific index.

Parameters:

reaction_idx (int) – Index of the reaction in the network.
reaction (Reaction) – Reaction instance to look up or modify.

Raises:

AssertionError – If setting the reaction changes the total count of reactions.

set_reaction_dict(new_dict: dict[int, uclchem.makerates.reaction.Reaction]) → None[source]#

Replace entire reaction dictionary.

Parameters:: new_dict (dict[int, Reaction]) – Replacement reactions dictionary.

set_specie(species_name: str, species: uclchem.makerates.species.Species) → None[source]#

Set/update a species.

Parameters:

species_name (str) – Name of the species.
species (Species) – Species instance or list of species to add.

set_species_dict(new_species_dict: dict[str, uclchem.makerates.species.Species]) → None[source]#

Replace entire species dictionary.

Parameters:: new_species_dict (dict[str, Species]) – Replacement species dictionary.

sort_reactions() → None[source]#

Sort reactions by type and first reactant.

Raises:: AssertionError – If sorting changes the total count of reactions.

sort_species() → None[source]#: Sort species by type and mass, with electron last.

add_crp_photo_to_grain: bool = False#

database_reaction_exothermicity: list[str | pathlib.Path] | None = None#

derive_reaction_exothermicity: list[str] | None = None#

enthalpies_present: bool = False#

excited_species: bool = False#

important_reactions: dict[str, int | None]#

property species: dict[str, uclchem.makerates.species.Species]#

Get species dictionary.

Returns:: Ordered dict of species in the network, keyed by name.
Return type:: dict[str, Species]

species_indices: dict[str, int]#

user_defined_bulk: list = []#

class uclchem.makerates.NetworkABC[source]#

Bases: 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)

abstractmethod change_binding_energy(specie: str, new_binding_energy: float) → None[source]#

Change binding energy of an existing species.

Parameters:

specie (str) – Name of the species.
new_binding_energy (float) – New binding energy in Kelvin.

abstractmethod change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) → None[source]#

Change activation barrier of an existing reaction.

Parameters:

reaction (Reaction) – Reaction instance to look up or modify.
barrier (float) – New reaction barrier in Kelvin.

abstractmethod find_similar_reactions(reaction: uclchem.makerates.reaction.Reaction) → dict[int, uclchem.makerates.reaction.Reaction][source]#

Find reactions with same reactants/products.

Parameters:: reaction (Reaction) – Reaction instance to look up or modify.

abstractmethod get_reaction(reaction_idx: int) → uclchem.makerates.reaction.Reaction[source]#

Get a specific reaction by index.

Parameters:: reaction_idx (int) – Index of the reaction in the network.

abstractmethod get_reaction_dict() → dict[int, uclchem.makerates.reaction.Reaction][source]#: Get the reactions dictionary.

abstractmethod get_reaction_index(reaction: uclchem.makerates.reaction.Reaction) → int[source]#

Get the unique index of a reaction.

Parameters:: reaction (Reaction) – Reaction instance to look up or modify.

abstractmethod get_reaction_list() → list[uclchem.makerates.reaction.Reaction][source]#: Get all reactions in the network.

abstractmethod get_reactions_by_types(reaction_type: str | list[str]) → list[uclchem.makerates.reaction.Reaction][source]#

Get all reactions of specific type(s).

Parameters:: reaction_type (str | list[str]) – Reaction type label to filter on (e.g. 'MA', 'DR').

abstractmethod get_specie(specie_name: str) → uclchem.makerates.species.Species[source]#

Get a specific species by name.

Parameters:: specie_name (str) – Name of the species.

abstractmethod get_species_dict() → dict[str, uclchem.makerates.species.Species][source]#: Get the species dictionary.

abstractmethod get_species_list() → list[uclchem.makerates.species.Species][source]#: Get all species in the network.

property reactions: dict[int, uclchem.makerates.reaction.Reaction]#

Abstractmethod:

Get the reactions collection.

property species: dict[str, uclchem.makerates.species.Species]#

Abstractmethod:

Get the species collection.

class uclchem.makerates.Reaction(input_row: list[str | float] | Reaction, reaction_source: str | None = None)[source]#

Representation of reactions.

Initialize a Reaction object.

Parameters:

input_row (list[str | float] | Reaction) – Either a Reaction object to copy, or a list/array with reaction data
reaction_source (str | None) – Optional source identifier for the reaction. Default = None.

Raises:

ValueError – If the length of input_row is not long enough.

changes_surface_count() → bool[source]#

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.
Return type:: bool

changes_total_mantle() → bool[source]#

Check if the total grains on the mantle are changed by the reaction.

Returns:: Whether the total ice abundance is affected by this reaction.
Return type:: bool

check_charge_conservation() → None[source]#

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.

check_element_conservation() → None[source]#

Check the conservation of elements.

Raises:: ValueError – If the elements are not conserved by the reaction.

check_temperature_collision(other: Reaction) → bool[source]#

Check if two reactions have overlapping temperature ranges.

Returning True means there is a collision.

Parameters:: other (Reaction) – Another reaction
Returns:: Whether there is a collision (True), or not (False)
Return type:: bool
Raises:: NotImplementedError – If other is not a Reaction instance. Currently we can only compare against instantiated Reaction objects.

convert_gas_to_surf() → None[source]#

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.

convert_surf_to_bulk() → None[source]#: Convert the surface species to bulk species in place for this reaction.

generate_ode_bit(i: int, species_names: list[str]) → None[source]#

Generate the ODE string of this reaction.

Parameters:

i (int) – index of reaction in network in python format (counting from 0)
species_names (list[str]) – List of species names so we can find index of reactants in species list

get_alpha() → float[source]#

Get the alpha parameter from the Kooij-Arrhenius equation.

Returns:: the alpha parameter of the reaction
Return type:: float

get_beta() → float[source]#

Get the beta parameter from the Kooij-Arrhenius equation.

Returns:: the beta parameter of the reaction
Return type:: float

get_exothermicity() → float[source]#

Get the cooling/heating for the reaction in erg s^-1.

Returns:: the reaction enthalpy change
Return type:: float

get_extrapolation() → bool[source]#

Get whether extrapolation is applied for this reaction.

Returns:: whether extrapolation is applied.
Return type:: bool

get_gamma() → float[source]#

Get the gamma parameter from the Kooij-Arrhenius equation.

Returns:: the gamma parameter of the reaction
Return type:: float

get_products() → list[str][source]#

Get the four products present in the reaction,.

padded with NAN for nonexistent entries.

Returns:: The four products names
Return type:: list[str]

get_pure_products() → list[str][source]#

Get only the pure species that are products,.

no reaction types and NAN entries.

Returns:: The list of produced species.
Return type:: list[str]

get_pure_reactants() → list[str][source]#

Get only the pure species, no reaction types and NAN entries.

Returns:: The list of reacting species.
Return type:: list[str]

get_reactants() → list[str][source]#

Get the four reactants present in the reaction,.

padded with NAN for nonexistent entries.

Returns:: The four reactants names
Return type:: list[str]

get_reaction_type() → str[source]#

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
Return type:: str

get_reduced_mass() → float[source]#

Get the reduced mass to be used to calculate tunneling rate in.

atomic mass units.

Returns:: reduced mass of moving atoms
Return type:: float

get_sorted_products() → list[str][source]#

Get the four products present in the reaction,.

sorted for fast comparisons.

Returns:: The four sorted products names
Return type:: list[str]

get_sorted_reactants() → list[str][source]#

Get the four reactants present in the reaction,.

sorted for fast comparisons.

Returns:: The four sorted reactant names
Return type:: list[str]

get_source() → str | None[source]#

Get the source of the reaction.

Returns:: The source of the reaction
Return type:: str | None

get_temphigh() → float[source]#

Get the higher temperature boundary of the reaction in Kelvin.

Returns:: the higher temperature boundary
Return type:: float

get_templow() → float[source]#

Get the lower temperature boundary of the reaction in Kelvin.

Returns:: the lower temperature boundary
Return type:: float

is_bulk_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = False) → bool[source]#

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

Parameters:

include_reactants (bool) – Include the reactants. Defaults to True.
include_products (bool) – Include the products. Defaults to True.
strict (bool) – Choose between all (true) or any (false) must in the bulk. Defaults to False.

Returns:

Is it a bulk reaction?

Return type:

bool

is_gas_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = True) → bool[source]#

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.

Parameters:

include_reactants (bool) – Include the reactants. Defaults to True.
include_products (bool) – Include the products. Defaults to True.
strict (bool) – Choose between all (true) or any (false) must be gas phase. Defaults to True.

Returns:

Is it a gas phase reaction?

Return type:

bool

is_ice_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = True) → bool[source]#

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

Parameters:

include_reactants (bool) – Include the reactants. Defaults to True.
include_products (bool) – Include the products. Defaults to True.
strict (bool) – Choose between all (true) or any (false) must be ice phase. Defaults to True.

Returns:

Is it an ice phase reaction?

Return type:

bool

is_surface_reaction(include_reactants: bool = True, include_products: bool = True, strict: bool = False) → bool[source]#

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

Parameters:

include_reactants (bool) – Include the reactants. Defaults to True.
include_products (bool) – Include the products. Defaults to True.
strict (bool) – Choose between all (true) or any (false) must be on the surface. Defaults to False.

Returns:

Is it a surface reaction?

Return type:

bool

predict_reduced_mass() → None[source]#

Predict the reduced mass of the tunneling particle in this reaction.

This is used in the calculation of the tunneling rates.

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

set_alpha(alpha: float) → None[source]#

Set the alpha parameter from the Kooij-Arrhenius equation.

Parameters:: alpha (float) – the alpha parameter of the reaction

set_beta(beta: float) → None[source]#

Set the beta parameter from the Kooij-Arrhenius equation.

Parameters:: beta (float) – the beta parameter of the reaction

set_exothermicity(rate: float) → None[source]#

Set the cooling/heating for the reaction in erg s^-1.

Parameters:: rate (float) – the reaction enthalpy change

set_extrapolation(flag: bool) → None[source]#

Set whether extrapolation is applied for this reaction.

Parameters:: flag (bool) – whether extrapolation is applied.
Raises:: AssertionError – If flag is not a boolean.

set_gamma(gamma: float) → None[source]#

Set the gamma parameter from the Kooij-Arrhenius equation.

Parameters:: gamma (float) – the gamma parameter of the reaction

set_products(products: list[str]) → None[source]#

Set the four products present in the reaction, padded with NAN for nonexistent entries.

Parameters:: products (list[str]) – The four products names

set_reactants(reactants: list[str]) → None[source]#

Set the four reactants present in the reaction,.

padded with NAN for nonexistent entries.

Parameters:: reactants (list[str]) – The four reactants names

set_reduced_mass(reduced_mass: float) → None[source]#

Set the reduced mass to be used to calculate tunneling rate in.

atomic mass units.

Parameters:: reduced_mass (float) – reduced mass of moving atoms

set_source(source: str) → None[source]#

Set the source of the reaction.

Parameters:: source (str) – The source of the reaction

set_temphigh(temphigh: float) → None[source]#

Set the higher temperature boundary of the reaction in Kelvin.

Parameters:: temphigh (float) – the higher temperature boundary

set_templow(templow: float) → None[source]#

Set the lower temperature boundary of the reaction in Kelvin.

Parameters:: templow (float) – the lower temperature boundary

to_UCL_format() → str[source]#

Convert a reaction to UCLCHEM reaction file format.

Returns:: string representing species
Return type:: str

body_count = -1#

duplicate = False#

source = None#

class uclchem.makerates.Species(input_row: list[str | float] | pandas.Series)[source]#

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.

Parameters:: input_row (list[str | float] | pd.Series) – Row from the species CSV, as a list of values.

add_default_freeze() → None[source]#

Add a default freezeout, which is freezing out to the species itself,.

but with no ionization.

calculate_rotational_partition_factor() → float[source]#

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
Return type:: float

check_symmetry_factor() → None[source]#

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

find_constituents(quiet: bool = False) → collections.Counter[str][source]#

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.

Parameters:: quiet (bool) – If True, suppress warnings about unknown constituents. Defaults to False.
Returns:: Counter of how many times each element is in the molecule.
Return type:: 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.

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

get_Ix() → float[source]#

Set the moment of inertia along the first principal axis.

Returns:: moment of inertia in amu/Angstrom^2
Return type:: float

get_Iy() → float[source]#

Set the moment of inertia along the second principal axis.

Returns:: moment of inertia in amu/Angstrom^2
Return type:: float

get_Iz() → float[source]#

Set the moment of inertia along the third principal axis.

Returns:: moment of inertia in amu/Angstrom^2
Return type:: float

get_binding_energy() → float[source]#

Get the binding energy of the species in K.

Returns:: The binding energy in K
Return type:: float

get_charge() → int[source]#

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
Return type:: int

get_desorb_products() → list[str][source]#

Obtain the desorbtion products of ice species.

Returns:: The desorption products
Return type:: list[str]
Raises:: AttributeError – If the species has no attribute desorb_products. This can occur if the species is a gas-phase species.

get_desorption_pref() → float[source]#

Get the desorption prefactor.

Alias getter matching CSV column name desorption_pref.

Returns:: The desorption prefactor in s-1
Return type:: float

get_diffusion_barrier() → float[source]#

Get the diffusion barrier for the species.

Returns:: The diffusion barrier in K
Return type:: float

get_diffusion_pref() → float[source]#

Set the diffusion prefactor.

Alias getter matching CSV column name diffusion_pref.

Returns:: The diffusion prefactor in s-1
Return type:: float

get_enthalpy() → float[source]#

Get the ice enthalpy of the species.

Returns:: The ice enthalpy
Return type:: float

get_freeze_alpha(product_list: list[str]) → float[source]#

Obtain the freeze out ratio of a species for a certain reaction.

Parameters:: product_list (list[str]) – For a specific reaction, get the freezeout ratio
Returns:: The freezeout ratio
Return type:: float

get_freeze_products() → collections.abc.Iterator[tuple[list[str], float]][source]#

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

get_freeze_products_list() → list[list[str]][source]#

Get all the freeze products without their ratios.

Returns:: List of freeze products
Return type:: list[list[str]]

get_mass() → int[source]#

Get the molecular mass of the chemical species.

Returns:: The molecular mass in atomic mass units.
Return type:: int

get_mono_fraction() → float[source]#

Get the monolayer fraction of the species.

Returns:: The monolayer fraction
Return type:: float

get_n_atoms() → int[source]#

Get the number of atoms in the molecule.

Returns:: The number of atoms
Return type:: int

get_name() → str[source]#

Get the name of the chemical species.

Returns:: The name
Return type:: str

get_solid_fraction() → float[source]#

Get the solid fraction of the species.

Returns:: The solid fraction
Return type:: float

get_standard_desorb_products() → list[str][source]#

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]
Return type:: list[str]

get_symmetry_factor() → int[source]#

Get the symmetry factor of the species.

Returns:: Symmetry factor
Return type:: int

get_vdes() → float[source]#

Get the desorption prefactor.

Returns:: The desorption prefactor in s-1
Return type:: float

get_vdiff() → float[source]#

Get the diffusion prefactor.

Returns:: The diffusion prefactor in s-1
Return type:: float

get_volcano_fraction() → float[source]#

Get the volcano fraction of the species.

Returns:: The volcano fraction
Return type:: float

is_bulk_species() → bool[source]#

Check if the species is in the bulk.

Returns:: True if a bulk species
Return type:: bool

is_grain_species() → bool[source]#

Return whether the species is a species on the grain.

Returns:: True if it is a grain species.
Return type:: bool

is_ice_species() → bool[source]#

Return whether the species is a species on the grain.

Returns:: True if it is an ice species.
Return type:: bool

is_ion() → bool[source]#

Check if the species is ionized, either positively or negatively.

Returns:: True if it is ionized
Return type:: bool

is_linear() → bool[source]#

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
Return type:: bool

is_surface_species() → bool[source]#

Check if the species is on the surface.

Returns:: True if a surface species
Return type:: bool

set_Ix(Ix: float) → None[source]#

Set the moment of inertia along the first principal axis.

Parameters:: Ix (float) – desired moment of inertia (in amu/Angstrom^2)

set_Iy(Iy: float) → None[source]#

Set the moment of inertia along the second principal axis.

Parameters:: Iy (float) – desired moment of inertia (in amu/Angstrom^2)

set_Iz(Iz: float) → None[source]#

Set the moment of inertia along the third principal axis.

Parameters:: Iz (float) – desired moment of inertia (in amu/Angstrom^2)

set_binding_energy(binding_energy: float) → None[source]#

Set the binding energy of the species in K.

Parameters:: binding_energy (float) – The new binding energy in K

set_desorb_products(new_desorbs: list[str]) → None[source]#

Set the desorption products for species on the surface or in the bulk.

It is assumed that there is only one desorption pathway.

Parameters:: new_desorbs (list[str]) – The new desorption products

set_desorption_pref(vdes: float) → None[source]#

Set the desorption prefactor.

Alias setter matching CSV column name desorption_pref.

Parameters:: vdes (float) – The desorption prefactor in s-1

set_diffusion_barrier(barrier: float) → None[source]#

Set the diffusion barrier for the species.

Parameters:: barrier (float) – Diffusion barrier in K

set_diffusion_pref(vdiff: float) → None[source]#

Set the diffusion prefactor.

Alias setter matching CSV column name diffusion_pref.

Parameters:: vdiff (float) – The diffusion prefactor in s-1

set_enthalpy(enthalpy: float) → None[source]#

Set the enthalpy of the species in kcal per mole.

Parameters:: enthalpy (float) – The new ice enthalpy

set_freeze_products(product_list: list[str], freeze_alpha: float) → None[source]#

Add the freeze products of the species, one species can have.

several freeze products.

Parameters:

product_list (list[str]) – The list of freeze out products
freeze_alpha (float) – The freeze out ratio.

set_mass(mass: int) → None[source]#

Set the molecular mass of the chemical species in atomic mass units.

Parameters:: mass (int) – The new molecular mass

set_mono_fraction(mono_fraction: float) → None[source]#

Set the monolayer fraction of the species.

Parameters:: mono_fraction (float) – The new monolayer fraction

set_n_atoms(new_n_atoms: int) → None[source]#

Set the number of atoms.

Parameters:: new_n_atoms (int) – The new number of atoms

set_name(name: str) → None[source]#

Set the name of the chemical species.

Parameters:: name (str) – The new name for the species

set_solid_fraction(solid_fraction: float) → None[source]#

Set the solid fraction of the species.

Parameters:: solid_fraction (float) – The new solid fraction

set_symmetry_factor(sym: int | str) → None[source]#

Set the symmetry factor of the species.

Sets the symmetry factor to -1 if sym cannot be turned into an integer.

Parameters:: sym (int | str) – Symmetry factor

set_vdes(vdes: float) → None[source]#

Set the desorption prefactor.

Parameters:: vdes (float) – The desorption prefactor in s-1

set_vdiff(vdiff: float) → None[source]#

Set the diffusion prefactor (vdiff) for the species.

Parameters:: vdiff (float) – The diffusion prefactor in s-1

set_volcano_fraction(volcano_fraction: float) → None[source]#

Set the volcano fraction of the species.

Parameters:: volcano_fraction (float) – The new volcano fraction

to_UCL_format() → str[source]#

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.
Return type:: str

diffusion_barrier = -1.0#

enthalpy = -1.0#

gains: str = ''#

losses: str = ''#

mass#

monoFraction = -1.0#

name = ''#

prefix#

solidFraction = -1.0#

vdes = -1.0#

vdiff = -1.0#

volcFraction = -1.0#

uclchem.makerates.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[source]#

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

Parameters:

species (list[Species]) – List of Species objects
reactions (list[Reaction]) – List of Reaction objects
user_defined_bulk (list | None) – User-specified bulk species (optional). Defaults to None.
gas_phase_extrapolation (bool) – Extrapolate gas-phase reactions temperatures. Defaults to False.
add_crp_photo_to_grain (bool) – Add CRP/PHOTON reactions to grain surface. Defaults to False.
derive_reaction_exothermicity (list[str] | None) – Reaction types to calculate exothermicity for. Defaults to None.
database_reaction_exothermicity (list[str | Path] | None) – Custom exothermicity database files. Defaults to None.

Returns:

Fully built and validated network

Return type:

Network

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(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv"
... )
>>> reactions_list, dropped_reactions = read_reaction_file(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv",
...     species_list,
...     "UCL",
... )

>>> # Build network with standard options
>>> network = build_network(
...     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']
... )

uclchem.makerates.create_network(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction]) → Network[source]#

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.

Parameters:

species (list[Species]) – List of Species objects
reactions (list[Reaction]) – List of Reaction objects

Returns:

Network instance

Return type:

Network

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(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv"
... )
>>> reactions_list, dropped_reactions = read_reaction_file(
...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv",
...     species_list,
...     "UCL",
... )
>>>
>>> network = create_network(species_list, reactions_list)
>>>
>>> # Add some additional reactions
>>> network.add_reactions(additional_reactions)

uclchem.makerates.load_network_from_csv(species_path: str | pathlib.Path | None = None, reactions_path: str | pathlib.Path | None = None) → Network[source]#

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.

Parameters:

species_path (str | Path | None) – Path to species CSV (None = use default installation)
reactions_path (str | Path | None) – Path to reactions CSV (None = use default installation)

Returns:

Loaded network instance

Return type:

Network

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'
... )
>>> print(f"Species added: {len(network.get_species_list()) - len(old_network.get_species_list())}")

uclchem.makerates.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[source]#

Run makerates.

Main run wrapper for makerates. Loads and validates configuration, generates chemical network, and optionally writes output files.

Parameters:

configuration_file (str | bytes | Path | MakeratesConfig) – Path to YAML configuration file, or just a configuration. Defaults to “user_settings.yaml”.
write_files (bool) – Whether to write fortran files to src/fortran_src. Defaults to True.
output_directory (str | os.PathLike | None) – 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.

Returns:

network – A validated chemical network instance.

Return type:

Network

Raises:

ValueError – If coolants_file is a directory, and not a path to a file.