Installation

Installation#

Dependencies#

heyoka.py has several Python and C++ dependencies. On the C++ side, heyoka.py depends on:

  • the heyoka C++ library, version 6.1.x (mandatory),

  • the Boost C++ libraries (mandatory),

  • the {fmt} library (mandatory),

  • the TBB library (mandatory),

  • the mp++ library (mandatory if the heyoka C++ library was compiled with the HEYOKA_WITH_MPPP option enabled and the mp++ installation supports quadruple-precision computations via the mppp::real128 type and/or arbitrary-precision computations via the mppp::real type - see the heyoka and mp++ installation instructions).

On the Python side, heyoka.py requires at least Python 3.5 and depends on:

  • NumPy (version <2, mandatory),

  • cloudpickle (mandatory),

  • SymPy (version >=1.13.0) and mpmath (optional, for converting heyoka.py expressions to/from SymPy expressions).

The tested and supported CPU architectures at this time are x86-64, 64-bit ARM and 64-bit PowerPC.

Packages#

conda#

heyoka.py is available via the conda package manager for Linux, OSX and Windows thanks to the infrastructure provided by conda-forge. In order to install heyoka.py via conda, you just need to add conda-forge to the channels, and then we can immediately install heyoka.py:

$ conda config --add channels conda-forge
$ conda config --set channel_priority strict
$ conda install heyoka.py

The conda packages for heyoka.py are maintained by the core development team, and they are regularly updated when new heyoka.py versions are released.

Please refer to the conda documentation for instructions on how to setup and manage your conda installation.

pip#

A heyoka.py package for x86-64 Linux is available on PyPI. You can install it via pip:

$ pip install heyoka

Warning

heyoka.py relies on a stack of C++ dependencies which are bundled in the pip package. There is a non-negligible chance of conflicts with other packages which might also depend on and bundle the same C++ libraries, which can lead to unpredictable runtime errors and hard-to-diagnose issues.

We encourage users to install heyoka.py via conda rather than pip whenever possible.

FreeBSD#

A community-supported FreeBSD port via pkg is available for heyoka.py. In order to install heyoka.py using pkg, execute the following command:

$ pkg install py39-heyoka

Installation from source#

Warning

When installing from source, it is important to ensure that the compiler that was used to build heyoka.py’s dependencies is ABI-compatible with the compiler that is being used to build heyoka.py. Mixing incompatible compilers will likely lead to hard-to-diagnose build and/or runtime issues.

heyoka.py is written in modern C++, and it requires a compiler able to understand at least C++20. The library is regularly tested on a continuous integration pipeline which currently includes several compilers (GCC, Clang, MSVC) on several operating systems (Linux, OSX, Windows) and several CPU architectures (x86-64, 64-bit ARM and 64-bit PowerPC).

In addition to the C++ dependencies enumerated earlier, installation from source requires also:

Note that heyoka.py makes use of the NumPy C API and thus NumPy must be installed before compiling heyoka.py from source. The other Python dependencies need not to be installed at compilation time.

After making sure the dependencies are installed on your system, you can download the heyoka.py source code from the GitHub release page. Alternatively, and if you like living on the bleeding edge, you can get the very latest version of heyoka.py via git:

$ git clone https://github.com/bluescarni/heyoka.py.git

We follow the usual PR-based development workflow, thus heyoka.py’s main branch is normally kept in a working state.

After downloading and/or unpacking heyoka.py’s source code, go to heyoka.py’s source tree, create a build directory and cd into it. E.g., on a Unix-like system:

$ cd /path/to/heyoka.py
$ mkdir build
$ cd build

Once you are in the build directory, you must configure your build using cmake. There are various useful CMake variables you can set, such as:

  • CMAKE_BUILD_TYPE: the build type (Release, Debug, etc.), defaults to Release.

  • CMAKE_PREFIX_PATH: additional paths that will be searched by CMake when looking for dependencies.

  • HEYOKA_PY_INSTALL_PATH: the path into which the heyoka.py module will be installed. If left empty (the default), heyoka.py will be installed in the global modules directory of your Python installation.

  • HEYOKA_PY_ENABLE_IPO: set this flag to ON to compile heyoka.py with link-time optimisations. Requires compiler support, defaults to OFF.

Please consult CMake’s documentation for more details about CMake’s variables and options.

The HEYOKA_PY_INSTALL_PATH option is particularly important. If you want to install heyoka.py locally instead of globally (which is in general a good idea), you can set this variable to the output of python -m site --user-site.

After configuring the build with CMake, we can then proceed to actually building heyoka.py:

$ cmake --build .

Finally, we can install heyoka.py with the command:

$ cmake  --build . --target install

Verifying the installation#

You can verify that heyoka.py was successfully compiled and installed by running the test suite with the following command:

$ python -c "import heyoka; heyoka.test.run_test_suite();"

If this command executes without any error, then your heyoka.py installation is ready for use.

Note that the test suite makes use of the optional dependencies, thus if they are not installed some tests will fail.

Getting help#

If you run into troubles installing heyoka.py, please do not hesitate to contact us by opening an issue report on github.