Skip to main content

Standalone driver for ICON4Py

main.py contains a simple Python program to run the experimental ICON4Py port.

The driver reads its configuration from a configuration directory, initializes the grid and model state, and runs the time integration. Which granules are active (diffusion, solve_nonhydro, tracer advection, microphysics) is determined by the provided configuration rather than being hardcoded.

It supports both single-node and distributed (MPI) runs, including distributed output: in MPI runs the ranks write either through the root rank (gather mode) or each into its own block of a shared store (distributed mode, the default; see icon4py.model.common.io).

Installation

See the general instructions in the README.md in the base folder of the repository.

Usage

# set environment variables (optional but convenient)
export ICON4PY_ROOT=<path to the icon4py clone>
export GRID_FOLDER=<path to the folder holding grids>
export CONFIG_FOLDER=<path to the configuration directory>

# command line arguments
icon4py-driver \
    --grid-file-path $GRID_FOLDER/icon_grid_0013_R02B04_R.nc \
    --config-file-path $CONFIG_FOLDER \
    --icon4py-backend gtfn_cpu \
    --output-path $ICON4PY_ROOT/output_path \
    --enable-output

A distributed (MPI) run with output only differs in the launcher:

mpirun -np 4 icon4py-standalone-driver \
    --grid-file-path $GRID_FOLDER/icon_grid_0013_R02B04_R.nc \
    --config-file-path $CONFIG_FOLDER \
    --icon4py-backend gtfn_cpu \
    --output-path $ICON4PY_ROOT/output_path \
    --enable-output --output-backend zarr --output-mode distributed

Configuration directory

The driver expects a configuration directory containing the following JSON files:

  • NAMELIST_ICON_output_atm.json
  • icon_master.namelist.json
  • NAMELIST_expname.json

These are generated from the corresponding Fortran namelists and describe the experiment, the atmosphere setup, and the input parameters.

To generate these from an experiment run with Fortran ICON you can use the f90nml Python package to generate the JSON files from the original NAMELIST files of the Fortran ICON simulation. Once the Fortran ICON simulation has finished, there is a folder generated in <ICON_ROOT>/<BUILD_TYPE>/experiments/<EXPERIMENT_NAME> that includes the necessary NAMELIST files to configure the ICON4Py driver. Using the following instruction you can export the necessary files to their JSON equivalent format:

mkdir CONFIG_DIR
f90nml -g config_nml <ICON_ROOT>/<BUILD_TYPE>/experiments/<EXPERIMENT_NAME>/NAMELIST_ICON_output_atm CONFIG_DIR/NAMELIST_ICON_output_atm.json
f90nml -g config_nml <ICON_ROOT>/<BUILD_TYPE>/experiments/<EXPERIMENT_NAME>/icon_master.namelist CONFIG_DIR/icon_master.namelist.json
f90nml -g config_nml <ICON_ROOT>/<BUILD_TYPE>/experiments/<EXPERIMENT_NAME>/NAMELIST_<EXPERIMENT_NAME> CONFIG_DIR/NAMELIST_expname.json

Once the above is done you can provide the CONFIG_DIR to the --config-file-path of the icon4py-driver to configure the simulation the same way as the ICON Fortran one.

Of course you can write the necessary configuration files manually or start by some template files and edit them yourself.

Required options

  • --grid-file-path: path to the ICON grid file.
  • --config-file-path: path to the directory containing the configuration JSON files.
  • --icon4py-backend: GT4Py backend for running the driver. Run with --help to see the available backends.

Optional options

  • --output-path: override the output path from the configuration file.
  • --log-level: logging level. Possible values are notset (default), debug, info, warning, error, critical.
  • --print-distributed-debug-msg: print debug logging messages from all MPI ranks (only effective when --log-level debug is set).
  • --enable-output/--no-enable-output: write prognostic and diagnostic fields to output. Defaults to --no-enable-output. Works in single-node and MPI runs alike (output is collective in MPI runs).
  • --output-backend: file format of the output, zarr (default) or netcdf.
  • --output-mode: how the ranks of an MPI run write the output: distributed (default; every rank writes its own block of a shared store) or gather (owned entries are collected and written by the root rank). Distributed netCDF requires an MPI-parallel netCDF4 installation (checked at startup, see icon4py.model.common.io); zarr is parallel with any installation.

Metadata

Release files for icon4py-driver 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for icon4py-driver 0.5.0
File Size Uploaded Provenance Actions
icon4py_driver-0.5.0.tar.gz 49.8 kB With provenance Details for icon4py_driver-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for icon4py-driver 0.5.0
File Interpreter ABI Platform Actions
icon4py_driver-0.5.0-py3-none-any.whl Python 3 none any Details for icon4py_driver-0.5.0-py3-none-any.whl

Total release size: 102.1 kB

Release files / icon4py_driver-0.5.0.tar.gz

Download URL icon4py_driver-0.5.0.tar.gz
Size 49.8 kB
Tags Source
SHA-256 checksum
How to use checksums
42815575a2c3e575ef559692dee155dfe0e300621244eeba145f7001ce442fba
BLAKE2b-256 checksum
How to use checksums
10d14b63218019b9ccd025edb74633993ba76c96e0397b3d543b77b97d7d2dfb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / icon4py_driver-0.5.0-py3-none-any.whl

Download URL icon4py_driver-0.5.0-py3-none-any.whl
Size 52.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
580f4f58b33f3e05d5b85abdadd95bbec68bad43d9552891063030caa6bf6360
BLAKE2b-256 checksum
How to use checksums
9819fa1fafde6d13096efd8c90dfd4427a08032dbec5c29ca2ef72c27a558ce4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for icon4py-driver 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for icon4py_driver-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page