From 3223e5a3fbefbc2bdf0476de93e16ccfe5538170 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Franz=20P=C3=B6schel?= <franz.poeschel@gmail.com>
Date: Wed, 10 Nov 2021 15:07:31 +0100
Subject: [PATCH] Document .toml schema

---
 docs/source/usage/plugins/openPMD.rst  | 15 +++++++++++++
 docs/source/usage/plugins/openPMD.toml | 30 ++++++++++++++++++++++++++
 2 files changed, 45 insertions(+)
 create mode 100644 docs/source/usage/plugins/openPMD.toml

diff --git a/docs/source/usage/plugins/openPMD.rst b/docs/source/usage/plugins/openPMD.rst
index 1469aa2c66..ee7e6c2530 100644
--- a/docs/source/usage/plugins/openPMD.rst
+++ b/docs/source/usage/plugins/openPMD.rst
@@ -31,6 +31,9 @@ Also see :ref:`common patterns of defining particle filters <usage-workflows-par
 .cfg file
 ^^^^^^^^^
 
+Note that all the following command line parameters can *alternatively* be specified in a ``.toml`` configuration file.
+See the next section for further information: `Configuring the openPMD plugin with a TOML configuration file>`
+
 You can use ``--openPMD.period`` to specify the output period.
 The base filename is specified via ``--openPMD.file``.
 The openPMD API will parse the file name to decide the chosen backend and iteration layout:
@@ -199,6 +202,18 @@ Performance
 On the Summit compute system, specifying ``export IBM_largeblock_io=true`` disables data shipping, which leads to reduced overhead for large block write operations.
 This setting is applied in the Summit templates found in ``etc/picongpu/summit-ornl``.
 
+Configuring the openPMD plugin with a TOML configuration file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The openPMD plugin can alternatively be configured by using a ``.toml`` configuration file.
+Note the inline comments for a description of the used schema:
+
+.. literalinclude:: openPMD.toml
+
+The location of the ``.toml`` file on the filesystem is specified via ``--openPMD.toml``.
+If using this parameter, no other parameters must be specified.
+If another parameter is specified, the openPMD plugin will notice and abort.
+
 
 Memory Complexity
 ^^^^^^^^^^^^^^^^^
diff --git a/docs/source/usage/plugins/openPMD.toml b/docs/source/usage/plugins/openPMD.toml
new file mode 100644
index 0000000000..b8e7907135
--- /dev/null
+++ b/docs/source/usage/plugins/openPMD.toml
@@ -0,0 +1,30 @@
+# The following parameters need not be specified
+# If a parameter is left unspecified, it falls back to its default value
+file = "simData"   # replaces --openPMD.file,
+                   # given value is the default
+infix = ""         # replaces --openPMD.infix,
+                   # default is "%06T"
+ext = "bp"         # replaces --openPMD.ext,
+                   # given value is the default
+backend_config = "@./adios_config.json"    # replaces --openPMD.json,
+                                           # default is "{}"
+data_preparation_strategy = "mappedMemory" # replaces --openPMD.dataPreparationStrategy,
+                                           # default is "doubleBuffer"
+
+
+# Periods and data sources are specified independently per reading application
+# The application names can be arbitrary and are not interpreted, except
+# potentially for logging and other messages.
+[sink.saxs_scattering.period]
+# Each entry here denotes a periodicity combined with data sources requested
+# by the reading code from PIConGPU at the specified periodicity
+500 = "species_all"
+
+# A second data sink needs other output data
+# All reading requests are merged into one single instance of the openPMD plugin
+# Overlapping requests are no problem
+[sink.some_other_name.period]
+# Data sources can be specified as a list if needed
+"400:400" = ["E", "B"]
+# Time slice syntax is equivalent to that used by --openPMD.period
+"100:300:200,444:444" = "fields_all"