SimVascularWIP

Requirements

• CMake 3.26+
• A C/C++17 compiler
• Git
• Python 3.12 (with development headers)
• Qt6 6.10+ (Core, CoreTools, Gui, Widgets, Xml) — not built by the superbuild, must be pre-installed unless SV_BUILD_QT=OFF (see below)

Everything else (VTK, GDCM, HDF5, ITK, OpenCASCADE, MMG, TetGen, tinyxml2, VMTK) is fetched and built from source by the CMake superbuild. See Dependencies.md for version pins and per-dependency notes.

Qt-free, Python-only builds

Qt6 is only needed by the desktop GUI and the Qt-integrated VTK/ITK/VMTK modules it uses — neither of which the current build actually produces (see Dependencies.md). If all you need is the sv Python module (SV_WRAP_PYTHON, the default), pass -DSV_BUILD_QT=OFF and drop -DQt6_DIR=... entirely; no Qt6 install is required at all in that case.

Building

The superbuild is enabled by default (SimVascular_SUPERBUILD=ON) and drives the whole process — configuring and building it builds every dependency followed by SimVascular itself.

cmake -S . -B ../simwip -DQt6_DIR=/path/to/Qt6/lib/cmake/Qt6

cmake --build ../simwip --parallel

Qt6_DIR points at the lib/cmake/Qt6 directory of your Qt6 install; its exact location depends on how Qt was installed, e.g. C:\Qt\6.10.0\msvc2019_64\lib\cmake\Qt6 on Windows, /path/to/Qt/6.10.0/gcc_64/lib/cmake/Qt6 on Linux, or /path/to/Qt/6.10.0/macos/lib/cmake/Qt6 on macOS.

cmake --build ... --parallel dispatches to whatever build tool the generator selected (Make, Ninja, MSBuild, Xcode, ...) and picks a sensible parallelism level automatically; pass --parallel N to pin it to N jobs.

Useful CMake options (pass as -D<OPTION>=<VALUE>):

Option	Default	Purpose
SimVascular_SUPERBUILD	ON	Build dependencies via superbuild. Set OFF only if all deps are already installed and their *_DIR variables are supplied.
SV_WRAP_PYTHON	ON	Build the sv Python extension module.
SV_BUILD_QT	ON	Require Qt6 and build the Qt-integrated VTK/ITK/VMTK modules it enables. Set OFF for a Qt-free, Python-only build (see above).
BUILD_SHARED_LIBS	ON	Build shared vs. static libraries.
CMAKE_BUILD_TYPE	Release	Standard CMake build type.

The superbuild produces one install tree per dependency (e.g. VTK-install/, OpenCASCADE-install/) alongside a SuperBuild/SimVascular-build/ directory containing the actual SimVascular build (libraries under lib/, the Python package under lib/python3.12/site-packages/sv/).

If you only need to iterate on SimVascular itself after the dependencies are already built, reconfigure/rebuild directly in SuperBuild/SimVascular-build/ instead of re-running the top-level build — it's a normal (non-superbuild) CMake project pointed at the dependency install trees via cached *_DIR variables.

Testing

Python API smoke test

Verifies that the sv Python extension module built above is importable and exposes its expected submodules (geometry, imaging, meshing, modeling, pathplanning, segmentation, simulation, vmtk, ...).

Testing/PythonAPI/test_python_api.sh

By default it assumes the superbuild install trees live in ../simwip relative to this repo checkout and the build lives in ../simwip/SuperBuild/SimVascular-build. Override either with positional arguments if your layout differs:

Testing/PythonAPI/test_python_api.sh <SIMWIP_ROOT> [BUILD_DIR]

Linting

The Lint GitHub Actions workflow (.github/workflows/lint.yml) checks pull requests with clang-format (C++, via .clang-format) and ruff (Python, via ruff.toml). Both only look at lines/files a PR actually changes — most of Source/sv1 and Source/sv4gui predates this fork and doesn't conform, so the whole tree isn't linted, only new/changed code.

To check or fix formatting locally before pushing:

# C++ — only the lines changed since a given base ref/commit
git-clang-format <base-ref>

# Python
ruff check <changed files>
ruff format <changed files>