classes

This module contains the core classes of the library: Energy, MassBalance, JacobianElement, Compound, TransitionState, DiffusionTS, Reaction, Chemical System and SimulationParameters and ConvergenceParameters.

Energy

class pykinetic.classes.Energy(value=0.0, unit='hartree')

Objects that represents a number with an energy unit.

Parameters:

• value (float) -- Number or object with a __float__ (the default is 0.0).

• unit (str) -- Energy unit in which the value parameter is provided. See class variable _units for the different implemented units (the default is 'hartree').

_units

['hartree', 'eV', 'cm-1', 'kcal/mol', 'kJ/mol', 'J/mol', 'K', 'J', 'Hz']

Type:

list

unit

value

as_unit(unit)

Returns a string with the value expressed in the unit specified.

Parameters:

unit (str) -- A valid string representing an energy unit, see Energy._units.

Return type:

str

to_SI()

Returns the value in units of the SI.

Return type:

float

to_unit(unit)

Changes the unit of the object.

Parameters:

unit (str) -- A valid string representing an energy unit, see Energy._units.

ChemicalSystem

class pykinetic.classes.ChemicalSystem(T=298.15, unit='kcal/mol')

This class represents a chemical system, understanding it as a set of compounds, reactions, barriers and Free Energies of Reaction, it includes the utilities for human representation (A + B => C) and the matrix representation.

Parameters:

• T (float) -- Temperature in K (the default is 298.15).

• unit (str) -- Default unit to assume when any conflict arises. It is also the default unit to report all energies.

shape

(n_reactions, n_compounds)

Type:

tuple

species

n_compounds

Type:

int

Name2Compound

Mapping used for accesing the compounds by name

Type:

dict

Name2TS

Mapping used for accesing the Transition States by name

Type:

dict

compounds

Type:

list

reactions

Type:

list

transitionstates

Type:

list

T

Temperature in K. Setting this attribute will set the same T for all the reactions in the system.

Type:

float

RxCMatrix()

Returns a matrix that represents the system in which per each Matrix[i,j] corresponds to the coefficient of the j compound in the i reaction. Possitive if its a product and negative if its a reactant.

Return type:

numpy.array

Raises:

OperationError -- If the ChemicalSystem is not Updated

cadd(compound, update=False)

Forcefully adds a compound object and updates the dictionaries overwriting it if it already existed.

Parameters:

• compound (Compound) --

• update (bool) -- Whether to update the compounds in the system after adding it or not (the default is False).

cextend(compounds, update=True)

Lazy Addition, it first adds all the compounds and then it updates them.

Parameters:

• compounds (list) -- list of Compound instances

• update (bool) -- Whether to update the compounds in the system after adding it or not (the default is True).

cupdate(start=0, update_keys=False)

Updates the compounds attr reinitializing the indices.

Parameters:

• start (int) -- Positive integrer that represents the initial index used to represent compounds. This parameter should only be changed when writing programs for non-python languages or for including the T and/or V in the differential equations.(the default is 0)

• update_keys (bool) -- if True it will update the Name2Compound attr as well as the keys of each compound in it. (the default is False).

Raises:

AssertionError -- If the start value is negative the whole

jacobian()

returns a list of Jacobian elements for the mass balances of all the compounds in the system.

Returns:

list of JacobianElement items.

Return type:

Out

massbalance(compound)

Creates a MassBalance instance from the mass balance of the compound provided in the chemical system.

Parameters:

compound (Compound) -- Compound whose mass balance is to be obtained

Returns:

MassBalance object

Return type:

MB

radd(reaction, update=True)

Adds and updates a Reaction Instance avoiding duplicates of it within the ChemicalSystem.

Parameters:

• reaction (Reaction) -- reaction to add to the system.

• update (bool) -- if True it modifies the state of the Reaction Instance (the default is True).

rextend(reactions, update=True)

Lazy Addition, it first adds all the reactions and then it updates them.

Parameters:

• reactions (list) -- list of Reaction instances

• update (bool) -- Whether to update the reactions in the system after adding it or not (the default is True).

rupdate(start=0)

Updates the reactions attr ensuring appropiate key and T of each Reaction Instance.

Parameters:

start (int) -- Initial value for the key in the reactions (the default is 0).

Compound

class pykinetic.classes.Compound(label, energy, key=None, scannable=False)

Object representation of a chemical species.

Parameters:

• label (str) -- identifier/name of the species

• energy (energy) -- relative or absolute free energy of the species.

