Add numerical flow solvers for device authoring

[marpaia]

Purpose

This layer introduces the numerical flow and device-authoring methodology. It turns PR #2's wall and transport primitives into reproducible microfluidic inputs; it does not yet move cells with the resulting field.

Key methodological contributions

• Depth-averaged device flow: cellmodeller2.flow solves div(m grad p) = 0 over fluid voxels with harmonic face mobilities, fixed inlet and outlet pressures, and no wall flux. A matrix-free preconditioned conjugate-gradient solve produces a face-staggered field that satisfies discrete continuity to solver tolerance and is normalized to a requested mean inlet speed. Gap-height mobility supplies the Hele-Shaw closure.
• Resolved Stokes-Brinkman reference: cellmodeller2.stokes solves the incompressible Stokes-Brinkman equations on a marker-and-cell grid with no-slip voxel walls and optional drag. It returns the same velocity representation used by signal transport, providing a higher-cost reference when the mesh resolves the channel gap.
• Phenomenological colony feedback: cell volume is rasterized into center voxels and converted to Kozeny-Carman-style resistance. colony_mobility combines that resistance with channel mobility, and Simulation.set_velocity_field atomically installs a re-solved field at a model-chosen cadence.
• One device description across mechanics and transport: TrapChannelDevice and BiopixelTrapDevice generate analytic mechanics walls, a conservatively voxelized solid mask, fixed reservoirs, gap mobility, and a solved flow field from common dimensions. A voxel is solid only when it lies wholly inside a wall, so the smooth mechanics boundary encloses the transport mask.
• Source-separated CAD and device contracts: the bounded ASCII-DXF reader returns model-space drawing coordinates without guessing physical units; callers must provide a source-specific scale. Block definitions are opt-in and remain unplaced because INSERT transforms are not applied. Separately, BiopixelTrapDevice defaults to the published 100 x 85 x 1.65 micrometer Prindle trapping region; channel dimensions, wall thickness, and flow speed remain explicit model choices. The supplied CAD assets are isolated in Add Prindle microfluidic device source files #5 and interpreted in Add microfluidic device and biology tutorials #6.

Scientific scope

• The depth-averaged solver omits in-plane viscous boundary layers and returns gap-mean velocity. The MAC solver is the appropriate reference when the gap is resolved and wall shear or cross-channel profiles matter.
• Both solvers impose a pressure shape and then normalize to mean inlet speed. They represent constant-flow operation and do not predict pressure drop or viscosity-dependent amplitude.
• Colony resistance is a phenomenological center-voxel closure. Its coefficient, mesh, and refresh cadence are model choices rather than measured device constants.
• CAD extraction establishes drawing geometry only. Physical units, fabrication layers, registration, and correspondence to a published device require source-specific evidence; generic block placement is unsupported.
• The benchmark suite checks conservation, convergence, analytic profiles, a literature duct ratio, and cross-solver agreement. It is numerical verification, not device-scale experimental validation.
• Cell motion is intentionally deferred to experimental PR Add experimental kinematic flow coupling #4.

Stack

PR 2 of 5.

Base: #2 (marpaia/microfluidics-primitives)

Next: #4 (marpaia/microfluidics-experimental-coupling)

Validation

• Exact Add numerical flow solvers for device authoring #3 CPU-only package: 221 passed, 63 skipped
• Focused flow, mask, and device tests: 32 passed
• Flow benchmark suite: 10 of 10 passed
• Ruff: passed
• Pyright: 0 errors; 3 compiled-extension source-resolution warnings