Skip to content

Doxygen HDF5 #5231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
WeiqunZhang wants to merge 2 commits into
base: development
Choose a base branch
from
Open

Doxygen HDF5 #5231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
021c25a
Doxygen HDF5
WeiqunZhang Feb 23, 2026
6c23964
update
WeiqunZhang Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions Src/Extern/HDF5/AMReX_ParticleUtilHDF5.H
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,18 @@

namespace amrex {

/**
* \file AMReX_ParticleUtilHDF5.H
*
* Async-HDF5 helpers shared by the particle checkpoint/write routines.
*/

//! Global async VOL event-set used to synchronize particle HDF5 I/O.
hid_t es_par_g = 0;

/**
* \brief Block until all pending particle async VOL operations complete.
*/
void async_vol_es_wait_particle()
{
size_t num_in_progress;
Expand All @@ -17,6 +27,9 @@ void async_vol_es_wait_particle()
return;
}

/**
* \brief Wait for pending async VOL work and destroy the shared event-set.
*/
void async_vol_es_wait_close_particle()
{
size_t num_in_progress;
Expand Down
59 changes: 59 additions & 0 deletions Src/Extern/HDF5/AMReX_ParticlesHDF5.H
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
#ifndef AMREX_PARTICLES_HDF5_H_
#define AMREX_PARTICLES_HDF5_H_

/**
* \file AMReX_ParticlesHDF5.H
*
* HDF5-specific ParticleContainer hooks (checkpointing, plotfile output, and
* supporting helpers shared by all particle types).
*/

public:
/**
* \brief Write a contiguous chunk of real particle data to an HDF5 file.
Expand Down Expand Up @@ -32,6 +39,13 @@ public:

/**
* \brief Writes a particle checkpoint to file, suitable for restarting.
*
* \param dir Directory that owns the per-type subdirectory.
* \param name Particle type subdirectory (e.g., "Tracer").
* \param is_checkpoint Reserved for parity with ASCII checkpoints (ignored because HDF5 always writes id/cpu).
* \param real_comp_names Optional labels for each real component.
* \param int_comp_names Optional labels for each integer component.
* \param compression Compression scheme, e.g., `"ZFP_ACCURACY@0.001"`.
*/
void CheckpointHDF5 (const std::string& dir, const std::string& name, bool is_checkpoint,
const Vector<std::string>& real_comp_names = Vector<std::string>(),
Expand Down Expand Up @@ -64,8 +78,20 @@ public:
F&& f, bool is_checkpoint=false) const;


/**
* \brief Prepare metadata used by deferred HDF5 checkpoint writes.
*
* Tallies particles/NextID values per level so CheckpointPostHDF5() can
* finish the header without revisiting particle data.
*/
void CheckpointPreHDF5 ();

/**
* \brief Finalize a checkpoint header handed off by CheckpointPreHDF5().
*
* Aggregates distributed offsets/counts, appends per-level bookkeeping,
* and removes empty per-file fragments when requested.
*/
void CheckpointPostHDF5 ();

/**
Expand Down Expand Up @@ -264,10 +290,30 @@ public:
const std::string& compression,
F&& f) const;

/**
* \brief Plotfile-friendly alias for CheckpointPreHDF5().
*/
void WritePlotFilePreHDF5 ();

/**
* \brief Plotfile-friendly alias for CheckpointPostHDF5().
*/
void WritePlotFilePostHDF5 ();

/**
* \brief Write all particles from one AMR level into the given HDF5 group.
*
* \param level AMR level whose particles are written.
* \param grp Open HDF5 group corresponding to `level_%d`.
* \param which Placeholder vector kept for API compatibility (unused by the HDF5 backend).
* \param count Per-grid particle counts updated in place.
* \param where Placeholder vector kept for API compatibility (unused by the HDF5 backend).
* \param write_real_comp Flags enabling each real component.
* \param write_int_comp Flags enabling each integer component.
* \param compression Compression string (`ZFP_*`, `SZ`, etc.).
* \param particle_io_flags Per-grid/tile masks returned by the filter functor.
* \param is_checkpoint Reserved; the HDF5 writer always preserves id/cpu regardless of this flag.
*/
void
WriteParticlesHDF5 (int level, hid_t grp,
Vector<int>& which, Vector<int>& count, Vector<Long>& where,
Expand All @@ -277,6 +323,19 @@ public:

protected:

/**
* \brief Read particle records from HDF5 datasets into a level/tile buffer.
*
* \tparam RTYPE Floating-point storage type stored in the file.
* \param offset Starting element offset inside the dataset.
* \param count Number of entries to load.
* \param grd Grid index being populated.
* \param lev AMR level index being populated.
* \param int_dset HDF5 dataset handle for integer components.
* \param real_dset HDF5 dataset handle for real components.
* \param finest_level_in_file Finest level encoded in the file (for sanity checks).
* \param convert_ids True when reading `Version_Two_Dot_One` checkpoints whose 64-bit id/cpu pairs were split into two 32-bit words and must be reassembled.
*/
template <class RTYPE>
void ReadParticlesHDF5 (hsize_t offset, hsize_t count, int grd, int lev, hid_t int_dset, hid_t real_dset, int finest_level_in_file, bool convert_ids);

Expand Down
102 changes: 102 additions & 0 deletions Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.H
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,30 @@
#include <string>
#include <memory>

/**
* \file AMReX_PlotFileUtilHDF5.H
*
* HDF5-backed plotfile writers mirroring the ASCII/Binary interfaces.
*/

namespace amrex
{

/**
* \brief Write a single-level plotfile (one dataset per level).
*
* \param plotfilename Output directory (e.g., `"plt00000"`).
* \param mf MultiFab whose data are stored.
* \param varnames Names assigned to each component of \p mf.
* \param geom Geometry describing the level.
* \param t Simulation time stored in the header.
* \param level_step Level timestep counter.
* \param compression Compression descriptor (e.g., `"ZFP_RATE@4"`).
* \param versionName Metadata version string written to the header.
* \param levelPrefix Directory prefix used for each level (default `Level_`).
* \param mfPrefix Dataset prefix describing the MultiFab type.
* \param extra_dirs Optional sibling directories to create alongside the plotfile.
*/
void WriteSingleLevelPlotfileHDF5 (const std::string &plotfilename,
const MultiFab &mf,
const Vector<std::string> &varnames,
Expand All @@ -26,6 +47,23 @@ namespace amrex
const std::string &mfPrefix = "Cell",
const Vector<std::string>& extra_dirs = Vector<std::string>());

/**
* \brief Write a multi-level plotfile (one dataset per level).
*
* \param plotfilename Output directory (e.g., `"plt00000"`).
* \param nlevels Number of AMR levels provided.
* \param mf Vector of levelwise MultiFabs (component counts must match).
* \param varnames Names assigned to each component.
* \param geom Vector of per-level geometries.
* \param time Simulation time stored in the header.
* \param level_steps Per-level timestep counters.
* \param ref_ratio Refinement ratios between levels (fine/coarse).
* \param compression Compression descriptor (e.g., `"None@0"`).
* \param versionName Metadata version string written to the header.
* \param levelPrefix Directory prefix used for each level.
* \param mfPrefix Dataset prefix describing the MultiFab type.
* \param extra_dirs Optional sibling directories to create alongside the plotfile.
*/
void WriteMultiLevelPlotfileHDF5 (const std::string &plotfilename,
int nlevels,
const Vector<const MultiFab*> &mf,
Expand All @@ -40,6 +78,21 @@ namespace amrex
const std::string &mfPrefix = "Cell",
const Vector<std::string>& extra_dirs = Vector<std::string>());

/**
* \brief Write a single-level plotfile where all state lives in one dataset.
*
* \param plotfilename Output directory (e.g., `"plt00000"`).
* \param mf MultiFab whose data are stored.
* \param varnames Names assigned to each component of \p mf.
* \param geom Geometry describing the level.
* \param t Simulation time stored in the header.
* \param level_step Level timestep counter.
* \param compression Compression descriptor (e.g., `"ZFP_RATE@4"`).
* \param versionName Metadata version string written to the header.
* \param levelPrefix Directory prefix used for each level (default `Level_`).
* \param mfPrefix Dataset prefix describing the MultiFab type.
* \param extra_dirs Optional sibling directories to create alongside the plotfile.
*/
void WriteSingleLevelPlotfileHDF5SingleDset (const std::string &plotfilename,
const MultiFab &mf,
const Vector<std::string> &varnames,
Expand All @@ -52,6 +105,23 @@ namespace amrex
const std::string &mfPrefix = "Cell",
const Vector<std::string>& extra_dirs = Vector<std::string>());

/**
* \brief Write a multi-level plotfile using a single dataset per level.
*
* \param plotfilename Output directory (e.g., `"plt00000"`).
* \param nlevels Number of AMR levels provided.
* \param mf Vector of levelwise MultiFabs (component counts must match).
* \param varnames Names assigned to each component.
* \param geom Vector of per-level geometries.
* \param time Simulation time stored in the header.
* \param level_steps Per-level timestep counters.
* \param ref_ratio Refinement ratios between levels (fine/coarse).
* \param compression Compression descriptor (e.g., `"None@0"`).
* \param versionName Metadata version string written to the header.
* \param levelPrefix Directory prefix used for each level.
* \param mfPrefix Dataset prefix describing the MultiFab type.
* \param extra_dirs Optional sibling directories to create alongside the plotfile.
*/
void WriteMultiLevelPlotfileHDF5SingleDset (const std::string &plotfilename,
int nlevels,
const Vector<const MultiFab*> &mf,
Expand All @@ -66,6 +136,21 @@ namespace amrex
const std::string &mfPrefix = "Cell",
const Vector<std::string>& extra_dirs = Vector<std::string>());

/**
* \brief Write a single-level plotfile with one HDF5 dataset per component.
*
* \param plotfilename Output directory (e.g., `"plt00000"`).
* \param mf MultiFab whose data are stored.
* \param varnames Names assigned to each component of \p mf.
* \param geom Geometry describing the level.
* \param t Simulation time stored in the header.
* \param level_step Level timestep counter.
* \param compression Compression descriptor (e.g., `"ZFP_RATE@4"`).
* \param versionName Metadata version string written to the header.
* \param levelPrefix Directory prefix used for each level (default `Level_`).
* \param mfPrefix Dataset prefix describing the MultiFab type.
* \param extra_dirs Optional sibling directories to create alongside the plotfile.
*/
void WriteSingleLevelPlotfileHDF5MultiDset (const std::string &plotfilename,
const MultiFab &mf,
const Vector<std::string> &varnames,
Expand All @@ -78,6 +163,23 @@ namespace amrex
const std::string &mfPrefix = "Cell",
const Vector<std::string>& extra_dirs = Vector<std::string>());

/**
* \brief Write a multi-level plotfile with one dataset per component.
*
* \param plotfilename Output directory (e.g., `"plt00000"`).
* \param nlevels Number of AMR levels provided.
* \param mf Vector of levelwise MultiFabs (component counts must match).
* \param varnames Names assigned to each component.
* \param geom Vector of per-level geometries.
* \param time Simulation time stored in the header.
* \param level_steps Per-level timestep counters.
* \param ref_ratio Refinement ratios between levels (fine/coarse).
* \param compression Compression descriptor (e.g., `"None@0"`).
* \param versionName Metadata version string written to the header.
* \param levelPrefix Directory prefix used for each level.
* \param mfPrefix Dataset prefix describing the MultiFab type.
* \param extra_dirs Optional sibling directories to create alongside the plotfile.
*/
void WriteMultiLevelPlotfileHDF5MultiDset (const std::string &plotfilename,
int nlevels,
const Vector<const MultiFab*> &mf,
Expand Down
62 changes: 62 additions & 0 deletions Src/Extern/HDF5/AMReX_WriteBinaryParticleDataHDF5.H
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,25 @@
#ifndef AMREX_WRITE_BINARY_PARTICLE_DATA_HDF5_H
#define AMREX_WRITE_BINARY_PARTICLE_DATA_HDF5_H

/**
* \file AMReX_WriteBinaryParticleDataHDF5.H
*
* Low-level helpers that implement ParticleContainer HDF5 checkpoint/plotfile
* output (attribute helpers, FAPL configuration, and the synchronous writer).
*/

namespace amrex {

/**
* \brief Create and write a numeric attribute on the given HDF5 object.
*
* \param loc HDF5 object on which to store the attribute.
* \param name Attribute name.
* \param n Number of entries (for vector-valued attributes).
* \param data Pointer to the values written to the attribute.
* \param dtype HDF5 datatype describing \p data.
* \return 1 on success, -1 on error (message already printed).
*/
static int CreateWriteHDF5Attr(hid_t loc, const char *name, hsize_t n, void *data, hid_t dtype)
{
herr_t ret;
Expand Down Expand Up @@ -30,6 +47,14 @@ static int CreateWriteHDF5Attr(hid_t loc, const char *name, hsize_t n, void *dat
return 1;
}

/**
* \brief Create and write a null-terminated string attribute on the given object.
*
* \param loc HDF5 object on which to store the attribute.
* \param name Attribute name.
* \param str Null-terminated string copied into the attribute.
* \return 1 on success, -1 on error.
*/
static int CreateWriteHDF5AttrString(hid_t loc, const char *name, const char* str)
{
hid_t attr, atype, space;
Expand Down Expand Up @@ -61,6 +86,15 @@ static int CreateWriteHDF5AttrString(hid_t loc, const char *name, const char* st
return 1;
}

/**
* \brief Read an attribute from an HDF5 object into the supplied buffer.
*
* \param loc HDF5 object that owns the attribute.
* \param name Attribute name.
* \param data Destination buffer.
* \param dtype Datatype used for the read.
* \return 1 on success, -1 on error.
*/
static int ReadHDF5Attr(hid_t loc, const char *name, void *data, hid_t dtype)
{
herr_t ret;
Expand All @@ -82,8 +116,19 @@ static int ReadHDF5Attr(hid_t loc, const char *name, void *data, hid_t dtype)
}

#ifdef AMREX_USE_MPI
/**
* \brief Configure a file-access property list for parallel particle writes.
*
* \param fapl Property list modified in place.
* \param comm MPI communicator spanning the writing ranks.
*/
static void SetHDF5fapl(hid_t fapl, MPI_Comm comm)
#else
/**
* \brief Configure a serial file-access property list for particle writes.
*
* \param fapl Property list modified in place.
*/
static void SetHDF5fapl(hid_t fapl)
#endif
{
Expand Down Expand Up @@ -116,6 +161,23 @@ static void SetHDF5fapl(hid_t fapl)
#endif

}
/**
* \brief Synchronous HDF5 particle writer shared by checkpoint and plotfile routines.
*
* \tparam PC ParticleContainer-like type.
* \tparam F Predicate that returns true for particles that should be written.
*
* \param pc Particle container whose data are written.
* \param dir Base directory (plotfile or checkpoint root).
* \param name Particle subdirectory/file stem.
* \param write_real_comp Flags enabling each real component.
* \param write_int_comp Flags enabling each integer component.
* \param real_comp_names Labels for each enabled real component.
* \param int_comp_names Labels for each enabled integer component.
* \param compression Compression descriptor (e.g., `"ZFP_RATE@4"`).
* \param f Predicate that filters individual particles.
* \param is_checkpoint True when ids/cpus are required for restarts.
*/
template <class PC, class F, std::enable_if_t<IsParticleContainer<PC>::value, int> foo = 0>
void WriteHDF5ParticleDataSync (PC const& pc,
const std::string& dir, const std::string& name,
Expand Down
Loading