• key (int) -- integrer used to represent the species in the overall chemical system see ChemicalSystem (the default is None).

• scannable (bool) -- Flag to identify if this compound's energy is to be modified.

copy()

Creates a copy of the object with the key set as None.

Reaction

class pykinetic.classes.Reaction(reactants, products, TS=None, T=298.15)

Object that represents a reaction as an elemental step.

Parameters:

• reactants (list) -- Compound instances that represent the reactants of the reaction

• products (list) -- Compound instances that represent the products of the reaction

• TS (TransitionState) -- Transition state that connects reactants and products. It must contain a 'energy' attribute

reactants

compounds

key

number that identifies the reaction in a ChemicalSystem instance.

Type:

int

products

TS

T

Temperature in K.

Type:

float

AE

Activation energy defined as AE = energy(TS)-energy(reactants)

Type:

Energy

k

kinetic constant calculated at the Temperature T.

Type:

float

static ActE2k(T, AE)

Transforms an activation energy to a kinetic constant. Uses TST and Erying Equation with the transmission coefficient equal to 1. The partition coefficients correspond to fluid phase.

Parameters:

• T (float) -- Temperature in Kelvin.

• AE (Energy) -- Activation energy.

Return type:

float

Raises:

ValueError -- If a negative activation energy is provided

coefficient(compound)

Returns the global coefficient of the compound in the reaction if the compound is in the reaction, otherwise returns a 0 This function acts as a wrapper for readability

Transition states

class pykinetic.classes.TransitionState(energy, reactions=None, label=None, scannable=False)

Object representation of the TS. Without an instance of this class assigned to a reaction it is not possible to calculate the Activation energy.

Parameters:

• energy (Energy) -- free energy of the transition state.

• reactions (list) -- A list of reactions where the TS is used. It is used to have a reference to those instances in case it is needed.

• label (str) -- A string to identify the Transition State. If none is provided a default one is assigned upon initialization.

• scannable (bool) -- Marks if the Transition State is object of a scan.

class pykinetic.classes.DiffusionTS(barrier, reactions, label=None, scannable=False)

Object representation of the TS for a diffusion process. It requires a reactions argument and a relative barrier. The transition state will always be 'barrier' in energy higher than the highest reactants.

Parameters:

• energy (Energy) -- free energy of the transition state.

• reactions (list) -- A list of reactions where the TS is used. It is used to ensure that any modification to the TS energy or to the compounds of those reactions does not lead t below any of the reactants in those reactions

• label (str) -- A string to identify the Transition State. If none is provided a default one is assigned upon initialization.

• scannable (bool) -- Marks if the Transition State is object of a scan.

Parameters

class pykinetic.classes.Parameters(**kwargs)

Base class for the Convergence and Simulation Parameters. Provides a construction method from a file. The class should behave like a dictionary.

classmethod read_from(file)

Reads a file line by line and transforms it into a dictionary.

Parameters:

file (str) -- A valid filepath to a file.

Returns:

dictionary containing first column as key and an empty string or the rest of columns as a string

Return type:

dict

class pykinetic.classes.SimulationParameters(**kwargs)

Dictionary with default values for simulations. It includes the keys: {tfin, dt, trep, concentrations}.

classmethod read_from(file)

Reads a file line by line and transforms it into a dictionary.

Parameters:

file (str) -- A valid filepath to a file.

Returns:

dictionary containing first column as key and an empty string or the rest of columns as a string

Return type:

dict

class pykinetic.classes.ConvergenceParameters(**kwargs)

Dictionary with default values for the parameters needed for the convergence of the differential equation solvers to proceed. It includes the keys: {rtol, atol}.

as_str(sep=',')

Joins all the key=val pairs by the selected 'sep' string

MassBalance

class pykinetic.classes.MassBalance(compound, items=None)

Representation of a mass balance.

Parameters:

• compound (Compound) -- Compound of the targeted mass balance

• items (list) -- list of Reactions with a net generation/consumption of 'compound' != 0.

partial(compound)

Do the partial derivative of the mass balance with respect to 'compound' and return a JacobianElement object.

Parameters:

compound (Compound) -- Compound with which the partial derivative is to be carried out.

Returns:

JacobianElement

Return type:

JE

JacobianElement

class pykinetic.classes.JacobianElement(compound1, compound2, items=None)

Representation of an element of a jacobian matrix of the mass balances.

Parameters:

• compound1 (Compound) -- Compound of the targeted mass balance

• compound2 (Compound) -- Compound of the partial derivative.

• items (list) -- list of Reactions in which compound2 appears.