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
orgit
for downloading the source codePackage manager such as
apt
for Debian-like systems orconda
/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:
Read about mandatory and optional dependencies in the Dependencies section
Install dependencies:
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+ orclang
7+A C++ compiler supporting the C++17 standard, such as
g++
9+ orclang++
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 python3-numpy python3-scipy python3-msgpack
Optional dependencies include LAPACK
and SUNDIALS
libraries
for C implementations, which can be installed via:
sudo apt install liblapack-dev libsundials-dev
Then it is recommended to 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
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.