Warning

You are reading the documentation related to the development version. Go here if you are looking for the documentation of the stable release.

spectrochempy.ActionMassKinetics

class ActionMassKinetics(reactions, species_concentrations, arrhenius, T=298.0, **kwargs)[source]

An object which stores a reaction network of elementary reactions.

It stores its rate parameterization, set(s) of initial concentrations, temperature profile(s), with methods for evaluating production rates and concentration profiles assuming action mass kinetic and closed reactor.

Parameters

  • reactions (‘dict’ or list or tuple of str) – Strings giving the n_reactions chemical equation of the network. Reactants and products must be separated by a "->" or “→” symbol, The name of each species should match a key of the species dictionary. Examples: "A + B -> C" or "2A → D" species : dict or list or tuple of dict Dictionary or list of dictionaries giving the initial concentrations for the n_species species.

  • arrhenius (array-like) – Iterable of shape n_reactions x 1, n_reactions x 2 or n_reactions x 3 with either the isothermal rate constants (\(k_1\), …, \(k_n\)) or the Arrhenius rate parameters ((\(A_1\), \(b_1\), \(Ea_1\)), … (\(A_n\), \(b_n\), \(Ea_n\))) or ((\(A_1\), \(Ea_1\)), …)). If a 2-column iterable is provided the temperature exponents are set to 0.

  • T (float, Quantity, callable or list or tuple of , or None, optional default: None) – Temperature. If None, or not given, the system is considered isothermal and T = 298.0 If it is not a temperature quantity, the unit is assumed to be in Kelvin. A function can also be provided which output a temperature T in K vs. time t.

  • Examples

  • ———

  • # A simple A → B → C

  • >>> reactions = (“A -> B”, “B -> C”)

  • >>> species_concentrations = {“A” (1.0, “B”: 0.0, “C”: 0.0})

  • >>> time = np.arange(0, 10)

  • >>> k_exp = np.array(((1.0e8, 52.0e3), (1.0e8, 50.0e3)))

  • >>> kin_exp = scp.ActionMassKinetics(reactions, species_concentrations, k_exp, T=298.0)

  • >>> C_exp = kin_exp.integrate(time)

  • >>> print(f”Concentrations at t = 4 ({C_exp[4.].data}”))

  • Concentrations at t = 4 ([[ 0.7355 0.1879 0.07666]])

  • # Several sets of experimental conditions can be used. In this case, `species`, `T`

  • # are set using lists or tuples of the same length, even if only one is changed

  • >>> species_concentrations = ({“A” (1.0, “B”: 0.0, “C”: 0.0}, {“A”: 1.0, “B”: 0.0, “C”: 0.0}))

  • >>> T = (298.0, 308.0)

  • >>> time = (np.arange(0, 10), np.arange(0, 5))

  • >>> kin_exp = scp.ActionMassKinetics(reactions, species_concentrations, k_exp, T=T)

  • >>> C_exp = kin_exp.integrate(time)

  • >>> print(f”Concentrations at {T[0]}K, t = 4 ({C_exp[0][4.].data}”))

  • >>> print(f”Concentrations at {T[1]}K, t = 4 ({C_exp[1][4.].data}”))

  • Concentrations at 298.0K, t = 4 ([[ 0.7355 0.1879 0.07666]])

  • Concentrations at 308.0K, t = 4 ([[ 0.5448 0.236 0.2192]])

Attributes Summary

A

Stoichiometry matrix A

B

Stoichiometry matrix B

init_concentrations

Concentrations.

n_reactions

Number of reaction reactions

n_species

Number of species

species

Components names.

Methods Summary

fit_to_concentrations(self, Cexp, iexp, ...)

Fit rate parameters and concentrations to a concentration profile.

integrate(self, t[, k_dt, method, left_op, ...])

Integrate the kinetic equations at times t.

Attributes Documentation

A

Stoichiometry matrix A

Stoichiometry matrices A and B are defined in Chellaboina et al. [2009].

B

Stoichiometry matrix B

Stoichiometry matrices A and B are defined in Chellaboina et al. [2009].

init_concentrations

Concentrations.

n_reactions

Number of reaction reactions

n_species

Number of species

species

Components names.

Methods Documentation

fit_to_concentrations(self, Cexp, iexp, i2iexp, dict_param_to_optimize, ivp_solver_kwargs={}, optimizer_kwargs={})[source]

Fit rate parameters and concentrations to a concentration profile.

