API Reference

Module: radigen3.oxidation.py

Core module for radical oxidation modeling within the Generative Simulation Initiative.

This kernel supports the generative construction, parameterization, and simulation of oxidation reaction networks in chemically diverse mixtures, such as edible oils, FAMEs, fuels, and polymers. The oxidation model is built from chemical species annotated with reactive functions and product maps. Radical propagation, decomposition, and termination pathways are handled automatically, including temperature effects and diffusion-limited corrections.

Features:

Auto-generation of all relevant reaction species and products from labile H donors.
Rule-based reaction network construction with automatic cross-reaction inference.
Temperature-dependent Arrhenius and Smoluchowski kinetics.
Support for hydroperoxide decomposition equilibrium (free vs. cage).
Stoichiometric matrix generation and fast vectorized ODE solving.
Oxygen dissolution modeled as a transport-limited source term.
Support for hundreds of reactions and species from text prompts.
Support arbitrary lumped species.

LLM compatibility:

This module is designed to be a kernel for Large Language Models (LLMs) that can reason about and manipulate chemical mixtures and reaction systems from natural language. The full system is composable, traceable, and extensible.

Key References: [2] Touffet M., Vitrac O. (2025), “Temperature-dependent kinetics of unsaturated fatty acid methyl esters:

Modeling autoxidation mechanisms”, Food Chemistry, 481, 143952. https://doi.org/10.1016/j.foodchem.2025.143952

[1] Touffet M., Smith P., Vitrac O. (2023), “A comprehensive two-scale model for predicting the oxidizability: of fatty acid methyl ester mixtures”, Food Research International, 173(1), 113289. https://doi.org/10.1016/j.foodres.2023.113289

Author: Olivier Vitrac — olivier.vitrac@gmail.com Revision: 2025-05-13

class radigen3.oxidation.H2O(**kwargs)

Bases: species

Water class (stable)

allylic = 0

classAliases = ['H2O']

className = 'water'

defaultName = 'H2O'

defaultRoot = ''

freevalence = 0

freevalenceHolder = None

interpretation = 'stable water'

oxidationState = 0

product = None

reactWith = None

reactiveFunction = 'None'

suffix = 'H2O'

class radigen3.oxidation.PrintableFigure(figsize=None, dpi=None, *, facecolor=None, edgecolor=None, linewidth=0.0, frameon=None, subplotpars=None, tight_layout=None, constrained_layout=None, layout=None, **kwargs)

Bases: Figure

Custom Figure class with show and print methods.

print(filename='', destinationfolder='/home/olivi/maxime/radigen/docs_sphinx/source', overwrite=True, dpi={'pdf': 300, 'png': 150})

print_pdf(filename='', destinationfolder='/home/olivi/maxime/radigen/docs_sphinx/source', overwrite=False, dpi=300)

print_png(filename='', destinationfolder='/home/olivi/maxime/radigen/docs_sphinx/source', overwrite=False, dpi=300)

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, canvas=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, constrained_layout=<UNSET>, constrained_layout_pads=<UNSET>, dpi=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, figheight=<UNSET>, figwidth=<UNSET>, frameon=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, layout_engine=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, size_inches=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, tight_layout=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or None animated: bool canvas: FigureCanvas clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None constrained_layout: unknown constrained_layout_pads: unknown dpi: float edgecolor: :mpltype:`color` facecolor: :mpltype:`color` figheight: float figure: unknown figwidth: float frameon: bool gid: str in_layout: bool label: object layout_engine: {‘constrained’, ‘compressed’, ‘tight’, ‘none’, .LayoutEngine, None} linewidth: number mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool size_inches: (float, float) or float sketch_params: (scale: float, length: float, randomness: float) snap: bool or None tight_layout: unknown transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

show(display_mode=None): Show figure based on the environment: - In Jupyter: Uses display(fig) - In scripts or GUI mode: Uses plt.show()

class radigen3.oxidation.TKO2cycle(times, T_values, kO2_values)

Bases: object

Class to define temperature (T) and oxygenation (kO2) cycles over time.

Supports:

Constant values
Linear ramps between two values
Multiple steps combined using +

Each cycle defines:

T(t): temperature in Celsius
kO2(t): oxygen mass transfer coefficient [m/s]

Example

cycle = TKO2cycle.constant(60, 1e-5, duration=2*3600) + TKO2cycle.ramp(60, 80, 1e-5, 2e-5, duration=1*3600)

property T: T(t) interpolant at t as an anonymous function

classmethod constant(T, kO2, duration): generate an holding step for T and kO2

property kO2: kO2(t) interpolation at t as an anonymous function

classmethod ramp(T, kO2, duration): generate a ramp from pair values of T and kO2

radigen3.oxidation.custom_plt_figure(*args, **kwargs): Ensure all figures use PrintableFigure.

radigen3.oxidation.custom_plt_subplots(*args, **kwargs): Ensure plt.subplots() returns a PrintableFigure.

class radigen3.oxidation.diAllylicC(**kwargs)

Bases: species

Alkyl radical (C•) on diallylic site

allylic = 2

classAliases = ['C2', 'R2', 'L2', 'P2']

className = 'alkyl radical on diallylic site'

defaultName = 'L2•'

defaultRoot = 'L2'

freevalence = 1

freevalenceHolder = 'C'

interpretation = 'O2 addition'

oxidationState = 0

product = ['diAllylicCOO', 'terminationPolymers', 'terminationPolymers']

reactWith = ['•OO•', 'C•', 'COO•']

reactiveFunction = 'C•'

suffix = '•'

class radigen3.oxidation.diAllylicCH(**kwargs)

Bases: species

Aliphatic (CH) on diallylic site

allylic = 2

classAliases = ['C2H', 'R2H', 'L2H', 'P2H']

className = 'aliphatic with diallylic C-H'

defaultName = 'L2H'

defaultRoot = 'L2'

freevalence = 0

freevalenceHolder = None

interpretation = 'labile H abstraction'

oxidationState = -0.5

product = ['diAllylicC']

reactWith = ['HO•', 'CO•', 'COO•']

reactiveFunction = 'CH'

suffix = 'H'

class radigen3.oxidation.diAllylicCHO(**kwargs)

Bases: species

Aldehyde (CHO) on diallylic site (stable)

allylic = 2

classAliases = ['C2=O', 'R2=O', 'L2=O', 'P2=O']

className = 'aldehyde on diallylic site'

defaultName = 'L2HO'

defaultRoot = 'L2'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable aldehyde'

oxidationState = 2

product = None

reactWith = None

reactiveFunction = 'CHO'

suffix = '=O'

class radigen3.oxidation.diAllylicCO(**kwargs)

Bases: species

Alkoxyl radical (CO•) on diallylic site

allylic = 2

classAliases = ['C2O', 'R2O', 'L2O', 'P2O']

className = 'alkoxyl radical on diallylic site'

defaultName = 'L2O•'

defaultRoot = 'L2'

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'beta-scission or reduction to alcohol'

oxidationState = -1

product = ['diAllylicCeqO', 'diAllylicCOH']

reactWith = [None, 'CH']

reactiveFunction = 'CO•'

suffix = 'O•'

