Add microfluidic geometry and transport primitives

[marpaia]

Purpose

This first stack layer defines the CellModeller2 contracts needed to represent device walls, spatial flow, and washout. These are new modeling primitives beyond the legacy CellModeller mechanics and signal logic.

Key methodological contributions

• Finite device walls with full-capsule contact: add axis-aligned boxes, z-aligned cylinders, and spheres with explicit INSIDE and OUTSIDE admissible regions. Outside-sphere contact projects the obstacle center onto the complete rod centerline; finite boxes and cylinders minimize their analytic signed-distance functions along the complete centerline after an expanded-bounds rejection test. Contacts carry the minimizing centerline location into the existing one-sided seven-degree-of-freedom mechanics operator, so a rod crossing a wall at mid-span produces the correct translational and rotational constraint. CPU, Metal, and CUDA implement the same geometry; checkpoints, scenes, and the viewer preserve it.
• Walls that also block chemistry: add a per-voxel solid mask to signal grids. Fluid-solid faces use no-flux diffusion and zero advective flux, solid sites carry no concentration or reaction, and trilinear sampling and scatter renormalize over fluid sites. This gives model authors paired mechanical and transport representations of the same device boundary.
• Spatially varying transport flow: add one face-staggered velocity field shared by all signals. First-order upwind fluxes read the normal velocity on each face, so a divergence-free supplied field is discretely conservative and closed wall faces are exactly zero.
• Washout semantics: add stable-ID cell removal with compacted storage but retained lineage, enabling cells that leave a device to be removed without breaking ancestry.

Scientific scope and merge boundary

• Boxes are axis-aligned and cylinders are z-aligned; arbitrary orientations are not represented.
• Wall contact is a static overlap constraint evaluated at each mechanics step, not continuous collision detection. A cell can still tunnel through a thin wall if a timestep or an externally imposed displacement carries the complete capsule past it between evaluations.
• The analytic mechanics geometry and voxel mask are separate inputs in this layer. Their consistency remains an authoring responsibility until the device helpers in PR Add numerical flow solvers for device authoring #3.
• The velocity field is supplied data and advects signals only. This PR contains neither a flow solver nor fluid coupling to cells.
• CUDA coverage here is compile-only because no NVIDIA runtime was available; CUDA runtime parity remains required before claiming runtime validation on that backend.

Stack

PR 1 of 5, based directly on master.

Next: #3 (marpaia/microfluidics-flow-solvers).

Validation

• CPU CTest: 20 of 20 passed
• Metal native conformance: 21 of 21 passed, including runtime compilation and execution of the Metal contact kernels
• Python: 213 passed, 40 skipped; skips require CUDA or a separately supplied legacy CellModeller checkout
• CUDA 12.8 compile gate: all CUDA kernels and test binaries compiled and linked for architecture 75; runtime tests were enumerated but not executed
• Ruff: passed
• Pyright: 0 errors