Parameters

  • Cexp (NDDataset or list ot tuple of NDDatasets) – Experimental concentration profiles on which to fit the model. each set of concentrations can contain more concentration profiles than those to fit.

  • iexp (int) – Indexes of experimental concentration profiles on which the model will be fitted.

  • i2iexp (int) – Correspondence between optimized (external) concentration profile and experimental concentration profile.

  • dict_param_to_optimize (dict or None) – rate parameters to optimize. Keys should be ‘k[i].A’ and ‘k[i].Ea’ for pre-exponential factor.

  • ivp_solver_kwargs (dict) – keyword arguments for the ode solver. Defaults are the same as for solve_ivp, except for method=LSDOA

  • optimizer_kwargs (dict) – keyword arguments the optimization (see minimize).

Returns

dict – A result dictionary.

integrate(self, t, k_dt=None, method='LSODA', left_op=None, c_names=None, use_jac=False, atol=1e-6, rtol=1e-3, **kwargs)[source]

Integrate the kinetic equations at times t.

This function computes and integrates the set of kinetic differential equations given the initial concentration values.

Parameters

  • t (array-like of shape (t_points,) or list or tuple of)

  • `arrays-like`. – Iterable with time values or sets of timle values at which the concentrations are computed.

  • k_dt (float or None') -- Resolution of the time grid used to compute `k(T(t)). Used only for non isothermal reaction.

  • method (str or OdeSolver, optional, default: 'LSODA') – Integration method to use:

    • 'LSODA' (default): Adams/BDF method with automatic stiffness detection and switching.

    • 'RK45' (default): Explicit Runge-Kutta method of order 5(4).

    • 'RK23' : Explicit Runge-Kutta method of order 3(2).

    • 'DOP853': Explicit Runge-Kutta method of order 8.

    • 'Radau' : Implicit Runge-Kutta method of the Radau IIA family of order 5.

    • 'BDF' : Implicit multi-step variable-order (1 to 5) method based on a backward differentiation formula for the derivative approximation.

    ‘LSODA’ is generally faster and seems a good choice for the systems treated in scpy so far. Explicit Runge-Kutta methods (‘RK23’, ‘RK45’, ‘DOP853’) can be used for non-stiff problems and implicit methods (‘Radau’, ‘BDF’) for stiff problems. Among Runge-Kutta methods, ‘DOP853’ is recommended for solving with high precision (low values of rtol and atol ). If not sure, first try to run ‘RK45’. If it makes unusually many iterations, diverges, or fails, your problem is likely to be stiff and you should use ‘Radau’ or ‘BDF’. You can also pass an arbitrary class derived from OdeSolver which implements the solver.

  • left_op (array_like, optional) – A (m x n_species) array to left multiply the (n_species, n_times) array obtained after integration: C.T = left_op @ C.T. Can be used to pool and/or remove some concentration profiles in/from the output matrix of concentrations

  • c_names (list of str) – List of names for each concentration profile. Used if left_op is not None to name/rename the output concentration profiles.

  • use_jac (Bool) – Whether to use the jacobian. Useful for stiff problems, can slightly increase the execution time for non-stiff problems.

  • atol, rtol (float or array_like, optional) – Relative and absolute tolerances. The solver keeps the local error estimates less than atol + rtol * abs(y). Here rtol controls a relative accuracy (number of correct digits), while atol controls absolute accuracy (number of correct decimal places). To achieve the desired rtol, set atol < min(rtol * C) so that rtol dominates the allowable error. If atol > rtol * C the number of correct digits is not guaranteed. Conversely, to achieve the desired atol set rtol such that max(rtol * C) < atol is always smaller than atol. If components of C have different scales, it might be beneficial to set different atol values for different components by passing array_like with shape (n_species,) for atol. Default values are rtol=1e-3 and atol=1e-6.

  • **kwargs – Additional keyword parameters. See Other Parameters.

Other Parameters

  • return_NDDataset (bool, optional, default: True) – Whether to return a NDDataset

  • return_meta (bool, optional, default: False) – Whether to return a dictionary with the solver results. Note that when return_NDDataset is True, meta is always included in the meta attribute of the NDDataset.

Returns

  • C (ndarray or NDDataset, shape ( t_points, n_species)) – Values of the solution at times t.

  • meta (Bunch object with the following fields defined:) –

    • t : ndarray, shape (t_points,) Time points.

    • sol : OdeSolution or None Found solution as OdeSolution instance; None if dense_output was set to False.

    • t_events : list of ndarray or None Contains for each event type a list of arrays at which an event of that type event was detected. None if events` was None.

    • y_events : list of ndarray or None For each value of t_events , the corresponding value of the solution. None if events was None.

    • nfev : int Number of evaluations of the right-hand side.

    • njev : int Number of evaluations of the Jacobian.

    • nlu : int Number of LU decompositions.

    • status : int Reason for a successful algorithm termination:

      • 0 : The solver successfully reached the end of tspan .

      • 1 : A termination event occurred.

    • message : str Human-readable description of the termination reason.

Examples using spectrochempy.ActionMassKinetics

MCR-ALS with kinetic constraints

MCR-ALS with kinetic constraints