Source code for pyphyschemtools.kinetics

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib.ticker as mtick
from scipy.optimize import curve_fit
from scipy.integrate import solve_ivp
from sklearn.metrics import root_mean_squared_error as rmse
from sklearn.metrics import r2_score as r2
from .visualID_Eng import fg, hl, bg, color
from .colab_utils import colab_upload
import os
import re
import unicodedata
import copy as _copy

# =====================================================================
#  FR — kbasic : recherche de la constante de vitesse k par minimisation
#  du RMSE. Version pédagogique, simple et autonome.
#
#  Une classe avec trois opérations, dans l'ordre :
#     1) kb.read(fichier)  : lire le fichier Excel (temps, Y) + récapitulatif
#     2) kb.fit(ordre)     : faire le fit (trouver le meilleur k)
#     3) kb.plot()         : tracer le résultat (comparer modèle et données)
#
#  Idée : on a des points expérimentaux (temps, grandeur mesurée Y) et un
#  modèle théorique qui dépend de k. On cherche le k qui MINIMISE l'écart
#  entre modèle et données. Cet écart est le RMSE.
#
#  EN — kbasic: pedagogical, self-contained search for the rate constant
#  k by minimizing the RMSE.
#
#  A class with three operations, in order:
#     1) kb.read(file)   : read the Excel file (time, Y) + summary table
#     2) kb.fit(order)   : do the fit (find the best k)
#     3) kb.plot()       : plot the result (compare model and data)
#
#  Idea: we have experimental points (time, measured quantity Y) and a
#  theoretical model that depends on k. We look for the k that MINIMIZES
#  the gap between model and data. That gap is the RMSE.
# =====================================================================

# numpy, pandas and matplotlib.pyplot are already imported at the top of this
# file (used by KORD too); the one new import kbasic needs is minimize:
from scipy.optimize import minimize     # FR: outil qui cherche le minimum d'une fonction / EN: tool that finds the minimum of a function


