Add cartesian_mesh_from_geometry convenience function

[jcschaff]

What

Generate a VCell finite-volume CartesianMesh directly from a Geometry, without hand-assembling a biomodel:

import pyvcell.vcml as vc

geo = vc.Geometry(name="g", dim=3, extent=(8, 8, 8), origin=(0, 0, 0))
geo.add_sphere("cell", radius=2.0, center=(4, 4, 4))
geo.add_background("bg")
geo.add_surface("cell_bg_membrane", "cell", "bg")

mesh = vc.cartesian_mesh_from_geometry(geo, mesh_size=(64, 64, 64))
# or the convenience method:
mesh = geo.to_cartesian_mesh()       # mesh_size defaults to resolution=50 per active axis

How

cartesian_mesh_from_geometry (in vcml_simulation.py) wraps the geometry in a minimal spatial biomodel — one structure per subvolume (Feature) and surface (Membrane), plus a single diffusing "probe" species so the simulation is a valid PDE — then:

1. uses libvcell (vcml_to_finite_volume_input) + the FV solver (simulate) to run one trivial time step, which writes the .mesh file (the .mesh is produced by the solver from the .vcg, not by the input step);
2. parses it with CartesianMesh(...).read();
3. cleans up the temp output dir and returns the mesh.

mesh_size defaults to the image size for image-based geometries, otherwise resolution (default 50) along each active dimension. Note: the region-defining subvolume must be added before the background (add_sphere then add_background), since earlier subvolumes have higher priority.

API placement / import-weight

• Implementation lives in the heavy/solver module and is exposed lazily from pyvcell.vcml (like simulate).
• Geometry.to_cartesian_mesh(...) delegates via a lazy import, so import pyvcell.vcml.models_geometry stays import-light (verified: pulls no libvcell/pyvcell_fvsolver/vtk/zarr).
• Requires the native + solver extras at call time.

Tests / verification

• tests/vcml/test_mesh_from_geometry.py: 2D and 3D analytic geometries (both the standalone function and the Geometry method), plus the default-resolution path — asserts size/extent/origin, dimension, the two volume regions (bg, cell), and the membrane region. (1D skipped per request; focus on 2D/3D.)
• Manually verified against fixtures too (1D/3D analytic, image-based Bunny → size [107, 87, 107]).
• make check green (ruff, mypy 313 files, deptry); pytest tests/vcml → 46 passed, 5 skipped.

🤖 Generated with Claude Code