class radigen3.oxidation.diAllylicCOH(*, root=None, name='', shortname='', concentration=0.0, index=None, _alias_used=None)

Bases: species

Alcohol (COH) on dioallylic site (stable)

allylic = 2

classAliases = ['C1OH', 'R1OH', 'L1OH', 'P1OH']

className = 'alcohol on diallylic site'

defaultName = 'L2OH'

defaultRoot = 'L2'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable alcohol'

oxidationState = 0

product = None

reactWith = None

reactiveFunction = 'COH'

suffix = 'OH'

class radigen3.oxidation.diAllylicCOO(**kwargs)

Bases: species

Hydroperoxyl radical (COO•) on diallylic site

allylic = 2

classAliases = ['C2OO', 'R2OO', 'L2OO', 'P2O']

className = 'hydroperoxyl radical on diallylic site'

defaultName = 'L2OO•'

defaultRoot = 'L2'

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'H abstraction termination'

oxidationState = 0

product = ['diAllylicCOOH', 'terminationPolymers', 'terminationPolymers']

reactWith = ['CH', 'COO•', 'C•']

reactiveFunction = 'COO•'

suffix = 'OO•'

class radigen3.oxidation.diAllylicCOOH(**kwargs)

Bases: species

Hydroperoxide (COOH) on diallylic site

allylic = 2

classAliases = ['C2OOH', 'R2OOH', 'L2OOH', 'P2OOH']

className = 'hydroperoxide on diallylic site'

defaultName = 'L2OOH'

defaultRoot = 'L2'

freevalence = 0

freevalenceHolder = None

interpretation = 'monomolecular or bimolecular decomposition'

oxidationState = -1

product = [{'diAllylicCO', 'peroxyl'}, ('diAllylicCO', 'diAllylicCOO')]

reactWith = [None, 'COOH']

reactiveFunction = 'COOH'

suffix = 'OOH'

class radigen3.oxidation.diAllylicCeqO(**kwargs)

Bases: species

Ketone (C=O) on diallylic site (stable)

allylic = 2

classAliases = ['C2=O', 'R2=O', 'L2=O', 'P2=O']

className = 'ketone on diallylic site'

defaultName = 'L2=O'

defaultRoot = 'L2'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable ketone'

oxidationState = 1

product = None

reactWith = None

reactiveFunction = 'C=O'

suffix = '=O'

radigen3.oxidation.is_valid_figure(fig)

Checks if fig is a valid and open Matplotlib figure.

Parameters: - fig: object to check

Returns: - bool: True if fig is a valid, open Matplotlib figure.

radigen3.oxidation.kttt3 = <L3• + L3• -> L3-polymer + L3-polymer> reaction rate constants

Entries from Table 1 in: Maxime Touffet, Olivier Vitrac, Temperature-dependent kinetics of unsaturated fatty acid methyl esters: Modeling autoxidation mechanisms, Food Chemistry, 481, 2025, 143952 https://doi.org/10.1016/j.foodchem.2025.143952

Note that the values defined here are automatically registered at instantiation

class radigen3.oxidation.lumped(species_list, color=None, linestyle='-')

Bases: species

Lumped species class representing the aggregate behavior of multiple individual species.

This class is used to group species that are chemically or functionally equivalent in a given context (e.g., radicals with similar reactivity, isomers, or chain-length variants).

The lumped object behaves like a single species whose concentration is the sum of its components. It inherits from the species base class but overrides key attributes.

Parameters:

species_list (list[species]) – list of species instances being lumped.
color (str or [RGB] values) – color to apply for plotting (default=None for automatic assignment).
linestyle (str, default="-") – Linestyle used in plots.

species

List of species instances being lumped.

Type:: list[species]

name

Default name is “lump_” + joined individual names.

Type:: str

index

Lumped species are not indexed in the mixture.

Type:: None

concentration

Total concentration of included species.

Type:: float

shortname

Default shorthand label (“LM”).

Type:: str

root

No root is assigned.

Type:: None

reactiveFunction

No reactive function is assigned.

Type:: None

freevalence

No freevalence is assigned.

Type:: None

_color: color to apply for plotting.

_linestyle

Linestyle used in plots.

Type:: str, default=”-”

_lumped

True for lumped species.

Type:: True

Usage Example:

>>> LOOH1 = species.create("L1OOH", concentration=0.1)
>>> LOOH2 = species.create("L2OOH", concentration=0.2)
>>> LOOH3 = species.create("L3OOH", concentration=0.3)
>>> LOOH = lumped([LOOH1, LOOH2, LOOH3])
>>> print(LOOH.name)
lump_L1OOH_L2OOH_L3OOH
>>> print(LOOH.concentration)
0.6

Notes

Lumped species are useful for reducing model complexity or matching experimental resolution.
They can be passed to plotting, integration, or export functions just like other species.
Operations on lumped species do not propagate changes back to the individual species.

See also

species.__or__: Supports the | operator for combining species.

class radigen3.oxidation.mixture(name='mixture', description='', A=0.45, V=0.003, pO2=21000.0, M=0.28246, rho0=883, rho_T0=25, rho_beta=0.00063, kO2=1e-05, Aunits='m²', Vunits='m³', pO2units='Pa', Munits='kg·m⁻¹', rhounits='kg·m⁻³', Tunits='°C', betaunits='K⁻¹', kO2units='m·s⁻¹')

Bases: object

Container class for chemical species and reactions involved in oxidation mechanisms.

The mixture class represents a chemical system composed of individual species objects, along with their physical properties, reaction relationships, and dynamic behaviors. It supports prompt-driven population of reactive species, combinatorial generation of reactions, and parameterization from a curated reaction rate database.

This class also encodes physical parameters relevant to kinetic modeling, including density, molar mass, volume, area, oxygen pressure, and diffusion properties.

It is the entry point for model creation in the oxidation kernel, and is tightly coupled with the mixtureKinetics class, which provides numerical integration of the reaction network.

name

Name of the mixture.

Type:: str

description

Optional description.

Type:: str

A

Interfacial area for mass transfer [m²].

Type:: float

V

Volume of the reacting domain [m³].

Type:: float

pO2

Partial pressure of oxygen [Pa].

Type:: float

M

Molar mass of the mixture [kg/mol].

Type:: float

rho0

Reference density [kg/m³] at rho_T0 °C.

Type:: float

rho_T0

Reference temperature for density [°C].

Type:: float

rho_beta

Thermal expansion coefficient [1/K].

Type:: float

kO2

Oxygen mass transfer coefficient [m/s].

Type:: float

Internals:

_substances (list): List of all species in the mixture. _reactions (dict): Indexed dictionary of all reactions. _reaction_hashes (set): Set of reaction fingerprints for uniqueness. _reaction_counter (int): Tracks reaction indices for auto-numbering.

Properties:

listReactiveFunctions (list): lists unique reactive functions held by species in the mixture. listProductsBySubstance (dict): lists the products it can form for each substance listProducts (list): lists the unique names of all product species that can be formed listFormattedProductsBySubstance (dict): lists the named products it can form for each each substance listFormattedProducts (list): lists the unique named products that can be formed in the mixture species (list): lists species names substances (list(species)): lists species objects reactions (list(reactions)): lists reactions objects reactionScheme (str): Reaction scheme as a string

