rxnfit.rxn_reader module

class rxnfit.rxn_reader.RxnToODE(file_path, encoding=None)

Bases: object

Convert reaction equations from CSV files to ODE systems.

Reads chemical reaction data from CSV and builds systems of ordinary differential equations using SymPy. Rate constants may be numeric, symbolic, or given by expressions (e.g. k2 = k1*2).

file_path

Path to the CSV file containing reaction data.

Type:

str

reactant_eq

List of reactant equations from the file.

Type:

list

t

SymPy symbol for time.

Type:

Symbol

function_names

Chemical species names in appearance order.

Type:

list

functions_dict

Species names to SymPy Function objects.

Type:

dict

rate_consts_dict

Rate constant key to float, Symbol, or SymPy Expr (e.g. 2*k1 for constraint k2=k1*2).

Type:

dict

sympy_symbol_dict

Combined dict of t, Derivative, rate_consts_dict, and functions_dict for parsing ODEs.

Type:

dict

sys_odes_dict

Species name to ODE right-hand side string.

Type:

dict

create_ode_system()

Build ODE right-hand side expressions (SymPy) per species.

Returns:

Species name -> SymPy expression for d(species)/dt.

Return type:

dict

get_equations()

Build the system of SymPy equations for the ODEs.

Returns:

List of sympy.Eq (lhs = Derivative(species(t), t), rhs expr).

Return type:

list

rxnfit.rxn_reader.generate_ode(reaction)

Generate ODE expressions for a single reaction.

This function is used internally by ‘generate_sys_ode’ to process individual reactions and generate differential equation expressions for each chemical species involved in the reaction.

Parameters:

reaction (list) – A list representing a reaction equation in the format [[‘ID’, rate_constant], reactants, products, conditions, [rate_law_string, [reactant_coeffs], [product_coeffs]]]. rate_constant may be float or str. The reaction must have at least 5 elements.

Returns:

A dictionary mapping species names (str) to their ODE

expression strings. Reactants contribute negative terms, products contribute positive terms.

Return type:

defaultdict

rxnfit.rxn_reader.generate_sys_ode(reactant_eq)

Generate system of ODEs from reactant equations.

Parameters:

reactant_eq (list) – A list of reactant equations.

Returns:

A dictionary containing the system of ODEs.

Return type:

dict

rxnfit.rxn_reader.get_reactions(file_path, encoding=None)

Imports elementary reaction formulas from a CSV file into a Python list.

The reaction formulas are written by reaction SMILES style. The CSV file is expected to have a header row and each subsequent row should represent a reaction with columns for Reaction ID, rate constant (k), followed by pairs of columns for reactant coefficient and reactant name, separated by “>”, then conditions, separated by “>”, and finally pairs of columns for product coefficient and product name. The “+” symbols in the CSV are ignored.

Rate constant column (k):

  • Empty: replaced by ‘k’ + RID (e.g. ‘k2’ for RID 2).

  • Numeric string (e.g. “0.04”): converted to float.

  • Other string: kept as-is (expression like “k1*2” or symbol name).

Parameters:

  • file_path (str) – The path to the CSV file containing the reaction formulas.

  • encoding (str, optional) – The encoding of the CSV file. Defaults to ‘utf-8’ if None.

Returns:

A list of lists, where each inner list represents a reaction

and contains: - A list [reaction_id, rate_constant] where rate_constant is

float, or str (e.g. ‘k2’ for empty, or expression like ‘k1*2’).

  • A list of [coefficient, name] for each reactant.

  • A list of [coefficient, name] for each product.

  • A list of condition strings.

Return type:

list

rxnfit.rxn_reader.get_unique_species(reaction_equations)

Extract unique chemical species from elementary reactions.

Parameters:

reaction_equations (list) – A list of lists representing elementary reactions.

Returns:

A list of unique chemical species sorted by their appearance

order.

Return type:

list

rxnfit.rxn_reader.rate_constants(reactant_eq)

Extract rate constants from reactant equations.

Each key is ‘k’ + reaction ID. Values are float when the rate constant cell was numeric; otherwise the raw string (e.g. ‘k2’, ‘k1*2’) is kept.

Parameters:

reactant_eq (list) – A list of reactant equations (output of reactant_consumption for each reaction from get_reactions).

Returns:

Mapping from rate constant key (e.g. ‘k1’, ‘k2’) to float or

str. String values are used later for symbol or expression parsing in _build_rate_consts_sympy.

Return type:

dict

rxnfit.rxn_reader.reactant_consumption(reaction_equation)

Generate rate law equations for reactant consumption.

The rate law equations and coefficients are determined as follows. For a reaction aA + bB -> cC + dD: -d[A]/dt = k * A^a * B^b -(1/a)d[A]/dt = -(1/b)d[B]/dt = (1/c)d[C]/dt = (1/d)d[D]/dt That is, -d[A]/dt = -(a/b)d[B]/dt = (a/c)d[C]/dt = (a/d)d[D]/dt

For products-only reactions (e.g. -> C), the rate is zero-order: v = k, d[C]/dt = k.

Parameters:

reaction_equation (list) – A list representing a reaction equation in the format [[‘ID’, rate_constant], [[coeff, reactant1], …], [[coeff, product1], …]]. rate_constant may be float or str. Reactants may be empty for zero-order formation.

Returns:

The input reaction_equation list extended with:

  • A string representing the RHS of the rate law equation

  • A list of coefficients for reactants

  • A list of coefficients for products

Return type:

list

rxnfit.rxn_reader.to_chempy_style(reaction)

Convert a reaction equation list to a ChemPy-style dictionary.

Parameters:

reaction (list) – A list representing a reaction equation in the format [[‘ID’, rate_constant], [[coeff, reactant1], …], [[coeff, product1], …]].

Returns:

A list containing the reaction ID and rate constant, followed

by two dictionaries representing the reactants and products with their coefficients.

Return type:

list