Adding the trajectories endpoint to OPTIMADE

optimade.rst

@@ -891,7 +891,7 @@ Examples:
 
 - :query-url:`http://example.com/optimade/v1/structures?_exmpl_key=A3242DSFJFEJE`
 - :query-url:`http://example.com/optimade/v1/structures?_exmpl_warning_verbosity=10`
-- :query-url:`http://example.com/optimade/v1/structures?\_exmpl\_filter="elements all in [Al, Si, Ga]"`
+- :query-url:`http://example.com/optimade/v1/structures?_exmpl_filter="elements all in [Al, Si, Ga]"`
 
     **Note**: the specification presently makes no attempt to standardize access control mechanisms.
     There are security concerns with access control based on URL tokens, and the above example is not to be taken as a recommendation for such a mechanism.
@@ -1103,6 +1103,7 @@ Example:
           "entry_types_by_format": {
             "json": [
               "structures",
+              "trajectories",
               "calculations"
             ],
             "xml": [
@@ -1111,6 +1112,7 @@ Example:
           },
           "available_endpoints": [
             "structures",
+            "trajectories",
             "calculations",
             "info",
             "links"
@@ -1538,7 +1540,6 @@ The following tokens are used in the filter query component:
   - :property:`_exmpl_formula_sum` (a property specific to that database)
   - :property:`_exmpl_band_gap`
   - :property:`_exmpl_supercell`
-  - :property:`_exmpl_trajectory`
   - :property:`_exmpl_workflow_id`
 
 - **Nested property names** A nested property name is composed of at least two identifiers separated by periods (``.``).
@@ -2258,6 +2259,7 @@ type
 - **Examples**:
 
   - :val:`"structures"`
+  - :val:`"trajectories"`
 
 immutable\_id
 ~~~~~~~~~~~~~
@@ -2314,7 +2316,6 @@ database-provider-specific properties
   - :property:`_exmpl_formula_sum`
   - :property:`_exmpl_band_gap`
   - :property:`_exmpl_supercell`
-  - :property:`_exmpl_trajectory`
   - :property:`_exmpl_workflow_id`
 
 Structures Entries
@@ -2860,6 +2861,338 @@ structure\_features
 
   - A structure having implicit atoms and using assemblies: :val:`["assemblies", "implicit_atoms"]`
 
+Trajectories Entries
+--------------------
+
+- **Description**: The :entry:`trajectories` entry is used to share data belonging to sequences of structures, e.g., from a molecular dynamics or Monte Carlo simulation.
+
+  The individual steps of the trajectories are called frames.
+
+  Some examples of the data that can be shared are the particle positions, the pressure and the energies.
+  :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the property `nframes`_ and `reference_frame`_.
+  Furthermore, :entry:`trajectories` can optionally have relationships, database specific fields and all the properties defined for the structures endpoint.
+  If one of these properties does not have a constant value it should be shared as a ranged property, as described in #TODO insert reference to ranged properties section.
+  The dimension that corresponds to the steps of the trajectory MUST have :field:`range_id` = :val:`"frames"`.
+
+reference_frame
+~~~~~~~~~~~~~~~
+
+- **Description**: The indexes of a set of frames that give a good but brief overview of the trajectory.
+  The first frame could for example be a starting configuration, the second a transition state and the third the final state.
+- **Type**: list of integers
+- **Requirements/Conventions**: The values MUST be larger than 0 and equal or less than nframes.
+
+  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
+  - **Query**: Support for queries on this property is OPTIONAL.
+    If supported, filters MAY support only a subset of comparison operators.
+
+- **Examples**:
+
+  - :val:`[0, 397, 1000]`
+
+nframes
+~~~~~~~
+
+- **Description**: The number of frames in the trajectory as exposed by the API.
+  This value may deviate from the number of steps used to calculate the trajectory.
+  E.g., for a 10 ps simulation with calculation steps of 1 fs where data is stored once every 50 fs, nframes = 200.
+- **Type**: integer
+- **Requirements/Conventions**:
+
+  - **Support**: MUST be supported by all implementations, i.e., MUST NOT be :val:`null`.
+  - **Query**: MUST be a queryable property with support for all mandatory filter features.
+  - The integer value MUST be equal to the length of the trajectory, that is, the number of frames.
+  - The integer MUST be a positive non-zero value.
+
+- **Querying**:
+
+  - A filter that matches trajectories that have exactly 100 frames:
+    - :filter:`nframes=100`
+  - A filter that matches trajectories that have between 100 and 1000 frames:
+    - :filter:`nframes>=100 AND nframes<=1000`
+
+- **Examples**:
+
+  -   :val:`42`
+
+
+Examples of a returned trajectory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an example of the data field of a JSON object that could be returned after the following query:
+:query-url:`http://example.com/optimade/v1/trajectories/traj00000001`
+
+.. code:: jsonc
+
+  {
+    "data":{
+      "id": "traj00000001",
+      "type": "trajectories",
+      "attributes": {
+        "last_modified":"2021-07-16T18:02:03Z",
+        "elements": ["H","O"],
+        "nelements": 2,
+        "elements_ratios": [0.666667,0.333333],
+        "chemical_formula_descriptive": "H2O",
+        "chemical_formula_reduced": "H2O",
+        "chemical_formula_anonymous": "A2B",
+        "dimension_types":[0,0,0],
+        "nperiodic_dimensions": 0,
+        "lattice_vectors" : [[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]],
+        "cartesian_site_positions" : null,
+        "nsites":3,
+        "species_at_sites":["O1","H1","H2"],
+        "species":[
+          {
+            "name":"O1",
+            "chemical_symbols":["O"],
+            "concentration":[1.0]
+          },
+          {
+            "name":"H1",
+            "chemical_symbols":["H"],
+            "concentration":[1.0]
+          },
+          {
+            "name":"H2",
+            "chemical_symbols":["H"],
+            "concentration":[1.0]
+          }
+        ],
+        "reference_frame": 1,
+        "nframes": 360,
+        "_exmpl_temperature_set": null,
+        "_exmpl_ekin": null
+      },
+      "meta":{
+        "more_data_available": true,
+        "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, _exmpl_temperature_set, _exmpl_ekin&property_ranges=",
+        "cartesian_site_positions" : {
+          "range": {
+            "dim_size": [360, 3, 3],
+            "nvalues": 3240,
+            "range_ids": ["frames", "particles", "xyz"],
+            "indexable_dim": ["frames", "particles"],
+            "data_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 360,
+                "step": 1
+              },{
+                "name": "particles",
+                "start": 1,
+                "stop": 3,
+                "step": 1
+              },{
+                "name": "xyz",
+                "start": 1,
+                "stop": 3,
+                "step": 1
+              },
+            ],
+            "contains_null": false,
+            "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions&property_ranges=frames(1,360,1)",
+            "more_data_available": true
+          }
+        },
+        "_exmpl_temperature_set":{
+          "range": {
+            "dim_size": [360],
+            "nvalues": 144,
+            "range_ids": ["frames"],
+            "indexable_dim": ["frames"],
+            "data_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 360,
+                "step": null
+              }
+            ],
+            "contains_null": false,
+            "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=_exmpl_ekin&property_ranges=frames(1,360,1)",
+            "more_data_available": true
+          }
+        },
+        "_exmpl_ekin":{
+          "range": {
+            "dim_size": [360],
+            "nvalues": 180,
+            "range_ids": ["frames"],
+            "indexable_dim": ["frames"],
+            "data_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 360,
+                "step": 2
+              }
+            ],
+            "contains_null": false,
+            "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=_exmpl_ekin&property_ranges=frames(1,360,2)",
+            "more_data_available": true
+          }
+        }
+      },
+      "relationships": {
+        "references": {
+          "data": [
+            {
+              "type": "references",
+              "id": "dummy/2019"
+            }
+          ]
+        }
+      }
+    }
+    //...
+  }
+Upon having performed the above query, the following query can be performed to return trajectory data:
+:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions,_exmpl_ekin,_exmpl_temperature_set&property_ranges=`
+
+.. code:: jsonc
+
+  {
+    "data":{
+      "id": "traj00000001",
+      "type": "trajectories",
+      "attributes":{
+        "last_modified":"2021-07-16T18:02:03Z",
+        "cartesian_site_positions":[
+            [[2,2,2],[1.238,2.000,1.416],[2.762,2.000,1.416]],
+            [[2,2,2],[1.238,2.013,1.416],[2.762,1.987,1.416]],
+            [[2,2,2],[1.238,2.027,1.416],[2.762,1.973,1.416]],
+            [[2,2,2],[1.239,2.040,1.416],[2.761,1.960,1.416]],
+            [[2,2,2],[1.240,2.053,1.416],[2.760,1.947,1.416]],
+            [[2,2,2],[1.241,2.066,1.416],[2.759,1.934,1.416]],
+            [[2,2,2],[1.242,2.080,1.416],[2.758,1.920,1.416]],
+            [[2,2,2],[1.244,2.093,1.416],[2.756,1.907,1.416]],
+            [[2,2,2],[1.245,2.106,1.416],[2.755,1.894,1.416]],
+            [[2,2,2],[1.247,2.119,1.416],[2.753,1.881,1.416]],
+            [[2,2,2],[1.250,2.132,1.416],[2.750,1.868,1.416]]
+            //...
+          ],
+        "_exmpl_temperature_set": [293.0,293.1,293.2,293.3,293.4,293.5
+          //...
+        ],
+        "_exmpl_ekin": [4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21
+          //...
+        ]
+      },
+      "meta":{
+        "more_data_available": true,
+        "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, _exmpl_temperature_set, _exmpl_ekin&property_ranges=frames(101,360,1)",
+        "cartesian_site_positions":{
+          "range": {
+            "dim_size": [360, 3, 3],
+            "nvalues": 3240,
+            "range_ids": ["frames", "particles", "xyz"],
+            "indexable_dim": ["frames", "particles"],
+            "data_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 360,
+                "step": 1
+              },{
+                "name": "particles",
+                "start": 1,
+                "stop": 3,
+                "step": 1
+              },{
+                "name": "xyz",
+                "start": 1,
+                "stop": 3,
+                "step": 1
+              },
+            ],
+            "contains_null": false,
+            "more_data_available": true,
+            "nreturned_values": 900,
+            "returned_range":[{
+               "name": "frames",
+                "start": 1,
+                "stop": 100,
+                "step": 1
+              },{
+                "name": "particles",
+                "start": 1,
+                "stop": 3,
+                "step": 1
+              },{
+                "name": "xyz",
+                "start": 1,
+                "stop": 3,
+                "step": 1}
+            ],
+            "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions&property_ranges=frames(101,360,1)"
+          }
+        },
+        "_exmpl_temperature_set":{
+          "range":{
+            "dim_size": [360],
+            "nvalues": 144,
+            "range_ids": ["frames"],
+            "indexable_dim": ["frames"],
+            "data_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 360,
+                "step": null
+              }
+            ],
+            "contains_null": false,
+            "indexes": [[1],[3],[6],[8],[11],[13],[16],[18],[21],[23],[26],[28],[31],[33],[36],[38],[41]
+              //...
+            ],
+            "nreturned_values": 40,
+            "returned_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 100,
+                "step": 1
+              }
+            ],
+            "more_data_available": true,
+            "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=_exmpl_temperature_set&property_ranges=frames(101,360,1)
+          }
+        },
+        "_exmpl_ekin":{
+          "range": {
+            "dim_size": [360],
+            "nvalues": 180,
+            "range_ids": ["frames"],
+            "indexable_dim": ["frames"],
+            "data_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 360,
+                "step": 2
+              }
+            ],
+            "contains_null": false,
+            "nreturned_values": 50,
+            "returned_range": [
+              {
+                "name": "frames",
+                "start": 1,
+                "stop": 100,
+                "step": 2
+              }
+            ],
+            "more_data_available": true,
+            "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=_exmpl_ekin&property_ranges=frames(101,360,1)"
+          }
+        }
+      }
+    }
+    //...
+  }
+
 Calculations Entries
 --------------------