rajkmsaini/gridformat

GridFormat is a header-only C++ library for writing data into grid file formats that can be visualized with tools such as ParaView. The typical use case for GridFormat is within codes for numerical simulations that want to export numerical results into visualizable file formats. A variety of simulation frameworks exist, such as Dune, DuMuX, Deal.II, Fenics or MFEM, which usually provide mechanisms to export data produced with the framework into some file formats. However, there are situations in which one wants to use a format that the framework does not support, or, use some features of the format specification that are not implemented in the framework. GridFormat aims to provide access to a variety of file formats through a unified interface and without the need to convert any data or to use a specific data structure to represent computational grids. Using generic programming and traits classes, GridFormat fully operates on the user-given data structures, thereby minimizing the runtime overhead. GridFormat also supports writing files from parallel computations that use MPI. Ideally, simulation frameworks use GridFormat under-the-hood to avoid duplicate implementation efforts, and implement support for new formats into GridFormat such that they are directly available to all other frameworks that utilize it.

Quick Start

Prerequisites:

C++-compiler with C++-20-support (tests run with gcc-12/13, clang++-16)
cmake (tests run with cmake-3.26)

It is easiest to integrate GridFormat either as a git submodule or via the FetchContent module of cmake. A minimal example (using FetchContent) of a project using GridFormat to write a VTU file may look like this:

cmake_minimum_required(VERSION 3.22)
project(some_app_using_gridformat)

include(FetchContent)
FetchContent_Declare(
    gridformat
    GIT_REPOSITORY https://github.com/dglaeser/gridformat
    GIT_TAG main
    GIT_PROGRESS true
    GIT_SHALLOW true
    GIT_SUBMODULES_RECURSE OFF
)
FetchContent_MakeAvailable(gridformat)

add_executable(my_app my_app.cpp)
target_link_libraries(my_app PRIVATE gridformat::gridformat)

#include <array>
#include <gridformat/gridformat.hpp>

double f(const std::array<double, 2>& x) { return x[0]*x[1]; }

int main () {
    // For this example we have no user-defined grid type. Let's just use a predefined one...
    GridFormat::ImageGrid<2, double> grid{
        {1.0, 1.0}, // domain size
        {10, 12}    // number of cells (pixels) in each direction
    };

    // This shows the `GridFormat` API: Construct a writer for the desired format, and add
    // point/cell fields as lambdas. Metadata can be added directly and can be ranges or scalars.
    GridFormat::Writer writer{GridFormat::vtu, grid};
    writer.set_meta_data("some_metadata", "i am metadata");
    writer.set_point_field("point_field", [&] (const auto& point) { return f(grid.position(point)); });
    writer.set_cell_field("cell_field", [&] (const auto& cell) { return f(grid.center(cell)); });
    writer.write("my_test_file");  // the file extension will be appended by the writer

    return 0;
}

Many more formats and options are available, see the API documentation or have a look at the examples.

Installation

The recommended way of using GridFormat is to include it via cmake's FetchContent module (see quickstart). However, if you want to install GridFormat locally into a custom location, clone the repository, enter the folder and type

cmake -DCMAKE_INSTALL_PREFIX=$(pwd)/install \
      -DCMAKE_C_COMPILER=/usr/bin/gcc-12 \
      -DCMAKE_CXX_COMPILER=/usr/bin/g++-12 \
      -B build
cmake --install build

Note that you can omit the explicit definition of C_COMPILER and CXX_COMPILER in case your default compiler is compatible. Moreover, for a system-wide installation you may omit the definition of CMAKE_INSTALL_PREFIX. After installation, you can use cmake to link against GridFormat in your own project:

find_package(gridformat)
target_link_libraries(... gridformat::gridformat)

Dependencies

GridFormat has no required dependencies, however, some features are only available if certain dependencies are present. For instance, the VTK-HDF file formats are only available if HighFive is found, which itself requires libhdf5-dev. If the latter is found on your system, including GridFormat via cmake's FetchContent (see quickstart) automatically brings in HighFive, as it is included in GridFormat as a git submodule. However, when installing GridFormat from the cloned sources (as described above), make sure to use git clone --recursive in case you want to use the HDF file formats.

The availability of some specific features of a file format may also depend on the availability of certain dependencies. For instance, compression of data (e.g. for the VTK-XML file formats) can only be used if the respective compression libraries are found on the system. Dependencies of those features are stated in the API documentation.

Compatibility with user-defined grids

GridFormat does not operate on a specific grid data structure, but instead, it can be made compatible with any user-defined grid types by implementing specializations for a few traits classes. For information on how to do this, please have a look at the traits classes overview, the examples, the predefined image grid implementation or the predefined traits for several frameworks.

Predefined traits

GridFormat comes with predefined traits for dune grid views (tested dune version: 2.9), deal.ii triangulations (tested deal.ii version: 9.4.0), cgal triangulations in 2d and 3d (tested cgal version: 5.5.2), dolfinx meshes and function spaces (tested dolfinx version: 0.6.0) and mfem meshes (tested mfem version: 4.5.2). Users of these frameworks can include these predefined traits and use GridFormat directly (see the examples).

Contribution Guidelines

Contributions are highly welcome! For bug reports, please file an issue. If you want to contribute with features, improvements or bug fixes please fork this project and open a merge request into the main branch of this repository.

Development and test suite

In order to configure your local copy for testing, tell cmake to include the test suite:

# Note: you may have to set a compiler explicitly (see installation section)
cmake -DGRIDFORMAT_BUILD_TESTS=ON -B build

Afterwards, you can build and run all tests with ctest:

# Note: use, e.g., ctest -j4 if you want to use 4 processors
cd build
make build_tests
ctest

Note that an internet connection is required for the call to cmake as it pulls in ut on-the-fly.

License

GridFormat is licensed under the terms and conditions of the MIT License. It can be read online or in the LICENSES/MIT.txt file. See LICENSES/MIT.txt for full copying permissions.

rajkmsaini / gridformat