Skip to content

Installation

NovaPhy is currently version 0.4.0. The default build is CPU-only; CUDA, DLAN, and IPC support are opt-in build variants rather than runtime downloads.

Source access

NovaPhy does not currently publish a package on PyPI, and the source repository is access-controlled. Obtain an authorized checkout from a maintainer first; all commands below run from that repository root. See Contributing for the checkout workflow.

Prerequisites

  • Python 3.11 is the development configuration in environment.yml (pyproject.toml accepts Python 3.9+).
  • Conda is recommended for the development environment.
  • vcpkg supplies Eigen3, tinyxml2, GoogleTest, and the optional IPC dependency set.
  • A C++20 compiler: MSVC 2022, GCC 11+, or Clang 14+ is a practical baseline.
  • CMake 3.15+ for an explicit CPU build, 3.21+ for the repository's version-3 presets, and 3.24+ for the default NVIDIA CUDA architecture value native. IPC's bundled libuipc raises the requirement to CMake 3.25+.
  • Optional GPU variants require their matching compiler and runtime:
    • NVIDIA CUDA for the NVIDIA backends; IPC enforces CUDA 12.4+.
    • A CoreX CUDA compatibility toolchain for the CoreX path.
    • The Denglin compiler wrapper and libcurt.so for VBD DLAN.

pybind11 comes from pip

Install pybind11 in the active Python environment. Do not install the vcpkg pybind11 port for this build: it can resolve a different Python than the active Conda environment.

Standard CPU Install

conda env create -f environment.yml
conda activate novaphy

export CMAKE_TOOLCHAIN_FILE="/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
python -m pip install -e .

conda env create -f environment.yml
conda activate novaphy

$env:CMAKE_TOOLCHAIN_FILE="C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake"
python -m pip install -e .

The editable build compiles the CPU implementations of SolverSemiImplicit, SolverXPBD, SolverFeatherstone, SolverMuJoCo, SolverVBD, and SolverPBF. SolverSPH is present, but its current runnable backend is CUDA-only; a CPU backend is not implemented. Verify CUDA support with has_sph_cuda() before constructing it. SolverLBM and its configuration are also present in the standard build, but fluid operations require the optional LBM CUDA backend; construct it and inspect solver.has_cuda_backend.

Viewer and Example Extras

The core install includes ViewerNull, which is suitable for headless loops. Install the viewer extra for the optional OpenGL, Rerun, USD, and Viser backends:

python -m pip install -e ".[viewer]"

The extras declared by the current pyproject.toml are:

Extra Installs
viewer ModernGL/GLFW, ImGui, Rerun, USD, Viser, trimesh, pycollada, and Pillow dependencies used by novaphy.viewer backends
viz Polyscope for demos that still use the lightweight novaphy.viz layer
examples viewer and viz plus PyYAML, USD, and trimesh dependencies used by examples
test pytest, trimesh, and pycollada (used by mesh/import regression tests, including Collada/DAE visuals)
policy examples plus PyTorch
dev viewer, viz, and test

Install the complete example dependency set with:

python -m pip install -e ".[examples]"

Optional viewer packages are imported when their backend is used. Installing the extra makes the dependencies available; it does not guarantee that an interactive window or GPU context can be created on a headless host.

CUDA and Accelerator Variants

Pass CMake cache entries through CMAKE_ARGS. Use a separate build directory or reinstall after changing flags so that Python does not keep loading an older editable extension.

Core DeviceArray and collision CUDA

NOVAPHY_WITH_CUDA compiles the core CUDA DeviceArray lifecycle. The CUDA collision pipeline is enabled by default with it and can be disabled independently:

# Core CUDA + CUDA collision pipeline
CMAKE_ARGS="-DNOVAPHY_WITH_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

# Core CUDA without CUDA collision kernels
CMAKE_ARGS="-DNOVAPHY_WITH_CUDA=ON -DNOVAPHY_WITH_COLLISION_CUDA=OFF -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

