uclchem.analysis#

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:

read_output_file() - Read UCLCHEM output files into DataFrames
analysis() - Analyze production/destruction pathways for a species
check_element_conservation() - Verify element conservation

Example Usage:

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:

uclchem.plot - Dedicated plotting utilities
uclchem.model - Run chemical models

Module Contents#

Functions#

`analysis`(→ None)	Loop over every time step in an output file and finds the rate of change.
`analyze_element_per_phase`(→ pandas.DataFrame)	Calculate the total elemental abundance of a species as a function of time.
`check_element_conservation`(→ dict[str, str])	Check the conservation of elements by comparing their total.
`compute_heating_per_reaction`(→ pandas.DataFrame)	Compute heating/cooling per reaction by multiplying rates by exothermicity.
`construct_incidence`(→ numpy.ndarray)	Construct the incidence matrix, a matrix that describes the in and out degree.
`derive_phase_from_name`(→ str)	Derive the phase of the species from its name.
`get_change_df`(→ pandas.DataFrame)	From a dataframe containing all the reaction rates, get the change of a species over time,.
`get_production_and_destruction`(...)	Split the rate constants or rates into production and destruction parts for a given species.
`get_total_swap`(→ numpy.ndarray)	Obtain the amount of 'random' swapping per timestep.
`rate_constants_to_dy_and_rates`(...)	Apply postprocessing to obtain the equivalent of GETYDOT from the fortran side.
`read_analysis`(→ tuple[pandas.DataFrame, list[str]])	Read the analysis output.
`read_output_file`(→ pandas.DataFrame)	Read the output of a UCLCHEM run created with the outputFile parameter.
`read_rate_file`(→ pandas.DataFrame)	Read the output of a UCLCHEM run created with the rateConstantFile.
`total_element_abundance`(→ pandas.Series)	Calculate the total elemental abundance of a species as a function of time.

uclchem.analysis.analysis(species_name: str, output_file: str | pathlib.Path, analysis_file: str | pathlib.Path, rate_threshold: float = 0.99) → None[source]#

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

Parameters:

species_name (str) – Name of species to be analyzed
output_file (str | Path) – The path to the file where the analysis output will be written
analysis_file (str | Path) – The path to the file containing the UCLCHEM output
rate_threshold (float) – 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.

uclchem.analysis.analyze_element_per_phase(element: str, df: pandas.DataFrame) → pandas.DataFrame[source]#

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.

Parameters:

element (str) – Name of element
df (pd.DataFrame) – DataFrame from read_output_file()

Returns:

content – Total abundance of element per phase for all time steps in df.

Return type:

pd.DataFrame

uclchem.analysis.check_element_conservation(df: pandas.DataFrame, element_list: list[str] | None = None, percent: bool = True) → dict[str, str][source]#

Check the conservation of elements by comparing their total.

abundance at start and end of model.

Parameters:

df (pd.DataFrame) – UCLCHEM output in format from read_output_file
element_list (list[str] | None) – List of elements to check. If None, defaults to uclchem.constants.default_elements_to_check.
percent (bool) – Whether to return the change formatted as a percentage. Default = False.

Returns:

Dictionary containing the change in the total abundance of each element as a fraction of initial value

Return type:

dict[str, str]

uclchem.analysis.compute_heating_per_reaction(rates: pandas.DataFrame, network: uclchem.makerates.network.Network | None = None, reactions: list[uclchem.makerates.reaction.Reaction] | None = None) → pandas.DataFrame[source]#

Compute heating/cooling per reaction by multiplying rates by exothermicity.

Parameters:

rates (pd.DataFrame) – (time x n_reactions) of reaction rates
network (Network | None) – Network object with exothermicity data. Default = None.
reactions (list[Reaction] | None) – List of Reaction objects (alternative to network) Default = None.

Returns:

(time x n_reactions) of heating rates in erg/s

Return type:

pd.DataFrame

Raises:

ValueError – If the number of reactions and rates are not the same.

uclchem.analysis.construct_incidence(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction]) → numpy.ndarray[source]#

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.

Parameters:

species (list[Species]) – A list of S species
reactions (list[Reaction]) – The list of R reactions

Returns:

incidence – An RxS incidence matrix

Return type:

