Installation

Using pip

The recommended way to download and install chalc is from the PyPI repository using pip. Pre-packaged binary distributions are available for Windows and Linux with x86_64 CPUs, and MacOS with M-series CPUs.

# To chalc to your uv project
uv add chalc

# To install chalc into the current Python environment
pip install chalc

Build from source

If a pre-packaged binary distribution is not available for your platform, you can build chalc from source.

Dependencies

Chalc is a C++ extension module for Python and has several additional dependencies.

  1. Eigen C++ library (tested with version 3.4.0).

  2. GNU MP Library (tested with version 6.3.1) and the GNU MPFR Library (tested with version 4.2.0) for exact geometric computation.

  3. Computational Geometry Algorithms Library (CGAL) library (tested with version 6.0.1).

  4. Boost C++ libraries (transitive dependency through CGAL).

  5. Intel OneAPI Threading Building Blocks (TBB) (tested with version 2022.1.0).

The recommended way to obtain and manage these dependencies is using vcpkg (see the build dependencies section).

Build dependencies

  1. CMake (version 4.0.0 or later).

  2. On Windows: Visual Studio 2019 or later.

    On Linux: GCC11 or later. On MacOS: Clang 14 or later.

  3. On Linux and MacOS, the build tools automake, autoconf, autoconf-archive, and libtool. Install them with apt install autoconf autoconf-archive automake libtool, dnf install autoconf autoconf-archive automake libtool, pacman -S autoconf autoconf-archive automake libtool, or brew install autoconf autoconf-archive automake libtool.

  4. The Python project tool uv.

  5. (Recommended) Microsoft vcpkg C++ dependency manager.

  6. (Recommended) GNU Make.

Build steps

  1. Clone the git repository.

git clone https://github.com/abhinavnatarajan/chalc
cd chalc

  1. If you have vcpkg installed on your system, make sure that the environment variable VCPKG_ROOT is set and points to the base directory where vcpkg is installed.

export VCPKG_ROOT=/path/to/vcpkg/dir

$Env:VCPKG_ROOT = 'C:\path\to\vcpkg\dir'

If you do not have vcpkg installed, the build process will automatically download vcpkg into a temporary directory, and fetch and build the required dependencies.

Note

If you would like to disable the use of vcpkg altogether, set the environment variable NO_USE_VPKG. You will have to ensure that all build requirements are met and the appropriate entries are recorded in PATH (see the file CMakeLists.txt for details).

export NO_USE_VPKG

$Env:NO_USE_VPKG = $null

  1. Install the project as an editable package, along with the development dependencies.

make install

uv sync --verbose --group dev --group docs --group test --no-progress
uv run python -m pybind11_stubgen chalc.chromatic --numpy-array-use-type-var --output-dir ..\src
uv run python -m pybind11_stubgen chalc.filtration --numpy-array-use-type-var --output-dir ..\src
uv lock
uv export --locked --format pylock.toml --group dev --group docs --group test -o pylock.toml --quiet

Running tests

Install test dependencies and run the test suite:

uv run --group test pytest

Some tests require the Python package GUDHI, which is not available for free-threaded Python as of 16 October 2026. To install GUDHI and run the complete suite on a Python version supported by GUDHI:

uv run --group test-gudhi pytest

The equivalent Makefile targets are make tests and make tests-gudhi. Tests that require GUDHI are marked with a pytest marker gudhi, and can be skipped even with GUDHI installed:

``uv run --group test pytest -m "not gudhi"``.

Building the Documentation

To build the documentation, the development dependencies of the project need to be installed into the current environment. You also need to have GraphViz installed. Then run the following commands from the project root directory to build the documentation files.

make docs

Set-Location docs
uv run sphinx-build -M html source build

This will build the documentation into the folder docs/build with root index.html.