From 716ad2e7c902217b842a792f6c8f92ff4983795d 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] Multiple small corrections for the trajectories entry --- optimade.rst | 110 ++++++++++++++++++++++++--------------------------- 1 file changed, 52 insertions(+), 58 deletions(-) diff --git a/optimade.rst b/optimade.rst index c82d8c1fc..f8dd95da7 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,20 @@ 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 +2356,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 +2365,11 @@ 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`. - - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. + - **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. - **Examples**: + - :val:`42` nframes @@ -2376,20 +2378,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,95 +2398,87 @@ 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",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. - **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 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 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. - **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 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. - **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 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 name. 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 the structures endpoint 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. - **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**: @@ -2528,7 +2520,7 @@ The data is returned in a data major format. i.e. the properties form the highes - **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]` @@ -2537,7 +2529,7 @@ The data is returned in a data major format. i.e. the properties form the highes - **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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2546,6 +2538,7 @@ This is an example of a JSON object that could be returned after the following q :query-url:`http://example.com/optimade/v1/trajectories/traj00000001` .. code:: jsonc + { "reference_structure":{ "elements": ["H","O"], @@ -2604,9 +2597,10 @@ 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&frame_step=5` .. code:: jsonc + { "id": "traj00000001", "type": "trajectories", @@ -2671,7 +2665,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=30&frame_step=5" } Calculations Entries