[docs] class kbasic: """ 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 """ def __init__(self): # Les données expérimentales (remplies par read). self.t_exp = None # temps mesurés self.Y_exp = None # grandeurs mesurées # Les en-têtes lus dans le fichier (remplis par read), pour les axes. self.label_t = "Temps" # nom de l'axe des temps (par défaut) self.label_Y = "Y" # nom de l'axe de la grandeur (par défaut) # Les résultats du fit (remplis par fit). self.Y0 = None # valeur de Y à t=0 self.ordre = None # ordre choisi pour le fit self.k_opt = None # meilleure valeur de k trouvée self.rmse_min = None # RMSE au minimum self.t_half = None # temps de demi-réaction t_1/2 self._initialized = True # voir __setattr__ ci-dessous def __setattr__(self, name, value): """ FR — Protection contre les fautes de frappe sur un nom d'attribut (p. ex. `kb.Y_initial = ...` au lieu de `kb.Y0 = ...`) : une fois l'objet construit, on ne peut plus CRÉER un nouvel attribut — seuls ceux déjà définis dans __init__ peuvent être modifiés. Sans ça, Python créerait silencieusement l'attribut mal orthographié, et le reste du code continuerait d'utiliser l'ancienne valeur sans jamais signaler l'erreur. EN — Guards against attribute-name typos (e.g. `kb.Y_initial = ...` instead of `kb.Y0 = ...`): once the object is built, no NEW attribute can be created — only ones already defined in __init__ can be changed. Without this, Python would silently create the misspelled attribute, and the rest of the code would keep using the old value with no error at all. """ if getattr(self, '_initialized', False) and name not in self.__dict__: existing = ', '.join(sorted(k for k in self.__dict__ if not k.startswith('_'))) raise AttributeError( f"kbasic has no attribute '{name}' (possible typo?). " f"Existing attributes: {existing}" ) object.__setattr__(self, name, value) # ----------------------------------------------------------------- # Les trois modèles théoriques. # Chacun ne dépend que du temps t, de la constante k et de Y0. # ----------------------------------------------------------------- def _modele(self, t, k, Y0, ordre): """Renvoie Y(t) prédit par le modèle de l'ordre demandé.""" if ordre == 0: # Ordre 0 : droite qui descend, bornée à zéro une fois le # réactif épuisé (np.maximum empêche de passer sous zéro). return np.maximum(Y0 - k * t, 0) elif ordre == 1: # Ordre 1 : exponentielle. À t=0, Y=Y0 ; à t grand, Y->0. return Y0 * np.exp(-k * t) elif ordre == 2: # Ordre 2 : hyperbole. À t=0, Y=Y0. return Y0 / (1 + k * t) else: raise ValueError("ordre doit valoir 0, 1 ou 2") # ----------------------------------------------------------------- # Le RMSE : la mesure de l'écart entre données et modèle. # RMSE = racine de la moyenne des carrés des écarts. # Plus il est petit, mieux le modèle colle aux données. # ----------------------------------------------------------------- def _rmse(self, k, ordre, Y0): """Calcule le RMSE pour une valeur de k donnée.""" # ATTENTION : ce n'est pas nous qui appelons cette fonction, c'est # minimize (voir la méthode fit). Or minimize travaille toujours avec # un TABLEAU de paramètres, jamais avec un simple nombre. Comme on lui # donne x0=[k_depart] (une liste), il rappelle _rmse en passant k sous # forme de tableau à un élément, par exemple [0.1] puis [0.093]... # La VALEUR change à chaque itération, mais la forme reste [un_element]. # On extrait donc ce nombre unique avec k[0] pour pouvoir l'utiliser # dans le modèle. np.ndim(k) vaut 0 pour un nombre, 1 pour un tableau : # le test rend la fonction utilisable aussi avec un simple nombre. if np.ndim(k) > 0: k = k[0] Y_modele = self._modele(self.t_exp, k, Y0, ordre) return np.sqrt(np.mean((self.Y_exp - Y_modele) ** 2)) # ================================================================= # 1) LIRE LES DONNÉES # # Fichier Excel à deux colonnes : temps à gauche, Y à droite. # La première ligne PEUT être un en-tête (texte) ou déjà des # données (nombres). On regarde la première cellule : # - texte -> c'est un en-tête, on saute la 1ère ligne # - nombre -> ce sont déjà des données, on garde tout # =================================================================
[docs] def read(self, fichier=None, colab=False): """ 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 : fichier : chemin (ou URL) du fichier Excel à lire. Inutile si colab=True (on choisit le fichier à l'upload). colab : si 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. Args: 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. """ # Mode Google Colab : on ouvre le sélecteur de fichier, l'utilisateur # choisit son .xlsx, et on récupère son nom pour le lire ensuite. if colab: fichier = colab_upload() # bouton "Parcourir" Colab, voir colab_utils.py # On lit d'abord SANS supposer d'en-tête (header=None), pour # examiner nous-mêmes la première cellule. brut = pd.read_excel(fichier, header=None) # isinstance(x, str) répond à : "est-ce que x est du texte ?" if isinstance(brut.iloc[0, 0], str): # En-tête présent : on garde les deux noms de colonnes pour # les utiliser comme labels d'axes dans plot(), puis les vraies # données commencent à la ligne 1. self.label_t = str(brut.iloc[0, 0]) self.label_Y = str(brut.iloc[0, 1]) donnees = brut.iloc[1:] else: # Pas d'en-tête : tout le tableau est déjà des données, et on # garde les labels par défaut ("Temps" et "Y"). donnees = brut # Colonne 0 = temps, colonne 1 = Y. On force en nombres (float). self.t_exp = donnees.iloc[:, 0].astype(float).values self.Y_exp = donnees.iloc[:, 1].astype(float).values # Récapitulatif propre sous forme de DataFrame, qu'on affiche. # On y réutilise les en-têtes lus (ou les labels par défaut). recap = pd.DataFrame({self.label_t: self.t_exp, self.label_Y: self.Y_exp}) print(f"{len(self.t_exp)} points lus.") try: # display() rend un joli tableau dans un notebook Jupyter. from IPython.display import display display(recap) except ImportError: # En dehors d'un notebook, un simple print suffit. print(recap) return recap
# ----------------------------------------------------------------- # Estimation d'un point de départ raisonnable pour k, à partir des # données elles-mêmes (plutôt qu'une constante arbitraire comme 0.1, # qui peut être très loin du bon ordre de grandeur et faire échouer # ou ralentir la convergence de minimize). # ----------------------------------------------------------------- def _k_depart_auto(self, ordre, Y0): """ FR — Estime un k de départ en inversant analytiquement le modèle de l'ordre choisi, à partir d'un seul point expérimental (ni le tout premier, ni le tout dernier) pris comme référence : - ordre 0 : Y = Y0 - k t => k = (Y0 - Y_n) / t_n - ordre 1 : Y = Y0 exp(-k t) => k = -ln(Y_n / Y0) / t_n - ordre 2 : Y = Y0 / (1 + k t) => k = (Y0 / Y_n - 1) / t_n Si l'estimation échoue ou donne un k négatif ou nul (données trop bruitées, point de référence mal choisi...), on revient à 0.1. EN — Estimates a starting k by analytically inverting the chosen order's model at a single reference data point (neither the very first nor the very last). Falls back to 0.1 if the estimate fails or comes out non-positive. """ # Point de référence : ~10% des données, jamais le premier point # (t=0 ne donne aucune information sur k). n = max(1, len(self.t_exp) // 10) t_n, Y_n = self.t_exp[n], self.Y_exp[n] if t_n == 0: return 0.1 try: if ordre == 0: k0 = (Y0 - Y_n) / t_n elif ordre == 1: if Y_n <= 0: return 0.1 k0 = -np.log(Y_n / Y0) / t_n elif ordre == 2: if Y_n == 0: return 0.1 k0 = (Y0 / Y_n - 1) / t_n else: return 0.1 except (ValueError, ZeroDivisionError): return 0.1 return k0 if k0 > 0 else 0.1 # ================================================================= # 2) FAIRE LE FIT : chercher le meilleur k (minimiser le RMSE) # =================================================================
[docs] def fit(self, ordre=1, Y0=None, k_depart=None): """ 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) """ # Valeur par défaut de Y0 : le premier point mesuré. if Y0 is None: Y0 = self.Y_exp[0] # Valeur de départ de k : estimée à partir des données si non fournie. if k_depart is None: k_depart = self._k_depart_auto(ordre, Y0) # minimize cherche le k qui rend le RMSE le plus petit possible. # - self._rmse : la fonction à minimiser # - x0=[k_depart] : valeur de départ de la recherche # - args=(...) : les autres arguments fixes passés à _rmse # - bounds : on impose k >= 0 (une vitesse n'est pas négative) # # Pourquoi x0=[k_depart] avec des crochets, et pas juste k_depart ? # minimize est conçu pour optimiser plusieurs paramètres à la fois ; il # attend donc TOUJOURS une LISTE de valeurs de départ, même quand il n'y # a qu'un seul paramètre (ici k). On écrit donc [k_depart], c.-à-d. # [0.1], et non 0.1. C'est aussi pour cela que _rmse reçoit k sous forme # de tableau et fait k = k[0] (voir le commentaire dans _rmse). resultat = minimize( self._rmse, x0=[k_depart], args=(ordre, Y0), bounds=[(0, None)], ) # On mémorise tout dans l'objet, pour que plot() puisse s'en servir. self.ordre = ordre self.Y0 = Y0 self.k_opt = resultat.x[0] # meilleure valeur de k self.rmse_min = resultat.fun # RMSE correspondant (le plus petit) # Temps de demi-réaction t_1/2, calculé à partir de k_opt et de la # formule propre à chaque ordre (voir section 3.4 "Theory" de Kinetics.md). if ordre == 0: self.t_half = self.Y0 / (2 * self.k_opt) elif ordre == 1: self.t_half = np.log(2) / self.k_opt elif ordre == 2: self.t_half = 1 / self.k_opt print(f"Ordre {ordre} : k optimal = {self.k_opt:.4e}" f" (RMSE = {self.rmse_min:.4e})" f" (t1/2 = {self.t_half:.4e})") return self.k_opt, self.rmse_min
# ================================================================= # 3) TRACER LE RÉSULTAT : comparer données et modèle ajusté # # Deux graphiques côte à côte : # - à gauche : les données et la courbe du modèle ajusté # - à droite : le "paysage" du RMSE en fonction de k, qui montre # la vallée dont minimize a trouvé le fond. # =================================================================
[docs] def plot(self): """FR — Trace la comparaison données / modèle et le paysage du RMSE. EN — Plots the data/model comparison and the RMSE landscape.""" # On a besoin du résultat du fit. Si fit() n'a pas encore été appelé, # k_opt vaut None : on prévient l'utilisateur au lieu de planter. if self.k_opt is None: raise RuntimeError("Faites d'abord kb.fit(...) avant kb.plot().") figure, (gauche, droite) = plt.subplots(1, 2, figsize=(13, 5)) # ---- Graphique de gauche : données + modèle ---- # Grille de temps fine et régulière pour une courbe bien lisse. t_lisse = np.linspace(self.t_exp.min(), self.t_exp.max(), 400) Y_lisse = self._modele(t_lisse, self.k_opt, self.Y0, self.ordre) gauche.scatter(self.t_exp, self.Y_exp, color="black", marker="x", label="Données expérimentales") gauche.plot(t_lisse, Y_lisse, color="red", label=f"Modèle ordre {self.ordre} (k = {self.k_opt:.4e})") # On utilise les en-têtes lus dans le fichier comme labels d'axes # (ou les valeurs par défaut "Temps" et "Y" s'il n'y avait pas d'en-tête). gauche.set_xlabel(self.label_t) gauche.set_ylabel(self.label_Y) gauche.legend() gauche.grid(True) gauche.set_title('Données et modèle ajusté ("fitté")') # ---- Graphique de droite : le paysage du RMSE ---- # On essaie plein de valeurs de k autour de l'optimum et on calcule # le RMSE pour chacune, afin de "voir" la vallée. k_essais = np.linspace(max(self.k_opt * 0.1, 1e-9), self.k_opt * 3, 300) rmse_essais = [self._rmse(k, self.ordre, self.Y0) for k in k_essais] droite.plot(k_essais, rmse_essais, color="blue", label="RMSE(k)") # On marque le minimum trouvé par minimize d'un gros point rouge. droite.scatter([self.k_opt], [self.rmse_min], color="red", zorder=5, label=f"minimum (k = {self.k_opt:.4e})") droite.axvline(self.k_opt, color="red", linestyle="--", alpha=0.5) droite.set_xlabel("k") droite.set_ylabel("RMSE") droite.legend() droite.grid(True) droite.set_title("Le paysage du RMSE : minimize en cherche le 'fond'") figure.tight_layout() plt.show()
[docs] class KORD: """ Initialize the kinetic study with experimental data. Reaction: alpha A = beta B Args: - t_exp (array-like): Time values. - Y_exp (array-like): 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 """ def __init__(self, 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): # Force conversion to float arrays to prevent 'object' dtype issues. # This ensures [0, 0.5, ...] (objects) become [0.0, 0.5, ...] (floats), # allowing NumPy mathematical functions (like np.exp) to operate correctly. # It is optional if a user wants to simulate a spectrum self.t_exp = np.array(t_exp, dtype=float) if t_exp is not None else None self.Y_exp = np.array(Y_exp, dtype=float) if Y_exp is not None else None self.headers = headers # Ensure fixed parameters are treated as native floats. # This prevents errors during optimization if values are passed as strings or tuples. self.a0 = float(a0) self.alpha = float(alpha) self.beta = float(beta) self.t_simul_max = t_simul_max # Logic for Guesses: Priority to provided values, then data, then defaults if Y0_guess is not None: self.Y0_guess = Y0_guess elif self.Y_exp is not None: self.Y0_guess = self.Y_exp[0] else: self.Y0_guess = 0.0 # Default fallback if no data and no guess (this is for a simulation plot) if Yinf_guess is not None: self.Yinf_guess = Yinf_guess elif self.Y_exp is not None: self.Yinf_guess = self.Y_exp[-1] else: self.Yinf_guess = 1.0 # Default fallback (this is for a simulation plot) self.binf_guess = binf_guess if binf_guess is not None else self.a0*self.beta/self.alpha self.k_guess = k_guess self.results = {} self.verbose = verbose # Color mapping for orders self.order_colors = {0: 'blue', 1: 'red', 2: 'green'} self.ansi_colors = {0: "\033[94m", 1: "\033[91m", 2: "\033[92m"} self.reset = "\033[0m" # t_fin = self.a0 / (self.alpha * self.k_guess) # print(f"{t_fin=}") self._initialized = True # voir __setattr__ ci-dessous def __setattr__(self, name, value): """ FR — Protection contre les fautes de frappe sur un nom d'attribut (p. ex. `study.Yinfguess = ...` au lieu de `study.Yinf_guess = ...`) : une fois l'objet construit, on ne peut plus CRÉER un nouvel attribut — seuls ceux déjà définis dans __init__ peuvent être modifiés. Sans cette protection, Python créerait silencieusement l'attribut mal orthographié ; fit() continuerait de lire l'ancienne valeur de Yinf_guess sans jamais signaler l'erreur. EN — Guards against attribute-name typos (e.g. `study.Yinfguess = ...` instead of `study.Yinf_guess = ...`): once the object is built, no NEW attribute can be created — only ones already defined in __init__ can be changed. Without this, Python would silently create the misspelled attribute, and fit() would keep reading the old value of Yinf_guess with no error at all. """ if getattr(self, '_initialized', False) and name not in self.__dict__: existing = ', '.join(sorted(k for k in self.__dict__ if not k.startswith('_'))) raise AttributeError( f"KORD has no attribute '{name}' (possible typo?). " f"Existing attributes: {existing}" ) object.__setattr__(self, name, value)
[docs] def copy(self): """ 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) """ return _copy.deepcopy(self)
[docs] @staticmethod def load_from_spreadsheet(file_path=None, exp_number=1, sheet_name=0, show_data=True, colab=False): """ 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 Args: 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. """ # 0. Google Colab mode: open the file picker, read the uploaded file's name. if colab: file_path = colab_upload() # Colab upload button, see colab_utils.py # 1. Check if file exists if not os.path.exists(file_path): print(f"❌ Error: The file '{file_path}' was not found.") return None try: df = pd.read_excel(file_path, sheet_name=sheet_name) except Exception as e: print(f"❌ Error while reading the spreadsheet: {e}") return None idx_t, idx_Y = 2*(exp_number-1), 2*(exp_number-1)+1 # --- Parameter Extraction (Now looking in the Y column: idx_Y) --- def parse_param(val): if isinstance(val, str): match = re.search(r"(\d+\.?\d*)", val) return float(match.group(1)) if match else 1.0 return float(val) if pd.notnull(val) else 1.0 total_cols = len(df.columns) num_experiments = total_cols // 2 print(f"Experiments detected: {num_experiments}") # Parameters are expected in rows 2, 3, and 4 of Excel (indices 0, 1, 2) a0 = parse_param(df.iloc[0, idx_Y]) alpha = parse_param(df.iloc[1, idx_Y]) beta = parse_param(df.iloc[2, idx_Y]) # --- Format sanity check: rows 2-4 of the t column should be empty or # text labels (see Format above) — a genuine number there usually means # the data doesn't follow the expected layout (e.g. real t,Y data was # put starting at row 2 instead of row 5). t_col_rows_2_4 = df.iloc[0:3, idx_t] suspicious = t_col_rows_2_4.apply(lambda v: pd.notnull(v) and not isinstance(v, str)) if suspicious.any(): print(f"⚠️ Warning: rows 2-4 of column '{df.columns[idx_t]}' (the t column) " f"contain numeric value(s): {list(t_col_rows_2_4[suspicious])}. Expected " f"format is row 1 = headers, rows 2-4 = [A]0/alpha/beta (in the Y column " f"only — the t column should be blank or a text label there), row 5+ = " f"data. It does not seem to be the case here; check your data.") # --- Data Extraction (From index 3 onwards) --- data = df.iloc[3:, [idx_t, idx_Y]].dropna() label_t = KORD._clean_pandas_suffix(df.columns[idx_t]) label_Y = KORD._clean_pandas_suffix(df.columns[idx_Y]) data.columns = [label_t, label_Y] print(f"✅ Loaded: {label_Y} (Exp {exp_number})") print(f" [Parameters from {label_Y}] a0: {a0:.4e} mol.L-1 | alpha: {alpha} | beta: {beta}\n") if show_data: from IPython.display import display display(data) return data.iloc[:, 0].values, data.iloc[:, 1].values, (label_t, label_Y), (a0, alpha, beta)
[docs] @staticmethod def load_from_excel(file_path=None, exp_number=1, sheet_name=0, show_data=True, colab=False): """ Deprecated alias for :meth:`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. """ print("⚠️ KORD.load_from_excel is deprecated, use KORD.load_from_spreadsheet instead " "(same behaviour — it never was Excel-only).") return KORD.load_from_spreadsheet(file_path, exp_number, sheet_name=sheet_name, show_data=show_data, colab=colab)
[docs] @classmethod def from_spreadsheet(cls, file_path=None, exp_number=1, sheet_name=0, show_data=True, colab=False, **kwargs): """ 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. """ t, Y, headers, (a0, alpha, beta) = cls.load_from_spreadsheet( file_path, exp_number, sheet_name=sheet_name, show_data=show_data, colab=colab) return cls(t, Y, headers, a0=a0, alpha=alpha, beta=beta, **kwargs)
@staticmethod def _clean_pandas_suffix(name): """ Safely removes the '.1', '.2' suffixes added by Pandas for duplicate names. Only matches a dot followed by digits at the VERY END of the string. Example: 'mol.L-1.1' -> 'mol.L-1' """ return re.sub(r'\.\d+$', '', str(name))
[docs] def simulate_plot(self, order=None, show_experimental=True, save_img=None): """ 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(). Args: 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 """ plt.figure(figsize=(10, 6)) # 2. Generate smooth time vector for simulation t_sim = np.linspace(0, self.t_simul_max, 500) # 3. Define the models to loop through models = {0: self.Y0_theo, 1: self.Y1_theo, 2: self.Y2_theo} orders_to_plot = [0, 1, 2] if order is None else [order] # Overlay the experimental data first, so the guess curve(s) are # drawn on top of it. if show_experimental and self.t_exp is not None: plt.scatter(self.t_exp, self.Y_exp, label="Experimental", color='black', marker="x", s=35, alpha=0.7, zorder=5) for o in orders_to_plot: func = models[o] # Use the color defined in your __init__ color = self.order_colors[o] # Simulate using the guess values from __init__ if o != 1: Y_sim = func(t_sim, k=self.k_guess, Y0=self.Y0_guess, Yinf=self.Yinf_guess, binf=self.binf_guess) else: Y_sim = func(t_sim, k=self.k_guess, Y0=self.Y0_guess, Yinf=self.Yinf_guess) plt.plot(t_sim, Y_sim, label=f"Guess Order {o}", color=color, lw=2.5, linestyle='-') # Formatting plt.xlabel(self.headers[0]) plt.ylabel(self.headers[1]) plt.title(f"Initial Kinetic Guesses for {self.headers[1]}") # Add a text box with the guess values for clarity guess_text = (f"Guesses:\n" f"k: {self.k_guess:.2e}\n" f"Y0: {self.Y0_guess:.4f}\n" f"Yinf: {self.Yinf_guess:.4f}\n" f"binf: {self.binf_guess:.2e}") plt.gca().text(0.05, 0.95, guess_text, transform=plt.gca().transAxes, verticalalignment='top', bbox=dict(boxstyle='round', facecolor='white', alpha=0.5)) plt.legend(loc='lower right') plt.grid(True, linestyle=':', alpha=0.6) if save_img: # Check if the file already exists to prevent accidental overwrite if os.path.exists(save_img): # Prompt the user for confirmation print(f"{color.RED}{hl.BOLD}⚠️ File '{save_img}' already exists. Overwrite? (y/n): {color.OFF}", end="") # Then call input response = input().lower().strip() if response != 'y': print("💾 Save cancelled. Plot not saved.") plt.show() # Display anyway without saving return # Exit the save logic # Security: ensure the target directory exists (e.g., if save_img="export/graph.svg") directory = os.path.dirname(save_img) if directory and not os.path.exists(directory): os.makedirs(directory) # Universal save (supports SVG, PNG, PDF, etc. based on extension) # bbox_inches='tight' prevents labels or secondary axes from being cropped plt.savefig(save_img, dpi=300, bbox_inches='tight') print(f"💾 Plot saved as: {hl.BOLD}{save_img}{hl.bold}") plt.show()
[docs] def Y0_theo(self, t, k, Y0, Yinf, binf): """ Model for Order 0 kinetics """ return np.where(t <= binf/(self.beta*k), Y0 + self.beta * k*t * (Yinf-Y0) / binf, Yinf)
[docs] def Y1_theo(self, t, k, Y0, Yinf): """Model for Order 1 kinetics""" return Yinf + np.exp(-self.alpha * k * t) * (Y0 - Yinf)
[docs] def Y2_theo(self, t, k, Y0, Yinf, binf): """Model for Order 2 kinetics""" # return np.where(t !=0, Y0 + (Yinf - Y0)/(1 + self.beta/(binf*self.alpha**2*k*t)), Y0) tterm = binf*self.alpha**2*k*t return Y0 + (Yinf-Y0)*tterm/(tterm+self.beta)
[docs] def concentrations(self,order,t,binf,k): """ 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. Args: 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: tuple: (a, b) where 'a' is the concentration array of reactant A and 'b' is the concentration array of product B. 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. """ import numpy as np a0 = binf*self.alpha/self.beta if order == 0: a = np.where(t <= a0/(self.alpha*k), a0 - self.alpha*k*t, 0) b = np.where(t <= binf/(self.beta*k), self.beta*k*t, binf) elif order == 1: a = a0 * np.exp(-self.alpha*k*t) b = binf * (1-np.exp(-self.alpha*k*t)) elif order == 2: a = 1 / (1/a0 + self.alpha*k*t) b = (binf*self.alpha)**2 * k*t/(self.beta + binf*self.alpha**2 * k*t) return a, b
[docs] def halflife(self,order, binf, k): """ 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). Args: order (int): Kinetic order (0, 1, or 2). k (float): The optimized or guessed rate constant. Returns: float: The calculated half-life value. 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. """ import numpy as np a0 = binf*self.alpha/self.beta if (order == 0): return a0/(2*self.alpha*k) elif (order == 1): return np.log(2)/(self.alpha*k) elif (order == 2): return 1/(self.alpha*k*a0)
[docs] def fit(self, order=1, fix_Y0=False, fix_Yinf=False): """ 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)``. Args: 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: dict: 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. 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. """ models = {0: self.Y0_theo, 1: self.Y1_theo, 2: self.Y2_theo} func = models[order] # smart guess for k n = max(2, len(self.t_exp) // 10) delta_G = abs(self.Y_exp[n] - self.Y_exp[0]) delta_t = self.t_exp[n] - self.t_exp[0] initial_slope = delta_G / delta_t if delta_t > 0 else 1e-5 # 2. Apply the smart guess logic delta_G_total = abs(self.Yinf_guess - self.Y0_guess) if delta_G_total == 0: delta_G_total = 1.0 norm_rate = initial_slope / delta_G_total if order == 0: k_start = (norm_rate * self.a0) / self.alpha elif order == 1: k_start = norm_rate / self.alpha elif order == 2: k_start = norm_rate / (self.alpha * self.a0) k_start = max(k_start, 1e-15) # Safety floor # Use the smart guess if k_guess wasn't explicitly provided by user final_k_guess = self.k_guess if self.k_guess is not None else k_start # --- Build the list of parameters, splitting it into the ones that # curve_fit is allowed to optimize ("free") and the ones held constant # ("fixed": Y0 and/or Yinf, on request). k is always free. binf is # NEVER a free fit parameter, for any order: mass balance already # fixes it at a0*beta/alpha (same formula used for order 1), so # letting it float too (as orders 0/2 used to) only adds a phantom, # non-identifiable degree of freedom — for a given k, the fit curve # depends on binf only through one combined ratio, so curve_fit can # trade k against binf along a whole family of equally-good pairs # without changing RMSE at all. Deriving binf everywhere removes # that degeneracy and keeps p (used in AIC/BIC) an honest count of # 3 free parameters for every order. binf_fixed = self.a0 * self.beta / self.alpha param_specs = [ ('k', final_k_guess, False, (0, np.inf)), ('Y0', self.Y0_guess, fix_Y0, (-np.inf, np.inf)), ('Yinf', self.Yinf_guess, fix_Yinf, (-np.inf, np.inf)), ] fixed_values = {name: guess for name, guess, fixed, _ in param_specs if fixed} free_specs = [(name, guess, bounds) for name, guess, fixed, bounds in param_specs if not fixed] free_names = [name for name, _, _ in free_specs] p0 = [guess for _, guess, _ in free_specs] lower_bounds = [b[0] for _, _, b in free_specs] upper_bounds = [b[1] for _, _, b in free_specs] def wrapped(t, *free_params): kwargs = dict(zip(free_names, free_params)) kwargs.update(fixed_values) if order != 1: return func(t, k=kwargs['k'], Y0=kwargs['Y0'], Yinf=kwargs['Yinf'], binf=binf_fixed) return func(t, k=kwargs['k'], Y0=kwargs['Y0'], Yinf=kwargs['Yinf']) if self.verbose: c = self.ansi_colors[order] print(f"{c}{hl.BOLD}--- Order {order} ---{self.reset}") tags = {'Y0': ' (fixed)' if fix_Y0 else '', 'Yinf': ' (fixed)' if fix_Yinf else ''} # Bold the parameters that are actually optimized (free); leave # the ones held fixed (fix_Y0/fix_Yinf) in normal weight, so a # glance at GUESS/OPTIM shows which numbers are allowed to move. def _field(label, value, spec, frozen): text = f"{label}: {value:{spec}}{tags.get(label, '')}" return text if frozen else f"{hl.BOLD}{text}{self.reset}" if order != 1: print(f" GUESS: {_field('k', final_k_guess, '.2e', False)} | " f"{_field('Y0', self.Y0_guess, '.4f', fix_Y0)} | " f"{_field('Yinf', self.Yinf_guess, '.4f', fix_Yinf)} | " f"{_field('binf', binf_fixed, '.3e', True)}") else: print(f" GUESS: {_field('k', final_k_guess, '.2e', False)} | " f"{_field('Y0', self.Y0_guess, '.4f', fix_Y0)} | " f"{_field('Yinf', self.Yinf_guess, '.4f', fix_Yinf)}") try: if free_specs: popt_free, _ = curve_fit(wrapped, self.t_exp, self.Y_exp, p0=p0, bounds=(lower_bounds, upper_bounds)) else: popt_free = np.array([]) full = dict(zip(free_names, popt_free)) full.update(fixed_values) k_opt, Y0_opt, Yinf_opt = full['k'], full['Y0'], full['Yinf'] binf_opt = binf_fixed if order != 1: Y_theo = func(self.t_exp, k=k_opt, Y0=Y0_opt, Yinf=Yinf_opt, binf=binf_opt) else: Y_theo = func(self.t_exp, k=k_opt, Y0=Y0_opt, Yinf=Yinf_opt) RMSE = rmse(self.Y_exp, Y_theo) R2 = r2(self.Y_exp, Y_theo) # t1/2 calculation t_half = self.halflife(order, binf_opt, k_opt) # AIC & BIC calculations # n: number of data points, p: number of FREE (actually optimized) parameters n = len(self.Y_exp) p = len(popt_free) # Using the simplified formula for AIC/BIC (assuming Gaussian errors) # RSS (Residual Sum of Squares) = RMSE^2 * n aic = n * np.log(RMSE**2) + 2 * p bic = n * np.log(RMSE**2) + p * np.log(n) if self.verbose: # Aligned exactly with the GUESS print for easy comparison; # same bold-if-free convention as GUESS above. if order != 1: print(f" OPTIM: {_field('k', k_opt, '.2e', False)} | " f"{_field('Y0', Y0_opt, '.4f', fix_Y0)} | " f"{_field('Yinf', Yinf_opt, '.4f', fix_Yinf)} | " f"{_field('binf', binf_opt, '.3e', True)}") else: print(f" OPTIM: {_field('k', k_opt, '.2e', False)} | " f"{_field('Y0', Y0_opt, '.4f', fix_Y0)} | " f"{_field('Yinf', Yinf_opt, '.4f', fix_Yinf)}") print(f" ✅ RMSE: {RMSE:.2e}") print(f" R2: {R2:.2f}") print(f" AIC: {aic:.2f} (lower is better)") print(f" BIC: {bic:.2f} (more strict on complexity)") self.results[order] = { 'k': k_opt, 'Y0': Y0_opt, 'Yinf': Yinf_opt, 'binf': binf_opt, 'RMSE': RMSE, 'R2': R2, 'AIC': aic, 'BIC': bic, 't_half': t_half, 'fix_Y0': fix_Y0, 'fix_Yinf': fix_Yinf, } return self.results[order] except Exception as e: print(f"Could not fit order {order}: {e}") return None
[docs] def plot_all_fits(self, save_img=None, fix_Y0=False, fix_Yinf=False): """ 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. """ mosaic = [['fit','o0'], ['fit','o1'], ['fit','o2']] cgraph = ['o0', 'o1', 'o2'] background_graph = ['#dbeeff', '#ffe4e4', '#d2ffdb'] Fig, Graph = plt.subplot_mosaic(mosaic, figsize=(14,10), gridspec_kw=dict(width_ratios = [1.4, 1])) # --- Check, before fitting/plotting anything, whether every order # will end up under the same fix_Y0/fix_Yinf conditions. An order # already cached in self.results keeps whatever conditions it was # originally fitted with (it is not re-fitted below); only orders # missing from self.results get fitted now, with the fix_Y0/fix_Yinf # passed to this call. conditions = [] for order in [0, 1, 2]: if order in self.results: conditions.append((order, self.results[order]['fix_Y0'], self.results[order]['fix_Yinf'], 'cached')) else: conditions.append((order, fix_Y0, fix_Yinf, 'fitted now')) mismatched = [c for c in conditions if c[3] == 'cached' and (c[1] != fix_Y0 or c[2] != fix_Yinf)] if mismatched: print(f"⚠️ Warning: not every order is fitted under the same fix_Y0/fix_Yinf " f"conditions (requested here: fix_Y0={fix_Y0}, fix_Yinf={fix_Yinf}) — " f"cached fit(s) were kept as-is, not re-fitted. Comparing orders on " f"this plot may be misleading:\n") print(f" {'Order':<7}{'fix_Y0':<9}{'fix_Yinf':<10}{'Source'}") print(f" {'-----':<7}{'------':<9}{'--------':<10}{'------'}") for order, g0, ginf, src in conditions: print(f" {order:<7}{str(g0):<9}{str(ginf):<10}{src}") print() ## Fit ############### Graph['fit'].scatter(self.t_exp, self.Y_exp, label=f"Experimental ($a_0$ = {self.a0:.2e})", color='black', marker="x", s=35, alpha=0.7) t_smooth = np.linspace(self.t_exp.min(), self.t_exp.max(), 500) models = {0: self.Y0_theo, 1: self.Y1_theo, 2: self.Y2_theo} for order in [0, 1, 2]: if order not in self.results: self.fit(order, fix_Y0=fix_Y0, fix_Yinf=fix_Yinf) res = self.results[order] if order != 1: Y_smooth = models[order](t_smooth, res['k'], res['Y0'], res['Yinf'], res['binf']) else: Y_smooth = models[order](t_smooth, res['k'], res['Y0'], res['Yinf']) Graph['fit'].plot(t_smooth, Y_smooth, label=f"Order {order}. $k_\mathrm{{app}}$ = {res['k']:.4e} (RMSE: {res['RMSE']:.2e})", color=self.order_colors[order], lw=2) a, b = self.concentrations(order,t_smooth,res['binf'],res['k']) Graph[cgraph[order]].plot(t_smooth,a,linestyle="-",marker="",markersize=12,label="$a(t)$",linewidth=2) Graph[cgraph[order]].plot(t_smooth,b,linestyle="-",marker="",markersize=12,label="$b(t)$",linewidth=2) Graph[cgraph[order]].set_xlim(left=t_smooth[0], right=None) binf = res['binf'] Graph[cgraph[order]].set_title(f"order {order}. $t_{{1/2}}$ = {res['t_half']:.1f}. $b_{{\infty}}$ = {binf:.2e} mol.L$^{-1}$",fontweight="bold",color='blue',fontsize=10) Graph[cgraph[order]].legend(fontsize=12) Graph[cgraph[order]].yaxis.set_major_formatter(mtick.FormatStrFormatter('%.1e')) Graph[cgraph[order]].set_facecolor(background_graph[order]) # Add a vertical line at t1/2 on each concentration graph Graph[cgraph[order]].axvline(res['t_half'], color=self.order_colors[order], linestyle='--', alpha=0.6) Graph['o1'].set_ylabel("C / mol.L$^{-1}$",size=12,weight='bold',color='b') Graph['o2'].set_xlabel(f"Time",size=12,weight='bold',color='b') # Add horizontal lines for the BEST model on the "fit" graph best_order = self.get_best_order(verbose=False) best_res = self.results[best_order] best_color = self.order_colors[best_order] Graph['fit'].axhline(best_res['Y0'], color=best_color, linestyle='--', alpha=0.6) Graph['fit'].axhline(best_res['Yinf'], color=best_color, linestyle='--', alpha=0.6) Graph['fit'].yaxis.grid( True, which='major', linestyle='--', # Ligne hachurée linewidth=0.8, # Épaisseur color='gray', # Couleur discrète alpha=0.5 # Transparence pour ne pas surcharger ) # Désactiver la grille verticale (optionnel, pour garder le focus sur Y) Graph['fit'].xaxis.grid(False) # Add the second axis for the fitted values ax2 = Graph['fit'].twinx() ax2.set_ylim(Graph['fit'].get_ylim()) # Keep scales aligned ax2.set_yticks([best_res['Y0'], best_res['Yinf']]) ax2.set_yticklabels([f"Y0_fit={best_res['Y0']:.3f}", f"Yinf_fit={best_res['Yinf']:.3f}"]) ax2.tick_params(axis='y', labelcolor=best_color) Graph['fit'].set_xlabel("Time",size=12,fontweight='bold',color='b') Graph['fit'].set_ylabel("Y property",size=12,fontweight='bold',color='b') Graph['fit'].set_title(f"KORD Kinetic Models Comparison (0, 1, 2). Label exp = {self.headers[1]}") plt.setp(Graph['fit'].get_xticklabels(), fontsize=12, fontweight='bold') plt.setp(Graph['fit'].get_yticklabels(), fontsize=12, fontweight='bold') Graph['fit'].legend() plt.tight_layout() if save_img: # Check if the file already exists to prevent accidental overwrite if os.path.exists(save_img): # Prompt the user for confirmation print(f"{color.RED}{hl.BOLD}⚠️ File '{save_img}' already exists. Overwrite? (y/n): {color.OFF}", end="") # Then call input response = input().lower().strip() if response != 'y': print("💾 Save cancelled. Plot not saved.") plt.show() # Display anyway without saving return # Exit the save logic # Security: ensure the target directory exists (e.g., if save_img="export/graph.svg") directory = os.path.dirname(save_img) if directory and not os.path.exists(directory): os.makedirs(directory) # Universal save (supports SVG, PNG, PDF, etc. based on extension) # bbox_inches='tight' prevents labels or secondary axes from being cropped plt.savefig(save_img, dpi=300, bbox_inches='tight') print(f"💾 Plot saved as: {hl.BOLD}{save_img}{hl.bold}") plt.show()
[docs] def get_best_order(self, verbose=True): """Determines and prints the best model based on the lowest RMSE.""" for i in [0, 1, 2]: if i not in self.results: self.fit(i) best_order = min(self.results, key=lambda x: self.results[x]['RMSE']) res = self.results[best_order] if verbose: # ANSI Escape sequences for color in terminal/notebook reset = self.reset color = self.ansi_colors[best_order] print(f"{hl.BOLD}{color}--- KORD CONCLUSION ---{hl.bold}") print(f"{hl.BOLD}Best model: ORDER {best_order}{hl.bold}") print(f"Initial concentration a0: {self.a0:.3e} mol.L-1") if best_order != 1: print(f"Fitted final concentration (b_inf): {res['binf']:.3e} mol.L-1") print(f"a0 after binf = [B](inf): {res['binf']*self.alpha/self.beta:.3e} mol.L-1") print(f"alpha: {self.alpha}") print(f"beta: {self.beta}") print() print(f"{hl.BOLD}metrics{hl.bold}") print(f"RMSE: {res['RMSE']:.3f}") print(f" R2: {res['R2']:.3f}") print() print(f"Y_exp(t=0): {self.Y_exp[0]:.3e}") print(f"Y_fit(t=0): {res['Y0']:.3e}") print(f"Y_fit(t=inf): {res['Yinf']:.3e}") print() print(f"k_fit: {res['k']:.3e}") print(f"t1/2: {res['t_half']:.3f}") print(f"------------------------{reset}") # Sort results by BIC to find the top two candidates sorted_orders = sorted(self.results.keys(), key=lambda x: self.results[x]['BIC']) best = sorted_orders[0] second = sorted_orders[1] delta_bic = self.results[second]['BIC'] - self.results[best]['BIC'] # Scientific interpretation of Delta BIC if delta_bic < 2: verdict = "Weak/Inconclusive" elif delta_bic < 6: verdict = "Positive" elif delta_bic < 10: verdict = "Strong" else: verdict = "Decisive" if verbose: print(f"\n{hl.BOLD}--- Final Statistical Verdict ---{hl.bold}") print(f"Model Selection Confidence: {verdict}") print(f"ΔBIC (Best [order {best}] vs 2nd Best [order {second}]): {delta_bic:.2f}") print(f"--------------------------------{self.reset}") return else: return best_order
# ===================================================================== # Comparing several KORD studies on the same graph # =====================================================================
[docs] def superpose_plots(studies, order=1, show_experimental=True, labels=None, fix_Y0=False, fix_Yinf=False, save_img=None): """ 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. Args: 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, 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(). """ plt.figure(figsize=(10, 6)) models = {0: 'Y0_theo', 1: 'Y1_theo', 2: 'Y2_theo'} for i, study in enumerate(studies): base_label = labels[i] if labels else f"Study {i + 1}" if order in study.results: cached_fix_Y0 = study.results[order]['fix_Y0'] cached_fix_Yinf = study.results[order]['fix_Yinf'] if cached_fix_Y0 != fix_Y0 or cached_fix_Yinf != fix_Yinf: print(f"⚠️ {base_label}: using the cached order-{order} fit " f"(fix_Y0={cached_fix_Y0}, fix_Yinf={cached_fix_Yinf}), " f"not the fix_Y0={fix_Y0}, fix_Yinf={fix_Yinf} requested here.") else: study.fit(order, fix_Y0=fix_Y0, fix_Yinf=fix_Yinf) res = study.results[order] func = getattr(study, models[order]) t_sim = np.linspace(study.t_exp.min(), study.t_exp.max(), 500) if order != 1: Y_sim = func(t_sim, k=res['k'], Y0=res['Y0'], Yinf=res['Yinf'], binf=res['binf']) else: Y_sim = func(t_sim, k=res['k'], Y0=res['Y0'], Yinf=res['Yinf']) tags = [tag for tag, fixed in (("Y0 fixed", res['fix_Y0']), ("Yinf fixed", res['fix_Yinf'])) if fixed] tag_str = f" ({', '.join(tags)})" if tags else " (free fit)" label = f"{base_label}{tag_str} — Order {order}" line, = plt.plot(t_sim, Y_sim, lw=2.5, label=label) if show_experimental and study.t_exp is not None: plt.scatter(study.t_exp, study.Y_exp, marker="x", s=35, alpha=0.7, color=line.get_color(), label=f"{base_label} — Experimental") plt.xlabel("Time") plt.ylabel("Y property") plt.title(f"Order {order} — fitted curves compared across studies") plt.legend() plt.grid(True, linestyle=':', alpha=0.6) if save_img: if os.path.exists(save_img): print(f"{color.RED}{hl.BOLD}⚠️ File '{save_img}' already exists. Overwrite? (y/n): {color.OFF}", end="") response = input().lower().strip() if response != 'y': print("💾 Save cancelled. Plot not saved.") plt.show() return directory = os.path.dirname(save_img) if directory and not os.path.exists(directory): os.makedirs(directory) plt.savefig(save_img, dpi=300, bbox_inches='tight') print(f"💾 Plot saved as: {hl.BOLD}{save_img}{hl.bold}") plt.show()
# ===================================================================== # ReactionNetwork: general, numerically-integrated chemical kinetics. # # kbasic and KORD both rely on closed-form integrated rate laws, valid # only for a single reactant -> single product transformation of order # 0, 1 or 2. ReactionNetwork drops that restriction: it builds the # system of ODEs for an *arbitrary* set of (ir)reversible elementary # reactions straight from mass-action kinetics, integrates it # numerically (scipy.integrate.solve_ivp), and fits rate constants # against experimental data the same way KORD does -- a measured # signal Y_EXP(t) as a linear combination of concentrations, # Y_EXP(t) = sum_i eta_i * C_i(t) (see Kinetics.md, 4.2.1). # # This subsumes parallel reactions (A->B, A->C), consecutive reactions # (A->B->C, the Bateman equations), reversible reactions (A<=>B), and # anything built out of those as a network -- and lets the quasi-steady- # state approximation be checked numerically against the exact solution # instead of only illustrated on a closed-form special case. # ===================================================================== def _normalize_species_name(name): """Strips accents (NFKD decomposition, dropping the combining marks -- "e" with an acute accent becomes a plain "e", etc., covering e/a/o/i/u with any accent) and forces the first character to uppercase; every other character is left exactly as typed. This only normalizes a single spelling in isolation ("ethylene" -> "Ethylene", a convenience for a lazily-typed lowercase name). It deliberately does NOT title-case the rest of the name the way an earlier version of this function did: that mangled a short chemical formula with no digit in it -- "NO" (nitric oxide), "CO", "OH", "HCl", "HCN"... -- into something like "No", indistinguishable from the element symbol for Nobelium. There is no way to tell from the text alone whether an all-letters name is a formula or a spelled-out word, so this function now never lowercases a letter the caller actually typed in uppercase. Recognizing the same species across different spellings ("ethylene" vs "ETHYLENE" vs "Ethylene", or "NO" vs "no") is handled separately and case-insensitively, by the per-network canonical-name registry in `ReactionNetwork._canonical_species()` -- see there.""" decomposed = unicodedata.normalize('NFKD', name) stripped = ''.join(c for c in decomposed if not unicodedata.combining(c)) if not stripped: return stripped return stripped[0].upper() + stripped[1:] def _parse_reaction_side(side, equation): """Parses one side of a reaction equation (left or right of the arrow) into a {species: stoichiometric_coefficient} dict. Terms are separated by '+'; each term is an optional integer coefficient followed by a species name, e.g. "2 B", "H2O", or a single-word Unicode name such as "ethylene" (accents included, e.g. "cyclobutane"). A species name cannot contain a space -- alias a multi-word compound to a short symbol first (A = ethylene, B = butadiene, then "2 A -> B"), exactly as on paper with A, B, C... Every name is run through `_normalize_species_name()` (accents stripped, first letter forced uppercase). Recognizing "2 ethylene -> cyclobutane" and "2 Ethylene -> Cyclobutane" (or "2 ETHYLENE -> CYCLOBUTANE") as the exact same reaction -- without ever mangling a short formula like "NO" or "HCl" in the process -- is handled case-insensitively one level up, in `ReactionNetwork.add_reaction()`. """ terms = {} for term in side.split("+"): term = term.strip() if not term: continue # First character: anything but a digit or whitespace (so a # leading coefficient is unambiguous); rest: any Unicode "word" # character (\w matches accented letters too for str patterns). m = re.match(r'^(\d+)?\s*([^\d\s]\w*)$', term, flags=re.UNICODE) if not m: raise ValueError( f"Could not parse term '{term}' in reaction '{equation}'. " f"Expected e.g. 'A', '2 B', 'H2O', 'ethylene' (a single " f"word -- no space -- optionally preceded by an integer " f"coefficient). For a multi-word compound, alias it to a " f"symbol first, e.g. A = ethylene, then write '2 A -> B'." ) coeff = int(m.group(1)) if m.group(1) else 1 species = _normalize_species_name(m.group(2)) terms[species] = terms.get(species, 0) + coeff if not terms: raise ValueError(f"Empty side in reaction '{equation}'.") return terms def _parse_reaction(equation): """Parses a reaction equation such as "A + 2 B -> C" (irreversible) or "A <=> B" (reversible) into (reactants, products, reversible).""" if "<=>" in equation: left, right = equation.split("<=>") reversible = True elif "->" in equation: left, right = equation.split("->") reversible = False else: raise ValueError( f"Reaction '{equation}' has no arrow: use '->' (irreversible) " f"or '<=>' (reversible)." ) reactants = _parse_reaction_side(left, equation) products = _parse_reaction_side(right, equation) return reactants, products, reversible
[docs] class ReactionNetwork: """ 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(). """ def __init__(self, verbose=True): self.species = [] self.reactions = [] self.C0 = None self.k_fit = None self.results = None self.verbose = verbose self._idx_of = {} self._canon_of = {} # case-insensitive species registry, see _canonical_species() self._initialized = True # see __setattr__ below def __setattr__(self, name, value): """Same typo guard as kbasic/KORD: once built, no new attribute can be created, only existing ones can be changed -- catches a misspelled attribute instead of silently creating it.""" if getattr(self, '_initialized', False) and name not in self.__dict__: existing = ', '.join(sorted(k for k in self.__dict__ if not k.startswith('_'))) raise AttributeError( f"ReactionNetwork has no attribute '{name}' (possible typo?). " f"Existing attributes: {existing}" ) object.__setattr__(self, name, value)
[docs] def copy(self): """ 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 """ return _copy.deepcopy(self)
def _canonical_species(self, raw_name, register=True): """Resolves a parsed/user-supplied species name to this network's canonical spelling for that species, matching case-insensitively (after `_normalize_species_name()`'s accent-stripping) against every species already known to this network: "ethylene", "ETHYLENE" and "Ethylene" all resolve to whichever spelling was registered first, and so do "NO" and "no" -- without ever lowercasing a letter the caller typed in uppercase (that was the earlier bug: it turned the formula "NO" into "No", identical to the symbol for Nobelium). ``register=True`` (the default, used for a reaction's own reactants/products): if this is the first time this species is seen, its (accent-stripped, first-letter-capitalized) spelling becomes the canonical one going forward. ``register=False`` (used for `order`/`order_back`, which must refer to species already declared by the very same reaction): an unseen name is returned as-is, without being added to the registry -- it's about to fail the "is this one of this reaction's reactants/products" check in `add_reaction()` anyway, and shouldn't leave a stray entry behind. """ name = _normalize_species_name(raw_name) key = name.upper() if key in self._canon_of: return self._canon_of[key] if register: self._canon_of[key] = name return name
[docs] def add_reaction(self, equation, k_guess=None, kf_guess=None, kr_guess=None, order=None, order_back=None): """ 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)``. Args: 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, 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. """ reactants, products, reversible = _parse_reaction(equation) # Resolve every species name against this network's case-insensitive # registry, so "ethylene"/"ETHYLENE"/"Ethylene" (or "NO"/"no") all # land on the same species, however they were typed in a previous # add_reaction() call -- see _canonical_species()'s docstring. def _merge_canonical(terms): merged = {} for sp, c in terms.items(): canon = self._canonical_species(sp, register=True) merged[canon] = merged.get(canon, 0) + c return merged reactants = _merge_canonical(reactants) products = _merge_canonical(products) if order is not None: order = {self._canonical_species(sp, register=False): v for sp, v in order.items()} if order_back is not None: order_back = {self._canonical_species(sp, register=False): v for sp, v in order_back.items()} if order is not None and not set(order) <= set(reactants): raise ValueError( f"order={order} refers to species not among this reaction's " f"reactants {list(reactants)} (equation: '{equation}')." ) if order_back is not None: if not reversible: raise ValueError("order_back only applies to a reversible ('<=>') reaction.") if not set(order_back) <= set(products): raise ValueError( f"order_back={order_back} refers to species not among this " f"reaction's products {list(products)} (equation: '{equation}')." ) for sp in list(reactants) + list(products): if sp not in self.species: self.species.append(sp) self._idx_of = {sp: i for i, sp in enumerate(self.species)} # Default kinetic order = stoichiometric coefficient (elementary # mass action); an explicit `order`/`order_back` overrides it, # species by species. fwd_order = dict(reactants) fwd_order.update(order or {}) back_order = dict(products) back_order.update(order_back or {}) idx = len(self.reactions) + 1 if reversible: kf_guess = kf_guess if kf_guess is not None else (k_guess if k_guess is not None else 1.0) kr_guess = kr_guess if kr_guess is not None else 1.0 reaction = { 'equation': equation, 'reactants': reactants, 'products': products, 'reversible': True, 'order': fwd_order, 'order_back': back_order, 'kf_name': f"k{idx}", 'kr_name': f"k-{idx}", 'kf_guess': kf_guess, 'kr_guess': kr_guess, } if self.verbose: print(f" Reaction {idx} (reversible): {equation} " f"[kf_guess={kf_guess:.3g}, kr_guess={kr_guess:.3g}]") else: k_guess = k_guess if k_guess is not None else 1.0 reaction = { 'equation': equation, 'reactants': reactants, 'products': products, 'reversible': False, 'order': fwd_order, 'k_name': f"k{idx}", 'k_guess': k_guess, } if self.verbose: print(f" Reaction {idx}: {equation} [k_guess={k_guess:.3g}]") self.reactions.append(reaction)
[docs] def overall_equation(self): """ 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). """ net = {sp: 0 for sp in self.species} for r in self.reactions: for sp, c in r['reactants'].items(): net[sp] -= c for sp, c in r['products'].items(): net[sp] += c def fmt(sp, c): return sp if c == 1 else f"{c} {sp}" left = [fmt(sp, -net[sp]) for sp in self.species if net[sp] < 0] right = [fmt(sp, net[sp]) for sp in self.species if net[sp] > 0] if not left or not right: return ("(every species cancels out -- the declared steps sum " "to no net change at all)") return f"{' + '.join(left)} -> {' + '.join(right)}"
[docs] def set_initial_conditions(self, conditions): """ 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``). """ missing = [sp for sp in self.species if sp not in conditions] if missing and self.verbose: print(f"⚠️ No initial concentration given for {missing}; " f"defaulting to 0.0.") self.C0 = np.array([conditions.get(sp, 0.0) for sp in self.species], dtype=float)
def _param_specs(self): """Ordered list of (parameter_name, starting_guess) across every reaction -- one entry for an irreversible reaction's k, two (kf, kr) for a reversible one.""" specs = [] for r in self.reactions: if r['reversible']: specs.append((r['kf_name'], r['kf_guess'])) specs.append((r['kr_name'], r['kr_guess'])) else: specs.append((r['k_name'], r['k_guess'])) return specs def _rhs(self, t, C, k_map): """Right-hand side of the mass-action ODE system, dC/dt, given the current concentration vector C and a {param_name: value} mapping of rate constants. The stoichiometric coefficients (reactants/products) always drive the mass-balance update of dC; the kinetic order used in the rate law itself comes from each reaction's 'order'/ 'order_back' dict, which defaults to those same stoichiometric coefficients (elementary mass action) but can be overridden per-species via add_reaction(order=..., order_back=...).""" dC = np.zeros(len(self.species)) for r in self.reactions: rate_f = k_map[r['kf_name'] if r['reversible'] else r['k_name']] for sp, exp in r['order'].items(): rate_f *= C[self._idx_of[sp]] ** exp rate_net = rate_f if r['reversible']: rate_b = k_map[r['kr_name']] for sp, exp in r['order_back'].items(): rate_b *= C[self._idx_of[sp]] ** exp rate_net = rate_f - rate_b for sp, coeff in r['reactants'].items(): dC[self._idx_of[sp]] -= coeff * rate_net for sp, coeff in r['products'].items(): dC[self._idx_of[sp]] += coeff * rate_net return dC def _gross_rhs(self, t, C, k_map): """Like _rhs, but also returns, for each species, the sum of the *absolute* contribution of every reaction touching it (gross flux, counting production and consumption as positive) -- used by qssa_check() to judge whether net change is small compared to how much is actually flowing through a species.""" dC = np.zeros(len(self.species)) gross = np.zeros(len(self.species)) for r in self.reactions: rate_f = k_map[r['kf_name'] if r['reversible'] else r['k_name']] for sp, exp in r['order'].items(): rate_f *= C[self._idx_of[sp]] ** exp rate_net = rate_f if r['reversible']: rate_b = k_map[r['kr_name']] for sp, exp in r['order_back'].items(): rate_b *= C[self._idx_of[sp]] ** exp rate_net = rate_f - rate_b for sp, coeff in r['reactants'].items(): dC[self._idx_of[sp]] -= coeff * rate_net gross[self._idx_of[sp]] += abs(coeff * rate_net) for sp, coeff in r['products'].items(): dC[self._idx_of[sp]] += coeff * rate_net gross[self._idx_of[sp]] += abs(coeff * rate_net) return dC, gross
[docs] def simulate(self, t, k_values=None): """ Integrates the ODE system and returns each species' concentration at the requested time points. Args: 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: dict: {species_name: numpy array of concentrations at `t`}. """ if self.C0 is None: raise RuntimeError("Call set_initial_conditions() before simulate().") specs = self._param_specs() if k_values is None: k_map = {name: (self.k_fit[name] if self.k_fit is not None else guess) for name, guess in specs} elif isinstance(k_values, dict): k_map = k_values else: k_map = {name: val for (name, _), val in zip(specs, k_values)} t = np.asarray(t, dtype=float) order = np.argsort(t) t_sorted = t[order] t0 = min(0.0, t_sorted[0]) sol = solve_ivp(lambda tt, C: self._rhs(tt, C, k_map), (t0, t_sorted[-1]), self.C0, t_eval=t_sorted, method="LSODA", rtol=1e-8, atol=1e-12) if not sol.success: raise RuntimeError(f"ODE integration failed: {sol.message}") inv_order = np.argsort(order) return {sp: sol.y[i][inv_order] for i, sp in enumerate(self.species)}
[docs] def qssa_check(self, species, t, k_values=None): """ 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. Args: 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: numpy array: the QSSA ratio at each time in ``t`` (same order as given, not necessarily sorted). """ if species not in self.species: raise ValueError(f"Unknown species '{species}'; known: {self.species}") if self.C0 is None: raise RuntimeError("Call set_initial_conditions() before qssa_check().") specs = self._param_specs() if k_values is None: k_map = {name: (self.k_fit[name] if self.k_fit is not None else guess) for name, guess in specs} elif isinstance(k_values, dict): k_map = k_values else: k_map = {name: val for (name, _), val in zip(specs, k_values)} t = np.asarray(t, dtype=float) C_at_t = self.simulate(t, k_values=k_map) idx = self._idx_of[species] ratio = np.empty(len(t)) for i in range(len(t)): C_vec = np.array([C_at_t[sp][i] for sp in self.species]) dC, gross = self._gross_rhs(t[i], C_vec, k_map) ratio[i] = abs(dC[idx]) / gross[idx] if gross[idx] > 0 else 0.0 return ratio
[docs] def fit(self, t_exp, Y_exp, weights=None, observed_species=None): """ 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). Args: t_exp, 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: dict: {'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). """ if observed_species is not None: if weights is not None: raise ValueError("Pass only one of weights= or observed_species=.") weights = {observed_species: 1.0} if weights is None: raise ValueError("Specify either weights={...} or observed_species='X'.") specs = self._param_specs() names = [name for name, _ in specs] p0 = [guess for _, guess in specs] t_exp = np.asarray(t_exp, dtype=float) Y_exp = np.asarray(Y_exp, dtype=float) def model(t, *k_vals): k_map = dict(zip(names, k_vals)) C = self.simulate(t, k_values=k_map) return sum(w * C[sp] for sp, w in weights.items()) popt, _ = curve_fit(model, t_exp, Y_exp, p0=p0, bounds=(0, np.inf)) k_opt = dict(zip(names, popt)) Y_theo = model(t_exp, *popt) RMSE_ = rmse(Y_exp, Y_theo) R2_ = r2(Y_exp, Y_theo) n, p = len(Y_exp), len(popt) aic = n * np.log(RMSE_**2) + 2 * p bic = n * np.log(RMSE_**2) + p * np.log(n) self.k_fit = k_opt self.results = {'k': k_opt, 'RMSE': RMSE_, 'R2': R2_, 'AIC': aic, 'BIC': bic, 'weights': weights} if self.verbose: k_str = ", ".join(f"{name}={val:.4g}" for name, val in k_opt.items()) print(f" FIT: {k_str}") print(f" ✅ RMSE: {RMSE_:.2e}") print(f" R2: {R2_:.2f}") print(f" AIC: {aic:.2f}") print(f" BIC: {bic:.2f}") return self.results
[docs] def plot(self, t_exp=None, Y_exp=None, t_max=None, log_scale=False, time_unit=None, species=None, save_img=None): """ 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. """ if species is None: species = self.species else: unknown = [sp for sp in species if sp not in self.species] if unknown: raise ValueError(f"Unknown species {unknown}; known species: {self.species}") if t_max is None: if t_exp is not None: t_max = float(np.max(t_exp)) else: raise ValueError("Pass t_max, or t_exp to infer it from.") t_grid = np.linspace(0.0, t_max, 300) C = self.simulate(t_grid) plt.figure(figsize=(8, 5)) for sp in species: plt.plot(t_grid, C[sp], lw=2.5, label=sp) if t_exp is not None and Y_exp is not None: if self.results is not None: label = "Experimental (" + " + ".join( f"{w:.2g}·{sp}" if w != 1 else sp for sp, w in self.results['weights'].items()) + ")" else: label = "Experimental" plt.scatter(t_exp, Y_exp, color='black', marker='x', s=35, alpha=0.7, zorder=5, label=label) plt.xlabel(f"Time / {time_unit}" if time_unit else "Time") plt.ylabel("Concentration") if log_scale: plt.yscale("log") plt.title("Reaction network simulation") plt.legend() plt.grid(True, linestyle=':', alpha=0.6) if save_img: if os.path.exists(save_img): print(f"{color.RED}{hl.BOLD}⚠️ File '{save_img}' already exists. Overwrite? (y/n): {color.OFF}", end="") response = input().lower().strip() if response != 'y': print("💾 Save cancelled. Plot not saved.") plt.show() return directory = os.path.dirname(save_img) if directory and not os.path.exists(directory): os.makedirs(directory) plt.savefig(save_img, dpi=300, bbox_inches='tight') print(f"💾 Plot saved as: {hl.BOLD}{save_img}{hl.bold}") plt.show()
[docs] def plot_qssa(self, species, t, threshold=0.1, time_unit=None, save_img=None): """ 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. """ t = np.asarray(t, dtype=float) order = np.argsort(t) t_sorted = t[order] C = self.simulate(t_sorted) ratio = self.qssa_check(species, t_sorted) fig, (ax_C, ax_r) = plt.subplots(2, 1, figsize=(8, 7), sharex=True, gridspec_kw={'height_ratios': [1.3, 1]}) for sp in self.species: lw = 3.0 if sp == species else 1.5 alpha = 1.0 if sp == species else 0.5 ax_C.plot(t_sorted, C[sp], lw=lw, alpha=alpha, label=sp) ax_C.set_ylabel("Concentration") ax_C.set_title(f"Quasi-steady-state check for '{species}'") ax_C.legend() ax_C.grid(True, linestyle=':', alpha=0.6) ax_r.axhspan(0, threshold, color='green', alpha=0.15, label=f"QSSA valid (ratio < {threshold:g})") ax_r.plot(t_sorted, ratio, color='black', lw=2.0) ax_r.set_xlabel(f"Time / {time_unit}" if time_unit else "Time") ax_r.set_ylabel(f"QSSA ratio for '{species}'") ax_r.set_ylim(0, max(1.0, float(np.max(ratio)) * 1.05)) ax_r.legend() ax_r.grid(True, linestyle=':', alpha=0.6) if save_img: if os.path.exists(save_img): print(f"{color.RED}{hl.BOLD}⚠️ File '{save_img}' already exists. Overwrite? (y/n): {color.OFF}", end="") response = input().lower().strip() if response != 'y': print("💾 Save cancelled. Plot not saved.") plt.show() return directory = os.path.dirname(save_img) if directory and not os.path.exists(directory): os.makedirs(directory) plt.savefig(save_img, dpi=300, bbox_inches='tight') print(f"💾 Plot saved as: {hl.BOLD}{save_img}{hl.bold}") plt.show()
[docs] def summary(self): """Prints each reaction with its (fitted, if available, else guessed) rate constant(s).""" for i, r in enumerate(self.reactions, start=1): if r['reversible']: kf = self.k_fit[r['kf_name']] if self.k_fit else r['kf_guess'] kr = self.k_fit[r['kr_name']] if self.k_fit else r['kr_guess'] tag = "fitted" if self.k_fit else "guess" print(f" {i}. {r['equation']} {r['kf_name']}={kf:.4g} ({tag}), " f"{r['kr_name']}={kr:.4g} ({tag})") else: k = self.k_fit[r['k_name']] if self.k_fit else r['k_guess'] tag = "fitted" if self.k_fit else "guess" print(f" {i}. {r['equation']} {r['k_name']}={k:.4g} ({tag})")