Chemical Kinetics

kinetics.py module

So far, it only contains the KORD class

Kinetic Order of Reaction Determination, KORD

1. Principle

1.1 Experimental Measurements (\(G_\mathrm{EXP}\))

In chemical kinetics, we track the evolution of molar concentrations over time: \(C_{i}(t)\). Experimentally, we measure a physical quantity proportional to these concentrations: \(G_\mathrm{EXP}(t)\).

  • Spectrophotometry: \(G_\mathrm{EXP} = A = \sum_{i} \epsilon_{i} \cdot l \cdot C_{i}\), where \(A\) is the absorbance

  • Polarimetry: \(G_\mathrm{EXP} = \alpha = \sum_{i} [\alpha]_{i} \cdot l \cdot C_{i}^{w}\)

  • Conductivity: \(G_\mathrm{EXP} = \sigma = \sum_{i} \lambda_{i} \cdot C_{i}\)

General Form: \(G_\mathrm{EXP}(t) = \sum_{i} \eta_{i} \cdot C_{i}(t)\)

1.2 Theoretical Model (\(G_\mathrm{THEO}\))

The model has three different expressions (see Theoretical model section), depending on the order of the reaction:

Standard Formula for Order 0:

\[\begin{split}\hat{G}^{[0]}(t)=\begin{cases} G_{0}+\beta\dfrac{kt}{b_{\infty}}\left(G_{\infty}-G_{0}\right) & t\leq\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k}\\ G_{\infty} & t>\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k} \end{cases}\end{split}\]

Standard Formula for Order 1:

\[\hat{G}^{[1]}(t)=G_{\infty}+\exp\left(-\alpha kt\right)\left(G_{0}-G_{\infty}\right)\]

Standard Formula for Order 2:

\[\hat{G}^{[2]}(t)= G_{0}+\dfrac{\left(G_{\infty}-G_{0}\right)}{1+\dfrac{\beta}{b_{\infty}\alpha^{2}kt}}=G_{0}+\frac{\left(G_{\infty}-G_{0}\right)b_{\infty}\alpha^{2}kt}{b_{\infty}\alpha^{2}kt+\beta}\]

\(G_\mathrm{THEO}\) is defined by two types of values: fixed parameters (input by the user) and adjustable variables (optimized by the algorithm).

Fixed Parameters:

  • Reaction Order: \(n \in \{0, 1, 2\}\) (The user selects the order to test).

  • Stoichiometry: \(\alpha\) and \(\beta\) are known constants, provided by the user.

    \(\alpha\) and \(\beta\) must be the smallest possible positive integers

  • Initial Concentration: \(a_{0}\) (Note: For Order 1, \(G_{THEO}\) is independent of \(a_{0}\)). The concentration must also be provided by the user

    The final concentration of B, \(b_{\infty}\) is related to \(a_0\) by the relation:

    \[\frac{a_0}{\alpha} = \frac{b_{\infty}}{\beta}\]

Adjustable Variables: The model fits the experimental data by adjusting the following:

  • Rate Constant: \(k\)

  • Final Value: \(G_{\infty}\)

  • Initial Value: \(G_{0}\) (While \(G_{0}\) is measured, the algorithm also adjusts it to ensure the best fit starting point).

The optimization is performed for a specific reaction order at a time to determine which model best describes the experimental data.

By default, KORD chooses the first and last \(G_\mathrm{EXP}\) values as \(G_{0}\) and \(G_{\infty}\). And a default \(k\) value is also setup by KORD. If you need to change that because of a convergence issue, ensure your starting values for \(k\), \(G_{0}\) and \(G_{\infty}\) are realistic to help the algorithm converge.

1.3 Optimization (RMSD)

The algorithm minimizes the Root-Mean-Square Deviation to fit the theoretical curve to the experimental data:

\[RMSD = \sqrt{\frac{1}{n} \sum_{k=1}^{n} \{G_\mathrm{EXP}(t_{k}) - G_\mathrm{THEO}(t_{k})\}^{2}}\]