Key Methods:

add(clsname, name=…, **kwargs) → species: Add a species to the mixture by class or alias name.
addProducts() → int: Recursively add all valid product species inferred from reactive pairs.
addReactions() → int: Combinatorially create all valid reactions among species in the mixture.
populateReactionRates() → int: Assign rate constants using registered reaction rate data.
buildStoichiometryMatrix(sparse=False) → (S, species_list, reactions_list): Build the full stoichiometric matrix (dense or sparse).
stoichiometryDataFrame(sparse=False) → pd.DataFrame: Return a human-readable DataFrame version of the stoichiometry.
getReactionByFingerprint(fingerprint: str) → reaction: Look up a reaction using its string representation.
getSpeciesByReactiveFunction(func: str) → list[species]: Return species that match a given reactive function (e.g., “COOH”).
get_lumped_by_function(function: str) → lumped: Return a lumped object for all species with the given reactive function.
get_lumped_by_pattern(pattern: str, attr=”name”) → lumped: Return a lumped object for species matching a regex pattern on a given attribute.
lumped_hydroperoxides() → lumped: Return a lumped species for all hydroperoxides (reactiveFunction = “COOH”).
lumped_alcohols() → lumped: Return a lumped species for all alcohols (reactiveFunction = “COH”).
lumped_aldehydes() → lumped: Return a lumped species for all aldehydes (reactiveFunction = “CHO”).
lumped_ketones() → lumped: Return a lumped species for all ketones (reactiveFunction = “C=O”).
lumped_radicals_on_C() → lumped: Return a lumped species for all radicals centered on carbon atoms.
lumped_radicals_on_O() → lumped: Return a lumped species for all radicals centered on oxygen atoms.
lumped_polar_compounds() → lumped: Return a lumped species for polar compounds (any compound with at least one oxygen).
lumped_polymers() → lumped: Return a lumped species for all termination polymers (reactiveFunction = “-polymer”).
copy() → mixture: Return a copy of a mixture.
mix1 + mix2 → mixture: Operator ‘+’ combine mixtures and dilute them accordingly

Usage Example:

oil = mixture() oil.add(“L1H”, concentration=3000) oil.add(“L1OOH”, concentration=100) oil.add(“O2”, concentration=10) oil.addProducts() oil.addReactions() oil.populateReactionRates() S, species_list, rxn_list = oil.buildStoichiometryMatrix() df = oil.stoichiometryDataFrame()

Notes

Products are named by combining the reagent root and the suffix of the product class.
Cross-reactions are inferred automatically but do not get their own parameter sets.
This class does not perform any kinetic simulation — see mixtureKinetics for that.
All parameters are expressed in SI units, unless otherwise noted.

See also

mixtureKinetics: For kinetic integration and modeling.
species: For base and derived chemical species.
reaction: For handling A (+B) → C (+D) logic.
reactionRateDB: To define and register kinetic data.

Part of the Generative Simulation Initiative — olivier.vitrac@gmail.com

add(clsname, *, name=None, **kwargs)

Add a new species to the mixture using a class name or alias.

Parameters:

clsname (str) – Alias or registered species class name.
name (str, optional) – Name to assign to the species instance. Defaults to the class’s defaultName.
**kwargs – Additional keyword arguments for the species constructor, including e.g. concentration, root, shortname.

Returns:

The created and registered species object.

Return type:

species

addProducts()

Recursively adds all potential product species (with zero concentration) derived from reactions under current reactive conditions.

Each product species is created with:: name = reagent.root + target_class.suffix

Returns:: Number of new species added to the mixture.
Return type:: int

addReaction(A, B, C, D=None)

addReactions(allow_self_reaction=True)

Generates all valid reactions based on current species.

This method uses the rule: - C = A.listProducts[B.reactiveFunction] - D = B.listProducts[A.reactiveFunction]

Products are looked up in the current mixture via their inferred names: root + suffix (from species registry).

Returns:: number of reactions added
Return type:: int

buildStoichiometryMatrix(sparse=False)

Constructs the stoichiometric matrix S of the mixture’s reaction network.

Rows: species (ordered by .index) Columns: reactions (ordered by .index)

Reactants A,B → -1 (increment, bimolecular → -2 with A=B) Products C,D → +1 (increment, except if polymerization → +0.5)

Parameters:: sparse (bool) – If True, returns a scipy.sparse CSR matrix.
Returns:: Stoichiometry matrix (dense ndarray or sparse CSR) species_list (list): Ordered list of species reactions_list (list): Ordered list of reactions
Return type:: S

copy()

Returns a deep copy (clone) of the current mixture instance.

This method ensures that all species, reactions, and internal structures are duplicated without shared references. Modifying the clone will not affect the original mixture.

Returns:: A fully independent clone of the original mixture.
Return type:: mixture

getReactionByFingerprint(fingerprint)

Retrieves the reaction object matching a given fingerprint string.

Parameters:: fingerprint (str) – A string representation of the reaction, e.g., “L1OOH -> L1HO• + L1O•”
Returns:: The matching reaction object, or None if not found.
Return type:: reaction or None

getSpeciesByReactiveFunction(reactiveFunction)

Retrieves a list of species matching a given reactiveFunction.

Parameters:: reactiveFunction (str) – A string representation of the reactive function, e.g., “L1OOH”
Returns:: An empty list is returned if the reactive function is not found.
Return type:: list of species

get_lumped_by_function(function, color=None, linestyle='-'): Returns a lumped object for all species with a given reactive function.

get_lumped_by_pattern(pattern, attr='name', color=None, linestyle='-'): Returns a lumped object for species whose attribute (default ‘name’) matches a regex.

property listFormattedProducts

Lists the unique named products that can be formed in the mixture using root + suffix logic (e.g., L1O• instead of monoAllylicCO).

Returns:: Sorted list of formatted product names.
Return type:: list[str]

property listFormattedProductsBySubstance

For each species in the mixture, lists the named products it can form (filtered by the reactive functions currently present in the mixture), using root + class suffix logic.

Returns:: {species_name: {reactWith: formatted_product_name}}
Return type:: dict[str, dict[str, str]]

property listProducts

Lists the unique names of all product species that can be formed by the species in the mixture under current reactive conditions.

Returns:: Sorted list of unique product class names.
Return type:: list[str]

property listProductsBySubstance

For each species in the mixture, lists the products it can form (filtered by the reactive functions currently present in the mixture).

Returns:: {species_name: {reactWith: product}}
Return type:: dict[str, dict[str, str]]

property listReactiveFunctions

Returns a sorted list of unique reactive functions held by species in the mixture.

Returns:: List of unique reactiveFunction values.
Return type:: list[str]

lumped_alcohols(color='Indigo', linestyle='-'): Returns a lumped species containing all aldehydes (COH).

lumped_aldehydes(color='DarkViolet', linestyle='-'): Returns a lumped species containing all aldehydes (CHO).

lumped_hydroperoxides(color='Magenta', linestyle='-'): Returns a lumped species containing all hydroperoxides (COOH).

lumped_ketones(color='DarkSlateBlue', linestyle='-'): Returns a lumped species containing all aldehydes (CHO).

lumped_polar_compounds(): Returns a lumped species including compounds with at least one oxygen (based on reactiveFunction/suffix).

lumped_polymers(color='DarkSlateGray', linestyle='-'): Returns a lumped species containing all polymer termination products.

lumped_radicals_on_C(color='DarkGreen', linestyle=':'): Returns a lumped species with radicals centered on carbon atoms.

lumped_radicals_on_O(color='Olive', linestyle='-.'): Returns a lumped species with radicals centered on oxygen atoms.

populateReactionRates()

Updates reaction rate constants (k0, Ea, T0) from the reactionRateDB based on reaction fingerprints.

If a matching fingerprint is found, the reaction’s parameters are updated. If not, the default values are retained.

Returns:: Number of reactions updated.
Return type:: int

property reactionScheme: Returns reaction scheme as a string

property reactions: Returns defined reactions in the mixture as a list

refresh_indices(): Refresh indices of compounds in the mixture. Ensures self._indexmap is contiguous and updates .index attributes.

property species: Return the list of substances in the mixture

stoichiometryDataFrame(sparse=False)

Converts the stoichiometry matrix into a human-readable DataFrame.

Parameters:: sparse (bool) – If True, builds sparse stoichiometry matrix.
Returns:: Species × Reactions stoichiometry.
Return type:: pd.DataFrame

property substances: Retuns list of substances as a list

class radigen3.oxidation.mixtureKinetics(mixture, name=None)

Bases: object

Solver class for time-resolved oxidation kinetics in reactive mixtures.

This class constructs and integrates the differential system for species concentrations:

dC/dt = S · R(C, T) + source_terms(C, T)

where:

C: vector of concentrations [mol/m³]
S: stoichiometric matrix
R: reaction rate vector
T: temperature (can be time-dependent)
source_terms includes mass transport (e.g., O2₂ influx)

Key Features:

Handles monomolecular and bimolecular mechanisms
Automatically applies Arrhenius/Smoluchowski hybrid kinetics
Models ROOH ↔ RO• + HO• with cage/free equilibrium
Tracks oxygen flux using Henry’s law and film model
Solves stiff ODE systems using scipy.integrate.solve_ivp
Supports arbitrary T(t) and kO₂(t) using a TKO2cycle object
Can merge multiple simulations via the ‘+’ operator

Lumped Species Support:

Lumped groups of species can be registered via:: model.register_lumped(“LOOH”, mix.lumped_hydroperoxides())

Registered lumped species can be plotted, tracked, and exported as if they were named species.

Plotting:

Colors and line styles are automatically detected from _color and _linestyle attributes.
Lumped species are rendered with thicker lines and a ‘†’ symbol in legends.
Annotations show the curve maximum for each species if enabled.

Dynamic Simulation Support:

By passing a TKO2cycle object to solve(cycle=…), the solver will use time-varying temperature and oxygen transfer coefficients.

solve(tspan, T, C0, ..., cycle=None): Integrate the ODE system over time.

plot(species=None, ...): Plot time-concentration profiles, including lumped groups.

results_as_dataframe(species=None): Export results as a DataFrame.

get_interpolator(): Returns interpolator for concentrations at arbitrary time points.

get_C0(), set_C(C=None): Retrieve or update species concentrations.

register_lumped(name, lumped_obj): Register a lumped species group.

get_lumped_concentration(name): Return total concentration over a lumped group.

copy(): Return a deep copy of the entire model and simulation state.

__add__(other): Concatenate two compatible simulations for continuous kinetics.

Static Methods:

parse_time_unit(tspan, unit): Convert time input (e.g., (10, “days”)) to seconds with canonical unit tracking.

name

Title of the model (e.g., “oxidation of oil”)

Type:: str

mixture

Associated mixture instance

Type:: mixture

species_list

List of species in simulation

Type:: list

reactions_list

List of reactions used

Type:: list

n_species

Number of species

Type:: int

n_reactions

Number of reactions

Type:: int

_results

Output from solve()

Type:: SimpleNamespace

_lumped_registry

Named groups for tracking output

Type:: dict[str, lumped]

Example

oil = mixture() oil.add(“L1H”, concentration=3000) oil.add(“L1OOH”, concentration=100) oil.add(“O2”, concentration=10) oil.addProducts(); oil.addReactions(); oil.populateReactionRates()

model = mixtureKinetics(oil) model.solve((5, ‘days’), T=60) model.plot([“L1H”, “hydroperoxides”])

df = model.results_as_dataframe() print(df.head())

KcagefreeROOH(T, C): Returns the equilibrium constant between cage and free hydroperoxides at T

cageROOH(T, C, CROOH): Returns the free conentration of hydroperoxides of type COOH at T

copy()

Returns a deep copy (clone) of the current mixture instance.

This method ensures that all species, reactions, and internal structures are duplicated without shared references. Modifying the clone will not affect the original mixture.

Returns:: A fully independent clone of the original mixture.
Return type:: mixture

freeROOH(T, C, CROOH): Returns the free conentration of hydroperoxides of type COOH at T

get_C0(): Returns the initial concentration vector C0 from species in the mixture.

get_R(T, C)

Computes the vector of reaction rates R at temperature T and concentrations C.

Parameters:

T (float) – Temperature in °C.
C (array) – Current concentrations of all species.

Returns:

Reaction rate vector.

Return type:

R (np.ndarray)

get_dCdt(T, C)

Computes the time derivative of species concentrations:

dC/dt = S · R(T, C) + source_vector

Includes source term for O2 transport.

get_dCdt_dynamic(Tfunc, kO2func): Computes the time derivative of species concentrations under dynamic T(t) and kO2(t) conditions

dC/dt = S · R(T(t), C) + source_vector(t)

get_interpolator()

Returns an interpolator object to estimate concentrations at arbitrary times.

Returns:: Function interp(t) that returns concentrations at time t (in seconds).
Return type:: interp (callable)

get_lumped_concentration(name): Return the concentration (cumulated) of a registered lumped species.

molarVolume(T)

Estimate molar volume (m³/mol) of the mixture :param T: Temperature in °C. :type T: float

Returns:: Molar volume in m³/mol
Return type:: float

oxygen_solubility(T)

Returns oxygen solubility in mol/(m³·Pa) using Arai et al. (1989) constants. Valid for FAMEs over a wide T range.

Parameters:: T (float) – Temperature in °C.
Returns:: Solubility S_O2 in mol/(m³·Pa)
Return type:: float

static parse_time_unit(tspan, unit='s')

Convert a time span with units to seconds, return also the canonical unit and inverse scale.

Parameters:

tspan (float or tuple) – time duration (e.g., 3600 or (10.0, “d”))
unit (str, optional) – time unit if not using tuple form.

Returns:

Time span converted to seconds. canonical_unit (str): Canonical form (‘s’, ‘min’, ‘hours’, ‘days’, ‘weeks’, ‘months’, ‘years’). inverse_scale (float): Scaling factor to convert seconds back to canonical unit.

Return type:

time_in_seconds (float)

Raises:

ValueError – If the unit is unknown or invalid.

Canonical units and definitions:

‘s’: seconds
‘min’: 60 seconds
‘hours’: 3600 seconds
‘days’: 86400 seconds
‘weeks’: 7 × 86400
‘months’: 30 × 86400
‘years’: 365 × 86400

