From f49193d7ae3a4d4e8cda0135f87872d8aa24db5e Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 20 Jul 2021 12:10:01 +0200 Subject: [PATCH 01/57] Added specification for the trajectories endpoint --- optimade.rst | 343 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 339 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index 9c0f49457..54facf9b5 100644 --- a/optimade.rst +++ b/optimade.rst @@ -149,7 +149,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH For example, a :entry:`structures` entry is comprised by data that pertain to a single structure. **Entry type** - Entries are categorized into types, e.g., :entry:`structures`, :entry:`calculations`, :entry:`references`. + Entries are categorized into types, e.g., :entry:`structures`, :entry:`trajectories` :entry:`calculations`, :entry:`references`. Entry types MUST be named according to the rules for identifiers. **Entry property** @@ -1067,6 +1067,7 @@ Example: "entry_types_by_format": { "json": [ "structures", + "trajectories", "calculations" ], "xml": [ @@ -1075,6 +1076,7 @@ Example: }, "available_endpoints": [ "structures", + "trajectories", "calculations", "info", "links" @@ -1447,7 +1449,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 (``.``). @@ -1749,6 +1750,7 @@ type - **Examples**: - :val:`"structures"` + - :val:`"trajectories"` immutable\_id ~~~~~~~~~~~~~ @@ -1802,7 +1804,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 @@ -2036,7 +2037,6 @@ lattice\_vectors - **Description**: The three lattice vectors in Cartesian coordinates, in ångström (Å). - **Type**: list of list of floats or unknown values. - **Requirements/Conventions**: - - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. @@ -2318,6 +2318,341 @@ structure\_features - A structure having implicit atoms and using assemblies: :val:`["assemblies", "implicit_atoms"]` +Trajectories Entries +-------------------- + +- **Description**: The :entry:`trajectories` contains data belonging to a set of structures. These structures are for example related because they were created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. Some examples of this data are: particle positions, pressure and energies. :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties `reference\_structure`_,`reference\_frame`_,`nframes`_, `available_properties`_ and `next_part_trajectory`_. Next to this they can optionally have all the fields of the structures entries as well as database specific fields. + +The reference_structure holds an example structure which can be queried in the same way as the structures in the structures end point. +The data belonging to the actual trajectory is only returned when this is specifically requested in the `response_field`_ parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. Querries on individual frames are currently not supported. + +reference\_structure +~~~~~~~~~~~~~~~~~~~~ +.. Or should we only supply a link to a regular structure entry and let people search by looking for structures with a trajectory reference? + +- **Description**: This is an example structure which can be used to select trajectories with queries and to give a quick visualization of the kind of structure in the trajectory. +- **Type**: dictionary +- **Requirements/Conventions**: +- Each trajectory MUST have a reference structure. +- This reference structure MAY be one of the frames from the trajectory, in that case the reference\_frame field MUST specify which frame has been used. +- Querries on the trajectories MUST be done on the information supplied in the reference\_structure. The subfields of the reference structure MUST have the same queryability as in the structure endpoint. + + This reference frame has the same properties as the structure entries namely: + - `elements`_ + - `nelements`_ + - `elements\_ratios`_ + - `chemical\_formula\_descriptive`_ + - `chemical\_formula\_reduced`_ + - `chemical\_formula\_hill`_ + - `chemical\_formula\_anonymous`_ + - `dimension\_types`_ + - `nperiodic\_dimensions`_ + - `lattice\_vectors`_ + - `cartesian\_site\_positions`_ + - `nsites`_ + - `species\_at\_sites`_ + - `species`_ + - `assemblies`_ + - `structure\_features`_ + +It can also have a 'relationships'_ field for references that apply to the entire trajectory rather than to a single frame. + +reference\_frame +~~~~~~~~~~~~~~~~ +- **Description**: The number of the frame at which the reference structure was taken. +- **Type**: integer +- **Requirements/Conventions**: + + - **Support**: MUST be supported if the reference frame is taken from the trajectory, if the reference structure is not in the trajectory, the value, if present, MUST 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:`42` + +nframes +~~~~~~~ + +- **Description**: The number of the frames in the trajectory. +- **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. + +- **Examples**: + + - :val:`42` + +- **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`. + + +available_properties +~~~~~~~~~~~~~~~~~~~~ + +.. Under info/trajectories there should already be a list of properties, but I am not sure we want to assume that all trajectories within a database have all properties. +.. By having a separate field, with all the properties in this trajectory it should be easy to search for trajectories with a particular property. + +- **Description**: A list of the names of the properties for which data is available in the trajectory. It is up to the server to decide which properties to share and there are no Mandatory fields. When sharing cartesian\_site\_positions the lattice_vectors, dimension_types and species_list MUST, however, be shared as well. +- **Type**: List of strings +- **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. + +- **Examples**: + + - :val:`["cartesian\_site\_positions","_exmpl_Pressure"]` + +next_part_trajectory +~~~~~~~~~~~~~~~~~~~~ +- **Description**: When the returned number of frames is less than the total number of frames requested by the client the server MUST supply a link which the client can use to download the remainder of the trajectory. +- **Type**: Link +- **Requirements/Conventions**: + - **Support**: MUST be present when the number of returned frames is smaller than the number of requested frames. MUST NOT be present otherwise. +- **Examples**: + + - :query-url:`/` + + +Retrieving the trajectory data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. Should I specify this or is this already covered sufficiently in the description of the response\_field? + +The preceding properties as well as any relationship fields(see `Relationships Used by Multiple Entry Types`_) and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no response\_fields property(see the section `Entry Listing URL Query Parameters`_) is specified. + +The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response\_fields. + +Next to this the Client MAY specify the following parameters to customize the return from the server. +While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. + +- **first_frame**: + - **Description**: **first_frame** specifies the first frame that should be returned. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less or equal to nframes.(The total number of frames in the trajectory) The default value is 0. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Examples**::query-url:`/trajectories?first_frame=1000`. +- **last_frame**: + - **Description**: **last_frame** specifies the last frame that should be returned. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less or equal to nframes. The default value is nframes.If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Examples**::query-url:`/trajectories?first_frame=1000`. + - **Examples**::query-url:`/trajectories?last_frame=2000`. + +- **frame_step**: + - **Description**: Specifies that only one out of every **frame_step** steps should be returned. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less or equal to . The default value is 1. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Examples**::query-url:`/trajectories?first_frame=1000`. + - **Examples**::query-url:`/trajectories?frame_step=10`. + + +.. The reason that there is a maximum number to the number of frames that are returned is that trajectories may be larger than the amount of memory available and JSON files should be processed whole. + +The server can decide how many frames are returned for each request. If the number of frames returned is less than the total number of frames requested by a client the server has to supply a link **next_part_trajectory** from which the remainder of the trajectory can be downloaded. + + +Return format for Trajectory Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The data is returned in a data major format. i.e. the properties form the highest nesting level. Each property has a dictionary as the value with the fields. The property can be any of the fields described under the structures endpoint as well as a reference entry or a database specific field. + +- **frame_encoding**: + - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. This is specified by the frame encoding parameter. + - **Type**: string + - **Requirements/Conventions**: The value Must be present. + - **Values**: + - **constant**: The value of the property is constant and thus has the same value for each frame in the trajectory. + - **explicit**: A value is given for each frame. The number of values must thus be equal to the number of frames. If for some reason a there is no value for a particular frame the value should be :val:`null`. + - **linear**: The value depends linearly on the frame number. + - **explicit_regular_sparse**: The value is set at every **offset_sparse** * **step_size_sparse** frames. + - **explicit_custom_sparse** : A separate list with frame numbers is present to indicate to which frame a value belongs. + +- **offset_linear**: + - **Description**: If **frame_encoding** is set to linear this property gives the value at frame 0. + - **Type**: float + - **Requirements/Conventions**: The value MAY be present when frame_encoding == linear, otherwise the value MUST NOT be present. The default value is 0. + - **Examples**: + - :val:`1.5` + +- **step_size_linear**: + - **Description**: If **frame_encoding** is set to linear, this value gives the increase/decrease in the value of the property when going from one frame to the next. + - **Type**: float + - **Requirements/Conventions**: The value MUST be present when frame_encoding == linear. Otherwise it MUST NOT be present. + - **Examples**: + - :val:`0.0005` + +- **offset_sparse**: + - **Description**: If **frame_encoding** is set to explicit_regular_sparse this property gives the frame number to which the first value belongs. + - **Type**: integer + - **Requirements/Conventions**: The value MAY be present when frame_encoding is set to explicit_regular_sparse, otherwise the value MUST NOT be present. The default value is 0. + - **Examples**: + - :val:`100` + +- **step_size_sparse**: + - **Description**: If **frame_encoding** is set to explicit_regular_sparse, this value indicates that every step_size_sparse frames a value is defined. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_regular_sparse. Otherwise it MUST NOT be present. + - **Examples**: + - :val:`100` + +- **frame_number**: + - **Description**: If **frame_encoding** is set to explicit_custom_sparse, this field holds the frames to which the values in the value field belong. + - **Type**: List of integers + - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_custom_sparse. Otherwise it MUST NOT be present. + - **Examples**: + - :val:`[0,20,78,345]` + +- **values**: + - **Description**: The values belonging to this property. The format of this field depends on the property and on the frame_encoding parameter. + - **Type**: Any + - **Requirements/Conventions**: The value MUST be present. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be usefull for grand canonical simulations where the number of particles in the simulation volume is not constant. + +Example of returned trajectory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is an example of a JSON object that could be returned after the following query: +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001` + +.. code:: jsonc + { + "reference_structure":{ + "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" : [[2.0,2.0,2.0],[1.238,2.0,1.416],[2.762,2.0,1.416]], + "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], + } + ] + }, + "id": "traj00000001", + "type": "trajectories", + "last_modified":"2021-07-16T18:02:03Z" + "reference_frame": 359, + "nframes": 360 + "relationships": { + "references": { + "data": [ + { + "type": "references", + "id": "dummy/2019" + } + ] + } + } + "available_properties":[ + "cartesian_site_positions", + "species", + "dimension_types", + "lattice_vectors", + "species_at_sites", + "_exmpl_temperature_set", + "_exmpl_time", + "_exmpl_ekin" + ] + } + +After the previous querry is an example of a JSON object that could be returned after the following query: +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships,&first_frame=0&frame_step=5` + +.. code:: jsonc + { + "id": "traj00000001", + "type": "trajectories", + "cartesian_site_positions":{ + "frame_encoding": "explicit", + "values": [ + [[2.0,2.0,2.0],[1.238,2.0,1.416],[2.762,2.0,1.416]], + [[2,2,2],[1.241,2.066,1.416],[2.759,1.934,1.416]], + [[2,2,2],[1.250,2,132,1.416],[2.750,1.868,1,416]], + [[2,2,2],[1.264,2.197,1.416],[2.736,1.803,1,416]], + [[2,2,2],[1.284,2.261,1.416],[2.716,1.739,1,416]], + [[2,2,2],[1.309,2.322,1.416],[2.691,1.678,1,416]] + ] + }, + "lattice_vectors":{ + "frame_encoding": "constant", + "values:[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]], + }, + "dimension_types":{ + "frame_encoding": "constant", + "values:[0,0,0] + }, + "_exmpl_time":{ + "frame_encoding": "linear", + "offset_linear": 0, + "step_size_linear": 1.5 + }, + "_exmpl_ekin":{ + "frame_encoding": "explicit_regular_sparse", + "step_size_sparse": 10, + "values":[4.1100E-21,4.1102E-21,4.1103-21] + }, + "species" : { + "frame_encoding": "constant", + "values": [ + { + "name":"O1", + "chemical_symbols":["O"], + "concentration":[1.0], + },{ + "name":"H1", + "chemical_symbols":["H"], + "concentration":[1.0], + },{ + "name":"H2", + "chemical_symbols":["H"], + "concentration":[1.0], + } + ] + }, + "species_at_sites":{ + "frame_encoding": "constant", + "values":["O1","H1","H2"], + }, + "structures":{ + "frame_encoding": "explicit_custom_sparse", + "frame_number" : [0,5,20] + "values": { + "data": { + "type": "structures", + "id": "example.db:structs:1234", + } + } + }, + "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species&first_frame=30&frame_step=5" + } + Calculations Entries -------------------- From 95092cddd431749aff1176bc157750b7ae87c5d2 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 20 Jul 2021 16:03:44 +0200 Subject: [PATCH 02/57] Made corrections to the indentation levels --- optimade.rst | 181 ++++++++++++++++++++++++++++----------------------- 1 file changed, 101 insertions(+), 80 deletions(-) diff --git a/optimade.rst b/optimade.rst index 54facf9b5..c82d8c1fc 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2321,10 +2321,7 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` contains data belonging to a set of structures. These structures are for example related because they were created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. Some examples of this data are: particle positions, pressure and energies. :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties `reference\_structure`_,`reference\_frame`_,`nframes`_, `available_properties`_ and `next_part_trajectory`_. Next to this they can optionally have all the fields of the structures entries as well as database specific fields. - -The reference_structure holds an example structure which can be queried in the same way as the structures in the structures end point. -The data belonging to the actual trajectory is only returned when this is specifically requested in the `response_field`_ parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. Querries on individual frames are currently not supported. +- **Description**: The :entry:`trajectories` contains data belonging to a set of structures. These structures are for example related because they were created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. Some examples of this data are: particle positions, pressure and energies. :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties `reference\_structure`_, `reference\_frame`_, `nframes`_, `available_properties`_ and `next_part_trajectory`_. Next to this they can optionally have all the fields of the structures entries as well as database specific fields. The reference_structure holds an example structure which can be queried in the same way as the structures in the structures end point. The data belonging to the actual trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. Querries on individual frames are currently not supported. reference\_structure ~~~~~~~~~~~~~~~~~~~~ @@ -2333,11 +2330,13 @@ reference\_structure - **Description**: This is an example structure which can be used to select trajectories with queries and to give a quick visualization of the kind of structure in the trajectory. - **Type**: dictionary - **Requirements/Conventions**: -- Each trajectory MUST have a reference structure. -- This reference structure MAY be one of the frames from the trajectory, in that case the reference\_frame field MUST specify which frame has been used. -- Querries on the trajectories MUST be done on the information supplied in the reference\_structure. The subfields of the reference structure MUST have the same queryability as in the structure endpoint. - This reference frame has the same properties as the structure entries namely: + - Each trajectory MUST have a reference structure. + - This reference structure MAY be one of the frames from the trajectory, in that case the reference\_frame field MUST specify which frame has been used. + - Querries on the trajectories MUST be done on the information supplied in the reference\_structure when the property is in the reference_frame. The subfields of the reference structure MUST have the same queryability as in the structure endpoint. + + - This reference frame has the same properties as the structure entries namely: + - `elements`_ - `nelements`_ - `elements\_ratios`_ @@ -2355,21 +2354,21 @@ reference\_structure - `assemblies`_ - `structure\_features`_ -It can also have a 'relationships'_ field for references that apply to the entire trajectory rather than to a single frame. + - It can also have a 'relationships'_ field for references that apply to the entire trajectory rather than to a single frame. reference\_frame ~~~~~~~~~~~~~~~~ + - **Description**: The number of the frame at which the reference structure was taken. - **Type**: integer - **Requirements/Conventions**: - - **Support**: MUST be supported if the reference frame is taken from the trajectory, if the reference structure is not in the trajectory, the value, if present, MUST be :val:`null`. - - - **Query**: Support for queries on this property is OPTIONAL. + - **Support**: MUST be supported if the reference frame is taken from the trajectory, if the reference structure is not in the trajectory, the value, if present, MUST 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:`42` + - :val:`42` nframes ~~~~~~~ @@ -2377,17 +2376,14 @@ nframes - **Description**: The number of the frames in the trajectory. - **Type**: integer - **Requirements/Conventions**: - - **Support**: MUST be supported by all implementations, i.e., + + - **Support**: MUST be supported by all implementations, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all + - **Query**: MUST be a queryable property with support for all mandatory filter features. - - The integer value MUST be equal to the length of the + - 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. - -- **Examples**: - - - :val:`42` + - The integer MUST be a positive non-zero value. - **Querying**: - A filter that matches trajectories that have exactly 100 frames: @@ -2395,6 +2391,9 @@ nframes - A filter that matches trajectories that have between 100 and 1000 frames: - :filter:`nframes>=100 AND nframes<=1000`. +- **Examples**: + + - :val:`42` available_properties ~~~~~~~~~~~~~~~~~~~~ @@ -2405,9 +2404,10 @@ available_properties - **Description**: A list of the names of the properties for which data is available in the trajectory. It is up to the server to decide which properties to share and there are no Mandatory fields. When sharing cartesian\_site\_positions the lattice_vectors, dimension_types and species_list MUST, however, be shared as well. - **Type**: List of strings - **Requirements/Conventions**: - - **Support**: MUST be supported by all implementations, i.e., + + - **Support**: MUST be supported by all implementations, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all + - **Query**: MUST be a queryable property with support for all mandatory filter features. - **Examples**: @@ -2419,10 +2419,11 @@ next_part_trajectory - **Description**: When the returned number of frames is less than the total number of frames requested by the client the server MUST supply a link which the client can use to download the remainder of the trajectory. - **Type**: Link - **Requirements/Conventions**: - - **Support**: MUST be present when the number of returned frames is smaller than the number of requested frames. MUST NOT be present otherwise. + + - **Support**: MUST be present when the number of returned frames is smaller than the number of requested frames. MUST NOT be present otherwise. - **Examples**: - - :query-url:`/` + - :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships,&first_frame=0&frame_step=5` Retrieving the trajectory data @@ -2438,24 +2439,31 @@ Next to this the Client MAY specify the following parameters to customize the re While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. - **first_frame**: - - **Description**: **first_frame** specifies the first frame that should be returned. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less or equal to nframes.(The total number of frames in the trajectory) The default value is 0. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. - - **Examples**::query-url:`/trajectories?first_frame=1000`. + + - **Description**: **first_frame** specifies the first frame that should be returned. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less or equal to nframes.(The total number of frames in the trajectory) The default value is 0. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Examples**: + + - :query-url:`/trajectories/traj00000001?first_frame=1000`. + - **last_frame**: - - **Description**: **last_frame** specifies the last frame that should be returned. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less or equal to nframes. The default value is nframes.If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. - - **Examples**::query-url:`/trajectories?first_frame=1000`. - - **Examples**::query-url:`/trajectories?last_frame=2000`. + + - **Description**: **last_frame** specifies the last frame that should be returned. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less or equal to nframes. The default value is nframes.If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Examples**: + + - :query-url:`/trajectories/traj00000001?last_frame=2000`. - **frame_step**: - - **Description**: Specifies that only one out of every **frame_step** steps should be returned. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less or equal to . The default value is 1. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. - - **Examples**::query-url:`/trajectories?first_frame=1000`. - - **Examples**::query-url:`/trajectories?frame_step=10`. + - **Description**: Specifies that only one out of every **frame_step** steps should be returned. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less or equal to . The default value is 1. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Examples**: + + - :query-url:`/trajectories/traj00000001?frame_step=10`. .. The reason that there is a maximum number to the number of frames that are returned is that trajectories may be larger than the amount of memory available and JSON files should be processed whole. @@ -2468,55 +2476,68 @@ Return format for Trajectory Data The data is returned in a data major format. i.e. the properties form the highest nesting level. Each property has a dictionary as the value with the fields. The property can be any of the fields described under the structures endpoint as well as a reference entry or a database specific field. - **frame_encoding**: - - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. This is specified by the frame encoding parameter. - - **Type**: string - - **Requirements/Conventions**: The value Must be present. - - **Values**: - - **constant**: The value of the property is constant and thus has the same value for each frame in the trajectory. - - **explicit**: A value is given for each frame. The number of values must thus be equal to the number of frames. If for some reason a there is no value for a particular frame the value should be :val:`null`. - - **linear**: The value depends linearly on the frame number. - - **explicit_regular_sparse**: The value is set at every **offset_sparse** * **step_size_sparse** frames. - - **explicit_custom_sparse** : A separate list with frame numbers is present to indicate to which frame a value belongs. - -- **offset_linear**: - - **Description**: If **frame_encoding** is set to linear this property gives the value at frame 0. - - **Type**: float - - **Requirements/Conventions**: The value MAY be present when frame_encoding == linear, otherwise the value MUST NOT be present. The default value is 0. - - **Examples**: - - :val:`1.5` + + - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. This is specified by the frame encoding parameter. + - **Type**: string + - **Requirements/Conventions**: The value Must be present. + - **Values**: + + - **constant**: The value of the property is constant and thus has the same value for each frame in the trajectory. + - **explicit**: A value is given for each frame. The number of values must thus be equal to the number of frames. If for some reason a there is no value for a particular frame the value should be :val:`null`. + - **linear**: The value depends linearly on the frame number. + - **explicit_regular_sparse**: The value is set at every **offset_sparse** * **step_size_sparse** frames. + - **explicit_custom_sparse** : A separate list with frame numbers is present to indicate to which frame a value belongs. + +- **offset_linear**: + + - **Description**: If **frame_encoding** is set to linear this property gives the value at frame 0. + - **Type**: float + - **Requirements/Conventions**: The value MAY be present when frame_encoding == linear, otherwise the value MUST NOT be present. The default value is 0. + - **Examples**: + + - :val:`1.5` - **step_size_linear**: - - **Description**: If **frame_encoding** is set to linear, this value gives the increase/decrease in the value of the property when going from one frame to the next. - - **Type**: float - - **Requirements/Conventions**: The value MUST be present when frame_encoding == linear. Otherwise it MUST NOT be present. - - **Examples**: - - :val:`0.0005` - -- **offset_sparse**: - - **Description**: If **frame_encoding** is set to explicit_regular_sparse this property gives the frame number to which the first value belongs. - - **Type**: integer - - **Requirements/Conventions**: The value MAY be present when frame_encoding is set to explicit_regular_sparse, otherwise the value MUST NOT be present. The default value is 0. - - **Examples**: - - :val:`100` + + - **Description**: If **frame_encoding** is set to linear, this value gives the increase/decrease in the value of the property when going from one frame to the next. + - **Type**: float + - **Requirements/Conventions**: The value MUST be present when frame_encoding == linear. Otherwise it MUST NOT be present. + - **Examples**: + + - :val:`0.0005` + +- **offset_sparse**: + + - **Description**: If **frame_encoding** is set to explicit_regular_sparse this property gives the frame number to which the first value belongs. + - **Type**: integer + - **Requirements/Conventions**: The value MAY be present when frame_encoding is set to explicit_regular_sparse, otherwise the value MUST NOT be present. The default value is 0. + - **Examples**: + + - :val:`100` - **step_size_sparse**: - - **Description**: If **frame_encoding** is set to explicit_regular_sparse, this value indicates that every step_size_sparse frames a value is defined. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_regular_sparse. Otherwise it MUST NOT be present. - - **Examples**: - - :val:`100` + + - **Description**: If **frame_encoding** is set to explicit_regular_sparse, this value indicates that every step_size_sparse frames a value is defined. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_regular_sparse. Otherwise it MUST NOT be present. + - **Examples**: + + - :val:`100` - **frame_number**: - - **Description**: If **frame_encoding** is set to explicit_custom_sparse, this field holds the frames to which the values in the value field belong. - - **Type**: List of integers - - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_custom_sparse. Otherwise it MUST NOT be present. - - **Examples**: - - :val:`[0,20,78,345]` + + - **Description**: If **frame_encoding** is set to explicit_custom_sparse, this field holds the frames to which the values in the value field belong. + - **Type**: List of integers + - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_custom_sparse. Otherwise it MUST NOT be present. + - **Examples**: + + - :val:`[0,20,78,345]` - **values**: - - **Description**: The values belonging to this property. The format of this field depends on the property and on the frame_encoding parameter. - - **Type**: Any - - **Requirements/Conventions**: The value MUST be present. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be usefull for grand canonical simulations where the number of particles in the simulation volume is not constant. + + - **Description**: The values belonging to this property. The format of this field depends on the property and on the frame_encoding parameter. + - **Type**: Any + - **Requirements/Conventions**: The value MUST be present. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be usefull for grand canonical simulations where the number of particles in the simulation volume is not constant. Example of returned trajectory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From a291b5950cc79fcc75921d2ebb75e4acfea49d66 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 20 Jul 2021 19:10:03 +0200 Subject: [PATCH 03/57] Multiple small corrections for the trajectories entry Placed all sentences on seperate lines. --- optimade.rst | 197 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 117 insertions(+), 80 deletions(-) diff --git a/optimade.rst b/optimade.rst index c82d8c1fc..4535fe33b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -149,7 +149,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH For example, a :entry:`structures` entry is comprised by data that pertain to a single structure. **Entry type** - Entries are categorized into types, e.g., :entry:`structures`, :entry:`trajectories` :entry:`calculations`, :entry:`references`. + Entries are categorized into types, e.g., :entry:`structures`, :entry:`trajectories`, :entry:`calculations`, :entry:`references`. Entry types MUST be named according to the rules for identifiers. **Entry property** @@ -2037,6 +2037,7 @@ lattice\_vectors - **Description**: The three lattice vectors in Cartesian coordinates, in ångström (Å). - **Type**: list of list of floats or unknown values. - **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. @@ -2321,19 +2322,30 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` contains data belonging to a set of structures. These structures are for example related because they were created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. Some examples of this data are: particle positions, pressure and energies. :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties `reference\_structure`_, `reference\_frame`_, `nframes`_, `available_properties`_ and `next_part_trajectory`_. Next to this they can optionally have all the fields of the structures entries as well as database specific fields. The reference_structure holds an example structure which can be queried in the same way as the structures in the structures end point. The data belonging to the actual trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. Querries on individual frames are currently not supported. +- **Description**: The :entry:`trajectories` entry point contains data belonging to a set of structures. + These structures are related because they were, for example, created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. + 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 following properties `reference\_structure`_, `reference\_frame`_, `nframes`_, `available_properties`_ and `next_part_trajectory`_. + Next to this they can optionally have all the fields of the structures entries, including relationships, as well as database specific fields. + + The `reference\_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. + The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. + In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. + It is possible to request only part of a trajectory and to request only 1 out of every n frames. + Queries on individual frames are currently not supported. reference\_structure ~~~~~~~~~~~~~~~~~~~~ -.. Or should we only supply a link to a regular structure entry and let people search by looking for structures with a trajectory reference? -- **Description**: This is an example structure which can be used to select trajectories with queries and to give a quick visualization of the kind of structure in the trajectory. +- **Description**: This is an example of the structures that can be found in the trajectory. + It can be used to select trajectories with queries and to give a quick visual impression of the structures in this trajectory. - **Type**: dictionary - **Requirements/Conventions**: - - Each trajectory MUST have a reference structure. - - This reference structure MAY be one of the frames from the trajectory, in that case the reference\_frame field MUST specify which frame has been used. - - Querries on the trajectories MUST be done on the information supplied in the reference\_structure when the property is in the reference_frame. The subfields of the reference structure MUST have the same queryability as in the structure endpoint. + - Each trajectory MUST have a reference_structure. + - This reference_structure MAY be one of the frames from the trajectory, in that case the `reference\_frame`_ field MUST specify which frame has been used. + - Queries on the trajectories MUST be done on the information supplied in the reference\_structure when the queried property is in the reference\_structure. + The subfields of the reference\_structure MUST have the same queryability as in the `structures entries`_. - This reference frame has the same properties as the structure entries namely: @@ -2354,7 +2366,7 @@ reference\_structure - `assemblies`_ - `structure\_features`_ - - It can also have a 'relationships'_ field for references that apply to the entire trajectory rather than to a single frame. + - It MAY also have a 'relationships'_ field for references that apply to the entire trajectory rather than to a single frame. reference\_frame ~~~~~~~~~~~~~~~~ @@ -2363,11 +2375,13 @@ reference\_frame - **Type**: integer - **Requirements/Conventions**: - - **Support**: MUST be supported if the reference frame is taken from the trajectory, if the reference structure is not in the trajectory, the value, if present, MUST be :val:`null`. + - **Support**: MUST be supported if the reference frame is taken from the trajectory. + If the reference structure is not in the trajectory, the value MUST NOT be present. - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. + If supported, filters MAY support only a subset of comparison operators. - **Examples**: + - :val:`42` nframes @@ -2376,20 +2390,18 @@ nframes - **Description**: The number of the frames in the trajectory. - **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. + + - **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`. + + - 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**: @@ -2398,154 +2410,173 @@ nframes available_properties ~~~~~~~~~~~~~~~~~~~~ -.. Under info/trajectories there should already be a list of properties, but I am not sure we want to assume that all trajectories within a database have all properties. -.. By having a separate field, with all the properties in this trajectory it should be easy to search for trajectories with a particular property. - -- **Description**: A list of the names of the properties for which data is available in the trajectory. It is up to the server to decide which properties to share and there are no Mandatory fields. When sharing cartesian\_site\_positions the lattice_vectors, dimension_types and species_list MUST, however, be shared as well. +- **Description**: A list of the names of the properties for which data is available in the trajectory. + It is up to the server to decide which properties to share and there are no mandatory fields. + When sharing `cartesian\_site\_positions`_ the lattice_vectors, species, dimension_types and species_at_sites MUST be shared as well. - **Type**: List of strings - **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. + - **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. - **Examples**: - - :val:`["cartesian\_site\_positions","_exmpl_Pressure"]` + - :val:`["cartesian\_site\_positions","lattice_vectors","species","dimension_types","species_at_sites","_exmpl_Pressure"]` next_part_trajectory ~~~~~~~~~~~~~~~~~~~~ -- **Description**: When the returned number of frames is less than the total number of frames requested by the client the server MUST supply a link which the client can use to download the remainder of the trajectory. +- **Description**: This is a link the client can use to download the remainder of the trajectory data when the server returns fewer frames than the client requested. - **Type**: Link - **Requirements/Conventions**: - - **Support**: MUST be present when the number of returned frames is smaller than the number of requested frames. MUST NOT be present otherwise. + - **Support**: MUST be present when the number of returned frames is smaller than the number of requested frames. + MUST NOT be present otherwise. - **Examples**: + If, for example, the server has returned data on the first 30 frames it could provide this link to the client to download the next part of the trajectory. - - :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships,&first_frame=0&frame_step=5` + - :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,species,species_at_sites&first_frame=30` Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. Should I specify this or is this already covered sufficiently in the description of the response\_field? - -The preceding properties as well as any relationship fields(see `Relationships Used by Multiple Entry Types`_) and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no response\_fields property(see the section `Entry Listing URL Query Parameters`_) is specified. +The preceding properties 7.3.1-4 and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response\_fields property` (see the section `Entry Listing URL Query Parameters`_) is specified. The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response\_fields. -Next to this the Client MAY specify the following parameters to customize the return from the server. +Next to this the client MAY specify the following parameters to customize the return from the server. While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. +The numbering of the frames is zero based, so the first frame is frame number 0. - **first_frame**: - **Description**: **first_frame** specifies the first frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less or equal to nframes.(The total number of frames in the trajectory) The default value is 0. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less than or equal to nframes.(The total number of frames in the trajectory) + If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. + The default value is 0. - **Examples**: - - :query-url:`/trajectories/traj00000001?first_frame=1000`. + - :query-url:`/trajectories/traj00000001?first_frame=1000` - **last_frame**: - **Description**: **last_frame** specifies the last frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less or equal to nframes. The default value is nframes.If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less than or equal to nframes(the total number of frames in the trajectory). + If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. + The default value is nframes. - **Examples**: - - :query-url:`/trajectories/traj00000001?last_frame=2000`. + - :query-url:`/trajectories/traj00000001?last_frame=2000` - **frame_step**: - - **Description**: Specifies that only one out of every **frame_step** steps should be returned. + - **Description**: Specifies that data should only be returned for one out of every **frame_step** frames. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less or equal to . The default value is 1. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect name. + - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less than or equal to the total number of frames. + If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. + The default value is 1. - **Examples**: - :query-url:`/trajectories/traj00000001?frame_step=10`. -.. The reason that there is a maximum number to the number of frames that are returned is that trajectories may be larger than the amount of memory available and JSON files should be processed whole. - -The server can decide how many frames are returned for each request. If the number of frames returned is less than the total number of frames requested by a client the server has to supply a link **next_part_trajectory** from which the remainder of the trajectory can be downloaded. - +The server can decide how many frames are returned for each request. +If the number of frames returned is less than the total number of frames requested by a client the server has to supply a link in the field `next_part_trajectory`_ which the client can use to download the rest of the trajectory. Return format for Trajectory Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The data is returned in a data major format. i.e. the properties form the highest nesting level. Each property has a dictionary as the value with the fields. The property can be any of the fields described under the structures endpoint as well as a reference entry or a database specific field. +The returned data is first grouped per property and then by frame. +The property can be any of the fields described under `structures entries`_ as well as a reference entry or a database specific field. +Each property has a dictionary as the value, with the following fields: - **frame_encoding**: - - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. This is specified by the frame encoding parameter. + - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. + This is specified by the frame encoding parameter. - **Type**: string - - **Requirements/Conventions**: The value Must be present. + - **Requirements/Conventions**: This field MUST be present. - **Values**: - **constant**: The value of the property is constant and thus has the same value for each frame in the trajectory. - - **explicit**: A value is given for each frame. The number of values must thus be equal to the number of frames. If for some reason a there is no value for a particular frame the value should be :val:`null`. - - **linear**: The value depends linearly on the frame number. - - **explicit_regular_sparse**: The value is set at every **offset_sparse** * **step_size_sparse** frames. - - **explicit_custom_sparse** : A separate list with frame numbers is present to indicate to which frame a value belongs. + - **explicit**: A value is given for each frame. + The number of values MUST thus be equal to the number of frames and MUST be in the same order as the frames. + If there is no value for a particular frame the value MUST be :val:`null`. + - **linear**: The value is a linear function of the frame number. + This function is defined by offset_linear and step_size_linear. + - **explicit_regular_sparse**: The value is set every one per **step_size_sparse** frames, with **offset_sparse** as the first frame. + - **explicit_custom_sparse**: A separate list with frame numbers is defined in the field frame_number to indicate to which frame a value belongs. - **offset_linear**: - - **Description**: If **frame_encoding** is set to linear this property gives the value at frame 0. + - **Description**: If **frame_encoding** is set to "linear" this property gives the value at frame 0. - **Type**: float - - **Requirements/Conventions**: The value MAY be present when frame_encoding == linear, otherwise the value MUST NOT be present. The default value is 0. + - **Requirements/Conventions**: The value MAY be present when **frame_encoding** is set to "linear", otherwise the value MUST NOT be present. + The default value is 0. - **Examples**: - :val:`1.5` - **step_size_linear**: - - **Description**: If **frame_encoding** is set to linear, this value gives the increase/decrease in the value of the property when going from one frame to the next. + - **Description**: If **frame_encoding** is set to "linear", this value gives the increase/decrease in the value of the property when going from one frame to the next. - **Type**: float - - **Requirements/Conventions**: The value MUST be present when frame_encoding == linear. Otherwise it MUST NOT be present. + - **Requirements/Conventions**: The value MUST be present when **frame_encoding** is set to "linear". + Otherwise it MUST NOT be present. - **Examples**: - :val:`0.0005` - **offset_sparse**: - - **Description**: If **frame_encoding** is set to explicit_regular_sparse this property gives the frame number to which the first value belongs. + - **Description**: If **frame_encoding** is set to "explicit_regular_sparse" this property gives the frame number to which the first value belongs. - **Type**: integer - - **Requirements/Conventions**: The value MAY be present when frame_encoding is set to explicit_regular_sparse, otherwise the value MUST NOT be present. The default value is 0. + - **Requirements/Conventions**: The value MAY be present when **frame_encoding** is set to "explicit_regular_sparse", otherwise the value MUST NOT be present. + The default value is 0. - **Examples**: - :val:`100` - **step_size_sparse**: - - **Description**: If **frame_encoding** is set to explicit_regular_sparse, this value indicates that every step_size_sparse frames a value is defined. + - **Description**: If **frame_encoding** is set to "explicit_regular_sparse", this value indicates that every step_size_sparse frames a value is defined. - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_regular_sparse. Otherwise it MUST NOT be present. + - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to "explicit_regular_sparse". + Otherwise it MUST NOT be present. - **Examples**: - :val:`100` - **frame_number**: - - **Description**: If **frame_encoding** is set to explicit_custom_sparse, this field holds the frames to which the values in the value field belong. + - **Description**: If **frame_encoding** is set to "explicit_custom_sparse", this field holds the frames to which the values in the value field belong. - **Type**: List of integers - - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to explicit_custom_sparse. Otherwise it MUST NOT be present. + - **Requirements/Conventions**: The value MUST be present when **frame_encoding** is set to "explicit_custom_sparse". + Otherwise it MUST NOT be present. + The frame numbers MUST be in the same order as the values. - **Examples**: - :val:`[0,20,78,345]` - **values**: - - **Description**: The values belonging to this property. The format of this field depends on the property and on the frame_encoding parameter. + - **Description**: The values belonging to this property. + The format of this field depends on the property and on the frame_encoding parameter. - **Type**: Any - - **Requirements/Conventions**: The value MUST be present. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be usefull for grand canonical simulations where the number of particles in the simulation volume is not constant. + - **Requirements/Conventions**: The value MUST be present. + If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. + In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. + This may be useful for grand canonical simulations where the number of particles in the simulation volume is not constant. Example of returned trajectory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is an example of a JSON object that could be returned after the following query: :query-url:`http://example.com/optimade/v1/trajectories/traj00000001` .. code:: jsonc + { "reference_structure":{ "elements": ["H","O"], @@ -2579,7 +2610,7 @@ This is an example of a JSON object that could be returned after the following q "id": "traj00000001", "type": "trajectories", "last_modified":"2021-07-16T18:02:03Z" - "reference_frame": 359, + "reference_frame": 0, "nframes": 360 "relationships": { "references": { @@ -2604,22 +2635,28 @@ This is an example of a JSON object that could be returned after the following q } After the previous querry is an example of a JSON object that could be returned after the following query: -:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships,&first_frame=0&frame_step=5` +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=0` .. code:: jsonc + { "id": "traj00000001", "type": "trajectories", "cartesian_site_positions":{ "frame_encoding": "explicit", "values": [ - [[2.0,2.0,2.0],[1.238,2.0,1.416],[2.762,2.0,1.416]], + [[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.250,2,132,1.416],[2.750,1.868,1,416]], - [[2,2,2],[1.264,2.197,1.416],[2.736,1.803,1,416]], - [[2,2,2],[1.284,2.261,1.416],[2.716,1.739,1,416]], - [[2,2,2],[1.309,2.322,1.416],[2.691,1.678,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]] + ] }, "lattice_vectors":{ "frame_encoding": "constant", @@ -2636,8 +2673,8 @@ After the previous querry is an example of a JSON object that could be returned }, "_exmpl_ekin":{ "frame_encoding": "explicit_regular_sparse", - "step_size_sparse": 10, - "values":[4.1100E-21,4.1102E-21,4.1103-21] + "step_size_sparse": 2, + "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] }, "species" : { "frame_encoding": "constant", @@ -2661,7 +2698,7 @@ After the previous querry is an example of a JSON object that could be returned "frame_encoding": "constant", "values":["O1","H1","H2"], }, - "structures":{ + "relationships":{ "frame_encoding": "explicit_custom_sparse", "frame_number" : [0,5,20] "values": { @@ -2671,7 +2708,7 @@ After the previous querry is an example of a JSON object that could be returned } } }, - "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species&first_frame=30&frame_step=5" + "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10&" } Calculations Entries From 66556cc84af0694622b37e9a03491f176efd88ec Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 22 Jul 2021 17:54:04 +0200 Subject: [PATCH 04/57] Changed layout JSON code blocks under Examples of a returned trajectory. --- optimade.rst | 249 ++++++++++++++++++++++++++------------------------- 1 file changed, 129 insertions(+), 120 deletions(-) diff --git a/optimade.rst b/optimade.rst index 4535fe33b..7c6731fc1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2421,7 +2421,7 @@ available_properties - **Examples**: - - :val:`["cartesian\_site\_positions","lattice_vectors","species","dimension_types","species_at_sites","_exmpl_Pressure"]` + - :val:`["cartesian_site_positions","lattice_vectors","species","dimension_types","species_at_sites","_exmpl_pressure"]` next_part_trajectory ~~~~~~~~~~~~~~~~~~~~ @@ -2572,144 +2572,153 @@ Each property has a dictionary as the value, with the following fields: Example of returned trajectory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is an example of a JSON object that could be returned after the following query: +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 - { - "reference_structure":{ - "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" : [[2.0,2.0,2.0],[1.238,2.0,1.416],[2.762,2.0,1.416]], - "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], - } - ] - }, + "data":{ "id": "traj00000001", "type": "trajectories", "last_modified":"2021-07-16T18:02:03Z" - "reference_frame": 0, - "nframes": 360 - "relationships": { - "references": { - "data": [ + "attributes": { + "reference_structure":{ + "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" : [[2.0,2.0,2.0],[1.238,2.0,1.416],[2.762,2.0,1.416]], + "nsites":3, + "species_at_sites":["O1","H1","H2"], + "species":[ + { + "name":"O1", + "chemical_symbols":["O"], + "concentration":[1.0], + }, { - "type": "references", - "id": "dummy/2019" + "name":"H1", + "chemical_symbols":["H"], + "concentration":[1.0], + }, + { + "name":"H2", + "chemical_symbols":["H"], + "concentration":[1.0], } ] - } - } - "available_properties":[ - "cartesian_site_positions", - "species", - "dimension_types", - "lattice_vectors", - "species_at_sites", - "_exmpl_temperature_set", - "_exmpl_time", - "_exmpl_ekin" - ] - } + "relationships": { + "references": { + "data": [ + { + "type": "references", + "id": "dummy/2019" + } + ] + } + } + }, + "reference_frame": 0, + "nframes": 360, + "available_properties":[ + "cartesian_site_positions", + "species", + "dimension_types", + "lattice_vectors", + "species_at_sites", + "_exmpl_temperature_set", + "_exmpl_time", + "_exmpl_ekin" + ] + }, + }, + ... After the previous querry is an example of a JSON object that could be returned after the following query: :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=0` .. code:: jsonc - { + "data":{ "id": "traj00000001", "type": "trajectories", - "cartesian_site_positions":{ - "frame_encoding": "explicit", - "values": [ - [[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]] - ] - }, - "lattice_vectors":{ - "frame_encoding": "constant", - "values:[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]], - }, - "dimension_types":{ - "frame_encoding": "constant", - "values:[0,0,0] - }, - "_exmpl_time":{ - "frame_encoding": "linear", - "offset_linear": 0, - "step_size_linear": 1.5 - }, - "_exmpl_ekin":{ - "frame_encoding": "explicit_regular_sparse", - "step_size_sparse": 2, - "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] - }, - "species" : { - "frame_encoding": "constant", - "values": [ - { - "name":"O1", - "chemical_symbols":["O"], - "concentration":[1.0], - },{ - "name":"H1", - "chemical_symbols":["H"], - "concentration":[1.0], - },{ - "name":"H2", - "chemical_symbols":["H"], - "concentration":[1.0], - } - ] - }, - "species_at_sites":{ - "frame_encoding": "constant", - "values":["O1","H1","H2"], - }, - "relationships":{ - "frame_encoding": "explicit_custom_sparse", - "frame_number" : [0,5,20] - "values": { - "data": { - "type": "structures", - "id": "example.db:structs:1234", + "last_modified":"2021-07-16T18:02:03Z" + "attributes::{ + "cartesian_site_positions":{ + "frame_encoding": "explicit", + "values": [ + [[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]] + ] + }, + "lattice_vectors":{ + "frame_encoding": "constant", + "values:[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]], + }, + "dimension_types":{ + "frame_encoding": "constant", + "values:[0,0,0] + }, + "_exmpl_time":{ + "frame_encoding": "linear", + "offset_linear": 0, + "step_size_linear": 1.5 + }, + "_exmpl_ekin":{ + "frame_encoding": "explicit_regular_sparse", + "step_size_sparse": 2, + "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] + }, + "species" : { + "frame_encoding": "constant", + "values": [ + { + "name":"O1", + "chemical_symbols":["O"], + "concentration":[1.0], + },{ + "name":"H1", + "chemical_symbols":["H"], + "concentration":[1.0], + },{ + "name":"H2", + "chemical_symbols":["H"], + "concentration":[1.0], + } + ] + }, + "species_at_sites":{ + "frame_encoding": "constant", + "values":["O1","H1","H2"], + }, + "relationships":{ + "frame_encoding": "explicit_custom_sparse", + "frame_number" : [0,5] + "values": { + "references":{ + "data": { + "type": "structures", + "id": "example.db:structs:1234", + } + } } - } - }, - "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10&" - } + }, + "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10&" + } Calculations Entries -------------------- From 2b841b3735c7515cae30735884ebbf62393bf971 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 22 Jul 2021 22:28:21 +0200 Subject: [PATCH 05/57] Changed indentation level relationships field and no longer discuss references for frames. --- optimade.rst | 67 +++++++++++++++++++++++----------------------------- 1 file changed, 30 insertions(+), 37 deletions(-) diff --git a/optimade.rst b/optimade.rst index 7c6731fc1..726b91da1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2326,7 +2326,7 @@ Trajectories Entries These structures are related because they were, for example, created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. 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 following properties `reference\_structure`_, `reference\_frame`_, `nframes`_, `available_properties`_ and `next_part_trajectory`_. - Next to this they can optionally have all the fields of the structures entries, including relationships, as well as database specific fields. + Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. The `reference\_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. @@ -2366,17 +2366,15 @@ reference\_structure - `assemblies`_ - `structure\_features`_ - - It MAY also have a 'relationships'_ field for references that apply to the entire trajectory rather than to a single frame. - reference\_frame ~~~~~~~~~~~~~~~~ -- **Description**: The number of the frame at which the reference structure was taken. +- **Description**: The number of the frame at which the reference\_structure was taken. - **Type**: integer - **Requirements/Conventions**: - - **Support**: MUST be supported if the reference frame is taken from the trajectory. - If the reference structure is not in the trajectory, the value MUST NOT be present. + - **Support**: MUST be supported if the reference\_structure is taken from the trajectory. + If the reference\_structure is not in the trajectory, the value MUST NOT be present. - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. @@ -2488,7 +2486,7 @@ Return format for Trajectory Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The returned data is first grouped per property and then by frame. -The property can be any of the fields described under `structures entries`_ as well as a reference entry or a database specific field. +The property can be any of the fields described under `structures entries`_ or a database specific field. Each property has a dictionary as the value, with the following fields: - **frame_encoding**: @@ -2569,8 +2567,8 @@ Each property has a dictionary as the value, with the following fields: In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be useful for grand canonical simulations where the number of particles in the simulation volume is not constant. -Example of returned trajectory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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` @@ -2580,8 +2578,8 @@ This is an example of the data field of a JSON object that could be returned aft "data":{ "id": "traj00000001", "type": "trajectories", - "last_modified":"2021-07-16T18:02:03Z" "attributes": { + "last_modified":"2021-07-16T18:02:03Z" "reference_structure":{ "elements": ["H","O"], "nelements": 2, @@ -2612,16 +2610,6 @@ This is an example of the data field of a JSON object that could be returned aft "concentration":[1.0], } ] - "relationships": { - "references": { - "data": [ - { - "type": "references", - "id": "dummy/2019" - } - ] - } - } }, "reference_frame": 0, "nframes": 360, @@ -2635,23 +2623,33 @@ This is an example of the data field of a JSON object that could be returned aft "_exmpl_time", "_exmpl_ekin" ] + "relationships": { + "references": { + "data": [ + { + "type": "references", + "id": "dummy/2019" + } + ] + } + } }, }, ... After the previous querry is an example of a JSON object that could be returned after the following query: -:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=0` +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` .. code:: jsonc "data":{ "id": "traj00000001", "type": "trajectories", - "last_modified":"2021-07-16T18:02:03Z" - "attributes::{ + "attributes:{ + "last_modified":"2021-07-16T18:02:03Z" "cartesian_site_positions":{ "frame_encoding": "explicit", - "values": [ + "values":[ [[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]], @@ -2683,9 +2681,9 @@ After the previous querry is an example of a JSON object that could be returned "step_size_sparse": 2, "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] }, - "species" : { + "species":{ "frame_encoding": "constant", - "values": [ + "values":[ { "name":"O1", "chemical_symbols":["O"], @@ -2705,20 +2703,15 @@ After the previous querry is an example of a JSON object that could be returned "frame_encoding": "constant", "values":["O1","H1","H2"], }, - "relationships":{ + "_exmpl_temperature_set":{ "frame_encoding": "explicit_custom_sparse", - "frame_number" : [0,5] - "values": { - "references":{ - "data": { - "type": "structures", - "id": "example.db:structs:1234", - } - } - } - }, + "frames":[0,9], + "values":[273,293] + } "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10&" } + }, + ... Calculations Entries -------------------- From f4c8e0ffb10360e86431f23945b636949def86d1 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 26 Jul 2021 13:15:22 +0200 Subject: [PATCH 06/57] Processed remarks Gian-Marco + minor changes --- optimade.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index 726b91da1..8f96bbf88 100644 --- a/optimade.rst +++ b/optimade.rst @@ -196,6 +196,12 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH This is particularly relevant for the default JSON-based response format. In this case, **field** refers to the name part of the name-value pairs of JSON objects. +**Trajectory** + A Trajectory contains data belonging to a set of structures. Usually this data will come from molecular dynamics simulations. It can however also contain data from structures that are related in an different way. For example the successive structures from a Monte Carlo simulation. + +**Frame** + An individual structure or data belonging to an individual structure from a trajectory. + Data types ---------- @@ -323,7 +329,7 @@ Index Meta-Database A database provider MAY publish a special Index Meta-Database base URL. The main purpose of this base URL is to allow for automatic discoverability of all databases of the provider. Thus, it acts as a meta-database for the database provider's implementation(s). The index meta-database MUST only provide the :endpoint:`info` and :endpoint:`links` endpoints, see sections `Info Endpoints`_ and `Links Endpoint`_. -It MUST NOT expose any entry listing endpoints (e.g., :endpoint:`structures`). +It MUST NOT expose any entry listing endpoints (e.g., :endpoint:`structures` and :endpoint:`trajectories`). These endpoints do not need to be queryable, i.e., they MAY be provided as static JSON files. However, they MUST return the correct and updated information on all currently provided implementations. @@ -2322,8 +2328,8 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` entry point contains data belonging to a set of structures. - These structures are related because they were, for example, created by the same procedure, e.g. molecular dynamic trajectories, relaxations of a molecule or crystal structure, Monte Carlo simulations, etc. +- **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. Usually this data will come from molecular dynamics simulations. It can however also be used to share data from structures that are related in an other way. For example the successive structures from a Monte Carlo simulation. + 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 following properties `reference\_structure`_, `reference\_frame`_, `nframes`_, `available_properties`_ and `next_part_trajectory`_. Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. From 05ddb3d20a4c45e0fb7d6da57707dee6cda1caa1 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 27 Jul 2021 21:21:50 +0200 Subject: [PATCH 07/57] Removed the next_part_trajectory field from the definition as it is also possible to do this via the next field in the links field of the JSON response. --- optimade.rst | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/optimade.rst b/optimade.rst index 8f96bbf88..7b356a547 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2331,7 +2331,7 @@ Trajectories Entries - **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. Usually this data will come from molecular dynamics simulations. It can however also be used to share data from structures that are related in an other way. For example the successive structures from a Monte Carlo simulation. 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 following properties `reference\_structure`_, `reference\_frame`_, `nframes`_, `available_properties`_ and `next_part_trajectory`_. + :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties `reference\_structure`_, `reference\_frame`_, `nframes`_ and `available_properties`_. Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. The `reference\_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. @@ -2427,19 +2427,6 @@ available_properties - :val:`["cartesian_site_positions","lattice_vectors","species","dimension_types","species_at_sites","_exmpl_pressure"]` -next_part_trajectory -~~~~~~~~~~~~~~~~~~~~ -- **Description**: This is a link the client can use to download the remainder of the trajectory data when the server returns fewer frames than the client requested. -- **Type**: Link -- **Requirements/Conventions**: - - - **Support**: MUST be present when the number of returned frames is smaller than the number of requested frames. - MUST NOT be present otherwise. -- **Examples**: - If, for example, the server has returned data on the first 30 frames it could provide this link to the client to download the next part of the trajectory. - - - :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,species,species_at_sites&first_frame=30` - Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2486,7 +2473,7 @@ The numbering of the frames is zero based, so the first frame is frame number 0. - :query-url:`/trajectories/traj00000001?frame_step=10`. The server can decide how many frames are returned for each request. -If the number of frames returned is less than the total number of frames requested by a client the server has to supply a link in the field `next_part_trajectory`_ which the client can use to download the rest of the trajectory. +If the number of frames returned is less than the total number of frames requested by a client the server has to supply a link in the :field:`next` field of the :field:`links` section of the JSON response, which the client can use to download the rest of the trajectory. Return format for Trajectory Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2714,9 +2701,18 @@ After the previous querry is an example of a JSON object that could be returned "frames":[0,9], "values":[273,293] } - "next_part_trajectory":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10&" + "next_part_trajectory" } }, + "links":{ + "next":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", + "base_url": { + "href": "http://example.com/optimade", + "meta": { + "_exmpl_db_version": "3.2.1" + } + } + } ... Calculations Entries From ee8f3dcd6a185e32e29a29062bc994cfa3301db0 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 28 Jul 2021 22:16:08 +0200 Subject: [PATCH 08/57] Replaced \_ with _ where pandoc did not interpreted \ correctly as escape character. --- optimade.rst | 72 ++++++++++++++++++++++++++-------------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/optimade.rst b/optimade.rst index 7b356a547..1d6677f0c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -786,7 +786,7 @@ The API implementation MAY provide other entry types than the ones standardized Such entry types MUST be prefixed by a database-provider-specific prefix (i.e., the resource objects' :property:`type` value should start with the database-provider-specific prefix, e.g., :property:`type` = :val:`_exmpl_workflows`). Each custom entry type SHOULD be served at a corresponding entry listing endpoint under the versioned or unversioned base URL that serves the API with the same name (i.e., equal to the resource objects' :property:`type` value, e.g., :endpoint:`/_exmpl_workflows`). It is RECOMMENDED to align with the OPTIMADE API specification practice of using a plural for entry resource types and entry type endpoints. -Any custom entry listing endpoint MUST also be added to the :property:`available\_endpoints` and :property:`entry\_types\_by\_format` attributes of the `Base Info Endpoint`_. +Any custom entry listing endpoint MUST also be added to the :property:`available_endpoints` and :property:`entry_types_by_format` attributes of the `Base Info Endpoint`_. For more on custom endpoints, see `Custom Extension Endpoints`_. @@ -871,7 +871,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. @@ -1828,7 +1828,7 @@ elements - **Query**: MUST be a queryable property with support for all mandatory filter features. - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters. - The order MUST be alphabetical. - - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements\_ratios`_, if the latter is provided. + - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`_, if the latter is provided. - Note: This property SHOULD NOT contain the string "X" to indicate non-chemical elements or "vacancy" to indicate vacancies (in contrast to the field :field:`chemical_symbols` for the :property:`species` property). - **Examples**: @@ -1851,7 +1851,7 @@ nelements - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. - - MUST be equal to the lengths of the list properties `elements`_ and `elements\_ratios`_, if they are provided. + - MUST be equal to the lengths of the list properties `elements`_ and `elements_ratios`_, if they are provided. - **Examples**: @@ -1999,8 +1999,8 @@ dimension\_types ~~~~~~~~~~~~~~~~ - **Description**: List of three integers. - For each of the three directions indicated by the three lattice vectors (see property `lattice\_vectors`_), this list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`). - Note: the elements in this list each refer to the direction of the corresponding entry in `lattice\_vectors`_ and *not* the Cartesian x, y, z directions. + For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`_), this list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`). + Note: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors`_ and *not* the Cartesian x, y, z directions. - **Type**: list of integers. - **Requirements/Conventions**: @@ -2019,18 +2019,18 @@ dimension\_types nperiodic\_dimensions ~~~~~~~~~~~~~~~~~~~~~ -- **Description**: An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension\_types`_. +- **Description**: An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`_. - **Type**: integer - **Requirements/Conventions**: - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. - - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension\_types`_ property. + - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types`_ property. - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents. - **Examples**: - - :val:`2` should be indicated in cases where :property:`dimension\_types` is any of :val:`[1, 1, 0]`, :val:`[1, 0, 1]`, :val:`[0, 1, 1]`. + - :val:`2` should be indicated in cases where :property:`dimension_types` is any of :val:`[1, 1, 0]`, :val:`[1, 0, 1]`, :val:`[0, 1, 1]`. - **Query examples**: @@ -2050,10 +2050,10 @@ lattice\_vectors - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates. (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates). - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane. - - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension\_types`_. + - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`_. The vectors SHOULD by convention be chosen so the determinant of the :property:`lattice_vectors` matrix is different from zero. The vectors in the non-periodic directions have no significance beyond fulfilling these requirements. - - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension\_types`_ is :val:`0`) MAY be given as a list of all :val:`null` values. + - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types`_ is :val:`0`) MAY be given as a list of all :val:`null` values. If a lattice vector contains the value :val:`null`, all coordinates of that lattice vector MUST be :val:`null`. - **Examples**: @@ -2331,10 +2331,10 @@ Trajectories Entries - **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. Usually this data will come from molecular dynamics simulations. It can however also be used to share data from structures that are related in an other way. For example the successive structures from a Monte Carlo simulation. 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 following properties `reference\_structure`_, `reference\_frame`_, `nframes`_ and `available_properties`_. + :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. - The `reference\_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. + The `reference_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. @@ -2349,38 +2349,38 @@ reference\_structure - **Requirements/Conventions**: - Each trajectory MUST have a reference_structure. - - This reference_structure MAY be one of the frames from the trajectory, in that case the `reference\_frame`_ field MUST specify which frame has been used. - - Queries on the trajectories MUST be done on the information supplied in the reference\_structure when the queried property is in the reference\_structure. - The subfields of the reference\_structure MUST have the same queryability as in the `structures entries`_. + - This reference_structure MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. + - Queries on the trajectories MUST be done on the information supplied in the reference_structure when the queried property is in the reference_structure. + The subfields of the reference_structure MUST have the same queryability as in the `structures entries`_. - This reference frame has the same properties as the structure entries namely: - `elements`_ - `nelements`_ - - `elements\_ratios`_ - - `chemical\_formula\_descriptive`_ - - `chemical\_formula\_reduced`_ - - `chemical\_formula\_hill`_ - - `chemical\_formula\_anonymous`_ - - `dimension\_types`_ - - `nperiodic\_dimensions`_ - - `lattice\_vectors`_ - - `cartesian\_site\_positions`_ + - `elements_ratios`_ + - `chemical_formula_descriptive`_ + - `chemical_formula_reduced`_ + - `chemical_formula_hill`_ + - `chemical_formula_anonymous`_ + - `dimension_types`_ + - `nperiodic_dimensions`_ + - `lattice_vectors`_ + - `cartesian_site_positions`_ - `nsites`_ - - `species\_at\_sites`_ + - `species_at_sites`_ - `species`_ - `assemblies`_ - - `structure\_features`_ + - `structure_features`_ -reference\_frame +reference_frame ~~~~~~~~~~~~~~~~ -- **Description**: The number of the frame at which the reference\_structure was taken. +- **Description**: The number of the frame at which the reference_structure was taken. - **Type**: integer - **Requirements/Conventions**: - - **Support**: MUST be supported if the reference\_structure is taken from the trajectory. - If the reference\_structure is not in the trajectory, the value MUST NOT be present. + - **Support**: MUST be supported if the reference_structure is taken from the trajectory. + If the reference_structure is not in the trajectory, the value MUST NOT be present. - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. @@ -2416,7 +2416,7 @@ available_properties - **Description**: A list of the names of the properties for which data is available in the trajectory. It is up to the server to decide which properties to share and there are no mandatory fields. - When sharing `cartesian\_site\_positions`_ the lattice_vectors, species, dimension_types and species_at_sites MUST be shared as well. + When sharing `cartesian_site_positions`_ the lattice_vectors, species, dimension_types and species_at_sites MUST be shared as well. - **Type**: List of strings - **Requirements/Conventions**: @@ -2431,9 +2431,9 @@ available_properties Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The preceding properties 7.3.1-4 and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response\_fields property` (see the section `Entry Listing URL Query Parameters`_) is specified. +The preceding properties 7.3.1-4 and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. -The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response\_fields. +The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. Next to this the client MAY specify the following parameters to customize the return from the server. While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. @@ -2631,7 +2631,7 @@ This is an example of the data field of a JSON object that could be returned aft ... After the previous querry is an example of a JSON object that could be returned after the following query: -:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` .. code:: jsonc @@ -2705,7 +2705,7 @@ After the previous querry is an example of a JSON object that could be returned } }, "links":{ - "next":"http://example.com/optimade/v1/trajectories/traj00000001?response\_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", + "next":"http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", "base_url": { "href": "http://example.com/optimade", "meta": { From fc869a879ec6706b9e1e0221cc88821472202359 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 30 Aug 2021 15:50:45 +0200 Subject: [PATCH 09/57] added a few more internal links --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 1d6677f0c..196575775 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2416,7 +2416,7 @@ available_properties - **Description**: A list of the names of the properties for which data is available in the trajectory. It is up to the server to decide which properties to share and there are no mandatory fields. - When sharing `cartesian_site_positions`_ the lattice_vectors, species, dimension_types and species_at_sites MUST be shared as well. + When sharing `cartesian_site_positions`_ the `lattice_vectors`_, `species`_, `dimension_types`_ and `species_at_sites`_ MUST be shared as well. - **Type**: List of strings - **Requirements/Conventions**: From 0ae7af89ca70f7565141b47b52ace2cd152d64d7 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 9 Sep 2021 15:52:53 +0200 Subject: [PATCH 10/57] Apply suggestions from code review Giovanni Co-authored-by: Giovanni Pizzi --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 47d61cd8c..9589de26e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2443,7 +2443,7 @@ The numbering of the frames is zero based, so the first frame is frame number 0. - **Description**: **first_frame** specifies the first frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less than or equal to nframes.(The total number of frames in the trajectory) + - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less than nframes.(The total number of frames in the trajectory) If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. The default value is 0. - **Examples**: @@ -2454,7 +2454,7 @@ The numbering of the frames is zero based, so the first frame is frame number 0. - **Description**: **last_frame** specifies the last frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less than or equal to nframes(the total number of frames in the trajectory). + - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less than nframes(the total number of frames in the trajectory). If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. The default value is nframes. - **Examples**: From d523efb51a42895464220f992b2c0fa00905646c Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 13 Sep 2021 17:30:39 +0200 Subject: [PATCH 11/57] added comments Giovani --- optimade.rst | 57 ++++++++++++++++++++++++++-------------------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/optimade.rst b/optimade.rst index 8c3a542a1..2d7449370 100644 --- a/optimade.rst +++ b/optimade.rst @@ -1,4 +1,4 @@ -========================================= +c========================================= OPTIMADE API specification v1.1.0~develop ========================================= @@ -2340,7 +2340,7 @@ Trajectories Entries It is possible to request only part of a trajectory and to request only 1 out of every n frames. Queries on individual frames are currently not supported. -reference\_structure +reference_structure ~~~~~~~~~~~~~~~~~~~~ - **Description**: This is an example of the structures that can be found in the trajectory. @@ -2375,9 +2375,9 @@ reference\_structure reference_frame ~~~~~~~~~~~~~~~~ -- **Description**: The number of the frame at which the reference_structure was taken. +- **Description**: The number of the frame at which the reference_structure was taken. The first frame is frame 0. - **Type**: integer -- **Requirements/Conventions**: +- **Requirements/Conventions**: The value MUST be equal or larger than 0 and less than nframes. - **Support**: MUST be supported if the reference_structure is taken from the trajectory. If the reference_structure is not in the trajectory, the value MUST NOT be present. @@ -2482,7 +2482,7 @@ The returned data is first grouped per property and then by frame. The property can be any of the fields described under `structures entries`_ or a database specific field. Each property has a dictionary as the value, with the following fields: -- **frame_encoding**: +- **frame_serialization_format**: - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. This is specified by the frame encoding parameter. @@ -2497,13 +2497,13 @@ Each property has a dictionary as the value, with the following fields: - **linear**: The value is a linear function of the frame number. This function is defined by offset_linear and step_size_linear. - **explicit_regular_sparse**: The value is set every one per **step_size_sparse** frames, with **offset_sparse** as the first frame. - - **explicit_custom_sparse**: A separate list with frame numbers is defined in the field frame_number to indicate to which frame a value belongs. + - **explicit_custom_sparse**: A separate list with frame numbers is defined in the field **sparse_frames** to indicate to which frame a value belongs. - **offset_linear**: - - **Description**: If **frame_encoding** is set to "linear" this property gives the value at frame 0. + - **Description**: If **frame_serialization_format** is set to "linear" this property gives the value at frame 0. - **Type**: float - - **Requirements/Conventions**: The value MAY be present when **frame_encoding** is set to "linear", otherwise the value MUST NOT be present. + - **Requirements/Conventions**: The value MAY be present when **frame_serialization_format** is set to "linear", otherwise the value MUST NOT be present. The default value is 0. - **Examples**: @@ -2511,9 +2511,9 @@ Each property has a dictionary as the value, with the following fields: - **step_size_linear**: - - **Description**: If **frame_encoding** is set to "linear", this value gives the increase/decrease in the value of the property when going from one frame to the next. + - **Description**: If **frame_serialization_format** is set to "linear", this value gives the change in the value of the property per unit of frame number. e.g. If at frame 3 the value of the property is 0.6 and **step_size_linear** = 0.2 than at frame 4 the value of the property will be 0.8. - **Type**: float - - **Requirements/Conventions**: The value MUST be present when **frame_encoding** is set to "linear". + - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is set to "linear". Otherwise it MUST NOT be present. - **Examples**: @@ -2521,9 +2521,9 @@ Each property has a dictionary as the value, with the following fields: - **offset_sparse**: - - **Description**: If **frame_encoding** is set to "explicit_regular_sparse" this property gives the frame number to which the first value belongs. + - **Description**: If **frame_serialization_format** is set to "explicit_regular_sparse" this property gives the frame number to which the first value belongs. - **Type**: integer - - **Requirements/Conventions**: The value MAY be present when **frame_encoding** is set to "explicit_regular_sparse", otherwise the value MUST NOT be present. + - **Requirements/Conventions**: The value MAY be present when **frame_serialization_format** is set to "explicit_regular_sparse", otherwise the value MUST NOT be present. The default value is 0. - **Examples**: @@ -2531,21 +2531,21 @@ Each property has a dictionary as the value, with the following fields: - **step_size_sparse**: - - **Description**: If **frame_encoding** is set to "explicit_regular_sparse", this value indicates that every step_size_sparse frames a value is defined. + - **Description**: If **frame_serialization_format** is set to "explicit_regular_sparse", this value indicates that every step_size_sparse frames a value is defined. - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when frame_encoding is set to "explicit_regular_sparse". + - **Requirements/Conventions**: The value MUST be present when frame_serialization_format is set to "explicit_regular_sparse". Otherwise it MUST NOT be present. - **Examples**: - :val:`100` -- **frame_number**: +- **sparse_frames**: - - **Description**: If **frame_encoding** is set to "explicit_custom_sparse", this field holds the frames to which the values in the value field belong. + - **Description**: If **frame_serialization_format** is set to "explicit_custom_sparse", this field holds the frames to which the values in the value field belong. - **Type**: List of integers - - **Requirements/Conventions**: The value MUST be present when **frame_encoding** is set to "explicit_custom_sparse". + - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is set to "explicit_custom_sparse". Otherwise it MUST NOT be present. - The frame numbers MUST be in the same order as the values. + The frame numbers in **sparse_frames** MUST be in the same order as the values. - **Examples**: - :val:`[0,20,78,345]` @@ -2553,9 +2553,9 @@ Each property has a dictionary as the value, with the following fields: - **values**: - **Description**: The values belonging to this property. - The format of this field depends on the property and on the frame_encoding parameter. + The format of this field depends on the property and on the frame_serialization_format parameter. - **Type**: Any - - **Requirements/Conventions**: The value MUST be present. + - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is not set to linear. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be useful for grand canonical simulations where the number of particles in the simulation volume is not constant. @@ -2641,7 +2641,7 @@ After the previous querry is an example of a JSON object that could be returned "attributes:{ "last_modified":"2021-07-16T18:02:03Z" "cartesian_site_positions":{ - "frame_encoding": "explicit", + "frame_serialization_format": "explicit", "values":[ [[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]], @@ -2657,25 +2657,25 @@ After the previous querry is an example of a JSON object that could be returned ] }, "lattice_vectors":{ - "frame_encoding": "constant", + "frame_serialization_format": "constant", "values:[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]], }, "dimension_types":{ - "frame_encoding": "constant", + "frame_serialization_format": "constant", "values:[0,0,0] }, "_exmpl_time":{ - "frame_encoding": "linear", + "frame_serialization_format": "linear", "offset_linear": 0, "step_size_linear": 1.5 }, "_exmpl_ekin":{ - "frame_encoding": "explicit_regular_sparse", + "frame_serialization_format": "explicit_regular_sparse", "step_size_sparse": 2, "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] }, "species":{ - "frame_encoding": "constant", + "frame_serialization_format": "constant", "values":[ { "name":"O1", @@ -2693,15 +2693,14 @@ After the previous querry is an example of a JSON object that could be returned ] }, "species_at_sites":{ - "frame_encoding": "constant", + "frame_serialization_format": "constant", "values":["O1","H1","H2"], }, "_exmpl_temperature_set":{ - "frame_encoding": "explicit_custom_sparse", + "frame_serialization_format": "explicit_custom_sparse", "frames":[0,9], "values":[273,293] } - "next_part_trajectory" } }, "links":{ From 84f007c170666c55eda54ce1ca2058275530d922 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 15 Sep 2021 12:41:32 +0200 Subject: [PATCH 12/57] processed remarks Giovanni --- optimade.rst | 63 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 57 insertions(+), 6 deletions(-) diff --git a/optimade.rst b/optimade.rst index 2d7449370..90e369bb6 100644 --- a/optimade.rst +++ b/optimade.rst @@ -1,4 +1,4 @@ -c========================================= +========================================= OPTIMADE API specification v1.1.0~develop ========================================= @@ -2414,18 +2414,68 @@ nframes available_properties ~~~~~~~~~~~~~~~~~~~~ -- **Description**: A list of the names of the properties for which data is available in the trajectory. +- **Description**: A dictionary with an entry for each of the properties for which data is available in the trajectory. The key is the name of the property. The value is a sub dictionary containing information about which value belongs to which frame. This makes it easier for a client to estimate the amount of data a query returns. + It is up to the server to decide which properties to share and there are no mandatory fields. - When sharing `cartesian_site_positions`_ the `lattice_vectors`_, `species`_, `dimension_types`_ and `species_at_sites`_ MUST be shared as well. -- **Type**: List of strings + When sharing `cartesian_site_positions`_ the `lattice_vectors`_, `species`_, `dimension_types`_ and `species_at_sites`_ MUST however be shared as well. + + +- **Type**: dictionary of dictionaries - **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. +- **Sub dictionary fields** + + - **frame_serialization** + + - **Description**: This property describes how the frames and the returned values of a property are related. For each **frame_serialization** method there are additional fields that describe how the values belong to the frames. These fields should also be present here. +A complete description of these fields can be found in the section: `Return Format for Trajectory Data`_ + + - **nvalues**: + + - **Description**: This field gives the number of values for this property. + - **Type**: integer + - **Requirements/Conventions**: The value MUST be present when frame_serialization_format is set to explicit, explicit_regular_sparse or explicit_custom_sparse. + - **Examples**: + + - :val:`100` + + + - **Examples**: - - :val:`["cartesian_site_positions","lattice_vectors","species","dimension_types","species_at_sites","_exmpl_pressure"]` + .. code:: jsonc + + "available_properties": { + "cartesian_site_positions": { + "frame_serialization_format": "explicit", + "nvalues": 1000 + }, + "lattice_vectors":{ + "frame_serialization_format": "constant", + }, + "species":{ + "frame_serialization_format": "constant", + }, + "dimension_types":{ + "frame_serialization_format": "constant", + }, + "species_at_sites":{ + "frame_serialization_format": "constant", + }, + "_exmpl_pressure":{ + "frame_serialization_format": "explicit_custom_sparse", + "nvalues": 20 + } + "_exmpl_temperature":{ + "frame_serialization_format": "explicit_regular_sparse", + "step_size_sparse": 10 + "nvalues": 100 + } + } + Retrieving the trajectory data @@ -2485,7 +2535,7 @@ Each property has a dictionary as the value, with the following fields: - **frame_serialization_format**: - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. - This is specified by the frame encoding parameter. + This is specified by the frame_serialization_format. - **Type**: string - **Requirements/Conventions**: This field MUST be present. - **Values**: @@ -2550,6 +2600,7 @@ Each property has a dictionary as the value, with the following fields: - :val:`[0,20,78,345]` + - **values**: - **Description**: The values belonging to this property. From 4dd22d392802613bc67b18dbb1e611c5f3ce532c Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 15 Sep 2021 17:53:37 +0200 Subject: [PATCH 13/57] Updated examples; specified that the values field is a list; and e few other small coorection --- optimade.rst | 67 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 23 deletions(-) diff --git a/optimade.rst b/optimade.rst index 90e369bb6..a56e553c3 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2331,7 +2331,7 @@ Trajectories Entries - **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. Usually this data will come from molecular dynamics simulations. It can however also be used to share data from structures that are related in an other way. For example the successive structures from a Monte Carlo simulation. 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 following properties `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. + :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. The `reference_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. @@ -2414,7 +2414,7 @@ nframes available_properties ~~~~~~~~~~~~~~~~~~~~ -- **Description**: A dictionary with an entry for each of the properties for which data is available in the trajectory. The key is the name of the property. The value is a sub dictionary containing information about which value belongs to which frame. This makes it easier for a client to estimate the amount of data a query returns. +- **Description**: A dictionary with an entry for each of the properties for which data is available in the trajectory. The key is the name of the property. The value is a dictionary containing information about which value belongs to which frame. This makes it easier for a client to estimate the amount of data a query returns. It is up to the server to decide which properties to share and there are no mandatory fields. When sharing `cartesian_site_positions`_ the `lattice_vectors`_, `species`_, `dimension_types`_ and `species_at_sites`_ MUST however be shared as well. @@ -2431,7 +2431,7 @@ available_properties - **frame_serialization** - **Description**: This property describes how the frames and the returned values of a property are related. For each **frame_serialization** method there are additional fields that describe how the values belong to the frames. These fields should also be present here. -A complete description of these fields can be found in the section: `Return Format for Trajectory Data`_ + A complete description of the **frame_serialization** methods and the fields belonging to these methods can be found in the section: `Return Format for Trajectory Data`_ - **nvalues**: @@ -2443,7 +2443,6 @@ A complete description of these fields can be found in the section: `Return Form - :val:`100` - - **Examples**: .. code:: jsonc @@ -2605,7 +2604,7 @@ Each property has a dictionary as the value, with the following fields: - **Description**: The values belonging to this property. The format of this field depends on the property and on the frame_serialization_format parameter. - - **Type**: Any + - **Type**: List of Any - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is not set to linear. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. @@ -2634,7 +2633,7 @@ This is an example of the data field of a JSON object that could be returned aft "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" : [[2.0,2.0,2.0],[1.238,2.0,1.416],[2.762,2.0,1.416]], + "cartesian_site_positions" : [[2,2,2],[1.238,2.000,1.416],[2.762,2.000,1.416]], "nsites":3, "species_at_sites":["O1","H1","H2"], "species":[ @@ -2657,16 +2656,38 @@ This is an example of the data field of a JSON object that could be returned aft }, "reference_frame": 0, "nframes": 360, - "available_properties":[ - "cartesian_site_positions", - "species", - "dimension_types", - "lattice_vectors", - "species_at_sites", - "_exmpl_temperature_set", - "_exmpl_time", - "_exmpl_ekin" - ] + "available_properties":{ + "cartesian_site_positions":{ + "frame_serialization_format": "explicit", + "nvalues":360 + }, + "species":{ + "frame_serialization_format": "constant", + }, + "dimension_types":{ + "frame_serialization_format": "constant", + }, + "lattice_vectors":{ + "frame_serialization_format": "constant", + }, + "species_at_sites":{ + "frame_serialization_format": "constant", + }, + "_exmpl_temperature_set":{ + "frame_serialization_format": "explicit_custom_sparse", + "nvalues":144, + }, + "_exmpl_time":{ + "frame_serialization_format": "linear", + "offset_linear": 0, + "step_size_linear": 1.5 + }, + "_exmpl_ekin":{ + "frame_serialization_format": "explicit_regular_sparse", + "step_size_sparse": 2, + "nvalues":180, + } + } "relationships": { "references": { "data": [ @@ -2709,11 +2730,11 @@ After the previous querry is an example of a JSON object that could be returned }, "lattice_vectors":{ "frame_serialization_format": "constant", - "values:[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]], + "values:[[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]]], }, "dimension_types":{ "frame_serialization_format": "constant", - "values:[0,0,0] + "values:[[0,0,0]] }, "_exmpl_time":{ "frame_serialization_format": "linear", @@ -2727,7 +2748,7 @@ After the previous querry is an example of a JSON object that could be returned }, "species":{ "frame_serialization_format": "constant", - "values":[ + "values":[[ { "name":"O1", "chemical_symbols":["O"], @@ -2741,16 +2762,16 @@ After the previous querry is an example of a JSON object that could be returned "chemical_symbols":["H"], "concentration":[1.0], } - ] + ]] }, "species_at_sites":{ "frame_serialization_format": "constant", - "values":["O1","H1","H2"], + "values":[["O1","H1","H2"]], }, "_exmpl_temperature_set":{ "frame_serialization_format": "explicit_custom_sparse", - "frames":[0,9], - "values":[273,293] + "sparse_frames":[0,4,5,9], + "values":[273,273,293,293] } } }, From 1ec442d3a67287bf2085674931cb8421c91a77c6 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 15 Dec 2021 14:54:54 +0100 Subject: [PATCH 14/57] Placed each sentecnce on a separate line. --- optimade.rst | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/optimade.rst b/optimade.rst index a56e553c3..b75ce770f 100644 --- a/optimade.rst +++ b/optimade.rst @@ -197,7 +197,10 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH In this case, **field** refers to the name part of the name-value pairs of JSON objects. **Trajectory** - A Trajectory contains data belonging to a set of structures. Usually this data will come from molecular dynamics simulations. It can however also contain data from structures that are related in an different way. For example the successive structures from a Monte Carlo simulation. + A Trajectory contains data belonging to a set of structures. + Usually this data will come from molecular dynamics simulations. + It can however also contain data from structures that are related in an different way. + For example the successive structures from a Monte Carlo simulation. **Frame** An individual structure or data belonging to an individual structure from a trajectory. @@ -2328,7 +2331,10 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. Usually this data will come from molecular dynamics simulations. It can however also be used to share data from structures that are related in an other way. For example the successive structures from a Monte Carlo simulation. +- **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. + Usually this data will come from molecular dynamics simulations. + It can however also be used to share data from structures that are related in an other way. + For example the successive structures from a Monte Carlo simulation. 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 following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. @@ -2375,7 +2381,8 @@ reference_structure reference_frame ~~~~~~~~~~~~~~~~ -- **Description**: The number of the frame at which the reference_structure was taken. The first frame is frame 0. +- **Description**: The number of the frame at which the reference_structure was taken. + The first frame is frame 0. - **Type**: integer - **Requirements/Conventions**: The value MUST be equal or larger than 0 and less than nframes. @@ -2414,7 +2421,10 @@ nframes available_properties ~~~~~~~~~~~~~~~~~~~~ -- **Description**: A dictionary with an entry for each of the properties for which data is available in the trajectory. The key is the name of the property. The value is a dictionary containing information about which value belongs to which frame. This makes it easier for a client to estimate the amount of data a query returns. +- **Description**: A dictionary with an entry for each of the properties for which data is available in the trajectory. + The key is the name of the property. + The value is a dictionary containing information about which value belongs to which frame. + This makes it easier for a client to estimate the amount of data a query returns. It is up to the server to decide which properties to share and there are no mandatory fields. When sharing `cartesian_site_positions`_ the `lattice_vectors`_, `species`_, `dimension_types`_ and `species_at_sites`_ MUST however be shared as well. @@ -2430,7 +2440,9 @@ available_properties - **frame_serialization** - - **Description**: This property describes how the frames and the returned values of a property are related. For each **frame_serialization** method there are additional fields that describe how the values belong to the frames. These fields should also be present here. + - **Description**: This property describes how the frames and the returned values of a property are related. + For each **frame_serialization** method there are additional fields that describe how the values belong to the frames. + These fields should also be present here. A complete description of the **frame_serialization** methods and the fields belonging to these methods can be found in the section: `Return Format for Trajectory Data`_ - **nvalues**: @@ -2560,7 +2572,8 @@ Each property has a dictionary as the value, with the following fields: - **step_size_linear**: - - **Description**: If **frame_serialization_format** is set to "linear", this value gives the change in the value of the property per unit of frame number. e.g. If at frame 3 the value of the property is 0.6 and **step_size_linear** = 0.2 than at frame 4 the value of the property will be 0.8. + - **Description**: If **frame_serialization_format** is set to "linear", this value gives the change in the value of the property per unit of frame number. + e.g. If at frame 3 the value of the property is 0.6 and **step_size_linear** = 0.2 than at frame 4 the value of the property will be 0.8. - **Type**: float - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is set to "linear". Otherwise it MUST NOT be present. From 5ae4993de93d08c8f0d3e18d6cc34c9b0e9d2c3f Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 16 Dec 2021 12:33:12 +0100 Subject: [PATCH 15/57] removed excess tilde --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index b75ce770f..31f10ea6b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2347,7 +2347,7 @@ Trajectories Entries Queries on individual frames are currently not supported. reference_structure -~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ - **Description**: This is an example of the structures that can be found in the trajectory. It can be used to select trajectories with queries and to give a quick visual impression of the structures in this trajectory. From e2c7f2c6f7aa23dbe424a68fb5ee80fa5b7235fc Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 16 Dec 2021 12:47:59 +0100 Subject: [PATCH 16/57] replaced reference to section 7.3.1-4 with links to the subsections --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 31f10ea6b..4c89b4ca9 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2379,7 +2379,7 @@ reference_structure - `structure_features`_ reference_frame -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~ - **Description**: The number of the frame at which the reference_structure was taken. The first frame is frame 0. @@ -2492,7 +2492,7 @@ available_properties Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The preceding properties 7.3.1-4 and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. +The preceding properties `reference_structure`_, `reference_frame`_, `nframes`, `available_properties`_ and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. From 18f54c8d42605f20488d60af33832d991b385a50 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 16 Dec 2021 13:40:58 +0100 Subject: [PATCH 17/57] added link to "Retrieving trajectory data" from the introduction section of the trajectory endpoint --- optimade.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 4c89b4ca9..0e9b30a32 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2344,6 +2344,7 @@ Trajectories Entries The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. +This is describe in more detail in the section `Retrieving the trajectory data`_ Queries on individual frames are currently not supported. reference_structure @@ -2492,7 +2493,7 @@ available_properties Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The preceding properties `reference_structure`_, `reference_frame`_, `nframes`, `available_properties`_ and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. +The preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, `available_properties`_ and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. From 5058ce7d9c209ccc00257bd67788c01dcfdb8f70 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 16 Dec 2021 15:50:10 +0100 Subject: [PATCH 18/57] changed the formatting of properties in trajectories section. --- optimade.rst | 58 ++++++++++++++++++++++++++-------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/optimade.rst b/optimade.rst index 0e9b30a32..d052bc148 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2344,7 +2344,7 @@ Trajectories Entries The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. -This is describe in more detail in the section `Retrieving the trajectory data`_ + This is describe in more detail in the section `Retrieving the trajectory data`_ Queries on individual frames are currently not supported. reference_structure @@ -2355,9 +2355,9 @@ reference_structure - **Type**: dictionary - **Requirements/Conventions**: - - Each trajectory MUST have a reference_structure. - - This reference_structure MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. - - Queries on the trajectories MUST be done on the information supplied in the reference_structure when the queried property is in the reference_structure. + - Each trajectory MUST have a :property:`reference_structure`. + - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. + - Queries on the trajectories MUST be done on the information supplied in the :property:`reference_structure` when the queried property is in the :property:`reference_structure`. The subfields of the reference_structure MUST have the same queryability as in the `structures entries`_. - This reference frame has the same properties as the structure entries namely: @@ -2382,13 +2382,13 @@ reference_structure reference_frame ~~~~~~~~~~~~~~~ -- **Description**: The number of the frame at which the reference_structure was taken. +- **Description**: The number of the frame at which the `reference_structure`_ was taken. The first frame is frame 0. - **Type**: integer - **Requirements/Conventions**: The value MUST be equal or larger than 0 and less than nframes. - - **Support**: MUST be supported if the reference_structure is taken from the trajectory. - If the reference_structure is not in the trajectory, the value MUST NOT be present. + - **Support**: MUST be supported if the `reference_structure`_ is taken from the trajectory. + If the `reference_structure`_ is not in the trajectory, the value MUST NOT be present. - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. @@ -2450,7 +2450,7 @@ available_properties - **Description**: This field gives the number of values for this property. - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when frame_serialization_format is set to explicit, explicit_regular_sparse or explicit_custom_sparse. + - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to explicit, explicit_regular_sparse or explicit_custom_sparse. - **Examples**: - :val:`100` @@ -2516,16 +2516,16 @@ The numbering of the frames is zero based, so the first frame is frame number 0. - **Description**: **last_frame** specifies the last frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to first_frame and MUST be less than nframes(the total number of frames in the trajectory). + - **Requirements/Conventions**: The value MUST be larger or equal to :property:`first_frame` and MUST be less than `nframes`_ (the total number of frames in the trajectory). If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. - The default value is nframes. + The default value is `nframes`_-1. - **Examples**: - :query-url:`/trajectories/traj00000001?last_frame=2000` - **frame_step**: - - **Description**: Specifies that data should only be returned for one out of every **frame_step** frames. + - **Description**: Specifies that data should only be returned for one out of every :property:`frame_step` frames. - **Type**: integer - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less than or equal to the total number of frames. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. @@ -2547,7 +2547,7 @@ Each property has a dictionary as the value, with the following fields: - **frame_serialization_format**: - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. - This is specified by the frame_serialization_format. + This is specified by the :property:`frame_serialization_format`. - **Type**: string - **Requirements/Conventions**: This field MUST be present. - **Values**: @@ -2557,15 +2557,15 @@ Each property has a dictionary as the value, with the following fields: The number of values MUST thus be equal to the number of frames and MUST be in the same order as the frames. If there is no value for a particular frame the value MUST be :val:`null`. - **linear**: The value is a linear function of the frame number. - This function is defined by offset_linear and step_size_linear. - - **explicit_regular_sparse**: The value is set every one per **step_size_sparse** frames, with **offset_sparse** as the first frame. - - **explicit_custom_sparse**: A separate list with frame numbers is defined in the field **sparse_frames** to indicate to which frame a value belongs. + This function is defined by :property:`offset_linear` and :property:`step_size_linear`. + - **explicit_regular_sparse**: The value is set every one per :property:`step_size_sparse` frames, with :property:`offset_sparse` as the first frame. + - **explicit_custom_sparse**: A separate list with frame numbers is defined in the field :property:`sparse_frames` to indicate to which frame a value belongs. - **offset_linear**: - - **Description**: If **frame_serialization_format** is set to "linear" this property gives the value at frame 0. + - **Description**: If :property:`frame_serialization_format` is set to :val:`"linear"` this property gives the value at frame 0. - **Type**: float - - **Requirements/Conventions**: The value MAY be present when **frame_serialization_format** is set to "linear", otherwise the value MUST NOT be present. + - **Requirements/Conventions**: The value MAY be present when :property:`frame_serialization_format` is set to :val:`"linear"`, otherwise the value MUST NOT be present. The default value is 0. - **Examples**: @@ -2573,10 +2573,10 @@ Each property has a dictionary as the value, with the following fields: - **step_size_linear**: - - **Description**: If **frame_serialization_format** is set to "linear", this value gives the change in the value of the property per unit of frame number. - e.g. If at frame 3 the value of the property is 0.6 and **step_size_linear** = 0.2 than at frame 4 the value of the property will be 0.8. + - **Description**: If :property:`frame_serialization_format` is set to :val:`"linear"`, this value gives the change in the value of the property per unit of frame number. + e.g. If at frame 3 the value of the property is 0.6 and :property:`step_size_linear` = 0.2 than at frame 4 the value of the property will be 0.8. - **Type**: float - - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is set to "linear". + - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to "linear". Otherwise it MUST NOT be present. - **Examples**: @@ -2584,9 +2584,9 @@ Each property has a dictionary as the value, with the following fields: - **offset_sparse**: - - **Description**: If **frame_serialization_format** is set to "explicit_regular_sparse" this property gives the frame number to which the first value belongs. + - **Description**: If :property:`frame_serialization_format` is set to :val:` "explicit_regular_sparse"` this property gives the frame number to which the first value belongs. - **Type**: integer - - **Requirements/Conventions**: The value MAY be present when **frame_serialization_format** is set to "explicit_regular_sparse", otherwise the value MUST NOT be present. + - **Requirements/Conventions**: The value MAY be present when :property:`frame_serialization_format` is set to :val:`"explicit_regular_sparse"`, otherwise the value MUST NOT be present. The default value is 0. - **Examples**: @@ -2594,9 +2594,9 @@ Each property has a dictionary as the value, with the following fields: - **step_size_sparse**: - - **Description**: If **frame_serialization_format** is set to "explicit_regular_sparse", this value indicates that every step_size_sparse frames a value is defined. + - **Description**: If :property:`frame_serialization_format` is set to :val:` "explicit_regular_sparse"`, this value indicates that every step_size_sparse frames a value is defined. - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when frame_serialization_format is set to "explicit_regular_sparse". + - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to :val:`"explicit_regular_sparse"`. Otherwise it MUST NOT be present. - **Examples**: @@ -2604,11 +2604,11 @@ Each property has a dictionary as the value, with the following fields: - **sparse_frames**: - - **Description**: If **frame_serialization_format** is set to "explicit_custom_sparse", this field holds the frames to which the values in the value field belong. + - **Description**: If :property:`frame_serialization_format` is set to :val:`"explicit_custom_sparse"`, this field holds the frames to which the values in the value field belong. - **Type**: List of integers - - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is set to "explicit_custom_sparse". + - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to "explicit_custom_sparse". Otherwise it MUST NOT be present. - The frame numbers in **sparse_frames** MUST be in the same order as the values. + The frame numbers in :property:`sparse_frames` MUST be in the same order as the values. - **Examples**: - :val:`[0,20,78,345]` @@ -2617,9 +2617,9 @@ Each property has a dictionary as the value, with the following fields: - **values**: - **Description**: The values belonging to this property. - The format of this field depends on the property and on the frame_serialization_format parameter. + The format of this field depends on the property and on the :property:`frame_serialization_format` parameter. - **Type**: List of Any - - **Requirements/Conventions**: The value MUST be present when **frame_serialization_format** is not set to linear. + - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is not set to :val:`"linear"`. If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. This may be useful for grand canonical simulations where the number of particles in the simulation volume is not constant. From 176917875e14f440fcc691176403cf05010eca47 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 09:20:13 +0100 Subject: [PATCH 19/57] Corrected spelling mistake --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index d052bc148..0aa0e37bc 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2344,7 +2344,7 @@ Trajectories Entries The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. - This is describe in more detail in the section `Retrieving the trajectory data`_ + This is described in more detail in the section `Retrieving the trajectory data`_. Queries on individual frames are currently not supported. reference_structure From df284d8b3644a8993ecebefbaaa6acd3140c6725 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 09:46:34 +0100 Subject: [PATCH 20/57] Changed "fields" to "properties at the start of the "Retrieving the trajectory data" section. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 0aa0e37bc..88769f106 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2493,7 +2493,7 @@ available_properties Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, `available_properties`_ and the fields described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. +The preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, `available_properties`_ and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. From 57b801d2626a20abad31857535dee8dd1518a71d Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 10:03:36 +0100 Subject: [PATCH 21/57] Readded uneccesary escape backslashes for underscores so the difference so this PR differs less from the previous version of the OPTIMADE specification. --- optimade.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/optimade.rst b/optimade.rst index 88769f106..942c7e040 100644 --- a/optimade.rst +++ b/optimade.rst @@ -789,7 +789,7 @@ The API implementation MAY provide other entry types than the ones standardized Such entry types MUST be prefixed by a database-provider-specific prefix (i.e., the resource objects' :property:`type` value should start with the database-provider-specific prefix, e.g., :property:`type` = :val:`_exmpl_workflows`). Each custom entry type SHOULD be served at a corresponding entry listing endpoint under the versioned or unversioned base URL that serves the API with the same name (i.e., equal to the resource objects' :property:`type` value, e.g., :endpoint:`/_exmpl_workflows`). It is RECOMMENDED to align with the OPTIMADE API specification practice of using a plural for entry resource types and entry type endpoints. -Any custom entry listing endpoint MUST also be added to the :property:`available_endpoints` and :property:`entry_types_by_format` attributes of the `Base Info Endpoint`_. +Any custom entry listing endpoint MUST also be added to the :property:`available\_endpoints` and :property:`entry\_types\_by\_format` attributes of the `Base Info Endpoint`_. For more on custom endpoints, see `Custom Extension Endpoints`_. @@ -1831,7 +1831,7 @@ elements - **Query**: MUST be a queryable property with support for all mandatory filter features. - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters. - The order MUST be alphabetical. - - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`_, if the latter is provided. + - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements\_ratios`_, if the latter is provided. - Note: This property SHOULD NOT contain the string "X" to indicate non-chemical elements or "vacancy" to indicate vacancies (in contrast to the field :field:`chemical_symbols` for the :property:`species` property). - **Examples**: @@ -1854,7 +1854,7 @@ nelements - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. - - MUST be equal to the lengths of the list properties `elements`_ and `elements_ratios`_, if they are provided. + - MUST be equal to the lengths of the list properties `elements`_ and `elements\_ratios`_, if they are provided. - **Examples**: @@ -2002,8 +2002,8 @@ dimension\_types ~~~~~~~~~~~~~~~~ - **Description**: List of three integers. - For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`_), this list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`). - Note: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors`_ and *not* the Cartesian x, y, z directions. + For each of the three directions indicated by the three lattice vectors (see property `lattice\_vectors`_), this list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`). + Note: the elements in this list each refer to the direction of the corresponding entry in `lattice\_vectors`_ and *not* the Cartesian x, y, z directions. - **Type**: list of integers. - **Requirements/Conventions**: @@ -2022,18 +2022,18 @@ dimension\_types nperiodic\_dimensions ~~~~~~~~~~~~~~~~~~~~~ -- **Description**: An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`_. +- **Description**: An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension\_types`_. - **Type**: integer - **Requirements/Conventions**: - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. - - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types`_ property. + - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension\_types`_ property. - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents. - **Examples**: - - :val:`2` should be indicated in cases where :property:`dimension_types` is any of :val:`[1, 1, 0]`, :val:`[1, 0, 1]`, :val:`[0, 1, 1]`. + - :val:`2` should be indicated in cases where :property:`dimension\_types` is any of :val:`[1, 1, 0]`, :val:`[1, 0, 1]`, :val:`[0, 1, 1]`. - **Query examples**: @@ -2053,10 +2053,10 @@ lattice\_vectors - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates. (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates). - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane. - - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`_. + - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension\_types`_. The vectors SHOULD by convention be chosen so the determinant of the :property:`lattice_vectors` matrix is different from zero. The vectors in the non-periodic directions have no significance beyond fulfilling these requirements. - - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types`_ is :val:`0`) MAY be given as a list of all :val:`null` values. + - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension\_types`_ is :val:`0`) MAY be given as a list of all :val:`null` values. If a lattice vector contains the value :val:`null`, all coordinates of that lattice vector MUST be :val:`null`. - **Examples**: From 5bbef725fb194716a04abdcb32963bba68a43a24 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 11:56:47 +0100 Subject: [PATCH 22/57] Added example query to show how fields within the reference structure should be queried. --- optimade.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/optimade.rst b/optimade.rst index 942c7e040..e9caafe96 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2359,6 +2359,7 @@ reference_structure - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. - Queries on the trajectories MUST be done on the information supplied in the :property:`reference_structure` when the queried property is in the :property:`reference_structure`. The subfields of the reference_structure MUST have the same queryability as in the `structures entries`_. + For example, the query : http://example.com/optimade/v1/trajectories?filter=nelements=2 would use the `nelements`_ property within the reference_structure. - This reference frame has the same properties as the structure entries namely: From e8af14dc6203eba26f518e123a1aa1395ccb81aa Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 12:06:38 +0100 Subject: [PATCH 23/57] Added that the query parameters first_frame, last_frame and frame_step only apply to the trtajectories endpoint. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index e9caafe96..d732d56ea 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2498,7 +2498,7 @@ The preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. -Next to this the client MAY specify the following parameters to customize the return from the server. +Next to this the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. The numbering of the frames is zero based, so the first frame is frame number 0. From e69f8f6b59e8fce068b1c229f528d4abb5c1c479 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 13:34:24 +0100 Subject: [PATCH 24/57] changed frame serialization to frame_serialization_format under in the available properties section. --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index d732d56ea..ef23d4338 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2440,12 +2440,12 @@ available_properties - **Sub dictionary fields** - - **frame_serialization** + - **frame_serialization_format** - **Description**: This property describes how the frames and the returned values of a property are related. - For each **frame_serialization** method there are additional fields that describe how the values belong to the frames. + For each :property:`frame_serialization_format` method there are additional fields that describe how the values belong to the frames. These fields should also be present here. - A complete description of the **frame_serialization** methods and the fields belonging to these methods can be found in the section: `Return Format for Trajectory Data`_ + A complete description of the :property:`frame_serialization_format` methods and the fields belonging to these methods can be found in the section: `Return Format for Trajectory Data`_ - **nvalues**: From aed3e1795501c2723f9a65129a3a0888d2e68886 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 14:02:28 +0100 Subject: [PATCH 25/57] removed sentence about only returning trajectory data when the property is specified in `response_fields` and changed the alinea a bit to make the sentences around it connect better. --- optimade.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index ef23d4338..77e0a6c34 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2340,12 +2340,12 @@ Trajectories Entries :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. - The `reference_structure`_ is an example of the kind of structures that are in the trajectory, and it is used to query the trajectory entries in the same way as the structures entries. - The data belonging to the frames of the trajectory is only returned when this is specifically requested in the :query-param:`response_fields` parameter. - In this case each property has a dictionary as a value which contains the values of this property and information about which value belongs to which frame. + The `reference_structure`_ is an example of the kind of structures that are in the trajectory. + It is used to query the trajectory entries in the same way as the structures entries. + For each property in a trajectory there is a dictionary which contains the values of this property in the trajectory and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. This is described in more detail in the section `Retrieving the trajectory data`_. - Queries on individual frames are currently not supported. + Queries on individual frames are not supported. reference_structure ~~~~~~~~~~~~~~~~~~~ From 875f6cc4faac90ec97249ca9d8b79623293e4dbd Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 17 Dec 2021 14:20:45 +0100 Subject: [PATCH 26/57] Removed undetected trailing white space. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 77e0a6c34..2efd51c56 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2340,7 +2340,7 @@ Trajectories Entries :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. - The `reference_structure`_ is an example of the kind of structures that are in the trajectory. + The `reference_structure`_ is an example of the kind of structures that are in the trajectory. It is used to query the trajectory entries in the same way as the structures entries. For each property in a trajectory there is a dictionary which contains the values of this property in the trajectory and information about which value belongs to which frame. It is possible to request only part of a trajectory and to request only 1 out of every n frames. From c8d87691faf089e699a76bae902dea06f935360d Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 4 Mar 2022 11:41:42 +0100 Subject: [PATCH 27/57] Added missing comma in example available_properties. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 2efd51c56..1748da312 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2481,7 +2481,7 @@ available_properties "_exmpl_pressure":{ "frame_serialization_format": "explicit_custom_sparse", "nvalues": 20 - } + }, "_exmpl_temperature":{ "frame_serialization_format": "explicit_regular_sparse", "step_size_sparse": 10 From 9aadfca8db63cda533a0b5632f0c1c63c5561503 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 2 Jun 2022 14:06:40 +0200 Subject: [PATCH 28/57] Made the frame index start from 1. --- optimade.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/optimade.rst b/optimade.rst index 1748da312..c7ffeca81 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2384,9 +2384,9 @@ reference_frame ~~~~~~~~~~~~~~~ - **Description**: The number of the frame at which the `reference_structure`_ was taken. - The first frame is frame 0. + The first frame is frame 1. - **Type**: integer -- **Requirements/Conventions**: The value MUST be equal or larger than 0 and less than nframes. +- **Requirements/Conventions**: The value MUST be larger than 0 and equal or less than nframes. - **Support**: MUST be supported if the `reference_structure`_ is taken from the trajectory. If the `reference_structure`_ is not in the trajectory, the value MUST NOT be present. @@ -2500,15 +2500,15 @@ The data from the trajectory frames SHOULD only be returned when the user specif Next to this the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. -The numbering of the frames is zero based, so the first frame is frame number 0. +The numbering of the frames is one based, so the first frame is frame number 1. - **first_frame**: - **Description**: **first_frame** specifies the first frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 0 and MUST be less than nframes.(The total number of frames in the trajectory) + - **Requirements/Conventions**: The value MUST be larger than 0 and MUST be less or equal to nframes.(The total number of frames in the trajectory) If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. - The default value is 0. + The default value is 1. - **Examples**: - :query-url:`/trajectories/traj00000001?first_frame=1000` @@ -2517,9 +2517,9 @@ The numbering of the frames is zero based, so the first frame is frame number 0. - **Description**: **last_frame** specifies the last frame that should be returned. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to :property:`first_frame` and MUST be less than `nframes`_ (the total number of frames in the trajectory). + - **Requirements/Conventions**: The value MUST be larger or equal to :property:`first_frame` and MUST not be larger than `nframes`_ (the total number of frames in the trajectory). If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. - The default value is `nframes`_-1. + The default value is `nframes`. - **Examples**: - :query-url:`/trajectories/traj00000001?last_frame=2000` @@ -2528,7 +2528,7 @@ The numbering of the frames is zero based, so the first frame is frame number 0. - **Description**: Specifies that data should only be returned for one out of every :property:`frame_step` frames. - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less than or equal to the total number of frames. + - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less than or equal to `nframes`_. If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. The default value is 1. - **Examples**: @@ -2564,7 +2564,7 @@ Each property has a dictionary as the value, with the following fields: - **offset_linear**: - - **Description**: If :property:`frame_serialization_format` is set to :val:`"linear"` this property gives the value at frame 0. + - **Description**: If :property:`frame_serialization_format` is set to :val:`"linear"` this property gives the value at frame 1. - **Type**: float - **Requirements/Conventions**: The value MAY be present when :property:`frame_serialization_format` is set to :val:`"linear"`, otherwise the value MUST NOT be present. The default value is 0. @@ -2669,7 +2669,7 @@ This is an example of the data field of a JSON object that could be returned aft } ] }, - "reference_frame": 0, + "reference_frame": 1, "nframes": 360, "available_properties":{ "cartesian_site_positions":{ From c817004f5b3406cdda356d6fffa585e12305736b Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 28 Sep 2022 15:55:47 +0200 Subject: [PATCH 29/57] Processed comments Merkys. --- optimade.rst | 68 ++++++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/optimade.rst b/optimade.rst index d0fd4b8d6..836ca8d86 100644 --- a/optimade.rst +++ b/optimade.rst @@ -149,7 +149,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH For example, a :entry:`structures` entry is comprised by data that belong to a single structure. **Entry type** - Entries are categorized into types, e.g., :entry:`structures`, :entry:`trajectories`, :entry:`calculations`, :entry:`references`. + Entries are categorized into types, e.g., :entry:`structures`, :entry:`calculations`, :entry:`references`. Entry types MUST be named according to the rules for identifiers. **Entry property** @@ -197,9 +197,9 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH In this case, **field** refers to the name part of the name-value pairs of JSON objects. **Trajectory** - A Trajectory contains data belonging to a set of structures. + A Trajectory contains data belonging to a sequence of structures. Usually this data will come from molecular dynamics simulations. - It can however also contain data from structures that are related in an different way. + It can however also contain data from structures that are related in a different way. For example the successive structures from a Monte Carlo simulation. **Frame** @@ -332,7 +332,7 @@ Index Meta-Database A database provider MAY publish a special Index Meta-Database base URL. The main purpose of this base URL is to allow for automatic discoverability of all databases of the provider. Thus, it acts as a meta-database for the database provider's implementation(s). The index meta-database MUST only provide the :endpoint:`info` and :endpoint:`links` endpoints, see sections `Info Endpoints`_ and `Links Endpoint`_. -It MUST NOT expose any entry listing endpoints (e.g., :endpoint:`structures` and :endpoint:`trajectories`). +It MUST NOT expose any entry listing endpoints (e.g., :endpoint:`structures`). These endpoints do not need to be queryable, i.e., they MAY be provided as static JSON files. However, they MUST return the correct and updated information on all currently provided implementations. @@ -2823,7 +2823,7 @@ Trajectories Entries - **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. Usually this data will come from molecular dynamics simulations. - It can however also be used to share data from structures that are related in an other way. + It can however also be used to share data from structures that are related in another way. For example the successive structures from a Monte Carlo simulation. Some examples of the data that can be shared are the particle positions, the pressure and the energies. @@ -2848,10 +2848,8 @@ reference_structure - Each trajectory MUST have a :property:`reference_structure`. - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. - Queries on the trajectories MUST be done on the information supplied in the :property:`reference_structure` when the queried property is in the :property:`reference_structure`. - The subfields of the reference_structure MUST have the same queryability as in the `structures entries`_. For example, the query : http://example.com/optimade/v1/trajectories?filter=nelements=2 would use the `nelements`_ property within the reference_structure. - - - This reference frame has the same properties as the structure entries namely: + - This reference frame has the same properties as the `structures entries`_ namely: - `elements`_ - `nelements`_ @@ -2870,6 +2868,8 @@ reference_structure - `assemblies`_ - `structure_features`_ + - The subfields of the :property:`reference_structure` MUST have the same queryability as in the :entry:`structures` entries. + reference_frame ~~~~~~~~~~~~~~~ @@ -2946,7 +2946,6 @@ available_properties - :val:`100` - - **Examples**: .. code:: jsonc @@ -3127,7 +3126,7 @@ This is an example of the data field of a JSON object that could be returned aft "id": "traj00000001", "type": "trajectories", "attributes": { - "last_modified":"2021-07-16T18:02:03Z" + "last_modified":"2021-07-16T18:02:03Z", "reference_structure":{ "elements": ["H","O"], "nelements": 2, @@ -3145,17 +3144,17 @@ This is an example of the data field of a JSON object that could be returned aft { "name":"O1", "chemical_symbols":["O"], - "concentration":[1.0], + "concentration":[1.0] }, { "name":"H1", "chemical_symbols":["H"], - "concentration":[1.0], + "concentration":[1.0] }, { "name":"H2", "chemical_symbols":["H"], - "concentration":[1.0], + "concentration":[1.0] } ] }, @@ -3210,13 +3209,14 @@ This is an example of the data field of a JSON object that could be returned aft After the previous querry is an example of a JSON object that could be returned after the following query: :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` -.. code:: jsonc +.. code:: json + { "data":{ "id": "traj00000001", "type": "trajectories", - "attributes:{ - "last_modified":"2021-07-16T18:02:03Z" + "attributes":{ + "last_modified":"2021-07-16T18:02:03Z", "cartesian_site_positions":{ "frame_serialization_format": "explicit", "values":[ @@ -3235,11 +3235,11 @@ After the previous querry is an example of a JSON object that could be returned }, "lattice_vectors":{ "frame_serialization_format": "constant", - "values:[[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]]], + "values":[[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]]] }, "dimension_types":{ "frame_serialization_format": "constant", - "values:[[0,0,0]] + "values":[[0,0,0]] }, "_exmpl_time":{ "frame_serialization_format": "linear", @@ -3247,9 +3247,9 @@ After the previous querry is an example of a JSON object that could be returned "step_size_linear": 1.5 }, "_exmpl_ekin":{ - "frame_serialization_format": "explicit_regular_sparse", - "step_size_sparse": 2, - "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] + "frame_serialization_format": "explicit_regular_sparse", + "step_size_sparse": 2, + "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] }, "species":{ "frame_serialization_format": "constant", @@ -3257,38 +3257,38 @@ After the previous querry is an example of a JSON object that could be returned { "name":"O1", "chemical_symbols":["O"], - "concentration":[1.0], + "concentration":[1.0] },{ "name":"H1", "chemical_symbols":["H"], - "concentration":[1.0], + "concentration":[1.0] },{ "name":"H2", "chemical_symbols":["H"], - "concentration":[1.0], + "concentration":[1.0] } ]] }, "species_at_sites":{ "frame_serialization_format": "constant", - "values":[["O1","H1","H2"]], + "values":[["O1","H1","H2"]] }, "_exmpl_temperature_set":{ "frame_serialization_format": "explicit_custom_sparse", "sparse_frames":[0,4,5,9], "values":[273,273,293,293] } - } - }, - "links":{ - "next":"http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", - "base_url": { - "href": "http://example.com/optimade", - "meta": { - "_exmpl_db_version": "3.2.1" + }, + "links":{ + "next":"http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", + "base_url": { + "href": "http://example.com/optimade", + "meta": { + "_exmpl_db_version": "3.2.1" + } } } - } + }, ... Calculations Entries From b51758dfedf92e1ccdd564fce02c84faaeac8c06 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 28 Sep 2022 18:53:29 +0200 Subject: [PATCH 30/57] Removed frame and trajectory from Definition of Terms. --- optimade.rst | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/optimade.rst b/optimade.rst index 836ca8d86..622e6317b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -196,15 +196,6 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH This is particularly relevant for the default JSON-based response format. In this case, **field** refers to the name part of the name-value pairs of JSON objects. -**Trajectory** - A Trajectory contains data belonging to a sequence of structures. - Usually this data will come from molecular dynamics simulations. - It can however also contain data from structures that are related in a different way. - For example the successive structures from a Monte Carlo simulation. - -**Frame** - An individual structure or data belonging to an individual structure from a trajectory. - Data types ---------- @@ -2821,10 +2812,11 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` entry point is used to share data from molecular simulations. +- **Description**: The :entry:`trajectories` entry point is used to share data belonging to sequences of structures. Usually this data will come from molecular dynamics simulations. It can however also be used to share data from structures that are related in another way. - For example the successive structures from a Monte Carlo simulation. + For example, the successive structures from a Monte Carlo simulation. + The individual structures 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 following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. From bb6acaa2577ed800406dad7fefddc2d8371056fc Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 28 Sep 2022 19:41:22 +0200 Subject: [PATCH 31/57] Further improvements to JSON examples. --- optimade.rst | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/optimade.rst b/optimade.rst index 622e6317b..c7fa8439e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3114,6 +3114,7 @@ This is an example of the data field of a JSON object that could be returned aft .. code:: jsonc + { "data":{ "id": "traj00000001", "type": "trajectories", @@ -3158,20 +3159,20 @@ This is an example of the data field of a JSON object that could be returned aft "nvalues":360 }, "species":{ - "frame_serialization_format": "constant", + "frame_serialization_format": "constant" }, "dimension_types":{ - "frame_serialization_format": "constant", + "frame_serialization_format": "constant" }, "lattice_vectors":{ - "frame_serialization_format": "constant", + "frame_serialization_format": "constant" }, "species_at_sites":{ - "frame_serialization_format": "constant", + "frame_serialization_format": "constant" }, "_exmpl_temperature_set":{ "frame_serialization_format": "explicit_custom_sparse", - "nvalues":144, + "nvalues":144 }, "_exmpl_time":{ "frame_serialization_format": "linear", @@ -3181,9 +3182,9 @@ This is an example of the data field of a JSON object that could be returned aft "_exmpl_ekin":{ "frame_serialization_format": "explicit_regular_sparse", "step_size_sparse": 2, - "nvalues":180, + "nvalues":180 } - } + }, "relationships": { "references": { "data": [ @@ -3194,14 +3195,14 @@ This is an example of the data field of a JSON object that could be returned aft ] } } - }, - }, - ... - + } + } + //,... + } After the previous querry is an example of a JSON object that could be returned after the following query: :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` -.. code:: json +.. code:: jsonc { "data":{ @@ -3270,18 +3271,19 @@ After the previous querry is an example of a JSON object that could be returned "sparse_frames":[0,4,5,9], "values":[273,273,293,293] } - }, - "links":{ - "next":"http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", - "base_url": { - "href": "http://example.com/optimade", - "meta": { - "_exmpl_db_version": "3.2.1" - } - } } }, - ... + "links":{ + "next":"http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", + "base_url": { + "href": "http://example.com/optimade", + "meta": { + "_exmpl_db_version": "3.2.1" + } + } + } + //,... + } Calculations Entries -------------------- From fe6f0d79655080b1282435ef006d096f6eaa5926 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 28 Sep 2022 21:53:18 +0200 Subject: [PATCH 32/57] Capitalized Structures Entries when referring to section 8.2. --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index c7fa8439e..64908ae4c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2820,7 +2820,7 @@ Trajectories Entries 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 following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. - Next to this they can optionally have all the fields of the structures entries as well as relationships and database specific fields. + Next to this they can optionally have all the fields of the Structures Entries`_ as well as relationships and database specific fields. The `reference_structure`_ is an example of the kind of structures that are in the trajectory. It is used to query the trajectory entries in the same way as the structures entries. @@ -2841,7 +2841,7 @@ reference_structure - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. - Queries on the trajectories MUST be done on the information supplied in the :property:`reference_structure` when the queried property is in the :property:`reference_structure`. For example, the query : http://example.com/optimade/v1/trajectories?filter=nelements=2 would use the `nelements`_ property within the reference_structure. - - This reference frame has the same properties as the `structures entries`_ namely: + - This reference frame has the same properties as the `Structures Entries`_ namely: - `elements`_ - `nelements`_ @@ -3023,7 +3023,7 @@ Return format for Trajectory Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The returned data is first grouped per property and then by frame. -The property can be any of the fields described under `structures entries`_ or a database specific field. +The property can be any of the fields described under `Structures Entries`_ or a database specific field. Each property has a dictionary as the value, with the following fields: - **frame_serialization_format**: From 378994397fcf43865688bcb270a34af4b56605b8 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Sep 2022 11:02:35 +0200 Subject: [PATCH 33/57] removed commas from JSON comment lines. --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 64908ae4c..c7a792c71 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3197,7 +3197,7 @@ This is an example of the data field of a JSON object that could be returned aft } } } - //,... + //... } After the previous querry is an example of a JSON object that could be returned after the following query: :query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` @@ -3282,7 +3282,7 @@ After the previous querry is an example of a JSON object that could be returned } } } - //,... + //... } Calculations Entries From 5ba755f95d7ff5ae51e34bee5279c8db1ccb1117 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Sep 2022 11:18:32 +0200 Subject: [PATCH 34/57] Removed lines which stated queries must be performed on the properties in the reference structure. --- optimade.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index c7a792c71..a3696979c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2839,8 +2839,6 @@ reference_structure - Each trajectory MUST have a :property:`reference_structure`. - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. - - Queries on the trajectories MUST be done on the information supplied in the :property:`reference_structure` when the queried property is in the :property:`reference_structure`. - For example, the query : http://example.com/optimade/v1/trajectories?filter=nelements=2 would use the `nelements`_ property within the reference_structure. - This reference frame has the same properties as the `Structures Entries`_ namely: - `elements`_ From e8c5577f02f37e216c49d2211de2221a7a0ccc06 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Sep 2022 14:38:24 +0200 Subject: [PATCH 35/57] Apply suggestions from code review rartino Co-authored-by: Rickard Armiento --- optimade.rst | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/optimade.rst b/optimade.rst index a3696979c..85d6be846 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2838,7 +2838,7 @@ reference_structure - **Requirements/Conventions**: - Each trajectory MUST have a :property:`reference_structure`. - - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field MUST specify which frame has been used. + - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field SHOULD specify which frame has been used. - This reference frame has the same properties as the `Structures Entries`_ namely: - `elements`_ @@ -2868,11 +2868,11 @@ reference_frame - **Type**: integer - **Requirements/Conventions**: The value MUST be larger than 0 and equal or less than nframes. - - **Support**: MUST be supported if the `reference_structure`_ is taken from the trajectory. - If the `reference_structure`_ is not in the trajectory, the value MUST NOT be present. + - **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. - + - SHOULD NOT be :val:`null` if the `reference_structure`_ is in the trajectory. + - MUST be :val:`null` or omitted if `reference_structure`_ is not in the trajectory. - **Examples**: - :val:`42` @@ -2940,44 +2940,51 @@ available_properties .. code:: jsonc - "available_properties": { - "cartesian_site_positions": { + "available_properties": [ + { + "property": "cartesian_site_positions", "frame_serialization_format": "explicit", "nvalues": 1000 }, - "lattice_vectors":{ + { + "property": "lattice_vectors", "frame_serialization_format": "constant", }, - "species":{ + { + "property": "species", "frame_serialization_format": "constant", }, - "dimension_types":{ + { + "property": "dimension_types", "frame_serialization_format": "constant", }, - "species_at_sites":{ + { + "property": "species_at_sites", "frame_serialization_format": "constant", }, - "_exmpl_pressure":{ + { + "property": "_exmpl_pressure", "frame_serialization_format": "explicit_custom_sparse", "nvalues": 20 }, - "_exmpl_temperature":{ + { + "property": "_exmpl_temperature", "frame_serialization_format": "explicit_regular_sparse", "step_size_sparse": 10 "nvalues": 100 } - } + ] Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, `available_properties`_ and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. +For queries referencing the :endpoint:`trajectories` endpoint, the preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, `available_properties`_ and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. -Next to this the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. +Furthermore, the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. The numbering of the frames is one based, so the first frame is frame number 1. From bd3bbd87346f284eef77a6db3705a9078461fb57 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Sep 2022 15:05:09 +0200 Subject: [PATCH 36/57] processed remark rartino and removed trailing whitespace. --- optimade.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/optimade.rst b/optimade.rst index 85d6be846..bf15c464d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2812,10 +2812,8 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` entry point is used to share data belonging to sequences of structures. - Usually this data will come from molecular dynamics simulations. - It can however also be used to share data from structures that are related in another way. - For example, the successive structures from a Monte Carlo simulation. +- **Description**: The :entry:`trajectories` entry is used to share data belonging to sequences of structures, e.g., from a molecular dynamics simulation or a Monte Carlo simulation. + The individual structures of the trajectories are called frames. Some examples of the data that can be shared are the particle positions, the pressure and the energies. @@ -2871,7 +2869,7 @@ reference_frame - **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. - - SHOULD NOT be :val:`null` if the `reference_structure`_ is in the trajectory. + - SHOULD NOT be :val:`null` if the `reference_structure`_ is in the trajectory. - MUST be :val:`null` or omitted if `reference_structure`_ is not in the trajectory. - **Examples**: From c32c477e33f7c3fa9c1fc9529742a3241b28b909 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Sep 2022 16:07:29 +0200 Subject: [PATCH 37/57] removed trailing white space Co-authored-by: Rickard Armiento --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index bf15c464d..3c92f6212 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2940,7 +2940,7 @@ available_properties "available_properties": [ { - "property": "cartesian_site_positions", + "property": "cartesian_site_positions", "frame_serialization_format": "explicit", "nvalues": 1000 }, From 952ef2a6bd31ba253d079fda579fcf73953a2579 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 4 Oct 2022 12:33:19 +0200 Subject: [PATCH 38/57] Apply suggestions from code review ml-evs Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/optimade.rst b/optimade.rst index 3c92f6212..72cc574d5 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2818,7 +2818,7 @@ Trajectories Entries 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 following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. - Next to this they can optionally have all the fields of the Structures Entries`_ as well as relationships and database specific fields. + Next to this they can optionally have all the fields of the `Structures Entries`_ as well as relationships and database specific fields. The `reference_structure`_ is an example of the kind of structures that are in the trajectory. It is used to query the trajectory entries in the same way as the structures entries. @@ -2830,14 +2830,14 @@ Trajectories Entries reference_structure ~~~~~~~~~~~~~~~~~~~ -- **Description**: This is an example of the structures that can be found in the trajectory. - It can be used to select trajectories with queries and to give a quick visual impression of the structures in this trajectory. +- **Description**: A representative example of the structures that make up the trajectory. + This structure is used when filtering trajectories according to fixed properties of the underlying frames, such as composition or dimensionality. - **Type**: dictionary - **Requirements/Conventions**: - Each trajectory MUST have a :property:`reference_structure`. - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field SHOULD specify which frame has been used. - - This reference frame has the same properties as the `Structures Entries`_ namely: + - This reference frame has the same properties outlined in `Structures Entries`_, namely: - `elements`_ - `nelements`_ @@ -2856,12 +2856,12 @@ reference_structure - `assemblies`_ - `structure_features`_ - - The subfields of the :property:`reference_structure` MUST have the same queryability as in the :entry:`structures` entries. + - The subfields of the :property:`reference_structure` have the same support and queryability constraints as the corresponding :entry:`structures` entry fields. reference_frame ~~~~~~~~~~~~~~~ -- **Description**: The number of the frame at which the `reference_structure`_ was taken. +- **Description**: The index of the frame from which the `reference_structure`_ was taken. The first frame is frame 1. - **Type**: integer - **Requirements/Conventions**: The value MUST be larger than 0 and equal or less than nframes. @@ -2869,8 +2869,8 @@ reference_frame - **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. - - SHOULD NOT be :val:`null` if the `reference_structure`_ is in the trajectory. - - MUST be :val:`null` or omitted if `reference_structure`_ is not in the trajectory. + - SHOULD NOT be :val:`null` if the `reference_structure`_ exactly matches the structure at the index `reference_frame`_ in the trajectory. + - MUST be :val:`null` or omitted if `reference_structure`_ is not an exact match to any structure in the trajectory. - **Examples**: - :val:`42` @@ -2878,7 +2878,7 @@ reference_frame nframes ~~~~~~~ -- **Description**: The number of the frames in the trajectory. +- **Description**: The number of frames in the trajectory. - **Type**: integer - **Requirements/Conventions**: From 4958296060e2ad3faad30130a790f8cda73ee20f Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 4 Oct 2022 14:44:49 +0200 Subject: [PATCH 39/57] Added extra explanation to field nframes. --- optimade.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/optimade.rst b/optimade.rst index 3c92f6212..80b488d52 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2818,14 +2818,8 @@ Trajectories Entries 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 following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. - Next to this they can optionally have all the fields of the Structures Entries`_ as well as relationships and database specific fields. + Furthermore, :entry:`trajectories` can optionally have all the fields of the Structures Entries`_ as well as relationships and database specific fields. - The `reference_structure`_ is an example of the kind of structures that are in the trajectory. - It is used to query the trajectory entries in the same way as the structures entries. - For each property in a trajectory there is a dictionary which contains the values of this property in the trajectory and information about which value belongs to which frame. - It is possible to request only part of a trajectory and to request only 1 out of every n frames. - This is described in more detail in the section `Retrieving the trajectory data`_. - Queries on individual frames are not supported. reference_structure ~~~~~~~~~~~~~~~~~~~ @@ -2878,7 +2872,9 @@ reference_frame nframes ~~~~~~~ -- **Description**: The number of the frames in the trajectory. +- **Description**: The number of the frames in the trajectory as exposed by the API. + This value may deviate from the number 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**: From a6cd4945203247246f176d74234475b6cee74a8f Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 6 Oct 2022 12:59:45 +0200 Subject: [PATCH 40/57] Add remark rartino Co-authored-by: Rickard Armiento --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 72cc574d5..df4538ab5 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3202,7 +3202,7 @@ This is an example of the data field of a JSON object that could be returned aft } //... } -After the previous querry is an example of a JSON object that could be returned after the following query: +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, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` .. code:: jsonc From d210a97250e6772171643d6a9669db3e9703266a Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Sat, 15 Oct 2022 20:21:16 +0200 Subject: [PATCH 41/57] Changed MUST to SHOULD for the support level of theg first_frame, last_frame and frame_step parameters for servers. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 80b488d52..7ff14cc99 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2979,7 +2979,7 @@ For queries referencing the :endpoint:`trajectories` endpoint, the preceding pro The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. Furthermore, the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. -While these URL query parameters are OPTIONAL for clients, API implementations MUST accept and handle them. +While these URL query parameters are OPTIONAL for clients, API implementations SHOULD accept and handle them. The numbering of the frames is one based, so the first frame is frame number 1. - **first_frame**: From 9d0df98ed387c21bf6ee60ca706bb08c0b3b8ebd Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 7 Dec 2022 16:06:28 +0100 Subject: [PATCH 42/57] Removed Available properties field. --- optimade.rst | 86 +++------------------------------------------------- 1 file changed, 5 insertions(+), 81 deletions(-) diff --git a/optimade.rst b/optimade.rst index 3e4f5b937..ee13914c9 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2812,13 +2812,13 @@ structure\_features Trajectories Entries -------------------- -- **Description**: The :entry:`trajectories` entry is used to share data belonging to sequences of structures, e.g., from a molecular dynamics simulation or a Monte Carlo simulation. +- **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 structures 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 following properties: `reference_structure`_, `reference_frame`_, `nframes`_ and `available_properties`_. - Furthermore, :entry:`trajectories` can optionally have all the fields of the Structures Entries`_ as well as relationships and database specific fields. + :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the following properties: `reference_structure`_, `reference_frame`_ and `nframes`_. + Furthermore, :entry:`trajectories` can optionally have relationships and database specific fields as well as "ranged" properties that contain the values of that property for the frames of the trajectory. reference_structure @@ -2829,7 +2829,7 @@ reference_structure - **Type**: dictionary - **Requirements/Conventions**: - - Each trajectory MUST have a :property:`reference_structure`. + - Each trajectory MAY have a :property:`reference_structure`. - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field SHOULD specify which frame has been used. - This reference frame has the same properties outlined in `Structures Entries`_, namely: @@ -2894,87 +2894,11 @@ nframes - :val:`42` -available_properties -~~~~~~~~~~~~~~~~~~~~ - -- **Description**: A dictionary with an entry for each of the properties for which data is available in the trajectory. - The key is the name of the property. - The value is a dictionary containing information about which value belongs to which frame. - This makes it easier for a client to estimate the amount of data a query returns. - - It is up to the server to decide which properties to share and there are no mandatory fields. - When sharing `cartesian_site_positions`_ the `lattice_vectors`_, `species`_, `dimension_types`_ and `species_at_sites`_ MUST however be shared as well. - - -- **Type**: dictionary of dictionaries -- **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. - -- **Sub dictionary fields** - - - **frame_serialization_format** - - - **Description**: This property describes how the frames and the returned values of a property are related. - For each :property:`frame_serialization_format` method there are additional fields that describe how the values belong to the frames. - These fields should also be present here. - A complete description of the :property:`frame_serialization_format` methods and the fields belonging to these methods can be found in the section: `Return Format for Trajectory Data`_ - - - **nvalues**: - - - **Description**: This field gives the number of values for this property. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to explicit, explicit_regular_sparse or explicit_custom_sparse. - - **Examples**: - - - :val:`100` - -- **Examples**: - - .. code:: jsonc - - "available_properties": [ - { - "property": "cartesian_site_positions", - "frame_serialization_format": "explicit", - "nvalues": 1000 - }, - { - "property": "lattice_vectors", - "frame_serialization_format": "constant", - }, - { - "property": "species", - "frame_serialization_format": "constant", - }, - { - "property": "dimension_types", - "frame_serialization_format": "constant", - }, - { - "property": "species_at_sites", - "frame_serialization_format": "constant", - }, - { - "property": "_exmpl_pressure", - "frame_serialization_format": "explicit_custom_sparse", - "nvalues": 20 - }, - { - "property": "_exmpl_temperature", - "frame_serialization_format": "explicit_regular_sparse", - "step_size_sparse": 10 - "nvalues": 100 - } - ] - - Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For queries referencing the :endpoint:`trajectories` endpoint, the preceding properties `reference_structure`_, `reference_frame`_, `nframes`_, `available_properties`_ and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. +For queries referencing the :endpoint:`trajectories` endpoint, the preceding properties `reference_structure`_, `reference_frame`_, `nframes`_ and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. From a73f5c181f73ea1f51231b9b4eb65e0afd058d39 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 7 Dec 2022 18:20:36 +0100 Subject: [PATCH 43/57] removed last reference to solely using the reference structure for querying. --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index ee13914c9..f99975048 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2825,7 +2825,7 @@ reference_structure ~~~~~~~~~~~~~~~~~~~ - **Description**: A representative example of the structures that make up the trajectory. - This structure is used when filtering trajectories according to fixed properties of the underlying frames, such as composition or dimensionality. + This structure can be used to give a quick visualization of the type of structures that are present in the trajectory. - **Type**: dictionary - **Requirements/Conventions**: @@ -2898,9 +2898,9 @@ nframes Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For queries referencing the :endpoint:`trajectories` endpoint, the preceding properties `reference_structure`_, `reference_frame`_, `nframes`_ and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. +For queries referencing the :endpoint:`trajectories` endpoint, the ranged properties and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. For the ranged properties, only the metadata fields should be returned in this case. -The data from the trajectory frames SHOULD only be returned when the user specifically requests these properties in the response_fields. +The values of the ranged properties SHOULD only be returned when the user specifically requests these properties in the response_fields. Furthermore, the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. While these URL query parameters are OPTIONAL for clients, API implementations SHOULD accept and handle them. From a65f5868273416155e8aac2092dd47aa1f9ca7ad Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 8 Dec 2022 12:32:35 +0100 Subject: [PATCH 44/57] Removed reference to using the response_field parameter to trigger returning trajectory data. --- optimade.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/optimade.rst b/optimade.rst index f99975048..938bfc4e4 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2814,7 +2814,7 @@ 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 structures of the trajectories are called frames. + 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 following properties: `reference_structure`_, `reference_frame`_ and `nframes`_. @@ -2828,8 +2828,8 @@ reference_structure This structure can be used to give a quick visualization of the type of structures that are present in the trajectory. - **Type**: dictionary - **Requirements/Conventions**: +- **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - - Each trajectory MAY have a :property:`reference_structure`. - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field SHOULD specify which frame has been used. - This reference frame has the same properties outlined in `Structures Entries`_, namely: @@ -2898,11 +2898,10 @@ nframes Retrieving the trajectory data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For queries referencing the :endpoint:`trajectories` endpoint, the ranged properties and the properties described under `Properties Used by Multiple Entry Types`_ MUST be returned when no :query-param:`response_fields` property (see the section `Entry Listing URL Query Parameters`_) is specified. For the ranged properties, only the metadata fields should be returned in this case. +By default only the metadata fields should be returned for the ranged properties. +The values of the ranged properties SHOULD only be returned when the user specifies a range of frames with the query parameters described below. -The values of the ranged properties SHOULD only be returned when the user specifically requests these properties in the response_fields. - -Furthermore, the client MAY specify the following parameters to customize the return from the server at the trajectory endpoint. +The client can use these parameters to customize the return from the server at the trajectory endpoint. While these URL query parameters are OPTIONAL for clients, API implementations SHOULD accept and handle them. The numbering of the frames is one based, so the first frame is frame number 1. From 9b752540666930a80f44585044ff07d4d1d37688 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 20 Mar 2023 15:50:58 +0100 Subject: [PATCH 45/57] Updated description trajectory endpoint for new ranged property definition. --- optimade.rst | 406 +++++++++++++++++---------------------------------- 1 file changed, 136 insertions(+), 270 deletions(-) diff --git a/optimade.rst b/optimade.rst index 04b227d80..cd9405471 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2869,54 +2869,24 @@ Trajectories Entries 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 following properties: `reference_structure`_, `reference_frame`_ and `nframes`_. + :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 and database specific fields as well as "ranged" properties that contain the values of that property for the frames of the trajectory. - - -reference_structure -~~~~~~~~~~~~~~~~~~~ - -- **Description**: A representative example of the structures that make up the trajectory. - This structure can be used to give a quick visualization of the type of structures that are present in the trajectory. -- **Type**: dictionary -- **Requirements/Conventions**: -- **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - - - This :property:`reference_structure` MAY be one of the frames from the trajectory, in that case the `reference_frame`_ field SHOULD specify which frame has been used. - - This reference frame has the same properties outlined in `Structures Entries`_, namely: - - - `elements`_ - - `nelements`_ - - `elements_ratios`_ - - `chemical_formula_descriptive`_ - - `chemical_formula_reduced`_ - - `chemical_formula_hill`_ - - `chemical_formula_anonymous`_ - - `dimension_types`_ - - `nperiodic_dimensions`_ - - `lattice_vectors`_ - - `cartesian_site_positions`_ - - `nsites`_ - - `species_at_sites`_ - - `species`_ - - `assemblies`_ - - `structure_features`_ - - - The subfields of the :property:`reference_structure` have the same support and queryability constraints as the corresponding :entry:`structures` entry fields. + In addition they can have 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. + The dimension that corresponds to the steps of the trajectory MUST be have the :field:`range_id`=:val:`frames`. reference_frame ~~~~~~~~~~~~~~~ -- **Description**: The index of the frame from which the `reference_structure`_ was taken. - The first frame is frame 1. +- **Description**: The index of a frame that, according the server, would be a good example of the structures in the trajectory. - **Type**: integer - **Requirements/Conventions**: The value 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. - - SHOULD NOT be :val:`null` if the `reference_structure`_ exactly matches the structure at the index `reference_frame`_ in the trajectory. - - MUST be :val:`null` or omitted if `reference_structure`_ is not an exact match to any structure in the trajectory. + - **Examples**: - :val:`42` @@ -2947,139 +2917,6 @@ nframes - :val:`42` -Retrieving the trajectory data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default only the metadata fields should be returned for the ranged properties. -The values of the ranged properties SHOULD only be returned when the user specifies a range of frames with the query parameters described below. - -The client can use these parameters to customize the return from the server at the trajectory endpoint. -While these URL query parameters are OPTIONAL for clients, API implementations SHOULD accept and handle them. -The numbering of the frames is one based, so the first frame is frame number 1. - -- **first_frame**: - - - **Description**: **first_frame** specifies the first frame that should be returned. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger than 0 and MUST be less or equal to nframes.(The total number of frames in the trajectory) - If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. - The default value is 1. - - **Examples**: - - - :query-url:`/trajectories/traj00000001?first_frame=1000` - -- **last_frame**: - - - **Description**: **last_frame** specifies the last frame that should be returned. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to :property:`first_frame` and MUST not be larger than `nframes`_ (the total number of frames in the trajectory). - If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. - The default value is `nframes`. - - **Examples**: - - - :query-url:`/trajectories/traj00000001?last_frame=2000` - -- **frame_step**: - - - **Description**: Specifies that data should only be returned for one out of every :property:`frame_step` frames. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be larger or equal to 1 and MUST be less than or equal to `nframes`_. - If this is not the case :http-error:`400 Bad Request` MUST be returned with a message indicating that the value for this field is incorrect. - The default value is 1. - - **Examples**: - - - :query-url:`/trajectories/traj00000001?frame_step=10`. - -The server can decide how many frames are returned for each request. -If the number of frames returned is less than the total number of frames requested by a client the server has to supply a link in the :field:`next` field of the :field:`links` section of the JSON response, which the client can use to download the rest of the trajectory. - -Return format for Trajectory Data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The returned data is first grouped per property and then by frame. -The property can be any of the fields described under `Structures Entries`_ or a database specific field. -Each property has a dictionary as the value, with the following fields: - -- **frame_serialization_format**: - - - **Description**: To improve the compactness of the data there are several ways to show to which frame a value belongs. - This is specified by the :property:`frame_serialization_format`. - - **Type**: string - - **Requirements/Conventions**: This field MUST be present. - - **Values**: - - - **constant**: The value of the property is constant and thus has the same value for each frame in the trajectory. - - **explicit**: A value is given for each frame. - The number of values MUST thus be equal to the number of frames and MUST be in the same order as the frames. - If there is no value for a particular frame the value MUST be :val:`null`. - - **linear**: The value is a linear function of the frame number. - This function is defined by :property:`offset_linear` and :property:`step_size_linear`. - - **explicit_regular_sparse**: The value is set every one per :property:`step_size_sparse` frames, with :property:`offset_sparse` as the first frame. - - **explicit_custom_sparse**: A separate list with frame numbers is defined in the field :property:`sparse_frames` to indicate to which frame a value belongs. - -- **offset_linear**: - - - **Description**: If :property:`frame_serialization_format` is set to :val:`"linear"` this property gives the value at frame 1. - - **Type**: float - - **Requirements/Conventions**: The value MAY be present when :property:`frame_serialization_format` is set to :val:`"linear"`, otherwise the value MUST NOT be present. - The default value is 0. - - **Examples**: - - - :val:`1.5` - -- **step_size_linear**: - - - **Description**: If :property:`frame_serialization_format` is set to :val:`"linear"`, this value gives the change in the value of the property per unit of frame number. - e.g. If at frame 3 the value of the property is 0.6 and :property:`step_size_linear` = 0.2 than at frame 4 the value of the property will be 0.8. - - **Type**: float - - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to "linear". - Otherwise it MUST NOT be present. - - **Examples**: - - - :val:`0.0005` - -- **offset_sparse**: - - - **Description**: If :property:`frame_serialization_format` is set to :val:` "explicit_regular_sparse"` this property gives the frame number to which the first value belongs. - - **Type**: integer - - **Requirements/Conventions**: The value MAY be present when :property:`frame_serialization_format` is set to :val:`"explicit_regular_sparse"`, otherwise the value MUST NOT be present. - The default value is 0. - - **Examples**: - - - :val:`100` - -- **step_size_sparse**: - - - **Description**: If :property:`frame_serialization_format` is set to :val:` "explicit_regular_sparse"`, this value indicates that every step_size_sparse frames a value is defined. - - **Type**: integer - - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to :val:`"explicit_regular_sparse"`. - Otherwise it MUST NOT be present. - - **Examples**: - - - :val:`100` - -- **sparse_frames**: - - - **Description**: If :property:`frame_serialization_format` is set to :val:`"explicit_custom_sparse"`, this field holds the frames to which the values in the value field belong. - - **Type**: List of integers - - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is set to "explicit_custom_sparse". - Otherwise it MUST NOT be present. - The frame numbers in :property:`sparse_frames` MUST be in the same order as the values. - - **Examples**: - - - :val:`[0,20,78,345]` - - -- **values**: - - - **Description**: The values belonging to this property. - The format of this field depends on the property and on the :property:`frame_serialization_format` parameter. - - **Type**: List of Any - - **Requirements/Conventions**: The value MUST be present when :property:`frame_serialization_format` is not set to :val:`"linear"`. - If a value has not been sampled for a particular frame the value should be set to :val:`null` at the highest possible nesting level. - In case of `cartesian_site_positions`_, a site that has the value :val:`null` for the x,y and z coordinates means that the site is not in the simulation volume. - This may be useful for grand canonical simulations where the number of particles in the simulation volume is not constant. - Examples of a returned trajectory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3094,37 +2931,46 @@ This is an example of the data field of a JSON object that could be returned aft "type": "trajectories", "attributes": { "last_modified":"2021-07-16T18:02:03Z", - "reference_structure":{ - "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" : [[2,2,2],[1.238,2.000,1.416],[2.762,2.000,1.416]], - "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] - } - ] - }, + "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" : None, + "cartesian_site_positions_meta" : { + "range": { + "serialization_format" : "regular", + "nindexable_dim": 3,` + "dim_size": [360, 3, 3], + "nvalues": 3240, + "step_size_regular" : 1, + "offset_regular": 1, + "range_ids": ["frames", "particles", "xyz"] + } + } + "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, "available_properties":{ @@ -3144,22 +2990,39 @@ This is an example of the data field of a JSON object that could be returned aft "species_at_sites":{ "frame_serialization_format": "constant" }, - "_exmpl_temperature_set":{ - "frame_serialization_format": "explicit_custom_sparse", - "nvalues":144 - }, - "_exmpl_time":{ - "frame_serialization_format": "linear", - "offset_linear": 0, - "step_size_linear": 1.5 - }, - "_exmpl_ekin":{ - "frame_serialization_format": "explicit_regular_sparse", - "step_size_sparse": 2, - "nvalues":180 + "_exmpl_temperature_set": null, + "_exmpl_temperature_set_meta":{ + "range": { + "serialization_format": "custom", + "nindexable_dim": 1,` + "dim_size": [360], + "nvalues": 144, + "range_ids": ["frames"] } }, - "relationships": { + "_exmpl_time": null, + "_exmpl_time_meta":{ + "range": { + "serialization_format": "linear", + "offset_linear": [0], + "step_size_linear": [1.5], + "range_ids": ["frames"] + } + }, + "_exmpl_ekin": null + "_exmpl_ekin_meta":{ + "range": { + "serialization_format" : "regular", + "nindexable_dim": 1,` + "dim_size": [180], + "nvalues": 180, + "step_size_regular" : 2, + "offset_regular": 1, + "range_ids": ["frames"] + } + } + }, + "relationships": { "references": { "data": [ { @@ -3174,7 +3037,7 @@ This is an example of the data field of a JSON object that could be returned aft //... } 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, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,_exmpl_temperature_set&first_frame=0` +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions,cartesian_site_positions_meta,_exmpl_time,_exmpl_ekin,_exmpl_temperature_set&property_ranges=cartesian_site_positions` .. code:: jsonc @@ -3184,9 +3047,7 @@ Upon having performed the above query, the following query can be performed to r "type": "trajectories", "attributes":{ "last_modified":"2021-07-16T18:02:03Z", - "cartesian_site_positions":{ - "frame_serialization_format": "explicit", - "values":[ + "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]], @@ -3198,64 +3059,69 @@ Upon having performed the above query, the following query can be performed to r [[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]] + //... ] + "cartesian_site_positions_meta":{ + "range": { + "serialization_format" : "regular", + "nindexable_dim": 3,` + "dim_size": [360, 3, 3], + "nvalues": 3240, + "step_size_regular" : 1, + "offset_regular": 1, + "range_ids": ["frames", "particles", "xyz"], + "nreturned_values": 900, + "returned_range": [[1,200,1],[1,3,1],[1,3,1]], + "more_data_available": true, + "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions,cartesian_site_positions_meta&property_ranges=cartesian_site_positions[[201,900,1],[1,3,1],[1,3,1]]" + } }, - "lattice_vectors":{ - "frame_serialization_format": "constant", - "values":[[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,0.0,4.0]]] - }, - "dimension_types":{ - "frame_serialization_format": "constant", - "values":[[0,0,0]] - }, - "_exmpl_time":{ - "frame_serialization_format": "linear", - "offset_linear": 0, - "step_size_linear": 1.5 - }, - "_exmpl_ekin":{ - "frame_serialization_format": "explicit_regular_sparse", - "step_size_sparse": 2, - "values":[4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21] - }, - "species":{ - "frame_serialization_format": "constant", - "values":[[ - { - "name":"O1", - "chemical_symbols":["O"], - "concentration":[1.0] - },{ - "name":"H1", - "chemical_symbols":["H"], - "concentration":[1.0] - },{ - "name":"H2", - "chemical_symbols":["H"], - "concentration":[1.0] - } - ]] + "_exmpl_temperature_set": [293.0,293.1,293.2,293.3,293.4,293.5 + //... + ], + "_exmpl_temperature_set_meta":{ + "range":{ + "serialization_format": "custom", + "nindexable_dim": 1,` + "dim_size": [360], + "nvalues": 144, + "range_ids": ["frames"] + "indexes": [1,3,6,8,11,13,16,18,21,23,26,28,31,33,36,38,41 + //... + ], + "nreturned_values": 144, + "more_data_available": false, + "next": null + } }, - "species_at_sites":{ - "frame_serialization_format": "constant", - "values":[["O1","H1","H2"]] + "_exmpl_time": null, + "_exmpl_time_meta":{ + "range": { + "serialization_format": "linear", + "offset_linear": [0], + "step_size_linear": [1.5], + "range_ids": ["frames"] + } }, - "_exmpl_temperature_set":{ - "frame_serialization_format": "explicit_custom_sparse", - "sparse_frames":[0,4,5,9], - "values":[273,273,293,293] + "_exmpl_ekin": [4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21 + //... + ], + "_exmpl_ekin_meta":{ + "range": { + "serialization_format" : "regular", + "nindexable_dim": 1,` + "dim_size": [180], + "nvalues": 180, + "step_size_regular" : 2, + "offset_regular": 1, + "range_ids": ["frames"], + "returned_range": [[1,360,2]], + "more_data_available": false, + "next": null + } } } }, - "links":{ - "next":"http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, lattice_vectors,dimension_types,_exmpl_time,_exmpl_ekin,species,species_at_sites,relationships&first_frame=10", - "base_url": { - "href": "http://example.com/optimade", - "meta": { - "_exmpl_db_version": "3.2.1" - } - } - } //... } From 68b074e330a1d9a15b467c94c1ec2c997a02ce0d Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 2 Jun 2023 12:05:00 +0200 Subject: [PATCH 46/57] Updated examples for the changes in the metadata and ranged properties proposals. --- optimade.rst | 249 +++++++++++++++++++++++++++++---------------------- 1 file changed, 144 insertions(+), 105 deletions(-) diff --git a/optimade.rst b/optimade.rst index cd9405471..c6adf99b3 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2873,15 +2873,16 @@ Trajectories Entries Furthermore, :entry:`trajectories` can optionally have relationships and database specific fields as well as "ranged" properties that contain the values of that property for the frames of the trajectory. In addition they can have 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. - The dimension that corresponds to the steps of the trajectory MUST be have the :field:`range_id`=:val:`frames`. + 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 index of a frame that, according the server, would be a good example of the structures in the trajectory. -- **Type**: integer -- **Requirements/Conventions**: The value MUST be larger than 0 and equal or less than nframes. +- **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. @@ -2889,7 +2890,7 @@ reference_frame - **Examples**: - - :val:`42` + - :val:`[0, 397, 1000]` nframes ~~~~~~~ @@ -2940,18 +2941,7 @@ This is an example of the data field of a JSON object that could be returned aft "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" : None, - "cartesian_site_positions_meta" : { - "range": { - "serialization_format" : "regular", - "nindexable_dim": 3,` - "dim_size": [360, 3, 3], - "nvalues": 3240, - "step_size_regular" : 1, - "offset_regular": 1, - "range_ids": ["frames", "particles", "xyz"] - } - } + "cartesian_site_positions" : null, "nsites":3, "species_at_sites":["O1","H1","H2"], "species":[ @@ -2973,71 +2963,95 @@ This is an example of the data field of a JSON object that could be returned aft ], "reference_frame": 1, "nframes": 360, - "available_properties":{ - "cartesian_site_positions":{ - "frame_serialization_format": "explicit", - "nvalues":360 - }, - "species":{ - "frame_serialization_format": "constant" - }, - "dimension_types":{ - "frame_serialization_format": "constant" - }, - "lattice_vectors":{ - "frame_serialization_format": "constant" - }, - "species_at_sites":{ - "frame_serialization_format": "constant" - }, "_exmpl_temperature_set": null, - "_exmpl_temperature_set_meta":{ + "_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": { - "serialization_format": "custom", - "nindexable_dim": 1,` - "dim_size": [360], - "nvalues": 144, - "range_ids": ["frames"] + "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_time": null, - "_exmpl_time_meta":{ + "_exmpl_temperature_set":{ "range": { - "serialization_format": "linear", - "offset_linear": [0], - "step_size_linear": [1.5], - "range_ids": ["frames"] + "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": null - "_exmpl_ekin_meta":{ + "_exmpl_ekin":{ "range": { - "serialization_format" : "regular", - "nindexable_dim": 1,` - "dim_size": [180], + "dim_size": [360], "nvalues": 180, - "step_size_regular" : 2, - "offset_regular": 1, - "range_ids": ["frames"] + "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" - } - ] - } + "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,cartesian_site_positions_meta,_exmpl_time,_exmpl_ekin,_exmpl_temperature_set&property_ranges=cartesian_site_positions` +:query-url:`http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions,_exmpl_ekin,_exmpl_temperature_set&property_ranges=` .. code:: jsonc @@ -3060,68 +3074,93 @@ Upon having performed the above query, the following query can be performed to r [[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]] //... - ] - "cartesian_site_positions_meta":{ + ], + "_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": { - "serialization_format" : "regular", - "nindexable_dim": 3,` "dim_size": [360, 3, 3], "nvalues": 3240, - "step_size_regular" : 1, - "offset_regular": 1, "range_ids": ["frames", "particles", "xyz"], - "nreturned_values": 900, - "returned_range": [[1,200,1],[1,3,1],[1,3,1]], + "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, - "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions,cartesian_site_positions_meta&property_ranges=cartesian_site_positions[[201,900,1],[1,3,1],[1,3,1]]" + "nreturned_values": 900, + "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions&property_ranges=frames(101,360,1)" } }, - "_exmpl_temperature_set": [293.0,293.1,293.2,293.3,293.4,293.5 - //... - ], - "_exmpl_temperature_set_meta":{ + "_exmpl_temperature_set":{ "range":{ - "serialization_format": "custom", - "nindexable_dim": 1,` "dim_size": [360], "nvalues": 144, - "range_ids": ["frames"] + "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": 144, - "more_data_available": false, - "next": null - } - }, - "_exmpl_time": null, - "_exmpl_time_meta":{ - "range": { - "serialization_format": "linear", - "offset_linear": [0], - "step_size_linear": [1.5], - "range_ids": ["frames"] + "nreturned_values": 40, + "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": [4.1100E-21,4.1102E-21,4.1101E-21,4.1102E-21,4.1099E-21 - //... - ], - "_exmpl_ekin_meta":{ + "_exmpl_ekin":{ "range": { - "serialization_format" : "regular", - "nindexable_dim": 1,` - "dim_size": [180], + "dim_size": [360], "nvalues": 180, - "step_size_regular" : 2, - "offset_regular": 1, "range_ids": ["frames"], - "returned_range": [[1,360,2]], - "more_data_available": false, - "next": null + "indexable_dim": ["frames"], + "data_range": [ + { + "name": "frames", + "start": 1, + "stop": 360, + "step": 2 + } + ], + "contains_null": false, + "nreturned_values": 50, + "returned_range": [[1,99,2]], + "more_data_available": true, + "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=_exmpl_ekin&property_ranges=frames(101,360,1)" } } } - }, + } //... } From b5a72e752319675187ea58f643361e7c3e6f9215 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 2 Jun 2023 16:06:56 +0200 Subject: [PATCH 47/57] Added returned_range_field to example. --- optimade.rst | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index c6adf99b3..7ab564c7b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3112,6 +3112,22 @@ Upon having performed the above query, the following query can be performed to r "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)" } }, @@ -3134,6 +3150,14 @@ Upon having performed the above query, the following query can be performed to r //... ], "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) } @@ -3154,7 +3178,14 @@ Upon having performed the above query, the following query can be performed to r ], "contains_null": false, "nreturned_values": 50, - "returned_range": [[1,99,2]], + "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)" } From 3a0b503fb358b8aeb5e3c7c4e25dff85c158bcca Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 2 Jun 2023 18:00:18 +0200 Subject: [PATCH 48/57] some small changes. --- optimade.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/optimade.rst b/optimade.rst index 7ab564c7b..971b9d699 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2870,17 +2870,15 @@ Trajectories Entries 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 and database specific fields as well as "ranged" properties that contain the values of that property for the frames of the trajectory. - In addition they can have 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. + 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. + 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. @@ -2895,8 +2893,8 @@ reference_frame nframes ~~~~~~~ -- **Description**: The number of the frames in the trajectory as exposed by the API. - This value may deviate from the number steps used to calculate the trajectory. +- **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**: From 399c6d7fdea9a380bd97ce47ce2805560062e03f Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 2 Jun 2023 18:54:00 +0200 Subject: [PATCH 49/57] corrected indexes field in example. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 971b9d699..1cc38691c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3144,7 +3144,7 @@ Upon having performed the above query, the following query can be performed to r } ], "contains_null": false, - "indexes": [1,3,6,8,11,13,16,18,21,23,26,28,31,33,36,38,41 + "indexes": [[1],[3],[6],[8],[11],[13],[16],[18],[21],[23],[26],[28],[31],[33],[36],[38],[41] //... ], "nreturned_values": 40, From 75a97ba309e43c66094b47ccfc71327030146c43 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Jun 2023 18:59:11 +0200 Subject: [PATCH 50/57] Apply suggestions from code review Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 86d240491..e8c32e8d0 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3078,7 +3078,7 @@ Trajectories Entries 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. + 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"`. From 5cd0f98e8b910b2eab300084ed16c9aee9ab6450 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 29 Jun 2023 19:19:51 +0200 Subject: [PATCH 51/57] intermediate state updating trajectory proposal for new developments. --- optimade.rst | 52 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/optimade.rst b/optimade.rst index e8c32e8d0..37aa1ee39 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3079,25 +3079,9 @@ Trajectories Entries 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. + If one of these properties does not have a constant value it should be shared via the partial data method, as described in section ` Transmission of large property values`_. 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 ~~~~~~~ @@ -3123,6 +3107,22 @@ nframes - :val:`42` +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 or equal to 0 and e 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]` + Examples of a returned trajectory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3173,7 +3173,23 @@ This is an example of the data field of a JSON object that could be returned aft "_exmpl_ekin": null }, "meta":{ - "more_data_available": true, + "property_metadata":{ + "cartesian_site_positions":{ + "range":{ + "range_ids":["frames","particles"], + "indexable_dim": ["frames"], + "data_range": [{ + "start": 1, + "step": 1, + "stop": 200, + },{ + "start": 1, + "step": 1, + "stop": 3, + }], + "layout":"dense", + "nvalues": 600 + } "next": "http://example.com/optimade/v1/trajectories/traj00000001?response_fields=cartesian_site_positions, _exmpl_temperature_set, _exmpl_ekin&property_ranges=", "cartesian_site_positions" : { "range": { From 92d0300c7f368984b703740b1f1b83f2ba2e0a44 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 30 Jun 2023 12:05:37 +0200 Subject: [PATCH 52/57] Updated example. --- optimade.rst | 311 +++++++++++++-------------------------------------- 1 file changed, 79 insertions(+), 232 deletions(-) diff --git a/optimade.rst b/optimade.rst index 37aa1ee39..cfddc5cfd 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3078,8 +3078,10 @@ Trajectories Entries 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 via the partial data method, as described in section ` Transmission of large property values`_. + Furthermore, :entry:`trajectories` can optionally have relationships and database-specific fields. + The properties defined for the structures endpoint can also be used for trajectories. + In this case the values of these properties are however lists of whatever type has been defined for the original structures property. + This allows these properties to change during the trajectory. The dimension that corresponds to the steps of the trajectory MUST have :field:`range_id` = :val:`"frames"`. nframes @@ -3110,7 +3112,7 @@ nframes reference_frame ~~~~~~~~~~~~~~~ -- **Description**: The indexes of a set of frames that give a good but brief overview of the trajectory. +- **Description**: The indexes of a set of frames that give a good but very 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 or equal to 0 and e less than nframes. @@ -3138,19 +3140,19 @@ This is an example of the data field of a JSON object that could be returned aft "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]], + "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":[ + "nsites":[3], + "species_at_sites":[["O1","H1","H2"]], + "species":[[ { "name":"O1", "chemical_symbols":["O"], @@ -3166,97 +3168,86 @@ This is an example of the data field of a JSON object that could be returned aft "chemical_symbols":["H"], "concentration":[1.0] } - ], - "reference_frame": 1, - "nframes": 360, - "_exmpl_temperature_set": null, + ]], + "reference_frame": [1], + "nframes": [360], + "_exmpl_temperature": null, "_exmpl_ekin": null }, "meta":{ "property_metadata":{ "cartesian_site_positions":{ "range":{ - "range_ids":["frames","particles"], + "range_ids":["frames","particles","xyz"], "indexable_dim": ["frames"], "data_range": [{ "start": 1, "step": 1, - "stop": 200, + "stop": 360, },{ "start": 1, "step": 1, "stop": 3, + },{ + "start": 1, + "step": 1, + "stop": 3, }], "layout":"dense", - "nvalues": 600 - } - "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 + "nvalues": 3240 + }, + "_exmpl_temperature":{ + "range": { + "range_ids":["frames"], + "nvalues": 144, + "indexable_dim": ["frames"], + "data_range": [ + { + "start": 1, + "stop": 360, + "step": null + } + ], + "layout": "sparse" + }, + "_exmpl_ekin":{ + "range": { + "nvalues": 180, + "range_ids": ["frames"], + "indexable_dim": ["frames"], + "data_range": [ + { + "start": 1, + "stop": 360, + "step": 2 + } + ], + "layout":"dense", + } } }, - "_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 - } + "partial_data_links": { + "cartesian_site_positions": [ + { + "format": "jsonlines", + "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/cartesian_site_positions/jsonlines" + },{ + "format": "_exmpl_xyz", + "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/cartesian_site_positions/xyz" + }, + ], + "_exmpl_temperature": [ + { + "format": "jsonlines", + "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/temperature/jsonlines" + }, + ], + "_exmpl_ekin": [ + { + "format": "jsonlines", + "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/ekin/jsonlines" + }, + ] } }, "relationships": { @@ -3272,150 +3263,6 @@ This is an example of the data field of a JSON object that could be returned aft } //... } -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 -------------------- From bea17d9761bd3c9fc9865eebc32e4e8c81a58809 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 4 Jul 2023 17:19:24 +0200 Subject: [PATCH 53/57] Small corrections --- optimade.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index cfddc5cfd..e763f30b1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3072,10 +3072,9 @@ structure\_features 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. +- **Description**: The :entry:`trajectories` entry is used to share data belonging to sequences of structures, for example, from molecular dynamics or Monte Carlo simulations. 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 and database-specific fields. @@ -3115,7 +3114,7 @@ reference_frame - **Description**: The indexes of a set of frames that give a good but very 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 or equal to 0 and e less than nframes. +- **Requirements/Conventions**: The values MUST be larger than or equal to 0 and less than nframes. - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. From b351d46414e0fde485f0013a37eed9586bd95e15 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Thu, 6 Jul 2023 13:05:43 +0200 Subject: [PATCH 54/57] Apated PR for moving range_ids to property definitions. --- optimade.rst | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/optimade.rst b/optimade.rst index e763f30b1..fdcd97a49 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3081,7 +3081,7 @@ Trajectories Entries The properties defined for the structures endpoint can also be used for trajectories. In this case the values of these properties are however lists of whatever type has been defined for the original structures property. This allows these properties to change during the trajectory. - The dimension that corresponds to the steps of the trajectory MUST have :field:`range_id` = :val:`"frames"`. + The dimension that corresponds to the steps of the trajectory MUST have :field:`range_id` = :val:`"frames"` for that dimension in its property definition, See `Property Definition keys from JSON Schema`_. nframes ~~~~~~~ @@ -3176,28 +3176,27 @@ This is an example of the data field of a JSON object that could be returned aft "meta":{ "property_metadata":{ "cartesian_site_positions":{ - "range":{ - "range_ids":["frames","particles","xyz"], - "indexable_dim": ["frames"], - "data_range": [{ - "start": 1, - "step": 1, - "stop": 360, - },{ - "start": 1, - "step": 1, - "stop": 3, - },{ - "start": 1, - "step": 1, - "stop": 3, - }], - "layout":"dense", - "nvalues": 3240 - }, + "range":{ + "indexable_dim": ["frames"], + "data_range": [{ + "start": 1, + "step": 1, + "stop": 360, + },{ + "start": 1, + "step": 1, + "stop": 3, + },{ + "start": 1, + "step": 1, + "stop": 3, + }], + "layout":"dense", + "nvalues": 3240 + }, + }, "_exmpl_temperature":{ "range": { - "range_ids":["frames"], "nvalues": 144, "indexable_dim": ["frames"], "data_range": [ @@ -3208,11 +3207,11 @@ This is an example of the data field of a JSON object that could be returned aft } ], "layout": "sparse" + } }, "_exmpl_ekin":{ "range": { "nvalues": 180, - "range_ids": ["frames"], "indexable_dim": ["frames"], "data_range": [ { From af2675722a781972789b8d4eb79697f7c9e39bef Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 13 Sep 2023 17:22:22 +0200 Subject: [PATCH 55/57] Changed reference_frame to reference_frames as it is now a list which can contain multiple values. --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index fdcd97a49..22bb00c4c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3076,7 +3076,7 @@ Trajectories Entries 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`_. + :entry:`trajectories` entries have the properties described in the section `Properties Used by Multiple Entry Types`_ as well as the property `nframes`_ and `reference_frames`_. Furthermore, :entry:`trajectories` can optionally have relationships and database-specific fields. The properties defined for the structures endpoint can also be used for trajectories. In this case the values of these properties are however lists of whatever type has been defined for the original structures property. @@ -3108,7 +3108,7 @@ nframes - :val:`42` -reference_frame +reference_frames ~~~~~~~~~~~~~~~ - **Description**: The indexes of a set of frames that give a good but very brief overview of the trajectory. @@ -3168,7 +3168,7 @@ This is an example of the data field of a JSON object that could be returned aft "concentration":[1.0] } ]], - "reference_frame": [1], + "reference_frames": [1], "nframes": [360], "_exmpl_temperature": null, "_exmpl_ekin": null From 2023e7f5db083395d55280e477ab91d38059b4fc Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Thu, 18 Jan 2024 09:08:07 +0200 Subject: [PATCH 56/57] Update optimade.rst Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 22bb00c4c..2f1c335c3 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3109,7 +3109,7 @@ nframes - :val:`42` reference_frames -~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ - **Description**: The indexes of a set of frames that give a good but very 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. From 68648d05093e1c874b7e1635473bf0840882adbc Mon Sep 17 00:00:00 2001 From: Giovanni Pizzi Date: Thu, 4 Jul 2024 09:27:33 +0200 Subject: [PATCH 57/57] Update optimade.rst Co-authored-by: Antanas Vaitkus --- optimade.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/optimade.rst b/optimade.rst index 2f1c335c3..14b29d15c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3181,19 +3181,19 @@ This is an example of the data field of a JSON object that could be returned aft "data_range": [{ "start": 1, "step": 1, - "stop": 360, + "stop": 360 },{ "start": 1, "step": 1, - "stop": 3, + "stop": 3 },{ "start": 1, "step": 1, - "stop": 3, + "stop": 3 }], "layout":"dense", "nvalues": 3240 - }, + } }, "_exmpl_temperature":{ "range": { @@ -3220,7 +3220,7 @@ This is an example of the data field of a JSON object that could be returned aft "step": 2 } ], - "layout":"dense", + "layout":"dense" } } }, @@ -3232,19 +3232,19 @@ This is an example of the data field of a JSON object that could be returned aft },{ "format": "_exmpl_xyz", "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/cartesian_site_positions/xyz" - }, + } ], "_exmpl_temperature": [ { "format": "jsonlines", "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/temperature/jsonlines" - }, + } ], "_exmpl_ekin": [ { "format": "jsonlines", "link": "https://example.org/optimade/v1.2/extensions/partial_data/trajectories/traj00000001/ekin/jsonlines" - }, + } ] } },