Skip to content

Installation

Prerequisites

  • Conda (Miniconda or Anaconda)
  • vcpkg installed
  • C++20 compiler:
    • MSVC 2022 (Windows)
    • GCC 11+ (Linux)
    • Clang 14+ (Linux/macOS)
  • (Optional) NVIDIA CUDA 12.4+ or the CoreX CUDA compatibility toolchain for IPC support
  • (Optional) CUDA toolkit for VBD CUDA backend
  • (Optional) CUDA toolkit for SPH CUDA backend

Standard Install

# Create conda environment
conda env create -f environment.yml
conda activate novaphy

# Set vcpkg toolchain
export CMAKE_TOOLCHAIN_FILE="/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"

# Install NovaPhy
pip install -e .

# Create conda environment
conda env create -f environment.yml
conda activate novaphy

# Set vcpkg toolchain
$env:CMAKE_TOOLCHAIN_FILE="C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake"

# Install NovaPhy
pip install -e .

conda activate novaphy
CMAKE_ARGS="--preset=default" pip install -e .

Editable vs. Non-editable (Site-Packages) Install

NovaPhy supports two installation modes, each serving a different purpose:

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 In the build directory Bundled inside the package
Source tree required? Yes — deleting it breaks imports No — fully self-contained
Demo scripts Always available from source Included unless NOVAPHY_EXCLUDE_DEMOS=true
PYTHONPATH / .pth files? No — scikit-build-core handles redirects No — standard install
Use case Development, debugging, rapid iteration Deployment, CI, distribution

Development workflow (editable):

pip install -e .          # install once; edit Python files in-place

After editing Python files under python/novaphy/ or python/demos/, changes take effect immediately without re-installation. C++ changes still require a rebuild (pip install -e . again, or run cmake --build directly in the build directory).

Release / distribution (non-editable / wheel):

pip install .             # site-packages install
# or
python -m build           # build a wheel
pip install dist/novaphy-*.whl

The installed package lives entirely in site-packages and no longer depends on the source tree. To verify from any directory:

python -c "import novaphy; print(novaphy.version())"

You can run this verification at any time with:

python scripts/verify_install.py

Switching between modes

To switch from editable to non-editable (or vice versa), run pip uninstall novaphy -y first, then install in the new mode.

With IPC Support

IPC builds the libuipc submodule under external/libuipc. Select the GPU path with NOVAPHY_GPU_PLATFORM=NVIDIA or NOVAPHY_GPU_PLATFORM=COREX.

# NVIDIA CUDA path
CMAKE_ARGS="-DNOVAPHY_WITH_IPC=ON -DNOVAPHY_GPU_PLATFORM=NVIDIA" pip install -e .

# NVIDIA RTX 50-series / compute_120 path
CMAKE_ARGS="-DNOVAPHY_WITH_IPC=ON -DNOVAPHY_GPU_PLATFORM=NVIDIA -DCMAKE_CUDA_COMPILER=/usr/local/cuda-12.8/bin/nvcc" pip install -e .

# CoreX compatibility path
CMAKE_ARGS="-DNOVAPHY_WITH_IPC=ON -DNOVAPHY_GPU_PLATFORM=COREX" pip install -e .

With VBD CUDA Backend

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

With SPH CUDA Backend

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

Excluding Demo Scripts

Demo scripts under novaphy.demos are included in the wheel by default. To produce a slimmer wheel without them, set NOVAPHY_EXCLUDE_DEMOS=true at build time:

NOVAPHY_EXCLUDE_DEMOS=true pip install .

After install, the demos are available as novaphy.demos and can be run with:

python -m novaphy.demos.demo_basic_urdf
python -m novaphy.demos.demo_newton_xpbd_pyramid --headless 100

Editable installs

pip install -e . (editable mode) always exposes the source-tree contents, so demos are accessible regardless of NOVAPHY_EXCLUDE_DEMOS. The flag only affects non-editable wheel installs and sdist builds.

Verify Installation

import novaphy
print(novaphy.version())   # 0.4.0
print(novaphy.has_ipc())   # True if built with IPC
print(novaphy.has_sph_cuda())   # True if built with SPH CUDA backend

Dependencies

Component Source
Eigen3 vcpkg
Google Test vcpkg
pybind11 pip (NOT vcpkg)
scikit-build-core pip
NumPy pip / conda
Polyscope pip (optional, for visualization)

pybind11 via pip, not vcpkg

Always install pybind11 via pip. The vcpkg version conflicts with conda's Python installation.

Next Steps