plot(species=None, ax=None, figsize=None, ncol=None, legend_loc='center left', bbox_to_anchor=(1.0, 0.5), annotate_max=True, xscale='linear', yscale='linear', **kwargs)

Plot the concentration profiles of selected species over time.

Species are rendered with custom colors if their _color attribute is set. Lumped species (_lumped = True) are plotted with thicker lines and shown with a † symbol in the legend. The maximum value of each curve can be labeled for clarity.

Parameters:

species (list[str], optional) – List of species or lumped names to plot. If None, all species and registered lumped groups are shown.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. If None, creates a new figure.
figsize (tuple, optional) – Size of the figure.
ncol (int, optional) – Number of columns in the legend.
legend_loc (str) – Location of the legend.
bbox_to_anchor (tuple) – Anchor position for the legend.
annotate_max (bool) – Whether to annotate the curve maximum (default: True).
xscale (str) – Scale for x-axis (‘linear’ or ‘log’). Default: ‘linear’.
yscale (str) – Scale for y-axis (‘linear’ or ‘log’). Default: ‘linear’.

Raises:

RuntimeError – If no solution is available.
ValueError – If a species or lumped group is unrecognized.

register_lumped(name, lumped_obj): Register a lumped group under a name for plotting/dataframe output.

results_as_dataframe(species=None)

Return the time evolution of species as a pandas DataFrame.

Parameters:: species (list[str], optional) – If provided, limits the output to these species.
Returns:: DataFrame with time and concentrations.
Return type:: pd.DataFrame

rho(T)

Temperature-dependent density model for mixture. :param T: Temperature in °C. :type T: float

Returns:: density in kg/m³
Return type:: float

set_C(C=None)

Updates the concentrations of species in the mixture.

If C is None, uses the last simulated concentration vector from the final time point.

solve(tspan, T=None, C0=None, species=None, cycle=None, method='BDF', rtol=1e-06, atol=1e-07, max_order=5, **kwargs)

Integrate the system of ODEs dC/dt = S·R(C,T) with optional oxygen source and dynamic conditions.

Supports both constant and time-dependent temperature and oxygenation profiles. When a TKO2cycle object is passed to cycle, the simulation will use the temperature and kO₂ values defined by the cycle for each time point.

Parameters:

tspan (float or tuple) – Final time tf or (t0, tf) in seconds. Can also be passed as (value, unit) tuples (e.g., (10, “days”)).
T (float, optional) – Constant temperature [°C] if no cycle is specified.
C0 (np.ndarray, optional) – Initial concentration vector. If None, uses current species concentrations.
species (list[str], optional) – Species to include in the result. Defaults to all species.
cycle (TKO2cycle, optional) – Time-dependent temperature and oxygenation cycle object.
method (str) – Integration method (e.g., ‘BDF’, ‘LSODA’). ‘BDF’ recommended if the concentrations in radicals are initially 0
rtol (float) – Relative tolerance.
atol (float) – Absolute tolerance.
max_order (int) – Maximum solver order (for implicit methods).
**kwargs – Additional arguments passed to scipy.integrate.solve_ivp.

Returns:

t (np.ndarray): Time points [unit-scaled].
y (np.ndarray): Concentrations at each time step.
tunit (str): Original time unit (e.g., “days”).
tscale (float): Scale factor applied to time for output.
concunits (str): Concentration units (“mol/m³”).
species (list[str]): Names of tracked species.
success (bool): Whether the integration succeeded.
message (str): Solver status message.
solver (str): Solver method used.
cycle (TKO2cycle or None): Applied cycle, if any.
isCycle (bool): True if dynamic conditions were used.

Return type:

types.SimpleNamespace

sourceO2(T, concO2): Oxygen transport model

temporary_kO2(new_kO2): Temporarily override current kO2 value

totalROOH(C): Returns the total concentration in hydroperoxides

class radigen3.oxidation.monoAllylicC(**kwargs)

Bases: species

Alkyl radical (C•) on monoallylic site

allylic = 1

classAliases = ['C1', 'R1', 'L1', 'P1']

className = 'alkyl radical on monoallylic site'

defaultName = 'L1•'

defaultRoot = 'L1'

freevalence = 1

freevalenceHolder = 'C'

interpretation = 'O2 addition'

oxidationState = 0

product = ['monoAllylicCOO', 'terminationPolymers', 'terminationPolymers']

reactWith = ['•OO•', 'C•', 'COO•']

reactiveFunction = 'C•'

suffix = '•'

class radigen3.oxidation.monoAllylicCH(**kwargs)

Bases: species

Aliphatic (CH) on monoallylic site

allylic = 1

classAliases = ['C1H', 'R1H', 'L1H', 'P1H']

className = 'aliphatic with monoallylic C-H'

defaultName = 'L1H'

defaultRoot = 'L1'

freevalence = 0

freevalenceHolder = None

interpretation = 'labile H abstraction'

oxidationState = -1

product = ['monoAllylicC']

reactWith = ['HO•', 'CO•', 'COO•']

reactiveFunction = 'CH'

suffix = 'H'

class radigen3.oxidation.monoAllylicCHO(**kwargs)

Bases: species

Aldehyde (CHO) on monoallylic site (stable)

allylic = 1

classAliases = ['C1=O', 'R1=O', 'L1=O', 'P1=O']

className = 'aldehyde on monoallylic site'

defaultName = 'L1HO'

defaultRoot = 'L1'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable aldehyde'

oxidationState = 2

product = None

reactWith = None

reactiveFunction = 'CHO'

suffix = '=O'

class radigen3.oxidation.monoAllylicCO(**kwargs)

Bases: species

Alkoxyl radical (CO•) on monoallylic site

allylic = 1

classAliases = ['C1O', 'R1O', 'L1O', 'P1O']

className = 'alkoxyl radical on monoallylic site'

defaultName = 'L1O•'

defaultRoot = 'L1'

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'beta-scission or reduction to alcohol'

oxidationState = -1

product = ['monoAllylicCeqO', 'monoAllylicCOH']

reactWith = [None, 'CH']

reactiveFunction = 'CO•'

suffix = 'O•'

class radigen3.oxidation.monoAllylicCOH(**kwargs)

Bases: species

Alcohol (COH) on monoallylic site (stable)

allylic = 1

classAliases = ['C1OH', 'R1OH', 'L1OH', 'P1OH']

className = 'alcohol on monoallylic site'

defaultName = 'L1OH'

defaultRoot = 'L1'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable alcohol'

oxidationState = 0

product = None

reactWith = None

reactiveFunction = 'COH'

suffix = 'OH'

class radigen3.oxidation.monoAllylicCOO(**kwargs)

Bases: species

Hydroperoxyl radical (COO•) on monoallylic site

allylic = 1

classAliases = ['C1OO', 'R1OO', 'L1OO', 'P1OO']

className = 'hydroperoxyl radical on monoallylic site'

defaultName = 'L1OO•'

defaultRoot = 'L1'

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'H abstraction termination'

oxidationState = 0

product = ['monoAllylicCOOH', 'terminationPolymers', 'terminationPolymers']

reactWith = ['CH', 'COO•', 'C•']

reactiveFunction = 'COO•'