1.4 Input

Data input is performed through a structured Excel file. Users simply provide the kinetic parameters (\(\alpha\), \(\beta\)), the initial concentration \([A]_0\), and the experimental data series (time \(t\) and property \(G_{\mathrm{exp}}\)).

2. Theoretical Model

The reaction model used in KORD is designed to be as simple as possible based on the following criteria:

  • Single-component reaction: A unique reactant \(A\) transforms into a unique product \(B\) (\(\alpha A \rightarrow \beta B\))

  • Total reaction: The reaction goes to completion (the extent of reaction is 100%)

  • Closed system: No exchange of matter occurs between the system and its environment; only energy exchanges are possible

  • Homogeneous system: The concentration of any compound \(C_i\) is uniform throughout the entire system

  • Isochoric system: The volume of the system remains constant throughout the reaction.

2.1 Reactant Expression \(a(t)\)

The rate law is defined as:

\[v = -\frac{1}{\alpha} \frac{d[A]}{dt} = k [A]^{n}\]

  • Order 0:

\[\begin{split}a(t)=\begin{cases} a_{0}-\alpha kt & t\leq\frac{a_{0}}{\alpha k}\\ 0 & t>\frac{a_{0}}{\alpha k} \end{cases}\end{split}\]

  • Order 1:

\[a(t) = a_{0} \exp(-\alpha kt)\]

  • Order 2:

\[a(t) = \frac{1}{\frac{1}{a_{0}} + \alpha kt}\]

2.2 Product Expression \(B(t)\)

Derived from mass balance (\(M_{A} a(t) + M_{B} b(t) = M_{A} a_{0} = M_{B} b_{\infty}\)):

  • Order 0:

\[\begin{split}b(t)=\begin{cases} \beta kt & t\leq\frac{b_{\infty}}{\beta k}\\ 0 & t>\frac{b_{\infty}}{\beta k} \end{cases}\end{split}\]

  • Order 1:

\[b(t) = b_{\infty} \{1 - \exp(-\alpha kt)\}\]

  • Order 2:

\[b(t)=\frac{b_{\infty}}{1+\frac{\beta}{b_{\infty}\alpha^{2}kt}}\]

2.3 Global Expression \(G_\mathrm{THEO}(t)\)

The theoretical quantity is a linear combination of \(a(t)\) and \(b(t)\):

\[G_\mathrm{THEO}(t) = \frac{G_{0}}{a_{0}} \cdot a(t) + \frac{G_{\infty}}{b_{\infty}} \cdot b(t)\]

Standard Formula for Order 0:

\[\begin{split}\hat{G}^{[0]}(t)=\begin{cases} G_{0}+\beta\dfrac{kt}{b_{\infty}}\left(G_{\infty}-G_{0}\right) & t\leq\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k}\\ G_{\infty} & t>\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k} \end{cases}\end{split}\]

Warning: This mathematical model for Order 0 is a linear equation. Unlike Order 1 or 2, this linear model does not naturally plateau. Depending on the values of \(k\) and \(t\), the model may predict non-physical values (e.g., negative absorbance or negative concentration) if the time \(t\) exceeds the theoretical completion time \(t_{\mathrm{end}} = \frac{a_{0}}{\alpha k}=\frac{b_{\infty}}{\beta k}\). These values are mathematical artifacts and should be ignored.


Standard Formula for Order 1:

\[\hat{G}^{[1]}(t)=G_{\infty}+\exp\left(-\alpha kt\right)\left(G_{0}-G_{\infty}\right)\]

Standard Formula for Order 2:

\[\begin{split}\hat{G}^{[0]}(t)=\begin{cases} G_{0}+\beta\dfrac{kt}{b_{\infty}}\left(G_{\infty}-G_{0}\right) & t\leq\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k}\\ G_{\infty} & t>\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k} \end{cases}\end{split}\]

API reference

