uclchem.advanced.runtime_network ================================ .. py:module:: uclchem.advanced.runtime_network .. autoapi-nested-parse:: 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 ~~~~~~~ .. autoapisummary:: uclchem.advanced.runtime_network.RuntimeNetwork .. py:class:: RuntimeNetwork Bases: :py:obj:`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 :meth:`reset_to_initial_state`. .. rubric:: 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 .. py:method:: add_reactions(reactions: uclchem.makerates.reaction.Reaction | list[uclchem.makerates.reaction.Reaction]) -> None NOT SUPPORTED: Cannot add reactions to compiled Fortran network. :param reactions: Reactions to add to the network. :type reactions: Reaction | list[Reaction] :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: add_species(species: uclchem.makerates.species.Species | list[uclchem.makerates.species.Species]) -> None NOT SUPPORTED: Cannot add species to compiled Fortran network. :param species: Species instance or list of species to add. :type species: Species | list[Species] :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: change_binding_energy(specie: str, new_binding_energy: float) -> None Change binding energy of a species (modifies Fortran array). :param specie: Name of the species :type specie: str :param new_binding_energy: New binding energy in Kelvin :type new_binding_energy: float .. py:method:: change_diffusion_barrier(specie: str, new_diffusion_barrier: float) -> None Change diffusion barrier of a species (modifies Fortran array). :param specie: Name of the species. :type specie: str :param new_diffusion_barrier: New diffusion barrier in Kelvin. :type new_diffusion_barrier: float .. py:method:: change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) -> None Change activation barrier of a reaction (modifies Fortran gamma). :param reaction: Reaction to modify :type reaction: Reaction :param barrier: New activation barrier in Kelvin :type barrier: float :raises RuntimeError: If reaction is not a reaction on the ices. .. py:method:: disable_reaction(reaction_idx: int) -> None 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. :param reaction_idx: Index of reaction to disable (0-based) :type reaction_idx: int .. rubric:: Examples >>> network = RuntimeNetwork() >>> network.disable_reaction(5) >>> network.reset_to_initial_state() .. py:method:: modify_reaction_parameters(reaction_idx: int, alpha: float | None = None, beta: float | None = None, gamma: float | None = None) -> None Modify reaction rate parameters in Fortran arrays. :param reaction_idx: Index of reaction to modify (0-based) :type reaction_idx: int :param alpha: New alpha value (pre-exponential factor) (Default value = None) :type alpha: float | None :param beta: New beta value (temperature exponent) (Default value = None) :type beta: float | None :param gamma: New gamma value (activation energy in K) (Default value = None) :type gamma: float | None :raises IndexError: If reaction_idx out of range .. rubric:: Examples >>> network = RuntimeNetwork() >>> network.modify_reaction_parameters(0, alpha=1e-10, beta=2.0) >>> network.reset_to_initial_state() .. py:method:: remove_reaction(reaction: uclchem.makerates.reaction.Reaction) -> None NOT SUPPORTED: Cannot remove reactions from compiled Fortran network. Use disable_reaction() to set alpha=0 instead. :param reaction: Reaction instance to look up or modify. :type reaction: Reaction :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: remove_reaction_by_index(reaction_idx: int) -> None NOT SUPPORTED: Cannot remove reactions from compiled Fortran network. Use disable_reaction() to set alpha=0 instead. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: remove_species(specie_name: str) -> None NOT SUPPORTED: Cannot remove species from compiled Fortran network. :param specie_name: Name of the species. :type specie_name: str :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: reset_to_initial_state() -> None Reset all Fortran parameters to their initial cached values. Restores: - All reaction parameters (alpha, beta, gamma) - All species binding energies .. rubric:: Examples >>> network = RuntimeNetwork() >>> network.modify_reaction_parameters(0, alpha=999.0) >>> network.reset_to_initial_state() # Restores original alpha .. py:method:: set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) -> None NOT SUPPORTED: Cannot replace reactions in compiled Fortran network. :param reaction_idx: Index of the reaction in the network. :type reaction_idx: int :param reaction: Reaction instance to look up or modify. :type reaction: Reaction :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: set_reaction_dict(new_dict: dict[int, uclchem.makerates.reaction.Reaction]) -> None NOT SUPPORTED: Cannot replace reaction dictionary. :param new_dict: Replacement reactions dictionary. :type new_dict: dict[int, Reaction] :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: set_specie(species_name: str, species: uclchem.makerates.species.Species) -> None NOT SUPPORTED: Cannot replace species in compiled Fortran network. :param species_name: Name of the species. :type species_name: str :param species: Species instance or list of species to add. :type species: Species :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: set_species_dict(new_species_dict: dict[str, uclchem.makerates.species.Species]) -> None NOT SUPPORTED: Cannot replace species dictionary. :param new_species_dict: Replacement species dictionary. :type new_species_dict: dict[str, Species] :raises NotImplementedError: Always - Fortran arrays have fixed size .. py:method:: sort_reactions() -> None NOT SUPPORTED: Reaction order is fixed in compiled network. :raises NotImplementedError: Always - reaction order is fixed .. py:method:: sort_species() -> None NOT SUPPORTED: Species order is fixed in compiled network. :raises NotImplementedError: Always - species order is fixed .. py:property:: fortran_module :type: types.ModuleType 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. :rtype: ModuleType