uclchem.analysis ================ .. py:module:: uclchem.analysis .. autoapi-nested-parse:: UCLCHEM Analysis Module. Tools for analyzing chemical model outputs and reaction pathways. This module provides functions to: - Read and parse UCLCHEM output files - Analyze chemical reaction pathways for specific species - Check element conservation in model results - Create abundance plots and visualizations - Compare model results across different runs **Key Functions:** - :func:`read_output_file` - Read UCLCHEM output files into DataFrames - :func:`analysis` - Analyze production/destruction pathways for a species - :func:`check_element_conservation` - Verify element conservation **Example Usage:** .. code-block:: python import uclchem.analysis as analysis # Read model output df = analysis.read_output_file("output.dat") # Analyze CO chemistry analysis.analysis( "CO", "output.dat", "co_reactions.dat" ) # Check conservation conservation = analysis.check_element_conservation( df, ["C", "O", "N"] ) **See Also:** - :mod:`uclchem.plot` - Dedicated plotting utilities - :mod:`uclchem.model` - Run chemical models Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: uclchem.analysis.analysis uclchem.analysis.analyze_element_per_phase uclchem.analysis.check_element_conservation uclchem.analysis.compute_heating_per_reaction uclchem.analysis.construct_incidence uclchem.analysis.derive_phase_from_name uclchem.analysis.get_change_df uclchem.analysis.get_production_and_destruction uclchem.analysis.get_total_swap uclchem.analysis.rate_constants_to_dy_and_rates uclchem.analysis.read_analysis uclchem.analysis.read_output_file uclchem.analysis.read_rate_file uclchem.analysis.total_element_abundance .. py:function:: analysis(species_name: str, output_file: str | pathlib.Path, analysis_file: str | pathlib.Path, rate_threshold: float = 0.99) -> None Loop over every time step in an output file and finds the rate of change. of a species at that time due to each of the reactions it is involved in. From this, the most important reactions are identified and printed to file. This can be used to understand the chemical reason behind a species' behavior. DEPRECATED :param species_name: Name of species to be analyzed :type species_name: str :param output_file: The path to the file where the analysis output will be written :type output_file: str | Path :param analysis_file: The path to the file containing the UCLCHEM output :type analysis_file: str | Path :param rate_threshold: Analysis output will contain the only the most efficient reactions that are responsible for rate_threshold of the total production and destruction rate. Default = 0.99. :type rate_threshold: float .. py:function:: analyze_element_per_phase(element: str, df: pandas.DataFrame) -> pandas.DataFrame Calculate the total elemental abundance of a species as a function of time. within each phase (gas, surface, bulk and ion). Allows you to check conservation of elements. :param element: Name of element :type element: str :param df: DataFrame from `read_output_file()` :type df: pd.DataFrame :returns: **content** -- Total abundance of element per phase for all time steps in df. :rtype: pd.DataFrame .. py:function:: check_element_conservation(df: pandas.DataFrame, element_list: list[str] | None = None, percent: bool = True) -> dict[str, str] Check the conservation of elements by comparing their total. abundance at start and end of model. :param df: UCLCHEM output in format from `read_output_file` :type df: pd.DataFrame :param element_list: List of elements to check. If None, defaults to `uclchem.constants.default_elements_to_check`. :type element_list: list[str] | None :param percent: Whether to return the change formatted as a percentage. Default = False. :type percent: bool :returns: Dictionary containing the change in the total abundance of each element as a fraction of initial value :rtype: dict[str, str] .. py:function:: compute_heating_per_reaction(rates: pandas.DataFrame, network: uclchem.makerates.network.Network | None = None, reactions: list[uclchem.makerates.reaction.Reaction] | None = None) -> pandas.DataFrame Compute heating/cooling per reaction by multiplying rates by exothermicity. :param rates: (time x n_reactions) of reaction rates :type rates: pd.DataFrame :param network: Network object with exothermicity data. Default = None. :type network: Network | None :param reactions: List of Reaction objects (alternative to network) Default = None. :type reactions: list[Reaction] | None :returns: (time x n_reactions) of heating rates in erg/s :rtype: pd.DataFrame :raises ValueError: If the number of reactions and rates are not the same. .. py:function:: construct_incidence(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction]) -> numpy.ndarray Construct the incidence matrix, a matrix that describes the in and out degree. for each of the reactions; useful to matrix multiply by the individual rates per reaction to obtain a rates (dy) per species. :param species: A list of S species :type species: list[Species] :param reactions: The list of R reactions :type reactions: list[Reaction] :returns: **incidence** -- An RxS incidence matrix :rtype: np.ndarray .. py:function:: derive_phase_from_name(name: str) -> str Derive the phase of the species from its name. :param name: name of the species. :type name: str :returns: Phase. One of `["gas", "surface", "bulk", "ion"]`. :rtype: str .. py:function:: get_change_df(rate_df: pandas.DataFrame, species: str, on_grain: bool = False) -> pandas.DataFrame From a dataframe containing all the reaction rates, get the change of a species over time,. due to each reaction. :param rate_df: dataframe containing physical parameters and reaction rate constants over time :type rate_df: pd.DataFrame :param species: species to get the change over time :type species: str :param on_grain: whether to analyze the ice phase of this species (Default value = False) :type on_grain: bool :returns: **change_df** -- change of species over time due to each reaction the species is involved in :rtype: pd.DataFrame :raises DeprecationWarning: Deprecated in UCLCHEM 4.0 :raises ValueError: If "#" or "@" is in `species`. .. py:function:: get_production_and_destruction(species: str, dataframe: pandas.DataFrame) -> tuple[pandas.DataFrame, pandas.DataFrame] Split the rate constants or rates into production and destruction parts for a given species. Stoichiometry is accounted for: if a species appears N times on one side of a reaction, the column is scaled by N so that summing production - destruction recovers the net dy for that species. :param species: Name of species to split rates for :type species: str :param dataframe: DataFrame of rates :type dataframe: pd.DataFrame :returns: production rates, destruction rates :rtype: tuple[pd.DataFrame, pd.DataFrame] .. py:function:: get_total_swap(rates: pandas.DataFrame, abundances: pandas.DataFrame, reactions: list[uclchem.makerates.reaction.Reaction]) -> numpy.ndarray Obtain the amount of 'random' swapping per timestep. :param rates: The rates obtained from running an UCLCHEM model :type rates: pd.DataFrame :param abundances: The abundances obtained from running an UCLCHEM model :type abundances: pd.DataFrame :param reactions: The reactions used in UCLCHEM :type reactions: list[Reaction] :returns: **totalSwap** -- The total swap per timestep :rtype: np.ndarray :raises AssertionError: If rates and abundances have different lengths, or if the number of rate columns does not match the number of reactions. .. py:function:: rate_constants_to_dy_and_rates(physics: pandas.DataFrame, abundances: pandas.DataFrame, rate_constants: pandas.DataFrame, network: uclchem.makerates.network.Network | None = None, species: list[uclchem.makerates.species.Species] | None = None, reactions: list[uclchem.makerates.reaction.Reaction] | None = None) -> tuple[pandas.DataFrame, pandas.DataFrame] Apply postprocessing to obtain the equivalent of GETYDOT from the fortran side. and the reaction rates at each timestep. :param physics: The physics output from running a model :type physics: pd.DataFrame :param abundances: The abundances output from running a model :type abundances: pd.DataFrame :param rate_constants: The rate constants output from running a model :type rate_constants: pd.DataFrame :param network: The reaction network used to postprocess the rate constants. Defaults to None. :type network: Network | None :param species: The species used to postprocess the rate constants. Defaults to None. :type species: list[Species] | None :param reactions: The reactions used to postprocess the rate constants. Defaults to None. :type reactions: list[Reaction] | None :returns: * **ydot** (*pd.DataFrame*) -- the RHS that is solved in UCLCHEM at every output timestep * **rate_by_reaction** (*pd.DataFrame*) -- the individual terms that result in ydot when multiplied by the incidence matrix. :raises ValueError: If `species` is specified, but `reactions` is not, or vice versa :raises ValueError: If `species`, `reactions` and `network` are all specified, or all not specified. :raises ValueError: If there are any reaction types not processed. :raises AssertionError: If `species` or `reactions` is ``None`` after the validation guard (should not happen; indicates a logic error). .. py:function:: read_analysis(filepath: str | pathlib.Path, species: str) -> tuple[pandas.DataFrame, list[str]] Read the analysis output. :param filepath: path to analysis output. :type filepath: str | Path :param species: Species of interest. :type species: str :returns: * **df** (*pd.DataFrame*) -- dataframe with rates and time. * **all_reactions** (*list[str]*) -- list of all reactions that the species is involved in. :raises DeprecationWarning: Deprecated in UCLCHEM 4.0 .. py:function:: read_output_file(output_file: str | pathlib.Path) -> pandas.DataFrame Read the output of a UCLCHEM run created with the outputFile parameter. into a pandas DataFrame. :param output_file: path to file containing a full UCLCHEM output :type output_file: str | Path :returns: **data** -- A dataframe containing the abundances and physical parameters of the model at every time step. :rtype: pd.DataFrame .. py:function:: read_rate_file(rate_file: str | pathlib.Path) -> pandas.DataFrame Read the output of a UCLCHEM run created with the rateConstantFile. parameter into a pandas DataFrame. :param rate_file: path to file containing the UCLCHEM reaction rates. :type rate_file: str | Path :returns: **data** -- A dataframe containing the physical parameters, and reaction rates (s-1) at each timestep. :rtype: pd.DataFrame .. py:function:: total_element_abundance(element: str, df: pandas.DataFrame) -> pandas.Series Calculate the total elemental abundance of a species as a function of time. Allows you to check conservation. :param element: Name of element :type element: str :param df: DataFrame from `read_output_file()` :type df: pd.DataFrame :returns: Total abundance of element for all time steps in df. :rtype: pd.Series