Region variables: VolumeRegion/MembraneRegion equations in the math model, VCML, and results

[jcschaff]

Why

VCell writes a well-mixed species in a spatial application, and a whole-membrane quantity such as the membrane potential, as a region variable. A region variable has one value per connected region and is governed by a VolumeRegionEquation or MembraneRegionEquation. pyvcell read the variables but dropped their equations. Everything downstream saw undeclared variables: in the vcell-fenics coverage survey, 29 of 600 sampled public applications failed this way (virtualcell/vcell-fenics#188).

Result processing also crashed on any such model. A volume function that uses the region variable had no numexpr binding, so write_zarr raised KeyError: 's1'.

What

• Math model (models_math.py): VolumeRegionEquation (uniform_rate, volume_rate, initial, solution_type, solution) on CompartmentSubDomain, and MembraneRegionEquation (with membrane_rate) on MembraneSubDomain. Both are exported from pyvcell.vcml.
• VCML read/write, matching VCell's XmlReader / Xmlproducer: UniformRate and the region rate (written as 0.0 when absent), Initial, and <SolutionType Type="unknown|exact">, whose text is an exact solution.
• SpeciesMapping flags: force_constant, well_mixed and force_continuous (the LocalizedCompoundSpec attributes). The writer used to drop them, so any round trip, including vc.simulate, turned a well-mixed species spatial and unclamped a clamped species.
• Results (zarr_writer.py), per the "push it down to each element" convention used for x/y/z/t: each domain-qualified VOLUME_REGION state variable is replicated onto every voxel of its region (values[volume_region_map]). It becomes its own channel, placed after the volume variables, and a binding for the volume functions. The solver's built-in region quantities (vcRegionVolume, no domain) aren't state, so they stay out. Membrane-region variables stay out of the zarr for now, like membrane variables, since it's a volume grid.

Tests

• New fixture SmallSpatialProject_3D_well_mixed.vcml (20 KB): the existing 3D fixture with s1 (volume) and s2 (membrane) marked well-mixed, and its math regenerated by libvcell. s1 becomes a VolumeRegionVariable and s2 a MembraneRegionVariable.
• Reading: the region equations come back as expected.
• Round trips: the math round trip is extended to this fixture, and the species-mapping flags round-trip (including a clamped species).
• fvsolver run: the s1 channel exists; J_r0 = f(s0, s1) evaluates; and at every output time s1 is constant across subdomain0 and equal to the solver's per-region value.
• Suite: pytest gives 115 passed and 11 skipped, and mypy and pre-commit are clean.

🤖 Generated with Claude Code