README

This repository gives examples of how to use ParaView Catalyst (www.paraview.org/in-situ)
for in situ analysis and visualization. For assistance, please visit the Discourse page
at discourse.paraview.org. The examples show how to create VTK data
structures from native simulation code data structures, how to interface to ParaView
Catalyst and how to set up several different types of pipelines. As of ParaView 5.7
the examples must be built as a group. Users should point CMake to this directory in
order to build. Many of the examples work in parallel as well. The tests
are very simple and just verify that the examples run -- they do not verify
correctness of outputs. A description of the examples are:
* FortranPoissonSolver -- An example of a parallel, finite difference discretization of the Poisson equation
                          implemented in Fortran using a Conjugate Gradient solver. Instead of co-processing
                          at the end of each time step it co-processes at the end of each iteration.
* Fortran90FullExample -- An example of a simulation code written in Fortran
                          that is linked with Catalyst.
* CFullExample -- An example of a simulation code written in C. This uses some
                  methods from Catalyst for storing VTK data structures. This
                  assumes a vtkUnstructuredGrid.
* CFullExample2 -- An example of a simulation code written in C. This improves
                   upon the CFullExample by explicitly storing VTK data structures.
                   This assumes a vtkUnstructuredGrid.
* CxxFullExample -- A C++ example of a simulation code interfacing with Catalyst.
                    This assumes a vtkUnstructuredGrid.
* PythonFullExample -- An example of a simulation code written in Python
                       that uses Catalyst.
* PythonDolfinExample -- An example that uses the Dolfin simulation code.
* CxxImageDataExample -- A C++ example of a simulation code interfacing with
                         Catalyst. The grid is a vtkImageData.
* CxxMultiPieceExample -- A C++ example of a simulation code interfacing with
                          Catalyst. The grid is a vtkMultiPiece data set with
                          a single vtkImageData for each process.
* CxxNonOverlappingAMRExample -- A C++ example of a simulation code interfacing with
                                 Catalyst. The grid is a vtkNonOverlappingAMR.h
                                 data set.
* CxxOverlappingAMRExample -- A C++ example of a simulation code interfacing with
                              Catalyst. The grid is a vtkOverlappingAMR.h
                              data set.
* CxxPVSMPipelineExample -- An example where we manually create a Catalyst
                            pipeline in C++ code using ParaView's server-manager.
                            This example can be run without ParaView being built
                            with Python.
* CxxVTKPipelineExample -- An example where we manually create a Catalyst
                           pipeline in C++ code using VTK filters.
                           This example can be run without ParaView being built
                           with Python.
* CxxMappedDataArrayExample -- An example of an adaptor where we use VTK mapped
                               arrays to map simulation data structures to
                               VTK data arrays to save on memory use by Catalyst.
                               Note that this example is deprecated as of
                               ParaView 5.1 in favor of the CxxSOADataArrayExample.
* MPISubCommunicatorExample -- An example where only a subset of the MPI
                               processes are used for the simulation and Catalyst.
* CxxParticlePathExample -- An example for computing particle paths in situ.
* CxxSOADataArrayExample -- An example of an adaptor where we use
                            vtkSOADataArrayTemplate to reuse simulation memory
                            for VTK field arrays.
* CxxMultiChannelInputExample -- An example that has two adaptor channels/inputs.
                                 The first is an unstructured volumetric grid
                                 with the "volumetric grid" identifier and the
                                 second is a particle grid with the "particles"
                                 identifier. It is tested with the allinputsgridwriter.py
                                 Catalyst Python pipeline script available under the
                                 SampleScripts subdirectory.
* CxxGhostCellsExample -- An example where Catalyst is passed in ghost levels.
                          This example is meant to be used as an example of how
                          Catalyst deals with ghost cells for an unstructured grid
                          or an image data. This example requires a Catalyst build.
* CxxHyperTreeGridExample -- An example where a vtkHyperTreeGrid is produced.

Other objects of interest:
* LICENSE.md -- The license of this software.
* SampleScripts -- A directory with some useful sample Catalyst Python pipelines.
                   The scripts are gridwriter.py and allinputsgridwriter.py which
                   write out the full dataset/s at a given output frequency specified
                   by the outputfrequency variable in each script. This can be useful
                   for creating other Catalyst Python pipelines with the Catalyst Script
                   Generator plugin in the ParaView GUI. gridwriter.py assumes that
                   there is a single adaptor channel/input that uses the "input"
                   identifier. allinputsgridwriter.py will write out all adaptor
                   channel/inputs. Both of these scripts will automatically set
                   the filename based on the channel/inputs identifier string. For
                   example, for gridwriter.py which assumes the "input" identifier
                   string the generated datasets will be called
                   "input_<time step>.<file extension>". The file extension is
                   automatically specified based on the dataset type (e.g. polydata,
                   unstructured grid, etc.).
* CMakeLists.txt -- The file used to build all of the examples in a single shot.