Installation#

There are two ways to get pyoti (the Python interface to OTIlib) on your system:

  • Install the conda package (recommended for most users). A precompiled package is published on anaconda.org for Linux and macOS. No compilers or build steps are required.

  • Build from source (recommended for development, or if you need a compiler configuration that the conda package does not provide). The source code is available at mauriaristi/otilib.

Both approaches use conda to manage the environment and its dependencies. Make sure you have a conda distribution installed (see Anaconda or Miniconda).

Warning

This library has been tested under the following operating systems:

  • Unix platforms (Ubuntu, CentOS, Rocky Linux).

  • macOS (tested on Tahoe 26.*; see macOS specific instructions below when building from source).

  • Windows (only working under WSL).

A pure Windows installation is currently not supported.

Installing with conda#

The easiest way to get pyoti installed is to create a separate conda environment that includes the package and all of its requirements:

conda create -n pyoti-env -c conda-forge mauriaristi::pyoti --solver rattler

This command:

  • Creates a new environment named pyoti-env (you may choose any other name).

  • Installs all dependencies from the conda-forge channel.

  • Installs pyoti from the mauriaristi channel on anaconda.org.

  • Uses the rattler solver. This is required because the current default solver freezes while solving the environment (observed with conda 26.7.2).

The conda package ships the compiled library together with the precomputed data tables, so no compilation or make gendata step is needed.

After the installation completes, activate the environment so that pyoti becomes importable:

conda activate pyoti-env

You can verify the installation with:

python -c "import pyoti; print(pyoti.__version__)"

To update to the latest published version at a later time, run the following from within the environment:

conda update -c conda-forge mauriaristi::pyoti --solver rattler

Note

If you also want to use pyoti from Jupyter notebooks, see Adding the environment to the global jupyter notebook server below. The steps are the same for both installation methods, replacing the environment name where appropriate.

Building from source#

Prerequisites#

The recommended way to install the prerequisites is to use conda and the provided environment.yml file.

Minimum requirements are the following:

  • Python 3 (Tested with python 3.13)

  • Numpy >= 2.1, < 3

  • Scipy

  • scikit-umfpack (optional; only needed for the solver=’umfpack’ sparse solver, requires a NumPy 2-compatible upstream build)

  • sksparse-cholmod (optional; only needed for the solver=’cholesky’ sparse solver, requires a NumPy 2-compatible upstream build)

  • Cython>=3.0

  • CMake>=3.20

Conda environment for building#

After cloning OTILIB, go to a terminal instance and go to the directory where you downloaded this repository.

cd /PATH/TO/OTILIB-MASTER/

It is recommended to create a conda environment with the required dependencies. For this, it is easier to install the environment.yml file by running:

conda env create -f environment.yml --solver rattler

The --solver rattler flag is needed for the same reason as above: the default solver may hang while solving this environment.

NOTE: If you had a previous version of OTILIB, you may avoid this step. However, it is recommended that you update your current environment. For this, run the following command (see this for more details):

conda activate pyoti
conda env update --file environment.yml --prune --solver rattler

Note: Use env_basic.yml to use pyoti in its most basic form.

After running the previous command, you should have installed/updated the conda environment that will allow you to build and use the python version of the library. To activate this environment, run the following command:

conda activate pyoti

MacOS additional instructions#

When you use MacOS, particularly Apple Silicon Macs, it is recommended to have the following steps:

Install libomp using brew:

brew install libomp

In addition, install GNU gfortran from conda-forge:

conda install -c conda-forge gfortran --solver rattler

This will add gfortran with support for the architecture of your processor, which is important.

Compiling the library#

In order to build the library with your default compilers, run the following commands:

cd path/to/src/otilib
mkdir build
cd build
cmake ..
make

This will compile the library and link to the required dependencies.

If you want to compile with a different compiler, e.g. the Intel OneApi compilers, you can define the CC and FC flags as follow

cd path/to/src/otilib
mkdir build
cd build
CC=icx FC=icx cmake ..
make

Note

If you had previously compiled the library and want to change the compiler, you need to remove the contents of the build/ directory. Use rm -rf -v !(data) to keep the data folder (if any).

Note

If this is your first time compiling the library, you should run the following command after the library is compiled:

make gendata

This will pre-compute the data required for standard operation of OTI library.

Additional CMake compilation options include disabling OpenMP compilation. For that, use a command line as follows:

cmake -D USE_OPENMP=OFF ..

The library is currently in an active development stage. Therefore, you need to add the library to the conda path in order to import the library in your projects. For this, please run the following command. (Got instructions from this link to add the build directory to the path):

cd /PATH/TO/OTILIB-MASTER/build/
conda activate pyoti
conda develop .

In order to remove this folder to the path, run:

cd /PATH/TO/OTILIB-MASTER/build/
conda activate pyoti
conda develop -u .

Adding the environment to the global jupyter notebook server#

You need to install ipykernel within your environment. To do so, activate your environment if not activated and run the following command (ipykernel is already included when the environment was created from environment.yml).

conda install -c conda-forge ipykernel --solver rattler

After this, and still within your environment, run the following to add the environment to your ipython kernel options. Replace pyoti-env with pyoti if you built from source.

python -m ipykernel install --user --name=pyoti-env