uclchem.analysis#
Module Contents#
Functions#
|
A function which loops 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. |
|
Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation. |
|
Check the conservation of major element by comparing total abundance at start and end of model |
|
Construct the incidence matrix, a matrix that describes the in and out degree |
|
Create a plot of the abundance of a list of species through time. |
|
|
|
From a dataframe containing all the reaction rates, get the change of a species over time, due to each reaction. |
|
|
|
Obtain the amount of 'random' swapping per timestep |
|
Plot the abundance of a list of species through time directly onto an axis. |
|
Apply postprocessing to obtain the equivalent of GETYDOT from the fortran |
|
|
|
Read the output of a UCLCHEM run created with the outputFile parameter into a pandas DataFrame |
|
Read the output of a UCLCHEM run created with the rateFile parameter into a pandas DataFrame |
|
Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation. |
Attributes#
- uclchem.analysis.analysis(species_name, rates, output_file, rate_threshold=0.99)[source]#
A function which loops 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’ behaviour.
- Parameters:
species_name (str) – Name of species to be analysed
result_file (str) – The path to the file containing the UCLCHEM output
output_file (str) – The path to the file where the analysis output will be written
rate_threshold (float,optional) – Analysis output will contain the only the most efficient reactions that are responsible for rate_threshold of the total production and destruction rate. Defaults to 0.99.
- uclchem.analysis.analyze_element_per_phase(element, df)[source]#
Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation.
- Parameters:
element (str) – Name of element
df (pandas.DataFrame) – DataFrame from read_output_file()
- Returns:
Total abundance of element for all time steps in df.
- Return type:
- uclchem.analysis.check_element_conservation(df, element_list=['H', 'N', 'C', 'O'], percent=True)[source]#
Check the conservation of major element by comparing total abundance at start and end of model
- Parameters:
df (pandas.DataFrame) – UCLCHEM output in format from read_output_file
element_list (list, optional) – List of elements to check. Defaults to [“H”, “N”, “C”, “O”].
- Returns:
Dictionary containing the change in the total abundance of each element as a fraction of initial value
- Return type:
- uclchem.analysis.construct_incidence(species: List[uclchem.makerates.species.Species], reactions: List[uclchem.makerates.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 indvidual fluxes per reaction to obtain a flux (dy) per species.
- uclchem.analysis.create_abundance_plot(df, species, figsize=(16, 9), plot_file=None)[source]#
Create a plot of the abundance of a list of species through time.
- Parameters:
df (pd.DataFrame) – Pandas dataframe containing the UCLCHEM output, see read_output_file
species (list) – list of strings containing species names. Using a $ instead of # or @ will plot the sum of surface and bulk abundances.
figsize (tuple, optional) – Size of figure, width by height in inches. Defaults to (16, 9).
plot_file (str, optional) – Path to file where figure will be saved. If None, figure is not saved. Defaults to None.
- Returns:
matplotlib figure and axis objects
- Return type:
fig,ax
- 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:
- Returns:
change of species over time due to each reaction the species is involved in
- Return type:
change_df (pd.DataFrame)
- uclchem.analysis.get_production_and_destruction(species: str, rates_or_flux: pandas.DataFrame)[source]#
- uclchem.analysis.get_total_swap(rates: pandas.DataFrame, abundances: pandas.DataFrame, reactions: List[uclchem.makerates.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:
The total swap per timestep
- Return type:
np.ndarray
- uclchem.analysis.plot_species(ax, df, species, legend=True, **plot_kwargs)[source]#
Plot the abundance of a list of species through time directly onto an axis.
- Parameters:
ax (pyplot.axis) – An axis object to plot on
df (pd.DataFrame) – A dataframe created by read_output_file
species (str) – A list of species names to be plotted. If species name starts with “$” instead of # or @, plots the sum of surface and bulk abundances
- Returns:
Modified input axis is returned
- Return type:
pyplot.axis
- uclchem.analysis.rates_to_dy_and_flux(physics: pandas.DataFrame, abundances: pandas.DataFrame, rates: pandas.DataFrame, network: uclchem.makerates.network.Network = None, species: list[uclchem.makerates.species.Species] = None, reactions: list[uclchem.makerates.Reaction] = None) tuple[pandas.DataFrame, pandas.DataFrame][source]#
Apply postprocessing to obtain the equivalent of GETYDOT from the fortran side; It returns two dataframes:
ydot: the RHS that is solved in UCLCHEM at every output timestep
flux_by_reaction: the individual terms that result in ydot when multiplied by the incidence matrix
- Parameters:
physics (pd.DataFrame) – The physics output from running a model
abundances (pd.DataFrame) – The abundances output from running a model
rates (pd.DataFrame) – The rates output from running a model
network (Network, optional) – The reaction network used to postprocess the rates. Defaults to None.
species (list[Species], optional) – The species used to postprocess the rates . Defaults to None.
reactions (list[Reaction], optional) – The reactions used to postprocess the rates. Defaults to None.
- Returns:
dy, flux_by_reaction.
- Return type:
tuple[pd.DataFrame, pd.DataFrame]
- uclchem.analysis.read_output_file(output_file)[source]#
Read the output of a UCLCHEM run created with the outputFile parameter into a pandas DataFrame
- Parameters:
output_file (str) – path to file containing a full UCLCHEM output
- Returns:
A dataframe containing the abundances and physical parameters of the model at every time step.
- Return type:
- uclchem.analysis.read_rate_file(rate_file)[source]#
Read the output of a UCLCHEM run created with the rateFile parameter into a pandas DataFrame
- Parameters:
rate_file (str) – path to file containing the UCLCHEM reaction rates.
- Returns:
A dataframe containing the physical parameters, and reaction rates (s-1) at each timestep.
- Return type:
- uclchem.analysis.total_element_abundance(element, df)[source]#
Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation.
- Parameters:
element (str) – Name of element
df (pandas.DataFrame) – DataFrame from read_output_file()
- Returns:
Total abundance of element for all time steps in df.
- Return type: