SBML native kinetic workflows

Import a supplied kinetic model once, then solve and fit it through Grid's existing native dynamics. The importer produces an editable ordinary Grid module containing a REACTIONS definition, global parameter inputs, and a source manifest. It performs no integration, external lookup or job submission.

cargo run --offline --locked --manifest-path rust/Cargo.toml \
  --config .cargo/no-debug-symbols.toml -p grid-format-standard \
  --example sbml-to-grid -- examples/scientific/transfer.sbml > /tmp/transfer.grid
cat examples/scientific/transfer-workflow.grid >> /tmp/transfer.grid

Open the resulting source as a normal Grid model. The supplied SBML model and workflow formulas form a complete transfer experiment. trajectory contains named series, terminal values and diagnostics from REACTION_SOLUTION. fit_report fits the kinetic rate to independently defined observations using CURVE_FIT.REPORT, returning the existing numerical fit report. The expected fitted rate is 0.7 per second. The initial authored rate is 0.2; fitting does not overwrite it.

estimate is an inert CALIBRATION definition using the same imported model. Explicitly run it through the existing Experiments calibration operation to get its retained job/result/trace lifecycle. Reading the definition does not run a job. See direct trajectory calibration for that existing API. The importer introduces no new calibration runner or evidence store.

The Rust embedding API is grid_format_standard::sbml::import(text, context). It returns ImportedModel { grid_source, manifest }. The tool reads at most 256 KiB plus one overflow byte and writes generated source to stdout. File selection and writing belong to the tool; the importer itself receives bytes. This first workflow is an explicit source import, not a PARSE_SBML cell function or an SBML literal that silently starts execution.

Admitted scientific profile

Profile identity: sbml-l3v2-constant-compartment-kinetics-v1. The source must use the Level 3 Version 2 Core namespace and Content MathML. The following conventions preserve the distinction between SBML symbols and native state coordinates:

• Model units are explicitly mole for substance/extent, second for time, and litre for volume. Compartments are constant, positive, three-dimensional volumes in litre. No scaling or conversion is inferred.
• Each species has exactly one finite nonnegative initial amount or concentration. Native states always store amounts in mole. Initial concentration is multiplied by compartment volume. In kinetic expressions, hasOnlySubstanceUnits=true resolves to amount; otherwise the symbol resolves to amount divided by its compartment volume.
• Boundary and constant species are captured fixed parameters, rather than evolving states. Boundary species can contribute to kinetic laws while being omitted from the state derivatives. A constant, non-boundary species cannot participate as a reactant or product. Modifiers must identify real species; they introduce no rate term beyond the authored kinetic law.
• Reaction stoichiometries are explicit positive constant integers up to 1,000. The kinetic law is the signed net extent rate in mole/second. Reversible reactions use that law directly; the importer invents no reverse rate.
• Global parameters are explicit finite constants in the imported model and become editable native inputs. Their values are captured once per solve. Local kinetic parameters shadow global symbols in their reaction only. Original SBML identifiers are case-sensitive; deterministic generated names avoid Grid keywords, coordinates, and case-folding collisions.
• Kinetic MathML admits bound ci, finite real/integer cn, and bounded applications of plus, minus, times, divide, power, exp and ln. Binary and unary arities are checked; plus/times admit 2–8 operands. No generic MathML rendering or XML projection is treated as executable kinetics.

Parameter unit labels may be absent or one of dimensionless, mole, second or litre. Labels are retained; dimensional consistency of arbitrary kinetic expressions is not inferred or proved by this profile. Supply numerically consistent rates in the declared model system. Custom unit definitions and scaled units refuse rather than silently converting them.

Bounds are 256 KiB input, 4,096 XML events/nodes, depth 32, 16 compartments, 64 species, 128 global parameters, 128 reactions, 32 local parameters per reaction, and 1 MiB logical output. A tighter embedding context is honored. Cancellation is checked during XML admission and semantic traversal. Malformed structure, unknown attributes/namespaces, duplicates, unresolved references, DTDs, unsupported MathML, unsupported units, and exceeded budgets produce a diagnostic with source offsets. Unsupported constructs include rules, initial assignments, events, functions, delays, conversion factors, variable compartments, SBML packages, notes/annotations, and CDATA. There is no best-effort partial execution.

These conventions are grounded in SBML Level 3 Version 2 Core. This bounded importer is not a claim of full SBML conformance or validation.

Edits, provenance and portability

The generated sbml_import value retains the exact input text, profile, original-to-native name mapping, quantity conventions and parameter scopes. The manifest records the original imported file; current edited parameter inputs remain separate native bindings. Generated sbml_input_N bindings drive global parameters; changing one updates ordinary dependent trajectories. The mapping identifies the corresponding native parameter for per-solve overrides and calibration. Fixed local parameters are private model declarations, not global calibration inputs.

Save the generated source to retain editable inputs and the source manifest. Owning-source serialization and saved LIR retain the same model and provenance. Stripped LIR executes through the existing native solver without an SBML reader; no source parsing occurs in the numerical loop. Persist input edits using the normal model/source lifecycle. Fit reports are ordinary reproducible values; retained calibration jobs use the existing separate Experiments lifecycle.

The transfer example starts with five mole/litre of substrate in a two-litre vessel: ten mole total. Its kinetic expression multiplies volume, rate and concentration, so the independent solution is substrate = 10 exp(-rate*time) and product = 10 - substrate. Both the volume conversion and conservation matter; substituting concentration directly as native amount gives the wrong trajectory.

CellML equations, SED-ML experiments, events, rules, arbitrary unit algebra and broader SBML MathML remain separately scoped work. Existing EQUATIONS, ODE/DAE, events and retained studies remain available in their native authoring forms.