Chemical Kinetics

kinetics.py module

This module contains three classes and one standalone function:

  • kbasic — a minimal, self-contained, pedagogical tool: fit a single rate constant \(k\) for one chosen reaction order. See 3. kbasic.

  • KORD (Kinetic Order of Reaction Determination) — the full tool: fit \(k\), \(Y_0\), \(Y_\infty\) (and \(b_\infty\)) for reaction orders 0, 1 and 2, and decide which order the data actually support. See 4. KORD.

  • ReactionNetwork — the general tool: build an arbitrary network of (ir)reversible elementary reactions, simulate every species’ concentration by numerically integrating the mass-action ODE system, and fit the rate constant(s) against experimental data. Not limited to a single A -> B transformation like kbasic/KORD — covers parallel reactions, consecutive reactions, reversible reactions, and any network built out of those. See 5. ReactionNetwork.

  • superpose_plots() — the module’s only standalone function (not a method of any class): overlays the fitted curves of several KORD studies on one plot, e.g. to compare the same data fitted freely vs. with fix_Y0/fix_Yinf. See 4.4.1 Comparing several fits.

Table of Contents


1. Finding a Mathematical Model That Fits the Data

Curve fitting, in general, is the search for the free parameters — generically \(a, b, c, \ldots\) (not to be confused with this module’s own \(a_0\), \(\alpha\), \(\beta\)) — of a mathematical model \(Y_\mathrm{THEO}(t;\, a, b, c, \ldots)\) that make it track the measured data \(Y_\mathrm{EXP}(t)\) as closely as possible. “As closely as possible” needs a single number to minimize, and that number is the Root-Mean-Square Deviation between the measured values and the model evaluated at its best-fit parameters, \(\hat{Y}_\mathrm{THEO}(t)\) (the hat marks a prediction, exactly as in the usual machine-learning notation), over the experimental time points \(t_k\):

\[RMSE = \sqrt{\frac{1}{n} \sum_{k=1}^{n} \{Y_\mathrm{EXP}(t_{k}) - \hat{Y}_\mathrm{THEO}(t_{k})\}^{2}}\]

(You may see this quantity called RMSD — Root Mean Square Deviation — elsewhere, e.g. in crystallography or molecular dynamics; RMSE — Root Mean Square Error, the name used throughout this module and by scikit-learn’s root_mean_squared_error — is the same formula, just the name preferred in statistics/ML.)

Both kbasic.fit() and KORD.fit() work exactly this way: they search — via scipy.optimize.minimize (kbasic) or scipy.optimize.curve_fit (KORD) — for the parameter values that make the RMSE as small as possible.

The RMSE should tend toward 0 as the fit improves, and it will, provided the chosen mathematical model is the right one for the data: a correct model, once its parameters are optimized, reproduces the measurements almost exactly. A wrong model (the wrong reaction order, say) cannot be pushed to a near-zero RMSE no matter how its parameters are tuned, simply because its shape doesn’t match the data’s. KORD builds on this further — see 4.2.4 Model Selection — to compare reaction orders against each other, not just to fit one order’s parameters.


2. Integrated rate laws: \(a(t)\), \(b(t)\) and half-lives for orders 0, 1, 2

Consider a single-reactant, single-product transformation \(\alpha A \rightarrow \beta B\), under the usual simplifying assumptions used throughout this module:

  • Single-component reaction: a unique reactant \(A\) transforms into a unique product \(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.

The rate law is defined as:

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

This section gives the integrated form \(a(t)=[A](t)\), the corresponding product expression \(b(t)=[B](t)\), and the resulting half-life, for \(n \in \{0,1,2\}\). kbasic (section 3) and KORD (section 4) both build on these — kbasic as the special case \(\alpha=1\), \(Y_\infty=0\) (see 3.4 Theory), KORD directly (see 4.3 Theoretical Model).

2.1 Reactant Expression \(a(t)\)

  • 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}\\ b_{\infty} & 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 Half-life \(t_{1/2}\)

The half-life is the time at which \(a(t)\) has fallen to half its initial value, \(a(t_{1/2}) = a_{0}/2\). Inverting the \(a(t)\) expressions above gives, for each order:

  • Order 0: \(t_{1/2} = \dfrac{a_{0}}{2\alpha k}\) — depends on \(a_0\).

  • Order 1: \(t_{1/2} = \dfrac{\ln 2}{\alpha k}\) — independent of \(a_0\).

  • Order 2: \(t_{1/2} = \dfrac{1}{\alpha k a_{0}}\) — inversely proportional to \(a_0\).

KORD.halflife(order, binf, k) implements exactly these three formulas (recovering \(a_0\) from \(b_\infty\), \(\alpha\), \(\beta\) internally), and fit()/get_best_order() store the result in study.results[order]['t_half'].


3. kbasic: a minimal, pedagogical rate-constant fit

3.1 Purpose and limitations

kbasic is a deliberately minimal teaching tool. Given a single time series \((t, Y)\), it finds the one rate constant \(k\) that minimizes the RMSE (see 1. Finding a Mathematical Model That Fits the Data above), for a reaction order you choose yourself (0, 1 or 2). Its point is to make the fitting procedure itself — build a model, define an RMSE, call scipy.optimize.minimize — easy to read and follow end to end in a first course, before moving on to KORD’s richer (and more opaque) model.

To stay that transparent, kbasic makes simplifying assumptions KORD does not, and these are real limitations, not just simplifications:

  • No stoichiometry: it assumes \(\alpha = 1\) and reports an apparent \(k\); it has no \(\beta\), \(a_0\) or \(b_\infty\) at all, and cannot separate a true rate constant from the stoichiometric coefficient.

  • No baseline/plateau: \(Y_\infty\) is implicitly 0 — the three models in _modele decay from \(Y_0\) toward 0 (the order-0 case is floored at exactly 0 by np.maximum). There is no adjustable \(Y_\infty\). Do not use kbasic on data whose measured quantity levels off at a non-zero value — use KORD instead.

  • A single free parameter: only \(k\) is optimized by fit(); \(Y_0\) is always taken from the data (first point) or supplied by the user, never fitted — kbasic already does, permanently, what KORD.fit(fix_Y0=True) does on request.

  • One order at a time, no model comparison: unlike KORD.get_best_order(), there is no AIC/BIC-based verdict. You pick the order yourself, and kbasic only reports the RMSE for that one choice.

  • Order 2 gives an apparent \(k\), not the true rate constant: see 3.4 Theory below for why, and how to recover the true value if you need it.

In short: reach for kbasic for a quick, from-scratch look at a single order on data that genuinely decays to 0 at large \(t\). Reach for KORD as soon as \(Y_\infty \ne 0\), stoichiometry matters, or you want the reaction order itself determined for you rather than assumed.

3.2 Data format

kbasic.read() expects a plain two-column spreadsheet: time in the first column, the measured quantity \(Y\) in the second — nothing else. An optional header row (text) sets the axis labels for plot(); without one, the default labels “Temps”/”Y” are used.

Temps / s

Abs

0

1.40

7.59

1.33

15.18

1.27

…

…

There are no parameter rows here (unlike KORD’s format, see 4.2.3 Input below) — kbasic has no \(\alpha\), \(\beta\) or \(a_0\) to read from the file.

3.3 Quick Start

from pyphyschemtools import kbasic   # lazy-loaded from the package root

kb = kbasic()
kb.read("measurements.xlsx")   # 2-column file: time, Y
kb.fit(ordre=1)                # try order 1 (exponential decay to 0)
kb.plot()                      # data vs. model, and the RMSE landscape

fit() estimates its own starting value for \(k\) directly from the data: it inverts the chosen order’s \(Y(t)\) equation (see 3.4 Theory below) at one reference point, rather than always starting from an arbitrary constant. You can still impose your own starting value with k_depart=... if needed.

With your own file. Where your file lives decides how to read it, and the difference between “Google Colab” and “my own computer” matters here, even if both look like a notebook in a browser: on Colab, the notebook runs on a Google machine, which cannot see the files of your PC.

# On Google Colab: an upload button appears, pick your Excel file
kb = kbasic()
kb.read(colab=True)

# On your own PC: give the name (or the full path) of the file
kb = kbasic()
kb.read("measurements.xlsx")           # file in the same folder as the notebook
kb.read("C:/Users/me/data/kin.xlsx")   # or anywhere else, with its path

kb.read(colab=True) is a convenience built into kbasic. The same upload can be done in two explicit steps with the generic colab_upload() function (it returns the path of the uploaded file, which you can also pass to pandas):

from pyphyschemtools import colab_upload

path = colab_upload()    # upload button, returns the file path
kb.read(path)            # same as kb.read(colab=True)

3.4 Theory

kbasic’s three models are the special case \(\alpha=1\), \(Y_\infty=0\) of the general \(a(t)\) expressions in 2.1 above, with \(a_0\) renamed \(Y_0\):

  • Order 0: \(Y(t)=\max(Y_{0}-kt,\ 0)\)

  • Order 1: \(Y(t)=Y_{0}\exp(-kt)\)

  • Order 2: \(Y(t)=\dfrac{Y_{0}}{1+kt}\)

and correspondingly, the half-life (special case \(\alpha=1\), \(a_0=Y_0\) of 2.3):

  • Order 0: \(t_{1/2} = \dfrac{Y_{0}}{2k}\)

  • Order 1: \(t_{1/2} = \dfrac{\ln 2}{k}\)

  • Order 2: \(t_{1/2} = \dfrac{1}{k}\)

fit() computes and prints this \(t_{1/2}\) alongside \(k\) and the RMSE, and stores it in self.t_half.

