Installation

PAMTRA is installed with pip, which compiles the Fortran core and builds both the pyPamtra Python extension and the standalone pamtra command line binary (PAMTRA) in one step via meson-python. This has replaced the old make / make pyinstall workflow.

Note

A regular pip install . puts the pamtra binary in the same bin/ directory as python/pip themselves, so it’s already on PATH whenever that environment is active – no extra step needed. An editable install (pip install -e ., see below) does not install it, since meson-python’s editable-install support only covers the Python extension; build/run it straight out of the build directory instead (see PAMTRA).

Warning

If this checkout was ever built with the legacy Makefile (make / make pamtra, still used for HPC deployments – see below), run make clean first. The Makefile compiles directly into src/, and a subsequent pip install . can pick up those leftover .mod files instead of building fresh ones, failing with something like Cannot read module file '../src/foo.mod' ... created by a different version of GNU Fortran.

Get the code

The version control system git (http://git-scm.com/) is used to keep track of the code. Get a copy of the model with:

git clone https://github.com/igmk/pamtra.git
cd pamtra

conda-forge / pixi (recommended, cross-platform)

The dependencies below (openblas, fftw, netcdf, a matching C/Fortran compiler pair) are all available as conda-forge packages, including working macOS (both Intel and Apple Silicon) builds. This avoids needing a system package manager (apt/brew) at all, and is the same install path used by PAMTRA’s CI.

With conda or mamba:

conda create -n pamtra -c conda-forge python numpy scipy netcdf4 matplotlib \
    meson meson-python cython pkg-config fftw libopenblas libnetcdf \
    c-compiler fortran-compiler
conda activate pamtra
pip install --no-deps --no-build-isolation .

Or, if you use pixi (also conda-forge-based), the repository already has a pixi.toml with this dependency set defined — just run:

pixi install
pixi run install
pixi run test    # optional, runs the test suite

pixi run install and the manual pip install above both build with --no-build-isolation, so the compiler/library versions actually pinned in your conda/pixi environment are used instead of a fresh isolated build environment.

Linux (Ubuntu), apt

Install the system libraries needed to compile PAMTRA:

sudo apt install git gfortran libopenblas-dev libfftw3-dev libnetcdff-dev

Create and activate a virtual environment:

sudo apt install python3-venv
python3 -m venv pamtraenv
source pamtraenv/bin/activate

Install the Python build and runtime dependencies:

pip install numpy scipy matplotlib netcdf4 xarray meson numexpr cython

Then install PAMTRA itself:

pip install .

Warning

On some Linux systems, OpenBLAS is not thread-safe when run with multiple parallel jobs. If you see hangs or crashes, set:

export OPENBLAS_NUM_THREADS=1

before starting python.

macOS, Homebrew

Install the required libraries with Homebrew:

brew install openblas pkgconf netcdf fftw

Then install PAMTRA, pointing the C compiler at the Homebrew gcc that matches your gfortran (adjust the version number, e.g. gcc-14, to whatever brew install gcc provides on your system):

env CC=gcc-14 pip install .

Note

openblas is keg-only in Homebrew (macOS ships BLAS/LAPACK via the Accelerate framework instead), so its .pc file is not on the default pkg-config search path. The build automatically falls back to brew --prefix openblas to locate it, so you do not need to manually export PKG_CONFIG_PATH for openblas.

Windows, WSL2

On Windows, install WSL2 with an Ubuntu distribution, then follow the Linux instructions above verbatim inside the WSL2 Ubuntu shell – there is no separate native Windows build.

DKRZ Levante HPC

module load git
spack load /fwvsvi # python3.9.9
python -m venv pamtraenv
source pamtraenv/bin/activate
pip install numpy scipy matplotlib netcdf4 cython xarray meson

git clone https://github.com/igmk/pamtra.git
cd pamtra

spack load /bcn7mbu # gcc 11.2
spack load /tpmfvwu # openblas 0.3.18 gcc 11.2
spack load /fnfhvr6 # fftw 3.10.10
spack load /jn6xcuy # netcdf-fortran 4.6.1 gcc 11.2
pip install .

The exact spack hashes may change over time; use spack find to look up the current ones if a spack load fails. See also install_levante_readmefirst.sh in the repository root, which automates an equivalent module/env setup using the legacy Makefile build – kept around specifically for HPC deployments like this one, where hand-tuned linker flags against cluster module paths are simpler to express as Makefile variables than through meson/pkg-config.

For Jupyter support:

pip install ipykernel
python -m ipykernel install --user --name=pamtra-kernel --display-name="pamtra kernel"

Editable / development install

While developing PAMTRA, an editable install avoids a full reinstall after every Fortran change:

pip install --no-build-isolation -e . -Cbuild-dir=build

Download data

This data includes the land surface emissivity maps and some scattering databases. Many features (e.g. Mie-sphere scattering, the built-in surface emissivity defaults) work without it.

For pyPamtra, nothing to do here: if PAMTRA_DATADIR isn’t set at all, import pyPamtra downloads and caches the data automatically (via pooch, with a checksum check), the first time only. If you’d rather not have the first import trigger a ~250 MB download, fetch it ahead of time the same way:

export PAMTRA_DATADIR=$(pamtra-fetch-data)

and add that line to your shell startup file. To explicitly skip the data entirely (rather than let it auto-download), set PAMTRA_DATADIR="" before importing.

For the standalone pamtra binary (PAMTRA, no pip/Python dependency at runtime, so no auto-download either), download and unpack the data manually:

wget -q -O data.tar.bz2 https://github.com/igmk/pamtra/releases/download/data-v1/pamtra_data.tar.bz2
tar xjf data.tar.bz2
rm data.tar.bz2
echo 'export PAMTRA_DATADIR="wherever/it/is/"' >> ~/.bashrc
source ~/.bashrc

Start PAMTRA

You can start using pyPamtra in python with

import pyPamtra

Build documentation

The documentation is built using Sphinx. Install the build dependency with pip:

pip install sphinx

Then build it using the Makefile in the doc directory:

cd doc
make html