1.2. Installation¶

This page describes how to install and build Open Interfaces on a Unix-like system, such as Ubuntu or macOS. We do not support Windows at the moment, unfortunately, but it might be possible to install Open Interfaces using Windows Subsystem for Linux (WSL).

1.2.1. Overview and prerequisites¶

The installation of Open Interfaces depends on what programming languages you want to use (bindings and implementations) as well as the preferred package manager for installing dependencies.

We assume that the following software is installed on your system:

curl or git for downloading the source code
Package manager such as apt for Debian-like systems or conda/ mamba for Linux, for installing the dependencies.
Xcode Command Line Tools and package manager brew for macOS (this is currently the only supported option)

If the prerequisites are installed:

Obtain the source code
Read about mandatory and optional dependencies in the Dependencies section
Install dependencies:
- On macOS
- On Ubuntu
Build the source
Run tests
Run examples

1.2.2. The source code¶

Download the archive with the source code of the (latest release of Open Interfaces)[https://github.com/MaRDI4NFDI/open-interfaces/releases/latest] and unpack the content to a directory of your choice. Then open a terminal and go to that directory.

Alternatively, download and unpack the source code directly from the terminal, for example, for the latest release:

curl -LO https://github.com/MaRDI4NFDI/open-interfaces/archive/refs/tags/v0.6.2.tar.gz
tar -xzvf v0.6.2.tar.gz
cd open-interfaces-0.6.2

If you prefer to use the latest development version, you can obtain it by cloning the repository via git:

git clone git@github.com:MaRDI4NFDI/open-interfaces.git      # via SSH
# or
git clone https://github.com/MaRDI4NFDI/open-interfaces.git  # via HTTPS

and then change to the repository directory:

cd open-interfaces

1.2.3. Dependencies¶

Open Interfaces depend on several external libraries and tools, such as CMake, a C compiler, Python interpreter, Julia, SUNDIALS, SciPy, etc.

All dependencies can be installed through a package manager, such as apt, brew, or conda.

1.2.3.1. Mandatory dependencies¶

The following dependencies are mandatory for building and running Open Interfaces:

A C compiler supporting the C17 standard, such as gcc 9+ or clang 7+
A C++ compiler supporting the C++17 standard, such as g++ 9+ or clang++ 7+
The CMake meta-build system v3.18+
libffi v8+
The Make build system v4.3+
pkg-config v0.29+

With these dependencies installed, very minimal build can be done enabling C bindings and one (test-level) implementation in C. It is recommended to follow with the next section before building the source code.

1.2.3.2. Optional recommended dependencies¶

The following dependencies are optional but recommended:

To really benefit from Open Interfaces, it is recommended to install additional dependencies which enable more implementations (and also languages).

For C implementations LAPACK library and SUNDIALS v6.0+ will enable c_lapack implementation of the linsolve interface and sundials_cvode implementation of the ivp interface, respectively.

For Julia bindings and implementations, Julia 1.10+ is required along with several Julia packages. The only supported installation method for Julia and Julia packages is described in this section.

If your preferred programming language is Python, you can install Open Interfaces via pip as described here, which builds Open Interfaces automatically, so you do not have to build the library by hand.

1.2.4. Installation on Ubuntu¶

Mandatory and optional dependencies can be installed on Ubuntu using the apt package manager as described in this section or alternatively via conda as described here.

1.2.4.1. Installation on Ubuntu via `apt`¶

Mandatory dependencies:

sudo apt install build-essential cmake libffi-dev pkg-config

Python development headers, scientific packages and test framework:

sudo apt install python3-dev python3-numpy python3-scipy python3-matplotlib python3-pytest

For instructions on how to install Julia and Julia packages, please go here.

1.2.4.2. Installation on Ubuntu via `conda`¶

Using the conda package manager helps with obtaining software dependencies such as C compiler, Python interpreter, SUNDIALS, etc. Additionally, all dependencies (except Julia and Julia packages) will be installed in a separate environment, therefore, there will be no conflicts with system packages.

If conda is not installed, it can be installed via the following command:

curl -LO https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh

After that, create an environment for Open Interfaces and install the dependencies using the provided environment-linux.yaml file:

conda env create -n open-interfaces -f environment-linux.yaml

Then activate the created environment:

conda activate open-interfaces

and proceed with building the source code.

1.2.5. Installation on macOS¶

On modern macOS systems with Apple Silicon architecture the only supported installation depends on Apple-provided core development tools and additional dependencies such as Python or OpenBlAS installed via the Homebrew package manager.

Install development tools (Clang, Clang++, Make, etc.):
```
  xcode-select install
```
Install CMake via Homebrew:
```
brew install cmake
```
(Optional) Install C implementations:
```
brew install openblas sundials
```
(Optional) Install Python:
```
brew install python
```

(Optional) Create Python virtual environment and install Python packages (recommended):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-macos.txt

(Optional) Install Julia Instructuctions are here.
Proceed with building the source code.

1.2.5.1. Installing Julia and Julia packages¶

If you are interested in using Julia bindings and implementations, you need to install Julia and required Julia packages. Currently, Julia packages are not available, but the instructions in this section will help you to set up the environment and install Julia dependencies via provided project files.

The recommend way of installing Julia is via the following command:

curl -fsSL https://install.julialang.org | sh

Then, assuming that the current working directory is the source code of Open Interfaces, create and activate a Julia environment for Open Interfaces and install required Julia packages:

julia --project=. -e 'using Pkg; Pkg.instantiate()'

1.2.6. Building the source code¶

After the necessary dependencies are installed, and environments are activated, we can build Open Interfaces.

To build the software, use command

    make

which invokes cmake and builds Open Interfaces inside the build subdirectory enabling compiler optimizations.

1.2.7. Checking the build¶

We set auxiliary environment variables via the following command:

source env.sh

that sets PATH, LD_LIBRARY_PATH, and PYTHONPATH, and OIF_IMPL_PATH variables. These variables are necessary for running examples and tests. The last variable, OIF_IMPL_PATH, is used to point to the directories where implementations are searched for.

To check that the build was successful, you can run the provided tests via command

    make test

which should take no more than a few minutes to complete. In case when not all dependencies are installed, some tests might be skipped if the corresponding implementations or languages are not available.

1.2.8. Running examples¶

Open Interfaces comes with several examples the source code of which can be found in the examples directory of the source code.

For guidance on how to run them, please refer to the specific pages in the Table of Contents.

1.2.9. Installation of Python bindings via `pip`¶

If you are interested mostly in Python bindings as well as C and Python implementations, then the easiest way to install Open Interfaces is via pip from the Python Package Index (PyPI).

First, ensure that essential dependencies for Python are installed. On Ubuntu, this can be done via (in addition to the mandatory dependencies):

sudo apt install python3-dev python3-venv

Optional dependencies include LAPACK and SUNDIALS libraries for C implementations, which can be installed via:

sudo apt install liblapack-dev libsundials-dev

Then create a virtual environment for Python:

python3 -m venv .venv

and activate it:

source .venv/bin/activate

Finally, install Open Interfaces via pip:

pip install openinterfaces

To quickly make sure that the installed package work, execute this lines in the Python console:

from openinterfaces.interfaces.ivp import IVP
solver = IVP("scipy_ode")

1.2.10. For developers: Building the source code for development¶

If you plan to work on the source code, it is recommended to build it in the Debug mode with the command

    make debug

which enables additional runtime checks and debugging symbols, particularly useful when using a debugger such as gdb or lldb.

Also, there is a special configuration for development that helps with finding memory leaks and memory corruption errors:

    make debug-verbose-info-and-sanitize

which should be used when working on the C source code mostly, as sanitizers are not compatible with Python and Julia bindings, as well as due to the verbosity of debugging messages.

1.2.10.1. Quality assurance during development¶

To ensure code consistency, we use pre-commit. It is configured to run multiple checks for formatting and trailing whitespace for all source code in the repository. During development, the checks can be run automatically by installing a pre-commit Git hook:

pre-commit install

or by invoking it manually via

pre-commit run --all-files

We recommend running it automatically so that the code is pushed only after running these checks to avoid wasting time and computational resources on the continuous-integration service.