Reference¶
Subpackages¶
Submodules¶
catmap.model module¶
-
class
catmap.model.
ReactionModel
(**kwargs)[source]¶ The central object that defines a microkinetic model consisting of:
- active sites
- species
- possible reaction steps
- rate constant expressions
- descriptors and descriptor ranges
- data files for energies
- external parameters (temperature, pressures)
- other more technical settings related to the solver and mapper
-
__init__
(**kwargs)[source]¶ Class for managing microkinetic models.
Parameters: setup_file (str) – Specify <mkm-file> from which to load model.
-
__module__
= 'catmap.model'¶
-
_header
(exclude_outputs=[], re_parse=False)[source]¶ Create a string which acts as a header for the log file. The header string ensures that the logfile can be opened interactively by Python by importing necessary libraries and automatically reading in the data_file.
Parameters: - exclude_outputs ([str]) – Attribute names of ReactionModel to exclude in the log file. Optional parameter, default is [].
- re_parse (bool) – Determines whether or not the parser should be specified in the log file. If a parser is included in the log file then a ReactionModel instantiated using that log file as a setup_file argument will attempt to re-parse values from the input_file and setup_file. Optional parameter, default is False.
-
_token
()[source]¶ Create a ‘token’ which uniquely identifies the model based on the user-input parameters. Two models with identical tokens should have identical solutions, although this is not guaranteed if an expert user changes some private attributes.
-
adsorption_to_reaction_energies
(free_energy_dict)[source]¶ Convert adsorption formation energies to reaction energies/barriers.
Parameters: free_energy_dict (dict) – Dictionary containing free energies for each species in the reaction network.
-
static
array_to_map
(array, descriptor_ranges, resolution)[source]¶ Convert numpy array object into CatMAP “map” data structure.
Parameters: - array (numpy.array) – Numpy array of size (resolution x resolution) corresponding to grid spanning descriptor_ranges.
- descriptor_ranges ([[float]]) – Minimum and maximum values of descriptor range for each dimension included in array.
- resolution (int) – Resolution at which the descriptor ranges are sampled.
-
compatibility_check
()[source]¶ Check that the reaction model has all required attributes. Required attributes can be specified in self._required.
-
generate_echem_TS
()[source]¶ generates fake transition state species from self.echem_transition_state_names and populates self.species_definitions with them.
-
generate_echem_species_definitions
()[source]¶ Generates proper species_definitions entries for ele_g, H_g, or OH_g.
-
get_rxn_energy
(rxn, energy_dict)[source]¶ Calculate reaction energy given the energies of all species.
Parameters: - rxn ([[str]]) –
Reaction in CatMAP form:
- [[IS],[TS],[FS]] for activated reaction
- [[IS],[FS]] for non-activated reaction where IS,TS,FS correspond to the names of the species in the initial/transition/final states respectively.
- energy_dict (dict) – Dictionary of energies for all species. Keys should be species names and values should be energies.
- rxn ([[str]]) –
-
get_state_energy
(rxn_state, energy_dict)[source]¶ Calculate energy of a “reaction state” (list of species) given the energies of all species.
Parameters: - rxn_state – List of intermediate species (must be defined in species_definitions)
- energy_dict (dict) – Dictionary of energies for all species. Keys should be species names and values should be energies.
-
load
(setup_file)[source]¶ Load a ‘setup file’ by importing it and assigning all local variables as attributes of the kinetic model. Special attributes mapper, parser, scaler, solver will attempt to convert strings to modules.
-
log
(event, **kwargs)[source]¶ Add an event to the log file. This assumes that the template for the event has been specified in the _log_strings attribute of the class that calls the log() function.
Parameters: - event (str) –
A key that defines the event to be logged. The _log_strings attribute of the subclass which calls log() should be a dictionary where event is a key and the value is a template string. The template string can contain the following variables which will auto-populate:
- pt - the current point in descriptor space
- priority - defaults to 0
In addition, the template may contain other variables which can be passed in as keyword arguments. The following are special arguments:
*n_iter - the iteration number will be appended to the event title
The event title should be of the form routinename_status, where routinename is the name of the routine/algorithm and the status is succeess/failure/evaluation/etc.
- kwargs (keyword arguments) – Keyword arguments can be specified and will be passed into the template retrieved from _log_strings[‘event’]
- event (str) –
-
make_standalone
(standalone_script='stand_alone.py')[source]¶ Create a stand alone script containing the current model.
Parameters: standalone_script (str) – The name of the file where the standalone script is created [stand_alone.py].
-
static
map_to_array
(mapp, descriptor_ranges, resolution, log_interpolate=False, minval=None, maxval=None)[source]¶ Convert into CatMAP “map” data structure into numpy array. The “map” will be interpolated onto a regular grid.
Parameters: - mapp (CatMAP map (see MapperBase)) – CatMAP “map” structured lists of descriptor points and corresponding values.
- descriptor_ranges ([[float]]) – Minimum and maximum values of descriptor range for each dimension included in array.
- resolution (int) – Resolution at which the descriptor ranges are sampled.
- log_interpolate (bool, optional) – Take logarithm of values before interpolation. Defaults to False.
- minval (float) – Replace any values less than minval with minval. None implies no cutoff. Defaults to None.
- maxval (float) – Replace any values greater than maxval with maxval. None implies no cutoff. Defaults to None.
-
model_summary
(summary_file='summary.tex')[source]¶ Write summary of model into TeX file.
Parameters: summary_file (str) – Filename where TeX summary of model is written.
-
multi_point_analysis
()[source]¶ Analyze the output at a list of points. Points should be specified as a list in the descriptor_values attribute.
-
parse
(*args, **kwargs)[source]¶ Read in all the information from the input_file. Alias to parser.parse.
-
parse_elementary_rxns
(equations)[source]¶ Convert elementary reaction strings into structured elementary reaction lists.
Parameters: equations – List of reaction equation strings. For non-activated reactions (e.g. no activation barrier) the strings should follow a syntax like:
- A_s + B_q <-> C_s + D_q
- A_s + B_q -> C_s + D_q
while an activated reaction should follow a syntax like:
- A_s + B_q <-> A-B_s + *_q -> AB_s + *_q
where A,B,C,D are names of chemical species, A-B is the name of a transition-state, and s,q are names of different site types.
:type equations:[str]
-
print_rxn
(rxn, mode='latex', include_TS=True, print_out=False)[source]¶ Print a structured elementary step and print it as plain text or latex.
Parameters: - rxn ([[str]]) – Elementary step list of the form [[IS1,IS2,…],[TS1,TS2,…],[FS1,FS2,…]] where ISi,TSi,FSi correspond to species in the initial/transition/final states and the [TS1,TS2,…] list is optional.
- mode (str) – Output mode. Should be ‘latex’ for LaTeX, or ‘text’ for plain text.
- include_TS – Include the transition-state in the output. Optional parameter, default is True.
:type include_TS:bool
Parameters: print_out – Print the reaction to stdout. Optional parameter, default is False. :type print_out:bool
-
retrieve_data
(mapp, point, precision=2)[source]¶ Retrieve the data corresponding to a given point in descriptor space from a CatMAP ‘map’ object. If no data is found for the specified point, then None is returned.
Parameters:
-
static
reverse_rxn
(rxn)[source]¶ Reverse the reaction provided. [[IS],[TS],[FS]] -> [[FS],[TS],[IS]]
Parameters: rxn ([[str]]) – Reaction in CatMAP form:
- [[IS],[TS],[FS]] for activated reaction
- [[IS],[FS]] for non-activated reaction where IS,TS,FS correspond to the names of the species in the initial/transition/final states respectively.
-
run
(**kwargs)[source]¶ Run the microkinetic model. If recalculate is True then data which is re-loaded will be used as an initial guess; otherwise it will be assumed to be correct.
Parameters: recalculate (bool) – If True solve model again using previous results as initial guess
-
static
same_rxn
(rxn1, rxn2)[source]¶ Determine if two reactions rxn1 and rxn2 are identical.
Parameters:
-
single_point_analysis
(pt)[source]¶ Find rates/coverages at a single point.
Parameters: pt ([float]) – Point in descriptor-space ([x,y])
-
texify
(ads)[source]¶ Generate LaTeX representation of an adsorbate.
Parameters: ads (str) – Adsorbate short-hand.
-
update
(dictvar, override=False)[source]¶ Update the attributes of the model with the attribute names/vals included in dictvar. The keys of dictvar correspond to attributes of the ReactionModel to be set, and the values correspond to the values they will be set to.
Parameters: - dictvar (dict) – Dictionary of key names corresponding to attributes of ReactionModel instance to be updated with the associated values in dictvar.
- override (bool) – If True then the values in dictvar will override existing values of the attributes of ReactionModel instance. Optional parameter, default is False.
catmap.functions module¶
-
catmap.functions.
add_dict_in_place
(dict1, dict2)[source]¶ Updates dict1 with elements in dict2 if they do not exist. otherwise, add the value for key in dict2 to the value for that key in dict1
Parameters:
-
catmap.functions.
cartesian_product
(*args, **kwds)[source]¶ Take the Cartesian product
Todo
Explain what the args and kwds are
-
catmap.functions.
constrained_relaxation
(A, b, x0, x_min, x_max, max_iter=100000, tolerance=1e-10)[source]¶ Solve Ax=b subject to the constraints that x_i > x_min_i and x_i < x_max_i. Algorithm is from Axelson 1996.
Note that x_min/Max are both lists/arrays of length equal to x
Parameters: Todo
Check to make sure docstring is correct.
-
catmap.functions.
convert_formation_energies
(energy_dict, atomic_references, composition_dict)[source]¶ Convert dictionary of energies, atomic references and compositions into a dictionary of formation energies
Parameters: Todo
Explain the keys and values for energy_dict, atomic_references, and composition_dict
-
catmap.functions.
fetch_all_output_variables
()[source]¶ Use code-inspection to extract all processed output variables from
catmap.scalers.scaler_base.ScalerBase.set_output_attrs, catmap.solvers.solver_base.SolverBase.set_output_attrsNew keywords should work out of the box if they are added in one of those functions and using one of the kind of if-statements that are already in place.
-
catmap.functions.
get_composition
(species_string)[source]¶ Convert string of species into a dictionary of species and the number of each species.
Parameters: species_string – A string of the reaction species. Should be a chemical formula string that may also contain ‘-‘,’&’,or,’pe’. ‘pe’ is a special case corresponding to a proton-electron pair and has the compositon of H, while ele corresponds to an electron and has no associated atoms.
-
catmap.functions.
linear_regression
(x, y, constrain_slope=None)[source]¶ Perform linear regression on x and y and return the slope and intercept.
Parameters: - x (array_like) – x-coordinates.
- y (array_like) – y-coordinates.
- constrain_slope (float, optional) – Slope constraint
-
catmap.functions.
match_regex
(string, regex, group_names)[source]¶ Find matching regular expression in string and return a dictionary of the matched expressions.
Parameters: Todo
Check that this docstring is correct.
-
catmap.functions.
numerical_jacobian
(f, x, matrix, h=1e-10, diff_idxs=None)[source]¶ Calculate the Jacobian matrix of a function at the point x0.
This is the first derivative of a vectorial function:
f : R^m -> R^n with m >= nHacked from mpmath.calculus.optimize
Parameters: - f (callable) – Function.
- x –
- matrix –
- h (float, optional) –
Todo
Fill in the descriptions for f, x, matrix, and h
-
catmap.functions.
offset_smooth_piecewise_linear
(theta_tot, slope=1, cutoff=0.25, smoothing=0.05, offset=0.1)[source]¶ Piecewise linear function with an offset. Not equivalent to piecewise linear for second-order interactions
Parameters: Todo
Fill in description for theta_tot
-
catmap.functions.
parse_constraint
(minmaxlist, name)[source]¶ Parse constraints for the relation. Returns two lists of minimum and maximum constraints
Parameters: Todo
Explain minmaxlist and name
-
catmap.functions.
scaling_coefficient_matrix
(parameter_dict, descriptor_dict, surface_names, parameter_names=None, coeff_mins=0, coeff_maxs=1e+99, return_error_dict=False)[source]¶ Class for determining adsorption and transition-state energies as a linear function of descriptors.
Parameters: - parameter_dict (dict) – Dictionary where the key is adsorbate name and the value is a list of adsorption energies for each surface. If some surfaces do not have an adsorption energy use None as a placeholder.
- descriptor_dict (dict) – Dictionary where the key is surface name and the value is a list of descriptor values for each surface.
- surface_names (list) – List of surfaces which defines the order of surface adsorption energies in parameter_dict.
- parameter_names (list, optional) – List of adsorbates which defines the order of adsorption coefficients in the output. Default is the order of parameter_dict.keys().
- coeff_mins (float, optional) – Defines the minimum value of the coefficient for each descriptor. Should be a matrix/array/list of lists which matches the shape of the expected output.
- coeff_maxs (float, optional) – Same as coeff_mins but for the maximum value of the coefficient.
- return_error_dict (bool, optional) – Specify whether or not to return a dictionary of the errors.
catmap.cli module¶
-
catmap.cli.
main
(args=None)[source]¶ The CLI main entry point function.
The optional argument args, can be used to directly supply command line argument like
$ catmap <args>
otherwise args will be taken from STDIN.