suffix = 'OO•'

class radigen3.oxidation.monoAllylicCOOH(**kwargs)

Bases: species

Hydroperoxide (COOH) on monoallylic site

allylic = 1

classAliases = ['C1OOH', 'R1OOH', 'L1OOH', 'P1OOH']

className = 'hydroperoxide on monoallylic site'

defaultName = 'L1OOH'

defaultRoot = 'L1'

freevalence = 0

freevalenceHolder = None

interpretation = 'monomolecular or bimolecular decomposition'

oxidationState = -1

product = [{'monoAllylicCO', 'peroxyl'}, ('monoAllylicCO', 'monoAllylicCOO')]

reactWith = [None, 'COOH']

reactiveFunction = 'COOH'

suffix = 'OOH'

class radigen3.oxidation.monoAllylicCeqO(**kwargs)

Bases: species

Ketone (C=O) on monoallylic site (stable)

allylic = 1

classAliases = ['C1=O', 'R1=O', 'L1=O', 'P1=O']

className = 'ketone on monoallylic site'

defaultName = 'L1=O'

defaultRoot = 'L1'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable ketone'

oxidationState = 1

product = None

reactWith = None

reactiveFunction = 'C=O'

suffix = '=O'

class radigen3.oxidation.oxygen(**kwargs)

Bases: species

Dioxygen (•OO•)

allylic = 0

classAliases = ['O2']

className = 'dioxygen (triplet state)'

defaultName = 'oxygen'

defaultRoot = ''

freevalence = 2

freevalenceHolder = 'O'

interpretation = 'O2 is fixed'

oxidationState = 0

product = ['-']

reactWith = ['C•']

reactiveFunction = '•OO•'

suffix = 'O2'

class radigen3.oxidation.peroxyl(**kwargs)

Bases: species

Peroxyl radical (HO•) class

allylic = 0

classAliases = ['OH']

className = 'peroxyl radical'

defaultName = 'HO•'

defaultRoot = ''

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'labile H abstraction'

oxidationState = 0

product = ['H2O']

reactWith = ['CH']

reactiveFunction = 'HO•'

suffix = 'HO•'

radigen3.oxidation.print_figure(fig, filename='', destinationfolder='/home/olivi/maxime/radigen/docs_sphinx/source', overwrite=False, dpi={'pdf': 300, 'png': 150})

Save the figure in both PDF and PNG formats.

Parameters: - fig: Matplotlib figure object to be saved. - filename: str, base filename (auto-generated if empty). - destinationfolder: str, folder to save the files. - overwrite: bool, overwrite existing files. - dpi: int, resolution (default=300).

radigen3.oxidation.print_pdf(fig, filename='', destinationfolder='/home/olivi/maxime/radigen/docs_sphinx/source', overwrite=False, dpi=300)

Save a given figure as a PDF.

Parameters: - fig: Matplotlib figure object to be saved. - filename: str, PDF filename (auto-generated if empty). - destinationfolder: str, folder to save the file. - overwrite: bool, overwrite existing file. - dpi: int, resolution (default=300).

radigen3.oxidation.print_png(fig, filename='', destinationfolder='/home/olivi/maxime/radigen/docs_sphinx/source', overwrite=False, dpi=300)

Save a given figure as a PNG.

Parameters: - fig: Matplotlib figure object to be saved. - filename: str, PNG filename (auto-generated if empty). - destinationfolder: str, folder to save the file. - overwrite: bool, overwrite existing file. - dpi: int, resolution (default=300).

class radigen3.oxidation.reaction(*, A, C, B=None, D=None, index=None, k0=1.0, Ea=45000.0, T0=25.0, Tunits='°C', kunits='m³/mol·s', Eaunits='J/mol', diffusionLimited=False, ratio_rgh=0.77, eta0=0.0019, eta_Ea=17000.0, eta_T0=80, etaunits='Pa·s', model='default', Tdefault=40, phi=2.0)

Bases: object

Represents a chemical reaction of the form A (+ B) → C (+ D).

This class handles the logical structure and parameterization of elementary reactions in radical oxidation mechanisms. It supports Arrhenius and Smoluchowski rate models, diffusion-limited corrections, and fingerprinting for unique identification and cross-term inference.

It distinguishes between monomolecular and bimolecular reactions, between self- and cross-reactions, and supports equilibrium treatment for specific classes (e.g. hydroperoxides).

A, B

Reactants; B can be None (monomolecular reaction).

Type:: species

C, D

Products; D can be None.

Type:: species

index

Reaction index within the mixture.

Type:: int

k0

Pre-exponential rate constant at T0.

Type:: float

Ea

Activation energy [J/mol].

Type:: float

T0

Reference temperature [°C].

Type:: float

kunits, Eaunits, Tunits

Units for k0, Ea, T0.

Type:: str

diffusionLimited

Whether reaction is diffusion-limited.

Type:: bool

ratio_rgh

Ratio of gyration to hydrodynamic radii.

Type:: float

eta0, eta_Ea, eta_T0, etaunits: Viscosity model parameters.

model

String describing the rate model origin.

Type:: str

phi

Multiplicative factor for cross-reactions.

Type:: float

inherit

Self-reactions from which a cross-reaction inherits its rate.

Type:: tuple

Properties:: ismonomolecular (bool): True if only A is defined. isbimolecular (bool): True if both A and B are defined. isselfroot (bool): True if A and B share the same root. iscrossroot (bool): True if A and B differ by root. isdecompositionROOH (bool): True if hydroperoxide decomposition. iscagedecompositionROOH (bool): True if bimolecular hydroperoxide cage decomposition.

k(T): Return rate constant (includes cross-term inference).

kArrhenius(T): Arrhenius-only rate constant.

kSmoluchowski(T): Smoluchowski diffusion rate.

viscosity(T): Temperature-dependent viscosity.

fingerprint(): Human-readable identifier (e.g. “A + B -> C + D”).

crossfingerprints(): Tuple of fingerprints for each self-reaction of a cross-term.

__str__, __repr__: Human-readable and detailed representations.

Static Methods:: hash_reagents(A, B): Hash based on reactants. hash_reagents_products(A, B, C, D): Hash including products. order_reagents(A, B, C, D): Canonical ordering of inputs.

Notes

Reactions are ordered to ensure uniqueness (e.g., oxidant = B if ranks differ).
Rate constants are inferred from registered reactionRateDB entries.
Cross-reactions use a geometric mean of inherited rate constants.

See also

species: for chemical participant definitions.
mixture: for reaction network generation and storage.
reactionRateDB: for assigning kinetic constants.

property crossfingerprints: Returns the human-readable fingerprints for cross-reactions

property fingerprint: Returns the human-readable fingerprint of a reaction

static hash_reagents(A, B=None)

Returns a hash based on reagent identities.

Parameters:

A (species) – First reactant.
B (species or None) – Second reactant (optional).

Returns:

Unique hash for the reaction based on its reactants.

Return type:

int

static hash_reagents_products(A, B=None, C=None, D=None): Returns a hash based on reagent and product identities.

property isbimolecular: Returns True if the reaction is bimolecular

property iscagedecompositionROOH: Returns True if the reaction involves a bimolecular cage decomposition of hydroperoxides

