VFGen XML Exporter

Epimodels can export continuous-time (ODE) models to the VFGen XML format, enabling use with external numerical analysis tools such as AUTO, MATLAB, and Scipy-based utilities.

VFGen is a tool that converts vector field definitions into code for various target languages and analysis frameworks. See the VFGen documentation for the full XML specification.

Quick Start

from epimodels.continuous import SIR
from epimodels.exporters import VFGenExporter

model = SIR()
model.param_values = {'beta': 0.3, 'gamma': 0.1}

exporter = VFGenExporter(model)

# Export to file
exporter.export("sir_model.xml", initial_conditions={'S': 990, 'I': 10, 'R': 0})

# Export to string
xml_str = exporter.export(
    initial_conditions={'S': 990, 'I': 10, 'R': 0},
    population=1000,
)
print(xml_str)

The VFGenExporter automatically extracts the model’s ODE formulas via symbolic analysis and converts them to the VFGen XML schema.

Export Options

The export() method supports several options:

exporter = VFGenExporter(model)

# Full export with all options
xml = exporter.export(
    filepath="model.xml",                  # Write to file (None = return string)
    default_values={'beta': 0.3, 'gamma': 0.1},  # Override parameter defaults
    initial_conditions={'S': 990, 'I': 10, 'R': 0},
    population=1000,                       # Total population (N)
    include_description=True,              # Include Description attributes
    include_latex=True,                    # Include LaTeX symbol attributes
    include_n_constant=True,               # Include N as a Constant element
    validate_formulas_flag=True,           # Validate formulas before export
)

Advanced: Custom Expressions and Functions

You can add custom expressions and functions to the XML output:

import sympy as sp

# Custom expression (e.g., force of infection)
beta, S, I, N = sp.symbols('beta S I N')
foi = beta * S * I / N

exporter = VFGenExporter(model)
xml = exporter.export(
    expressions={'FOI': foi},              # Additional Expression elements
    functions={'log_base2': sp.log(2)},    # Additional Function elements
)

Supported Models

VFGen export is supported for all continuous-time models that have a well-defined _model() method, including:

  • SIR

  • SIS

  • SIRS

  • SEIR

  • SEQIAHR

  • SIRSEI

  • SIR2Strain

  • All other ContinuousModel subclasses

If automatic formula extraction fails for a custom model, you can define _formulas manually on the model class.

API Reference