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/stimestep_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 toinitialTemp
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 shockparam_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/sinitial_dens
float - Preshock density of the gas in cm
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, seeread_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 ondf
pd.DataFrame - A dataframe created byread_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 analysedresult_file
str - The path to the file containing the UCLCHEM outputoutput_file
str - The path to the file where the analysis output will be writtenrate_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 elementdf
pandas.DataFrame - DataFrame fromread_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 fromread_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.