pyvcell 0.2.4__tar.gz → 0.3.0__tar.gz

{pyvcell-0.2.4 → pyvcell-0.3.0}/PKG-INFO

@@ -1,38 +1,46 @@
 Metadata-Version: 2.3
 Name: pyvcell
-Version: 0.2.4
+Version: 0.3.0
 Summary: This is the python wrapper for vcell modeling and simulation
 Author: Jim Schaff, Logan Drescher
 Author-email: Jim Schaff <schaff@uchc.edu>, Logan Drescher <drescher@uchc.edu>
-Requires-Dist: antimony>=3.1.3
-Requires-Dist: h5py>=3.11.0,<4
-Requires-Dist: imageio>=2.37.0,<3
-Requires-Dist: libvcell>=0.0.15.3
 Requires-Dist: lxml>=6.1.0,<7
-Requires-Dist: matplotlib>=3.10.0,<4
 Requires-Dist: numexpr>=2.10,<3
 Requires-Dist: numpy>=1.26.4,<3.0
-Requires-Dist: orjson>=3.10.3,<4
-Requires-Dist: overrides>=7.7.0,<8
 Requires-Dist: pydantic>=2.10.5,<3
-Requires-Dist: python-dateutil>=2.8.2,<3
-Requires-Dist: python-libsbml>=5.20.4,<6
-Requires-Dist: pyvcell-fvsolver>=0.2.1
-Requires-Dist: pyvista>=0.44.2,<1
-Requires-Dist: requests>=2.32.3,<3
-Requires-Dist: requests-oauth2client>=1.6.0,<2
-Requires-Dist: sympy>=1.13.1,<2
-Requires-Dist: tensorstore>=0.1.72,<1
-Requires-Dist: trame>=3.8.1,<4
-Requires-Dist: trame-server>=3.4.0,<4
-Requires-Dist: trame-vtk>=2.8.15,<3
-Requires-Dist: trame-vuetify>=3.2.2,<4
-Requires-Dist: typer>=0.12.3,<1.0.0
 Requires-Dist: typing-extensions>=4.12.2,<5
-Requires-Dist: urllib3>=2.3.0,<3
-Requires-Dist: vtk>=9.3.1,<10
-Requires-Dist: zarr>=2.17.2,<3
-Requires-Python: >=3.10, <4.0
+Requires-Dist: pyvcell[solver,viz,remote,io,convert,native] ; extra == 'all'
+Requires-Dist: antimony>=3.1.3 ; extra == 'convert'
+Requires-Dist: python-libsbml>=5.20.4,<6 ; extra == 'convert'
+Requires-Dist: sympy>=1.13.1,<2 ; extra == 'convert'
+Requires-Dist: h5py>=3.11.0,<4 ; extra == 'io'
+Requires-Dist: orjson>=3.10.3,<4 ; extra == 'io'
+Requires-Dist: tensorstore>=0.1.72,<1 ; extra == 'io'
+Requires-Dist: typer>=0.12.3,<1.0.0 ; extra == 'io'
+Requires-Dist: zarr>=2.17.2,<3 ; extra == 'io'
+Requires-Dist: libvcell>=0.0.15.3 ; extra == 'native'
+Requires-Dist: overrides>=7.7.0,<8 ; extra == 'remote'
+Requires-Dist: python-dateutil>=2.8.2,<3 ; extra == 'remote'
+Requires-Dist: requests>=2.32.3,<3 ; extra == 'remote'
+Requires-Dist: requests-oauth2client>=1.6.0,<2 ; extra == 'remote'
+Requires-Dist: urllib3>=2.3.0,<3 ; extra == 'remote'
+Requires-Dist: pyvcell-fvsolver>=0.2.1 ; extra == 'solver'
+Requires-Dist: imageio>=2.37.0,<3 ; extra == 'viz'
+Requires-Dist: matplotlib>=3.10.0,<4 ; extra == 'viz'
+Requires-Dist: pyvista>=0.44.2,<1 ; extra == 'viz'
+Requires-Dist: trame>=3.8.1,<4 ; extra == 'viz'
+Requires-Dist: trame-server>=3.4.0,<4 ; extra == 'viz'
+Requires-Dist: trame-vtk>=2.8.15,<3 ; extra == 'viz'
+Requires-Dist: trame-vuetify>=3.2.2,<4 ; extra == 'viz'
+Requires-Dist: vtk>=9.3.1,<10 ; extra == 'viz'
+Requires-Python: >=3.12, <4.0
+Provides-Extra: all
+Provides-Extra: convert
+Provides-Extra: io
+Provides-Extra: native
+Provides-Extra: remote
+Provides-Extra: solver
+Provides-Extra: viz
 Description-Content-Type: text/markdown
 
 # pyvcell

