FINAM VTK#

VTK readers, writers, and helper utilities for the FINAM model coupling framework.

Quickstart#

Installation:

pip install finam-vtk

The top-level finam_vtk package exports:

Readers: VTKStaticReader and PVDReader
Writers: VTKStaticWriter, PVDTimedWriter, and PVDPushWriter
Helpers: DataArray, read_vtk_grid(), read_aux_file(), and the finam_vtk.tools module

For the generated API reference, see the API reference.

Usage#

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

Readers#

The package provides two reader components:

VTKStaticReader reads a single VTK dataset during initialization.
PVDReader reads one dataset per time step from a PVD collection.

Both readers can expose multiple arrays from the same source file.

`VTKStaticReader`#

Use VTKStaticReader when the input file represents a static state, for example start conditions or a geometry with attached variables.

from finam_vtk import DataArray, VTKStaticReader

reader = VTKStaticReader(
    "examples/data/test2.vtu",
    outputs=[DataArray("HEAD", units="m")],
)

`PVDReader`#

Use PVDReader when the source is a PVD time series. FINAM timestamps are derived from the PVD time values together with a reference date and time unit.

from datetime import datetime
from finam_vtk import DataArray, PVDReader

start = datetime(2024, 5, 1, 0, 0, 0)
reader = PVDReader(
    "examples/data/test.pvd",
    reference_date=start,
    time_unit="seconds",
    outputs=[DataArray("HEAD", units="m")],
)

When multiple arrays are requested, they must all be available at the same PVD time steps.

Outputs#

Component outputs are addressed by the declared array names, for example when linking a reader to another FINAM component:

reader["HEAD"] >> target["head"]

Writers#

The package exports three writer classes:

VTKStaticWriter writes one VTK dataset from static inputs.
PVDTimedWriter writes a sequence of VTK files plus a matching PVD file.
PVDPushWriter writes a PVD series whenever all connected inputs push data for the same timestamp.

`VTKStaticWriter`#

Use VTKStaticWriter for one-off output files. The writer chooses the VTK file extension from the incoming FINAM grid unless legacy=True is requested.

from finam_vtk import DataArray, VTKStaticWriter

writer = VTKStaticWriter(
    "out/static_head",
    inputs=[DataArray("head", units="m")],
)

`PVDTimedWriter`#

Use PVDTimedWriter to write time-indexed VTK output in fixed FINAM intervals together with a .pvd collection file.

from datetime import timedelta
from finam_vtk import DataArray, PVDTimedWriter

writer = PVDTimedWriter(
    "out/head_series.pvd",
    inputs=[DataArray("head", units="m")],
    step=timedelta(hours=1),
    time_unit="seconds",
)

`PVDPushWriter`#

Use PVDPushWriter when the upstream components already control the time steps and push new data as soon as it becomes available. All connected inputs must push for the same timestamps.

from finam_vtk import DataArray, PVDPushWriter

writer = PVDPushWriter(
    "out/head_push.pvd",
    inputs=[DataArray("head", units="m")],
    time_unit="seconds",
)

Helpers#

The most commonly used helper objects are:

DataArray to declare variable names, associations, units, and optional metadata.
read_vtk_grid() to derive a FINAM grid from an existing VTK file.
read_aux_file() to read the JSON sidecar written by PVDTimedWriter.
finam_vtk.tools for lower-level conversion and time-handling utilities.

from finam_vtk import read_aux_file, read_vtk_grid

grid = read_vtk_grid("examples/data/test1.vtu")
aux = read_aux_file("out/head_series.json")

API References#

Information about the API of FINAM-VTK.

API reference

About#

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

About