Nektar++

Users of this software are expected to have generated datasets using Nektar++.

Nektar++ Best Practices

A Nektar++ simulation dataset following best practices must consist of at least:

  • session.xml - Session file in XML format

  • geometry.nekg - Geometry file in HDF5 format

  • output.fld - Output file in HDF5 format

It can optionally have:

  • checkpoint.chk - Checkpoint files in HDF5 format

  • filter.fce - Filter files in HDF5 format

Supporting items to the dataset can include:

  • Images (*jpg,*png)

  • Research Papers (*.pdf)

Since Nektar++ v5.0.0, there has been full HDF5 support for geometry and output files. HDF5 files provide many benefits over the traditional XML format for geometry and output. XML files are inefficient to load into memory. The entire file is often loaded into the program’s memory before it can be parsed and used. With HDF5, many readers support memory mapping, which allows for faster read access. Moreover, range loading is supported, so only relevant sections of the file have to be loaded in. Parallel I/O is also supported.

Therefore, there is a shift from XML file formats towards HDF5 where applicable, and this software will enforce these best practices.

Converting files

For legacy simulation datasets that follow the old Nektar++ best practices, where all files are in plain XML format with the geometry encoded as an Endian, conversion is necessary. NekUpload does not provide tools to automate the conversion process, so users must convert files themselves. This is a conscious design decision to encourage users to become more familiar with the HDF5-format.

Nektar++ provides the NekMesh and FieldConvert commands that can be used to convert files from XML format to HDF5 format. FieldConvert is part of the Nektar++ installation. HDF5 support and MPI support must be enabled if building Nektar++ from source.

Obtaining geometry.nekg

In XML format, the geometry is sometimes nested inside session.xml, or can be in a separate geometry.xml file. To obtain a geometry.nekg file utilise the following command:

#if geometry is within session file
NekMesh session.xml HDF5geometry.nekg

#if geometry is separate to session file
nekupload mergexml session.xml geometry.xml merged_session.xml
NekMesh merged_session.xml HDF5geometry.nekg

This will generate two files: HDF5geometry.xml (the new session file) and HDF5geometry.nekg (the new geometry file). An additional flag in the session file is required, ensuring it is placed before the expansion list being:

1    <GEOMETRY DIM="3" SPACE="3" HDF5FILE="HDF5Mesh.nekg" />

For more info, see Section 4.5.2.1 of the Nektar User Guide

Note

NekMesh only accepts one input file for converting xml to nekg. To workaround this, this package provides a CLI nekupload. nekupload mergexml file1 file2 output will merge the two stated files, and any repeated first level elements are replaced with the one specified in file2. This is the standard Nektar++ behaviour when multiple input files are detected for a solver e.g. ADRSolver file1.xml file2.xml file1 and file2 are merged as per the previously stated rule. The new merged XML file can then be used with NekMesh as usual.

Warning

Order of files specified is important in nekupload. First-level elements, such as <EXPANSIONS>, in first file will be replaced by the one defined in second file if present. Otherwise, appended. Formatting may be screwed up a little, so always double check files afterwards.

Obtaining HDF5 Filter, Checkpoint & Output files

Convert fld files using:

FieldConvert in.fld out.fld:fld:format=Hdf5

Convert chk files using:

FieldConvert in.chk out.chk:chk:format=Hdf5

This will convert the in file and create and out file. out should be named same as in.

TBC for his

For more info see Section 5.3 of the Nektar User Guide