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 (x86_64), and macOS (x86_64 and aarch64). Chalc works with CPython and PyPy ≥ 3.12.

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. The Eigen C++ library (tested with version 3.4.0).

2. The 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. The Computational Geometry Algorithms Library (CGAL) library (tested with version 6.0.1).

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

The recommended way to obtain and manage these dependencies is using vcpkg (see the build dependencies section) . It is also recommended to use a Python virtual environment for the build process to avoid polluting the package namespace.

Build dependencies

1. CMake (version 3.23 or later).

2. On Windows: Visual Studio 2019 or later.

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

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

4. (MacOS only) The build tools automake, autoconf, and libtool. You can install these with brew install automake autoconf libtool.

Build steps

1. Clone the git repository.

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

2. 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.

Bash

export VCPKG_ROOT=/path/to/vcpkg/dir

Powershell

$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 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).

Bash

export NO_USE_VPKG

Powershell

$Env:NO_USE_VPKG = $null

3. Build the package wheel using pip wheel and install the compiled binary.

pip wheel . -w outputdir
pip install outputdir/<name_of_generated_wheel>.whl

Building the Documentation

To build the documentation, the development dependencies of the project need to be installed into a virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Then run the following commands from the project root directory to build the documentation files.

Bash

make -C docs html

Powershell

Set-Location docs
python -m pybind11_stubgen chalc.chromatic --numpy-array-use-type-var --output-dir ..\src
python -m pybind11_stubgen chalc.filtration --numpy-array-use-type-var --output-dir ..\src
sphinx-build -M html source build

This will build the documentation into the folder docs/build with root index.html. You can then clean up the generated virtual environment.

Bash

deactivate && rm -rf .venv

Powershell

Set-Location .. && deactivate && Remove-Item -Path .venv -Recurse -Force