1. Installation
OkadaPy is a predominantly Python package with some routines written and optimised in C. These are built and linked to OkadaPy at installation - if installing from source you will need to ensure that there is a suitable compiler available (see C compilers).
However, most users can bypass this step by installing OkadaPy using pip.
1.1. Supported operating systems
OkadaPy was developed and tested on macOS 12.5.1 (M1 chip), with the intention of being “platform agnostic”. As of November 2024, the package has been successfully built and run on:
Ubuntu 16.04/18.04/20.04/22.04
Red Hat Enterprise Linux
Debian
Windows 10
macOS Monterey 12 (including M1)
1.2. Prerequisites
OkadaPy supports Python 3.11 or newer (3.11/3.12). We recommend using uv as a package manager and virtual environment system to isolate and install the specific dependencies of OkadaPy.
Instructions for downloading and installing uv can be found here.
1.3. Installation via pip
The simplest way to get a working copy of OkadaPy is to install it from the Python Package Index (PyPI) using pip (the Python package installer).
To do this you first need to set up an enivironment. We recommend creating a minimal environment initially:
uv venv --python=3.12
source .venv/bin/activate
All other dependencies will be handled during the installation of OkadaPy. After activating your environment, type the following command into terminal:
uv pip install okadapy
This will install OkadaPy and its explicit dependencies!
Note
Installing the package this way will not provide you with the examples. These can be retrieved directly from the GitHub repository (see Testing your installation).
The full list of dependencies is:
matplotlib
numpy
pandas
pyproj >= 2.5
pygmt (optional plotting backend)
Note
We are currently not pinning the version of any dependencies. We aim to keep on top of any new syntax changes etc. as new versions of these packages are released - but please submit an issue if you come across something!
If you want to explore the example notebooks, you will also need to install ipython and jupyter. This can be done with conda (making sure your environment is still activated) as:
uv pip install jupyter ipython
1.4. Other installation methods
1.4.1. From source
Note
In order to install from source, you will need an accessible C compiler, such as gcc or clang (see C compilers).
Clone the repository from our GitHub (note: you will need git installed on your system), or alternatively download the source code directly through the GitHub web interface. Once you have a local copy, navigate to the new OkadaPy directory.
As with the installation from PyPI, you should set up a virtual environment:
uv venv --python=3.12
source .venv/bin/activate
Since building from source means the C routines included with the package need to be compiled during installation, you will need an appropriate C compiler, such as gcc (Linux) or clang (macOS). If you are using Linux and uv, you will need to first set an environment variable specifying GCC should be used. This is necessary because the uv binaries are built with clang.
You can optionally pass a -e argument to install the package in ‘editable’ mode.
You should now be able to import okada within a Python session:
Warning
You should try this import in any directory that is not the root of the git repository (i.e. OkadaPy/. Here, the local okada directory will override the version of OkadaPy installed in your environment site-packages!
cd # Moving out of OkadaPy directory - see warning above!
python
>>> import okada
>>> okada.__version__
If successful, this should return ‘0.0.1’.
1.5. Testing your installation
In order to test your installation, you will need to have cloned the GitHub repository (see installation from source). This will ensure you have all of the required benchmarked data (which is not included in pip/conda installs).
To run the tests, navigate to OkadaPy/tests and run the benchmark testing script. This compares the outputs of OkadaPy with those computed for an identical input file with Coulomb3.4:
python run_benchmark_tests.py
If your installation is working as intended, this should execute with no failures.
1.6. C compilers
In order to install and use OkadaPy from source, you will need a C compiler.
If you already have a suitable compiler (e.g. gcc, MSVC, clang) at the OS level, then you can proceed with installation. If this fails, then read on for tips to overcome common issues!
1.6.1. Checking for a C compiler
On Linux or macOS, to check if you have a C compiler, open a terminal and type:
which gcc
gcc --version
If a compiler is present, the first command will return /usr/bin/gcc. However, this does not guarantee it is present! The second command will confirm this.
On Linux the second command should output something like:
gcc (Ubuntu 11.3.0-1ubuntu1~22.04) 11.3.0
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
As long as the version is relatively recent (version 9 or later), you should be good to go. To additionally confirm that you have a C++ compiler installed, type:
which g++
g++ --version
For which you should obtain a similar result.
On macOS it will be obvious if the compiler is not actually installed – you will be faced with a prompt to install the Xcode Command Line Tools. You can go ahead and install this (press Install and wait for the process to complete). If these are already installed, the second command should output something like:
Configured with: --prefix=/Library/Developer/CommandLineTools/usr --with-gxx-include-dir=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/4.2.1
Apple clang version 12.0.5 (clang-1205.0.22.11)
Target: x86_64-apple-darwin20.5.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin
Warning
Even if clang is installed, it may not have all necessary libraries included. See OpenMP on macOS.
Note that this indicates that the system compiler is clang, and that the accompanying C++ compiler is also installed. These are all supplied as part of the Xcode Command Line Tools (see e.g. here for a rundown).
If you do not have a compiler, or to be sure, we provide a simple guide for Linux, macOS and Windows operating systems below.
1.6.2. Linux
If you have root access, the simplest route is to install gcc and gxx at system-level. You should search for the correct way to do this for your Linux Distribution. For example, on Ubuntu you would type:
sudo apt-get install build-essential
This includes gcc, g++ as well as make. The commands will differ on other distros (CentOS, Red Hat, etc.).
Alternatively, you can install gcc and g++ through conda. Make sure you have activated your environment, then type:
conda install -c conda-forge gcc_linux-64 gxx_linux-64
You can test this was successful with the same procedure detailed above. Once installed, you can proceed with the OkadaPy installation from source.
1.6.3. macOS
By default, there is no C compiler included with macOS. If you have previously installed the Xcode Command Line Tools (via the web or the App Store), the clang compiler will be installed. However, this may not include all necessary libraries to install OkadaPy (see OpenMP on macOS).
Whether you already have Xcode installed or not, there are two options to install what is required: the user can either install all dependencies through conda - noting that they will only be available in that specific environment - or using HomeBrew. We generally recommend using conda, unless the user is already familiar with brew (in which case, see brew).
1.6.3.1. OpenMP on macOS
The default C compiler on macOS does not include support for OpenMP. This will result in the following error during installation from source:
ld: library not found for -lomp
clang: error: linker command failed with exit code 1 (use -v to see invocation)
error: command '/usr/bin/clang' failed with exit code 1
1.6.3.2. conda
First create and/or activate your environment:
conda create -n okada python=3.12 # if not already created
conda activate okada # replace with alternative environment name if desired
Then use conda to install the compiler (along with the OpenMP libraries). Note the syntax is different if your machine is running on an Apple Silicon (M1, M2, etc.) chip:
conda install -c conda-forge llvm-openmp clang_osx-64 clangxx_osx-64 # Intel chip
conda install -c conda-forge llvm-openmp clang_osx-arm64 clangxx_osx-arm64 # Apple Silicon chip (M1, M2 etc.)
Note
If you did not already have Xcode Command Line Tools installed, you will be prompted to install them now. Click Install and wait for installation to complete.
You should now open a fresh terminal, and activate your environment. To test the installation was successful, type:
echo $CC
$CC --version
This should return something like:
echo $CC
x86_64-apple-darwin13.4.0-clang
$CC --version
clang version 14.0.6
Target: x86_64-apple-darwin13.4.0
Thread model: posix
InstalledDir: /Users/user/miniconda3/envs/okada/bin
You can proceed with the OkadaPy installation from source.
1.6.3.3. brew
If brew is not already installed (check with which brew), follow the instructions on the HomeBrew frontpage. This will offer to install the Xcode Command Line Tools if they are not already present (press ‘ENTER’ or ‘Y’ to accept this suggestion).
You can then proceed to install the OpenMP libraries with brew:
brew install libomp
You can safely ignore the warning about explicitly adding the relevant LDFLAGS etc. - this is already handled in the OkadaPy setup.py script.
You can proceed with the OkadaPy installation from source.
1.6.3.4. Legacy: brew gcc
Alternatively, you can use the gcc compiler to install OkadaPy. As with clang, we recommend installing GCC through Homebrew. First, check if you already have gcc installed, with:
which gcc
If this doesn’t return anything, continue to installing gcc. If this returns the path to a gcc executable (e.g. /usr/bin/gcc), then you should check the version, with:
gcc --version
If the version string includes Apple clang, or is a version number lower than 9, you should proceed to install with Homebrew:
brew install gcc
brew link gcc
Note that the brew link command should add gcc to your path, but might not succeed if a previous gcc install was present. To test this, type:
which gcc
gcc --version
If the linking was successful, this should point to a new gcc executable, and the version string should contain gcc (Homebrew GCC 9.4.0) 9.4.0 or similar. If not, you will need to manually link the new gcc executable. To do this, find the path to your new gcc` installation with:
brew --prefix gcc
Then create a symlink to this executable:
ln -s /usr/local/bin/gcc /path/to/brew/gcc
Where /path/to/brew/gcc is the path returned by the brew --prefix command.
Finally, test this has worked by repeating the check from above:
which gcc
gcc --version
This should now return the Homebrew gcc version string. If not, please get in touch and we will try to help if we can…
1.6.4. Windows
Compilation and linking of the C extensions has been successful using the Microsoft Visual C++ (MSVC) build tools.
We strongly recommend that you download and install these tools in order to use OkadaPy. You can either install Visual Studio in its entirety, or just the Build Tools - available here.
You will need to restart your computer once the installation process has completed. We recommend using the anaconda command line interface (unix shell-like) to install OkadaPy over command prompt.
Once installed, you can proceed with the OkadaPy installation from source.