Installation

Supported versions and platforms

Note

Python environments may seem complex to new users. See the official tutorial on Virtual Environments and Packages for why they are necessary, and PyPA’s Tool recommendations. ember requires Python 3.12 or newer, and is incompatible with older versions of Python that may be provided by your operating system’s package manager.

The author’s preference is uv, as it is the fastest solution, and manages both virtual environments and Python versions.

ember follows SPEC 0 for its Python support window, currently Python |PythonVersion| or newer. We only test and provide precompiled wheels on Linux. The code may possibly be coerced to work on other operating systems, with some modifications, but you will need a working Fortran toolchain to build from source.

Via the Python Package Index

The most convenient way to install ember is via the Python Package Index (PyPI). Pass pip the distribution name ember-cfd, not the import name ember:

pip install ember-cfd

We precompile and distribute wheels for Linux (x86_64), so if your system matches you should not need a Fortran compiler to install from PyPI. On other systems, pip will automatically attempt to build from source, which requires a Fortran toolchain. Install these packages from your distribution’s package manager, for example on Debian/Ubuntu:

apt-get update
apt-get install -y gfortran meson ninja-build

The pip command above should then work without errors.

Note

On some cloud or CI images, the system gfortran symlink points at an uninstalled gfortran-<N> package. If the build fails with a missing gfortran error, run:

apt-get update
apt-get install -y --fix-broken

to pull in the missing compiler and fix the symlink.

From source

For performance tuning, or if you want to modify the code, you can build ember from source. You will need a Fortran compiler and build system:

apt-get update
apt-get install -y gfortran meson ninja-build

Clone the repository and make an editable install with pip:

git clone git@github.com:jb753/ember.git
cd ember
pip install -e .

Note that edits to .f90 files are not picked up automatically and need pip install -e . rerun; but edits to Python files are picked up immediately. This command always recompiles the Fortran extension from scratch, as when installing from a local directory there is no incremental build or wheel cache to go stale.

Verifying the install

Run this one-liner to check the Fortran extension is working:

python -c "from ember.fortran import set_residual; print('OK')"

Performance tuning

By default the Fortran extension is built for a portable x86_64 baseline (compiler flag -march=haswell), so a wheel or source build works on any Haswell-or-newer machine. For a build tuned to the exact CPU it will run on, replace that flag by setting the environment variable EMBER_MARCH before installing:

EMBER_MARCH="-march=native -mtune=native" pip install -e .

Both GNU and Intel Fortran toolchains are supported. To build with Intel compilers instead of gfortran, set EMBER_COMPILER=ifort before installing:

EMBER_COMPILER=ifort pip install -e .

Compiler flags can be further customised by editing setup.py. See the tools/compile_wilkes.sh script for an example of how to build on an HPC cluster.