Order 2 caveat. The true integrated second-order rate law is \(a(t) = a_{0}/(1+a_{0}kt)\) — note the extra \(a_0\) multiplying \(kt\) in the denominator (consistent with 2.1 for \(\alpha=1\)). kbasic’s order-2 model, \(Y(t)=Y_{0}/(1+kt)\), omits that factor. As a result, the \(k\) kbasic reports for order 2 is an apparent constant, \(k_{\mathrm{app}} = k_{\mathrm{true}} \times Y_{0}\), not the true molecular rate constant — and it is not comparable between two experiments run at different \(Y_0\). If you need the true \(k\) for order 2, divide kbasic’s result by \(Y_0\), or use KORD instead, which tracks \(a_0\) explicitly.


4. KORD: Kinetic Order of Reaction Determination

4.1 Quick Start

4.1.1 Basic use

from pyphyschemtools import KORD, get_ppct_data

# Load a bundled example file (experiment 1) and build the KORD instance in one call:
file = get_ppct_data("Kinetics/Test_Examples_VP.ods")
study = KORD.from_spreadsheet(file, exp_number=1)

study.get_best_order()      # fits orders 0, 1, 2 and reports the best one
study.plot_all_fits()       # visual comparison of the three fits

plot_all_fits() fits (or reuses, from study.results) all three orders and plots them together. An order already cached in study.results from an earlier fit() call is not re-fitted here, even if the fix_Y0/fix_Yinf passed to plot_all_fits() differ from the ones that produced that cached fit — your earlier, explicit choice is kept rather than silently overwritten. If that creates a mismatch (some orders fitted under different fix_Y0/fix_Yinf than the others), a warning table is printed, since comparing orders fitted under different constraints can be misleading. The same rule, and the same warning, apply to superpose_plots() below.

4.1.2 Specific fit

You can also fix \(Y_0\) (or \(Y_\infty\)) at a chosen value instead of letting the optimizer adjust it freely — fully explained in 4.2 Principle below:

# A better starting point than the raw first data point (e.g. because it's
# visibly noisy), used here as a hard constraint rather than a free guess:
study = KORD.from_spreadsheet(file, exp_number=1, Y0_guess=1.40)
study.simulate_plot()              # the three guesses (order 0, 1, 2) vs. the data
study.fit(order=1, fix_Y0=True)    # Y0 is held fixed at 1.40

# Changing the guess afterwards and fitting order 1 again works the same way,
# without re-creating study:
study.Y0_guess = 1.35
study.fit(order=1, fix_Y0=True)             # now fixed at 1.35
study.simulate_plot(order=1)                # only the order-1 guess vs. the data

simulate_plot(order=None, show_experimental=True, save_img=None) plots the current guess curve(s) — before or without fitting — against the measured data (shown by default; pass show_experimental=False to hide it). Use order=None (the default) to compare all three orders’ guesses at once, or order=0/1/2 to see just one.

Note that fit() itself never plots anything — it only computes and stores numbers in study.results[order]; plot_all_fits() (above) or simulate_plot() (just for the initial guesses, before any fit) are what draw a figure.

4.1.3 With your own file

As for kbasic (see 3.3 Quick Start), it depends on where the notebook runs. The file must follow the format described in 4.2.3 Input.

from pyphyschemtools import KORD

# On Google Colab: an upload button appears, pick your spreadsheet
study = KORD.from_spreadsheet(exp_number=1, colab=True)

# On your own PC: give the name (or the full path) of the file
study = KORD.from_spreadsheet("my_kinetics.xlsx", exp_number=1)

study.get_best_order()
study.plot_all_fits()

The two-step version also works, with colab_upload():

from pyphyschemtools import KORD, colab_upload

path = colab_upload()    # Colab only: upload button, returns the file path
study = KORD.from_spreadsheet(path, exp_number=1)

And a line that works in both environments:

import sys
study = KORD.from_spreadsheet("my_kinetics.xlsx", exp_number=1,
                              colab="google.colab" in sys.modules)

4.2 Principle

Scope and limitations. KORD only models the transformation of a single followed species, \(\alpha A \rightarrow \beta B\), with rate law \(v=k[A]^n\) (\(n \in \{0,1,2\}\)). This covers:

  • a genuine unimolecular transformation of A (most order-1 cases);

  • a genuine bimolecular reaction of A with itself, \(2A \rightarrow \text{products}\) (\(n=2\)), since there is still only one concentration, \([A]\), varying;

  • a mixed bimolecular reaction between two different species, \(A+B\rightarrow\ldots\), only in the pseudo-order approximation: one reactant held in large excess so its concentration stays essentially constant (the “isolation method”/Ostwald method, “flooding”, or dégénérescence de l’ordre in French). The apparent order and \(k\) obtained then describe the minority reactant only.

KORD does not correctly describe a true mixed second-order reaction where both \([A]_0\) and \([B]_0\) are comparable and both vary independently — that needs the (different, more complex) two-species integrated rate law, which this module does not implement.

\(\alpha\) and \(\beta\) are plain stoichiometric coefficients of \(\alpha A \rightarrow \beta B\), not “association” vs. “dissociation”: \(\alpha=2\) means 2 molecules of A are consumed per reaction event (e.g. \(2A\rightarrow P\)), \(\beta=2\) means each event produces 2 molecules of B (e.g. \(A\rightarrow 2B\), a fragmentation).

4.2.1 Experimental Measurements (\(Y_\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: \(Y_\mathrm{EXP}(t)\).

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

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

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

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

4.2.2 Theoretical Model (\(Y_\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{Y}^{[0]}(t)=\begin{cases} Y_{0}+\beta\dfrac{kt}{b_{\infty}}\left(Y_{\infty}-Y_{0}\right) & t\leq\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k}\\ Y_{\infty} & t>\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k} \end{cases}\end{split}\]

Standard Formula for Order 1:

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

Standard Formula for Order 2:

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

\(Y_\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, \(\hat{Y}_\mathrm{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: By default, the model fits the experimental data by adjusting the following:

  • Rate Constant: \(k\)

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

  • Initial Value: \(Y_{0}\) (While \(Y_{0}\) is measured, the algorithm also adjusts it by default 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 \(Y_\mathrm{EXP}\) values as \(Y_{0}\) and \(Y_{\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\), \(Y_{0}\) and \(Y_{\infty}\) are realistic to help the algorithm converge.

Letting the optimizer adjust \(Y_0\) freely can let it drift away from the actually measured starting point just to minimize the RMSE — which defeats the purpose of measuring it in the first place. Conversely, some experiments have a \(Y_\infty\) that is known on physical/chemical grounds (e.g. a non-absorbing product, \(Y_\infty = 0\)), and leaving it free can make the optimizer report a spurious non-zero plateau. fit() therefore accepts two independent boolean switches, fix_Y0 and fix_Yinf, to hold either one at its guess value instead of optimizing it (only \(k\) remains free when both are True — see the note on \(b_\infty\) below, which is never a free fit parameter for any order). BIC is computed using the actual number of free parameters, so model comparison across orders stays meaningful whichever switches are used (see 4.2.4 Model Selection below — fit() also stores an AIC for reference in study.results[order]['AIC'], but the printed verdict is based on BIC only).

Unless you pass Y0_guess/Yinf_guess yourself when creating the KORD instance, \(Y_0\)’s guess defaults to Y_exp[0] (the first measured point) and \(Y_\infty\)’s to Y_exp[-1] (the last). The guess and the fix switch are independent: giving your own Y0_guess does not force fix_Y0 one way or the other — it only changes which value is used, whether it ends up fixed or merely as the optimizer’s starting point.

fit(order=1, fix_Y0=False, fix_Yinf=False) never takes k_guess/Y0_guess/ Yinf_guess/binf_guess as arguments: it always reads the current self.k_guess, self.Y0_guess, self.Yinf_guess, self.binf_guess — set once at KORD(...)/from_spreadsheet(...) creation time, or changed later by assigning the attribute directly. See 4.1.2 above for an example.

There is no fix_binf switch, because \(b_\infty\) is never a free fit parameter in the first place. It is always derived from mass balance, \(b_\infty = a_0\,\beta/\alpha\), for every order — the same relation Order 1 already relied on. This is not a simplification: for Orders 0 and 2, if \(k\) and \(b_\infty\) were both left free, the model would depend on them only through a single combined ratio (\(\beta k/b_\infty\) for order 0, \(\beta/(b_\infty\alpha^2 k)\) for order 2). Infinitely many \((k, b_\infty)\) pairs then trace the exact same curve and give the exact same RMSE, so curve_fit would converge to an arbitrary point on that family — whichever one happens to sit closest to binf_guess — rather than to a unique, physically meaningful value. Deriving \(b_\infty\) removes that degeneracy: binf_guess still exists (used only to draw the guess curve in simulate_plot() before any fit is run), but fit() itself ignores it and always uses the mass-balance value, so k is the only quantity the data actually has to say about \(b_\infty\)’s combined effect — and it reports a binf value you can trust.

This buys physical consistency, but it also removes the fit’s ability to absorb noise or systematic error on that one point (e.g. mixing dead-time on the first point, or a \(Y_\infty\) assumed from “known” chemistry that is in fact slightly off): a wrong fixed value does not just affect that one parameter, it biases \(k\) (and whichever of \(Y_0\)/\(Y_\infty\)/\(b_\infty\) is still free) as the optimizer tries to compensate for it elsewhere.

One case is fixed by necessity rather than by choice: for order 1, \(\hat{Y}^{[1]}(t)=Y_{\infty}+\exp(-\alpha kt)(Y_{0}-Y_{\infty})\) does not depend on \(b_\infty\) at all, so there is nothing in the order-1 curve shape that could identify it — fit() always derives \(b_\infty\) from \(a_0\), \(\alpha\), \(\beta\) instead of optimizing it, for order 1 only.

4.2.3 Input

Data input is performed through a structured spreadsheet file (.xlsx, .ods, …), read by KORD.load_from_spreadsheet(file_path, exp_number, sheet_name=0) — or, more conveniently, by KORD.from_spreadsheet(...), which calls it for you (see 4.1 Quick Start). Within the chosen sheet, each experiment occupies a pair of columns (t, Y), laid out like this:

Row

Column \(2k{-}1\) (t)

Column \(2k\) (Y)

1

header for \(t\)

header for \(Y\)

2

[A]0

\([A]_0\) value

3

alpha

\(\alpha\) value

4

beta

\(\beta\) value

5+

\(t\) data

\(Y_\mathrm{EXP}\) data

where \(k\) is the experiment number (exp_number, 1-indexed). In the Column \(2k{-}1\) (t), [A]0, alpha and beta are unused labels, written in the table purely for clarity — only the Column \(2k\) (Y) cells in rows 2-4 are actually read. Several experiments can sit side by side in the same sheet this way, each in its own column pair; load_from_spreadsheet returns, for one experiment: t, Y, (label_t, label_Y), (a0, alpha, beta).

As a sanity check, load_from_spreadsheet inspects rows 2-4 of the t column (which should be blank or a text label, never real data at this stage): if it finds a genuine number there instead, it prints a warning reminding you of the expected format, since this usually means the data doesn’t follow the layout above (e.g. actual \((t,Y)\) data starting at row 2 instead of row 5).

4.2.4 Model Selection: get_best_order() and \(\Delta\)BIC

get_best_order() fits orders 0, 1 and 2 (any order not already in study.results) and prints a conclusion, in two separate steps:

  1. Best model: the order with the lowest RMSE (plain goodness of fit).

  2. Final Statistical Verdict: a confidence label on how clearly the data favor one order over the others, based on the BIC (Bayesian Information Criterion) rather than the RMSE. BIC trades off goodness of fit against the number of free parameters \(p\) actually optimized (fewer free parameters is rewarded — this matters more once you can fix \(Y_0\)/\(Y_\infty\) with fix_Y0/fix_Yinf, since that changes \(p\)):

    \[BIC = n\ln(RMSE^{2}) + p\ln(n)\]

    where \(n\) is the number of experimental points (the same for every order, since it’s the same dataset) and \(p\) is the number of parameters actually optimized for that order — normally 3 for order 1 (\(k\), \(Y_0\), \(Y_\infty\); \(b_\infty\) is fixed) and 4 for orders 0 and 2 (\(k\), \(Y_0\), \(Y_\infty\), \(b_\infty\)), one less for each of \(Y_0\)/\(Y_\infty\) held fixed via fix_Y0/fix_Yinf.

    fit()’s printed GUESS/OPTIM block also shows an AIC (Akaike Information Criterion) value alongside BIC, for reference:

    \[AIC = n\ln(RMSE^{2}) + 2p\]

    Same \(n\) and \(p\) as BIC above; the only difference is the penalty for extra parameters (\(2p\) instead of \(p\ln(n)\)), which is milder — AIC penalizes model complexity less harshly than BIC does once \(n\) is more than a handful of points. study.results[order]['AIC'] stores it, but the printed verdict below is based on BIC only — AIC is kept for reference, not used in get_best_order()’s conclusion.

    The three orders (0, 1, 2) are ranked by their BIC (lowest = best), and

    \[\Delta BIC = BIC(\text{2}^{\text{nd}}\text{ best}) - BIC(\text{best})\]

    is the strength of evidence for the best-BIC order over its closest rival. The verdict label follows the standard scale from Kass, R. E., & Raftery, A. E. (1995), “Bayes Factors”, J. Am. Stat. Assoc., 90(430), 773–795 — see also the Bayesian information criterion and Bayes factor Wikipedia pages (ΔBIC approximates twice the log Bayes factor between the two models):

    \(\Delta\)BIC

    Verdict

    < 2

    Weak / Inconclusive

    2–6

    Positive

    6–10

    Strong

    > 10

    Decisive

    Example: Model Selection Confidence: Decisive, ΔBIC (Best [order 1] vs 2nd Best [order 2]): 359.15 means order 1 beats order 2 by 359 BIC points — an overwhelming margin, far past the “decisive” threshold of 10: the data leave essentially no doubt that order 1 is the right kinetic order.

    Note: the “Best model” (step 1, by RMSE) and the two orders compared in the verdict (step 2, by BIC) are usually the same, but are determined independently and need not coincide exactly, especially when parameters are fixed asymmetrically across orders.


4.3 Theoretical Model

\(Y_\mathrm{THEO}(t)\) is built directly from the integrated rate laws of section 2: it is a linear combination of the reactant expression \(a(t)\) and the product expression \(b(t)\) introduced there, under the same assumptions (single-component, total, closed, homogeneous, isochoric reaction):

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

Compte tenu des équations de \(a(t)\) et \(b(t)\) pour les ordres 0, 1 et 2, il vient :

Standard Formula for Order 0:

\[\begin{split}\hat{Y}^{[0]}(t)=\begin{cases} Y_{0}+\beta\dfrac{kt}{b_{\infty}}\left(Y_{\infty}-Y_{0}\right) & t\leq\dfrac{a_{0}}{\alpha k}=\dfrac{b_{\infty}}{\beta k}\\ Y_{\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{Y}^{[1]}(t)=Y_{\infty}+\exp\left(-\alpha kt\right)\left(Y_{0}-Y_{\infty}\right)\]

Standard Formula for Order 2:

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

4.4 Advanced use

4.4.1 Comparing several fits

superpose_plots(studies, order=1, show_experimental=True, labels=None, fix_Y0=False, fix_Yinf=False, save_img=None) is a standalone function (not a KORD method, since it takes a list of instances) that overlays the fitted curve of one chosen order — and, by default, each study’s data — across several KORD studies on the same graph. Typical use: the same data fitted under different fix_Y0/fix_Yinf settings, to see directly how that choice moves the fitted curve.

Being standalone, it is called as superpose_plots(...), imported separately (from pyphyschemtools.kinetics import superpose_plots) — not as KORD.superpose_plots(...), which raises an AttributeError since KORD has no such method.

study.copy() returns an independent copy — data, guesses and cached results are duplicated, not shared, so fitting one does not affect the other — which is the natural way to get two variants of the same study to compare:

from pyphyschemtools.kinetics import superpose_plots

study_free = KORD.from_spreadsheet(file, exp_number=1)
study_fixed = study_free.copy()

study_free.fit(order=1, fix_Y0=False)   # Y0 optimized
study_fixed.fit(order=1, fix_Y0=True)   # Y0 held fixed at its guess value

superpose_plots([study_free, study_fixed], order=1)

Each study’s legend entry is tagged automatically (free fit, Y0 fixed, Yinf fixed, or both), based on the actual fit found in study.results. If an order isn’t fitted yet for a given study, it is fitted now with fix_Y0/fix_Yinf; if it’s already cached under different settings, the cache is kept as-is (same rule as plot_all_fits(), see 4.1.1 above) and a warning is printed for that study.

4.4.2 from_spreadsheet vs load_from_spreadsheet

from_spreadsheet(file_path, exp_number, sheet_name=0, show_data=True, colab=False, **kwargs) is a convenience constructor: it reads the experiment with load_from_spreadsheet (below) and forwards headers, a0, alpha, beta to KORD() for you — any extra keyword (k_guess, Y0_guess, verbose, …) is passed straight through to KORD.__init__. The returned study is a perfectly ordinary KORD instance: all its attributes (study.k_guess, study.Y0_guess, study.a0, …) are set exactly as they would be from a direct KORD(...) call. file_path can be any local path ("data/exp.ods", get_ppct_data(...) is just one way to point at a bundled example file — your own files work the same way), or, on Google Colab, pass colab=True and omit file_path: an upload button appears and the chosen file is read instead (same mechanism as kbasic.read(colab=True)). show_data=True (the default) also prints the usual summary table.

from_spreadsheet is what you should reach for by default — it’s what every example in this doc uses. The lower-level load_from_spreadsheet (which it calls internally) stays available separately, and is worth using directly when you need to inspect, filter or correct the loaded data or parameters before creating the KORD instance — e.g. overriding a stoichiometry value read from the file, dropping an outlier point, or feeding the same raw \((t, Y)\) into kbasic instead:

t, Y, headers, parameters = KORD.load_from_spreadsheet(file, exp_number=1)
# ... inspect / fix t, Y, parameters here if needed ...
study = KORD(t, Y, headers, a0=parameters[0], alpha=parameters[1], beta=parameters[2])

4.4.3 Reading a different sheet / experiment

load_from_spreadsheet(file_path, exp_number, sheet_name=0, show_data=True) (formerly named load_from_excel — same method; it reads with pandas.read_excel, so it already worked on .ods files as well as .xlsx, and the old, Excel-specific name was misleading. load_from_excel still works, as a deprecated alias.) reads one sheet (sheet_name, by index or by name — the first sheet by default) and, within that sheet, picks the column pair identified by exp_number (1 for the first pair of columns, 2 for the next pair, etc. — see the data format in 4.2.3 Input above). from_spreadsheet takes the exact same sheet_name/exp_number arguments and forwards them:

  • If every experiment lives in its own pair of columns within the same sheet, just change exp_number (exp_number=2 for the second experiment).

  • If each experiment instead lives on its own sheet/tab of the workbook, pass sheet_name explicitly, by index or by name, e.g.:

    study = KORD.from_spreadsheet(file, exp_number=1, sheet_name=1)
    # or, by sheet name:
    study = KORD.from_spreadsheet(file, exp_number=1, sheet_name="Feuille2")
    

5. ReactionNetwork: general reaction networks

5.1 Purpose and scope

kbasic and KORD both rely on closed-form integrated rate laws, valid only for a single reactant transforming into a single product (\(\alpha A \rightarrow \beta B\)), of order 0, 1 or 2 (see 2. Integrated rate laws). That covers a lot of real experiments, but not every mechanism a student or a researcher might need to fit:

  • Parallel (competitive) reactions: \(A \rightarrow B\) and \(A \rightarrow C\) at the same time, with their own rate constants \(k_1\), \(k_2\).

  • Consecutive reactions: \(A \rightarrow B \rightarrow C\), where \(B\) is an intermediate that builds up, then decays — its concentration goes through a maximum (the classic setting for introducing the quasi-steady-state approximation, QSSA).

  • Reversible reactions: \(A \rightleftharpoons B\), which relax toward an equilibrium set by the ratio of the forward and backward rate constants, not all the way to \(A=0\).

  • Any network combining several of the above.

None of these have a simple closed-form solution in general. ReactionNetwork drops the closed-form restriction entirely: it builds the system of ODEs for an arbitrary set of elementary reactions straight from mass-action kinetics (a reaction’s rate is \(k\) times the product of its reactants’ concentrations, each raised to its own stoichiometric coefficient), integrates it numerically with scipy.integrate.solve_ivp, and fits the rate constant(s) against experimental data the same way KORD does — a measured signal as a linear combination of concentrations, \(Y_\mathrm{EXP}(t) = \sum_i \eta_i\, C_i(t)\) (see 4.2.1 Experimental Measurements).

This is a genuine generalization: kbasic/KORD’s orders 0/1/2 are just the special case of a single \(A \rightarrow B\) reaction, and the quasi-steady-state approximation can now be checked numerically against the exact solution of a consecutive network, instead of only illustrated on a closed-form special case.

Mass action is the standard assumption for an elementary step; it is not automatically valid for an overall, multi-step reaction written as a single line (the same caveat KORD’s 4.2 Principle raises for pseudo-order kinetics) — build the actual elementary steps of the mechanism, not a shortcut lumped equation, if you want physically meaningful rate constants.

5.2 Quick Start

Four steps, in order: read the experimental data, declare the reactions, set the initial concentrations, then either fit() against the data or simulate()/plot() directly.

Step 1: read the data. fit() just needs two plain arrays, t_exp (time) and Y_exp (the measured quantity), so any spreadsheet can be read with pandas. Start with the bundled example file, which works everywhere (Colab or your own computer):

import pandas as pd
from pyphyschemtools import get_ppct_data

file = get_ppct_data("Kinetics/consecutive_fit_data.ods")
df = pd.read_excel(file, engine="odf")   # .ods needs the odfpy package
display(df)
t_exp = df["Time / min"].values
Y_exp = df["Y"].values           # the intermediate, as actually observed

To use your own file (two columns: time, then the measured quantity), only the first lines change. The rest of the example is identical:

# On Google Colab: an upload button appears, pick your file
from pyphyschemtools import colab_upload
file = colab_upload()

# On your own PC: give the name (or the full path) of the file
file = "my_kinetics.xlsx"

df = pd.read_excel(file)          # for an .ods file: engine="odf"
display(df)
t_exp = df["Time / min"].values
Y_exp = df["Y"].values           # the intermediate, as actually observed

Steps 2 to 4: build the network and fit.

from pyphyschemtools import ReactionNetwork

net = ReactionNetwork()
net.add_reaction("A -> B", k_guess=0.5)
net.add_reaction("B -> C", k_guess=0.1)
net.set_initial_conditions({"A": 1.0, "B": 0.0, "C": 0.0})

# If only B is measured (e.g. it's the one colored/absorbing species):
net.fit(t_exp, Y_exp, observed_species="B")
net.plot(t_exp, Y_exp, time_unit="min")   # all three species + the experimental overlay
net.summary()                             # fitted k1, k2 for each reaction

The bundled file tracks the intermediate of an \(A\rightarrow I\rightarrow P\) mechanism, which is why it is declared here as B (the middle species); the time is in minutes, hence time_unit="min". 5.10 Worked example 2 runs the same fit with the species named \(A\), \(I\), \(P\).

plot() draws every species by default; pass species=[...] to zoom in on a subset — handy for a reactive intermediate whose concentration is orders of magnitude below the reactant/product, especially combined with log_scale=True:

net.plot(species=["A", "B"], log_scale=True, t_max=20, time_unit="s")

Each name is checked against the network’s actual species first, so a typo (or a species that was never declared via add_reaction()) raises a clear error listing the known ones, instead of silently plotting nothing for it.

No fit needed at all if you already know the rate constants and just want to see how the concentrations evolve: simulate(t) integrates the ODE system with the guesses given to add_reaction() — or the fitted values, once fit() has been called — and returns a {species: concentration array} dict:

import numpy as np
t = np.linspace(0, 20, 200)
C = net.simulate(t)            # {"A": array(...), "B": array(...), "C": array(...)}

copy() returns an independent deep copy of the whole network (reactions, initial conditions, any fitted result), e.g. to fit the same network twice under different conditions — different weights, a different subset of the data — without having to declare every reaction a second time, and without one fit() call overwriting the other’s results.

plot()/plot_qssa() save the figure to disk, in addition to showing it, with save_img="path/to/figure.png" (any extension matplotlib’s savefig understands — png, pdf, svg…); both ask before overwriting a file that already exists. Pass time_unit="s" (or "min", "h", "yr"…) to label the x-axis “Time / s” — see 5.3 Units for why this is just a label and not an actual unit conversion.

5.3 Reaction syntax

add_reaction(equation, k_guess=..., kf_guess=..., kr_guess=..., order=..., order_back=...) parses a plain chemical-equation string:

  • Species are single-word names — letters/digits/underscore, Unicode accents included (A, B2, H2O, ethylene, éthylène…). A species name cannot contain a space, so a multi-word compound needs a short alias first, exactly as on paper: A = ethylene, B = cyclobutane, then net.add_reaction("2 A -> B", ...).

  • Every name is normalized on parsing, so the same compound is always recognized as the same species no matter how it’s typed across different add_reaction() calls, case-insensitively — "ethylene", "Ethylene", "ETHYLENE" and "éthylène" all resolve to the single species “Ethylene” (accents are stripped, and the very first spelling seen becomes the one used for the rest of the network). This matching is purely about recognizing the same name typed differently — it never lowercases a letter you actually typed in uppercase, precisely so that a short formula with no digit in it, like "NO" (nitric oxide), "CO", "OH", "HCl" or "HCN", is never mistaken for a spelled-out word and mangled into something like "No" (indistinguishable from the element symbol for Nobelium). So "2 ethylene -> cyclobutane" and "Cyclobutane -> 2 ETHYLENE" are recognized as the forward/backward of the very same reaction between the very same two species, while "N2O5 -> NO2 + NO3" keeps "NO2"/"NO3" exactly as written, however later reactions spell them.

  • Terms are separated by +, with an optional leading integer stoichiometric coefficient: "A + 2 B -> C", or "2 ethylene -> cyclobutane" directly if you’d rather not alias.

  • -> for an irreversible reaction (give k_guess); <=> for a reversible one (give kf_guess/kr_guess — each defaults to 1.0 if omitted, and kf_guess also accepts the value passed as k_guess, for convenience). Reversible reactions are fully supported, with any kinetic order (see below) on either side.

  • Any species not seen in an earlier call is added to the network automatically, in order of first appearance — no separate species declaration needed.

  • All rate constants are constrained to be \(\geq 0\) (physical consistency, exactly like \(k\)/\(b_\infty\) in KORD.fit()).

  • Kinetic order vs. stoichiometry: by default, the rate law is elementary mass action — the exponent on each reactant (product, for the backward direction) equals its stoichiometric coefficient. Pass order={"A": 1.5} (forward) and/or order_back={"B": 2} (backward, reversible only) to override this species by species, when the actual kinetic order differs from the written stoichiometry (the same caveat 4.2 Principle raises for KORD’s pseudo-order case) — e.g. a reversible reaction that is first order forward but second order backward: net.add_reaction("A <=> 2 B", kf_guess=0.5, kr_guess=0.2, order_back={"B": 2}) (this one actually matches the stoichiometry, so order_back isn’t even needed here — it’s for when it doesn’t match).

5.4 Units of rate constants

ReactionNetwork is entirely unit-agnostic: t, C0 and every rate constant are just numbers — there is no internal unit system, no conversion, and nothing to configure. You choose the units once (e.g. mol·L⁻¹ for concentration and s for time) and keep every input in that same system; the output comes out consistently in it too.

Given that, the unit a rate constant carries is fixed by the reaction’s overall kinetic order \(n\) (the sum of the forward exponents — the stoichiometric coefficients by default, or the order dict when it’s been overridden), from the requirement that the rate itself always has units of concentration/time:

\[[k] = \text{(concentration)}^{1-n}\cdot\text{(time)}^{-1}\]
  • order 1 (e.g. "A -> B"): \([k]=\text{time}^{-1}\) (e.g. s⁻¹) — same as kbasic’s order-1 case.

  • order 2 (e.g. "A + B -> C" or "2 A -> B"): \([k]=\text{concentration}^{-1}\cdot\text{time}^{-1}\) (e.g. L·mol⁻¹·s⁻¹).

  • order 0: \([k]=\text{concentration}\cdot\text{time}^{-1}\).

A reversible reaction’s \(k_f\) and \(k_r\) don’t have to share the same unit — each follows this rule from its own side’s order, e.g. "A <=> 2 B" has \(k_f\) in time⁻¹ (order 1 forward) but \(k_r\) in concentration⁻¹·time⁻¹ (order 2 backward, unless overridden via order_back).

Since the module itself carries no unit label, plot()/plot_qssa() accept time_unit="s" (or "min", "h", "yr"…) purely to annotate the x-axis as “Time / s” — this labels the figure only, it does not check or convert anything, so it’s on you to make sure time_unit actually matches the time unit t/t_exp and the rate constants were expressed in.

5.5 Parallel, consecutive and reversible reactions

Parallel reactions (\(A\rightarrow B\), \(A\rightarrow C\), with \(k_1\), \(k_2\)): the classic result is that the branching ratio \([B]/[C]\) equals \(k_1/k_2\) at every instant (not just at completion), since both channels drain \(A\) at rates proportional to their own \(k\):

net = ReactionNetwork()
net.add_reaction("A -> B", k_guess=0.5)
net.add_reaction("A -> C", k_guess=0.2)
net.set_initial_conditions({"A": 2.0, "B": 0.0, "C": 0.0})

Consecutive reactions (\(A\rightarrow B\rightarrow C\)): \([B]\) rises then falls, peaking at \(t_\mathrm{max}=\dfrac{\ln(k_2/k_1)}{k_2-k_1}\) (the Bateman equations give the exact closed form for this particular two-step case — ReactionNetwork’s numerical solution matches it to \(\sim 10^{-9}\)). This is the standard setting to introduce the quasi-steady-state approximation (QSSA): when \(k_2\gg k_1\), \(B\) is consumed almost as fast as it forms, so \(d[B]/dt\approx 0\) is a good approximation after a short induction period — checkable directly here by comparing net.simulate(t)['B'] for \(k_2\gg k_1\) against the QSSA prediction \([B]_\mathrm{QSSA}\approx \frac{k_1}{k_2}[A](t)\).

net = ReactionNetwork()
net.add_reaction("A -> B", k_guess=0.6)
net.add_reaction("B -> C", k_guess=0.15)
net.set_initial_conditions({"A": 1.5, "B": 0.0, "C": 0.0})

Reversible reactions (\(A\rightleftharpoons B\)): the system relaxes toward an equilibrium with \([B]_\mathrm{eq}/[A]_\mathrm{eq}=k_f/k_r\) (not to \([A]=0\)) — ReactionNetwork includes the backward rate in \(A\)’s and \(B\)’s ODEs automatically as soon as a reaction is declared with <=>:

net = ReactionNetwork()
net.add_reaction("A <=> B", kf_guess=0.8, kr_guess=0.3)
net.set_initial_conditions({"A": 1.0, "B": 0.0})

5.6 Fitting rate constants

fit(t_exp, Y_exp, weights=...) or the observed_species="X" shortcut (equivalent to weights={"X": 1.0}) fits every reaction’s rate constant(s) by nonlinear least squares, wrapping the ODE integration inside scipy.optimize.curve_fit exactly as KORD.fit() wraps its closed-form model. weights={...} is for a signal mixing several species, e.g. a UV-Vis absorbance both \(A\) and \(B\) contribute to: weights={"A": eta_A, "B": eta_B}.

The returned dict (also stored in net.results) has the same shape as KORD.fit()’s: {'k': {param_name: value, ...}, 'RMSE', 'R2', 'AIC', 'BIC', 'weights'} — 'k' has one entry per irreversible reaction (k1, k2, …, numbered by the order reactions were added), two per reversible reaction: k{i} for the forward constant and k-{i} for the reverse one — the classic \(k_1\)/\(k_{-1}\) notation for the two directions of the same step i (e.g. a reversible reaction added first gives k1/k-1; the next reaction added, even if irreversible, continues at k2). The fitted values are also stored in net.k_fit, so a later simulate() or plot() call with no k_values argument uses them automatically, and summary() prints each reaction with its fitted (or, before any fit() call, guessed) rate constant(s).

5.7 Checking the overall equation (bilan)

For a multi-step mechanism, overall_equation() sums the stoichiometry of every declared reaction (forward direction as written, each counted once) and cancels out whatever appears on both sides — typically the intermediate(s) — to get the net equation the whole sequence implies:

net = ReactionNetwork()
net.add_reaction("A -> I", k_guess=0.5)   # I: reactive intermediate
net.add_reaction("I -> P", k_guess=0.1)
print(net.overall_equation())             # "A -> P"  (I cancels out)

This is an important sanity check on a mechanism: the overall equation it implies should match the balanced equation you started from. If it doesn’t, either a step is missing/wrong, or a stoichiometric coefficient is off — exactly the kind of mistake this check catches before any fitting happens. Note that a reversible reaction contributes its forward stoichiometry only (this is about the mechanism’s bookkeeping across the whole sequence, not about net flux at a given time, which depends on the actual rate constants and concentrations — see 5.7 Quasi-steady-state check for that).

5.8 Quasi-steady-state check (QSSA)

For a reactive intermediate (e.g. \(B\) in \(A\rightarrow B\rightarrow C\)), the quasi-steady-state approximation (QSSA) assumes \(d[B]/dt\approx 0\) once \(B\) is being consumed about as fast as it forms — valid when \(k_2\gg k_1\), but not obviously so otherwise. qssa_check(species, t) answers this numerically, without needing a closed-form solution: at each time in t, it compares the net rate of change of species to its gross rate — the sum of the absolute value of every reaction’s individual contribution to it (production and consumption both counted positive, so they can’t cancel each other the way they do in the net rate):

\[\text{QSSA ratio}(t) = \frac{|d[\text{species}]/dt|}{\sum_j |\text{contribution}_j(t)|}\]

The numerator is the first derivative of the concentration (in absolute value) — exactly \(d[\text{species}]/dt\), the same net rate simulate() integrates. What makes it a ratio rather than just the derivative is the denominator: the gross rate, i.e. how much is flowing through species in total (production and consumption summed as positive numbers, so a large forward flux and a large backward flux don’t cancel there the way they do in the numerator). So the ratio asks “how small is the net change compared to the traffic actually going through this species?” — a small \(|d[B]/dt|\) on its own doesn’t mean much if nothing is happening at all, but a small \(|d[B]/dt|\) next to a large gross flux is the real signature of a species sitting at quasi-steady state.

A ratio near 0 means production and consumption are nearly balanced — the QSSA holds; a ratio near 1 means species is still mostly accumulating or depleting on its own.

net = ReactionNetwork()
net.add_reaction("A -> B", k_guess=0.05)
net.add_reaction("B -> C", k_guess=5.0)     # k2 >> k1
net.set_initial_conditions({"A": 1.0, "B": 0.0, "C": 0.0})

t = np.linspace(0.01, 20, 40)
ratio = net.qssa_check("B", t)   # << 1 here (after a short induction period):
                                 # the QSSA is a good approximation for B

With k_guess=0.5 for both steps instead (so \(k_2\sim k_1\)), the same check gives a ratio climbing well above 0.5 — the QSSA clearly does not hold, exactly as expected since \(B\) never gets consumed fast enough to stay near steady state.

5.9 Worked example 1: stratospheric ozone decomposition (QSSA)

A textbook mechanism that ties every feature above together: the classical two-step scheme for ozone decomposition,

\[\mathrm{O_3}\rightleftharpoons \mathrm{O_2}+\mathrm{O}\qquad(k_{f1},\,k_{r1},\text{ fast})\]
\[\mathrm{O}+\mathrm{O_3}\rightarrow 2\,\mathrm{O_2}\qquad(k_2,\text{ slow})\]

with atomic oxygen \(\mathrm{O}\) as a short-lived intermediate. \(\mathrm{O_2}\) is given a sizeable initial concentration here (as it would have in a real stratospheric mixture) — it has to, for the reverse of the first step to have anything to act on from the very start; starting it at exactly 0 instead leaves the backward rate \(k_{r1}[\mathrm{O_2}][\mathrm{O}]\) pinned near 0 until \(\mathrm{O_2}\) builds up on its own, so the pre-equilibrium needs an induction period far longer than the one shown below:

net = ReactionNetwork()
net.add_reaction("O3 <=> O2 + O", kf_guess=1.0, kr_guess=100.0)
net.add_reaction("O + O3 -> 2 O2", k_guess=50.0)
net.set_initial_conditions({"O3": 1.0, "O2": 1.0, "O": 0.0})

print(net.overall_equation())   # "2 O3 -> 3 O2"  (O cancels: it's the
                                 #  intermediate, consistent with the
                                 #  textbook balanced equation)

Checking that \(\mathrm{O}\) is indeed a good QSSA candidate here — the whole point of calling the first step “fast” and the second “slow” — is exactly what qssa_check()/plot_qssa() are for:

import numpy as np
t = np.linspace(1e-5, 8, 300)

ratio = net.qssa_check("O", t)
# ratio ~ 1 only for a brief induction period (t << 0.03), then drops
# below 1% and stays there for the rest of the decomposition: the QSSA
# for atomic oxygen is excellent once that short transient is over.

net.plot_qssa("O", t, threshold=0.05, time_unit="s")   # two-panel diagnostic plot
net.plot(species=["O3", "O"], log_scale=True, t_max=8, time_unit="s")  # zoom on
                                                                         # the trace intermediate

This is also a good illustration of why the induction period matters when choosing initial conditions for a QSSA demonstration: with \(k_{f1}\), \(k_{r1}\) both very large and \(\mathrm{O_2}(0)=0\) instead, qssa_check() would correctly report the approximation failing for a much longer stretch, not because the mechanism is wrong but because the reverse step has nothing to react with yet — a reminder that the QSSA is a statement about rates staying balanced, not simply about \(k_{r1}\gg k_{f1}\).

5.10 Worked example 2: consecutive reactions with a fit

A second worked example, this time exercising fit() rather than qssa_check(): the classic two-step consecutive mechanism \(A\rightarrow I\rightarrow P\), where only the intermediate \(I\) is experimentally observed (e.g. a UV-Vis absorbing species, as in 4.2 Experimental Measurements for KORD) — the exact setting observed_species= is for.

ReactionNetwork has no built-in read()/load_from_excel() of its own (unlike kbasic/KORD) — not because it can’t be done, but because fit()/simulate() just need two plain arrays t_exp, Y_exp, so reading whatever file they come from is a two-line pandas call, with no dedicated method needed: pandas.read_excel() reads .xlsx as well as .ods (LibreOffice Calc’s native format — needs the odfpy package) the same way, so here the data (one \(A\rightarrow I\rightarrow P\) “experiment”, with \([I]\) tracked over time) is loaded straight from a two-column spreadsheet, consecutive_fit_data.ods, exactly as a real lab measurement would be:

import pandas as pd

df = pd.read_excel("consecutive_fit_data.ods", engine="odf")
t_exp = df["Time / min"].values
Y_exp = df["Y"].values           # the intermediate [I], as actually observed

net = ReactionNetwork()
net.add_reaction("A -> I", k_guess=1.0)   # deliberately uninformed guesses
net.add_reaction("I -> P", k_guess=1.0)
net.set_initial_conditions({"A": 1.0, "I": 0.0, "P": 0.0})

results = net.fit(t_exp, Y_exp, observed_species="I")
net.plot(t_exp, Y_exp, time_unit="min", save_img="./fig_examples/Kinetics/consecutive_fit.png")
net.summary()

The rate constants used to actually generate consecutive_fit_data.ods are not needed to run this fit — that’s the point: fit() recovers them from the data alone, starting from guesses that give it no head start. 5.11 Worked example 3 shows exactly how that file was produced, for anyone who wants to check the fit against the true values or generate a similar file for a different mechanism.

Unlike the ozone example, there’s no reversible step and no QSSA claim here — it’s a plain nonlinear least-squares fit of two rate constants against one observed species, the same workflow as net.fit(t_exp, Y_exp, observed_species="B") in 5.2 Quick Start.

A genuine identifiability trap, not a code bug: fitting the exact same data with observed_species="P" instead of "I" converges just as well (comparable RMSE) but can recover \(k_1\approx 0.15\), \(k_2\approx 0.54\) — the two rate constants swapped. This isn’t curve_fit failing: the Bateman closed form for the final product,

\[[P](t) = a_0\left(1+\frac{k_2e^{-k_1t}-k_1e^{-k_2t}}{k_1-k_2}\right),\]

is exactly symmetric under exchanging \(k_1\leftrightarrow k_2\) (swap them and \([P](t)\) is unchanged, for every \(t\)) — the final product’s time profile carries no information about which of the two steps is the fast one, only about the unordered pair \(\{k_1, k_2\}\). curve_fit is free to land on either equally-good solution depending on the starting guesses. It’s the intermediate \([I](t)\) — which rises then falls, asymmetrically in \(k_1\) and \(k_2\) — that breaks this symmetry and pins down the correct assignment; whenever only the final product can realistically be followed, this is a hard identifiability limit of the data itself, not something a different k_guess or a tighter fit can get around.

5.11 Worked example 3: generating a synthetic kinetics dataset

This is how consecutive_fit_data.ods, read blind in 5.10 Worked example 2, was actually produced: a network with known, “true” rate constants simulates noise-free concentrations, Gaussian noise is added to \([I]\) only (mimicking real measurement noise on the one species actually followed), and the result is written out to a two-column spreadsheet — the same logic used elsewhere in this module to validate KORD.fit() against synthetic data, just saved to a file instead of being fit immediately in the same script.

import numpy as np
import pandas as pd

np.random.seed(0)   # reproducible noise

true_net = ReactionNetwork(verbose=False)
true_net.add_reaction("A -> I", k_guess=0.5)     # true k1 = 0.5 min^-1
true_net.add_reaction("I -> P", k_guess=0.15)    # true k2 = 0.15 min^-1
true_net.set_initial_conditions({"A": 1.0, "I": 0.0, "P": 0.0})

t_exp = np.linspace(0.5, 25, 18)
Y_exp = true_net.simulate(t_exp)["I"] + np.random.normal(0, 0.01, size=t_exp.shape)

df = pd.DataFrame({"Time / min": t_exp, "Y": Y_exp})
df.to_excel("consecutive_fit_data.ods", index=False, engine="odf")

A note on naming, for a reversible reaction: add_reaction() already names a reversible step’s rate constants the standard textbook way, \(k_1\) forward and \(k_{-1}\) backward (not \(k_{f1}\)/\(k_{r1}\)) — e.g. net.add_reaction("A <=> B", kf_guess=0.8, kr_guess=0.3) reports as k1=0.8, k-1=0.3 in summary() and in results['k'], and a second reversible reaction added afterwards would be k2/k-2, and so on, numbered in the order the reactions were declared (irreversible and reversible steps share the same counter, so "A -> B" then "B <=> C" gives k1, then k2/k-2).

API reference

class pyphyschemtools.kinetics.KORD(t_exp=None, Y_exp=None, headers=('Time / s', 'Y'), a0=1.0, alpha=1.0, beta=1.0, k_guess=None, Y0_guess=None, Yinf_guess=None, binf_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.

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

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

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

  • binf_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 Y_exp arrays read in the excel file

Y0_theo(t, k, Y0, Yinf, binf)[source]

Model for Order 0 kinetics

Y1_theo(t, k, Y0, Yinf)[source]

Model for Order 1 kinetics

Y2_theo(t, k, Y0, Yinf, 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.

copy()[source]

FR — Retourne une copie indépendante de cette étude KORD : les données, les guesses et les résultats déjà en cache (self.results) sont dupliqués, pas partagés. Un fit() ultérieur sur la copie (ou sur l’original) ne modifie pas l’autre.

Utile pour comparer, par exemple, un ajustement avec Y0 figé et un ajustement libre sur les mêmes données, sans que l’un écrase le cache de l’autre (voir superpose_plots()) :

>>> study_free = KORD.from_spreadsheet(file, exp_number=1)
>>> study_fixed = study_free.copy()
>>> study_fixed.fit(order=1, fix_Y0=True)
>>> superpose_plots([study_free, study_fixed], order=1)

EN — Returns an independent copy of this KORD study: the data, the guesses, and any results already cached (self.results) are duplicated, not shared. A later fit() on the copy (or on the original) does not affect the other.

Useful to compare, e.g., a fit with Y0 frozen against a free fit of the same data, without either one overwriting the other’s cache (see superpose_plots()):

>>> study_free = KORD.from_spreadsheet(file, exp_number=1)
>>> study_fixed = study_free.copy()
>>> study_fixed.fit(order=1, fix_Y0=True)
>>> superpose_plots([study_free, study_fixed], order=1)
fit(order=1, fix_Y0=False, fix_Yinf=False)[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 optimize the rate constant (k), and - unless fixed, see below - the initial and final physical property values (Y0, Yinf). The final product concentration (binf) is never a free fit parameter: it is always derived from mass balance as binf = a0*beta/alpha (see the Notes below for why). Physical constraints are applied via parameter bounds to ensure k remains positive.

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

The starting guesses (k_guess, Y0_guess, Yinf_guess) are NOT passed here: they are read from the attributes set when the KORD instance was created (self.k_guess, self.Y0_guess, self.Yinf_guess). To change a guess, set it on the instance (or pass it to KORD(…) / KORD.from_spreadsheet(…) in the first place) before calling fit(), e.g. study.Y0_guess = 1.40 then study.fit(order=1, fix_Y0=True).

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

  • fix_Y0 (bool, optional) – If True, Y0 is held fixed at Y0_guess (normally the first measured value) instead of being optimized. Use this when you trust the measured starting point and want to stop the fit from drifting it away to improve the apparent fit. Defaults to False (Y0 is optimized, as before).

  • fix_Yinf (bool, optional) – If True, Yinf is held fixed at Yinf_guess instead of being optimized. Use this when the final value is known on physical/chemical grounds (e.g. a non-absorbing product, Yinf = 0) and you don’t want the optimizer to report a spurious non-zero plateau. Defaults to False (Yinf is optimized, as before).

Returns:

A dictionary containing the optimized parameters (‘k’, ‘Y0’,

’Yinf’), the derived final product concentration (‘binf’), and statistical metrics (‘RMSE’, ‘R2’, ‘t_half’). Returns None if optimization fails to converge.

Return type:

dict

Notes

  • binf is never fitted: it is always derived as binf = a0*beta/alpha, for every order, the same formula Order 1 already relied on. This is not an approximation to simplify the model — it is required for k and binf to be individually meaningful. For Orders 0 and 2, if k AND binf were both left free, the model’s shape would depend on them only through one combined ratio (beta*k/binf for order 0, beta/(binf*alpha**2*k) for order 2): infinitely many (k, binf) pairs then give an identical curve and an identical RMSE, so curve_fit would converge to an arbitrary point on that family (whichever one is closest to binf_guess) rather than to a unique, physically meaningful answer. Deriving binf from mass balance removes that degeneracy.

  • fix_Y0 / fix_Yinf let you turn off the optimization of Y0 and/or Yinf independently of each other, for any order. AIC/BIC account for the resulting (smaller) number of free parameters, so model comparison across orders remains fair even when parameters are fixed.

classmethod from_spreadsheet(file_path=None, exp_number=1, sheet_name=0, show_data=True, colab=False, **kwargs)[source]

Convenience constructor: reads one experiment from a spreadsheet with load_from_spreadsheet(), then builds and returns a KORD instance from it, in a single call.

Equivalent to:

t, Y, headers, (a0, alpha, beta) = KORD.load_from_spreadsheet(
    file_path, exp_number, sheet_name, show_data, colab)
study = KORD(t, Y, headers, a0=a0, alpha=alpha, beta=beta, **kwargs)

Any extra keyword argument (k_guess, Y0_guess, Yinf_guess, binf_guess, t_simul_max, verbose, …) is forwarded to KORD.__init__. colab=True opens the Google Colab upload widget instead of reading file_path (same as in load_from_spreadsheet / kbasic.read).

Use load_from_spreadsheet() directly instead when you need to inspect or modify the loaded data/parameters before creating the KORD instance.

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=None, exp_number=1, sheet_name=0, show_data=True, colab=False)[source]

Deprecated alias for load_from_spreadsheet() (kept so existing scripts/notebooks that call load_from_excel keep working — the method always read any spreadsheet format pandas.read_excel supports, including .ods, so the old name was misleading). Prefer load_from_spreadsheet in new code.

static load_from_spreadsheet(file_path=None, exp_number=1, sheet_name=0, show_data=True, colab=False)[source]

Static method to extract data from a spreadsheet file (.xlsx, .xls, .ods, … anything pandas.read_excel can open — a local path, or any path/URL pandas.read_excel accepts). Selects the pair of columns (t, Y) corresponding to the experiment number. Also loads parameters (a0, alpha, beta)

Format:
  • Row 1: Headers for t and Y

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

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

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

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

Parameters:
  • file_path – path (or URL) of the spreadsheet to read. Not needed if colab=True (the file is picked via the Colab upload widget).

  • colab – if True, opens the Google Colab upload button and reads the chosen file instead of file_path. Default False.

plot_all_fits(save_img=None, fix_Y0=False, fix_Yinf=False)[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.

fix_Y0 / fix_Yinf are forwarded to fit() for any order not already present in self.results, so you can get all three comparison plots fitted with Y0 and/or Yinf held fixed (see fit()’s docstring).

An order already present in self.results (from an earlier fit() call) is NOT re-fitted here, even if fix_Y0/fix_Yinf passed to this plot differ from the ones that produced the cached fit — your earlier, explicit choice is respected rather than silently overwritten. If that creates a mismatch (some orders fitted under different fix_Y0/fix_Yinf settings than the others), a warning table is printed, since comparing orders fitted under different constraints can be misleading.

simulate_plot(order=None, show_experimental=True, save_img=None)[source]

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

Parameters:
  • order (int or None, optional) – which order’s guess to plot. None (the default) plots all three (0, 1, 2), as before. Pass 0, 1 or 2 to show only that one order’s guess curve.

  • show_experimental (bool, optional) – if True (the default), overlays the measured data (self.t_exp, self.Y_exp) as scatter points, so the guess can be checked visually against the actual data instead of only against the other guesses. Set to False to recover the old guesses-only behaviour.

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

class pyphyschemtools.kinetics.ReactionNetwork(verbose=True)[source]

Bases: object

A general chemical kinetics tool: build an arbitrary network of (ir)reversible elementary reactions, simulate the concentration of every species over time by numerically integrating the mass-action ODE system, and fit the rate constant(s) of each reaction against experimental data.

Unlike kbasic/KORD (closed-form integrated rate laws for a single A -> B transformation of order 0, 1 or 2), ReactionNetwork has no restriction on the number of species or reactions: parallel reactions (A->B, A->C), consecutive reactions (A->B->C), reversible reactions (A<=>B), and any combination of those, are all just a network of elementary steps.

Workflow (three steps, in order):
  1. net.add_reaction(“A -> B”, k_guess=…) # one call per step

  2. net.set_initial_conditions({“A”: a0, …})

  3. net.fit(t_exp, Y_exp, weights={…}) # or net.simulate(t)

Example (consecutive reactions, A -> B -> C):

net = ReactionNetwork()
net.add_reaction("A -> B", k_guess=0.5)
net.add_reaction("B -> C", k_guess=0.1)
net.set_initial_conditions({"A": 1.0, "B": 0.0, "C": 0.0})

# If only B is measured (e.g. it's the colored/absorbing species):
net.fit(t_exp, Y_exp, observed_species="B")
net.plot(t_exp, Y_exp)

Example (reversible reaction, A <=> B):

net = ReactionNetwork()
net.add_reaction("A <=> B", kf_guess=1.0, kr_guess=0.2)
net.set_initial_conditions({"A": 1.0, "B": 0.0})
net.fit(t_exp, Y_exp, observed_species="B")

Notes

  • Rate law: mass action by default – a reaction’s forward (and, if reversible, backward) rate is k times the product of its reactants’ (products’) concentrations, each raised to its own stoichiometric coefficient. This is the standard assumption for an elementary step; it is not automatically valid for an overall multi-step reaction written as a single line (see Kinetics.md 4.2’s discussion of pseudo-order and the QSSA).

  • fit() requires set_initial_conditions() to have been called first, and either weights={…} (general linear combination of concentrations) or the observed_species=”X” shortcut (equivalent to weights={“X”: 1.0}).

  • All rate constants are constrained to be >= 0 (physical consistency), exactly like k/binf in KORD.fit().

add_reaction(equation, k_guess=None, kf_guess=None, kr_guess=None, order=None, order_back=None)[source]

Adds one elementary reaction to the network, e.g. net.add_reaction("A + 2 B -> C", k_guess=0.5) or net.add_reaction("A <=> B", kf_guess=1.0, kr_guess=0.2).

Parameters:
  • equation (str) – reaction equation. Species are single-word names (letters/digits/underscore, Unicode accents allowed, e.g. “A”, “H2O”, “ethylene”); terms are separated by ‘+’, with an optional leading integer stoichiometric coefficient (e.g. “2 B”). Use ‘->’ for an irreversible reaction, ‘<=>’ for a reversible one.

  • k_guess (float, optional) – starting guess for the (single) rate constant of an irreversible reaction. Defaults to 1.0 if not given.

  • kf_guess (float, optional) – starting guesses for the forward/backward rate constants of a reversible reaction. Each defaults to 1.0 if not given (kf_guess also accepts the value passed as k_guess, for convenience).

  • kr_guess (float, optional) – starting guesses for the forward/backward rate constants of a reversible reaction. Each defaults to 1.0 if not given (kf_guess also accepts the value passed as k_guess, for convenience).

  • order (dict, optional) – forward rate law exponents, as {species: exponent}, overriding the default assumption that the kinetic order in each reactant equals its stoichiometric coefficient. Only needed when the mechanism isn’t a textbook elementary step (e.g. a measured/pseudo order that differs from the written stoichiometry) – see Kinetics.md 4.2’s discussion of pseudo-order kinetics for the same caveat on kbasic/ KORD. Keys must be a subset of this reaction’s reactants.

  • order_back (dict, optional) – same as order, but for the backward rate of a reversible reaction; keys must be a subset of this reaction’s products. Ignored for an irreversible reaction.

Any species not seen in a previous call is added to the network automatically, in order of first appearance.

copy()[source]

Returns an independent deep copy of this ReactionNetwork, so the same reaction list/initial conditions can be fitted more than once (different starting guesses, different weights, a different subset of the data…) without one fit() call overwriting another’s result – the same rationale as KORD.copy(). Mainly a convenience once a network has several reactions, so they don’t have to be declared twice:

net_B_only = ReactionNetwork()
net_B_only.add_reaction("A -> B", k_guess=0.5)
net_B_only.add_reaction("B -> C", k_guess=0.1)
net_B_only.set_initial_conditions({"A": 1.0, "B": 0.0, "C": 0.0})

net_mixed = net_B_only.copy()           # same reactions/initial conditions
net_B_only.fit(t_exp, Y_exp, observed_species="B")
net_mixed.fit(t_exp, Y_exp, weights={"B": 0.8, "C": 0.2})
# net_B_only.results and net_mixed.results can now be compared
fit(t_exp, Y_exp, weights=None, observed_species=None)[source]

Fits every reaction’s rate constant(s) against experimental data, assuming the measured signal is a linear combination of concentrations, Y_EXP(t) = sum_i eta_i * C_i(t) (see Kinetics.md, 4.2.1 – the same assumption KORD relies on).

Parameters:
  • t_exp – experimental time points and measured values.

  • Y_exp – experimental time points and measured values.

  • weights (dict, optional) – {species: eta_i} linear-combination weights. Use this when the signal mixes several species.

  • observed_species (str, optional) – shortcut for weights={observed_species: 1.0}, when the signal is one single species’ concentration directly.

Exactly one of weights/observed_species must be given.

Returns:

{‘k’: {param_name: fitted_value}, ‘RMSE’, ‘R2’, ‘AIC’, ‘BIC’, ‘weights’}. Also stored in self.results, and the fitted rate constants in self.k_fit (so a later simulate()/plot() call with no k_values argument uses them automatically).

Return type:

dict

overall_equation()[source]

Sums the stoichiometry of every declared reaction (each counted once, forward direction as written) and cancels out whatever appears on both sides – typically the reaction intermediates – to get the overall/net equation of the mechanism. Returns a string such as “A -> C” for the mechanism “A -> B”, “B -> C” (B is an intermediate and cancels).

This is a useful sanity check on a multi-step mechanism: the overall equation it implies should match the one you started from (e.g. the balanced equation given in the problem).

Note: a reversible reaction contributes its forward stoichiometry only – this is about the mechanism’s bookkeeping (which atoms go where across the whole sequence), not about net flux at a given time, which depends on the actual rate constants and concentrations (see qssa_check() for that).

plot(t_exp=None, Y_exp=None, t_max=None, log_scale=False, time_unit=None, species=None, save_img=None)[source]

Plots simulated concentration vs. time (using the fitted rate constants if fit() was called, otherwise the guesses), optionally overlaying the experimental (t_exp, Y_exp) points on the fitted observed linear combination.

species: optional list of species names to plot (e.g. net.plot(['A', 'I']) to zoom in on a reactant and a reaction intermediate). Defaults to every species in the network. Each name is checked against self.species first, with a clear error listing the known species if one doesn’t exist (a likely typo, or a name that was never declared via add_reaction()).

log_scale=True switches the y-axis to log scale – useful whenever concentrations span several orders of magnitude, e.g. a trace reactive intermediate alongside a bulk reactant/product (species that reach exactly 0 are simply left off the log plot for the points where they’re non-positive, as matplotlib does).

time_unit: optional string purely for the x-axis label, e.g. time_unit="s" labels the axis “Time / s”. ReactionNetwork itself is unit-agnostic – t, C0 and the rate constants just have to be in a mutually consistent set of units; nothing here converts between units or checks them, this only labels the plot.

save_img: optional file path to save the figure to (png, pdf, svg, … – whatever matplotlib’s savefig infers from the extension), in addition to showing it. Asks before overwriting an existing file.

plot_qssa(species, t, threshold=0.1, time_unit=None, save_img=None)[source]

Two-panel diagnostic plot for the quasi-steady-state approximation on species (see qssa_check()): concentrations on top, the QSSA ratio on the bottom, with the region under threshold shaded to mark where the approximation is a good one.

time_unit: optional string purely for the (shared) x-axis label, e.g. time_unit="s" – see plot()’s docstring; this does not convert or check units, only labels the axis.

save_img: optional file path to save the figure to, in addition to showing it – see plot()’s docstring.

qssa_check(species, t, k_values=None)[source]

Checks, numerically, how good the quasi-steady-state approximation (QSSA/QSSA) is for species at each time in t – the classic question for an intermediate in a consecutive mechanism (e.g. B in A -> B -> C): is d[B]/dt really negligible compared to how fast B is being produced and consumed, or only “small enough” after some induction period?

Integrates the exact ODE system (same as simulate()), then at every requested time compares the net rate of change of species to its gross rate – the sum of the absolute value of every reaction’s individual contribution to it (production and consumption both counted as positive, so they cannot cancel out the way they do in the net rate):

$$text{QSSA ratio}(t) = frac{|d[\text{species}]/dt|}{sum_j |\text{contribution}_j(t)|}$$

A ratio close to 0 means production and consumption are nearly balanced (net change negligible compared to the flux passing through) – the QSSA holds; a ratio close to 1 means the species is still mostly accumulating or mostly depleting on its own, not yet (or no longer) in a quasi-steady state.

Parameters:
  • species (str) – the species to check (typically a reactive intermediate).

  • t – array-like of time points to evaluate the ratio at.

  • k_values – same as simulate() – rate constants to use, or None to use the fitted/guessed values.

Returns:

the QSSA ratio at each time in t (same order as given, not necessarily sorted).

Return type:

numpy array

set_initial_conditions(conditions)[source]

Sets each species’ concentration at t=0, e.g. net.set_initial_conditions({"A": 1.0, "B": 0.0}).

Any species already in the network but missing from conditions defaults to 0.0 (with a warning if verbose).

simulate(t, k_values=None)[source]

Integrates the ODE system and returns each species’ concentration at the requested time points.

Parameters:
  • t – array-like of time points (need not be sorted).

  • k_values – rate constants to use – a {param_name: value} dict, a flat list/array in the same order as the reactions were added (k or kf,kr per reaction), or None (default) to use the fitted values from fit() if available, otherwise the guesses passed to add_reaction().

Returns:

{species_name: numpy array of concentrations at t}.

Return type:

dict

summary()[source]

Prints each reaction with its (fitted, if available, else guessed) rate constant(s).

class pyphyschemtools.kinetics.kbasic[source]

Bases: object

FR — 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 Y décroît avec le temps depuis sa valeur initiale Y0. La forme de Y(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

EN — Pedagogical search for the rate constant k.

Typical usage

kb = kbasic()
kb.read("measurements.xlsx")  # 1) read the data
kb.fit(order=1)               # 2) look for the best k
kb.plot()                     # 3) plot the result

The measured quantity Y decreases with time from its initial value Y0. The shape of Y(t) depends on the reaction order:

  • order 0: LINEAR decay

  • order 1: EXPONENTIAL decay (the most common case)

  • order 2: HYPERBOLIC decay

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

FR — Trouve la valeur de k qui minimise le RMSE pour l’ordre choisi.

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

Si k_depart n’est pas donné (défaut), il est estimé automatiquement à partir des données par _k_depart_auto() (voir cette méthode) au lieu d’une constante arbitraire — utile si k est très différent de 0.1 en ordre de grandeur, ce qui pouvait auparavant ralentir ou faire échouer la convergence. Vous pouvez toujours imposer votre propre valeur de départ en passant k_depart explicitement.

Calcule aussi le temps de demi-réaction t_1/2 (stocké dans self.t_half et affiché), selon la formule propre à l’ordre choisi (voir section 3.4 “Theory” de Kinetics.md) :

  • ordre 0 : t_1/2 = Y0 / (2*k)

  • ordre 1 : t_1/2 = ln(2) / k

  • ordre 2 : t_1/2 = 1 / k

Retourne : (k_optimal, rmse_au_minimum)

EN — Finds the value of k that minimizes the RMSE for the chosen order.

If Y0 is not given, it is taken equal to the first measured value. Otherwise, the user-provided value is used.

If k_depart is not given (default), it is estimated automatically from the data by _k_depart_auto() instead of an arbitrary constant — useful when k is far from 0.1 in order of magnitude, which could previously slow down or fail convergence. You can still force your own starting value by passing k_depart explicitly.

Also computes the half-life t_1/2 (stored in self.t_half and printed), using the order-specific formula (see section 3.4 “Theory” in Kinetics.md):

  • order 0: t_1/2 = Y0 / (2*k)

  • order 1: t_1/2 = ln(2) / k

  • order 2: t_1/2 = 1 / k

Returns: (k_optimal, rmse_at_minimum)

plot()[source]

FR — Trace la comparaison données / modèle et le paysage du RMSE. EN — Plots the data/model comparison and the RMSE landscape.

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

FR — Lit un fichier Excel à deux colonnes (temps, Y) 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.

EN — Reads a two-column Excel file (time, Y) and displays a summary as a pandas DataFrame.

Automatically detects whether the first row is a header. If so, the column names are used as axis labels for the plot.

Returns the DataFrame of the data read.

Parameters:
  • fichier – path (or URL) of the Excel file to read. Unused if colab=True (the file is picked via the upload widget).

  • colab – if True, opens the Google Colab upload button and reads the chosen file. Default False.

pyphyschemtools.kinetics.superpose_plots(studies, order=1, show_experimental=True, labels=None, fix_Y0=False, fix_Yinf=False, save_img=None)[source]

FR — Superpose, sur un même graphe, la courbe ajustée (fit, pas guess) d’un seul ordre pour plusieurs instances KORD — typiquement la même expérience fittée dans des conditions différentes (p.ex. une étude avec Y0 figé, une autre où Y0 reste libre), pour voir directement l’effet de ce choix sur la courbe ajustée.

Pour chaque étude, si order n’est pas déjà présent dans study.results, l’ajustement est fait maintenant avec fix_Y0/fix_Yinf (mêmes réglages que plot_all_fits()). Si order est déjà en cache (study.results) avec des réglages fix_Y0/fix_Yinf différents de ceux demandés ici, le cache n’est PAS écrasé — exactement le comportement de plot_all_fits() — mais un avertissement est affiché pour cette étude. La légende indique automatiquement, pour chaque étude, si Y0 et/ou Yinf ont été figés dans l’ajustement effectivement tracé.

Args :
studies (list[KORD])les instances KORD à comparer (peuvent être

des fits de la même donnée, sous des réglages différents).

order (int, optionnel)l’ordre à tracer pour toutes les études

(0, 1 ou 2). Par défaut 1.

show_experimental (bool, optionnel)si True (par défaut), superpose

aussi les données mesurées de chaque étude.

labels (list[str] ou None, optionnel)légendes de base pour chaque

étude ; par défaut “Study 1”, “Study 2”, … (le statut fix_Y0/fix_Yinf est ajouté automatiquement).

fix_Y0, fix_Yinf (bool, optionnel)transmis à fit() pour toute

étude dont order n’est pas déjà dans son .results.

save_img : comme pour simulate_plot()/plot_all_fits().

EN — Overlays, on a single graph, the fitted (not guess) curve of one chosen order for several KORD instances — typically the same experiment fitted under different conditions (e.g. one study with Y0 frozen, another with Y0 left free), to see directly how that choice changes the fitted curve.

For each study, if order is not already present in study.results, it is fitted now with fix_Y0/fix_Yinf (same settings as plot_all_fits()). If order is already cached in study.results under different fix_Y0/fix_Yinf settings than requested here, the cache is NOT overwritten — exactly like plot_all_fits() — but a warning is printed for that study. The legend automatically shows, for each study, whether Y0 and/or Yinf were held fixed in the fit actually plotted.

Parameters:
  • studies (list[KORD]) – the KORD instances to compare (can be fits of the very same data, under different settings).

  • order (int, optional) – the order to plot for every study. Default 1.

  • show_experimental (bool, optional) – if True (the default), also overlay each study’s measured data.

  • labels (list[str] or None, optional) – base legend labels; default “Study 1”, “Study 2”, … (the fix_Y0/fix_Yinf status is added automatically).

  • fix_Y0 (bool, optional) – forwarded to fit() for any study whose order isn’t already in its .results.

  • fix_Yinf (bool, optional) – forwarded to fit() for any study whose order isn’t already in its .results.

  • save_img – as in simulate_plot()/plot_all_fits().