pbg-mem3dg

Process-bigraph wrapper for Mem3DG, a membrane mechanics simulator using discrete differential geometry on triangulated surface meshes.

View Interactive Demo Report -- osmotic deflation, membrane patch bulging, and tubular constriction with 3D mesh viewers, Plotly charts, and bigraph architecture diagrams.

What it does

Wraps the Mem3DG simulation engine as a process-bigraph Process, enabling membrane mechanics simulations to be composed with other biological processes in the bigraph framework. The wrapper uses the bridge pattern: it lazily initializes a Mem3DG System and Euler integrator internally, and on each update() call advances the simulation by the requested time interval using manual stepping.

Installation

# System dependency (macOS)
brew install netcdf-cxx

# Install into a virtual environment
uv venv .venv && source .venv/bin/activate
uv pip install -e .

Quick Start

from process_bigraph import Composite, allocate_core, gather_emitter_results
from process_bigraph.emitter import RAMEmitter
from pbg_mem3dg import Mem3DGProcess, make_membrane_document

core = allocate_core()
core.register_link('Mem3DGProcess', Mem3DGProcess)
core.register_link('ram-emitter', RAMEmitter)

doc = make_membrane_document(
    mesh_type='icosphere',
    radius=1.0,
    subdivision=3,
    Kbc=8.22e-5,
    tension_modulus=0.1,
    osmotic_strength=0.02,
    preferred_volume_fraction=0.7,
    interval=100.0,
)

sim = Composite({'state': doc}, core=core)
sim.run(1000.0)

results = gather_emitter_results(sim)
emitter_data = results[('emitter',)]
for entry in emitter_data:
    print(f"t={entry['time']:.0f}  E={entry['total_energy']:.6f}  V={entry['volume']:.4f}")

API Reference

Mem3DGProcess (Process)

Output ports (all overwrite — absolute values, not deltas):

make_membrane_document()

Factory function that returns a composite document dict with:

• membrane: the Mem3DGProcess wired to stores
• stores: shared state
• emitter: RAM emitter collecting energy, area, volume time series

Architecture

Composite
├── membrane (Mem3DGProcess)
│   └── internally manages:
│       ├── pymem3dg.System (mesh + physics)
│       └── pymem3dg.Euler (integrator)
├── stores/
│   ├── vertex_positions
│   ├── mean_curvatures
│   ├── total_energy, bending_energy, ...
│   ├── surface_area, volume
│   └── converged
└── emitter (RAMEmitter)
    └── records energy, area, volume vs time

The bridge pattern: on each update(state, interval), the process advances Mem3DG's Euler integrator by interval time units using march(), then reads updated geometry and energy back into PBG output ports.

Demo

python demo/demo_report.py

Produces demo/demo_output.png showing energy, surface area, and volume evolution during membrane relaxation.

Tests

pytest tests/ -v