uclchem.makerates.reaction#

UCLCHEM Reaction.

Module Contents#

Classes#

`CoupledReaction`	Representation of reactions that are coupled to another Reaction instance.
`Reaction`	Representation of reactions.

Functions#

skip_reaction_validation(→ collections.abc.Iterator[None])

Context manager to temporarily disable reaction validation.

Attributes#

`ER_REACTION_TYPES`
`LH_REACTION_TYPES`
`REACTION_TYPES`
`TUNNELING_REACTION_TYPES`
`logger`
`reaction_header`

class uclchem.makerates.reaction.CoupledReaction(input: list[str | float] | Reaction)[source]#

Bases: Reaction

Representation of reactions that are coupled to another Reaction instance.

This means that if a reaction has a parameter changed by, for example, network.change_binding_energy(), every CoupledReaction that has that instance as its partner also has its binding energy changed to that value.

Initialize the CoupledReaction.

Parameters:: input (list[str | float] | Reaction) – Either a Reaction object to copy, or a list with reaction data.

get_partner() → Reaction | None[source]#

Get the partner.

Returns:: partner of this reaction.
Return type:: Reaction | None

set_partner(partner: Reaction) → None[source]#

Set the partner.

Parameters:: partner (Reaction) – partner of this reaction.
Raises:: TypeError – if parter is not an instance of a Reaction.

partner: Reaction | None = None[source]#

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

duplicate = False[source]#

source = None[source]#

uclchem.makerates.reaction.skip_reaction_validation() → collections.abc.Iterator[None][source]#

Context manager to temporarily disable reaction validation.

This is useful when loading pre-validated networks where you do not necessarily want to check element and charge conservation.

Yields:: None – Control is yielded to the with block.

Examples

>>> with skip_reaction_validation():
...     reaction = Reaction(["#C2N", "LH", "NAN", "#CH3CNH", "NAN", "NAN", "NAN"]+ [0] * 10)
>>> reaction = Reaction(["#C2N", "LH", "NAN", "#CH3CNH", "NAN", "NAN", "NAN"] + [0] * 10)
Traceback (most recent call last):
...
ValueError: Elements not conserved in a reaction.
The following reaction caused this error: #C2N + LH -> #CH3CNH.
...

uclchem.makerates.reaction.ER_REACTION_TYPES[source]#

uclchem.makerates.reaction.LH_REACTION_TYPES[source]#

uclchem.makerates.reaction.REACTION_TYPES = ['PHOTON', 'CRP', 'CRPHOT', 'FREEZE', 'DESORB', 'THERM', 'DESOH2', 'DESCR', 'DEUVCR', 'H2FORM',...[source]#

uclchem.makerates.reaction.TUNNELING_REACTION_TYPES[source]#

uclchem.makerates.reaction.logger[source]#

uclchem.makerates.reaction.reaction_header = ['REACTANT 1', 'REACTANT 2', 'REACTANT 3', 'PRODUCT 1', 'PRODUCT 2', 'PRODUCT 3', 'PRODUCT 4',...[source]#