Docstrings for ligpy modules

Included below are the docstrings for most of the modules and functions included in ligpy. Three modules are not included here but are well documented in the source code:

1. generate_bash_script : this is a customized module for my hardware and software environment at the University of Washington. Future users will need to modify this to suit their own systems.

2. ligpy.py : this module coordinates the solving of the kinetic model by interacting with all the other modules in the program, but does not contain any functions of its own to document.

3. revisions_to_faravelli.py : this module was included just for reference, it shows the changes we made from the kinetic scheme that we modified to develop our scheme, but it should not need to be used in the future.

analysis_tools.py

Tools used by the explore_ligpy_results.ipynb notebook that help with analysis and plotting.

analysis_tools.C_fun_gen(fractions, speciesindices, y, time)

Calculate the distribution of carbon functional groups as a percent of total carbon.

Parameters:

• fractions (list) – The lumped phases that you want to include (as specified in MW[‘species’][1], options are any subset of [‘g’,’s’,’lt’,’t’,’char’,’H20’,’CO’,’CO2’] or [‘initial’] for the case when you want to determine the initial distribution before pyrolysis)
• speciesindices (dict) – dictionary from load_results() where species names are keys and values are the index in y that corresponds to that species
• y (numpy array) – a matrix with the concentrations of each species in the kinetic scheme for every time in t (mol/L)
• time (int) – the index of the timepoint that you want the results for

Returns:

C_fun – the distribution of carbon functional groups as a percent of total carbon. The order of the elements in the array is: carbonyl, aromatic C-O, aromatic C-C, aromatic C-H, aliphatic C-O, aromatic methoxyl, aliphatic C-C

Return type:

numpy array

analysis_tools.generate_report(speciesindices, specieslist, y, m, t, which_result)

Print a descriptive summary of a specific simulation.

Parameters:

• speciesindices (dict) – dictionary from load_results() where species names are keys and values are the index in y that corresponds to that species
• specieslist (list) – the specieslist_ddasac object from load_results()
• y (numpy array) – a matrix with the concentrations of each species in the kinetic scheme for every time in t (mol/L)
• m (numpy array) – a matrix with the mass fraction of each species in the kinetic scheme for every time in t
• t (numpy array) – array with all the times (s) corresponding to entries in y and T
• which_result (str) – the name of the simulation folder you are analysing

Returns:

t_index – the index of t where this analysis was performed

Return type:

int

analysis_tools.load_results(path)

Load the results from the ODE solver, along with the program parameters used to generate those results. The program parameters should be saved in the prog_params.pkl file generated by ligpy.py. The model species concentration results should be in the same format as those output by DDASAC (see the ligpy/sample_files/ folder for an example).

Parameters:path (str) – path to the folder that contains /results_dir/, where the *.out files (model results) and prog_params.pkl are saved. Returns:

• end_time (float) – the pyrolysis end time in seconds (excludes cool-down time)
• output_time_step (float) – the time step at which results were saved (sec)
• initial_T (float) – initial temperature (K)
• heating_rate (float) – the heating rate (K/min)
• max_T (float) – maximum temperature of pyrolysis (K)
• atol (float) – absolute tolerance used by the ODE solver
• rtol (float) – relative tolerance used by the ODE solver
• plant (str) – the name of the lignin species modeled
• cool_time (int) – the time (s) to cool down after an isothermal hold
• y (numpy matrix) – a matrix with the concentrations of each species in the kinetic scheme for every time in t (mol/L)
• t (numpy array) – array with all the times (s) corresponding to entries in y and T
• T (numpy array) – array with the temperature (K) at every time in t
• specieslist (list) – a list of all the species participating in the model
• speciesindices (dict) – dictionary where species names are keys and values are the index in y that corresponds to that species
• indices_to_species (dict) – the opposite of speciesindices

analysis_tools.lump_species(speciesindices, m)

Lump the molecular species in the model into subsets of solids, tars, and gases. Also separate heavy tars into phenolic and syringol families.

Parameters:

• speciesindices (dict) – dictionary from load_results() where species names are keys and values are the index in y that corresponds to that species
• m (numpy array) – a matrix with the mass fraction of each species in the kinetic scheme for every time in t

Returns:

• lumped (numpy array) – each row in this array is the mass fraction of a lumped phase (0 = solid, 1 = heavy tar, 2 = light tar, 3 = gas, 4 = CO, 5 = CO2, 6 = H2O, 7 = char)
• phenolic_families (numpy array) – Splits the heavy tar components into the phenol family (first row) and syringol family (second row)
• morelumped (numpy array) – a “more lumped” version of lumped where column 0 = solids, 1 = tars, 2 = gases

