Ext: PatchBasedMeshRefinement by ax3l · Pull Request #252 · openPMD/openPMD-standard

ax3l · 2021-03-09T07:45:51Z

Adds a simple convention for patch based mesh refinement.

Description

This adds a naming convention to efficiently identify levels of a refined mesh.

Affected Components

base (cosmetic)
EXT: PatchBasedMeshRefinement

Logic Changes

Adds a naming convention through record suffixes for meshes that can be used to identify refined meshes.

Allows two ways to store a refined mesh: through one record per refinement level (e.g. for ADIOS) or through one record per refinement level and patch (for non-contiguous refinements).

Writer Changes

A writer can suffix the meshes to express levels.

openPMD-api: https://github.com/openPMD/openPMD-api
WarpX: openPMD: Support for mesh refinement BLAST-WarpX/warpx#1842

Reader Changes

A reader can group mesh-refined records visually or build an MR structure.

Good candidates:

yt: https://github.com/yt-project/yt
ParaView: ...

Unaffected for now:

openPMD-validator: https://github.com/openPMD/openPMD-validator
openPMD-viewer: https://github.com/openPMD/openPMD-viewer
VisIt: https://github.com/openPMD/openPMD-visit-plugin
converter: https://github.com/openPMD/openPMD-converter
openPMD-api: https://github.com/openPMD/openPMD-api

Data Updater

New functionality. No data update needed.

franzpoeschel · 2023-06-28T09:15:36Z

I see two major issues with the current state of mesh refinement:

The use of suffixes _lvl<N> and _<P> seems inconsistent in an otherwise hierarchical data standard, as it reimplements hierarchies at the naming level. Should we consider developing this in conjunction with Allow user to store non-openPMD information #115 (custom hierarchies)?
The feature description in the standard should be more explicit on the required capabilities of the storage formats and maybe even reconsider them. Without mesh refinement, openPMD requires (roughly) a storage format that supports attributes, hierarchies and n-dimensional datasets. With mesh refinement, the backend is additionally required to allow querying written regions (in the API, the information returned by .available_chunks() is purely backend-specific and completely transparent to the actual openPMD standard).
In my understanding, HDF5 chunking allows storing a sparsely written dataset without using disk space corresponding with the entire domain (rather, it will use disk space corresponding with the covered chunks). Explicitly encoding the written chunks in either the standard or the HDF5 schema would then enable mesh refinement in HDF5, too.
To me, this seems like too small a detail for making mesh-refinement ADIOS-only over it.

ax3l · 2023-07-26T07:41:28Z

Potential directions for HDF5 support of MR in openPMD:

ursg · 2023-09-28T12:57:23Z

This is clearly motivated specifically with a patch-based refinement strategy in mind, and as such probably works very well.

However, I would like to point out that this structure would seem quite alien to other refined mesh approaches (tree-based or individuall-cell-based ones). Deliberately grouping mesh data by refinement level does not come natural to them!

Sorry about this nonproductive comment, as I do not have a suggestion for a suitable, more general approach. There certainly is merit in the proposal as it is specified here, but you might want to adapt a more specific name ("PatchBasedMeshRefinement"), as to not encumber future applications with different approaches.

Thank you, Urs!

ax3l · 2025-12-03T17:13:25Z

+The coarsest level of a record is implicitly assigned the level `0` of a simulation.
+The record names of finer levels are suffixed with `_lvl<N>` where `<N>` is the integer of the refined level.
+
+A patch of a refinemnet level shall be a spatially hyperrectangular subselection of the previous level.


Suggested change

A patch of a refinemnet level shall be a spatially hyperrectangular subselection of the previous level.

A patch of a refinement level shall be a spatially hyperrectangular subselection of the previous level.

RemiLehe · 2025-12-03T17:13:36Z

+
+A mesh record describing a refined level shall add the following attribute:
+
+  - `refinementRatio`


I don't think that is needed, because we already save the cell size at each level. So this would duplicate the same info.

ax3l · 2025-12-03T17:13:50Z

  see [EXT_BeamPhysics.md](EXT_BeamPhysics.md).
 - **ED-PIC**: electro-dynamic/static particle-in-cell codes,
  see [EXT_ED-PIC.md](EXT_ED-PIC.md).
+- **MeshRefinement**: mesh records refined over multiple levels of resolution,


Suggested change

- **MeshRefinement**: mesh records refined over multiple levels of resolution,

- **PatchBasedMeshRefinement**: mesh records refined over multiple levels of resolution,

Following up on the comment above, are there advantages to differentiate between patch-based refinement and other types of refinement?
Or could all types be covered by a very simple/basic extension?

RemiLehe · 2025-12-03T17:14:47Z

+The coarsest level of a record is implicitly assigned the level `0` of a simulation.
+The record names of finer levels are suffixed with `_lvl<N>` where `<N>` is the integer of the refined level.
+
+A patch of a refinemnet level shall be a spatially hyperrectangular subselection of the previous level.


Suggested change

A patch of a refinemnet level shall be a spatially hyperrectangular subselection of the previous level.

A patch of a refinement level shall be a spatially hyperrectangular subselection of the previous level.

BenWibking · 2026-06-25T20:42:14Z