property iscrossroot: Returns True if the reaction is monomolecular or involves different roots (e.g., L1OOH+L2OOH)

property isdecompositionROOH: Returns True is the reaction involves the decomposition of hydroperoxides

property ismonomolecular: Returns True if the reaction is monomolecular

property ispolymerization: Returns True if the reaction involves a polymerization

property isselfroot: Returns True if the reaction is bimolecular and involves same roots (e.g., L1OOH+L1OOH)

k(T=None): Returns a function k(T) giving the Arrhenius rate constant at temperature T (°C).

kArrhenius(T=None): Returns the Arrhenian reaction rate

kSmoluchowski(T=None): Returns the Smoluchowski reaction rate

static order_reagents(A, B, C=None, D=None)

Orders A + B -> C + D for reaction consistency (B is the oxidizer) Note that the products C and D must match A and B

Rules: - If A is None and B is not, swap. - If both are defined and A._redoxRank > B._redoxRank, swap.

Returns:: (A, B) in canonical order
Return type:: tuple

viscosity(T=None): Returns the dynamic viscosity

class radigen3.oxidation.reactionRateDB(*, fingerprint, T0, k0, k0_CI=None, Ea, Ea_CI=None, Tunits='°C', kunits='m³·mol⁻¹·s⁻¹', Eaunits='J·mol⁻¹', source='', diffusionLimited=False, ratio_rgh=0.77, eta0=0.0019, eta_Ea=17000.0, eta_T0=80, etaunits='Pa·s', phi=2.0)

Bases: object

Database and container class for reaction rate constants.

This class enables registration, storage, and retrieval of kinetic parameters associated with elementary reactions involved in radical oxidation mechanisms. It is designed to support both monomolecular and bimolecular reactions, including Arrhenius parameters, solvent-dependent viscosity corrections, and diffusion limits.

Each entry corresponds to a uniquely defined reaction fingerprint (e.g., “L1OOH -> L1O• + HO•”) and may include confidence intervals, diffusion-limited behavior, and Smoluchowski model parameters.

=== Attributes === Class Attributes:

_registry (dict): Maps canonical fingerprints to lists of registered entries. _fingerprint_substitutions (list): List of (pattern, replacement) regex pairs

used to transform fingerprints queried via .get() or .get_latest().

Instance Attributes:: fingerprint (str): Reaction descriptor in canonical form. T0 (float): Reference temperature [°C]. Tunits (str): Units of T0. k0 (float): Pre-exponential factor (Arrhenius rate at T0). k0_CI (float or None): Confidence interval on k0. kunits (str): Units of k0 (e.g., “m³·mol⁻¹·s⁻¹”). Ea (float): Activation energy [J/mol]. Ea_CI (float or None): Confidence interval on Ea. Eaunits (str): Units of activation energy. source (str): Source or reference for the entry (e.g., literature citation). diffusionLimited (bool): Whether rate is capped by diffusion. ratio_rgh (float): Radius-of-gyration to hydrodynamic-radius ratio. eta0 (float): Reference viscosity [Pa·s]. eta_Ea (float): Activation energy for viscosity [J/mol]. eta_T0 (float): Reference temperature for viscosity model [°C]. etaunits (str): Units for viscosity. phi (float): Scaling factor used for cross-reaction inference.

=== Methods === Instance:

__init__: Creates and registers a new rate constant entry. __iter__: Iterator over main fields. __str__, __repr__: Human-readable and detailed representations.

Class:: get(fingerprint): Return all entries matching the given fingerprint or a substituted one. get_latest(fingerprint): Return the latest entry registered for a (possibly substituted) fingerprint. to_dataframe(): Export the full database to a pandas DataFrame. register_fingerprint_substitution(pattern, replacement): Register a regex substitution to transform

a queried fingerprint into a canonical one, allowing lookup under different naming schemes.

=== Fingerprint Substitution === If a reaction fingerprint is not found in the registry, a set of regex-based substitutions is applied in sequence to find alternative forms (e.g., “L1H” → “R1H”). This enables the reuse of reaction rate constants across different naming conventions.

Example

reactionRateDB.register_fingerprint_substitution(r”L([123])”, r”R1”)

# Register using R-prefixed names reactionRateDB(fingerprint=”R1H + R1O• -> R1• + R1OH”, …)

# Lookup via L-prefixed form will succeed: reactionRateDB.get_latest(“L1H + L1O• -> L1• + L1OH”)

Notes

Only the first matching substitution is applied.
Substitution is used only for lookup; registered fingerprints remain unchanged.

=== Usage Example ===

reactionRateDB(: fingerprint=”L1OOH -> L1O• + HO•”, T0=140, k0=2.11e-4, Ea=74.8e3, source=”Touffet et al. 2023”

)

See also

reaction: Uses this class to populate kinetic parameters.
mixture.populateReactionRates(): Assigns values to all reactions in a mixture.

classmethod get(fingerprint): Returns all entries matching the fingerprint or its substituted variant.

classmethod get_latest(fingerprint): Returns the last entry added for a fingerprint (with substitution if needed).

classmethod register_fingerprint_substitution(pattern: str, replacement: str)

Register a regex-based substitution rule to rewrite reaction fingerprints. The first rule that matches will be used.

Example

pattern = r”L([123])” # matches L1, L2, L3 replacement = r”R” # replaces with R1, R2, R3

classmethod to_dataframe()

class radigen3.oxidation.species(*, root=None, name='', shortname='', concentration=0.0, index=None, _alias_used=None)

Bases: object

Base class for chemical species involved in radical oxidation.

This class supports structural and kinetic representation of organic species, including radicals, hydroperoxides, oxygen, alcohols, aldehydes, and stable products. Derived classes should specify suffix, aliases, reactive functions, and redox ranks.

name

Long name.

Type:: str

shortname

Abbreviation or label.

Type:: str

root

Identifier used to group related species.

Type:: str

concentration

Current concentration in mol/m³.

Type:: float

index

Index in the mixture (set automatically).

Type:: int

Class Attributes:: _registry (dict): Mapping from names and aliases to subclasses.
Core Properties:: isradical (bool): True if species has nonzero free valence. ishydroperoxide (bool): True if reactiveFunction is “COOH”. isreactive (bool): True if species has a defined reaction partner/product. islumped (bool): True if species is a lumped group of species. listProducts (dict): Maps reactive functions → product class names. formattedProducts (dict): Maps reactive functions → formatted product names (root + suffix).
Behavior:: __or__(other): Lump two species (returns a lumped object). __add__(other): Placeholder for defining reaction A + B. __iter__(): Iterator over main attributes. __repr__(), __str__(): Print-friendly formatting.
Class Methods:: register(cls): Decorator to register subclasses (with aliases). create(name, **kwargs): Factory method to instantiate from alias or class name.

Notes

reactiveFunction, reactWith, and product must be defined in subclasses.
reactWith may be a list of functional groups or None (monomolecular).
Products can be a string, tuple (ordered), or set (unordered).
Naming conventions follow: name = root + suffix (e.g., L1OO• from root L1 + suffix OO•).

Example

@species.register class monoAllylicCH(species):

suffix = “H” reactiveFunction = “CH” reactWith = [“COO•”, “CO•”] product = [“monoAllylicC”] defaultRoot = “L1” defaultName = “L1H”

See also

mixture: For managing collections of species.
reaction: For defining A + B → C + D.
lumped: For combining species into pseudo-compounds.

static create(name, **kwargs)

Factory method to create a species by name or alias.

Parameters:

name (str) – Name or alias of the species.
**kwargs – Passed to the constructor of the target class.

Returns:

An instance of the requested class.

Return type:

species

Raises:

ValueError – If no class matches the name or alias.

property formattedProducts

Returns a dictionary mapping reaction types to formatted product names using root + suffix (e.g., ‘L1OO•’ instead of ‘monoAllylicCOO’).

Keys:: ‘self’ → product of monomolecular decomposition <functional_group> → product from bimolecular reaction

Returns:: Maps reaction type to formatted name(s)
Return type:: dict[str, str or list[str]]

property isbimolecular: Returns True if the species reacts with another reactant (reactWith is not None). If reactWith is a list, returns a list of bools for each reactant type. Returns False if not reactive.

property ishydroperoxide: True if reactiveFunction is ‘COOH’, interpreted as a hydroperoxide.

property islumped: True if this species is a lumped group of multiple species.

property ismonomolecular: Returns True if the species reacts without a partner (reactWith is None). If reactWith is a list, returns a list of bools for each reactant type. Returns False if not reactive.

property isradical: True if species has free valence (i.e., is a radical).

property isradical_onC: True if radical center is on carbon.

property isradical_onO: True if radical center is on oxygen.

property isreactive: True if the species leads to at least one product.

property listProducts

Returns a dictionary mapping the type of reaction to the corresponding product.

Keys:: ‘self’ → product of monomolecular decomposition (i.e., if None is in reactWith) <functional_group> → product when reacting with that function (from reactWith)

Returns:: Maps reaction type to product name.
Return type:: dict[str, str or None]

classmethod register(derived_cls)

Class decorator to register a derived species class.

Adds both the class name and any class-defined aliases to the registry.

Parameters:: derived_cls (type) – The class to register.
Returns:: The same class, unmodified.
Return type:: type

class radigen3.oxidation.terminationPolymers(*, root=None, name='', shortname='', concentration=0.0, index=None, _alias_used=None)

Bases: species

Generic stable polymer termination product

allylic = None

classAliases = ['polymer']

className = 'stable polymer termination product'

defaultName = 'termination product (polymer)'

defaultRoot = 'polymer'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable termination products (polymers)'

oxidationState = 0

product = None

reactWith = None

reactiveFunction = '-polymer'

suffix = '-polymer'

class radigen3.oxidation.triAllylicC(**kwargs)

Bases: species

Alkyl radical (C•) on triallylic site

allylic = 3

classAliases = ['C3', 'R3', 'L3', 'P3']

className = 'alkyl radical on triallylic site'

defaultName = 'L3•'

defaultRoot = 'L3'

freevalence = 1

freevalenceHolder = 'C'

interpretation = 'O2 addition'

oxidationState = 0

product = ['triAllylicCOO', 'terminationPolymers', 'terminationPolymers']

reactWith = ['•OO•', 'C•', 'COO•']

reactiveFunction = 'C•'

suffix = '•'

class radigen3.oxidation.triAllylicCH(**kwargs)

Bases: species

Aliphatic (CH) on triallylic site

allylic = 3

classAliases = ['C3H', 'R3H', 'L3H', 'P3H']

className = 'aliphatic with triallylic C-H'

defaultName = 'L3H'

defaultRoot = 'L3'

freevalence = 0

freevalenceHolder = None

interpretation = 'labile H abstraction'

oxidationState = 0

product = ['triAllylicC']

reactWith = ['HO•', 'CO•', 'COO•']

reactiveFunction = 'CH'

suffix = 'H'

class radigen3.oxidation.triAllylicCHO(**kwargs)

Bases: species

Aldehyde (CHO) on triallylic site (stable)

allylic = 3

classAliases = ['C3=O', 'R3=O', 'L3=O', 'P3=O']

className = 'aldehyde on triallylic site'

defaultName = 'L3HO'

defaultRoot = 'L3'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable aldehyde'

oxidationState = 2

product = None

reactWith = None

reactiveFunction = 'CHO'

suffix = '=O'

class radigen3.oxidation.triAllylicCO(**kwargs)

Bases: species

Alkoxyl radical (CO•) on triallylic site

allylic = 3

classAliases = ['C3O', 'R3O', 'L3O', 'P3O']

className = 'alkoxyl radical on triallylic site'

defaultName = 'L3O•'

defaultRoot = 'L3'

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'beta-scission or reduction to alcohol'

oxidationState = -1

product = ['triAllylicCeqO', 'triAllylicCOH']

reactWith = [None, 'CH']

reactiveFunction = 'CO•'

suffix = 'O•'

class radigen3.oxidation.triAllylicCOH(**kwargs)

Bases: species

Alcohol (COH) on trioallylic site (stable)

allylic = 3

classAliases = ['C1OH', 'R1OH', 'L1OH', 'P1OH']

className = 'alcohol on triallylic site'

defaultName = 'L3OH'

defaultRoot = 'L3'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable alcohol'

oxidationState = 0

product = None

reactWith = None

reactiveFunction = 'COH'

suffix = 'OH'

class radigen3.oxidation.triAllylicCOO(**kwargs)

Bases: species

Hydroperoxyl radical (COO•) on triallylic site

allylic = 3

classAliases = ['C3OO', 'R3OO', 'L3OO', 'P3OO']

className = 'hydroperoxyl radical on triallylic site'

defaultName = 'L3OO•'

defaultRoot = 'L3'

freevalence = 1

freevalenceHolder = 'O'

interpretation = 'H abstraction termination'

oxidationState = 0

product = ['triAllylicCOOH', 'terminationPolymers', 'terminationPolymers']

reactWith = ['CH', 'COO•', 'C•']

reactiveFunction = 'COO•'

suffix = 'OO•'

class radigen3.oxidation.triAllylicCOOH(**kwargs)

Bases: species

Hydroperoxide (COOH) on triallylic site

allylic = 3

classAliases = ['C3OOH', 'R3OOH', 'L3OOH', 'P3OOH']

className = 'hydroperoxide on diallylic site'

defaultName = 'L3OOH'

defaultRoot = 'L3'

freevalence = 0

freevalenceHolder = None

interpretation = 'monomolecular or bimolecular decomposition'

oxidationState = -1

product = [{'peroxyl', 'triAllylicCO'}, ('triAllylicCO', 'triAllylicCOO')]

reactWith = [None, 'COOH']

reactiveFunction = 'COOH'

suffix = 'OOH'

class radigen3.oxidation.triAllylicCeqO(**kwargs)

Bases: species

Ketone (C=O) on triallylic site (stable)

allylic = 3

classAliases = ['C3=O', 'R3=O', 'L3=O', 'P3=O']

className = 'ketone on triallylic site'

defaultName = 'L3=O'

defaultRoot = 'L3'

freevalence = 0

freevalenceHolder = None

interpretation = 'stable ketone'

oxidationState = 1

product = None

reactWith = None

reactiveFunction = 'C=O'

suffix = '=O'