There is currently no top-level has_cuda() or has_collision_cuda() Python check. A requested core CUDA build can fall back to the throwing stub if no CUDA compiler is found, so inspect the CMake configure summary and exercise the intended CUDA model/state path.

SolverVBD CUDA

CMAKE_ARGS="-DNOVAPHY_WITH_VBD_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

NOVAPHY_WITH_VBD_CUDA=ON forces NOVAPHY_WITH_CUDA=ON. It is mutually exclusive with NOVAPHY_WITH_VBD_DLAN=ON. Because core CUDA is forced on, the CUDA collision pipeline also builds by default; add -DNOVAPHY_WITH_COLLISION_CUDA=OFF if it is not wanted.

SolverSPH CUDA

CMAKE_ARGS="-DNOVAPHY_WITH_SPH_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

The SPH module and Python API are always compiled, but CUDA is the only current runnable SolverSPH backend; a CPU backend is not implemented. NOVAPHY_WITH_SPH_CUDA does not force the core NOVAPHY_WITH_CUDA option; add both flags only if the same build also needs CUDA Model/SimState buffers or the CUDA collision pipeline.

SolverLBM CUDA

CMAKE_ARGS="-DNOVAPHY_WITH_LBM_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

The sparse-block LBM module, Python class, and configuration are always compiled, but CUDA is the only current numerical backend. NOVAPHY_WITH_LBM_CUDA does not force the core NOVAPHY_WITH_CUDA option; enable both only when the same build also needs CUDA Model/SimState buffers or the CUDA collision pipeline. There is no top-level has_lbm_cuda() function; after constructing SolverLBM(model), inspect its has_cuda_backend property.

SolverMuJoCo CUDA

CMAKE_ARGS="-DNOVAPHY_WITH_CUDA=ON -DNOVAPHY_WITH_MUJOCO_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

Both flags are required. NOVAPHY_WITH_MUJOCO_CUDA does not force core CUDA on its own; an incomplete request leaves the MuJoCo CUDA stub in the build and has_mujoco_cuda() remains false.

SolverFeatherstone CUDA

CMAKE_ARGS="-DNOVAPHY_WITH_CUDA=ON -DNOVAPHY_WITH_FEATHERSTONE_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

Featherstone CUDA requires core CUDA. Configuration fails if the Featherstone flag is enabled without NOVAPHY_WITH_CUDA=ON or without a CUDA compiler.

SolverVBD DLAN

NOVAPHY_WITH_VBD_DLAN=ON forces core CUDA on, selects NOVAPHY_GPU_PLATFORM=COREX, and is mutually exclusive with the NVIDIA NOVAPHY_WITH_VBD_CUDA mode. It also requires a Denglin CUDA-compatible compiler wrapper and a discoverable libcurt.so:

export DLAN_SDK_ROOT=/path/to/dlgpu/sdk
CMAKE_ARGS="-DNOVAPHY_WITH_VBD_DLAN=ON -DCMAKE_CUDA_COMPILER=/path/to/clang_wrapper -DDLAN_SDK_ROOT=$DLAN_SDK_ROOT" \
  python -m pip install -e . --no-build-isolation

The CUDA collision backend defaults to off in this configuration. See the Denglin DLAN guide for the dedicated-machine setup and verification procedure.

IPC

IPC builds the libuipc submodule under external/libuipc. Initialize it before configuring:

git submodule update --init --recursive external/libuipc

Select NVIDIA or COREX explicitly when a machine has more than one GPU toolchain:

# NVIDIA CUDA path (CUDA 12.4+)
CMAKE_ARGS="-DNOVAPHY_WITH_IPC=ON -DNOVAPHY_GPU_PLATFORM=NVIDIA -DCMAKE_CUDA_COMPILER=/path/to/nvcc" \
  python -m pip install -e .

# CoreX compatibility path
CMAKE_ARGS="-DNOVAPHY_WITH_IPC=ON -DNOVAPHY_GPU_PLATFORM=COREX -DCMAKE_CUDA_COMPILER=/path/to/corex-wrapper" \
  python -m pip install -e .

