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

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.

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

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.


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.

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

Check that the reaction model has all required attributes. Required attributes can be specified in self._required.


Use mapper to create map/volcano-plot of rates/coverages.


generates fake transition state species from self.echem_transition_state_names and populates self.species_definitions with them.


Generates proper species_definitions entries for ele_g, H_g, or OH_g.


Dynamically compile static functions

get_rxn_energy(rxn, energy_dict)[source]

Calculate reaction energy given the energies of all species.

  • 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.
get_state_energy(rxn_state, energy_dict)[source]

Calculate energy of a “reaction state” (list of species) given the energies of all species.

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


Load in output data from external files.

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.

  • 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’]

Create a stand alone script containing the current model.

Parameters:standalone_script (str) – The name of the file where the standalone script is created [].
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.

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

Write summary of model into TeX file.

Parameters:summary_file (str) – Filename where TeX summary of model is written.

Analyze the output at a list of points. Points should be specified as a list in the descriptor_values attribute.

nearest_mapped_point(mapp, point)[source]

Get the point in the map nearest to the point supplied

parse(*args, **kwargs)[source]

Read in all the information from the input_file. Alias to parser.parse.


Convert elementary reaction strings into structured elementary reaction lists.


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]

static print_point(descriptors, n=2)[source]

Pretty-print a set of descriptor values.

  • descriptors ([float]) – List of descriptor values [d1,d2,…] where d1,d2,… are floats corresponding to coordinates in descriptor space.
  • n (int) – Number of decimals to print out. Optional parameter, default is 2.
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.

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

  • mapp (CatMAP map (see MapperBase)) – CatMAP “map” structured lists of descriptor points and corresponding values.
  • point ([float]) – Coordinates of a point in descriptor space.
  • precision (int) – Require descriptor coordinates to match with ‘precision’ decimals. Optional parameter, default is 2.
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 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.

  • rxn1 ([[str]]) – Elementary reaction list. See print_rxn for syntax.
  • rxn2 ([[str]]) – Elementary reaction list. See print_rxn for syntax.

sets elementary rxn-specific attributes to the appropriate places


Find rates/coverages at a single point.

Parameters:pt ([float]) – Point in descriptor-space ([x,y])

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.

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

Run several consistency check on the model, such as :

  • all gas ratios add to 1.
  • all mass and site balances are fulfilled.
  • prefactors are set in the correct format.
  • a mapping resolution is set (the default is 15 data points per descriptor axis).

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

  • dict1 (dict) – Dictionary.
  • dict2 (dict) – Dictionary.
catmap.functions.cartesian_product(*args, **kwds)[source]

Take the Cartesian product


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

  • A (numpy.array) – A matrix.
  • b (numpy.array) – b vector.
  • x0 (numpy.array) – x vector
  • x_min (array_like) – Minimum constraints.
  • x_max (array_like) – Maximum constraints.
  • max_iter (int, optional) – Maximum number of iterations.
  • tolerance (float, optional) – Tolerance.


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

  • energy_dict (dict) – Dictionary of energies for all species. Keys should be species names and values should be energies.
  • atomic_references (dict) – Dictionary of atomic reference energies (?)
  • composition_dict (dict) – Dictionary of compositions


Explain the keys and values for energy_dict, atomic_references, and composition_dict


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_attrs

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


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.

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

  • string (str) – String.
  • regex (str) – Regular expression.
  • group_names (list) – Corresponding names for each matched group.


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 >= n

Hacked from mpmath.calculus.optimize

  • f (callable) – Function.
  • x
  • matrix
  • h (float, optional) –


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

  • theta_tot
  • max_coverage (int, optional) – Maximum coverage.
  • cutoff (float, optional) – Cutoff.
  • smoothing (smoothing, optional) – Smoothing.
  • offset (float, optional) – Offset.


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

  • minmaxlist (list) – List of minimum and maximum constraints.
  • name (str) – Name for the list of constraints.


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.

  • 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.functions.smooth_piecewise_linear(theta_tot, slope=1, cutoff=0.25, smoothing=0.05)[source]

Smooth piecewise linear function.

  • theta_tot
  • slope (float, optional) – slope of line
  • cutoff (float, optional) – Cutoff.
  • smoothing (float, optional) – Amount of smoothing.


Fill in descriptions and types for theta_tot

catmap.cli module

catmap.cli.get_options(args=None, get_parser=False)[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.

catmap.cli.match_keys(arg, usage, parser)[source]

Try to match part of a command against the set of commands from usage. Throws an error if not successful.[source]

Wrapper around interactive ipython shell that factors out ipython version depencies.

Module contents

class catmap.ReactionModelWrapper[source]

Return the value of the reaction model instance if its there. Otherwise return the instances own value (or none if the instance does not have the attribute defined and the attribute is not private)

__module__ = 'catmap'
__setattr__(attr, val)[source]

Set attribute for the instance as well as the reaction_model instance

catmap.griddata(*args, **kwargs)[source]

Wrapper function to avoid annoying griddata errors