uclchem.makerates.species ========================= .. py:module:: uclchem.makerates.species .. autoapi-nested-parse:: UCLCHEM Species. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: uclchem.makerates.species.Species Functions ~~~~~~~~~ .. autoapisummary:: uclchem.makerates.species.is_number uclchem.makerates.species.normalize_species_name uclchem.makerates.species.sanitize_input_float Attributes ~~~~~~~~~~ .. autoapisummary:: uclchem.makerates.species.elementList uclchem.makerates.species.elementMass uclchem.makerates.species.logger uclchem.makerates.species.species_header uclchem.makerates.species.symbols .. py:class:: Species(input_row: list[str | float] | pandas.Series) 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. :param input_row: Row from the species CSV, as a list of values. :type input_row: list[str | float] | pd.Series .. py:method:: add_default_freeze() -> None Add a default freezeout, which is freezing out to the species itself,. but with no ionization. .. py:method:: calculate_rotational_partition_factor() -> float 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 :rtype: float .. py:method:: check_symmetry_factor() -> None 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 .. py:method:: find_constituents(quiet: bool = False) -> collections.Counter[str] 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. :param quiet: If ``True``, suppress warnings about unknown constituents. Defaults to ``False``. :type quiet: bool :returns: Counter of how many times each element is in the molecule. :rtype: 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. .. rubric:: 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 .. py:method:: get_Ix() -> float Set the moment of inertia along the first principal axis. :returns: moment of inertia in amu/Angstrom^2 :rtype: float .. py:method:: get_Iy() -> float Set the moment of inertia along the second principal axis. :returns: moment of inertia in amu/Angstrom^2 :rtype: float .. py:method:: get_Iz() -> float Set the moment of inertia along the third principal axis. :returns: moment of inertia in amu/Angstrom^2 :rtype: float .. py:method:: get_binding_energy() -> float Get the binding energy of the species in K. :returns: The binding energy in K :rtype: float .. py:method:: 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 :rtype: int .. py:method:: get_desorb_products() -> list[str] Obtain the desorbtion products of ice species. :returns: The desorption products :rtype: list[str] :raises AttributeError: If the species has no attribute `desorb_products`. This can occur if the species is a gas-phase species. .. py:method:: get_desorption_pref() -> float Get the desorption prefactor. Alias getter matching CSV column name `desorption_pref`. :returns: The desorption prefactor in s-1 :rtype: float .. py:method:: get_diffusion_barrier() -> float Get the diffusion barrier for the species. :returns: The diffusion barrier in K :rtype: float .. py:method:: get_diffusion_pref() -> float Set the diffusion prefactor. Alias getter matching CSV column name `diffusion_pref`. :returns: The diffusion prefactor in s-1 :rtype: float .. py:method:: get_enthalpy() -> float Get the ice enthalpy of the species. :returns: The ice enthalpy :rtype: float .. py:method:: get_freeze_alpha(product_list: list[str]) -> float Obtain the freeze out ratio of a species for a certain reaction. :param product_list: For a specific reaction, get the freezeout ratio :type product_list: list[str] :returns: The freezeout ratio :rtype: float .. py:method:: get_freeze_products() -> collections.abc.Iterator[tuple[list[str], float]] 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 .. py:method:: get_freeze_products_list() -> list[list[str]] Get all the freeze products without their ratios. :returns: List of freeze products :rtype: list[list[str]] .. py:method:: get_mass() -> int Get the molecular mass of the chemical species. :returns: The molecular mass in atomic mass units. :rtype: int .. py:method:: get_mono_fraction() -> float Get the monolayer fraction of the species. :returns: The monolayer fraction :rtype: float .. py:method:: get_n_atoms() -> int Get the number of atoms in the molecule. :returns: The number of atoms :rtype: int .. py:method:: get_name() -> str Get the name of the chemical species. :returns: The name :rtype: str .. py:method:: get_solid_fraction() -> float Get the solid fraction of the species. :returns: The solid fraction :rtype: float .. py:method:: get_standard_desorb_products() -> list[str] 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] :rtype: list[str] .. py:method:: get_symmetry_factor() -> int Get the symmetry factor of the species. :returns: Symmetry factor :rtype: int .. py:method:: get_vdes() -> float Get the desorption prefactor. :returns: The desorption prefactor in s-1 :rtype: float .. py:method:: get_vdiff() -> float Get the diffusion prefactor. :returns: The diffusion prefactor in s-1 :rtype: float .. py:method:: get_volcano_fraction() -> float Get the volcano fraction of the species. :returns: The volcano fraction :rtype: float .. py:method:: is_bulk_species() -> bool Check if the species is in the bulk. :returns: True if a bulk species :rtype: bool .. py:method:: is_grain_species() -> bool Return whether the species is a species on the grain. :returns: True if it is a grain species. :rtype: bool .. py:method:: is_ice_species() -> bool Return whether the species is a species on the grain. :returns: True if it is an ice species. :rtype: bool .. py:method:: is_ion() -> bool Check if the species is ionized, either positively or negatively. :returns: True if it is ionized :rtype: bool .. py:method:: is_linear() -> bool 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 :rtype: bool .. py:method:: is_surface_species() -> bool Check if the species is on the surface. :returns: True if a surface species :rtype: bool .. py:method:: set_Ix(Ix: float) -> None Set the moment of inertia along the first principal axis. :param Ix: desired moment of inertia (in amu/Angstrom^2) :type Ix: float .. py:method:: set_Iy(Iy: float) -> None Set the moment of inertia along the second principal axis. :param Iy: desired moment of inertia (in amu/Angstrom^2) :type Iy: float .. py:method:: set_Iz(Iz: float) -> None Set the moment of inertia along the third principal axis. :param Iz: desired moment of inertia (in amu/Angstrom^2) :type Iz: float .. py:method:: set_binding_energy(binding_energy: float) -> None Set the binding energy of the species in K. :param binding_energy: The new binding energy in K :type binding_energy: float .. py:method:: 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. :param new_desorbs: The new desorption products :type new_desorbs: list[str] .. py:method:: set_desorption_pref(vdes: float) -> None Set the desorption prefactor. Alias setter matching CSV column name `desorption_pref`. :param vdes: The desorption prefactor in s-1 :type vdes: float .. py:method:: set_diffusion_barrier(barrier: float) -> None Set the diffusion barrier for the species. :param barrier: Diffusion barrier in K :type barrier: float .. py:method:: set_diffusion_pref(vdiff: float) -> None Set the diffusion prefactor. Alias setter matching CSV column name `diffusion_pref`. :param vdiff: The diffusion prefactor in s-1 :type vdiff: float .. py:method:: set_enthalpy(enthalpy: float) -> None Set the enthalpy of the species in kcal per mole. :param enthalpy: The new ice enthalpy :type enthalpy: float .. py:method:: 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. :param product_list: The list of freeze out products :type product_list: list[str] :param freeze_alpha: The freeze out ratio. :type freeze_alpha: float .. py:method:: set_mass(mass: int) -> None Set the molecular mass of the chemical species in atomic mass units. :param mass: The new molecular mass :type mass: int .. py:method:: set_mono_fraction(mono_fraction: float) -> None Set the monolayer fraction of the species. :param mono_fraction: The new monolayer fraction :type mono_fraction: float .. py:method:: set_n_atoms(new_n_atoms: int) -> None Set the number of atoms. :param new_n_atoms: The new number of atoms :type new_n_atoms: int .. py:method:: set_name(name: str) -> None Set the name of the chemical species. :param name: The new name for the species :type name: str .. py:method:: set_solid_fraction(solid_fraction: float) -> None Set the solid fraction of the species. :param solid_fraction: The new solid fraction :type solid_fraction: float .. py:method:: set_symmetry_factor(sym: int | str) -> None Set the symmetry factor of the species. Sets the symmetry factor to -1 if `sym` cannot be turned into an integer. :param sym: Symmetry factor :type sym: int | str .. py:method:: set_vdes(vdes: float) -> None Set the desorption prefactor. :param vdes: The desorption prefactor in s-1 :type vdes: float .. py:method:: set_vdiff(vdiff: float) -> None Set the diffusion prefactor (vdiff) for the species. :param vdiff: The diffusion prefactor in s-1 :type vdiff: float .. py:method:: set_volcano_fraction(volcano_fraction: float) -> None Set the volcano fraction of the species. :param volcano_fraction: The new volcano fraction :type volcano_fraction: float .. py:method:: to_UCL_format() -> str 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. :rtype: str .. py:attribute:: diffusion_barrier :value: -1.0 .. py:attribute:: enthalpy :value: -1.0 .. py:attribute:: gains :type: str :value: '' .. py:attribute:: losses :type: str :value: '' .. py:attribute:: mass .. py:attribute:: monoFraction :value: -1.0 .. py:attribute:: name :value: '' .. py:attribute:: prefix .. py:attribute:: solidFraction :value: -1.0 .. py:attribute:: vdes :value: -1.0 .. py:attribute:: vdiff :value: -1.0 .. py:attribute:: volcFraction :value: -1.0 .. py:function:: is_number(s: Any) -> bool Try to convert input to a float, if it succeeds, return True. :param s: Input object to check :type s: Any :returns: True if a number, False if not. :rtype: bool .. py:function:: normalize_species_name(name: str) -> str 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. :param name: Raw species name string to normalize. :type name: str :returns: Normalized species name :rtype: str .. rubric:: 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) .. py:function:: sanitize_input_float(row: list[Any], index: int, default: Any = 0.0) -> float 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. :param row: list of objects :type row: list[Any] :param index: index within list to use :type index: int :param default: default value to use. Default = 0.0. :type default: Any :returns: sanitized value. :rtype: float .. py:data:: elementList :value: ['H', 'D', 'HE', 'C', 'N', 'O', 'F', 'P', 'S', 'CL', 'LI', 'NA', 'MG', 'SI', 'PAH', '15N',... .. py:data:: elementMass :value: [1, 2, 4, 12, 14, 16, 19, 31, 32, 35, 3, 23, 24, 28, 420, 15, 13, 18, 0, 56] .. py:data:: logger .. py:data:: species_header :value: ('NAME', 'MASS', 'BINDING_ENERGY', 'SOLID_FRACTION', 'MONO_FRACTION', 'VOLCANO_FRACTION',... .. py:data:: symbols :value: ['#', '@', '*', '+', '-', '(', ')']