uclchem.makerates.network_builder

NetworkBuilder - Handles complex network construction logic.

This module extracts the build-time complexity from the Network class, providing a clean separation between: - Network: Data container with unified interface - NetworkBuilder: Build-time validation and automatic reaction generation

Module Contents

Classes

NetworkBuilder

Builder for constructing complex chemical networks.

Attributes

logger

class uclchem.makerates.network_builder.NetworkBuilder(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)

Builder for constructing complex chemical networks.

Handles all build-time operations: - Input validation - Automatic freeze-out reactions - Automatic bulk species and reactions - Automatic desorption reactions - Branching ratio validation and correction - Temperature range collision detection - Gas-phase reaction extrapolation - Reaction exothermicity calculation

This class separates the complex build logic from the Network data container, making the code more maintainable and testable.

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",
... )
>>> builder = NetworkBuilder(
...     species=species_list,
...     reactions=reactions_list,
...     gas_phase_extrapolation=True,
...     add_crp_photo_to_grain=True
... )
>>> network = builder.build()

Initialize the network builder.

Parameters:

• species (list[Species]) – List of chemical species

• reactions (list[Reaction]) – List of chemical reactions

• user_defined_bulk (list | None) – User-specified bulk species (optional) (Default value = None)

• gas_phase_extrapolation (bool) – Extrapolate gas-phase temperature (default: False)

• add_crp_photo_to_grain (bool) – Add CRP/PHOTON to grain (default: False)

• derive_reaction_exothermicity (list[str] | None) – Reaction types to calculate exothermicity for (Default value = None)

• database_reaction_exothermicity (list[str | Path] | None) – Custom exothermicity database files (Default value = None)

Raises:

ValueError – If duplicate species are provided.

build() → uclchem.makerates.network.Network

Build the network with all validations and automatic additions.

This method orchestrates all build steps in the correct order: 1. Create initial network from inputs 2. Add electron species 3. Check and handle freeze/desorb species 4. Add automatic reactions (freeze, bulk, desorb, chemdes) 5. Validate branching ratios 6. Apply optional features (extrapolation, exothermicity) 7. Sort and filter final network

Returns:

Fully built and validated network

Return type:

Network

add_crp_photo_to_grain = False

database_reaction_exothermicity = None

derive_reaction_exothermicity = None

enthalpies_present = False

excited_species = False

gas_phase_extrapolation = False

input_reactions

input_species

property network: uclchem.makerates.network.Network

Return the network under construction.

Returns:

The network being built.

Return type:

Network

Raises:

RuntimeError – If accessed before build() has created the network.

user_defined_bulk = []

uclchem.makerates.network_builder.logger