VCell Moving Boundary Solver

A C++ solver library for moving-boundary problems in biological systems. A single build produces three artifacts:

Prerequisites

All platforms

Boost is required (header-only) — the build fails at configure time if it is not found. libcurl is only needed when -DOPTION_TARGET_MESSAGING=ON (off by default).

All former VCell monorepo dependencies (FronTier, ExpressionParser, vcommons) are bundled in this repo and built automatically — no external paths required.

Building

Ubuntu / Debian

# System dependencies
sudo apt-get install cmake libhdf5-dev libboost-dev python3-dev python3-pip pybind11-dev
pip3 install pybind11
# libcurl4-openssl-dev is only needed if you build with -DOPTION_TARGET_MESSAGING=ON

# Configure (substitute your actual library paths)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# Build everything
cmake --build build --parallel

Output files land in build/bin/:

build/bin/
  MovingBoundarySolver              # binary
  libMovingBoundaryLib.a            # static library
  pyvcell_mbsolver/                 # Python package
    __init__.py                     #   high-level wrapper
    _core.cpython-*.so              #   compiled pybind11 extension

macOS

# Dependencies via Homebrew
brew install cmake hdf5 boost python pybind11
# add `curl` too if you build with -DOPTION_TARGET_MESSAGING=ON

# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# Build everything
cmake --build build --parallel

For Apple Silicon the build system detects the architecture automatically and sets -DCMAKE_OSX_ARCHITECTURES=arm64. On Intel Macs it sets x86_64.

Windows (Visual Studio + vcpkg)

Native Windows builds use MSVC (Visual Studio 2022 / Build Tools) with the C++ dependencies supplied by vcpkg. All source, tests, and the Python extension build and pass on Windows.

Install prerequisites:

• Visual Studio 2022 or the Build Tools, with the Desktop development with C++ workload (x64 toolset)
• CMake
• Python 3 (check "Add to PATH")
• A bootstrapped vcpkg checkout (e.g. C:\vcpkg)
• Strawberry Perl — some vcpkg ports (curl/openssl) need it to build: choco install strawberryperl

The C++ dependencies (HDF5, Boost, curl, pybind11) are declared in vcpkg.json and installed via vcpkg's manifest mode.

Easiest: the helper script

build-windows.ps1 (repo root) reproduces the CI build end to end — it installs the vcpkg dependencies, configures with the Visual Studio generator, and builds Release:

.\build-windows.ps1              # full build
.\build-windows.ps1 -Test        # build, then run ctest
.\build-windows.ps1 -SkipVcpkg   # skip the (slow) dependency install on reruns

Manual

# 1. Install the manifest dependencies into .\vcpkg_installed
C:\vcpkg\vcpkg.exe install --triplet x64-windows

# 2. Configure. -G is required because a default of Ninja rejects -A x64;
#    the vcpkg toolchain makes CMake find the installed packages.
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
  -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake

# 3. Build
cmake --build build --config Release --parallel

Output files land in build\bin\Release\ (binary + .lib), and the Python package under build\bin\pyvcell_mbsolver\.

Build options

Example — debug build, shared library, no tests:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DBUILD_SHARED_LIBS=ON \
  -DBUILD_TESTING=OFF \
cmake --build build --parallel

Running the tests

Tests are built by default (BUILD_TESTING=ON). After a successful build:

cd build
ctest --output-on-failure

Test suites

All three suites run automatically when you invoke ctest. The Python tests require pytest (pip install pytest).

Python test prerequisites

No manual setup required. CMake creates an isolated virtual environment in build/python_venv/ at configure time and installs pytest into it automatically. The venv is recreated on every cmake -S . -B build run.

The Python tests import pyvcell_mbsolver._core (the compiled extension) and pyvcell_mbsolver (the high-level wrapper in python/). ctest sets PYTHONPATH so the package is importable from the build tree without installation.

Useful ctest options

# Run in parallel
ctest --output-on-failure -j$(nproc)

# Run only tests whose name matches a pattern
ctest --output-on-failure -R "algo"
ctest --output-on-failure -R "ExpressionParser"
ctest --output-on-failure -R "PyVcellMbSolver"

# List all registered tests without running them
ctest -N

