Skip to main content
Version: v3.1.0

Python API

uclchem

The UCLCHEM python module is divided into three parts. model contains the functions for running chemical models under different physics. analysis contains functions for reading and plotting output files as well as investigating the chemistry. tests contains functions for testing the code.

uclchem.model

cloud​

def cloud(param_dict=None, out_species=None)

Run cloud model from UCLCHEM

Arguments:

  • param_dict dict,optional - A dictionary of parameters where keys are any of the variables in defaultparameters.f90 and values are value for current run.
  • out_species list, optional - A list of species for which final abundance will be returned. If None, no abundances will be returned.. Defaults to None.

Returns:

A list where the first element is always an integer which is negative if the model failed to run and can be sent to uclchem.utils.check_error() to see more details. If the out_species parametere is provided, the remaining elements of this list will be the final abundances of the species in out_species.

collapse​

def collapse(collapse, physics_output, param_dict=None, out_species=None)

Run collapse model from UCLCHEM based on Priestley et al 2018 AJ 156 51 (https://ui.adsabs.harvard.edu/abs/2018AJ....156...51P/abstract)

Arguments:

  • collapse str - A string containing the collapse type, options are 'BE1.1', 'BE4', 'filament', or 'ambipolar'
  • physics_output(str) - Filename to store physics output, only relevant for 'filament' and 'ambipolar' collapses. If None, no physics output will be saved.
  • param_dict dict,optional - A dictionary of parameters where keys are any of the variables in defaultparameters.f90 and values are value for current run.
  • out_species list, optional - A list of species for which final abundance will be returned. If None, no abundances will be returned.. Defaults to None.

Returns:

A list where the first element is always an integer which is negative if the model failed to run and can be sent to uclchem.utils.check_error() to see more details. If the out_species parametere is provided, the remaining elements of this list will be the final abundances of the species in out_species.

hot_core​

def hot_core(temp_indx, max_temperature, param_dict=None, out_species=None)

Run hot core model from UCLCHEM, based on Viti et al. 2004 and Collings et al. 2004

Arguments:

  • temp_indx int - Used to select the mass of hot core. 1=1Msun,2=5, 3=10, 4=15, 5=25,6=60]
  • max_temperature float - Value at which gas temperature will stop increasing.
  • param_dict dict,optional - A dictionary of parameters where keys are any of the variables in defaultparameters.f90 and values are value for current run.
  • out_species list, optional - A list of species for which final abundance will be returned. If None, no abundances will be returned.. Defaults to None.

Returns:

A list where the first element is always an integer which is negative if the model failed to run and can be sent to uclchem.utils.check_error() to see more details. If the out_species parametere is provided, the remaining elements of this list will be the final abundances of the species in out_species.

cshock​

def cshock(shock_vel, timestep_factor=0.01, minimum_temperature=0.0, param_dict=None, out_species=None)

Run C-type shock model from UCLCHEM

Arguments:

  • shock_vel float - Velocity of the shock in km/s
  • timestep_factor float, optional - Whilst the time is less than 2 times the dissipation time of shock, timestep is timestep_factor*dissipation time. Essentially controls how well resolved the shock is in your model. Defaults to 0.01.
  • minimum_temperature float, optional - Minimum post-shock temperature. Defaults to 0.0 (no minimum). The shocked gas typically cools to initialTemp if this is not set.
  • param_dict dict,optional - A dictionary of parameters where keys are any of the variables in defaultparameters.f90 and values are value for current run.
  • out_species list, optional - A list of species for which final abundance will be returned. If None, no abundances will be returned.. Defaults to None.

Returns:

A list where the first element is always an integer which is negative if the model failed to run and can be sent to uclchem.utils.check_error() to see more details. If the model succeeded, the second element is the dissipation time and further elements are the abundances of all species in out_species.

jshock​

def jshock(shock_vel, param_dict=None, out_species=None)

Run J-type shock model from UCLCHEM

Arguments:

  • shock_vel float - Velocity of the shock
  • param_dict dict,optional - A dictionary of parameters where keys are any of the variables in defaultparameters.f90 and values are value for current run.
  • out_species list, optional - A list of species for which final abundance will be returned. If None, no abundances will be returned.. Defaults to None.

Returns:

A list where the first element is always an integer which is negative if the model failed to run and can be sent to uclchem.utils.check_error() to see more details. If the model succeeded, the second element is the dissipation time and further elements are the abundances of all species in out_species.

uclchem.utils

cshock_dissipation_time​

def cshock_dissipation_time(shock_vel, initial_dens)

A simple function used to calculate the dissipation time of a C-type shock. Use to obtain a useful timescale for your C-shock model runs. Velocity of ions and neutrals equalizes at dissipation time and full cooling takes a few dissipation times.

Arguments:

  • shock_vel float - Velocity of the shock in km/s
  • initial_dens float - Preshock density of the gas in cmβˆ’3^{-3}

Returns:

  • float - The dissipation time of the shock in years

check_error​

def check_error(error_code)

Converts the UCLCHEM integer result flag to a simple messaging explaining what went wrong"

Arguments:

  • error_code int - Error code returned by UCLCHEM models, the first element of the results list.

Returns:

  • str - Error message

get_species_table​

def get_species_table()

A simple function to load the list of species in the UCLCHEM network into a pandas dataframe.

Returns:

  • pandas.DataFrame - A dataframe containing the species names and their details

get_reaction_table​

def get_reaction_table()

A function to load the reaction table from the UCLCHEM network into a pandas dataframe.

Returns:

  • pandas.DataFrame - A dataframe containing the reactions and their rates

uclchem.analysis

read_output_file​

def read_output_file(output_file)

Read the output of a UCLCHEM run created with the outputFile parameter into a pandas DataFrame

Arguments:

  • output_file str - path to file containing a full UCLCHEM output

Returns:

  • pandas.DataFrame - A dataframe containing the abundances and physical parameters of the model at every time step.

create_abundance_plot​

def create_abundance_plot(df, species, figsize=(16, 9), plot_file=None)

Create a plot of the abundance of a list of species through time.

Arguments:

  • 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:

  • fig,ax - matplotlib figure and axis objects

plot_species​

def plot_species(ax, df, species)

Plot the abundance of a list of species through time directly onto an axis.

Arguments:

  • 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:

  • pyplot.axis - Modified input axis is returned

analysis​

def analysis(species_name, result_file, output_file, rate_threshold=0.99)

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.

Arguments:

  • 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.

total_element_abundance​

def total_element_abundance(element, df)

Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation.

Arguments:

  • element str - Name of element
  • df pandas.DataFrame - DataFrame from read_output_file()

Returns:

  • pandas.Series - Total abundance of element for all time steps in df.

check_element_conservation​

def check_element_conservation(df, element_list=["H", "N", "C", "O"])

Check the conservation of major element by comparing total abundance at start and end of model

Arguments:

  • 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:

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

uclchem.tests

test_ode_conservation​

def test_ode_conservation(element_list=["H", "N", "C", "O"])

Test whether the ODEs conserve elements. Useful to run each time you change network. Integrator errors may still cause elements not to be conserved but they cannot be conserved if the ODEs are not correct.

Arguments:

  • element_list list, optional - A list of elements for which to check the conservation. Defaults to ["H", "N", "C", "O"].

Returns:

  • dict - A dictionary of the elements in element list with values representing the total rate of change of each element.