IPC does not require NOVAPHY_WITH_CUDA=ON: libuipc owns its GPU backend. Enable core CUDA separately only when the same build needs CUDA DeviceArray, collision, MuJoCo, or Featherstone functionality.

GPU platform and architecture

NOVAPHY_GPU_PLATFORM accepts only NVIDIA or COREX. The architecture cache entry is NOVAPHY_CUDA_ARCHITECTURES; NovaPhy copies it into CMAKE_CUDA_ARCHITECTURES, so override the NovaPhy entry rather than only the generic CMake entry:

CMAKE_ARGS="-DNOVAPHY_WITH_CUDA=ON -DNOVAPHY_GPU_PLATFORM=NVIDIA -DNOVAPHY_CUDA_ARCHITECTURES=89" \
  python -m pip install -e .

Defaults are native for NVIDIA, ivcore11 for the general CoreX path, and 70 for VBD DLAN. Platform or architecture selection by itself does not enable a CUDA backend. The complete dependency table is in Build from Source.

Editable vs. Wheel Install

Feature Editable (pip install -e .) Non-editable (pip install . / wheel)
Python source location Imported directly from the working tree Copied into site-packages/
C++ extension location scikit-build-core build directory Bundled inside the package
Source tree required Yes No
Demo scripts Always exposed from the source tree Included unless NOVAPHY_EXCLUDE_DEMOS=true
Typical use Development and debugging Deployment, CI, and distribution

Python-only edits under python/novaphy/ or python/demos/ are visible immediately in an editable install. Rebuild after changing C++ bindings, native sources, or CMake flags:

python -m pip install -e .

Build and install a wheel with:

python -m pip install build
python -m build
python -m pip install dist/novaphy-*.whl

Switching install modes

Uninstall NovaPhy before switching between an editable install and a wheel so a stale _core extension cannot win Python's import resolution: python -m pip uninstall novaphy -y.

Excluding Demo Scripts

Demo scripts are included in wheels by default. Set NOVAPHY_EXCLUDE_DEMOS=true while building a non-editable package to omit them:

NOVAPHY_EXCLUDE_DEMOS=true python -m pip install .

Editable installs always expose the source-tree demos, regardless of this setting. With demos included, run them as modules, for example:

python -m novaphy.demos.demo_basic_urdf
python -m novaphy.demos.demo_pyramid_ball --solver xpbd --headless 100

Verify Installation and Compiled Features

import novaphy

assert novaphy.version() == "0.4.0"

features = {
    "IPC": novaphy.has_ipc(),
    "SPH CUDA": novaphy.has_sph_cuda(),
    "MuJoCo CUDA": novaphy.has_mujoco_cuda(),
    "Featherstone CUDA": novaphy.has_featherstone_cuda(),
    "VBD CUDA": novaphy.has_vbd_cuda(),
    "VBD DLAN": novaphy.has_vbd_dlan(),
}
for name, available in features.items():
    print(f"{name:18} {available}")

model = novaphy.ModelBuilder().finalize()
lbm = novaphy.solvers.SolverLBM(model)
print(f"{'LBM CUDA':18} {lbm.has_cuda_backend}")

The dictionary contains all current top-level compiled-feature checks; LBM uses the instance-level property shown below it. True confirms that the corresponding backend was compiled into the loaded extension; the matching driver, runtime libraries, and device must still be usable on the host. VBD DLAN compiles the shared CUDA-source implementation, so a DLAN build currently reports both has_vbd_cuda() and has_vbd_dlan() as true; use the latter to distinguish the DLAN variant.

For a general install-path check, run:

python scripts/verify_install.py

Native Dependencies

Component Source When needed
Eigen3 vcpkg All builds
tinyxml2 vcpkg All builds
GoogleTest vcpkg Native tests
pybind11 pip Python extension
scikit-build-core pip Python package build
NumPy pip / Conda Python runtime
libuipc dependency set vcpkg manifest feature + Git submodule IPC only

Next Steps