uclchem.makerates

Submodules

• uclchem.makerates.io_functions
• uclchem.makerates.makerates
• uclchem.makerates.network
• uclchem.makerates.reaction
• uclchem.makerates.species

Package Contents

Classes

Network	The network class stores all the information about reaction network.
Reaction
Species	Species is a class that holds all the information about an individual species in the

Functions

run_makerates(→ uclchem.makerates.network.Network)

The main run wrapper for makerates, it loads a configuration, parses it in Network

class uclchem.makerates.Network(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction], user_defined_bulk: list = [], gas_phase_extrapolation: bool = False, add_crp_photo_to_grain: bool = False)

The network class stores all the information about reaction network.

A class to store network information such as indices of important reactions.

The class fully utilizes getters and setters, which can be used to add/remove reactions and the species involved. Important is that you do not directly edit the internal dictionaries that store the species and reactions, unless you know what you are doing. The network by default checks for duplicates in species and identical reactions that overlap in temperature ranges, potentially causing problems.

Parameters:

• species (list[Species]) – A list of chemical species that are added to the network

• reactions (list[Reaction]) – A list of chemical reactions that are added to the network

• user_defined_bulk (list, optional) – List of user defined bulk. Defaults to [].

• add_crp_photo_to_grain (bool, optional) – Whether to add CRP, CRPHOT and PHOTON reactions from gas-phase into solid phase too.

add_CRP_and_PHOTO_reactions_to_grain() → None

Add all the gas-phase reactions with CRP, CRPHOT or PHOTON to the grain surface too

add_bulk_reactions() → None

We assume any reaction that happens on the surface of grains can also happen in the bulk (just more slowly due to binding energy). The user therefore only lists surface reactions in their input reaction file and we duplicate here.

add_bulk_species() → None

For three phase models, MakeRates will produce the version of the species in the bulk so that the user doesn’t have to endlessly relist the same species

add_chemdes_reactions() → None

We have the user list all Langmuir-Hinshelwood and Eley-Rideal reactions once. Then we duplicate so that the reaction branches with products on grain and products desorbing.

add_desorb_reactions() → None

Save the user effort by automatically generating desorption reactions

add_excited_surface_reactions() → None

All excited species will relax to the ground state if they do not react the vibrational frequency of the species is used as a pseudo approximation of the rate coefficient We assume all grain reactions have an excited variant. For example: #A, #B LH #C will have the variants: #A*, #B EXSOLID #C and #A, #B* EXSOLID #C If only one of the reactants in the base reaction has an excited counterpart then only one excited version of that reaction is created.

add_freeze_reactions() → None

Save the user effort by automatically generating freeze out reactions

add_gas_phase_extrapolation()

add_reactions(reactions: uclchem.makerates.reaction.Reaction | str | list[uclchem.makerates.reaction.Reaction | str])

Add a reaction, list of inputs to the Reaction class or list of reactions to the network.

Parameters:

reactions (Union[Union[Reaction, str], list[Union[Reaction, str]]]) – Reaction or list or reactions

add_species(species: uclchem.makerates.species.Species | str | list[uclchem.makerates.species.Species | str])

Add species to the network, given a (list of) species. If it is a list of strings, it tries to instantiate a species class with it. It also checks for duplicate entries and filters out attempts to add reaction types to the species.

Parameters:

species (Union[Union[Species, str], list[Union[Species, str]]]) – A (list of) species or strings.

Raises:

• ValueError – If we cannot parse the (list of) reactions

• ValueError – If an ice specie with binding energy of zero is added.

branching_ratios_checks() → None

Check that the branching ratios for the ice reactions sum to 1.0. If they do not, correct them. This needs to be done for LH and LHDES separately since we already added the desorption to the network.

change_binding_energy(specie: str, new_binding_energy: float) → None

change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) → None

check_and_filter_species() → None

Check every speces in network appears in at least one reaction. Remove any that do not and alert user.

check_for_excited_species() → bool

Check if there are any exicted species in the network, true if there are any.

check_freeze_and_desorbs() → None

add_freeze_reactions() and add_desorb_reactions() automatically generate all desorption and freeze out reactions. However, user may want to change a species on freeze out eg C+ becomes #C rather than #C+. This function checks for that and updates species so they’ll freeze or desorb correctly when reactions are generated.

check_network() → None

Run through the list of reactions and check for obvious errors such as duplicate reactions, multiple freeze out routes (to warn, not necessarily an error), etc.

duplicate_checks() → None

Check reaction network to make sure no reaction appears twice unless they have different temperature ranges.

find_similar_reactions(reaction: uclchem.makerates.reaction.Reaction) → dict[int, uclchem.makerates.reaction.Reaction]

Reactions are similar if the reaction has the same reactants and products, find all reactions that are similar, returning their index and the reaction itself.

Parameters:

reaction (Reaction) – Reaction with possible identical (but for temperature range) reactions in the network

Returns:

A dict with the identical reactions.

Return type:

dict[int, Reaction]

freeze_checks() → None

Check that every species freezes out and alert the user if a species freezes out via mutiple routes. This isn’t necessarily an error so best just print.

get_reaction(reaction_idx: int) → uclchem.makerates.reaction.Reaction

Obtain a reaction from the reaction set given an index of the internal _reactions_dict.

Parameters:

reaction_idx (int) – The reaction index

Returns:

the desired reaction

Return type:

Reaction

get_reaction_dict() → dict[int, uclchem.makerates.reaction.Reaction]

Returns the whole internal reaction dictionary.

Returns:

A copy of the internal reactions dictionary.

Return type:

dict[int, Reaction]

get_reaction_index(reaction: uclchem.makerates.reaction.Reaction) → int

Get the index of a reaction in the internal _reactions_dict.

Parameters:

reaction (Reaction) – The reaction to find the index of

Returns:

The index of the reaction in the internal _reactions_dict

Return type:

int

get_reaction_list() → list[uclchem.makerates.reaction.Reaction]

Obtain all the reactions in the Network.

Returns:

A list with all the reaction objects

Return type:

list[Reaction]

get_reactions_by_types(reaction_type: str | list[str]) → list[uclchem.makerates.reaction.Reaction]

Get the union of all reactions of a certain type.

Parameters:

reaction_type (str) – The reaction type to filter on

Returns:

A list of reactions of the specified type

Return type:

list[Reaction]

get_reactions_on_grain() → list[uclchem.makerates.reaction.Reaction]

get_specie(specie_name: str) → uclchem.makerates.species.Species

Get the species of the reaction network (from the internal dictionary)

Parameters:

specie_name (str) – the name of the species as a string

Returns:

The species object

Return type:

Species

get_species_dict() → dict[str, uclchem.makerates.species.Species]

Get the internal dictionary that stores all the species, it consists of all species’ names as key, with the species object as value.

Returns:

A dictionary with the species

Return type:

dict[str, Species]

get_species_list() → list[uclchem.makerates.species.Species]

Obtain a list with all the species in the network

Returns:

A list of all the species in the reaction network

Return type:

list[Species]

index_important_reactions() → None

We have a whole bunch of important reactions and we want to store their indices. We find them all here.

index_important_species() → None

Obtain the indices for all the important reactions.

remove_reaction(reaction: uclchem.makerates.reaction.Reaction) → None

Remove the reaction by giving the object itself, this only works if the reaction is not piecewise defined across the temperature ranges.

Parameters:

reaction (Reaction) – The reaction you wish to delete.

remove_reaction_by_index(reaction_idx: int) → None

Remove a reaction by its index in the internal _reactions_dict, this is the only way to remove reactions that are defined piecewise across temperature ranges.

Parameters:

reaction_idx (int) – Index of the reaction to remove

remove_species(specie_name: str) → None

Remove a specie from the network

Parameters:

specie_name (str) – Species to remove

set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) → None

This setter explicitely sets the reaction for a certain index.

Parameters:

• reaction_idx (int) – The index to be written to

• reaction (Reaction) – The reaction to be added to the index.

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

Override the reactions dictionary with a new dictionar.

Parameters:

new_dict (dict[int, Reaction]) – The new reactions_dictionary.

set_specie(species_name: str, species: uclchem.makerates.species.Species) → None

Set the species of the reaction network in the internal dictionary

Parameters:

• species_name (str) – The name of the species as string

• species (Species) – The Species object to set

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

Set the internal species dict

Parameters:

new_species_dict (dict[str, Species]) – The new dictionary to set

sort_reactions() → None

Sort the reaction dictionary by reaction type first and by the first reactant second.

sort_species() → None

Sort the species based on their mass in ascending order. We always make sure the Electron is last.

add_crp_photo_to_grain = False

excited_species = False

property reaction_list

property reactions

property species

property species_list

user_defined_bulk = []

class uclchem.makerates.Reaction(inputRow, reaction_source=None)

NANCheck(a)

Convert any Falsy statement to a NAN string

Parameters:

a – thing to check for falsiness

Returns:

input a if truthy, otherwise NAN

Return type:

bool

changes_surface_count()

This checks 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.

changes_total_mantle()

Check if the total grains on the mantle are changed by the reaction.

check_charge_conservation() → None

check_element_conservation() → None

check_temperature_collision(other) → bool

Check if two reactions have overlapping temperature ranges, returning True means there is a collision.

Parameters:

other – Another reaction

Raises:

NotImplementedError – Currently we can only compare against instantiated Reaction objects.

Returns:

Whether there is a collision (True), or not (False)

Return type:

bool

convert_gas_to_surf() → None

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

Convert the surface species to bulk species in place for this reaction.

generate_ode_bit(i: int, species_names: list)

get_alpha() → float

Get the alpha parameter from the Kooij-Arrhenius equation

Returns:

the alpha parameter of the reaction

Return type:

float

get_beta() → float

Get the beta parameter from the Kooij-Arrhenius equation

Returns:

the beta parameter of the reaction

Return type:

float

get_extrapolation() → bool

get_gamma() → float

Get the gamma parameter from the Kooij-Arrhenius equation

Returns:

the gamma parameter of the reaction

Return type:

float

get_products() → list[str]

Get the four products present in the reaction, padded with NAN for nonexistent

Parameters:

reactants (list[str]) – The four products names

get_pure_products() → list[str]

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]

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]

Get the four reactants present in the reaction, padded with NAN for nonexistent

Returns:

The four reactants names

Return type:

list[str]

get_reaction_type() → str

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.

Return type:

str

get_reduced_mass() → float

Get the reduced mass to be used to calculate tunneling rate in AMU

Returns:

reduced mass of moving atoms

Return type:

float

get_sorted_products() → list[str]

Get the four products present in the reaction, sorted for fast comparisons

Parameters:

products (list[str]) – The four sorted products names

get_sorted_reactants() → list[str]

Get the four reactants present in the reaction, sorted for fast comparisons

Parameters:

reactants (list[str]) – The four sorted reactant names

get_source() → str

Get the source of the reaction

Returns:

The source of the reaction

Return type:

str

get_temphigh() → float

Get the higher temperature boundary of the reaction in Kelvin

Returns:

the higher temperature boundary

Return type:

float

get_templow() → float

Get the lower temperature boundary of the reaction in Kelvin

Returns:

the lower temperature boundary

Return type:

float

is_bulk_reaction(include_reactants=True, include_products=True, strict=False) → bool

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, optional) – Include the reactants. Defaults to True.

• include_products (bool, optional) – Include the products. Defaults to True.

• strict (bool, optional) – 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=True, include_products=True, strict=True) → bool

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, optional) – Include the reactants. Defaults to True.

• include_products (bool, optional) – Include the products. Defaults to True.

• strict (bool, optional) – 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=True, include_products=True, strict=True) → bool

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, optional) – Include the reactants. Defaults to True.

• include_products (bool, optional) – Include the products. Defaults to True.

• strict (bool, optional) – 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=True, include_products=True, strict=False) → bool

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, optional) – Include the reactants. Defaults to True.

• include_products (bool, optional) – Include the products. Defaults to True.

• strict (bool, optional) – 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

Predict the reduced mass of the tunneling particle in this reaction. This is used in the calculation of the tunneling rates.

set_alpha(alpha: float) → None

Set the alpha parameter from the Kooij-Arrhenius equation

Parameters:

alpha (float) – the alpha parameter of the reaction

set_beta(beta: float) → None

Set the beta parameter from the Kooij-Arrhenius equation

Parameters:

beta (float) – the beta parameter of the reaction

set_extrapolation(flag: bool) → None

set_gamma(gamma: float) → None

Set the gamma parameter from the Kooij-Arrhenius equation

Parameters:

gamma (float) – the gamma parameter of the reaction

set_products(products: list[str]) → None

Set the four products present in the reaction, padded with NAN for nonexistent

Parameters:

products (list[str]) – The four products names

set_reactants(reactants: list[str]) → None

Set the four reactants present in the reaction, padded with NAN for nonexistent

Parameters:

reactants (list[str]) – The four reactants names

set_reduced_mass(reduced_mass: float) → None

Set the reduced mass to be used to calculate tunneling rate in AMU

Parameters:

reduced_mass (float) – reduced mass of moving atoms

set_source(source: str) → None

Set the source of the reaction

Parameters:

source (str) – The source of the reaction

set_temphigh(temphigh: float) → None

Set the higher temperature boundary of the reaction in Kelvin

Parameters:

templow (float) – the higher temperature boundary

set_templow(templow: float) → None

Set the lower temperature boundary of the reaction in Kelvin

Parameters:

templow (float) – the lower temperature boundary

to_UCL_format()

Convert a reaction to UCLCHEM reaction file format

body_count = -1

duplicate = False

source = None

class uclchem.makerates.Species(inputRow)

Species is a class that holds all the information about an individual species in the network. It also has convenience functions to check whether the species is a gas or grain species and to help compare between species.

A class representing chemical species, it reads in rows which are formatted as follows: NAME,MASS,BINDING ENERGY,SOLID FRACTION,MONO FRACTION,VOLCANO FRACTION,ENTHALPY :param inputRow: :type inputRow: list

add_default_freeze() → None

Adds a defalt freezeout, which is freezing out to the species itself, but with no ionization.

find_constituents(quiet=False)

Loop through the species’ name and work out what its consituent atoms are. Then calculate mass and alert user if it doesn’t match input mass.

get_charge() → int

Get the charge of the chemical species in e. Positive integer indicates positive ion, negative indicates negative ion. Assumes species are at most charged +1 or -1.

Returns:

The charge of the species

Return type:

int

get_desorb_products() → list[str]

Obtain the desorbtion products of ice species

Returns:

The desorption products

Return type:

list[str]

get_freeze_alpha(product_list: list[str]) → float

Obtain the freeze out ratio of a species for a certain reaction

Parameters:

product_list (list[str]) – For a specific reaction, get the freezeout ratio

Returns:

The freezeout ratio

Return type:

float

get_freeze_products() → dict[list[str], float]

Obtain the product to which the species freeze out

Returns:

Reactions and their respective freeze out ratios.

Return type:

dict[str, float]

Yields:

Iterator[dict[str, float]] – Iterator that returns all of the freeze out reactions with ratios

get_freeze_products_list() → list[list[str]]

Returns all the freeze products without their ratios

Returns:

List of freeze products

Return type:

list[list[str]]

get_mass() → int

Get the molecular mass of the chemical species

Returns:

The molecular mass

Return type:

int

get_n_atoms() → int

Obtain the number of atoms in the molecule

Returns:

The number of atoms

Return type:

int

get_name() → str

Get the name of the chemical species.

Returns:

The name

Return type:

str

is_bulk_species() → bool

Checks if the species is in the bulk

Returns:

True if a bulk species

Return type:

bool

is_grain_species() → bool

Return whether the species is a species on the grain

Returns:

True if it is a grain species.

Return type:

bool

is_ice_species() → bool

Return whether the species is a species on the grain

Returns:

True if it is an ice species.

Return type:

bool

is_ion() → bool

Checks if the species is ionized, either postively or negatively.

Returns:

True if it is an ionized

Return type:

bool

is_surface_species() → bool

Checks if the species is on the surface

Returns:

True if a surface species

Return type:

bool

set_desorb_products(new_desorbs: list[str]) → None

Set the desorption products for species on the surface or in the bulk. It is assumed that there is only one desorption pathway.

Parameters:

new_desorbs (list[str]) – The new desorption products

set_freeze_products(product_list: list[str], freeze_alpha: float) → None

Add the freeze products of the species, one species can have several freeze products.

Parameters:

• product_list (list[str]) – The list of freeze out products

• freeze_alpha (float) – The freeze out ratio.

It is called alpha, since it is derived from the alpha column in the UCLCHEM reaction format: uclchem/UCLCHEM

set_n_atoms(new_n_atoms: int) → None

Set the number of atoms

Parameters:

new_n_atoms (int) – The new number of atoms

to_UCL_format() → str

enthalpy

is_refractory = False

mass

monoFraction

n_atoms = 0

name

solidFraction

volcFraction

uclchem.makerates.run_makerates(configuration_file: str = 'user_settings.yaml', write_files: bool = True) → uclchem.makerates.network.Network

The main run wrapper for makerates, it loads a configuration, parses it in Network and then returns the Network. It by default writes to the uclchem fortran directory, but this can be skipped.

Parameters:

• configuration_file (str, optional) – A UCLCHEM Makerates configuration file. Defaults to “user_settings.yaml”.

• write_files (bool, optional) – Whether to write the fortran files to the src/fortran_src. Defaults to True.

Raises:

KeyError – The configuration cannot be found

Returns:

A chemical network instance.

Return type:

Network