This is supported by openpmd-visit-reader (https://github.com/BenWibking/openpmd-visit-reader) for VisIt, with an extension for how Parthenon (parthenon-hpc-lab/parthenon#1050) handles level suffixes for vector components. (Parthenon's octree AMR works fine in this representation.)

This plugin has also been tested with Quokka and WarpX outputs, which AFAIK adhere more strictly to this proposal.

pgrete

Dear all,
what would be required to push this across the finish line?
There are now multiple codes that use (some variant) of this extension plus some downstream tooling is available, too.
It seems like a good time to finalize the extension.

pgrete · 2026-07-14T09:44:19Z

+The coarsest level of a record is implicitly assigned the level `0` of a simulation.
+The record names of finer levels are suffixed with `_lvl<N>` where `<N>` is the integer of the refined level.


Does the "implicit" imply that level 0 cannot (or may not) carry the _lvl suffix?

pgrete · 2026-07-14T09:56:53Z

+A patch of a refinemnet level shall be a spatially hyperrectangular subselection of the previous level.
+Multiple patches might exist in a refined level.
+
+If the implemented file format supports sparse data sets, i.e. through efficient chunking of patches, the refined level must over the previous level in extend and store multiple patches through its chunking mechanism.
+
+File formats that do not support efficient storage a sparesly populated refinement level can store continguous patches on the same level with an additional suffix `_<P>` where `<P>` is the number of the (hyperrectangular) patch in the refinement level.


Does this need to be specified at all?

For example, if I have a mesh where half of the domain is refined and the other is not, the current wording suggests a either a global mesh with sparse data or a patched based one.
I could imagine that a simpler logic (i..e, just the _lvlN without considering sparse or patches) could be enough as it would already allow a code to query if data at certain location (and a certain level) exist.

I would also consider keeping the _<P> suffix, but optional and allowing for overlapping region (without making guarantees on the data in the overlapping regions), as it would allow to write individual patches/blocks with individual ghost zones (e.g., for debugging or calculating derived quantity on fine levels without prolongation from coarser ones).

This should then also cover/provide flexibility other MR strategies without breaking the existing usage, doesn't it?

pgrete · 2026-07-14T09:59:23Z

  see [EXT_BeamPhysics.md](EXT_BeamPhysics.md).
 - **ED-PIC**: electro-dynamic/static particle-in-cell codes,
  see [EXT_ED-PIC.md](EXT_ED-PIC.md).
+- **MeshRefinement**: mesh records refined over multiple levels of resolution,


Following up on the comment above, are there advantages to differentiate between patch-based refinement and other types of refinement?
Or could all types be covered by a very simple/basic extension?

Ext: MeshRefinement

e51be15

ax3l added the EXT: New? possible new extensions label Mar 9, 2021

ax3l mentioned this pull request Mar 29, 2021

openPMD: Support for mesh refinement BLAST-WarpX/warpx#1842

Merged

2 tasks

ax3l mentioned this pull request Jun 15, 2021

Mesh refinement: Adding IO Hi-PACE/hipace#526

Merged

9 tasks

ax3l requested review from RemiLehe, franzpoeschel and guj September 30, 2021 18:20

This was referenced Feb 18, 2022

Fix MR Reads (ADIOS) openPMD/openPMD-viewer#332

Merged

Option To Mask Invalid Regions with Zeros openPMD/openPMD-api#1203

Open

franzpoeschel mentioned this pull request Jun 28, 2023

Coordinates not set correctly (or at least not output correctly by OpenPMD) in CarpetX EinsteinToolkit/CarpetX#152

Closed

pgrete mentioned this pull request Jan 12, 2024

Current best practice for block structured AMR openPMD/openPMD-api#1588

Open

franzpoeschel mentioned this pull request Aug 13, 2024

Custom Hierarchies openPMD/openPMD-api#1432

Open

12 tasks

ax3l changed the title ~~Ext: MeshRefinement~~ Ext: PatchBasedMeshRefinement Dec 3, 2025

ax3l commented Dec 3, 2025

View reviewed changes

Comment thread EXT_MeshRefinement.md Outdated

ax3l commented Dec 3, 2025

View reviewed changes

Comment thread EXT_MeshRefinement.md Outdated

Rename Extension for Clarity

361dd31

Thank you, Urs!

ax3l commented Dec 3, 2025

View reviewed changes

RemiLehe reviewed Dec 3, 2025

View reviewed changes

ax3l commented Dec 3, 2025

View reviewed changes

RemiLehe reviewed Dec 3, 2025

View reviewed changes

pgrete reviewed Jul 14, 2026

View reviewed changes

ax3l mentioned this pull request Jul 23, 2026

Tools: pltfile-to-openpmd Converter AMReX-Codes/pyamrex#597

Open

3 tasks

	A patch of a refinemnet level shall be a spatially hyperrectangular subselection of the previous level.
	A patch of a refinement level shall be a spatially hyperrectangular subselection of the previous level.


		A mesh record describing a refined level shall add the following attribute:

		- `refinementRatio`

	- MeshRefinement: mesh records refined over multiple levels of resolution,
	- PatchBasedMeshRefinement: mesh records refined over multiple levels of resolution,

		The coarsest level of a record is implicitly assigned the level `0` of a simulation.
		The record names of finer levels are suffixed with `_lvl<N>` where `<N>` is the integer of the refined level.

Uh oh!

Conversation

ax3l commented Mar 9, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Affected Components

Logic Changes

Writer Changes

Reader Changes

Data Updater

Uh oh!

franzpoeschel commented Jun 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ax3l commented Jul 26, 2023

Uh oh!

ursg commented Sep 28, 2023

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BenWibking commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pgrete left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ax3l commented Mar 9, 2021 •

edited

Loading

franzpoeschel commented Jun 28, 2023 •

edited

Loading

BenWibking commented Jun 25, 2026 •

edited

Loading