Generic VTK File Readers

For an interactive inspection and analysis of the VTK files written by DORiE we recommend using ParaView. For more information, learn how to use ParaView. More detailed analyses typically require more complex operations on the data which is likely easier in Python. The DORiE Python module provides facilities based on the VTK Python module.


For using the modules and classes listed below, users need to install a set of required software packages. If you followed the installation instructions in the ReadMe, you are already set and can start using them inside the virtual environment.

If you install the DORiE Python package separately, you may need to install additional prerequisites for the VTK library, depending on your operating system. Linux users need to install the OpenGL library. On Ubuntu and similar systems, call

apt install libgl-dev

Example Code

This example code loads the resulting PVD file of a DORiE simulation, reports the simulation times for which files are available and prints the water content at the center of the domain for every file.

from dorie.utilities.vtktools.vtkreader import PVDReader

# Load the PVD file written by a DORiE simulation run
pvd_reader = PVDReader("result.pvd")

# Report the times

# Iterate over the output files
# NOTE: `dataset` is an instance of `VTKReader`
for dataset in pvd_reader:
    # Retrieve time from file directly
    time = dataset.time

    # Fetch the water content data array
    # NOTE: `water_content` is an instance of `VTKDataArray`
    water_content = dataset["theta_w"]

    # Compute the center of the domain
    center = np.mean(water_content.bounds, axis=1)

    # Report the water content at this location

Source Code Documentation

This is a flexible VTK XML file reader which can evaluate all data sets written by DORiE. It is derived from the abstract base class Mapping and thus supports accessing the data arrays stored inside like a Python dict. Use the data array names as keys.


VTK files do not store time inherently. When loading a file directly using the VTKReader, the time attribute will be set to None. Use the dorie.utilities.vtktools.vtkreader.PVDReader to load all VTK files of a simulation run and access their times.

class dorie.utilities.vtktools.vtkreader.VTKReader(file_name, time=None)[source]

A generic VTK reader for any type of VTK XML files.

It maps the data array names to data array evaluators, see VTKDataArray. Use it like any Python dict.


VTK files separately store vertex (point) and cell data and associate the data arrays by their names. If the loaded file contains one array of each type with the same name, the vertex (point) array takes precedence. The cell array cannot be accessed! The key sequence will contain the name twice, but the associated value will be the vertex data set in both cases.

  • file_name (str) – Name of the VTK file to open. Any VTK file in XML format is supported.

  • time (float, optional) – Time associated with the VTK file. Defaults to None.


The absolute path to the VTK file. Used for comparing two instances of VTKReader.




The time associated with the VTK file, if any.




Generic VTK XML data file reader.


The complete data set loaded by the reader.


Fast locator of grid cells based on global coordinates.


Pointer to the VTK point data arrays.


Pointer to the VTK cell data arrays.

property bounds

The rectangular bounds of the dataset grid in any spatial direction. This value is shared among all VTKDataArray objects retrieved from this instance.


np.array, shape (3, 2)

get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
values() an object providing a view on D's values

The VTKReader returns instances of VTKDataArray, which is a wrapper around the underlying VTK data array.

class dorie.utilities.vtktools.vtkreader.VTKDataArray(dataset, locator, data_array, data_type)[source]

Wrapper for evaluating a VTK data array


Outer bounds of the grid this data array lives on.


np.array, shape (3, 2)


Evaluate the selected data array at a certain position.


position (list) – 3D coordinate probing the data array.


The value of the data array at the given position.

The output is squeezed: Scalar data arrays return scalar values, vector arrays return numpy arrays with shape (3).

Return type


  • ValueErrorposition argument not a 3D list or array.

  • ValueError – Position outside grid.

  • RuntimeError – Numerical error in cell locator algorithm.

property number_of_components

Number of components of the evaluated quantity.

DORiE writes PVD files containing references to the VTK file(s) stored for every time step, and the associated simulation time. The PVDReader stores these references and orders them by time. If accessed, it returns instances of dorie.utilities.vtktools.vtkreader.VTKReader for each referenced file.

class dorie.utilities.vtktools.vtkreader.PVDReader(file_path, throw_on_missing=False)[source]

This class reads a PVD file and stores the referenced VTK file paths and their respective time stamps. Use this object like a list of VTKReader.

The VTK files are guaranteed to be ordered with respect to time, regardless of their actual order in the PVD file.


To avoid excessive RAM loads, this class initializes VTKReader instances lazily. They are only instantiated when they are actually requested by the user through an access operator. Users will have to keep/store VTKReader instances if they want to switch between several files often.

  • file_path (str) – Path to the PVD file to open.

  • throw_on_missing (bool, optional) – Throw immediately if a referenced file does not exist. Defaults to False, in which case a warning is issued. If the referenced file does not exist, retrieving the respective VTKReader will throw inevitably.

  • FileNotFoundError – PVD file at file_path does not exist.

  • IOError – PVD file has unknown XML structure.

  • FileNotFoundError – VTK file referenced by the PVD file does not exist (only if throw_on_missing is True).


Tuples of time stamp and VTK file path.



property times

The times associated with the stored VTK files.


iterable of float