# Show full output even for passing tests
ctest -V

Running the Python tests directly

After configuring, the venv already has pytest installed. Run the suite directly using the venv's Python:

PYTHONPATH=build/bin:python build/python_venv/bin/python -m pytest python/tests -v

On Windows, substitute build\python_venv\Scripts\python.exe.

Skipping tests

Pass -DBUILD_TESTING=OFF at configure time to skip building and registering the test executables entirely (this also disables the Python tests):

cmake -S . -B build -DBUILD_TESTING=OFF

Releases for VCell (SOLVER-RELEASE)

VCell consumes this repository through its GitHub releases and container images, under the contract every VCell solver repository meets (VCell docs/plan-solver-repos.md §1). .github/workflows/build-and-release.yml implements it; a vX.Y.Z tag on main (matching the project() version in CMakeLists.txt, which the workflow checks) publishes everything below. Pull requests build and test all of it.

Release assets — each archive holds, at its root, the executable under the name VCell resolves (MovingBoundary_x64, .exe on Windows), LICENSE and a VERSION file; no static libraries or test binaries.

Messaging (-tid <n> plus the <jms> block VCell writes for HPC runs, reported to the broker's REST API) is compiled into the Linux and macOS builds; the Windows build leaves it out, since the desktop client never passes -tid.

Container image ghcr.io/virtualcell/vcell-mbsolver:<X.Y.Z> (and :latest), linux/amd64 + linux/arm64: debian:bookworm-slim plus the Linux archive's contents in /opt/vcell/bin (on PATH) — docker/Dockerfile compiles nothing. SIF oras://ghcr.io/virtualcell/vcell-mbsolver_singularity:<X.Y.Z> (amd64), built from that image and pushed with ORAS.

Entry point /usr/local/bin/vcell-solver-entrypoint (docker/entrypoint.sh): no argument or --help prints the version and the executables and exits 0; a first argument naming a provided executable is execed (exit codes and SIGTERM pass through); anything else prints usage and exits 2. It writes nothing, runs as any uid and works from a read-only SIF, with argv as VCell's SlurmProxy writes it:

singularity run --containall --bind /share/apps/vcell3/users:/simdata <sif> \
    MovingBoundary_x64 --config /simdata/<user>/SimID_<key>_0_mb.xml -tid 0

Smoke test and reference. smoke/ holds a VCell-generated input (SimID_254696951_0_mb.xml: the MBswept model — a circular cell translating with velocity (sin t, cos t), two diffusing species, 31×31 nodes, t ∈ [0, 1]) and reference.h5, its output from the legacy MovingBoundary_x64 (vcell-solvers v0.0.44-dev4, macOS x86_64), which is bit-identical to the ghcr.io/virtualcell/vcell-solvers:v0.8.2 image's. CI runs it through every archive, the image (as a non-root uid with a read-only root) and the SIF (under apptainer run --containall), each with -tid 0, compares every species at every output time with smoke/compare.py, and checks that a run with a <jms> block reports its worker events to a stand-in broker (smoke/fake_broker.py).

To run it by hand:

python smoke/prepare.py /tmp/mb --output-dir /tmp/mb
MovingBoundary_x64 --config /tmp/mb/SimID_254696951_0_mb.xml
python smoke/compare.py smoke/reference.h5 /tmp/mb/SimID_254696951_0_.h5

Cutting a release. Bump project(VCellMovingBoundary VERSION X.Y.Z) in CMakeLists.txt (the Python wheel version follows it), merge to main, then tag vX.Y.Z on main. The tag also triggers wheels.yml, which publishes pyvcell_mbsolver X.Y.Z to PyPI.

Using the binary

./build/bin/MovingBoundarySolver --config <input_mb.xml> [-tid <n>]

The input file format is described in metadata/MovingBoundarySolverInputFile.docx and validated by Solver/MovingBoundarySetup.xsd.

Linking the library

Add to your project's CMakeLists.txt:

find_library(MB_LIB MovingBoundaryLib HINTS /path/to/vcell-mbsolver/build/bin)
find_path(MB_INCLUDE MovingBoundaryParabolicProblem.h
    HINTS /path/to/vcell-mbsolver/Solver/include)

target_link_libraries(my_target PRIVATE ${MB_LIB})
target_include_directories(my_target PRIVATE ${MB_INCLUDE})

Or install the project first and use the installed headers under <prefix>/include/vcell-mbsolver/.

Using the Python module

The bindings are shipped as the pyvcell_mbsolver package: the compiled extension is the private submodule pyvcell_mbsolver._core, and the high-level wrapper (MovingBoundarySolver, observer base classes) is the package itself.

import sys
sys.path.insert(0, "/path/to/vcell-mbsolver/build/bin")

import pyvcell_mbsolver
from pyvcell_mbsolver import MovingBoundarySolver   # high-level wrapper
from pyvcell_mbsolver import _core                  # low-level C++ API
# See python/pyvcellmbsolver.cpp for the exposed _core API

After cmake --install build --prefix /usr/local, the package is installed to the active Python's site-packages and importable directly:

import pyvcell_mbsolver

Python package & wheels

The repository also ships a PEP 517 build configuration (pyproject.toml, using the scikit-build-core backend) that drives the same CMake build to produce an installable Python wheel. The wheel contains only the pyvcell_mbsolver package (the _core extension and its pure-Python wrapper) — not the C++ library, CLI binary, or headers.

Install from a downloaded wheel

CI builds redistributable wheels for Linux (x86_64 + arm64) and macOS (x86_64 + arm64, macOS 15+) and uploads them as workflow artifacts (see the Wheels GitHub Actions workflow). Download the wheel for your platform/Python version and:

pip install pyvcell_mbsolver-<version>-<tags>.whl
python -c "import pyvcell_mbsolver; from pyvcell_mbsolver import _core; print('ok')"

The wheels are self-contained: the shared HDF5 libraries are vendored in by the wheel-repair step (auditwheel / delocate), so no system HDF5 install is required to use a wheel.

Native Windows source builds are supported via the Visual Studio/vcpkg flow above, but redistributable Windows wheels are not published yet. Use the source-build steps from the Windows section when building on MSVC.

Build a wheel locally

Building from source still needs the native toolchain and dependencies from the Prerequisites section (CMake, a C++14 compiler, HDF5, Boost):

pip install build
python -m build --wheel          # writes dist/pyvcell_mbsolver-*.whl
pip install dist/pyvcell_mbsolver-*.whl

pip install . works too. Wheel builds set BUILD_TESTING=OFF and OPTION_TARGET_MESSAGING=OFF automatically (see [tool.scikit-build] in pyproject.toml).

Publishing to PyPI

The Wheels workflow has a publish job that uploads the built wheels and sdist to PyPI via trusted publishing (OIDC — no stored API token). It runs only on v* tag pushes and stays dormant until a one-time setup is done on PyPI:

1. Register the project on PyPI (claim the pyvcell_mbsolver name).
2. Under the project's Publishing settings, add a trusted publisher:
   • Owner: virtualcell, Repository: vcell-mbsolver
   • Workflow: wheels.yml, Environment: pypi
3. Create the pypi environment in the repo settings (optionally with reviewers/branch protection).

Once configured, pushing a vX.Y.Z tag builds all wheels and publishes them. Until then, normal pushes and PRs simply produce downloadable wheel artifacts.

Dry run on TestPyPI first (recommended)

The workflow also has a publish-testpypi job to rehearse the release against TestPyPI before touching real PyPI. It runs only when the workflow is manually dispatched with the testpypi flag, and needs its own one-time setup mirroring the above:

1. Create a TestPyPI account (separate from PyPI; 2FA required).
2. At https://test.pypi.org/manage/account/publishing/, add a pending publisher:
   • PyPI Project Name: pyvcell_mbsolver
   • Owner: virtualcell, Repository: vcell-mbsolver
   • Workflow: wheels.yml, Environment: testpypi
3. Create a testpypi environment in the repo settings.

Then trigger the dry run (no tag needed):

gh workflow run wheels.yml -f testpypi=true

(or Actions → Wheels → Run workflow, check the box). It builds all wheels + sdist and uploads them to TestPyPI; skip-existing keeps repeat runs of the same version from failing. Verify at https://test.pypi.org/project/pyvcell-mbsolver/, then do the real release by tagging vX.Y.Z.