commitStructuralSetup --> populateMissingMetadata(bool recursive)

Author: franzpoeschel

include/openPMD/Iteration.hpp

@@ -151,13 +151,13 @@ namespace internal
 class Meshes : public Container<Mesh>
 {
 public:
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 };
 
 class Particles : public Container<ParticleSpecies>
 {
 public:
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 };
 
 /** @brief  Logical compilation of data from one snapshot (e.g. a single
@@ -298,7 +298,7 @@ class Iteration
     [[deprecated("This attribute is no longer set by the openPMD-api.")]] bool
     closedByWriter() const;
 
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
     Meshes meshes{};
     Particles particles{};

include/openPMD/Mesh.hpp

@@ -326,7 +326,7 @@ class Mesh : public BaseRecord<MeshRecordComponent>
         typename = std::enable_if_t<std::is_floating_point<T>::value>>
     Mesh &setTimeOffset(T timeOffset);
 
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
 private:
     Mesh();

include/openPMD/ParticlePatches.hpp

@@ -38,7 +38,7 @@ class ParticlePatches : public Container<PatchRecord>
     size_t numPatches() const;
     ~ParticlePatches() override = default;
 
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
 private:
     ParticlePatches() = default;

include/openPMD/ParticleSpecies.hpp

@@ -47,11 +47,7 @@ class ParticleSpecies
 public:
     ParticlePatches particlePatches;
 
-    void visitHierarchy(HierarchyVisitor &v) override
-    {
-        visitHierarchyImpl<ParticleSpecies>(v);
-        particlePatches.visitHierarchy(v);
-    }
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
 private:
     ParticleSpecies();

include/openPMD/Record.hpp

@@ -50,7 +50,7 @@ class Record : public BaseRecord<RecordComponent>
     template <typename T>
     Record &setTimeOffset(T);
 
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
 private:
     Record();

include/openPMD/RecordComponent.hpp

@@ -488,7 +488,7 @@ class RecordComponent
     auto visit(Args &&...args) -> decltype(Visitor::template call<char>(
         std::declval<RecordComponent &>(), std::forward<Args>(args)...));
 
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
     static constexpr char const *const SCALAR = "\vScalar";
 

include/openPMD/Series.hpp

@@ -69,7 +69,7 @@ class Series;
 class Iterations : public Container<Iteration, Iteration::IterationIndex_t>
 {
 public:
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 };
 
 namespace internal
@@ -784,7 +784,7 @@ class Series : public Attributable
      */
     void close();
 
-    void visitHierarchy(HierarchyVisitor &v) override;
+    void visitHierarchy(HierarchyVisitor &v, bool recursive) override;
 
     /**
      * This overrides Attributable::iterationFlush() which will fail on Series.

include/openPMD/backend/Attributable.hpp

@@ -408,10 +408,14 @@ class Attributable
      * @note As the HierarchyVisitor interface can be tedious to implement,
      *       consider using visitHierarchyFromLambda for a more convenient
      *       interface.
+
+     * @note to developers: if at any point a prefix traversal should become
+     *       necessary, consider emplacing configuration options for this inside
+     *       HierarchyVisitor to keep the interface clean.
      *
      * @param visitor Operations to run for each object.
      */
-    virtual void visitHierarchy(HierarchyVisitor &visitor);
+    virtual void visitHierarchy(HierarchyVisitor &visitor, bool recursive);
 
     /**
      * Visitor pattern for the openPMD object hierarchy in postfix traversal,
@@ -422,42 +426,31 @@ class Attributable
      *
      * @note Definition inside include/openPMD/backend/HierarchyVisitorImpl.hpp.
      * @param lambda Operations to run for each object.
+     * @param recursive Extend the operation recursively to children.
      */
     template <typename Lambda>
-    void visitHierarchyFromLambda(Lambda &&lambda);
+    void visitHierarchyFromLambda(Lambda &&lambda, bool recursive);
 
-    /**
-     * Recursively freeze structural definitions made so far on the current
-     * object and all its children.
-     *
-     * This includes:
-     * 1. Explicit attribute writes
-     * 2. Implicit attributes, i.e.: Attributes defined by the openPMD standard
-     *    will now be populated with sensible default values
-     * 3. Dataset creation: The Dataset declarations set by resetDataset() will
-     *    now be fixed. Datasets can no longer be changed to constant components
-     *    after this.
-     * 4. Hierarchy setup, i.e. creation of group paths.
-     *
-     * WARNING: this is still under development and not fully implemented yet
-     * (implementation status: only bullet 2. from above. ref.
-     * https://github.com/openPMD/openPMD-api/pull/1862 for the rest.)
-     *
-     * Uses of this include:
-     * 1. Setting up the metadata is a collective operation in some backends
-     *    (read: HDF5). When interacting with a dataset non-collectively (e.g.
-     *    single ranks without data contribution, variable number of blocks per
-     *    rank), this call harmonizes the collective metadata setup.
-     * 2. Forcing the creation of default attributes. By default, these are
-     *    written upon closing the containing Iteration / Series. Calling this
-     *    soon can make data available for early readers (e.g. read while the
-     *    writer is still modifying).
-     *
-     * Modifying the frozen structural setup is only possible insofar as the
-     * backend supports this, e.g. by dataset extension, attribute overwrite or
-     * group deletion.
+    /** Create standard defined attributes with default values now, insofar they
+     *  are still missing.
+     *
+     * Refer to
+     * https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md
+     * for the attributes implied by this operation.
+     *
+     * By default, standard defined attributes are written upon closing the
+     * containing Iteration / Series. Calling this soon can make data available
+     * for early readers (e.g. read while the writer is still modifying). In
+     * workflows that keep single Iterations open over an extended period of
+     * time (e.g. back-transformed diagnostics), this can help creating readable
+     * files earlier than without.
+     *
+     * Attributes may still be modified after this as usual. Attributes defined
+     * before this call will not be modified by it.
+     *
+     * @param recursive Extend the operation recursively to children.
      */
-    void commitStructuralSetup();
+    void populateMissingMetadata(bool recursive);
 
     [[nodiscard]] OpenpmdStandard openPMDStandard() const;
 

include/openPMD/backend/Container.hpp

@@ -264,11 +264,14 @@ class Container : virtual public Attributable
     }
 
     template <typename ChildClass>
-    void visitHierarchyImpl(HierarchyVisitor &v)
+    void visitHierarchyImpl(HierarchyVisitor &v, bool recursive)
     {
-        for (auto &p : *this)
+        if (recursive)
         {
-            p.second.visitHierarchy(v);
+            for (auto &p : *this)
+            {
+                p.second.visitHierarchy(v, recursive);
+            }
         }
         v(*static_cast<ChildClass *>(this));
     }

include/openPMD/backend/HierarchyVisitorImpl.hpp

@@ -81,9 +81,9 @@ auto makeHierarchyVisitorFromLambda(Lambda &&lambda)
 }
 
 template <typename Lambda>
-void Attributable::visitHierarchyFromLambda(Lambda &&lambda)
+void Attributable::visitHierarchyFromLambda(Lambda &&lambda, bool recursive)
 {
     auto visitor = makeHierarchyVisitorFromLambda(std::forward<Lambda>(lambda));
-    this->visitHierarchy(visitor);
+    this->visitHierarchy(visitor, recursive);
 }
 } // namespace openPMD