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 likekbasic/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 severalKORDstudies on one plot, e.g. to compare the same data fitted freely vs. withfix_Y0/fix_Yinf. See 4.4.1 Comparing several fits.
Table of Contents
2. Integrated rate laws: \(a(t)\), \(b(t)\) and half-lives for orders 0, 1, 2
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\):
(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:
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:
Order 1:
Order 2:
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:
Order 1:
Order 2:
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
_modeledecay from \(Y_0\) toward 0 (the order-0 case is floored at exactly 0 bynp.maximum). There is no adjustable \(Y_\infty\). Do not usekbasicon data whose measured quantity levels off at a non-zero value — useKORDinstead.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 —kbasicalready does, permanently, whatKORD.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, andkbasiconly 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:
Standard Formula for Order 1:
Standard Formula for Order 2:
\(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:
Best model: the order with the lowest RMSE (plain goodness of fit).
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 inget_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.15means 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):
Compte tenu des équations de \(a(t)\) et \(b(t)\) pour les ordres 0, 1 et 2, il vient :
Standard Formula for Order 0:
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:
Standard Formula for Order 2:
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=2for the second experiment).If each experiment instead lives on its own sheet/tab of the workbook, pass
sheet_nameexplicitly, 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, thennet.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 (givek_guess);<=>for a reversible one (givekf_guess/kr_guess— each defaults to 1.0 if omitted, andkf_guessalso accepts the value passed ask_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/ororder_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 forKORD’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, soorder_backisn’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:
order 1 (e.g.
"A -> B"): \([k]=\text{time}^{-1}\) (e.g. s⁻¹) — same askbasic’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):
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,
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,
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:
objectInitialize 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
- 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.40thenstudy.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 callload_from_excelkeep working — the method always read any spreadsheet format pandas.read_excel supports, including .ods, so the old name was misleading). Preferload_from_spreadsheetin 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:
objectA 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):
net.add_reaction(“A -> B”, k_guess=…) # one call per step
net.set_initial_conditions({“A”: a0, …})
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)ornet.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 inself.k_fit(so a latersimulate()/plot()call with nok_valuesargument 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 againstself.speciesfirst, 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=Trueswitches 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 underthresholdshaded 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
speciesat each time int– 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
speciesto 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
conditionsdefaults to 0.0 (with a warning ifverbose).
- 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
- class pyphyschemtools.kinetics.kbasic[source]
Bases:
objectFR — 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().