np.ndarray

uclchem.analysis.derive_phase_from_name(name: str) → str[source]#

Derive the phase of the species from its name.

Parameters:: name (str) – name of the species.
Returns:: Phase. One of [“gas”, “surface”, “bulk”, “ion”].
Return type:: str

uclchem.analysis.get_change_df(rate_df: pandas.DataFrame, species: str, on_grain: bool = False) → pandas.DataFrame[source]#

From a dataframe containing all the reaction rates, get the change of a species over time,.

due to each reaction.

Parameters:

rate_df (pd.DataFrame) – dataframe containing physical parameters and reaction rate constants over time
species (str) – species to get the change over time
on_grain (bool) – whether to analyze the ice phase of this species (Default value = False)

Returns:

change_df – change of species over time due to each reaction the species is involved in

Return type:

pd.DataFrame

Raises:

DeprecationWarning – Deprecated in UCLCHEM 4.0
ValueError – If “#” or “@” is in species.

uclchem.analysis.get_production_and_destruction(species: str, dataframe: pandas.DataFrame) → tuple[pandas.DataFrame, pandas.DataFrame][source]#

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.

Parameters:

species (str) – Name of species to split rates for
dataframe (pd.DataFrame) – DataFrame of rates

Returns:

production rates, destruction rates

Return type:

tuple[pd.DataFrame, pd.DataFrame]

uclchem.analysis.get_total_swap(rates: pandas.DataFrame, abundances: pandas.DataFrame, reactions: list[uclchem.makerates.reaction.Reaction]) → numpy.ndarray[source]#

Obtain the amount of ‘random’ swapping per timestep.

Parameters:

rates (pd.DataFrame) – The rates obtained from running an UCLCHEM model
abundances (pd.DataFrame) – The abundances obtained from running an UCLCHEM model
reactions (list[Reaction]) – The reactions used in UCLCHEM

Returns:

totalSwap – The total swap per timestep

Return type:

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.

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

Apply postprocessing to obtain the equivalent of GETYDOT from the fortran side.

and the reaction rates at each timestep.

Parameters:

physics (pd.DataFrame) – The physics output from running a model
abundances (pd.DataFrame) – The abundances output from running a model
rate_constants (pd.DataFrame) – The rate constants output from running a model
network (Network | None) – The reaction network used to postprocess the rate constants. Defaults to None.
species (list[Species] | None) – The species used to postprocess the rate constants. Defaults to None.
reactions (list[Reaction] | None) – The reactions used to postprocess the rate constants. Defaults to 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
ValueError – If species, reactions and network are all specified, or all not specified.
ValueError – If there are any reaction types not processed.
AssertionError – If species or reactions is None after the validation guard (should not happen; indicates a logic error).

uclchem.analysis.read_analysis(filepath: str | pathlib.Path, species: str) → tuple[pandas.DataFrame, list[str]][source]#

Read the analysis output.

Parameters:

filepath (str | Path) – path to analysis output.
species (str) – Species of interest.

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

uclchem.analysis.read_output_file(output_file: str | pathlib.Path) → pandas.DataFrame[source]#

Read the output of a UCLCHEM run created with the outputFile parameter.

into a pandas DataFrame.

Parameters:: output_file (str | Path) – path to file containing a full UCLCHEM output
Returns:: data – A dataframe containing the abundances and physical parameters of the model at every time step.
Return type:: pd.DataFrame

uclchem.analysis.read_rate_file(rate_file: str | pathlib.Path) → pandas.DataFrame[source]#

Read the output of a UCLCHEM run created with the rateConstantFile.

parameter into a pandas DataFrame.

Parameters:: rate_file (str | Path) – path to file containing the UCLCHEM reaction rates.
Returns:: data – A dataframe containing the physical parameters, and reaction rates (s-1) at each timestep.
Return type:: pd.DataFrame

uclchem.analysis.total_element_abundance(element: str, df: pandas.DataFrame) → pandas.Series[source]#

Calculate the total elemental abundance of a species as a function of time.

Allows you to check conservation.

Parameters:

element (str) – Name of element
df (pd.DataFrame) – DataFrame from read_output_file()

Returns:

Total abundance of element for all time steps in df.

Return type:

pd.Series