Skip to content

Latest commit

 

History

History
82 lines (61 loc) · 3.78 KB

json.rst

File metadata and controls

82 lines (61 loc) · 3.78 KB

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.

Additionally to the three mentioned keys, the top-level group stores information about the byte widths specific to the writing platform behind the key platform_byte_widths. Will be overwritten every time that a JSON value is stored to disk, hence this information is only available about the last platform writing the JSON value.

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 used by the openPMD backend.

Numerical values, integral as well as floating point, 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.

Upon reading null when expecting any other datatype, the JSON backend will propagate the exception thrown by Niels Lohmann's library.

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