view release on metacpan or  search on metacpan

externals/OPTIMADE/optimade.rst  view on Meta::CPAN

    [a-z_][a-z_0-9]*
    #END ERE identifiers

    #BEGIN ERE numbers
    [-+]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][-+]?[0-9]+)?
    #END ERE numbers

    #BEGIN ERE strings
    "([^\"]|\\.)*"
    #END ERE strings

The Symmetry Operation String Regular Expressions
-------------------------------------------------

Symmetry operation strings that comprise the :property:`space_group_symmetry_operations_xyz` property MUST conform to the following regular expressions.
The regular expressions are recorded below in two forms, one in a more readable form using variables and the other as an explicit pattern compatible with the `OPTIMADE Regular Expression Format`_.

- Perl Compatible Regular Expression (PCRE) syntax, with `Perl extensions <https://perldoc.perl.org/perlre>`__ used for readability and expressivity.
  The :val:`symop_definitions` section defines several variables in Perl syntax that capture common parts of the regular expressions (REs) and need to be interpolated into the final REs used for matching.
  The :val:`symops` section contains the REs themselves.
  The whitespace characters in these definitions are not significant; if used in Perl programs, these expressions MUST be processed with the :code:`/x` RE modifier.
  A working example of these REs in action can be found in the :code:`tests/cases/pcre_symops_001.sh` and other test cases.


  .. code:: PCRE

     #BEGIN PCRE symop_definitions

     $translations = '1\/2|[12]\/3|[1-3]\/4|[1-5]\/6';

     $symop_translation_appended = "[-+]? [xyz] ([-+][xyz])? ([-+] ($translations) )?";
     $symop_translation_prepended = "[-+]? ($translations) ([-+] [xyz] ([-+][xyz])? )?";

     $symop_re = "($symop_translation_appended|$symop_translation_prepended)";

     #END PCRE symop_definitions

  .. code:: PCRE

     #BEGIN PCRE symops

     ^ # From the beginning of the string...
     ($symop_re)(,$symop_re){2}
     $ # ... match to the very end of the string

     #END PCRE symops

- The regular expression is also provided in an expanded form as an OPTIMADE regex:

  .. code:: ECMA

     #BEGIN ECMA symops

     ^([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[x...

     #END ECMA symops

OPTIMADE JSON Lines partial data format
---------------------------------------
The OPTIMADE JSON Lines partial data format is a lightweight format for transmitting property data that are too large to fit in a single OPTIMADE response.
The format is based on `JSON Lines <https://jsonlines.org/>`__, which enables streaming of JSON data.
Note: since the below definition references both JSON fields and OPTIMADE properties, the data type names depend on context: for JSON they are, e.g., "array" and "object" and for OPTIMADE properties they are, e.g., "list" and "dictionary".

.. _slice object:

To aid the definition of the format below, we first define a "slice object" to be a JSON object describing slices of lists.
The dictionary has the following OPTIONAL fields:

- :field:`"start"`: Integer.
  The slice starts at the value with the given index (inclusive, meaning the item at the start index is included).
  It MUST be a non-negative integer.
  The default is 0, i.e., the value at the start of the list.
- :field:`"stop"`: Integer.
  The slice ends at the value with the given index (inclusive, meaning the item at the stop index is included).
  It MUST be a non-negative integer.
  If omitted, the end of the slice is the last index of the list.

  Note: The fact the stop index is inclusive differs from common slicing conventions in many programming languages, where the stop index is typically exclusive. Care should be taken to avoid off-by-one errors.
- :field:`"step"`: Integer.
  The absolute difference in index between two subsequent values that are included in the slice.
  It MUST be a non-zero positive integer.
  The default is 1, i.e., every value in the range indicated by :field:`start` and :field:`stop` is included in the slice.
  Hence, a value of 2 denotes a slice of every second value in the list.

For example, for the list :val:`["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"]` the slice object :val:`{"start": 1, "stop": 7, "step": 3}` refers to the items :val:`["b", "e", "h"]`.

Furthermore, we also define the following special markers:

- The *end-of-data-marker* is this exact JSON: :val:`["PARTIAL-DATA-END", [""]]`.
- A *reference-marker* is this exact JSON: :val:`["PARTIAL-DATA-REF", ["<url>"]]`, where :val:`"<url>"` is to be replaced with a URL being referenced.
  A reference-marker MUST only occur in a place where the property being communicated could have an embedded list.
- A *next-marker* is this exact JSON: :val:`["PARTIAL-DATA-NEXT", ["<url>"]]`, where :val:`"<url>"` is to be replaced with the target URL for the next link.

There is no requirement on the syntax or format of the URLs provided in these markers.
When data is fetched from these URLs the response MUST use the JSON Lines partial data format, i.e., the markers cannot be used to link to partial data provided in other formats.
The markers have been deliberately designed to be valid JSON objects but *not* valid OPTIMADE property values.
Since the OPTIMADE list data type is defined as a list of values of the same data type or :val:`null`, the above markers cannot be encountered inside the actual data of an OPTIMADE property.

  **Implementation note:** the recognizable string values for the markers should make it possible to prescreen the raw text of the JSON data lines for the reference-marker string to determine which are the lines that one can exclude from further proc...
  The underlying design idea is that for lines that have reference-markers, the time it takes to process the data structure to locate the markers should be negligible compared to the time it takes to resolve and handle the large data they reference.
  Hence, the most relevant optimization is to avoid spending time processing data structures to find markers for lines where there are none.

The full response MUST be valid `JSON Lines <https://jsonlines.org/>`__ that adheres to the following format:

- The first line is a header object (defined below).
- The following lines are data lines adhering to the formats described below.
- The final line is either an end-of-data-marker (indicating that there is no more data to be given), or a next-marker indicating that more data is available, which can be obtained by retrieving data from the provided URL.

The first line MUST be a JSON object providing header information.
The header object MUST contain the keys:

- :field:`"optimade-partial-data"`: Object.
  An object identifying the response as being on OPTIMADE partial data format.

  It MUST contain the following key:

  - :field:`"format"`: String.
    Specifies the minor version of the partial data format used.
    The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format.
    The version number string MUST NOT be prefixed by, e.g., "v". In implementations of the present version of the standard, the value MUST be exactly :val:`1.2`.
    A client MUST NOT expect to be able to parse the :field:`format` value if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized.