uclchem.makerates.species#

UCLCHEM Species.

Module Contents#

Classes#

Species

Species is a class that holds all the information about an individual species in the.

Functions#

`is_number`(→ bool)	Try to convert input to a float, if it succeeds, return True.
`normalize_species_name`(→ str)	Normalize a species name to a canonical form.
`sanitize_input_float`(→ float)	Sanitize the input. If the index is out of bounds of the row or the value.

Attributes#

`elementList`
`elementMass`
`logger`
`species_header`
`symbols`

class uclchem.makerates.species.Species(input_row: list[str | float] | pandas.Series)[source]#

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.

Parse a species row.

Uses the new extended order:

NAME,MASS,BINDING_ENERGY,SOLID_FRACTION,MONO_FRACTION,VOLCANO_FRACTION,ENTHALPY, DESORPTION_PREF,DIFFUSION_BARRIER,DIFFUSION_PREF,Ix,Iy,Iz,SYMMETRYFACTOR

Falls back to sensible defaults when fields are missing.

Parameters:: input_row (list[str | float] | pd.Series) – Row from the species CSV, as a list of values.

add_default_freeze() → None[source]#

Add a default freezeout, which is freezing out to the species itself,.

but with no ionization.

calculate_rotational_partition_factor() → float[source]#

Calculate 1/sigma*(SQRT(IxIyIz)) for non-linear molecules, and.

1/sigma*(SQRT(IyIz)) for linear molecules.

Returns -999.0 if molecular inertia data is not available (backward compatibility). This signals that TST prefactors cannot be used for this species.

Returns:: Rotational partition factor scaled by 1e50, or -999.0 if unavailable
Return type:: float

check_symmetry_factor() → None[source]#

Check the symmetry factor provided by the user.

Checks if n_atoms == 2, that if its homoatomic (e.g. H2), that sigma == 2, and if it is heteroatomic, (e.g. OH), sigma == 1

find_constituents(quiet: bool = False) → collections.Counter[str][source]#

Loop through the species’ name and work out what its constituent.

atoms are. Then calculate mass and alert user if it doesn’t match input mass.

Parameters:: quiet (bool) – If True, suppress warnings about unknown constituents. Defaults to False.
Returns:: Counter of how many times each element is in the molecule.
Return type:: Counter[str]
Raises:: ValueError – If the molecular formula is not valid, for example it has an element not in the element list, has no closing bracket, or starts with a digit.

Examples

>>> species = Species(['H2'] + [0] * 10)
>>> constituents = species.find_constituents()
>>> # Has the right number of H atoms
>>> constituents['H']
2
>>> # And 0 of the other atoms
>>> constituents['O']
0

>>> species = Species(['(CH3)2'] + [0] * 10)
>>> constituents = species.find_constituents()
>>> constituents['C'], constituents["H"]
(2, 6)

>>> species = Species(['C60'] + [0] * 10)
>>> constituents = species.find_constituents()
>>> constituents['C']
60

get_Ix() → float[source]#

Set the moment of inertia along the first principal axis.

Returns:: moment of inertia in amu/Angstrom^2
Return type:: float

get_Iy() → float[source]#

Set the moment of inertia along the second principal axis.

Returns:: moment of inertia in amu/Angstrom^2
Return type:: float

get_Iz() → float[source]#

Set the moment of inertia along the third principal axis.

Returns:: moment of inertia in amu/Angstrom^2
Return type:: float

get_binding_energy() → float[source]#

Get the binding energy of the species in K.

Returns:: The binding energy in K
Return type:: float

get_charge() → int[source]#

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][source]#

Obtain the desorbtion products of ice species.

Returns:: The desorption products
Return type:: list[str]
Raises:: AttributeError – If the species has no attribute desorb_products. This can occur if the species is a gas-phase species.

get_desorption_pref() → float[source]#

Get the desorption prefactor.

Alias getter matching CSV column name desorption_pref.

Returns:: The desorption prefactor in s-1
Return type:: float

get_diffusion_barrier() → float[source]#

Get the diffusion barrier for the species.

Returns:: The diffusion barrier in K
Return type:: float

get_diffusion_pref() → float[source]#

Set the diffusion prefactor.

Alias getter matching CSV column name diffusion_pref.

Returns:: The diffusion prefactor in s-1
Return type:: float

get_enthalpy() → float[source]#

Get the ice enthalpy of the species.

Returns:: The ice enthalpy
Return type:: float

get_freeze_alpha(product_list: list[str]) → float[source]#

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() → collections.abc.Iterator[tuple[list[str], float]][source]#

Obtain the product to which the species freeze out.

Yields:: tuple[list[str], float] – Iterator that returns all of the freeze out reactions with ratios

get_freeze_products_list() → list[list[str]][source]#

Get all the freeze products without their ratios.

Returns:: List of freeze products
Return type:: list[list[str]]

get_mass() → int[source]#

Get the molecular mass of the chemical species.

Returns:: The molecular mass in atomic mass units.
Return type:: int

get_mono_fraction() → float[source]#

Get the monolayer fraction of the species.

Returns:: The monolayer fraction
Return type:: float

get_n_atoms() → int[source]#

Get the number of atoms in the molecule.

Returns:: The number of atoms
Return type:: int

get_name() → str[source]#

Get the name of the chemical species.

Returns:: The name
Return type:: str

get_solid_fraction() → float[source]#

Get the solid fraction of the species.

Returns:: The solid fraction
Return type:: float

get_standard_desorb_products() → list[str][source]#

Return the 1:1 gas-phase counterpart by stripping the grain prefix.

For #CH4 returns [CH4, NAN, NAN, NAN]. Always a single product — used for gasIceList construction and auto-generated THERM/DESOH2/DESCR/DEUVCR reactions when the user has not provided explicit ones.

Returns:: [base_gas_species, NAN, NAN, NAN]
Return type:: list[str]

get_symmetry_factor() → int[source]#

Get the symmetry factor of the species.

Returns:: Symmetry factor
Return type:: int

get_vdes() → float[source]#

Get the desorption prefactor.

Returns:: The desorption prefactor in s-1
Return type:: float

get_vdiff() → float[source]#

Get the diffusion prefactor.

Returns:: The diffusion prefactor in s-1
Return type:: float

get_volcano_fraction() → float[source]#

Get the volcano fraction of the species.

Returns:: The volcano fraction
Return type:: float

is_bulk_species() → bool[source]#

Check if the species is in the bulk.

Returns:: True if a bulk species
Return type:: bool

is_grain_species() → bool[source]#

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[source]#

Return whether the species is a species on the grain.

Returns:: True if it is an ice species.
Return type:: bool

is_ion() → bool[source]#

Check if the species is ionized, either positively or negatively.

Returns:: True if it is ionized
Return type:: bool

is_linear() → bool[source]#

Check if molecule is linear based on moment of inertia.

For linear molecules, Ix = 0 (rotation axis along molecular axis has no inertia).

Returns:: True if linear, False otherwise
Return type:: bool

is_surface_species() → bool[source]#

Check if the species is on the surface.

Returns:: True if a surface species
Return type:: bool

set_Ix(Ix: float) → None[source]#

Set the moment of inertia along the first principal axis.

Parameters:: Ix (float) – desired moment of inertia (in amu/Angstrom^2)

set_Iy(Iy: float) → None[source]#

Set the moment of inertia along the second principal axis.

Parameters:: Iy (float) – desired moment of inertia (in amu/Angstrom^2)

set_Iz(Iz: float) → None[source]#

Set the moment of inertia along the third principal axis.

Parameters:: Iz (float) – desired moment of inertia (in amu/Angstrom^2)

set_binding_energy(binding_energy: float) → None[source]#

Set the binding energy of the species in K.

Parameters:: binding_energy (float) – The new binding energy in K

set_desorb_products(new_desorbs: list[str]) → None[source]#

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_desorption_pref(vdes: float) → None[source]#

Set the desorption prefactor.

Alias setter matching CSV column name desorption_pref.

Parameters:: vdes (float) – The desorption prefactor in s-1

set_diffusion_barrier(barrier: float) → None[source]#

Set the diffusion barrier for the species.

Parameters:: barrier (float) – Diffusion barrier in K

set_diffusion_pref(vdiff: float) → None[source]#

Set the diffusion prefactor.

Alias setter matching CSV column name diffusion_pref.

Parameters:: vdiff (float) – The diffusion prefactor in s-1

set_enthalpy(enthalpy: float) → None[source]#

Set the enthalpy of the species in kcal per mole.

Parameters:: enthalpy (float) – The new ice enthalpy

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

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.

set_mass(mass: int) → None[source]#

Set the molecular mass of the chemical species in atomic mass units.

Parameters:: mass (int) – The new molecular mass

set_mono_fraction(mono_fraction: float) → None[source]#

Set the monolayer fraction of the species.

Parameters:: mono_fraction (float) – The new monolayer fraction

set_n_atoms(new_n_atoms: int) → None[source]#

Set the number of atoms.

Parameters:: new_n_atoms (int) – The new number of atoms

set_name(name: str) → None[source]#

Set the name of the chemical species.

Parameters:: name (str) – The new name for the species

set_solid_fraction(solid_fraction: float) → None[source]#

Set the solid fraction of the species.

Parameters:: solid_fraction (float) – The new solid fraction

set_symmetry_factor(sym: int | str) → None[source]#

Set the symmetry factor of the species.

Sets the symmetry factor to -1 if sym cannot be turned into an integer.

Parameters:: sym (int | str) – Symmetry factor

set_vdes(vdes: float) → None[source]#

Set the desorption prefactor.

Parameters:: vdes (float) – The desorption prefactor in s-1

set_vdiff(vdiff: float) → None[source]#

Set the diffusion prefactor (vdiff) for the species.

Parameters:: vdiff (float) – The diffusion prefactor in s-1

set_volcano_fraction(volcano_fraction: float) → None[source]#

Set the volcano fraction of the species.

Parameters:: volcano_fraction (float) – The new volcano fraction

to_UCL_format() → str[source]#

Serialize to the extended UCLCHEM species CSV order.

Order: NAME,MASS,BINDING_ENERGY,SOLID_FRACTION,MONO_FRACTION,VOLCANO_FRACTION,ENTHALPY,: DESORPTION_PREF,DIFFUSION_BARRIER,DIFFUSION_PREF,Ix,Iy,Iz,SYMMETRYFACTOR

Returns:: String with species values shown in format shown above.
Return type:: str

diffusion_barrier = -1.0[source]#

enthalpy = -1.0[source]#

gains: str = ''[source]#

losses: str = ''[source]#

mass[source]#

monoFraction = -1.0[source]#

name = ''[source]#

prefix[source]#

solidFraction = -1.0[source]#

vdes = -1.0[source]#

vdiff = -1.0[source]#

volcFraction = -1.0[source]#

uclchem.makerates.species.is_number(s: Any) → bool[source]#

Try to convert input to a float, if it succeeds, return True.

Parameters:: s (Any) – Input object to check
Returns:: True if a number, False if not.
Return type:: bool

uclchem.makerates.species.normalize_species_name(name: str) → str[source]#

Normalize a species name to a canonical form.

Empty strings are preserved as empty strings. Other falsy values (like None) are converted to “NAN”. Grain prefixes (#/@) are preserved as-is. A chemical isomer prefix — a single alphabetic character followed by a hyphen (e.g. ‘o-’, ‘p-’, ‘a-’, ‘l-’) — is lowercased so that input is case-insensitive. The chemical formula part is uppercased. All other names are simply uppercased.

Parameters:: name (str) – Raw species name string to normalize.
Returns:: Normalized species name
Return type:: str

Examples

‘o-H2’ -> ‘o-H2’ ‘O-H2’ -> ‘o-H2’ (case-normalized prefix) ‘#o-H2’ -> ‘#o-H2’ ‘C-’ -> ‘C-’ (negative ion: len==2, not a prefix) ‘E-’ -> ‘E-’ (electron: same rule) ‘H2O’ -> ‘H2O’ ‘’ -> ‘’ (empty string) None -> ‘NAN’ (falsy non-string value)

uclchem.makerates.species.sanitize_input_float(row: list[Any], index: int, default: Any = 0.0) → float[source]#

Sanitize the input. If the index is out of bounds of the row or the value.

from the row cannot be turned into a float, use the default value. Otherwise, just gets the value from the row.

Parameters:

row (list[Any]) – list of objects
index (int) – index within list to use
default (Any) – default value to use. Default = 0.0.

Returns:

sanitized value.

Return type:

float

uclchem.makerates.species.elementList = ['H', 'D', 'HE', 'C', 'N', 'O', 'F', 'P', 'S', 'CL', 'LI', 'NA', 'MG', 'SI', 'PAH', '15N',...[source]#

uclchem.makerates.species.elementMass = [1, 2, 4, 12, 14, 16, 19, 31, 32, 35, 3, 23, 24, 28, 420, 15, 13, 18, 0, 56][source]#

uclchem.makerates.species.logger[source]#

uclchem.makerates.species.species_header = ('NAME', 'MASS', 'BINDING_ENERGY', 'SOLID_FRACTION', 'MONO_FRACTION', 'VOLCANO_FRACTION',...[source]#

uclchem.makerates.species.symbols = ['#', '@', '*', '+', '-', '(', ')'][source]#