NetCDF reader and writer components for the FINAM model coupling framework.

Uses xarray for all input and output functionality.



pip install finam-netcdf

For available components, see the API reference.


See the example scripts in the GitLab repository for fully functional usage examples.


The package provides two types of NetCDF reader components:

Both components can read multiple variables from a single dataset.


Reads once during initialization of the coupling setup. A time slice must be provided if the variable is actually temporal.

from finam_netcdf import Variable, NetCdfStaticReader

path = "tests/data/"
reader = NetCdfStaticReader(path, [Variable("lai", fixed={"time": 0})])


Reads once on each time step, where time steps are defined by the time dimension provided by the dataset (but see also [Time manipulation](#time-manipulation)).

from finam_netcdf import NetCdfReader

path = "tests/data/"
reader = NetCdfReader(path, ["lai"])

When multiple variables/layers are read, they must all use the same time dimension (i.e. they must have common time steps).

Time manipulation#

In some cases, it may not be desirable to use time data from a dataset directly. The example dataset used above contains 12 LAI rasters along the temporal axis, one for each month of the year. This example cycles through the 12 rasters every year:

from datetime import datetime
from finam_netcdf import NetCdfReader

start = datetime(2000, 1, 1)

def to_time_step(tick, _last_time, _last_index):
    year = start.year + tick // 12
    month = 1 + tick % 12
    return datetime(year, month, 1), tick % 12

path = "tests/data/"
reader = NetCdfReader(path, ["lai"], time_callback=to_time_step)


Component outputs can be accessed by the keys used for outputs, e.g. for linking:

reader.outputs["lai"] >> viewer.inputs["Grid"]


The package provides two types of NetCDF writer components:

Both components can write multiple variables to a single dataset.


Writes time slices regularly, irrespective of input time steps.

from datetime import timedelta
from finam_netcdf import NetCdfTimedWriter

path = "tests/data/"
reader = NetCdfTimedWriter(path, ["lai"], step=timedelta(days=1))


Writes time slices as soon as new data becomes available to the inputs. Note that all input data sources must have the same time step!

from finam_netcdf import NetCdfPushWriter

path = "tests/data/"
reader = NetCdfPushWriter(path, ["lai"])

API References#

Information about the API of FINAM-NetCDF.


Further information about licensing, the developers team and the changelog of FINAM-NetCDF.


LGPLv3, Copyright © 2021-2023, the FINAM developers from Helmholtz-Zentrum für Umweltforschung GmbH - UFZ. All rights reserved.