uclchem.advanced.runtime_network#

Runtime network interface for UCLCHEM’s compiled chemical network.

This module provides RuntimeNetwork for runtime parameter modification during model execution. Unlike the Network class in makerates (which supports full CRUD), RuntimeNetwork provides read access and parameter modification only, as the compiled Fortran network has fixed structure.

Key capabilities: - Read all species and reactions - Modify reaction parameters (alpha, beta, gamma) - Modify species binding energies - Disable reactions (set alpha=0) - Reset to initial state - Cannot add new species or reactions (Fortran arrays are fixed size) - Cannot truly remove species or reactions (only disable)

Thread Safety Warning:: RuntimeNetwork modifies global Fortran module state and is NOT thread-safe. Do not use with multiprocessing, multithreading, or concurrent model runs.

Module Contents#

Classes#

RuntimeNetwork

Runtime interface to UCLCHEM's compiled Fortran network.

class uclchem.advanced.runtime_network.RuntimeNetwork[source]#

Bases: uclchem.makerates.network.BaseNetwork

Runtime interface to UCLCHEM’s compiled Fortran network.

Provides read access and parameter modification for the compiled chemical network during model execution. The network structure (species/reactions) is fixed, but parameters can be modified.

To “remove” a reaction: set its alpha parameter to 0.0 using disable_reaction(). To reset changes: call reset_to_initial_state().

Examples

>>> # Load runtime network
>>> network = RuntimeNetwork()
>>> print(f"Species: {len(network.get_species_list())}")
Species: ...
>>> print(f"Reactions: {len(network.get_reaction_list())}")
Reactions: ...

>>> # Modify parameters
>>> network.modify_reaction_parameters(0, alpha=1e-10, beta=2.0)
>>> network.change_binding_energy("#H2O", 5773.0)

>>> # Disable a reaction
>>> network.disable_reaction(5)

>>> # Reset when done
>>> network.reset_to_initial_state()

You can use this to do a sensitivity analysis in a simple way.

>>> # Artificially set a higher diffusion barrier of atomic hydrogen
>>> network.change_diffusion_barrier("#H", 600)
>>>
>>> # Run a model at the increased hydrogen diffusion barrier
>>> import uclchem
>>> param_dict = {"initialDens": 1e5, "initialTemp": 10, "finalTime": 1e5}
>>> high_diffusion_barrier_model = uclchem.model.Cloud(param_dict=param_dict)
>>>
>>> # Reset to initial state, and then run a "standard" model
>>> network.reset_to_initial_state()
>>> regular_diffusion_barrier_model = uclchem.model.Cloud(param_dict=param_dict)
>>>
>>> # Do some analysis to see the effect of a higher hydrogen diffusion barrier
>>> # ...

Initialize RuntimeNetwork by loading the compiled Fortran module.

Automatically imports uclchemwrap.network and validates against species.csv and reactions.csv from the installation directory.

Raises:: ImportError – If uclchemwrap.network cannot be imported

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

NOT SUPPORTED: Cannot add reactions to compiled Fortran network.

Parameters:: reactions (Reaction | list[Reaction]) – Reactions to add to the network.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

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

NOT SUPPORTED: Cannot add species to compiled Fortran network.

Parameters:: species (Species | list[Species]) – Species instance or list of species to add.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

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

Change binding energy of a species (modifies Fortran array).

Parameters:

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

change_diffusion_barrier(specie: str, new_diffusion_barrier: float) → None[source]#

Change diffusion barrier of a species (modifies Fortran array).

Parameters:

specie (str) – Name of the species.
new_diffusion_barrier (float) – New diffusion barrier in Kelvin.

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

Change activation barrier of a reaction (modifies Fortran gamma).

Parameters:

reaction (Reaction) – Reaction to modify
barrier (float) – New activation barrier in Kelvin

Raises:

RuntimeError – If reaction is not a reaction on the ices.

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

Disable a reaction by setting alpha=0.

This is the only way to “remove” a reaction at runtime since the Fortran network has fixed structure. Setting alpha=0 makes the reaction have zero rate.

Parameters:: reaction_idx (int) – Index of reaction to disable (0-based)

Examples

>>> network = RuntimeNetwork()
>>> network.disable_reaction(5)
>>> network.reset_to_initial_state()

modify_reaction_parameters(reaction_idx: int, alpha: float | None = None, beta: float | None = None, gamma: float | None = None) → None[source]#

Modify reaction rate parameters in Fortran arrays.

Parameters:

reaction_idx (int) – Index of reaction to modify (0-based)
alpha (float | None) – New alpha value (pre-exponential factor) (Default value = None)
beta (float | None) – New beta value (temperature exponent) (Default value = None)
gamma (float | None) – New gamma value (activation energy in K) (Default value = None)

Raises:

IndexError – If reaction_idx out of range

Examples

>>> network = RuntimeNetwork()
>>> network.modify_reaction_parameters(0, alpha=1e-10, beta=2.0)
>>> network.reset_to_initial_state()

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

NOT SUPPORTED: Cannot remove reactions from compiled Fortran network.

Use disable_reaction() to set alpha=0 instead.

Parameters:: reaction (Reaction) – Reaction instance to look up or modify.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

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

NOT SUPPORTED: Cannot remove reactions from compiled Fortran network.

Use disable_reaction() to set alpha=0 instead.

Parameters:: reaction_idx (int) – Index of the reaction in the network.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

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

NOT SUPPORTED: Cannot remove species from compiled Fortran network.

Parameters:: specie_name (str) – Name of the species.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

reset_to_initial_state() → None[source]#

Reset all Fortran parameters to their initial cached values.

Restores: - All reaction parameters (alpha, beta, gamma) - All species binding energies

Examples

>>> network = RuntimeNetwork()
>>> network.modify_reaction_parameters(0, alpha=999.0)
>>> network.reset_to_initial_state()  # Restores original alpha

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

NOT SUPPORTED: Cannot replace reactions in compiled Fortran network.

Parameters:

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

Raises:

NotImplementedError – Always - Fortran arrays have fixed size

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

NOT SUPPORTED: Cannot replace reaction dictionary.

Parameters:: new_dict (dict[int, Reaction]) – Replacement reactions dictionary.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

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

NOT SUPPORTED: Cannot replace species in compiled Fortran network.

Parameters:

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

Raises:

NotImplementedError – Always - Fortran arrays have fixed size

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

NOT SUPPORTED: Cannot replace species dictionary.

Parameters:: new_species_dict (dict[str, Species]) – Replacement species dictionary.
Raises:: NotImplementedError – Always - Fortran arrays have fixed size

sort_reactions() → None[source]#

NOT SUPPORTED: Reaction order is fixed in compiled network.

Raises:: NotImplementedError – Always - reaction order is fixed

sort_species() → None[source]#

NOT SUPPORTED: Species order is fixed in compiled network.

Raises:: NotImplementedError – Always - species order is fixed

property fortran_module: types.ModuleType[source]#

Direct access to Fortran module for advanced users.

Warning: Use with caution. Direct modification bypasses safety checks.

Returns:: The underlying Fortran module handle for this runtime network.
Return type:: ModuleType