analysis_tools.read_results_files(filename, specieslist_ddasac)

Read and process the DDASAC *.out results files so they can be combined.

Parameters:

• filename (str) – the filename of the *.out file (including relative or absolute path)
• specieslist_ddasac (list) – the specieslist_ddasac object from load_results()

Returns:

• t (numpy array) – an array with the output time (s) for each entry in the concentration or temperature arrays
• y (numpy matrix) – a matrix with the concentrations of each species in the model for every timepoint in t (mol/L)
• T (numpy array) – an array with the temperature at evey timepoint in `

analysis_tools.tar_elem_analysis(speciesindices, y, t, t_choice='end')

Calculate the elemental analysis of the tar fraction at a specified time (moles of C, H, O). The species that make up the tar fraction are specified in the MW dictionary (in constants.py). This function also returns the wt% and mol% of C, H, O at that specified time.

Parameters:

• speciesindices (dict) – dictionary from load_results() where species names are keys and values are the index in y that corresponds to that species
• y (numpy array) – a matrix with the concentrations of each species in the kinetic scheme for every time in t (mol/L)
• t (numpy array) – array with all the times (s) corresponding to entries in y and T
• t_choice (str or int, optional) – if ‘end’ (default) then this elemental analysis will be done at the last timepoint saved in the simulation (i.e. after any isothermal or cool-down stage). Otherwise, an integer specifying the index of the t array can be passed to do the analysis at a specified time.

Returns:

• ea0 (numpy array) – the elemental analysis at time = 0
• ea (numpy array) – the elemental analysis of tars at the specified time
• ea0_molpercent (numpy array) – the mole% of C, H, O at time = 0
• ea_molpercent (numpy array) – the mole% of C, H, O at the specified time
• ea0_wtpercent (numpy array) – the wt% of C, H, O at time = 0
• ea_wtpercent (numpy array) – the wt% of C, H, O at the specified time
• choice (str) – a string describing the time that was chosen for analysis
• t_index (int) – the index of the time array at which analysis was done

constants.py

Named constants, or objects with values that are constant, used by other modules.

ddasac_utils.py

Functions that setup and run the modified DDASAC solver. This is the ODE solver used by the Pfaendtner group to solve this model - users from other institutions may need to configure their own solvers (or use ODE solvers in python, for example from scipy.integrate). All the paths and files referenced in this module are specific to what is on cmole (a computer at the University of Washington).

ddasac_utils.run_ddasac(reactionlist, kmatrix, working_dir, y0, specieslist, atol, rtol, T0, h, t_end, max_T, t_step, cool_time)

Run the DDASAC ODE solver on the model. Output from the solver is saved in the working directory.

Parameters:

• reactionlist (str) – path to the file complete_reactionlist.dat
• kmatrix (lst) – a list of lists that defines a matrix. Each entry in the list is A, n, E for a given reaction
• working_dir (str) – relative path to your working directory (where to save this file)
• y0 (numpy array) – an array of the initial concentrations of each species
• specieslist (lst) – a list of all the species in the kinetic scheme
• atol (float) – the absolute tolerance of the solver
• rtol (float) – the relative tolerance of the solver
• T0 (float) – initial temperature in degrees Kelvin
• h (float) – heating rate in K/min
• t_end (float) – the end time of the simulation in seconds
• max_T (float) – maximum temperature in degrees Kelvin
• t_step (float) – the output time step that you would like to save results at in seconds

Returns:

Return type:

None

ddasac_utils.write_ddasac_format_rxns(reactions_list, kmatrix, working_directory)

This function writes the reactions in a format appropriate to pass to our modified DDASAC solver. Reactions are written to a file in the working directory named ddasac_format_reactions.dat.

Parameters:

• reactions_list (str) – path to the file reactionlist.dat
• kmatrix (list) – the output of ligpy_utils.build_k_matrix()
• working_directory (str) – relative path to your working directory (where to save this file)

Returns:

Return type:

None

ddasac_utils.write_ddat(y0, specieslist, num_reactions, num_net_reactions, atol, rtol, T0, h, t_end, max_T, t_step, working_dir)

This function writes the ddat.in file to use with our modified DDASAC solver. The file is saved in the working directory specified.

Parameters:

• y0 (numpy array) – an array of the initial concentrations of each species
• specieslist (lst) – a list of all the species in the kinetic scheme
• num_reactions (int) – the number of reactions in the kinetic scheme
• num_net_reactions (int) – the number of net reactions in the kinetic scheme
• atol (float) – the absolute tolerance of the solver
• rtol (float) – the relative tolerance of the solver
• T0 (float) – initial temperature in degrees Kelvin
• h (float) – heating rate in K/min
• t_end (float) – the end time of the simulation in seconds
• max_T (float) – maximum temperature in degrees Kelvin
• t_step (float) – the output time step that you would like to save results at in seconds
• working_dir (str) – relative path to your working directory (where to save this file)

Returns:

Return type:

None

equivalent_compositions.py

Functions related to calculating and saving the equivalent composition of lignins (in terms of mole fractions of LIGC, LIGH, LIGO) from their elemental compositions (available experimentally).

equivalent_compositions.get_equiv_comp(species, datadir, filewrite=True)

Takes the name of a species of lignin and calculates the equivalent composition (mole fractions of LIGC, LIGH, LIGO) based on the elemental analysis of that lignin species. Equivalent composition is determined based on a linear relationship assuming conservation of mass.

Parameters:

• species (str) – a string corresponding to a species name in the file elementalanalysis.dat
• datadir (str) – absolute path to the data directory where compositionlist.dat should be saved
• filewrite (bool, optional) – a boolean indicating whether this function is being called in order to write the equivalent compositions to a file (=True). If False, information on the equivalent composition conversion is printed in addition to being returned by the function

Returns:

• LIGC (float) – the mole fraction of LIGC
• LIGH (float) – the mole fraction of LIGH
• LIGO (float) – the mole fraction of LIGO

equivalent_compositions.get_species_list(datadir)

Function that returns a list of all the species of lignin that have elemental analyses defined in the file elementalanalysis.dat.

Parameters:datadir (str) – absolute path to the data directory where compositionlist should be saved Returns:species – list of strings for all the species in elementalanalysis.dat Return type:list

equivalent_compositions.write_compositionlist(datadir)

Write (or overwrite) a file, compositionlist.dat, that contains the equivalent compositions (mole fractions of LIGC, LIGH, LIGO) of all the lignin species defined in elementalanalysis.dat.

When calculating equivalent compositions it is possible to generate a negative composition for one of the three components. This occurs when the elemental analysis is outside of the range that it is possible to approximate with the three model components. This function will print warnings to the user when this occurs, and will automatically set the negative value to zero and distribute the difference among the other two components. If the negative value is small, this approach is acceptable; if it is too large then you cannot approximate the offending lignin species with this model and you should manually delete the entry from your elementalanalysis.dat file and re-run this function.

Parameters:datadir (str) – absolute path to the data directory where compositionlist should be saved Returns: Return type:None

ligpy_utils.py

Misc utility functions required by several modules in the ligpy program.

ligpy_utils.build_dydt_list(rates_list, specieslist, species_rxns, human='no')

This function returns the list of dydt expressions generated for all the reactions from rates_list.

Parameters:

• rates_list (list) – the output of build_rates_list()
• specieslist (list) – a list of all the species in the kinetic scheme
• species_rxns (dict) – dictionary where keys that are the model species and values are the reactions they are involved in
• human (str, optional) – indicate whether the output of this function should be formatted for a human to read (‘yes’). Default is ‘no’

Returns:

dydt_expressions – expressions for the ODEs expressing the concentration of each species with time

Return type:

list

ligpy_utils.build_k_matrix(rateconsts)

Build a matrix of all the rate constant parameters (A, n, E).

Parameters:rateconsts (str) – the path to the file complete_rateconstant_list.dat Returns:kmatrix – a list of lists that defines a matrix. Each entry in the list is A, n, E for a given reaction Return type:list

ligpy_utils.build_rates_list(rateconstlist, reactionlist, speciesindices, indices_to_species, human='no')

This function writes the list of rate expressions for each reaction.

Parameters:

• rateconstlist (str) – the path to the file complete_rateconstant_list.dat
• reactionlist (str) – the path to the file complete_reaction_list.dat
• speciesindices (dict) – a dictionary of arbitrary indices with the species from specieslist as keys
• indices_to_species (dict) – the reverse of speciesindices (keys are the indices and values are the species)
• human (str, optional) – indicate whether the output of this function should be formatted for a human to read (‘yes’). Default is ‘no’

Returns:

rates_list – a list of the rate expressions for all the reactions in the model

Return type:

list

ligpy_utils.build_reactant_dict(completereactionlist, speciesindices)

Build a dictionary of the reactants involved in each reaction, along with their stoichiometric coefficients. The keys of the dictionary are the reaction numbers, the values are lists of lists [[reactant1index, -1*coeff1],...]

Parameters:

• completereactionlist (str) – path to the file complete_reaction_list.dat
• speciesindices (dict) – the dictionary speciesindices from get_speciesindices()

Returns:

reactant_dict – a dictionary where keys are reaction numbers and values are lists of lists with the reactants and their stoichiometric coefficients for each reaction

Return type:

dict

ligpy_utils.build_species_rxns_dict(completereactionlist)

Build a dictionary where keys are species and values are lists with the reactions that species is involved in, that reaction’s sign in the net rate equation, and the stoichiometric coefficient of the species in that reaction.

Parameters:completereactionlist (str) – path to the file complete_reaction_list.dat Returns:species_rxns – keys are the species in the model; values are lists of [reaction that species is involved in, sign of that species in the net rate equation, stoichiometric coefficient] Return type:dict

ligpy_utils.check_mass_balance()

Check for conservation of mass, and if mass is not conserved, see which reactions are creating or losing mass.

Note that mass will not be wholly conserved in this model because protons are not accounted for when radicals are involved in non-Hydrogen-abstraction reactions, but all other reactions should conserve mass.

Parameters:None – Returns:total_mass_balance – an array with the amount of mass gained or lost in each reaction Return type:numpy array

ligpy_utils.check_species_fate()

Check to see which species (if any) are only produced, but never consumed in the model reactions (assuming that all reactions occur).

Parameters:None – Returns:fate_dict – a dictionary with the fate of model species Return type:dictionary

ligpy_utils.check_species_in_MW(specieslist=None)

Check to make sure that everything in the specieslist is in the MW dictionary from constants.py.

Parameters:specieslist (list, optional) – a list of species to check against. If no list is specified then the function get_specieslist() will be used to generate the default list Returns: Return type:None

ligpy_utils.define_initial_composition(compositionlist, species)

Read the plant ID specified and define the initial composition of the lignin polymer in terms of the three model components (PLIGC, PLIGH, PLIGO).

Parameters:

• compositionlist (str) – the path of the compositionlist.dat file
• species (str) – the name of a lignin species that exists in the compositionlist.dat file

Returns:

• pligc_0 (float) – The initial composition (mol/L) of PLIGC
• pligh_0 (float) – The initial composition (mol/L) of PLIGH
• pligo_0 (float) – The initial composition (mol/L) of PLIGO

ligpy_utils.get_k_value(T, reaction_index, kmatrix)

Returns the value of the rate constant for a particular reaction index.

Parameters:

• T (float) – temperature in Kelvin
• reaction_index (int) – the index of the reaction for which you want the rate
• kmatrix (list) – the kmatrix generated by build_k_matrix()

Returns:

k – the value of the rate constant for the given reaction at the given temperature.

Return type:

float

ligpy_utils.get_k_value_list(T, kmatrix)

Returns a list of all the k-values for a given temperature.

Parameters:

• T (float) – temperature in Kelvin
• kmatrix (list) – the kmatrix generated by build_k_matrix()

Returns:

kvaluelist – a list of all the rate constant values for a given temperature

Return type:

list

ligpy_utils.get_speciesindices(specieslist)

Create a dictionary to assign an arbitrary index to each of the species in the kinetic scheme.

Parameters:specieslist (list) – a list of all the species in the model Returns:

• speciesindices (dict) – a dictionary of arbitrary indices with the species from specieslist as keys
• indices_to_species (dict) – the reverse of speciesindices (keys are the indices and values are the species)

ligpy_utils.get_specieslist(completereactionlist)

Make a list of all the molecular species involved in the kinetic scheme.

Parameters:completereactionlist (str) – the path to the complete_reaction_list.dat file Returns:specieslist – a list of all the species in the kinetic scheme Return type:list

ligpy_utils.set_paths()

Set the absolute path to required files on the current machine.

Returns:

• reactionlist_path (str) – path to the file complete_reactionlist.dat
• rateconstantlist_path (str) – path to the file complete_rateconstantlist.dat
• compositionlist_path (str) – path to the file compositionlist.dat

ligpy_utils.write_rates_and_odes(filename, rates, odes)

Writes a file that contains the model equations to be solved (a list of rate expressions, followed by a list of ODEs for each species). This file is just for reference for humans to be able to look at the specific reactions that are modeled, it is not actually used by the program. Users should only need to generate this file if they’ve changed anything about the kinetic scheme (it already exists in the data folder).

Parameters:

• filename (str) – the filename (including relative path if appropriate) of the ratesandodes file to write
• rates (list) – the output of build_rates_list() with human=’yes’
• odes (list) – the output of build_dydt_list() with human=’yes’

Returns:

Return type:

None