uclchem.makerates ================= .. py:module:: uclchem.makerates Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 io_functions/index.rst makerates/index.rst network/index.rst reaction/index.rst species/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: uclchem.makerates.Network uclchem.makerates.Reaction uclchem.makerates.Species Functions ~~~~~~~~~ .. autoapisummary:: uclchem.makerates.run_makerates .. py:class:: 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. :param species: A list of chemical species that are added to the network :type species: list[Species] :param reactions: A list of chemical reactions that are added to the network :type reactions: list[Reaction] :param user_defined_bulk: List of user defined bulk. Defaults to []. :type user_defined_bulk: list, optional :param add_crp_photo_to_grain: Whether to add CRP, CRPHOT and PHOTON reactions from gas-phase into solid phase too. :type add_crp_photo_to_grain: bool, optional .. py:method:: add_CRP_and_PHOTO_reactions_to_grain() -> None Add all the gas-phase reactions with CRP, CRPHOT or PHOTON to the grain surface too .. py:method:: 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. .. py:method:: 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 .. py:method:: 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. .. py:method:: add_desorb_reactions() -> None Save the user effort by automatically generating desorption reactions .. py:method:: 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. .. py:method:: add_freeze_reactions() -> None Save the user effort by automatically generating freeze out reactions .. py:method:: add_gas_phase_extrapolation() .. py:method:: add_reactions(reactions: Union[Union[uclchem.makerates.reaction.Reaction, str], list[Union[uclchem.makerates.reaction.Reaction, str]]]) Add a reaction, list of inputs to the Reaction class or list of reactions to the network. :param reactions: Reaction or list or reactions :type reactions: Union[Union[Reaction, str], list[Union[Reaction, str]]] .. py:method:: add_species(species: Union[Union[uclchem.makerates.species.Species, str], list[Union[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. :param species: A (list of) species or strings. :type species: Union[Union[Species, str], list[Union[Species, str]]] :raises ValueError: If we cannot parse the (list of) reactions :raises ValueError: If an ice specie with binding energy of zero is added. .. py:method:: 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. .. py:method:: change_binding_energy(specie: str, new_binding_energy: float) -> None .. py:method:: change_reaction_barrier(reaction: uclchem.makerates.reaction.Reaction, barrier: float) -> None .. py:method:: check_and_filter_species() -> None Check every speces in network appears in at least one reaction. Remove any that do not and alert user. .. py:method:: check_for_excited_species() -> bool Check if there are any exicted species in the network, true if there are any. .. py:method:: 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. .. py:method:: 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. .. py:method:: duplicate_checks() -> None Check reaction network to make sure no reaction appears twice unless they have different temperature ranges. .. py:method:: 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. :param reaction: Reaction with possible identical (but for temperature range) reactions in the network :type reaction: Reaction :returns: A dict with the identical reactions. :rtype: dict[int, Reaction] .. py:method:: 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. .. py:method:: get_reaction(reaction_idx: int) -> uclchem.makerates.reaction.Reaction Obtain a reaction from the reaction set given an index of the internal _reactions_dict. :param reaction_idx: The reaction index :type reaction_idx: int :returns: the desired reaction :rtype: Reaction .. py:method:: get_reaction_dict() -> dict[int, uclchem.makerates.reaction.Reaction] Returns the whole internal reaction dictionary. :returns: A copy of the internal reactions dictionary. :rtype: dict[int, Reaction] .. py:method:: get_reaction_index(reaction: uclchem.makerates.reaction.Reaction) -> int Get the index of a reaction in the internal _reactions_dict. :param reaction: The reaction to find the index of :type reaction: Reaction :returns: The index of the reaction in the internal _reactions_dict :rtype: int .. py:method:: get_reaction_list() -> list[uclchem.makerates.reaction.Reaction] Obtain all the reactions in the Network. :returns: A list with all the reaction objects :rtype: list[Reaction] .. py:method:: get_reactions_by_types(reaction_type: Union[str, list[str]]) -> list[uclchem.makerates.reaction.Reaction] Get the union of all reactions of a certain type. :param reaction_type: The reaction type to filter on :type reaction_type: str :returns: A list of reactions of the specified type :rtype: list[Reaction] .. py:method:: get_reactions_on_grain() -> list[uclchem.makerates.reaction.Reaction] .. py:method:: get_specie(specie_name: str) -> uclchem.makerates.species.Species Get the species of the reaction network (from the internal dictionary) :param specie_name: the name of the species as a string :type specie_name: str :returns: The species object :rtype: Species .. py:method:: 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 :rtype: dict[str, Species] .. py:method:: 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 :rtype: list[Species] .. py:method:: index_important_reactions() -> None We have a whole bunch of important reactions and we want to store their indices. We find them all here. .. py:method:: index_important_species() -> None Obtain the indices for all the important reactions. .. py:method:: 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. :param reaction: The reaction you wish to delete. :type reaction: Reaction .. py:method:: 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. :param reaction_idx: Index of the reaction to remove :type reaction_idx: int .. py:method:: remove_species(specie_name: str) -> None Remove a specie from the network :param specie_name: Species to remove :type specie_name: str .. py:method:: set_reaction(reaction_idx: int, reaction: uclchem.makerates.reaction.Reaction) -> None This setter explicitely sets the reaction for a certain index. :param reaction_idx: The index to be written to :type reaction_idx: int :param reaction: The reaction to be added to the index. :type reaction: Reaction .. py:method:: set_reaction_dict(new_dict: dict[int, uclchem.makerates.reaction.Reaction]) -> None Override the reactions dictionary with a new dictionar. :param new_dict: The new reactions_dictionary. :type new_dict: dict[int, Reaction] .. py:method:: set_specie(species_name: str, species: uclchem.makerates.species.Species) -> None Set the species of the reaction network in the internal dictionary :param species_name: The name of the species as string :type species_name: str :param species: The Species object to set :type species: Species .. py:method:: set_species_dict(new_species_dict: dict[str, uclchem.makerates.species.Species]) -> None Set the internal species dict :param new_species_dict: The new dictionary to set :type new_species_dict: dict[str, Species] .. py:method:: sort_reactions() -> None Sort the reaction dictionary by reaction type first and by the first reactant second. .. py:method:: sort_species() -> None Sort the species based on their mass in ascending order. We always make sure the Electron is last. .. py:attribute:: add_crp_photo_to_grain :value: False .. py:attribute:: excited_species :value: False .. py:property:: reaction_list .. py:property:: reactions .. py:property:: species .. py:property:: species_list .. py:attribute:: user_defined_bulk :value: [] .. py:class:: Reaction(inputRow, reaction_source=None) .. py:method:: NANCheck(a) Convert any Falsy statement to a NAN string :param a: thing to check for falsiness :returns: input a if truthy, otherwise NAN :rtype: bool .. py:method:: 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. .. py:method:: changes_total_mantle() Check if the total grains on the mantle are changed by the reaction. .. py:method:: check_charge_conservation() -> None .. py:method:: check_element_conservation() -> None .. py:method:: check_temperature_collision(other) -> bool Check if two reactions have overlapping temperature ranges, returning True means there is a collision. :param other: Another reaction :raises NotImplementedError: Currently we can only compare against instantiated Reaction objects. :returns: Whether there is a collision (True), or not (False) :rtype: bool .. py:method:: 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. .. py:method:: convert_surf_to_bulk() -> None Convert the surface species to bulk species in place for this reaction. .. py:method:: generate_ode_bit(i: int, species_names: list) .. py:method:: get_alpha() -> float Get the alpha parameter from the Kooij-Arrhenius equation :returns: the alpha parameter of the reaction :rtype: float .. py:method:: get_beta() -> float Get the beta parameter from the Kooij-Arrhenius equation :returns: the beta parameter of the reaction :rtype: float .. py:method:: get_extrapolation() -> bool .. py:method:: get_gamma() -> float Get the gamma parameter from the Kooij-Arrhenius equation :returns: the gamma parameter of the reaction :rtype: float .. py:method:: get_products() -> list[str] Get the four products present in the reaction, padded with NAN for nonexistent :param reactants: The four products names :type reactants: list[str] .. py:method:: 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. :rtype: list[str] .. py:method:: get_pure_reactants() -> list[str] Get only the pure species, no reaction types and NAN entries :returns: The list of reacting species. :rtype: list[str] .. py:method:: get_reactants() -> list[str] Get the four reactants present in the reaction, padded with NAN for nonexistent :returns: The four reactants names :rtype: list[str] .. py:method:: 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. :rtype: str .. py:method:: get_reduced_mass() -> float Get the reduced mass to be used to calculate tunneling rate in AMU :returns: reduced mass of moving atoms :rtype: float .. py:method:: get_sorted_products() -> list[str] Get the four products present in the reaction, sorted for fast comparisons :param products: The four sorted products names :type products: list[str] .. py:method:: get_sorted_reactants() -> list[str] Get the four reactants present in the reaction, sorted for fast comparisons :param reactants: The four sorted reactant names :type reactants: list[str] .. py:method:: get_source() -> str Get the source of the reaction :returns: The source of the reaction :rtype: str .. py:method:: get_temphigh() -> float Get the higher temperature boundary of the reaction in Kelvin :returns: the higher temperature boundary :rtype: float .. py:method:: get_templow() -> float Get the lower temperature boundary of the reaction in Kelvin :returns: the lower temperature boundary :rtype: float .. py:method:: 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 :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool, optional :param include_products: Include the products. Defaults to True. :type include_products: bool, optional :param strict: Choose between all (true) or any (false) must in the bulk . Defaults to False. :type strict: bool, optional :returns: Is it a bulk reaction? :rtype: bool .. py:method:: 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. :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool, optional :param include_products: Include the products. Defaults to True. :type include_products: bool, optional :param strict: Choose between all (true) or any (false) must be gas phase . Defaults to True. :type strict: bool, optional :returns: Is it a gas phase reaction? :rtype: bool .. py:method:: 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 :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool, optional :param include_products: Include the products. Defaults to True. :type include_products: bool, optional :param strict: Choose between all (true) or any (false) must be ice phase . Defaults to True. :type strict: bool, optional :returns: Is it an ice phase reaction? :rtype: bool .. py:method:: 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 :param include_reactants: Include the reactants. Defaults to True. :type include_reactants: bool, optional :param include_products: Include the products. Defaults to True. :type include_products: bool, optional :param strict: Choose between all (true) or any (false) must be on the surface . Defaults to False. :type strict: bool, optional :returns: Is it a surface reaction? :rtype: bool .. py:method:: 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. .. py:method:: set_alpha(alpha: float) -> None Set the alpha parameter from the Kooij-Arrhenius equation :param alpha: the alpha parameter of the reaction :type alpha: float .. py:method:: set_beta(beta: float) -> None Set the beta parameter from the Kooij-Arrhenius equation :param beta: the beta parameter of the reaction :type beta: float .. py:method:: set_extrapolation(flag: bool) -> None .. py:method:: set_gamma(gamma: float) -> None Set the gamma parameter from the Kooij-Arrhenius equation :param gamma: the gamma parameter of the reaction :type gamma: float .. py:method:: set_products(products: list[str]) -> None Set the four products present in the reaction, padded with NAN for nonexistent :param products: The four products names :type products: list[str] .. py:method:: set_reactants(reactants: list[str]) -> None Set the four reactants present in the reaction, padded with NAN for nonexistent :param reactants: The four reactants names :type reactants: list[str] .. py:method:: set_reduced_mass(reduced_mass: float) -> None Set the reduced mass to be used to calculate tunneling rate in AMU :param reduced_mass: reduced mass of moving atoms :type reduced_mass: float .. py:method:: set_source(source: str) -> None Set the source of the reaction :param source: The source of the reaction :type source: str .. py:method:: set_temphigh(temphigh: float) -> None Set the higher temperature boundary of the reaction in Kelvin :param templow: the higher temperature boundary :type templow: float .. py:method:: set_templow(templow: float) -> None Set the lower temperature boundary of the reaction in Kelvin :param templow: the lower temperature boundary :type templow: float .. py:method:: to_UCL_format() Convert a reaction to UCLCHEM reaction file format .. py:attribute:: body_count :value: -1 .. py:attribute:: duplicate :value: False .. py:attribute:: source :value: None .. py:class:: 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 .. py:method:: add_default_freeze() -> None Adds a defalt freezeout, which is freezing out to the species itself, but with no ionization. .. py:method:: 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. .. 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] .. 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() -> dict[list[str], float] Obtain the product to which the species freeze out :returns: Reactions and their respective freeze out ratios. :rtype: dict[str, float] :Yields: *Iterator[dict[str, float]]* -- Iterator that returns all of the freeze out reactions with ratios .. py:method:: get_freeze_products_list() -> list[list[str]] Returns 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 :rtype: int .. py:method:: get_n_atoms() -> int Obtain 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:: is_bulk_species() -> bool Checks 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 Checks if the species is ionized, either postively or negatively. :returns: True if it is an ionized :rtype: bool .. py:method:: is_surface_species() -> bool Checks if the species is on the surface :returns: True if a surface species :rtype: bool .. 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_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 It is called alpha, since it is derived from the alpha column in the UCLCHEM reaction format: https://github.com/uclchem/UCLCHEM/blob/08d37f8c3063f8ff8a9a7aa16d9eff0ed4f99538/Makerates/src/network.py#L160 .. 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:: to_UCL_format() -> str .. py:attribute:: enthalpy .. py:attribute:: is_refractory :value: False .. py:attribute:: mass .. py:attribute:: monoFraction .. py:attribute:: n_atoms :value: 0 .. py:attribute:: name .. py:attribute:: solidFraction .. py:attribute:: volcFraction .. py:function:: 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. :param configuration_file: A UCLCHEM Makerates configuration file. Defaults to "user_settings.yaml". :type configuration_file: str, optional :param write_files: Whether to write the fortran files to the src/fortran_src. Defaults to True. :type write_files: bool, optional :raises KeyError: The configuration cannot be found :returns: A chemical network instance. :rtype: Network