Installation Guide

Choose your platform-specific setup guide:

• Linux Installation
• Windows Installation
• macOS Installation

Shared Notes

• Use CMake presets from the repository root.
• Keep vcpkg outside the repository folder (for example, ../vcpkg).
• Preferred workflow: use pip install from source so Python packaging and C++ extension build happen in one step.

# Linux/macOS
CMAKE_ARGS="-D CMAKE_TOOLCHAIN_FILE=$(pwd)/../vcpkg/scripts/buildsystems/vcpkg.cmake" \
python3 -m pip install -e ".[dev,visualization]"

# Windows (PowerShell)
$env:CMAKE_ARGS='-D CMAKE_TOOLCHAIN_FILE="' + "$pwd\..\vcpkg\scripts\buildsystems\vcpkg.cmake" + '" -D CMAKE_C_COMPILER=cl -D CMAKE_CXX_COMPILER=cl'
python -m pip install -e ".[dev,visualization]"

• Install Python dev dependencies before running tests:

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

• To enable the sphinxsim preview visualizer, install the optional PyVista dependency:

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

See Visualization for details.

• Optional: enable CLI shell completion.

# bash
echo 'eval "$(sphinxsim --generate-completion bash)"' >> ~/.bashrc

# zsh
echo 'eval "$(sphinxsim --generate-completion zsh)"' >> ~/.zshrc

# fish
echo 'sphinxsim --generate-completion fish | source' >> ~/.config/fish/config.fish

• Troubleshooting shell completion:

# Reload startup config in the current terminal
source ~/.bashrc      # bash
source ~/.zshrc       # zsh
source ~/.config/fish/config.fish  # fish

# zsh completion must be initialized
autoload -Uz compinit
compinit
eval "$(sphinxsim --generate-completion zsh)"

# Quick sanity check that completion script is produced
sphinxsim --generate-completion bash | head

• Run full Python tests (including examples):

python -m pytest tests/ examples/ -v