class pyphyschemtools.kinetics.KORD(t_exp=None, G_exp=None, headers=('Time / s', 'G'), a0=1.0, alpha=1.0, beta=1.0, k_guess=None, G_0_guess=None, G_inf_guess=None, b_inf_guess=None, t_simul_max=15, verbose=True)[source]

Bases: object

Initialize the kinetic study with experimental data. Reaction: alpha A = beta B

Parameters:

  • t_exp (-) – Time values.

  • G_exp (-) – Measured physical quantity (Absorbance, Conductivity, etc.).

Fixed Parameters:

  • alpha (float): Stoichiometric coefficient for A reactant (smallest positive integer). Default is 1.0.

  • beta (float): Stoichiometric coefficient for B product (smallest positive integer). Default is 1.0.

  • a0 (float): Initial concentration. Note: G_theo is independent of a0 for Order 1. Default is 1.0.

Adjustable Variables (Initial Guesses):

  • k_guess (float, optional): Initial estimate for the rate constant. Default is 0.01.

  • G_0_guess (float, optional): Initial estimate for the initial measured value (G at t=0). if None, it will be initialized as G_exp[0]

  • G_inf_guess (float, optional): Initial estimate for the final measured value (G at infinity). if None, it will be initialized as G_exp[-1]

  • b_inf_guess (float, optional): Initial estimate for the final concentration of B ([B] at infinity). if None, it will be initialized as [A](t=0), i.e. a0

Other Args:

  • t_simul_max (float): the maximum time duration for theoretical simulations. It defines the range of the time vector [0, t_simul_max}] used to simulate and plot kinetic curves with simulate_plot

  • verbose (bool): If True defaulk), enables detailed optimization logs (recommended).

  • headers (tuple of strings): headers of the t_exp and G_exp arrays read in the excel file

G0_theo(t, k, G0, Ginf, binf)[source]

Model for Order 0 kinetics

G1_theo(t, k, G0, Ginf)[source]

Model for Order 1 kinetics

G2_theo(t, k, G0, Ginf, binf)[source]

Model for Order 2 kinetics

concentrations(order, t, binf, k)[source]

Calculate the time-dependent concentrations of reactant A and product B.

This method derives the initial concentration (a0) from the fitted final product concentration (binf) using the stoichiometric ratio alpha/beta. It then computes the concentration profiles based on the integrated rate laws for the specified kinetic order.

Parameters:

  • order (int) – Kinetic order (0, 1, or 2).

  • t (array-like) – Time vector for the calculation.

  • binf (float) – Final concentration of product B at t=infinity.

  • k (float) – Rate constant.

Returns:

(a, b) where ‘a’ is the concentration array of reactant A

and ‘b’ is the concentration array of product B.

Return type:

tuple

Notes

  • Order 0: Linear decay/formation until reactant exhaustion.

  • Order 1: Exponential decay/formation.

  • Order 2: Hyperbolic progression based on the 1/[A] linear relationship.

fit(k_guess, G_0_guess, G_inf_guess, A_0_guess, order=1)[source]

Fits the selected kinetic model (Order 0, 1, or 2) to the experimental data.

This method uses non-linear least squares (scipy.optimize.curve_fit) to simultaneously optimize the rate constant (k), the initial and final physical property values (G0, Ginf), and the final product concentration (binf). Physical constraints are applied via parameter bounds to ensure k and binf remain positive.

It includes automated ‘Smart Guessing’ for k, based on initial rates and computes information criteria (AIC/BIC) for model selection.

Parameters:

  • k_guess (float) – Initial estimate for the rate constant (k).

  • G_0_guess (float) – Initial estimate for the physical property at t=0.

  • G_inf_guess (float) – Initial estimate for the physical property at t=infinity.

  • b_inf_guess (float) – Initial estimate for the final product concentration [B].

  • order (int, optional) – Kinetic order of the reaction (0, 1, or 2). Defaults to 1.

Returns:

