Building from Source¶

Prerequisites¶

• CMake 3.20+
• C++ compiler with C++20 support:
  • Linux: GCC 10+ or Clang 12+
  • macOS: Xcode Command Line Tools (Clang 14+) or brew install llvm
• Python 3.12+
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh

Python Package Build (Recommended)¶

Builds the clifft Python package with C++ extensions:

git clone https://github.com/unitaryfoundation/clifft.git
cd clifft

uv venv
uv pip install -e .

# Verify
uv run python -c "import clifft; print(clifft.version())"

# Run tests
uv run pytest tests/python/ -v

The editable install (-e .) means you can re-run uv pip install -e . after modifying C++ code to rebuild.

Platform and CPU support¶

CPU baseline policy¶

• Published wheels use explicit portable baselines chosen in CI.
• Local Python source builds and standalone C++ Release builds default to CLIFFT_CPU_BASELINE=native.
• Supported values are native, generic, x86-64-v2, and x86-64-v3.
• Linux wheels use a pinned Clang toolchain with ThinLTO. Linux x86_64 wheels use x86-64-v2 as the global baseline; higher-ISA symbolic sampling kernels are compiled separately and selected at runtime when the host supports them.

Override the default when needed:

CLIFFT_CPU_BASELINE=generic uv pip install -e .

OpenMP support¶

Optimized intra-shot sampling uses OpenMP when it is available. The CMake setting CLIFFT_OPENMP defaults to AUTO: source builds enable OpenMP when the toolchain provides it and otherwise retain the serial and cross-shot paths. Use -DCLIFFT_OPENMP=OFF to test or require a build without the runtime, or -DCLIFFT_OPENMP=ON to make configuration fail when OpenMP is unavailable.

Linux GCC installations normally include OpenMP. Apple Clang needs a separate runtime; install it with brew install libomp. Clifft checks that Homebrew prefix automatically, or it can be supplied explicitly:

SKBUILD_CMAKE_ARGS="-DCLIFFT_OPENMP=ON -DOpenMP_ROOT=$(brew --prefix libomp)" \
  uv pip install -e .

Runtime kernel dispatch¶

On supported x86 GNU/Clang builds, the scalar, AVX2, and AVX-512 executor backends are compiled in separate translation units. The vector translation units use explicit ISA flags, while the rest of the library retains the configured CPU baseline. Executable preparation detects the host once and uses one backend consistently for the resulting program.

Apple arm64 builds additionally select a NEON backend. Apple Silicon guarantees the 128-bit Advanced SIMD baseline, so this backend needs no generation-specific feature probe. It specializes eligible rank-two fused rotations, direct Pauli rotations, and diagonal active-measurement probability and collapse. Shape- and width-specific thresholds retain the portable scalar kernels where measured NEON crossover behavior does not justify vector dispatch.

The AVX2 backend requires AVX2, BMI2, and FMA. The AVX-512 backend additionally requires AVX-512F and AVX-512DQ. If those features are unavailable, or runtime dispatch is not compiled for the platform, Clifft uses its portable scalar implementation.

CLIFFT_FORCE_ISA=scalar, neon, avx2, or avx512 can force an available backend in a runtime-dispatch build. This is a diagnostic and testing control, not a portable deployment setting; requesting features that the host lacks is an error. clifft.runtime_isa() reports which backend the process resolved, which is useful for verifying dispatch in tests and emulated environments.

Standalone C++ Build¶

For pure C++ development without Python:

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build --output-on-failure

Build Types¶

For optimized source builds, Release and RelWithDebInfo default to native CPU tuning on the build machine. On x86 GNU/Clang builds, that keeps the AVX2 and AVX-512 symbolic sampling specializations available for runtime dispatch.

The standalone build enables CLIFFT_BUILD_TESTS by default. To build only the native C++ library:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DCLIFFT_BUILD_TESTS=OFF
cmake --build build -j

If a full test build causes memory pressure, reduce parallelism with cmake --build build -j1.

Circuit size¶

Clifft sizes Pauli masks and coordinate-planning storage from the input circuit at runtime. clifft.trace(), and therefore the usual clifft.compile() path, rejects circuits above 65,536 physical qubits as a conservative safety check. Below that ceiling, practical limits depend on compilation memory, active width, and output volume rather than a fixed-width Pauli representation.

WebAssembly Build¶

For the browser-based Playground:

# Requires Docker
just build-wasm
just test-wasm

Outputs playground/public/clifft_wasm.{js,wasm}. See the Playground page.

The documentation link points to the deployed Playground for the selected docs version. To preview Playground changes locally, run npm run dev in the playground/ directory and open the Vite development server directly.

IDE Setup¶

CMake exports compile_commands.json for IDE integration:

ln -sf build/compile_commands.json .

This enables clangd, VS Code C++ extension, and CLion to provide accurate diagnostics.

just Shortcuts¶

The repository includes a justfile for common tasks:

just --list    # Show all recipes
just py        # Full Python workflow (venv + install + test)
just build     # Build C++ targets
just test      # Run C++ tests
just lint      # Run pre-commit checks

just is optional — all underlying commands are documented above.

Dependency Groups¶

Development dependencies are managed via PEP 735 dependency groups in pyproject.toml. The uv package manager uses these automatically.

• dev (default) — Installed by uv sync. Includes everything needed for building, testing, and linting.
• docs — Installed with uv sync --group docs. Includes the MkDocs toolchain for building the documentation site.

The only runtime dependency is numpy. All other packages are development-only.