rxnfit.build_ode module — rxnfit 20260310 documentation

# rxnfit.build_ode module

class rxnfit.build_ode.RxnODEbuild(file_path, encoding=None, rate_const_overrides=None, rate_const_overrides_encoding=None)

  Bases: `RxnToODE`

  Build ODE systems and numerical RHS functions from reaction definitions.

  Extends RxnToODE to produce callable ODE right-hand sides (e.g. for scipy.solve_ivp) and supports rate constants as expressions (e.g. k2=k1*2). Expression-defined constants are resolved to numbers when building create_ode_system(); for fitting, only free symbolic parameters appear in create_ode_system_with_rate_consts().

  Inherits all attributes from RxnToODE.
  create_ode_system()

    Numerical ODE functions (t, y) with rate constants resolved or embedded.

  create_ode_system_with_rate_consts()

    ODE functions with rate constants as extra arguments (for fitting).

  get_ode_system()

    Full ODE construction tuple for solvers.

  debug_ode_system()

    Detailed debug info.

  get_ode_info(debug_info=False)

    Print summary and optional debug.

  create_ode_system()

    Build numerical ODE right-hand side functions for integration.

    Rate constants that are expressions (e.g. k2=k1*2) are resolved to numbers via _resolve_rate_consts when all referenced symbols have numeric values; otherwise the expression or Symbol is left in place. Functions take (t, y) with y in function_names order.

    Returns:

      Species name -> callable(t, *y) returning d(species)/dt.

    Return type:

      dict

    Raises:

      RuntimeError – If lambdify fails for any species (fail fast).

  create_ode_system_with_rate_consts()

    Build ODE functions with rate constants as explicit arguments.

    Used for fitting: rate constants are passed in at call time instead of being embedded. Only “free” parameters appear: keys that are Symbol or that appear inside expression-defined constants (e.g. k1 in k2=2*k1). Keys defined only by expressions (e.g. k2) do not appear in symbolic_rate_const_keys.

    Returns:

      (ode_functions, symbolic_rate_const_keys)

        - ode_functions: Species name -> callable(t, *y, *rate_consts).

        - symbolic_rate_const_keys: List of free rate constant names in order (e.g. [‘k1’, ‘k3’] when k2=k1*2).

    Return type:

      tuple

    Raises:

      RuntimeError – If lambdify fails for any species (fail fast).

  debug_ode_system()

    Collect debug information for the ODE system.

    Returns:

      function_names, rate_constants, ode_expressions,

        lambdify_args, ode_functions_info (and test results).

    Return type:

      dict

  get_ode_info(debug_info: bool = False)

    Print a short summary of the ODE system (and optionally debug).

    Parameters:

      debug_info (bool, optional) – If True, also print detailed debug (e.g. lambdify args, ODE expressions). Defaults to False.

  get_ode_system()

    Return the full ODE construction for scipy.solve_ivp.

    Returns:

      (system_of_equations, sympy_symbol_dict, ode_system,

        function_names, rate_consts_dict). ode_system is from create_ode_system() (rate constants resolved or embedded).

    Return type:

      tuple

  get_symbolic_rate_const_keys()

    Return the list of free parameter names (p0 order) for fitting.

    Names are t-excluding symbols from rate_consts_dict (Symbol or free_symbols of expressions), in sorted order. Same order as create_ode_system_with_rate_consts and run_fit(p0=…) expect.

    Returns:

      Parameter names in order, e.g. [‘a’, ‘km’].

    Return type:

      list[str]

rxnfit.build_ode.create_system_rhs(ode_functions_dict, function_names, rate_const_values=None, symbolic_rate_const_keys=None)

  Build the RHS function (t, y) for scipy.solve_ivp.

  Creates a closure over the ODE functions and optional rate constant values. When rate_const_values and symbolic_rate_const_keys are given, the ODE functions are called with (t, y, *rate_consts) in the order of symbolic_rate_const_keys.

  Parameters:

    - ode_functions_dict (dict) – Species name -> ODE function (as from create_ode_system or create_ode_system_with_rate_consts).

    - function_names (list) – Species names in the same order as y.

    - rate_const_values (dict or callable, optional) – Rate constant key -> numeric value, or a callable (t) -> dict of rate constant values for time-dependent rates. Used when ODE functions expect rate constants as args. When callable, it is called with the current time t to get the dict.

    - symbolic_rate_const_keys (list, optional) – Order of rate constant keys matching the ODE functions. Required if rate_const_values is provided.

  Returns:

    system_rhs(t, y) returning a list of d(species)/dt in

      function_names order.

  Return type:

    callable

  Raises:

    RuntimeError – If any ODE function is None or if evaluation fails during integration (fail fast).