uclchem.makerates.network#

Unified Network implementation for UCLCHEM.

This module provides the Network class and factory functions for creating networks in different contexts: - load_network_from_csv(): Load compiled networks for analysis - build_network(): Build new networks with full validation - create_network(): Direct instantiation from objects

The Network class implements a complete interface for accessing and modifying chemical reaction networks, suitable for build-time and analysis-time use.

For runtime parameter modification during model execution, use RuntimeNetwork from uclchem.advanced.runtime_network instead.

Module Contents#

Classes#

`BaseNetwork`	Base implementation providing common network operations.
`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.

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.

Attributes#

logger

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

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

Get species dictionary.

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

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

Internal species storage {name: Species}

Type:: dict[str, Species]

_reactions_dict[source]#

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

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

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

enthalpies_present: bool = False[source]#

excited_species: bool = False[source]#

important_reactions: dict[str, int | None][source]#

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

Get species dictionary.

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

species_indices: dict[str, int][source]#

user_defined_bulk: list = [][source]#

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

Abstractmethod:

Get the reactions collection.

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

Abstractmethod:

Get the species collection.

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