Python API to SURFEX (pysurfex)

An API in python to the external surface model SURFEX.

• Prepare input and namelists to a SURFEX binary
• Create atmospheric forcing for offline SURFEX runs
• Read SURFEX output
• Quality control of observations with titanlib
• Optimal interpolation with gridpp
• Monitor the observations usage

See online documentation in https://metno.github.io/pysurfex/

Installation of pregenerated packages from pypi (pip)

All releases will trigger an autmomatic pre-built package on pypi which can be installed by pip

pip3 install pysurfex

User installation:

pip3 install pysurfex --user

Run pysurfex from pre-built container

Releases also trigger an update of the pysurfex container in the github container registry. Below is an example to run pgd without any arguments.

podman run -it ghcr.io/metno/pysurfex:latest poetry run pgd

Installation on debian based Linux system

Install the required pacakges (some might be obsolete if the pip packages contain the needed depedencies):

sudo apt-get update
sudo apt-get install -y libudunits2-dev libproj-dev libeccodes0 libeccodes-dev libnetcdf-dev netcdf-bin ca-certificates

The following depencies are needed. Install the non-standard ones e.g. with pip or your system installation system.

General dependencies (from pypi)

numpy
pyproj
pyyaml
toml
f90nml

To read NetCDF files:

NetCDF4
cfunits

To read grib files:

eccodes

from ECMWF https://software.ecmwf.int/wiki/display/ECC/Releases installed with ENABLE_PYTHON=ON

To plot:

matplotlib

To get observations from frost.met.no API:

requests

For Quality control of observations

titanlib

For optimal interpolation and observation operators

gridpp

For testing:

pytest

Install pysurfex

Download the source code, then install pysurfex by executing the following inside the extracted folder:

poetry install

This will install pysurfex in a poetry environment and this environment can be activated interactively by:

poetry shell

or

Run pysurfex client applications

poetry run [command]
# e.g.
poetry run python # will run python inside the pysurfex poetry environment

Run pysurfex client applications

import sys
from pysurfex.cli import parse_args_surfex_binary, run_surfex_binary

argv = sys.argv[1:]
kwargs = parse_args_surfex_binary(argv, "pgd")
run_surfex_binary("pgd", **kwargs)

Examples

See https://metno.github.io/pysurfex/#examples