Add documentation for the JSON backend

docs/source/backends/json.rst

@@ -0,0 +1,74 @@
+.. _backends-json:
+
+JSON Backend
+============
+
+openPMD supports writing to and reading from JSON files.
+For this, the installed copy of openPMD must have been built with support for the JSON backend.
+To build openPMD with support for JSON, use the CMake option ``-DopenPMD_USE_JSON=ON``.
+For further information, check out the :ref:`installation guide <install>`,
+:ref:`build dependencies <development-dependencies>` and the :ref:`build options <development-buildoptions>`.
+
+
+JSON File Format
+----------------
+A JSON file uses the file ending ``.json``. The JSON backend is chosen by creating
+a ``Series`` object with a filename that has this file ending.
+
+The top-level JSON object is a group representing the openPMD root group ``"/"``.
+Any **openPMD group** is represented in JSON as a JSON object with three keys:
+
+ * ``attributes``: Attributes associated with the group.
+ * ``subgroups``: A JSON array of groups that appear below the current group.
+ * ``datasets``: A JSON array of datasets contained in the group.
+
+Any of these keys may point to ``null`` or not be present,
+thus representing an empty array / object.
+
+Any **openPMD dataset** is a JSON object with four keys:
+
+ * ``attributes``: Attributes associated with the dataset. May be ``null`` or not present if no attributes are associated with the dataset.
+ * ``datatype``: A string describing the type of the stored data.
+ * ``extent``: A JSON array describing the extent of the dataset in every dimension.
+ * ``data`` A nested array storing the actual data in row-major manner.
+   The data needs to be consistent with the fields ``datatype`` and ``extent``.
+
+**Attributes** are stored as a JSON object with a key for each attribute.
+Every such attribute is itself a JSON object with two keys:
+
+ * ``datatype``: A string describing the type of the value.
+ * ``value``: The actual value of type ``datatype``.
+
+Restrictions
+------------
+For creation of JSON serializations (i.e. writing), the restrictions of the JSON backend are
+equivalent to those of the `JSON library by Niels Lohmann <https://github.com/nlohmann/json>`
+used by the openPMD backend.
+
+Integral values are supported up to a length of 128 bits.
+Floating point values are supported up to a length of 64 bits.
+Since JSON does not support special floating point values (i.e. NaN, Infinity, -Infinity),
+those values are rendered as ``null``.
+
+Instructing openPMD to write values of a datatype that is too wide for the JSON
+backend does *not* result in an error:
+ * If casting the value to the widest supported datatype of the same category (integer or floating point)
+   is possible without data loss, the cast is performed and the value is written.
+   As an example, on a platform with ``sizeof(double) == 8``, writing the value
+   ``static_cast<long double>(std::numeric_limits<double>::max())`` will work as expected
+   since it can be cast back to ``double``.
+ * Otherwise, a ``null`` value is written.
+
+Upon reading ``null`` when expecting a floating point number, a NaN value will be
+returned. Take notice that a NaN value returned from the deserialization process
+may have originally been +/-Infinity or beyond the supported value range.
+
+A parallel (i.e. MPI) implementation is *not* available.
+
+Example
+-------
+The example code in the :ref:`usage section <usage-serial>` will produce the following JSON serialization
+when picking the JSON backend:
+
+.. literalinclude:: json_example.json
+

docs/source/backends/json_example.json

@@ -0,0 +1,158 @@
+{
+  "attributes": {
+    "basePath": {
+      "byte_width": 1,
+      "datatype": "STRING",
+      "value": "/data/%T/"
+    },
+    "iterationEncoding": {
+      "byte_width": 1,
+      "datatype": "STRING",
+      "value": "groupBased"
+    },
+    "iterationFormat": {
+      "byte_width": 1,
+      "datatype": "STRING",
+      "value": "/data/%T/"
+    },
+    "meshesPath": {
+      "byte_width": 1,
+      "datatype": "STRING",
+      "value": "meshes/"
+    },
+    "openPMD": {
+      "byte_width": 1,
+      "datatype": "STRING",
+      "value": "1.1.0"
+    },
+    "openPMDextension": {
+      "byte_width": 4,
+      "datatype": "UINT",
+      "value": 0
+    }
+  },
+  "subgroups": {
+    "data": {
+      "subgroups": {
+        "1": {
+          "attributes": {
+            "dt": {
+              "byte_width": 8,
+              "datatype": "DOUBLE",
+              "value": 1
+            },
+            "time": {
+              "byte_width": 8,
+              "datatype": "DOUBLE",
+              "value": 0
+            },
+            "timeUnitSI": {
+              "byte_width": 8,
+              "datatype": "DOUBLE",
+              "value": 1
+            }
+          },
+          "subgroups": {
+            "meshes": {
+              "datasets": {
+                "rho": {
+                  "attributes": {
+                    "axisLabels": {
+                      "byte_width": 1,
+                      "datatype": "VEC_STRING",
+                      "value": [
+                        "x"
+                      ]
+                    },
+                    "dataOrder": {
+                      "byte_width": 1,
+                      "datatype": "CHAR",
+                      "value": 67
+                    },
+                    "geometry": {
+                      "byte_width": 1,
+                      "datatype": "STRING",
+                      "value": "cartesian"
+                    },
+                    "gridGlobalOffset": {
+                      "byte_width": 8,
+                      "datatype": "VEC_DOUBLE",
+                      "value": [
+                        0
+                      ]
+                    },
+                    "gridSpacing": {
+                      "byte_width": 8,
+                      "datatype": "VEC_DOUBLE",
+                      "value": [
+                        1
+                      ]
+                    },
+                    "gridUnitSI": {
+                      "byte_width": 8,
+                      "datatype": "DOUBLE",
+                      "value": 1
+                    },
+                    "position": {
+                      "byte_width": 8,
+                      "datatype": "VEC_DOUBLE",
+                      "value": [
+                        0
+                      ]
+                    },
+                    "timeOffset": {
+                      "byte_width": 4,
+                      "datatype": "FLOAT",
+                      "value": 0
+                    },
+                    "unitDimension": {
+                      "byte_width": 8,
+                      "datatype": "ARR_DBL_7",
+                      "value": [
+                        0,
+                        0,
+                        0,
+                        0,
+                        0,
+                        0,
+                        0
+                      ]
+                    },
+                    "unitSI": {
+                      "byte_width": 8,
+                      "datatype": "DOUBLE",
+                      "value": 1
+                    }
+                  },
+                  "byte_width": 8,
+                  "data": [
+                    [
+                      0,
+                      1,
+                      2
+                    ],
+                    [
+                      3,
+                      4,
+                      5
+                    ],
+                    [
+                      6,
+                      7,
+                      8
+                    ]
+                  ],
+                  "datatype": "DOUBLE",
+                  "extent": [
+                    3,
+                    3
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

docs/source/index.rst

@@ -81,3 +81,13 @@ Development
    dev/buildoptions
    dev/sphinx
    dev/doxygen
+
+********
+Backends
+********
+.. toctree::
+   :caption: BACKENDS
+   :maxdepth: 1
+   :hidden:
+
+   backends/json

docs/source/usage/firststeps.rst

@@ -1,4 +1,4 @@
-.. usage-firststeps:
+.. _usage-firststeps:
 
 First Steps
 ===========

docs/source/usage/parallel.rst

@@ -1,4 +1,4 @@
-.. usage-parallel:
+.. _usage-parallel:
 
 Parallel API
 ============

docs/source/usage/serial.rst

@@ -1,4 +1,4 @@
-.. usage-serial:
+.. _usage-serial:
 
 Serial API
 ==========