svVascularize

Quick-start

If you are running Python 3.9-3.12 on x86-64 or Apple Silicon:

python -m pip install --upgrade pip  # upgrade installer
python -m pip install svv

This installs the core pre-built synthetic vascular-generation wheel from PyPI.

System requirements

• Python: 3.9 ≤ 3.12 (CPython). Other interpreters are untested.
• Disk: ≈ 300 MB for wheels & caches, plus project data.
• Memory: 2 GB RAM minimum (8 GB recommended for large vascular trees).
• C++17 tool-chain: required only for source builds (see call-out below).
• Build-time Python deps: cython ≥0.29 <3.0, wheel, numpy ≥1.24 <2 on Python 3.9–3.12 or numpy ≥2.1 on Python 3.13 (pulled in automatically by pip).

Choosing an installation method

Installing with pip

The PyPI wheels are pre-built for every major OS and Python 3.9 – 3.12, so installs are fast and compiler-free. This route is ideal for:

• quick experiments or tutorials,
• lightweight CI jobs,
• users who already manage Python via pyenv, Homebrew, or the Windows Store.

Create a virtual environment first (recommended):

# Linux/macOS
python3 -m venv ~/.venvs/svv
source ~/.venvs/svv/bin/activate
pip install svv

# Windows (PowerShell)
py -m venv %USERPROFILE%\venvs\svv
%USERPROFILE%\venvs\svv\Scripts\Activate.ps1
pip install svv

Choose pure‑Python or accelerated

svVascularize runs entirely in pure Python, but ships optional C/Cython accelerators for heavier routines. You can select either experience at install time:

• Pure‑Python (default):

  pip install svv

  No compiler required. All performance‑critical paths have Python fallbacks.
• Accelerated (prebuilt extensions):

  pip install "svv[accel]"

  The [accel] extra pulls in a small companion wheel, svv-accelerated, which contains compiled accelerators. When present, svv automatically prefers those modules.

SVV_BUILD_EXTENSIONS=1 pip install --no-binary svv "svv[accel]"

Verify which backend is active

import importlib
m = importlib.import_module('svv.tree.utils.c_local_optimize')
print(getattr(m, '__file__', '<builtin>'))

If you see a .so/.pyd path, the accelerated backend is active. A .py path indicates the pure‑Python fallback.

Installing with conda

conda can install not only Python packages but also the C/C++ and Fortran libraries many scientific tools depend on. It excels when you need:

• a single cross-platform workflow (Windows, macOS, Linux),
• MPI, OpenBLAS, or GPU builds of downstream solvers,
• inter-package version pinning handled for you.

Until the official conda-forge feedstock is merged, you can still use a conda environment and install from PyPI inside it:

conda create -n svv python=3.11 pip
conda activate svv
pip install svv

Once the feedstock lands you'll be able to swap the final line for:

conda install -c conda-forge svv

Building from source

For advanced users and developers who want to customize svv or contribute to svv.

git clone https://github.com/SimVascular/svVascularize.git
cd svVascularize
python -m pip install -e .[dev]

To locally build and stage platform-specific MMG, TetGen, and 0D solver binaries into the package tree, run:

python setup.py build_ext --inplace --build-native-binaries

You can also build one tool at a time with --build-mmg, --build-tetgen-cli, or --build-solver-0d.

TetGen for constrained tissue meshing

Release wheels bundle the standalone tetgen/tetgen.exe used by Simulate → Build Constrained Tissue Mesh. The Python tetgen bindings used for ordinary meshing do not supply this executable. Older wheels may omit it. Check the active installation with:

import svv
from svv.utils.meshing.tetgen import get_packaged_tetgen_cli_path
print(svv.__version__, svv.__file__)
print(get_packaged_tetgen_cli_path())

For a source installation, install CMake and a C++ compiler, then run these commands from the source directory to build and install the executable:

python setup.py build_ext --build-tetgen-cli --parallel 2
python -m pip install .

To use an existing executable, set SVV_TETGEN_PATH to its full path before launching the GUI. A tetgen executable on PATH is also supported.

Simulation extras

The svVascularize Python API is solver-agnostic. The Simulation container prepares meshes and svFSI XML files, while helper functions in svv.simulation.fluid.rom emit 0-D circuits. To actually march solutions forward you can link to the SimVascular solvers below:

svZeroDSolver

svv wheels now bundle a platform-specific svZeroDSolver executable. The binary is selected automatically from svv/utils/solvers/0D/<OS>/<arch>.

You can override discovery with: SVV_SOLVER_0D_PATH (full executable path), SVV_SOLVER_0D_DIR (directory containing the executable), and SVV_SOLVER_0D_ARCH (arch override such as x86_64 or universal2).

svOneDSolver

This solver relies on PETSc and MPI. The easiest route is to download the pre-built binaries from SimTK. These binaries are compatible with Ubuntu 18/20, macOS Catalina, and Windows 10.

svMultiPhysics

Full 3D CFD/FSI binaries are published on SimTK. Download the latest installer for macOS/Linux platforms:

• Linux installers
• macOS DMG

Verifying the installation

After installing svVascularize, verify the version and public component imports by running the following script in the Python interpreter.

import svv
from svv import Domain, Forest, Simulation, Tree

print(svv.__version__)
print([name for name in ("Domain", "Forest", "Simulation", "Tree") if name in dir(svv)])

To test that individual components of the package are correctly installed and operational run the test suite associated with the module from the terminal or shell.

python -m svv.tests

Troubleshooting & FAQ

DLL load failed? Check bitness and Python version.