openPMD-api 0.16.1__tar.gz → 0.17.0__tar.gz

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/CMakeLists.txt

@@ -2,7 +2,7 @@
 #
 cmake_minimum_required(VERSION 3.22.0)
 
-project(openPMD VERSION 0.16.1) # LANGUAGES CXX
+project(openPMD VERSION 0.17.0) # LANGUAGES CXX
 
 # the openPMD "markup"/"schema" standard version
 set(openPMD_STANDARD_VERSION 1.1.0)
@@ -151,6 +151,8 @@ option(openPMD_USE_INTERNAL_TOML11   "Use internally shipped toml11"        ${op
 
 option(openPMD_USE_INVASIVE_TESTS "Enable unit tests that modify source code" OFF)
 option(openPMD_USE_VERIFY "Enable internal VERIFY (assert) macro independent of build type" ON)
+option(openPMD_USE_FILESYSTEM_HEADER "Enable filesystem header. May be disabled for old compiler versions." OFF)
+mark_as_advanced(openPMD_USE_FILESYSTEM_HEADER)
 
 set(CMAKE_CONFIGURATION_TYPES "Release;Debug;MinSizeRel;RelWithDebInfo")
 if(NOT CMAKE_BUILD_TYPE)
@@ -231,6 +233,7 @@ message(STATUS "openPMD-api superbuild: ${openPMD_SUPERBUILD}")
 #     Clang+MPI: Potentially needed MPI::MPI_C targets in the past
 #                (exact MPI flavor & Clang version lost)
 #     BullMPI: PUBLIC dependency to MPI::MPI_CXX is missing in MPI::MPI_C target
+set(MPI_CXX_SKIP_MPICXX ON)  # We do not use MPI-2 only MPI C++ bindings
 set(openPMD_MPI_LINK_C_DEFAULT OFF)
 option(openPMD_MPI_LINK_C  "Also link the MPI C targets" ${openPMD_MPI_LINK_C_DEFAULT})
 mark_as_advanced(openPMD_MPI_LINK_C)
@@ -326,8 +329,9 @@ if(openPMD_HAVE_HDF5)
 endif()
 # we imply support for parallel I/O if MPI variant is ON
 if(openPMD_HAVE_MPI AND openPMD_HAVE_HDF5
-    AND NOT HDF5_IS_PARALLEL      # FindHDF5.cmake
-    AND NOT HDF5_ENABLE_PARALLEL  # hdf5-config.cmake
+    AND NOT (HDF5_IS_PARALLEL      # FindHDF5.cmake
+             OR HDF5_ENABLE_PARALLEL # hdf5-config.cmake < 2.0.0
+             OR HDF5_PROVIDES_PARALLEL) # hdf5-config.cmake >= 2.0.0
 )
     string(CONCAT openPMD_HDF5_STATUS
             "Found MPI but only serial version of HDF5. Either set "
@@ -335,9 +339,11 @@ if(openPMD_HAVE_MPI AND openPMD_HAVE_HDF5
             "to disable HDF5 or provide a parallel install of HDF5.\n")
 endif()
 # HDF5 includes mpi.h in the public header H5public.h if parallel
-if(openPMD_HAVE_HDF5 AND
-   (HDF5_IS_PARALLEL OR HDF5_ENABLE_PARALLEL)
-   AND NOT openPMD_HAVE_MPI)
+if(openPMD_HAVE_HDF5 AND NOT openPMD_HAVE_MPI
+    AND (HDF5_IS_PARALLEL       # FindHDF5.cmake
+         OR HDF5_ENABLE_PARALLEL # hdf5-config.cmake < 2.0.0
+         OR HDF5_PROVIDES_PARALLEL) # hdf5-config.cmake >= 2.0.0
+   )
     string(CONCAT openPMD_HDF5_STATUS
         "Found only parallel version of HDF5 but no MPI. Either set "
         "openPMD_USE_MPI=ON to force using MPI or set openPMD_USE_HDF5=OFF "
@@ -365,14 +371,14 @@ if(openPMD_HAVE_MPI)
     list(APPEND openPMD_REQUIRED_ADIOS2_COMPONENTS MPI)
 endif()
 if(openPMD_USE_ADIOS2 STREQUAL AUTO)
-    find_package(ADIOS2 2.7.0 CONFIG COMPONENTS ${openPMD_REQUIRED_ADIOS2_COMPONENTS})
+    find_package(ADIOS2 2.9.0 CONFIG COMPONENTS ${openPMD_REQUIRED_ADIOS2_COMPONENTS})
     if(ADIOS2_FOUND)
         set(openPMD_HAVE_ADIOS2 TRUE)
     else()
         set(openPMD_HAVE_ADIOS2 FALSE)
     endif()
 elseif(openPMD_USE_ADIOS2)
-    find_package(ADIOS2 2.7.0 REQUIRED CONFIG COMPONENTS ${openPMD_REQUIRED_ADIOS2_COMPONENTS})
+    find_package(ADIOS2 2.9.0 REQUIRED CONFIG COMPONENTS ${openPMD_REQUIRED_ADIOS2_COMPONENTS})
     set(openPMD_HAVE_ADIOS2 TRUE)
 else()
     set(openPMD_HAVE_ADIOS2 FALSE)
@@ -397,28 +403,43 @@ set(CORE_SOURCE
         src/Mesh.cpp
         src/ParticlePatches.cpp
         src/ParticleSpecies.cpp
-        src/ReadIterations.cpp
         src/Record.cpp
+        src/ReadIterations.cpp
         src/RecordComponent.cpp
         src/Series.cpp
+        src/UnitDimension.cpp
         src/version.cpp
-        src/WriteIterations.cpp
         src/auxiliary/Date.cpp
         src/auxiliary/Filesystem.cpp
         src/auxiliary/JSON.cpp
+        src/auxiliary/JSONMatcher.cpp
+        src/auxiliary/Memory.cpp
         src/auxiliary/Mpi.cpp
+        src/auxiliary/UniquePtr.cpp
+        src/auxiliary/Variant.cpp
         src/backend/Attributable.cpp
+        src/backend/Attribute.cpp
+        src/backend/BaseRecord.cpp
         src/backend/BaseRecordComponent.cpp
+        src/backend/Container.cpp
         src/backend/MeshRecordComponent.cpp
         src/backend/PatchRecord.cpp
         src/backend/PatchRecordComponent.cpp
         src/backend/Writable.cpp
-        src/benchmark/mpi/OneDimensionalBlockSlicer.cpp
-        src/helper/list_series.cpp)
+        src/auxiliary/OneDimensionalBlockSlicer.cpp
+        src/helper/list_series.cpp
+        src/snapshots/ContainerImpls.cpp
+        src/snapshots/ContainerTraits.cpp
+        src/snapshots/IteratorHelpers.cpp
+        src/snapshots/IteratorTraits.cpp
+        src/snapshots/RandomAccessIterator.cpp
+        src/snapshots/Snapshots.cpp
+        src/snapshots/StatefulIterator.cpp)
 set(IO_SOURCE
         src/IO/AbstractIOHandler.cpp
         src/IO/AbstractIOHandlerImpl.cpp
         src/IO/AbstractIOHandlerHelper.cpp
+        src/IO/Access.cpp
         src/IO/DummyIOHandler.cpp
         src/IO/IOTask.cpp
         src/IO/FlushParams.cpp
@@ -429,6 +450,8 @@ set(IO_SOURCE
         src/IO/JSON/JSONIOHandlerImpl.cpp
         src/IO/JSON/JSONFilePosition.cpp
         src/IO/ADIOS/ADIOS2IOHandler.cpp
+        src/IO/ADIOS/ADIOS2PreloadAttributes.cpp
+        src/IO/ADIOS/ADIOS2PreloadVariables.cpp
         src/IO/ADIOS/ADIOS2File.cpp
         src/IO/ADIOS/ADIOS2Auxiliary.cpp
         src/IO/InvalidatableFile.cpp)
@@ -524,10 +547,18 @@ endif()
 
 # ADIOS2 Backend
 if(openPMD_HAVE_ADIOS2)
-    if(openPMD_HAVE_MPI)
-        target_link_libraries(openPMD PUBLIC adios2::cxx11_mpi)
+    if(${ADIOS2_VERSION} VERSION_GREATER_EQUAL 2.11.0)
+        if(openPMD_HAVE_MPI)
+            target_link_libraries(openPMD PUBLIC adios2::cxx_mpi)
+        else()
+            target_link_libraries(openPMD PUBLIC adios2::cxx)
+        endif()
     else()
-        target_link_libraries(openPMD PUBLIC adios2::cxx11)
+        if(openPMD_HAVE_MPI)
+            target_link_libraries(openPMD PUBLIC adios2::cxx11_mpi)
+        else()
+            target_link_libraries(openPMD PUBLIC adios2::cxx11)
+        endif()
     endif()
 endif()
 
@@ -542,6 +573,7 @@ endif()
 if(openPMD_HAVE_PYTHON)
     add_library(openPMD.py MODULE
         src/binding/python/openPMD.cpp
+        src/binding/python/auxiliary.cpp
         src/binding/python/Access.cpp
         src/binding/python/Attributable.cpp
         src/binding/python/BaseRecordComponent.cpp
@@ -671,11 +703,12 @@ set(openPMD_TEST_NAMES
 # command line tools
 set(openPMD_CLI_TOOL_NAMES
     ls
+    convert-toml-json
 )
 set(openPMD_PYTHON_CLI_TOOL_NAMES
     pipe
 )
-set(openPMD_PYTHON_CLI_MODULE_NAMES ${openPMD_CLI_TOOL_NAMES})
+set(openPMD_PYTHON_CLI_MODULE_NAMES ls)
 # examples
 set(openPMD_EXAMPLE_NAMES
     1_structure
@@ -695,6 +728,8 @@ set(openPMD_EXAMPLE_NAMES
     10_streaming_read
     12_span_write
     13_write_dynamic_configuration
+    14_toml_template
+    15_compression
 )
 set(openPMD_PYTHON_EXAMPLE_NAMES
     2_read_serial
@@ -711,6 +746,7 @@ set(openPMD_PYTHON_EXAMPLE_NAMES
     11_particle_dataframe
     12_span_write
     13_write_dynamic_configuration
+    15_compression
 )
 
 if(openPMD_USE_INVASIVE_TESTS)
@@ -721,6 +757,18 @@ if(openPMD_USE_INVASIVE_TESTS)
     target_compile_definitions(openPMD PRIVATE openPMD_USE_INVASIVE_TESTS=1)
 endif()
 
+function(set_filesystem_header_for_target target)
+    if(openPMD_USE_FILESYSTEM_HEADER)
+        target_compile_definitions(${target} PRIVATE openPMD_USE_FILESYSTEM_HEADER=1)
+    else()
+        target_compile_definitions(${target} PRIVATE openPMD_USE_FILESYSTEM_HEADER=0)
+    endif()
+endfunction()
+set_filesystem_header_for_target(openPMD)
+if(openPMD_HAVE_PYTHON)
+    set_filesystem_header_for_target(openPMD.py)
+endif()
+
 if(openPMD_BUILD_TESTING)
     # compile Catch2 implementation part separately
     add_library(CatchRunner ${_openpmd_lib_type}
@@ -772,8 +820,32 @@ if(openPMD_BUILD_TESTING)
         target_compile_definitions(CatchRunner PUBLIC openPMD_HAVE_MPI=1)
     endif()
 
+    macro(additional_testing_sources test_name out_list)
+        if(${test_name} STREQUAL "SerialIO")
+            list(APPEND ${out_list}
+                test/Files_SerialIO/close_and_reopen_test.cpp
+                test/Files_SerialIO/filebased_write_test.cpp
+                test/Files_SerialIO/issue_1744_unique_ptrs_at_close_time.cpp
+                test/Files_SerialIO/components_without_extent.cpp
+            )
+        elseif(${test_name} STREQUAL "ParallelIO" AND openPMD_HAVE_MPI)
+            list(APPEND ${out_list}
+                test/Files_ParallelIO/read_variablebased_randomaccess.cpp
+                test/Files_ParallelIO/iterate_nonstreaming_series.cpp
+                test/Files_ParallelIO/bug_1655_bp5_writer_hangup.cpp
+            )
+        elseif(${test_name} STREQUAL "Core")
+            list(APPEND ${out_list}
+                test/Files_Core/automatic_variable_encoding.cpp
+            )
+        endif()
+    endmacro()
+
     foreach(testname ${openPMD_TEST_NAMES})
-        add_executable(${testname}Tests test/${testname}Test.cpp)
+        set(ADDITIONAL_SOURCE_FILES "")
+        additional_testing_sources(${testname} ADDITIONAL_SOURCE_FILES)
+        add_executable(${testname}Tests test/${testname}Test.cpp ${ADDITIONAL_SOURCE_FILES})
+        target_include_directories(${testname}Tests PRIVATE test/Files_${testname}/)
         openpmd_cxx_required(${testname}Tests)
         set_target_properties(${testname}Tests PROPERTIES
             COMPILE_PDB_NAME ${testname}Tests
@@ -844,6 +916,9 @@ if(openPMD_BUILD_CLI_TOOLS)
         endif()
 
         target_link_libraries(openpmd-${toolname} PRIVATE openPMD)
+        target_include_directories(openpmd-${toolname} SYSTEM PRIVATE
+            $<TARGET_PROPERTY:openPMD::thirdparty::nlohmann_json,INTERFACE_INCLUDE_DIRECTORIES>
+            $<TARGET_PROPERTY:openPMD::thirdparty::toml11,INTERFACE_INCLUDE_DIRECTORIES>)
     endforeach()
 endif()
 
@@ -1286,27 +1361,30 @@ if(openPMD_BUILD_TESTING)
                 )
                 add_test(NAME CLI.pipe.py
                     COMMAND sh -c
-                        "${MPI_TEST_EXE} ${Python_EXECUTABLE}                      \
-                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe       \
-                            --infile ../samples/git-sample/data%T.h5               \
-                            --outfile ../samples/git-sample/data%T.bp &&           \
-                                                                                   \
-                        ${MPI_TEST_EXE} ${Python_EXECUTABLE}                       \
-                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe       \
-                            --infile ../samples/git-sample/data00000100.h5         \
-                            --outfile                                              \
-                                ../samples/git-sample/single_iteration_%T.bp &&    \
-                                                                                   \
-                        ${MPI_TEST_EXE} ${Python_EXECUTABLE}                       \
-                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe       \
-                            --infile ../samples/git-sample/thetaMode/data%T.h5     \
-                            --outfile                                              \
-                                ../samples/git-sample/thetaMode/data_%T.bp &&      \
-                                                                                   \
-                        ${MPI_TEST_EXE} ${Python_EXECUTABLE}                       \
-                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe       \
-                            --infile ../samples/git-sample/thetaMode/data_%T.bp    \
-                            --outfile ../samples/git-sample/thetaMode/data%T.json  \
+                        "${MPI_TEST_EXE} ${MPIEXEC_NUMPROC_FLAG} 2 ${Python_EXECUTABLE} \
+                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe            \
+                            --infile ../samples/git-sample/data%T.h5                    \
+                            --outfile ../samples/git-sample/data%T.bp &&                \
+                                                                                        \
+                        ${MPI_TEST_EXE} ${Python_EXECUTABLE}                            \
+                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe            \
+                            --infile ../samples/git-sample/data00000100.h5              \
+                            --outfile                                                   \
+                                ../samples/git-sample/single_iteration_%T.bp &&         \
+                                                                                        \
+                        ${MPI_TEST_EXE} ${MPIEXEC_NUMPROC_FLAG} 2 ${Python_EXECUTABLE}  \
+                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe            \
+                            --infile ../samples/git-sample/thetaMode/data%T.h5          \
+                            --outfile                                                   \
+                                ../samples/git-sample/thetaMode/data_%T.bp &&           \
+                                                                                        \
+                        ${MPI_TEST_EXE} ${Python_EXECUTABLE}                            \
+                            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/openpmd-pipe            \
+                            --infile ../samples/git-sample/thetaMode/data_%T.bp         \
+                            --outfile ../samples/git-sample/thetaMode/data%T.json       \
+                            --outconfig '                                               \
+                                json.attribute.mode = \"short\"                       \n\
+                                json.dataset.mode = \"template_no_warn\"'               \
                         "
                     WORKING_DIRECTORY ${openPMD_RUNTIME_OUTPUT_DIRECTORY}
                 )

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: openPMD-api
-Version: 0.16.1
+Version: 0.17.0
 Summary: C++ & Python API for Scientific I/O with openPMD
 Home-page: https://www.openPMD.org
 Author: Axel Huebl, Franz Poeschel, Fabian Koller, Junmin Gu
@@ -22,14 +22,13 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Database :: Front-Ends
 Classifier: Programming Language :: C++
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: COPYING
 License-File: COPYING.LESSER
@@ -41,6 +40,7 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: keywords
+Dynamic: license-file
 Dynamic: maintainer
 Dynamic: maintainer-email
 Dynamic: project-url
@@ -158,14 +158,14 @@ Shipped internally (downloaded by CMake unless `openPMD_SUPERBUILD=OFF` is set):
 I/O backends:
 * [JSON](https://en.wikipedia.org/wiki/JSON)
 * [HDF5](https://support.hdfgroup.org/HDF5) 1.8.13+ (optional)
-* [ADIOS2](https://github.com/ornladios/ADIOS2) 2.7.0+ (optional)
+* [ADIOS2](https://github.com/ornladios/ADIOS2) 2.9.0+ (optional)
 
 while those can be built either with or without:
 * MPI 2.1+, e.g. OpenMPI 1.6.5+ or MPICH2
 
 Optional language bindings:
 * Python:
-  * Python 3.8 - 3.13
+  * Python 3.10 - 3.14
   * pybind11 2.13.0+
   * numpy 1.15+
   * mpi4py 2.1+ (optional, for MPI)
@@ -354,7 +354,7 @@ export CMAKE_PREFIX_PATH=$HOME/somepath:$CMAKE_PREFIX_PATH
 Use the following lines in your project's `CMakeLists.txt`:
 ```cmake
 # supports:                       COMPONENTS MPI NOMPI HDF5 ADIOS2
-find_package(openPMD 0.16.1 CONFIG)
+find_package(openPMD 0.17.0 CONFIG)
 
 if(openPMD_FOUND)
     target_link_libraries(YourTarget PRIVATE openPMD::openPMD)
@@ -382,7 +382,7 @@ set(openPMD_INSTALL OFF)            # or instead use:
 set(openPMD_USE_PYTHON OFF)
 FetchContent_Declare(openPMD
   GIT_REPOSITORY "https://github.com/openPMD/openPMD-api.git"
-  GIT_TAG        "0.16.1")
+  GIT_TAG        "0.17.0")
 FetchContent_MakeAvailable(openPMD)
 ```
 
@@ -431,7 +431,7 @@ The following people and institutions [contributed](https://github.com/openPMD/o
 
 Maintained by the following research groups:
 
-* [Computational Radiation Physics (CRD)](https://www.casus.science/casus/team/) at CASUS/HZDR, led by [Michael Bussmann](https://github.com/bussmann)
+* [Computational Radiation Physics (CRP)](https://www.casus.science/casus/team/) at CASUS/HZDR, led by [Michael Bussmann](https://github.com/bussmann)
 * [Accelerator Modeling Program (AMP)](https://atap.lbl.gov/accelerator-modeling-program/) at LBNL, led by [Jean-Luc Vay](https://github.com/jlvay)
 * [Scientific Data Management (SDM)](https://crd.lbl.gov/divisions/scidata/sdm/) at LBNL, led by [Kesheng (John) Wu](https://github.com/john18)
 

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/README.md

@@ -108,14 +108,14 @@ Shipped internally (downloaded by CMake unless `openPMD_SUPERBUILD=OFF` is set):
 I/O backends:
 * [JSON](https://en.wikipedia.org/wiki/JSON)
 * [HDF5](https://support.hdfgroup.org/HDF5) 1.8.13+ (optional)
-* [ADIOS2](https://github.com/ornladios/ADIOS2) 2.7.0+ (optional)
+* [ADIOS2](https://github.com/ornladios/ADIOS2) 2.9.0+ (optional)
 
 while those can be built either with or without:
 * MPI 2.1+, e.g. OpenMPI 1.6.5+ or MPICH2
 
 Optional language bindings:
 * Python:
-  * Python 3.8 - 3.13
+  * Python 3.10 - 3.14
   * pybind11 2.13.0+
   * numpy 1.15+
   * mpi4py 2.1+ (optional, for MPI)
@@ -304,7 +304,7 @@ export CMAKE_PREFIX_PATH=$HOME/somepath:$CMAKE_PREFIX_PATH
 Use the following lines in your project's `CMakeLists.txt`:
 ```cmake
 # supports:                       COMPONENTS MPI NOMPI HDF5 ADIOS2
-find_package(openPMD 0.16.1 CONFIG)
+find_package(openPMD 0.17.0 CONFIG)
 
 if(openPMD_FOUND)
     target_link_libraries(YourTarget PRIVATE openPMD::openPMD)
@@ -332,7 +332,7 @@ set(openPMD_INSTALL OFF)            # or instead use:
 set(openPMD_USE_PYTHON OFF)
 FetchContent_Declare(openPMD
   GIT_REPOSITORY "https://github.com/openPMD/openPMD-api.git"
-  GIT_TAG        "0.16.1")
+  GIT_TAG        "0.17.0")
 FetchContent_MakeAvailable(openPMD)
 ```
 
@@ -381,7 +381,7 @@ The following people and institutions [contributed](https://github.com/openPMD/o
 
 Maintained by the following research groups:
 
-* [Computational Radiation Physics (CRD)](https://www.casus.science/casus/team/) at CASUS/HZDR, led by [Michael Bussmann](https://github.com/bussmann)
+* [Computational Radiation Physics (CRP)](https://www.casus.science/casus/team/) at CASUS/HZDR, led by [Michael Bussmann](https://github.com/bussmann)
 * [Accelerator Modeling Program (AMP)](https://atap.lbl.gov/accelerator-modeling-program/) at LBNL, led by [Jean-Luc Vay](https://github.com/jlvay)
 * [Scientific Data Management (SDM)](https://crd.lbl.gov/divisions/scidata/sdm/) at LBNL, led by [Kesheng (John) Wu](https://github.com/john18)
 

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/cmake/dependencies/pybind11.cmake

@@ -83,9 +83,9 @@ set(openPMD_pybind11_branch "v2.13.6"
     "Repository branch for openPMD_pybind11_repo if(openPMD_USE_INTERNAL_PYBIND11)")
 
 if(openPMD_USE_PYTHON STREQUAL AUTO)
-    find_package(Python 3.7.0 COMPONENTS Interpreter Development.Module)
+    find_package(Python 3.10.0 COMPONENTS Interpreter Development.Module)
 elseif(openPMD_USE_PYTHON)
-    find_package(Python 3.7.0 COMPONENTS Interpreter Development.Module REQUIRED)
+    find_package(Python 3.10.0 COMPONENTS Interpreter Development.Module REQUIRED)
 else()
     set(openPMD_HAVE_PYTHON FALSE)
 endif()

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/examples/10_streaming_read.cpp

@@ -1,3 +1,23 @@
+/* Copyright 2025 Franz Poeschel, Luca Fedeli
+ *
+ * This file is part of openPMD-api.
+ *
+ * openPMD-api is free software: you can redistribute it and/or modify
+ * it under the terms of of either the GNU General Public License or
+ * the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * openPMD-api is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License and the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * and the GNU Lesser General Public License along with openPMD-api.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
 #include <openPMD/openPMD.hpp>
 
 #include <algorithm>
@@ -18,6 +38,15 @@ int main()
         return 0;
     }
 
+    // Access the Series linearly. This means that upon opening the Series, no
+    // data is accessed yet. Instead, the single Iterations are processed
+    // collectively, one after the other, and data access only happens upon
+    // explicitly accessing an Iteration from `Series::snapshots()`. Note that
+    // the Container API of `Series::snapshots()` will work in a restricted mode
+    // compared to the `READ_RANDOM_ACCESS` access type, refer also to the
+    // documentation of the `Snapshots` class in `snapshots/Snapshots.hpp`. This
+    // restricted workflow enables performance optimizations in the backends,
+    // and more importantly is compatible with streaming I/O.
     Series series = Series("electrons.sst", Access::READ_LINEAR, R"(
 {
   "adios2": {
@@ -29,15 +58,9 @@ int main()
   }
 })");
 
-    // `Series::writeIterations()` and `Series::readIterations()` are
-    // intentionally restricted APIs that ensure a workflow which also works
-    // in streaming setups, e.g. an iteration cannot be opened again once
-    // it has been closed.
-    // `Series::iterations` can be directly accessed in random-access workflows.
-    for (IndexedIteration iteration : series.readIterations())
+    for (auto &[index, iteration] : series.snapshots())
     {
-        std::cout << "Current iteration: " << iteration.iterationIndex
-                  << std::endl;
+        std::cout << "Current iteration: " << index << std::endl;
         Record electronPositions = iteration.particles["e"]["position"];
         std::array<RecordComponent::shared_ptr_dataset_types, 3> loadedChunks;
         std::array<Extent, 3> extents;
@@ -54,7 +77,6 @@ int main()
 
         // 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)

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/examples/10_streaming_read.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-import json
 import sys
 
 import openpmd_api as io
@@ -18,19 +17,11 @@ if __name__ == "__main__":
         print("SST engine not available in ADIOS2.")
         sys.exit(0)
 
-    series = io.Series("simData.sst", io.Access_Type.read_linear,
-                       json.dumps(config))
+    series = io.Series("simData.sst", io.Access_Type.read_linear, config)
 
     # Read all available iterations and print electron position data.
-    # Direct access to iterations is possible via `series.iterations`.
-    # For streaming support, `series.read_iterations()` needs to be used
-    # instead of `series.iterations`.
-    # `Series.write_iterations()` and `Series.read_iterations()` are
-    # intentionally restricted APIs that ensure a workflow which also works
-    # in streaming setups, e.g. an iteration cannot be opened again once
-    # it has been closed.
-    for iteration in series.read_iterations():
-        print("Current iteration {}".format(iteration.iteration_index))
+    for index, iteration in series.snapshots().items():
+        print("Current iteration {}".format(index))
         electronPositions = iteration.particles["e"]["position"]
         loadedChunks = []
         shapes = []

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/examples/10_streaming_write.cpp

@@ -1,3 +1,25 @@
+/* Copyright 2025 Axel Huebl, Franz Poeschel
+ *
+ * This file is part of openPMD-api.
+ *
+ * openPMD-api is free software: you can redistribute it and/or modify
+ * it under the terms of of either the GNU General Public License or
+ * the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * openPMD-api is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License and the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * and the GNU Lesser General Public License along with openPMD-api.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+#include "openPMD/Series.hpp"
+#include "openPMD/snapshots/Snapshots.hpp"
 #include <openPMD/openPMD.hpp>
 
 #include <algorithm>
@@ -20,12 +42,21 @@ int main()
     }
 
     // open file for writing
-    Series series = Series("electrons.sst", Access::CREATE, R"(
+    // use QueueFullPolicy = Discard in order to create a situation where from
+    // the reader's perspective steps are skipped. This tests the bug reported
+    // in https://github.com/openPMD/openPMD-api/issues/1747.
+    // Create the Series with linear write access, i.e. one Iteration after
+    // the other. The alternative would be random-access where multiple
+    // Iterations can be accessed independently from one another. This more
+    // restricted mode enables performance optimizations in the backends, and
+    // more importantly is compatible with streaming I/O.
+    Series series = Series("electrons.sst", Access::CREATE_LINEAR, R"(
 {
   "adios2": {
     "engine": {
       "parameters": {
-        "DataTransport": "WAN"
+        "DataTransport": "WAN",
+        "QueueFullPolicy": "Discard"
       }
     }
   }
@@ -38,12 +69,7 @@ int main()
     std::shared_ptr<position_t> local_data(
         new position_t[length], [](position_t const *ptr) { delete[] ptr; });
 
-    // `Series::writeIterations()` and `Series::readIterations()` are
-    // intentionally restricted APIs that ensure a workflow which also works
-    // in streaming setups, e.g. an iteration cannot be opened again once
-    // it has been closed.
-    // `Series::iterations` can be directly accessed in random-access workflows.
-    WriteIterations iterations = series.writeIterations();
+    auto iterations = series.snapshots();
     for (size_t i = 0; i < 100; ++i)
     {
         Iteration iteration = iterations[i];

{openpmd_api-0.16.1 → openpmd_api-0.17.0}/examples/10_streaming_write.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-import json
 import sys
 
 import numpy as np
@@ -21,21 +20,13 @@ if __name__ == "__main__":
 
     # create a series and specify some global metadata
     # change the file extension to .json, .h5 or .bp for regular file writing
-    series = io.Series("simData.sst", io.Access_Type.create,
-                       json.dumps(config))
+    series = io.Series("simData.sst", io.Access_Type.create_linear, config)
     series.set_author("Franz Poeschel <f.poeschel@hzdr.de>")
     series.set_software("openPMD-api-python-examples")
 
     # now, write a number of iterations (or: snapshots, time steps)
     for i in range(10):
-        # Direct access to iterations is possible via `series.iterations`.
-        # For streaming support, `series.write_iterations()` needs to be used
-        # instead of `series.iterations`.
-        # `Series.write_iterations()` and `Series.read_iterations()` are
-        # intentionally restricted APIs that ensure a workflow which also works
-        # in streaming setups, e.g. an iteration cannot be opened again once
-        # it has been closed.
-        iteration = series.write_iterations()[i]
+        iteration = series.snapshots()[i]
 
         #######################
         # write electron data #