Documentation

Author: franzpoeschel

docs/source/usage/workflow.rst

@@ -76,10 +76,13 @@ The openPMD-api distinguishes between a number of different access modes:
   3. In streaming backends, random-access is not possible.
      When using such a backend, the access mode will be coerced automatically to *linear read mode*.
      Use of Series::readIterations() is mandatory for access.
-  4. Reading a variable-based Series is only fully supported with *linear access mode*.
-     If using *random-access read mode*, the dataset will be considered to only have one single step.
-     If the dataset only has one single step, this is guaranteed to work as expected.
-     Otherwise, it is undefined which step's data is returned.
+  4. *Random-access read mode* for a variable-based Series is currently experimental.
+     There is currently only very restricted support for metadata definitions that change across steps:
+
+     1. Modifiable attributes (except ``/data/snapshot``) can currently not be read. Attributes such as ``/data/time`` that naturally change their value across Iterations will hence not be really well-usable; the last Iteration's value will currently leak into all other Iterations.
+     2. There is no support for datasets that do not exist in all Iterations. The internal Iteration layouts should be homogeneous.
+        If you need this feature, please contact the openPMD-api developers; implementing this is currently not a priority.
+     3. Datasets with changing extents are supported.
 
 * **Read/Write mode**: Creates a new Series if not existing, otherwise opens an existing Series for reading and writing.
   New datasets and iterations will be inserted as needed.