Architecture

ode2sbml uses a layered architecture. Input-specific parsers normalize Python ODE definitions into a shared ODEModel intermediate representation. Writers then export that IR to SBML XML or PEtab bundles.

flowchart LR
    A[Convention A<br/>scipy-style function] --> P[parser.from_function]
    B[Convention B<br/>dict-of-formulas] --> Q[parser.from_dict]
    C[Convention C<br/>SymPy system] --> R[parser.from_sympy]

    P --> IR[ODEModel IR]
    Q --> IR
    R --> IR

    IR --> S[SBML writer<br/>libSBML document]
    IR --> T[PEtab writer<br/>SBML + TSV + YAML]
    S --> V[SBML validator]
    T --> V

    M[MathML utilities<br/>SymPy ↔ SBML MathML] --> S
    N[Annotations<br/>SBO + MIRIAM helpers] -. optional .-> S

Package layout

ode2sbml/
├── annotations.py
├── cli.py
├── converters/
│   ├── mathml_utils.py
│   ├── petab_writer.py
│   └── sbml_writer.py
├── model.py
├── parser.py
└── validators/
    └── sbml_validator.py

Data flow

1. A Python model is loaded from a file or imported as Python objects.
2. The parser converts the source convention into ODEModel.
3. ODEModel validates SBML-compatible identifiers and duplicate IDs.
4. SBML export builds a libSBML document with compartments, species, parameters, rate rules, assignment rules, and events.
5. Formula strings are parsed through SymPy and converted to SBML MathML AST nodes.
6. Optional validation runs libSBML consistency and internal consistency checks.
7. PEtab export writes SBML plus PEtab tables and a YAML manifest.

Boundary of responsibility

ode2sbml translates model structure. It does not prove biological correctness, parameter identifiability, or numerical stability of the ODE system.

Component responsibilities

Component	Responsibility
model.py	Defines Compartment, Species, Parameter, RateRule, AssignmentRule, EventTrigger, and ODEModel.
parser.py	Converts supported Python conventions into ODEModel.
mathml_utils.py	Converts SymPy-parseable formulas and SymPy expressions into libSBML AST nodes.
sbml_writer.py	Creates SBML Level 3 Version 2 documents and writes XML.
petab_writer.py	Creates PEtab v1 bundles from ODEModel.
sbml_validator.py	Wraps libSBML consistency checks.
annotations.py	Provides SBO constants and MIRIAM annotation helpers.
cli.py	Provides convert and validate commands.

Design invariant

All import formats should converge to the same IR. Exporters should depend on ODEModel, not on the original input convention.

Export path

sequenceDiagram
    participant User
    participant CLI
    participant Parser
    participant IR as ODEModel
    participant Writer as SBML Writer
    participant Math as MathML Utils
    participant File as XML/PEtab Files

    User->>CLI: ode2sbml convert model.py -o model.xml
    CLI->>Parser: auto-detect convention
    Parser->>IR: build validated ODEModel
    IR->>Writer: model_to_sbml_doc(ir)
    Writer->>Math: formula_to_astnode(rate.formula)
    Math-->>Writer: libSBML ASTNode
    Writer->>File: write SBML XML