{pyvcell-0.2.4 → pyvcell-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "pyvcell"
-version = "0.2.4"
-requires-python = ">=3.10,<4.0"
+version = "0.3.0"
+requires-python = ">=3.12,<4.0"
 description = "This is the python wrapper for vcell modeling and simulation"
 repository = "https://github.com/virtualcell/pyvcell"
 documentation = "https://virtualcell.github.io/pyvcell/"
@@ -14,39 +14,62 @@ authors = [
 packages = [
     {include="pyvcell"},
 ]
+# Core: just what the data models + VCML reader/writer need. Heavy runtime deps
+# live in the optional-dependencies extras below; install pyvcell[all] for the
+# full feature set (solver, viz, remote, io, convert, native).
 dependencies = [
-    "antimony (>=3.1.3)",
-    "h5py>=3.11.0,<4",
-    "imageio>=2.37.0,<3",
-    "libvcell (>=0.0.15.3)",
     "lxml>=6.1.0,<7",
-    "matplotlib>=3.10.0,<4",
     "numexpr>=2.10,<3",
     "numpy>=1.26.4,<3.0",
-    "orjson>=3.10.3,<4",
-    "overrides>=7.7.0,<8",
     "pydantic>=2.10.5,<3",
-    "python-dateutil>=2.8.2,<3",
-    "python-libsbml>=5.20.4,<6",
+    "typing-extensions>=4.12.2,<5",
+]
+
+[project.optional-dependencies]
+solver = [
     "pyvcell-fvsolver (>=0.2.1)",
+]
+viz = [
+    "imageio>=2.37.0,<3",
+    "matplotlib>=3.10.0,<4",
     "pyvista>=0.44.2,<1",
-    "requests>=2.32.3,<3",
-    "requests-oauth2client>=1.6.0,<2",
-    "sympy>=1.13.1,<2",
-    "tensorstore>=0.1.72,<1",
     "trame>=3.8.1,<4",
     "trame-server>=3.4.0,<4",
     "trame-vtk>=2.8.15,<3",
     "trame-vuetify>=3.2.2,<4",
-    "typer>=0.12.3,<1.0.0",
-    "typing-extensions>=4.12.2,<5",
-    "urllib3>=2.3.0,<3",
     "vtk>=9.3.1,<10",
+]
+remote = [
+    "overrides>=7.7.0,<8",
+    "python-dateutil>=2.8.2,<3",
+    "requests>=2.32.3,<3",
+    "requests-oauth2client>=1.6.0,<2",
+    "urllib3>=2.3.0,<3",
+]
+io = [
+    "h5py>=3.11.0,<4",
+    "orjson>=3.10.3,<4",
+    "tensorstore>=0.1.72,<1",
+    "typer>=0.12.3,<1.0.0",
     "zarr>=2.17.2,<3", # major upgrade will take some work!
 ]
+convert = [
+    "antimony (>=3.1.3)",
+    "python-libsbml>=5.20.4,<6",
+    "sympy>=1.13.1,<2",
+]
+native = [
+    "libvcell (>=0.0.15.3)",
+]
+all = [
+    "pyvcell[solver,viz,remote,io,convert,native]",
+]
 
 [dependency-groups]
 dev = [
+    # Dev/CI work against the full feature set (all optional extras). End users
+    # opt in per extra (e.g. `pip install pyvcell[viz]`) or `pip install pyvcell[all]`.
+    "pyvcell[all]",
     "pytest>=7.2.0,<8",
     "pytest-cov>=4.0.0,<5",
     "deptry>=0.16.2,<1",
@@ -76,6 +99,12 @@ build-backend = "uv_build"
 module-name = "pyvcell"
 module-root = ""
 
+[tool.deptry.per_rule_ignores]
+# `pyvcell[all]` is in the dev group so dev/CI install every optional extra;
+# it is a self-reference (first-party), so deptry's "unused dependency" check
+# does not apply.
+DEP002 = ["pyvcell"]
+
 [tool.mypy]
 files = ["pyvcell", "tests", "examples"]
 exclude = ["stubs.*"]

{pyvcell-0.2.4 → pyvcell-0.3.0}/pyvcell/_internal/simdata/python_infix.py

@@ -1,7 +1,8 @@
-from libvcell import vcell_infix_to_num_expr_infix
-
-
 def get_numexpr_expression(vcell_expression: str) -> str:
+    # libvcell (the `native` extra) is imported lazily so that importing the data
+    # models / VCML reader does not require it.
+    from libvcell import vcell_infix_to_num_expr_infix
+
     # First, get the string from vcell
     translation_result: bool
     result_message: str

{pyvcell-0.2.4 → pyvcell-0.3.0}/pyvcell/sbml/sbml_simulation.py

@@ -3,8 +3,6 @@ import shutil
 import tempfile
 from pathlib import Path
 
-from libvcell import sbml_to_finite_volume_input
-
 from pyvcell._internal.solvers.fvsolver import solve as fvsolve
 from pyvcell.sbml.sbml_spatial_model import SbmlSpatialModel
 from pyvcell.sim_results.result import Result
@@ -22,6 +20,8 @@ class SbmlSpatialSimulation:
             self.out_dir = out_dir if isinstance(out_dir, Path) else Path(out_dir)
 
     def run(self, duration: float | None = None, output_time_step: float | None = None) -> Result:
+        from libvcell import sbml_to_finite_volume_input
+
         # prepare solver input files
         # 1. upload the SBML model and retrieve generated solver inputs as a zip file
         # 2. extract the zip archive into the output directory

pyvcell-0.3.0/pyvcell/vcml/__init__.py

@@ -0,0 +1,256 @@
+"""Public API for ``pyvcell.vcml``.
+
+The lightweight data layer is eager: the data models (``models``,
+``models_geometry``, ``models_math``) and ``VcmlReader`` import with only the
+core dependencies (pydantic, lxml, numpy, numexpr). Everything that needs a
+heavy optional dependency — ``VcmlWriter``, ``Field``, ``SegmentedImageGeometry``,
+the remote ``VCellSession`` / ``connect`` / ``simulate`` API, and the ``utils`` /
+``workspace`` helpers — is imported lazily (PEP 562) on first access. If the
+optional dependency is missing, the lazy import raises a clear error naming the
+extra to install (e.g. ``pip install pyvcell[viz]``).
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+# --- eager, lightweight: data models + VCML reader (core deps only) ---
+from pyvcell.vcml.models import (
+    Application,
+    Biomodel,
+    BoundaryType,
+    Compartment,
+    Kinetics,
+    KineticsParameter,
+    Model,
+    ModelParameter,
+    Reaction,
+    Simulation,
+    Species,
+    SpeciesMapping,
+    SpeciesReference,
+    SpeciesRefType,
+    VCMLDocument,
+    Version,
+)
+from pyvcell.vcml.models_geometry import (
+    Geometry,
+    Image,
+    PixelClass,
+    SubVolume,
+    SubVolumeType,
+    SurfaceClass,
+)
+from pyvcell.vcml.models_math import (
+    Boundaries,
+    CompartmentSubDomain,
+    Constant,
+    Effect,
+    JumpCondition,
+    JumpProcess,
+    MathBoundaryType,
+    MathDescription,
+    MathFunction,
+    MathVariable,
+    MathVariableType,
+    MembraneSubDomain,
+    OdeEquation,
+    ParticleInitialCount,
+    ParticleJumpProcess,
+    ParticleProperties,
+    PdeEquation,
+    VariableInitialCount,
+    Velocity,
+)
+from pyvcell.vcml.vcml_reader import VcmlReader
+
+if TYPE_CHECKING:
+    # Heavy names — eager only for type checkers / IDE autocomplete.
+    from pyvcell._internal.geometry import SegmentedImageGeometry
+    from pyvcell.vcml.field import Field
+    from pyvcell.vcml.session import SimulationJob, VCellSession
+    from pyvcell.vcml.utils import (
+        field_data_refs,
+        load_antimony_file,
+        load_antimony_str,
+        load_sbml_file,
+        load_sbml_str,
+        load_sbml_url,
+        load_vcml_file,
+        load_vcml_str,
+        load_vcml_url,
+        restore_stdout,
+        suppress_stdout,
+        to_antimony_str,
+        to_sbml_str,
+        to_vcml_str,
+        update_biomodel,
+        write_antimony_file,
+        write_sbml_file,
+        write_vcml_file,
+    )
+    from pyvcell.vcml.vcml_remote import connect, logout
+    from pyvcell.vcml.vcml_simulation import simulate
+    from pyvcell.vcml.vcml_writer import VcmlWriter
+    from pyvcell.vcml.workspace import get_workspace_dir, set_workspace_dir
+
+
+# Heavy public name -> the submodule that defines it (imported on first access).
+_LAZY_IMPORTS: dict[str, str] = {
+    "SegmentedImageGeometry": "pyvcell._internal.geometry",
+    "Field": "pyvcell.vcml.field",
+    "VcmlWriter": "pyvcell.vcml.vcml_writer",
+    **dict.fromkeys(["SimulationJob", "VCellSession"], "pyvcell.vcml.session"),
+    **dict.fromkeys(["connect", "logout"], "pyvcell.vcml.vcml_remote"),
+    "simulate": "pyvcell.vcml.vcml_simulation",
+    **dict.fromkeys(["get_workspace_dir", "set_workspace_dir"], "pyvcell.vcml.workspace"),
+    **dict.fromkeys(
+        [
+            "field_data_refs",
+            "load_antimony_file",
+            "load_antimony_str",
+            "load_sbml_file",
+            "load_sbml_str",
+            "load_sbml_url",
+            "load_vcml_file",
+            "load_vcml_str",
+            "load_vcml_url",
+            "restore_stdout",
+            "suppress_stdout",
+            "to_antimony_str",
+            "to_sbml_str",
+            "to_vcml_str",
+            "update_biomodel",
+            "write_antimony_file",
+            "write_sbml_file",
+            "write_vcml_file",
+        ],
+        "pyvcell.vcml.utils",
+    ),
+}
+
+# Missing optional top-level module -> the extra that provides it, for a clear hint.
+_EXTRA_FOR_MODULE: dict[str, str] = {
+    "libvcell": "native",
+    "pyvcell_fvsolver": "solver",
+    "fvsolver": "solver",
+    "vtk": "viz",
+    "pyvista": "viz",
+    "matplotlib": "viz",
+    "imageio": "viz",
+    "trame": "viz",
+    "trame_server": "viz",
+    "trame_vtk": "viz",
+    "trame_vuetify": "viz",
+    "requests": "remote",
+    "requests_oauth2client": "remote",
+    "urllib3": "remote",
+    "dateutil": "remote",
+    "overrides": "remote",
+    "tensorstore": "io",
+    "zarr": "io",
+    "h5py": "io",
+    "orjson": "io",
+    "typer": "io",
+    "antimony": "convert",
+    "libsbml": "convert",
+    "sympy": "convert",
+}
+
+
+def __getattr__(name: str) -> object:
+    module_path = _LAZY_IMPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as exc:
+        missing = (exc.name or "").split(".")[0]
+        extra = _EXTRA_FOR_MODULE.get(missing)
+        hint = f"pip install pyvcell[{extra}]" if extra else "pip install pyvcell[all]"
+        raise ModuleNotFoundError(
+            f"pyvcell.vcml.{name} requires the optional dependency '{missing}', which is not installed. "
+            f"Install it with `{hint}`."
+        ) from exc
+    value = getattr(module, name)
+    globals()[name] = value  # cache so __getattr__ is not consulted again for this name
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+__all__ = [
+    "Application",
+    "Biomodel",
+    "Boundaries",
+    "BoundaryType",
+    "Compartment",
+    "CompartmentSubDomain",
+    "Constant",
+    "Effect",
+    "Field",
+    "Geometry",
+    "Image",
+    "JumpCondition",
+    "JumpProcess",
+    "Kinetics",
+    "KineticsParameter",
+    "MathBoundaryType",
+    "MathDescription",
+    "MathFunction",
+    "MathVariable",
+    "MathVariableType",
+    "MembraneSubDomain",
+    "Model",
+    "ModelParameter",
+    "OdeEquation",
+    "ParticleInitialCount",
+    "ParticleJumpProcess",
+    "ParticleProperties",
+    "PdeEquation",
+    "PixelClass",
+    "Reaction",
+    "SegmentedImageGeometry",
+    "Simulation",
+    "SimulationJob",
+    "Species",
+    "SpeciesMapping",
+    "SpeciesRefType",
+    "SpeciesReference",
+    "SubVolume",
+    "SubVolumeType",
+    "SurfaceClass",
+    "VCMLDocument",
+    "VCellSession",
+    "VariableInitialCount",
+    "VcmlReader",
+    "VcmlWriter",
+    "Velocity",
+    "Version",
+    "connect",
+    "field_data_refs",
+    "get_workspace_dir",
+    "load_antimony_file",
+    "load_antimony_str",
+    "load_sbml_file",
+    "load_sbml_str",
+    "load_sbml_url",
+    "load_vcml_file",
+    "load_vcml_str",
+    "load_vcml_url",
+    "logout",
+    "restore_stdout",
+    "set_workspace_dir",
+    "simulate",
+    "suppress_stdout",
+    "to_antimony_str",
+    "to_sbml_str",
+    "to_vcml_str",
+    "update_biomodel",
+    "write_antimony_file",
+    "write_sbml_file",
+    "write_vcml_file",
+]

pyvcell-0.3.0/pyvcell/vcml/models.py

@@ -0,0 +1,222 @@
+from pydantic import Field
+
+# Base + sibling-layer types are re-exported here (the `as` form marks them as an
+# explicit re-export) so `pyvcell.vcml.models.X` keeps resolving for all of them.
+from pyvcell.vcml.models_app import (
+    Application as Application,
+)
+from pyvcell.vcml.models_app import (
+    ApplicationParameter as ApplicationParameter,
+)
+from pyvcell.vcml.models_app import (
+    BoundaryType as BoundaryType,
+)
+from pyvcell.vcml.models_app import (
+    CompartmentMapping as CompartmentMapping,
+)
+from pyvcell.vcml.models_app import (
+    ReactionMapping as ReactionMapping,
+)
+from pyvcell.vcml.models_app import (
+    Simulation as Simulation,
+)
+from pyvcell.vcml.models_app import (
+    SpeciesMapping as SpeciesMapping,
+)
+from pyvcell.vcml.models_app import (
+    StructureMapping as StructureMapping,
+)
+from pyvcell.vcml.models_base import Parameter as Parameter
+from pyvcell.vcml.models_base import StrEnum as StrEnum
+from pyvcell.vcml.models_base import VcmlNode as VcmlNode
+from pyvcell.vcml.models_base import Version as Version
+from pyvcell.vcml.models_geometry import Geometry
+
+
+class Compartment(VcmlNode):
+    name: str
+    dim: int
+
+
+class Species(VcmlNode):
+    name: str
+    compartment_name: str
+
+
+class ModelParameter(Parameter):
+    pass
+
+
+class KineticsParameter(Parameter):
+    reaction_name: str
+
+
+class Kinetics(VcmlNode):
+    kinetics_type: str
+    kinetics_parameters: list[KineticsParameter] = Field(default_factory=list)
+
+
+class SpeciesRefType(StrEnum):
+    reactant = "reactant"
+    product = "product"
+    modifier = "modifier"
+
+
+class SpeciesReference(VcmlNode):
+    name: str
+    stoichiometry: int
+    species_ref_type: SpeciesRefType
+
+
+class Reaction(VcmlNode):
+    name: str
+    compartment_name: str
+    reversible: bool = True
+    is_flux: bool = False
+    kinetics: Kinetics | None = None
+    reactants: list[SpeciesReference] = Field(default_factory=list)
+    products: list[SpeciesReference] = Field(default_factory=list)
+
+
+class Model(VcmlNode):
+    name: str
+    species: list[Species] = Field(default_factory=list)
+    compartments: list[Compartment] = Field(default_factory=list)
+    reactions: list[Reaction] = Field(default_factory=list)
+    model_parameters: list[ModelParameter] = Field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return f"Model(compartments={self.compartment_names}, species={self.species_names}, reactions={self.reaction_names}, parameters={self.parameter_names})"
+
+    @property
+    def species_names(self) -> list[str]:
+        return [s.name for s in self.species]
+
+    def get_species(self, name: str) -> Species:
+        for species in self.species:
+            if species.name == name:
+                return species
+        raise ValueError(f"Species '{name}' not found in model.")
+
+    @property
+    def compartment_names(self) -> list[str]:
+        return [c.name for c in self.compartments]
+
+    def get_compartment(self, name: str) -> Compartment:
+        for compartment in self.compartments:
+            if compartment.name == name:
+                return compartment
+        raise ValueError(f"Compartment '{name}' not found in model.")
+
+    @property
+    def reaction_names(self) -> list[str]:
+        return [r.name for r in self.reactions]
+
+    def get_reaction(self, name: str) -> Reaction:
+        for reaction in self.reactions:
+            if reaction.name == name:
+                return reaction
+        raise ValueError(f"Reaction '{name}' not found in model.")
+
+    @property
+    def parameter_names(self) -> list[str]:
+        return [mp.name for mp in self.model_parameters]
+
+    def get_parameter(self, name: str) -> ModelParameter | KineticsParameter:
+        if "." in name:
+            reaction_name, param_name = name.split(".")
+            for reaction in self.reactions:
+                if reaction.name == reaction_name and reaction.kinetics:
+                    for kinetics_param in reaction.kinetics.kinetics_parameters:
+                        if kinetics_param.name == param_name:
+                            return kinetics_param
+        for model_parameter in self.model_parameters:
+            if model_parameter.name == name:
+                return model_parameter
+        raise ValueError(f"Parameter '{name}' not found in model.")
+
+    @property
+    def parameter_values(self) -> dict[str, float | str]:
+        model_params = {mp.name: mp.value for mp in self.model_parameters}
+        kin_params = {
+            f"{r.name}.{p.name}": p.value
+            for r in self.reactions
+            if r.kinetics
+            for p in r.kinetics.kinetics_parameters
+            if r.kinetics.kinetics_parameters
+        }
+        return {**model_params, **kin_params}
+
+    def set_parameter_value(self, name: str, value: float | str) -> None:
+        param = self.get_parameter(name=name)
+        param.value = value
+
+    def add_compartment(self, name: str, dim: int) -> Compartment:
+        compartment = Compartment(name=name, dim=dim)
+        self.compartments.append(compartment)
+        return compartment
+
+    def add_species(self, name: str, compartment: str | Compartment) -> Species:
+        compartment_name = compartment.name if isinstance(compartment, Compartment) else compartment
+        species = Species(name=name, compartment_name=compartment_name)
+        self.species.append(species)
+        return species
+
+    def add_model_parameter(self, name: str, value: float | str, role: str = "user defined") -> ModelParameter:
+        model_parameter = ModelParameter(name=name, value=value, role=role, unit="")
+        self.model_parameters.append(model_parameter)
+        return model_parameter
+
+    def add_reaction_mass_action(
+        self,
+        name: str,
+        comp: str | Compartment,
+        reactants: list[str | Species],
+        products: list[str | Species],
+        kf: float | str,
+        kr: float | str,
+    ) -> Reaction:
+        comp_name = comp.name if isinstance(comp, Compartment) else comp
+        p_kf = KineticsParameter(name="Kf", value=kf, role="forward rate constant", unit="", reaction_name=name)
+        p_kr = KineticsParameter(name="Kr", value=kr, role="reverse rate constant", unit="", reaction_name=name)
+        kinetics = Kinetics(kinetics_type="MassAction", kinetics_parameters=[p_kf, p_kr])
+        reaction = Reaction(name=name, compartment_name=comp_name, reversible=True, is_flux=False, kinetics=kinetics)
+        for reactant in reactants:
+            reactant_name = reactant.name if isinstance(reactant, Species) else reactant
+            reaction.reactants.append(
+                SpeciesReference(name=reactant_name, stoichiometry=1, species_ref_type=SpeciesRefType.reactant)
+            )
+        for product in products:
+            product_name = product.name if isinstance(product, Species) else product
+            reaction.products.append(
+                SpeciesReference(name=product_name, stoichiometry=1, species_ref_type=SpeciesRefType.product)
+            )
+        self.reactions.append(reaction)
+        return reaction
+
+
+class Biomodel(VcmlNode):
+    name: str
+    model: Model | None = None
+    applications: list[Application] = Field(default_factory=list)
+    version: Version | None = None
+
+    def __repr__(self) -> str:
+        return f"Biomodel(model={self.model.__repr__()}, applications={self.application_names}, simulations={self.simulation_names})"
+
+    @property
+    def application_names(self) -> list[str]:
+        return [app.name for app in self.applications]
+
+    def add_application(self, name: str, geometry: Geometry) -> Application:
+        application = Application(name=name, stochastic=False, geometry=geometry)
+        self.applications.append(application)
+        return application
+
+    @property
+    def simulation_names(self) -> list[str]:
+        return [sim.name for app in self.applications for sim in app.simulations]
+
+
+class VCMLDocument(VcmlNode):
+    biomodel: Biomodel | None = None