A dictionary containing the optimized parameters (‘k’, ‘G0’, ‘Ginf’, ‘binf’)

and statistical metrics (‘RMSE’, ‘R2’, ‘t_half’). Returns None if optimization fails to converge.

Return type:

dict

Notes

  • For Order 1, the timing is independent of binf, and alpha is coupled with k; hence binf is kept fixed during optimization.

  • For Orders 0 and 2, binf and stoichiometry (alpha, beta) explicitly define the reaction’s capacity and end-point timing, ensuring physical consistency between the plateau and the slope.

get_best_order(verbose=True)[source]

Determines and prints the best model based on the lowest RMSE.

halflife(order, binf, k)[source]

Calculate the half-life (t1/2) for the reaction based on the kinetic order.

The half-life represents the time required for the reactant concentration to reach half of its initial value (a0/2).

Parameters:

  • order (int) – Kinetic order (0, 1, or 2).

  • k (float) – The optimized or guessed rate constant.

Returns:

The calculated half-life value.

Return type:

float

Notes

  • Order 0: t1/2 = a0 / (2 * alpha * k) -> Dependent on a0.

  • Order 1: t1/2 = ln(2) / (alpha * k) -> Independent of a0.

  • Order 2: t1/2 = 1 / (alpha * k * a0) -> Inversely proportional to a0.

static load_from_excel(file_path, exp_number, sheet_name=0, show_data=True)[source]

Static method to extract data from an Excel file. Selects the pair of columns (t, G) corresponding to the experiment number. Also loads parameters (a0, alpha, beta)

Format:

  • Row 1: Headers for t and G

  • Row 2: [A]0 value (in the G column)

  • Row 3: alpha value (in the G column)

  • Row 4: beta value (in the G column)

  • Row 5+: [t, G] data points

plot_all_fits(save_img=None)[source]

Plots experimental data and all three kinetic models for visual comparison. If save_img is provided, saves the plot (png, svg, jpg, pdf according to the extension). Vectorial svg is recommended

simulate_plot(save_img=None)[source]

Plots the initial guesses for all three kinetic orders (0, 1, 2), for example to visualize the starting point of a fit.

If save_img is provided, saves the plot (png, svg, jpg, pdf according to the extension). Vectorial svg is recommended

class pyphyschemtools.kinetics.kbasic[source]

Bases: object

Recherche pédagogique de la constante de vitesse k.

Utilisation typique

kb = kbasic()
kb.read("mesures.xlsx")   # 1) lire les données
kb.fit(ordre=1)           # 2) chercher le meilleur k
kb.plot()                 # 3) tracer le résultat

La grandeur mesurée G décroît avec le temps depuis sa valeur initiale G0. La forme de G(t) dépend de l’ordre de la réaction :

  • ordre 0 : décroissance LINÉAIRE

  • ordre 1 : décroissance EXPONENTIELLE (le cas le plus courant)

  • ordre 2 : décroissance HYPERBOLIQUE

fit(ordre=1, G0=None, k_depart=0.1)[source]

Trouve la valeur de k qui minimise le RMSD pour l’ordre choisi.

Si G0 n’est pas donné, on le prend égal à la première valeur mesurée. Sinon, on utilise la valeur fournie par l’utilisateur.

Retourne : (k_optimal, rmsd_au_minimum)

plot()[source]

Trace la comparaison données / modèle et le paysage du RMSD.

read(fichier=None, colab=False)[source]

Lit un fichier Excel à deux colonnes (temps, G) et affiche un récapitulatif sous forme de DataFrame pandas.

Détecte automatiquement si la première ligne est un en-tête. Si oui, les noms de colonnes serviront de labels pour les axes du tracé.

Retourne le DataFrame des données lues.

Arguments :
fichierchemin (ou URL) du fichier Excel à lire.

Inutile si colab=True (on choisit le fichier à l’upload).

colabsi True, ouvre le bouton d’upload de Google Colab

et lit le fichier choisi. Défaut False.