Update examples (#1371)

* Update examples

Mainly Series::close, Iteration::close, Series::writeIterations,
Series::readIterations, READ_LINEAR

* Fix: Python bindings use copy return value policies

* Fix: Use explicit ::close() call in WriteIterations

Author: franzpoeschel

examples/10_streaming_read.cpp

@@ -39,6 +39,9 @@ int main()
             extents[i] = rc.getExtent();
         }
 
+        // The iteration can be closed in order to help free up resources.
+        // The iteration's content will be flushed automatically.
+        // An iteration once closed cannot (yet) be reopened.
         iteration.close();
 
         for (size_t i = 0; i < 3; ++i)
@@ -55,6 +58,14 @@ int main()
         }
     }
 
+    /* The files in 'series' are still open until the object is destroyed, on
+     * which it cleanly flushes and closes all open file handles.
+     * When running out of scope on return, the 'Series' destructor is called.
+     * Alternatively, one can call `series.close()` to the same effect as
+     * calling the destructor, including the release of file handles.
+     */
+    series.close();
+
     return 0;
 #else
     std::cout << "The streaming example requires that openPMD has been built "

examples/10_streaming_read.py

@@ -53,3 +53,10 @@
             print("dim: {}".format(dim))
             chunk = loadedChunks[i]
             print(chunk)
+
+    # The files in 'series' are still open until the object is destroyed, on
+    # which it cleanly flushes and closes all open file handles.
+    # When running out of scope on return, the 'Series' destructor is called.
+    # Alternatively, one can call `series.close()` to the same effect as
+    # calling the destructor, including the release of file handles.
+    series.close()

examples/10_streaming_write.cpp

@@ -45,6 +45,14 @@ int main()
         iteration.close();
     }
 
+    /* The files in 'series' are still open until the object is destroyed, on
+     * which it cleanly flushes and closes all open file handles.
+     * When running out of scope on return, the 'Series' destructor is called.
+     * Alternatively, one can call `series.close()` to the same effect as
+     * calling the destructor, including the release of file handles.
+     */
+    series.close();
+
     return 0;
 #else
     std::cout << "The streaming example requires that openPMD has been built "

examples/10_streaming_write.py

@@ -80,3 +80,10 @@
         # If not closing an iteration explicitly, it will be implicitly closed
         # upon creating the next iteration.
         iteration.close()
+
+    # The files in 'series' are still open until the object is destroyed, on
+    # which it cleanly flushes and closes all open file handles.
+    # When running out of scope on return, the 'Series' destructor is called.
+    # Alternatively, one can call `series.close()` to the same effect as
+    # calling the destructor, including the release of file handles.
+    series.close()

examples/11_particle_dataframe.py

@@ -96,3 +96,5 @@
             idx_max * E.grid_spacing + E.grid_global_offset)
         print("maximum intensity I={} at index={} z={}mu".format(
             Intensity_max, idx_max, pos_max[2]))
+
+    s.close()

examples/12_span_write.cpp

@@ -84,6 +84,14 @@ void span_write(std::string const &filename)
         }
         iteration.close();
     }
+
+    /* The files in 'series' are still open until the object is destroyed, on
+     * which it cleanly flushes and closes all open file handles.
+     * When running out of scope on return, the 'Series' destructor is called.
+    # Alternatively, one can call `series.close()` to the same effect as
+    # calling the destructor, including the release of file handles.
+     */
+    series.close();
 }
 
 int main()

examples/12_span_write.py

@@ -27,6 +27,13 @@ def span_write(filename):
             j += 1
         iteration.close()
 
+    # The files in 'series' are still open until the object is destroyed, on
+    # which it cleanly flushes and closes all open file handles.
+    # When running out of scope on return, the 'Series' destructor is called.
+    # Alternatively, one can call `series.close()` to the same effect as
+    # calling the destructor, including the release of file handles.
+    series.close()
+
 
 if __name__ == "__main__":
     for ext in io.file_extensions:

examples/13_write_dynamic_configuration.cpp

@@ -128,5 +128,13 @@ chunks = "auto"
         iteration.close();
     }
 
+    /* The files in 'series' are still open until the object is destroyed, on
+     * which it cleanly flushes and closes all open file handles.
+     * When running out of scope on return, the 'Series' destructor is called.
+     * Alternatively, one can call `series.close()` to the same effect as
+     * calling the destructor, including the release of file handles.
+     */
+    series.close();
+
     return 0;
 }

examples/13_write_dynamic_configuration.py

@@ -146,6 +146,13 @@ def main():
         # upon creating the next iteration.
         iteration.close()
 
+    # The files in 'series' are still open until the object is destroyed, on
+    # which it cleanly flushes and closes all open file handles.
+    # When running out of scope on return, the 'Series' destructor is called.
+    # Alternatively, one can call `series.close()` to the same effect as
+    # calling the destructor, including the release of file handles.
+    series.close()
+
 
 if __name__ == "__main__":
     main()

examples/1_structure.cpp

@@ -39,7 +39,8 @@ int main()
      * to the openPMD standard. Creation of new elements happens on access
      * inside the tree-like structure. Required attributes are initialized to
      * reasonable defaults for every object. */
-    ParticleSpecies electrons = series.iterations[1].particles["electrons"];
+    ParticleSpecies electrons =
+        series.writeIterations()[1].particles["electrons"];
 
     /* Data to be moved from memory to persistent storage is structured into
      * Records, each holding an unbounded number of RecordComponents. If a
@@ -59,9 +60,17 @@ int main()
     electrons["positionOffset"]["x"].resetDataset(dataset);
     electrons["positionOffset"]["x"].makeConstant(22.0);
 
+    // The iteration can be closed in order to help free up resources.
+    // The iteration's content will be flushed automatically.
+    // An iteration once closed cannot (yet) be reopened.
+    series.writeIterations()[1].close();
+
     /* The files in 'series' are still open until the object is destroyed, on
      * which it cleanly flushes and closes all open file handles.
      * When running out of scope on return, the 'Series' destructor is called.
+     * Alternatively, one can call `series.close()` to the same effect as
+     * calling the destructor, including the release of file handles.
      */
+    series.close();
     return 0;
 }