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.
The Eigen C++ library (tested with version 3.4.0).
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.
The Computational Geometry Algorithms Library (CGAL) library (version 5.6).
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¶
CMake (version 3.23 or later).
On Windows: Visual Studio 2019 or later. On Linux: GCC11 or later. On MacOS: Clang 14 or later.
(Recommended) Microsoft vcpkg C++ dependency manager.
(MacOS only) The build tools automake, autoconf, and libtool. You can install these with
brew install automake autoconf libtool
.
Build steps¶
Clone the git repository.
$ git clone https://github.com/abhinavnatarajan/chalc
$ cd chalc
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 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
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, first make sure that chalc
is installed and available to the Python interpreter.
Then run the following commands from the root directory of the repository.
$ cd docs
$ pip install -r requirements.txt
This installs the necessary dependencies used to generate the documentation from the API. The commands to build the documentation depend on the platform you are using:
$ make html
> 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
.
In order to avoid polluting your global Python package tree, it is a good idea to install chalc
and run the pip install ..
command above in a virtual environment.