vtk_readers.rst 3.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
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
:doc:`how to use ParaView </cookbook/2-paraview/tutorial>`. 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 <https://pypi.org/project/vtk/>`_.

.. contents::
   :depth: 2
   :local:


Prerequisites
=============

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
21
the :doc:`ReadMe </markdown/README>`, you are already set and can start
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
using them inside the :ref:`virtual environment <cli-venv>`.

If you install the DORiE Python package separately, you may need to install the
required VTK library, depending on your operating system. **Ubuntu** users need
to install ``python-vtk`` via

.. code-block:: console

    apt-get install python-vtk


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.

.. code-block:: python

    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
    print(pvd_reader.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
        print(water_content.evaluate(center))


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.

.. note:: 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
          :class:`dorie.utilities.vtktools.vtkreader.PVDReader` to load all VTK
          files of a simulation run and access their times.

.. autoclass:: dorie.utilities.vtktools.vtkreader.VTKReader
    :members:
    :inherited-members:

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

.. autoclass:: dorie.utilities.vtktools.vtkreader.VTKDataArray
   :members:

DORiE writes PVD files containing references to the VTK file(s) stored for
every time step, and the associated simulation time. The ``PVDReader`` stores
a sequence of :class:`dorie.utilities.vtktools.vtkreader.VTKReader` for these
files and orders them by time.

.. autoclass:: dorie.utilities.vtktools.vtkreader.PVDReader
   :members: