From 36650142ff591c6d6c1116dea5ba7429be2e4fda Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Fri, 17 Feb 2023 18:58:37 +0100 Subject: [PATCH 01/33] Add structure_origin to structures endpoint --- optimade.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/optimade.rst b/optimade.rst index 8c9d5562c..45e019443 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2846,6 +2846,42 @@ structure\_features - A structure having implicit atoms and using assemblies: :val:`["assemblies", "implicit_atoms"]` +structure\_origin +~~~~~~~~~~~~~~~~~ + +- **Description**: A string that describes key aspects of the origin of the structural information. +- **Type**: string +- **Requirements/Conventions**: + + - **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 take one of the following values: + + * :val:`experimental`: specifies that all the structural information (coordinates, elements, assemblies, etc.) is a direct and unmodified representation of the outcome of an experimental technique for structure determination. + + * :val:`processed`: specifies that the structural information originates from experimental data, but has been further processed in such a way that the resulting structure still is recognizable as the experimental one it was based on. + For example, structures that have undergone relaxation using ab-inito calculations with the experimental structure as the starting point are meant to be placed in this category. + Structures that have substituted one or more elements (but otherwise kept the experimental coordinates the same) are not meant to be in this category. + Ultimately there is a level of subjectivity in this definition which is to be decided by the database provider. + + * :val:`predicted`: the structural information has no direct connection to the outcome of an experimental technique on an existing material, but has undergone theoretical processing that motivates the database provider to suggest it as a candidate for a synthesizable structure. + This category is intended for, e.g., theoretically invented structures relaxed using ab-inito calculations and found to end up close to the convex hull of stability, or structures generated out of an AI model demonstrated to have a reasonable predictive power. + This category definition has a rather high level of subjectivity which has to be decided by the database provider. + + * :val:`hypothetical`: the structure comes with no guarantee of having any relationship to synthesizable structures or structures that can be found in nature. + This category is encouraged for, e.g., randomly placed atoms used as a starting point for further processing or the outcomes of AI models for which the predictive power is not deemed sufficient for `predicted`. + + * :val:`unknown`: specifies that the database provider does not have any information it can provide in relation to this aspect of the origin of the structural information. + + - If the field is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. + + - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure` MAY be used but are strongly discouraged. + +- **Examples**: + + - For a structure created directly out from experimental values: :val:`"experimental"`. + Calculations Entries -------------------- From a7b73168568d16f812ba06131f7c4e143aa658b3 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Feb 2023 09:45:47 +0100 Subject: [PATCH 02/33] Improved formulations for structure_origin --- optimade.rst | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/optimade.rst b/optimade.rst index 45e019443..396c9e4aa 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2849,7 +2849,8 @@ structure\_features structure\_origin ~~~~~~~~~~~~~~~~~ -- **Description**: A string that describes key aspects of the origin of the structural information. +- **Description**: A string that describes aspects of the origin of the structural data to indicate if is based directly or indirectly on experimental evidence or inferred from other sources, giving some information on whether the structure is believed to exist in nature or can be synthesized as a compound stable at non-extreme conditions. + - **Type**: string - **Requirements/Conventions**: @@ -2858,29 +2859,32 @@ structure\_origin If supported, filters MAY support only a subset of comparison operators. - SHOULD take one of the following values: - * :val:`experimental`: specifies that all the structural information (coordinates, elements, assemblies, etc.) is a direct and unmodified representation of the outcome of an experimental technique for structure determination. + * :val:`experimental`: the structural information is based directly on the outcome of an experimental technique for structure determination which is represented without further processing. + + * :val:`processed`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. + For example, experimental structures relaxed using ab-inito calculations are meant to be qualify for this category. + Substituting one or more elements in a structure (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. + The category definition involves a degree of subjectivity that has to be decided by the database provider. + + * :val:`predicted`: the structural information is not directly related to the outcome of an experimental technique on an existing material, but has undergone theoretical processing to suggest it as a candidate for a synthesizable structure. This category includes theoretically invented structures that have been relaxed using ab-inito calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. This category definition also involves a degree of subjectivity that has to be determined by the database provider. - * :val:`processed`: specifies that the structural information originates from experimental data, but has been further processed in such a way that the resulting structure still is recognizable as the experimental one it was based on. - For example, structures that have undergone relaxation using ab-inito calculations with the experimental structure as the starting point are meant to be placed in this category. - Structures that have substituted one or more elements (but otherwise kept the experimental coordinates the same) are not meant to be in this category. - Ultimately there is a level of subjectivity in this definition which is to be decided by the database provider. + * :val:`hypothetical`: the structural information is known to not have been created in a way that provides no guarantees of producing synthesizable structures or structures found in nature. This category is suitable for randomly placed atoms (e.g., meant to provide a starting point for further processing) or outcomes of AI models with predictive power deemed insufficient for the :val:`predicted` category. - * :val:`predicted`: the structural information has no direct connection to the outcome of an experimental technique on an existing material, but has undergone theoretical processing that motivates the database provider to suggest it as a candidate for a synthesizable structure. - This category is intended for, e.g., theoretically invented structures relaxed using ab-inito calculations and found to end up close to the convex hull of stability, or structures generated out of an AI model demonstrated to have a reasonable predictive power. - This category definition has a rather high level of subjectivity which has to be decided by the database provider. + * :val:`other`: the origin of the structural information is not correctly described by any of the other categories. - * :val:`hypothetical`: the structure comes with no guarantee of having any relationship to synthesizable structures or structures that can be found in nature. - This category is encouraged for, e.g., randomly placed atoms used as a starting point for further processing or the outcomes of AI models for which the predictive power is not deemed sufficient for `predicted`. + * :val:`unknown`: no information is available regarding these aspects of the origin of the structural information. - * :val:`unknown`: specifies that the database provider does not have any information it can provide in relation to this aspect of the origin of the structural information. + The experiments and predictions referred to in the above definitions of the categories refer to existence at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. + Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions should categorize them as :val:`other` and, if desired, use another facility (e.g., a provider-specific field) to communicate more specific information. - If the field is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. - - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure` MAY be used but are strongly discouraged. + - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure` MAY be used but are strongly discouraged. + Clients encountering unrecognized strings SHOULD treat them to mean the same as :val:`unknown`. - **Examples**: - - For a structure created directly out from experimental values: :val:`"experimental"`. + - For a structure entry directly encoding structural information obtained from a neutron diffraction experiment: :val:`"experimental"`. Calculations Entries -------------------- From a8d77cf8b2d022983e6f41df70d40a994fcb5302 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Feb 2023 10:09:28 +0100 Subject: [PATCH 03/33] Adjust terminology to use property rather than field --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 396c9e4aa..bc819ef23 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2875,9 +2875,9 @@ structure\_origin * :val:`unknown`: no information is available regarding these aspects of the origin of the structural information. The experiments and predictions referred to in the above definitions of the categories refer to existence at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. - Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions should categorize them as :val:`other` and, if desired, use another facility (e.g., a provider-specific field) to communicate more specific information. + Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions should categorize them as :val:`other` and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. - - If the field is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. + - If the property is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure` MAY be used but are strongly discouraged. Clients encountering unrecognized strings SHOULD treat them to mean the same as :val:`unknown`. From 8aedb8b3e4ba88dce6726bb64060b3c1285b6c13 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Feb 2023 13:39:51 +0100 Subject: [PATCH 04/33] Apply suggestions from code review Co-authored-by: Antanas Vaitkus --- optimade.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index bc819ef23..29f837487 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2862,13 +2862,16 @@ structure\_origin * :val:`experimental`: the structural information is based directly on the outcome of an experimental technique for structure determination which is represented without further processing. * :val:`processed`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. - For example, experimental structures relaxed using ab-inito calculations are meant to be qualify for this category. + For example, experimental structures relaxed using ab-initio calculations are meant to qualify for this category. Substituting one or more elements in a structure (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. - * :val:`predicted`: the structural information is not directly related to the outcome of an experimental technique on an existing material, but has undergone theoretical processing to suggest it as a candidate for a synthesizable structure. This category includes theoretically invented structures that have been relaxed using ab-inito calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. This category definition also involves a degree of subjectivity that has to be determined by the database provider. + * :val:`predicted`: the structural information is not directly related to the outcome of an experimental technique on an existing material, but has undergone theoretical processing to suggest it as a candidate for a synthesizable structure. + This category includes theoretically invented structures that have been relaxed using ab-initio calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. + This category definition also involves a degree of subjectivity that has to be determined by the database provider. - * :val:`hypothetical`: the structural information is known to not have been created in a way that provides no guarantees of producing synthesizable structures or structures found in nature. This category is suitable for randomly placed atoms (e.g., meant to provide a starting point for further processing) or outcomes of AI models with predictive power deemed insufficient for the :val:`predicted` category. + * :val:`hypothetical`: the structural information is known to have been created in a way that provides no guarantees of producing synthesizable structures or structures found in nature. + This category is suitable for randomly placed atoms (e.g., meant to provide a starting point for further processing) or outcomes of AI models with predictive power deemed insufficient for the :val:`predicted` category. * :val:`other`: the origin of the structural information is not correctly described by any of the other categories. @@ -2879,7 +2882,7 @@ structure\_origin - If the property is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. - - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure` MAY be used but are strongly discouraged. + - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. Clients encountering unrecognized strings SHOULD treat them to mean the same as :val:`unknown`. - **Examples**: From 14c28259e556edee9f6eb72b081481f9dd28c7d4 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Tue, 21 Feb 2023 23:46:05 +0100 Subject: [PATCH 05/33] Suggestions from review Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/optimade.rst b/optimade.rst index 29f837487..a7a14ec78 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2849,25 +2849,24 @@ structure\_features structure\_origin ~~~~~~~~~~~~~~~~~ -- **Description**: A string that describes aspects of the origin of the structural data to indicate if is based directly or indirectly on experimental evidence or inferred from other sources, giving some information on whether the structure is believed to exist in nature or can be synthesized as a compound stable at non-extreme conditions. +- **Description**: A string that describes aspects of the origin of the structural data to indicate if it is based directly or indirectly on experimental evidence, or inferred from other sources, giving some information on whether the structure is believed to exist in nature or can be synthesized as a compound stable at non-extreme conditions. - **Type**: string - **Requirements/Conventions**: - **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. + - **Query**: MUST be a queryable property with support for all mandatory filter features. - SHOULD take one of the following values: - * :val:`experimental`: the structural information is based directly on the outcome of an experimental technique for structure determination which is represented without further processing. + * :val:`experimental`: the structural information is a faithful representation of the outcome of an experimental technique for structure determination. * :val:`processed`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. - For example, experimental structures relaxed using ab-initio calculations are meant to qualify for this category. + For example, experimental structures relaxed using *ab initio* calculations are meant to qualify for this category. Substituting one or more elements in a structure (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. - * :val:`predicted`: the structural information is not directly related to the outcome of an experimental technique on an existing material, but has undergone theoretical processing to suggest it as a candidate for a synthesizable structure. - This category includes theoretically invented structures that have been relaxed using ab-initio calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. + * :val:`predicted`: the structural information is not directly related to the outcome of an experimental technique on an existing material, but has undergone theoretical processing to suggest it as a candidate for a potentially synthesizable structure. + This category includes theoretically invented structures that have been relaxed using *ab initio* calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. This category definition also involves a degree of subjectivity that has to be determined by the database provider. * :val:`hypothetical`: the structural information is known to have been created in a way that provides no guarantees of producing synthesizable structures or structures found in nature. From 529a65cb96e852450cd4b8917b467aea6f0453f2 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Feb 2023 16:11:35 +0100 Subject: [PATCH 06/33] Apply suggestions from review Co-authored-by: Antanas Vaitkus Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index a7a14ec78..5d08104d7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2865,14 +2865,16 @@ structure\_origin Substituting one or more elements in a structure (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. - * :val:`predicted`: the structural information is not directly related to the outcome of an experimental technique on an existing material, but has undergone theoretical processing to suggest it as a candidate for a potentially synthesizable structure. + * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but has undergone theoretical processing to suggest it as a candidate for a potentially synthesizable structure. This category includes theoretically invented structures that have been relaxed using *ab initio* calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. This category definition also involves a degree of subjectivity that has to be determined by the database provider. * :val:`hypothetical`: the structural information is known to have been created in a way that provides no guarantees of producing synthesizable structures or structures found in nature. - This category is suitable for randomly placed atoms (e.g., meant to provide a starting point for further processing) or outcomes of AI models with predictive power deemed insufficient for the :val:`predicted` category. + This category is suitable for configurations that have been deemed by calculation or AI predictions to be thermodynamically unstable (e.g., predicted to decompose into other competing phases) or structures that are the outcome of AI models with predictive power deemed insufficient for the :val:`predicted` category. + Such structures should still be the result of a local optimization (either directly or inferred by an AI model). * :val:`other`: the origin of the structural information is not correctly described by any of the other categories. + This could cover the case of structures that have not been locally optimized, e.g., a non-equilibrium snapshot, or any other arbitrary configuration of atoms in <=3D space. * :val:`unknown`: no information is available regarding these aspects of the origin of the structural information. From da4c43a4c8d1555da433ab1cdbe993efd9075378 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Feb 2023 17:45:14 +0100 Subject: [PATCH 07/33] Edited categories and formulations for structure_orgin based on review feedback --- optimade.rst | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/optimade.rst b/optimade.rst index 5d08104d7..bce3da206 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2856,30 +2856,38 @@ structure\_origin - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. - - SHOULD take one of the following values: + + - If the property is :val:`null` or omitted, no information is provided regarding these aspects of the origin of the structural information. + This value is used if the origin of the structural data is not known, or, if it is partially known but to an insufficient degree to distinguish between the categories defined below. + + - If present and not :val:`null`, the property SHOULD take the first of the following values for which the structural information qualifies: * :val:`experimental`: the structural information is a faithful representation of the outcome of an experimental technique for structure determination. * :val:`processed`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. For example, experimental structures relaxed using *ab initio* calculations are meant to qualify for this category. - Substituting one or more elements in a structure (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. + Structures where one or more elements in a structure have been substituted (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. - * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but has undergone theoretical processing to suggest it as a candidate for a potentially synthesizable structure. - This category includes theoretically invented structures that have been relaxed using *ab initio* calculations and found to be close to the convex hull of stability, or structures generated from AI models with a demonstrated reasonable predictive power. - This category definition also involves a degree of subjectivity that has to be determined by the database provider. + * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure. + For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions (see below) by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. + This category definition involves a degree of subjectivity that has to be determined by the database provider. + The database provider MAY choose not to use theoretical methods to propose structures in the way described here, in which case this category is not used. - * :val:`hypothetical`: the structural information is known to have been created in a way that provides no guarantees of producing synthesizable structures or structures found in nature. - This category is suitable for configurations that have been deemed by calculation or AI predictions to be thermodynamically unstable (e.g., predicted to decompose into other competing phases) or structures that are the outcome of AI models with predictive power deemed insufficient for the :val:`predicted` category. - Such structures should still be the result of a local optimization (either directly or inferred by an AI model). + * :val:`hypothetical`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a local energy minimum on the potential energy surface. + This category accommodates potentially highly thermodynamically unstable structures, e.g., predicted to decompose into other competing phases, even with respect to the elemental solids. + For example, structures relaxed using *ab initio* calculations but not identified to end up close to the convex hull of thermodynamical stability qualify for this category. + AI models which, with a demonstrated reasonable predictive power, can generate structures in local potential energy minimums (e.g., by relaxation via predicted forces, direct generation, etc.) also qualify. + This category definition also involves a degree of subjectivity that has to be determined by the database provider. - * :val:`other`: the origin of the structural information is not correctly described by any of the other categories. - This could cover the case of structures that have not been locally optimized, e.g., a non-equilibrium snapshot, or any other arbitrary configuration of atoms in <=3D space. + * :val:`arbitrary`: the structural information has been created in a way that does not ensure any type of stability, i.e., not even representing a local energy minimum on the potential energy surface. + For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. - * :val:`unknown`: no information is available regarding these aspects of the origin of the structural information. + * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. + For example, this category is suitable for structures that are a faithful representation of the outcome of experiments performed at extreme pressures. The experiments and predictions referred to in the above definitions of the categories refer to existence at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. - Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions should categorize them as :val:`other` and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. + Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions SHOULD use the :val:`other` category, and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. - If the property is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. From 27cde5f9cab793e0635d091e075aec8e74438fa8 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Feb 2023 17:52:38 +0100 Subject: [PATCH 08/33] Remove redundant line about null values in structure_origin --- optimade.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index bce3da206..499a5c381 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2889,8 +2889,6 @@ structure\_origin The experiments and predictions referred to in the above definitions of the categories refer to existence at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions SHOULD use the :val:`other` category, and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. - - If the property is omitted, set to an empty string, or `null` it means the same thing as :val:`unknown`. - - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. Clients encountering unrecognized strings SHOULD treat them to mean the same as :val:`unknown`. From 391629d792b65d02c229c213012d14baf8d31874 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Fri, 17 Mar 2023 19:31:45 +0100 Subject: [PATCH 09/33] Update according to feedback in web meeting; remove constraint on conditions for experimental structures in structure_origins --- optimade.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index a3b919c97..068624205 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2883,8 +2883,9 @@ structure\_origin Structures where one or more elements in a structure have been substituted (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. - * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure. - For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions (see below) by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. + * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. + For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. + Structures that are the outcome of theoretical methods that specifically target conditions far from normal conditions are not meant to qualify for this category. This category definition involves a degree of subjectivity that has to be determined by the database provider. The database provider MAY choose not to use theoretical methods to propose structures in the way described here, in which case this category is not used. @@ -2898,9 +2899,7 @@ structure\_origin For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. - For example, this category is suitable for structures that are a faithful representation of the outcome of experiments performed at extreme pressures. - The experiments and predictions referred to in the above definitions of the categories refer to existence at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions SHOULD use the :val:`other` category, and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. From 4d6d65d068c9b0c3e890fa7a80d3d18142c38091 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Fri, 17 Mar 2023 19:32:38 +0100 Subject: [PATCH 10/33] Update optimade.rst --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 068624205..ace49194b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2903,7 +2903,7 @@ structure\_origin Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions SHOULD use the :val:`other` category, and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. - Clients encountering unrecognized strings SHOULD treat them to mean the same as :val:`unknown`. + Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`null`. - **Examples**: From d7c991846737733c5e5a41ea822bce120f78674c Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Fri, 17 Mar 2023 19:35:08 +0100 Subject: [PATCH 11/33] Replacing processed with derived in structure_origin Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index ace49194b..4c06ff8c8 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2878,7 +2878,7 @@ structure\_origin * :val:`experimental`: the structural information is a faithful representation of the outcome of an experimental technique for structure determination. - * :val:`processed`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. + * :val:`derived`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. For example, experimental structures relaxed using *ab initio* calculations are meant to qualify for this category. Structures where one or more elements in a structure have been substituted (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. From e1c2b43ebbcd17c348d555effa1560a24f57a982 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 09:34:37 +0100 Subject: [PATCH 12/33] Apply suggestions from review Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 4c06ff8c8..f1ce442fc 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2883,7 +2883,7 @@ structure\_origin Structures where one or more elements in a structure have been substituted (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. The category definition involves a degree of subjectivity that has to be decided by the database provider. - * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure at non-extreme conditions (i.e., existence around NTP or at lower temperatures) and in a regular atmosphere. + * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure. For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. Structures that are the outcome of theoretical methods that specifically target conditions far from normal conditions are not meant to qualify for this category. This category definition involves a degree of subjectivity that has to be determined by the database provider. @@ -2908,6 +2908,7 @@ structure\_origin - **Examples**: - For a structure entry directly encoding structural information obtained from a neutron diffraction experiment: :val:`"experimental"`. + - For a structure entry that encodes the structural information from a theoretical relaxation of an "experimental" entry using computational software that implements density functional theory: val`"derived"`. Calculations Entries -------------------- From 55e20d128e631a546cc7a5f1713f5a2d847781ef Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 13:35:09 +0100 Subject: [PATCH 13/33] Attempt at clarifying non-required status of "predicted" --- optimade.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index f1ce442fc..d16358c67 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2887,7 +2887,8 @@ structure\_origin For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. Structures that are the outcome of theoretical methods that specifically target conditions far from normal conditions are not meant to qualify for this category. This category definition involves a degree of subjectivity that has to be determined by the database provider. - The database provider MAY choose not to use theoretical methods to propose structures in the way described here, in which case this category is not used. + It is OPTIONAL for database providers to predict theoretical structures as potentially synthesizable or not. + If this functionality is not provided, any structures that possibly could fit this category are meant to be assigned the next qualifying category below instead. * :val:`hypothetical`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a local energy minimum on the potential energy surface. This category accommodates potentially highly thermodynamically unstable structures, e.g., predicted to decompose into other competing phases, even with respect to the elemental solids. From dc198a47fa77aa15dedd886db835bbedf6eb93f0 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 13:36:42 +0100 Subject: [PATCH 14/33] Slightly adjust wording --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index d16358c67..b211afb3d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2885,7 +2885,7 @@ structure\_origin * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure. For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. - Structures that are the outcome of theoretical methods that specifically target conditions far from normal conditions are not meant to qualify for this category. + Structures that are the outcome of theoretical methods that specifically target conditions far outside normal conditions are not meant to qualify for this category. This category definition involves a degree of subjectivity that has to be determined by the database provider. It is OPTIONAL for database providers to predict theoretical structures as potentially synthesizable or not. If this functionality is not provided, any structures that possibly could fit this category are meant to be assigned the next qualifying category below instead. From 43d979900217ba3d4271d07ea0876aa8c161f6f8 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 13:37:51 +0100 Subject: [PATCH 15/33] Slightly adjust wording --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index b211afb3d..6e0e1b657 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2888,7 +2888,7 @@ structure\_origin Structures that are the outcome of theoretical methods that specifically target conditions far outside normal conditions are not meant to qualify for this category. This category definition involves a degree of subjectivity that has to be determined by the database provider. It is OPTIONAL for database providers to predict theoretical structures as potentially synthesizable or not. - If this functionality is not provided, any structures that possibly could fit this category are meant to be assigned the next qualifying category below instead. + If this functionality is not provided, any structures that could fit this category are meant to be assigned the next qualifying category below instead. * :val:`hypothetical`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a local energy minimum on the potential energy surface. This category accommodates potentially highly thermodynamically unstable structures, e.g., predicted to decompose into other competing phases, even with respect to the elemental solids. From a8857005cd7c240fd5882126f4222d9032ce2e3f Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 13:42:23 +0100 Subject: [PATCH 16/33] Remove "extreme conditions" also in the overview and clarifiy that some distinctions represents intent more than objective observation --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 6e0e1b657..a5a304471 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2863,7 +2863,7 @@ structure\_features structure\_origin ~~~~~~~~~~~~~~~~~ -- **Description**: A string that describes aspects of the origin of the structural data to indicate if it is based directly or indirectly on experimental evidence, or inferred from other sources, giving some information on whether the structure is believed to exist in nature or can be synthesized as a compound stable at non-extreme conditions. +- **Description**: A string that describes aspects of the origin of the structural data to indicate if it is based directly or indirectly on experimental evidence, or inferred from other sources, giving some information on whether the structural data was obtained with the intent of representing a structure that can exist in nature or be synthesized as a stable compound. - **Type**: string - **Requirements/Conventions**: From 69a54f8cb178d52df3eaf07ca311d402746a63d0 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 13:48:18 +0100 Subject: [PATCH 17/33] Remove another reference to extreme conditions --- optimade.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index a5a304471..343a2db5e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2901,8 +2901,6 @@ structure\_origin * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. - Providers who want to communicate structural information about compounds that exist only at unusual or extreme conditions SHOULD use the :val:`other` category, and, if desired, use another facility (e.g., a provider-specific property) to communicate more specific information. - - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`null`. From 6fbb752a8ec1c08d5b51e013a244a927231c1b8b Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 14:16:13 +0100 Subject: [PATCH 18/33] Fix formatting error Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 343a2db5e..5db81b4d9 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2907,7 +2907,7 @@ structure\_origin - **Examples**: - For a structure entry directly encoding structural information obtained from a neutron diffraction experiment: :val:`"experimental"`. - - For a structure entry that encodes the structural information from a theoretical relaxation of an "experimental" entry using computational software that implements density functional theory: val`"derived"`. + - For a structure entry that encodes the structural information from a theoretical relaxation of an "experimental" entry using computational software that implements density functional theory: :val:`"derived"`. Calculations Entries -------------------- From 2ca16b45f6597e4055f467e6ee80084706ef0ae5 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 17:19:46 +0100 Subject: [PATCH 19/33] Apply suggestions from review Co-authored-by: Andrius Merkys --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 5db81b4d9..f08c51d3e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2902,12 +2902,12 @@ structure\_origin * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. - Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`null`. + Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`. - **Examples**: - For a structure entry directly encoding structural information obtained from a neutron diffraction experiment: :val:`"experimental"`. - - For a structure entry that encodes the structural information from a theoretical relaxation of an "experimental" entry using computational software that implements density functional theory: :val:`"derived"`. + - For a structure entry that encodes the structural information from a theoretical relaxation of an :val:`"experimental"` entry using computational software that implements density functional theory: :val:`"derived"`. Calculations Entries -------------------- From cfaceabf2f7c821bbe5dabc0be970058c348b584 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 08:01:33 +0100 Subject: [PATCH 20/33] Remove trailing whitespace Co-authored-by: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index f08c51d3e..43acd4ed7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2887,7 +2887,7 @@ structure\_origin For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. Structures that are the outcome of theoretical methods that specifically target conditions far outside normal conditions are not meant to qualify for this category. This category definition involves a degree of subjectivity that has to be determined by the database provider. - It is OPTIONAL for database providers to predict theoretical structures as potentially synthesizable or not. + It is OPTIONAL for database providers to predict theoretical structures as potentially synthesizable or not. If this functionality is not provided, any structures that could fit this category are meant to be assigned the next qualifying category below instead. * :val:`hypothetical`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a local energy minimum on the potential energy surface. From 94e07a6b1c42ef1b0d165d65ca464c6e9e36457d Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 08:57:00 +0100 Subject: [PATCH 21/33] Add "indeterminate" classification --- optimade.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/optimade.rst b/optimade.rst index 43acd4ed7..57d43a808 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2899,6 +2899,10 @@ structure\_origin * :val:`arbitrary`: the structural information has been created in a way that does not ensure any type of stability, i.e., not even representing a local energy minimum on the potential energy surface. For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. +* :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data in these categories, e.g., because the source of the data provides no such information. + There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or have value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). + The value "indeterminate" communicates that the database provider has intentionally classified the structures into this category, i.e., it states that it is known that the origin is not known, in contrast to the database not providing any data value for classifying the structure. + * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. From 5b96c6e4d731daef0b7fb37c8136f85f4f765f3b Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 08:59:10 +0100 Subject: [PATCH 22/33] Minor grammar fix --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 57d43a808..1632351e7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2900,7 +2900,7 @@ structure\_origin For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. * :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data in these categories, e.g., because the source of the data provides no such information. - There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or have value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). + There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or has value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). The value "indeterminate" communicates that the database provider has intentionally classified the structures into this category, i.e., it states that it is known that the origin is not known, in contrast to the database not providing any data value for classifying the structure. * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. From ef40f6e6fcad721bc1f44d79bd069cb27829b991 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 09:00:21 +0100 Subject: [PATCH 23/33] Minor grammar fix --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 1632351e7..86817f71e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2901,7 +2901,7 @@ structure\_origin * :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data in these categories, e.g., because the source of the data provides no such information. There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or has value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). - The value "indeterminate" communicates that the database provider has intentionally classified the structures into this category, i.e., it states that it is known that the origin is not known, in contrast to the database not providing any data value for classifying the structure. + The value "indeterminate" communicates that the database provider has intentionally classified the structure into this category, i.e., it states that it is known that its origin is not known, in contrast to the database not providing any data value for classifying the structure. * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. From 7fadfc29fee94ced00a73207be8021f48a66e05c Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 09:02:59 +0100 Subject: [PATCH 24/33] Minor grammar fix --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 86817f71e..dee378932 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2899,7 +2899,7 @@ structure\_origin * :val:`arbitrary`: the structural information has been created in a way that does not ensure any type of stability, i.e., not even representing a local energy minimum on the potential energy surface. For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. -* :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data in these categories, e.g., because the source of the data provides no such information. +* :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data into these categories, e.g., because the source of the data provides no such information. There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or has value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). The value "indeterminate" communicates that the database provider has intentionally classified the structure into this category, i.e., it states that it is known that its origin is not known, in contrast to the database not providing any data value for classifying the structure. From 6994d2e1a08ed42dab219cdabcc848f7907d7601 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 13:12:54 +0100 Subject: [PATCH 25/33] Fix formatting Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index dee378932..12f7a11a6 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2899,7 +2899,7 @@ structure\_origin * :val:`arbitrary`: the structural information has been created in a way that does not ensure any type of stability, i.e., not even representing a local energy minimum on the potential energy surface. For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. -* :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data into these categories, e.g., because the source of the data provides no such information. + * :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data into these categories, e.g., because the source of the data provides no such information. There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or has value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). The value "indeterminate" communicates that the database provider has intentionally classified the structure into this category, i.e., it states that it is known that its origin is not known, in contrast to the database not providing any data value for classifying the structure. From 3e0bb6234bbac3dde25fa4d6f8496f5a3a5f6a80 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 22 Mar 2023 16:53:17 +0100 Subject: [PATCH 26/33] Remove incorrect sentence about null-valued structure_origin --- optimade.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 12f7a11a6..4dbdb4125 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2872,7 +2872,6 @@ structure\_origin - **Query**: MUST be a queryable property with support for all mandatory filter features. - If the property is :val:`null` or omitted, no information is provided regarding these aspects of the origin of the structural information. - This value is used if the origin of the structural data is not known, or, if it is partially known but to an insufficient degree to distinguish between the categories defined below. - If present and not :val:`null`, the property SHOULD take the first of the following values for which the structural information qualifies: From bcc44fad7d25db1557e34d6fbb36a79a9d8aea06 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 16:22:02 +0100 Subject: [PATCH 27/33] Complete rewrite based on review feedback --- optimade.rst | 61 ++++++++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 33 deletions(-) diff --git a/optimade.rst b/optimade.rst index 4dbdb4125..0f89d1f0d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2860,57 +2860,52 @@ structure\_features - A structure having implicit atoms and using assemblies: :val:`["assemblies", "implicit_atoms"]` -structure\_origin -~~~~~~~~~~~~~~~~~ +optimization\_type +~~~~~~~~~~~~~~~~~~ -- **Description**: A string that describes aspects of the origin of the structural data to indicate if it is based directly or indirectly on experimental evidence, or inferred from other sources, giving some information on whether the structural data was obtained with the intent of representing a structure that can exist in nature or be synthesized as a stable compound. +- **Description**: A string that classifies the type of optimization that has resulted in the structural data. - **Type**: string - **Requirements/Conventions**: - - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter features. - - - If the property is :val:`null` or omitted, no information is provided regarding these aspects of the origin of the structural information. - - - If present and not :val:`null`, the property SHOULD take the first of the following values for which the structural information qualifies: + - **Query**: Support for queries on this property is OPTIONAL. - * :val:`experimental`: the structural information is a faithful representation of the outcome of an experimental technique for structure determination. + - If the property is :val:`null` or omitted, no information is provided about the type of optimization used to obtain the structural data. - * :val:`derived`: the structural information originates from experimental data, but has undergone additional processing in such a way that the result is still recognizable as the experimental structure it was based on. - For example, experimental structures relaxed using *ab initio* calculations are meant to qualify for this category. - Structures where one or more elements in a structure have been substituted (while, e.g., keeping the experimental coordinates the same) are not meant to qualify for this category. - The category definition involves a degree of subjectivity that has to be decided by the database provider. + - If present and not :val:`null`, the property SHOULD take one of the following values: - * :val:`predicted`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a potentially synthesizable structure. - For example, theoretically invented structures found to be close to the convex hull of thermodynamical stability at reasonable conditions by relaxation using *ab initio* calculations, AI models with a demonstrated reasonable predictive power, or similar techniques qualify for this category. - Structures that are the outcome of theoretical methods that specifically target conditions far outside normal conditions are not meant to qualify for this category. - This category definition involves a degree of subjectivity that has to be determined by the database provider. - It is OPTIONAL for database providers to predict theoretical structures as potentially synthesizable or not. - If this functionality is not provided, any structures that could fit this category are meant to be assigned the next qualifying category below instead. + * :val:`experimental`: the structure is the result of an optimization or refinement process part of an experimental technique, e.g., minimization of the discrepancy between observed and predicted scattered amplitudes from diffraction data. - * :val:`hypothetical`: the structural information is not directly related to the outcome of an experiment on an existing material, but is proposed from theoretical methods to represent a local energy minimum on the potential energy surface. - This category accommodates potentially highly thermodynamically unstable structures, e.g., predicted to decompose into other competing phases, even with respect to the elemental solids. - For example, structures relaxed using *ab initio* calculations but not identified to end up close to the convex hull of thermodynamical stability qualify for this category. - AI models which, with a demonstrated reasonable predictive power, can generate structures in local potential energy minimums (e.g., by relaxation via predicted forces, direct generation, etc.) also qualify. - This category definition also involves a degree of subjectivity that has to be determined by the database provider. + * :val:`hybrid`: the structure is the result of the combination of an experiment and further optimization based on a reasonable theoretical energy model in such a way that it remains a fair representation of the original experimental structure. + For example, experimental structures relaxed using *ab initio* calculations are in this category. + Structures where the experimental coordinates are kept, but one or more elements are substituted for other elements are not included in this category. - * :val:`arbitrary`: the structural information has been created in a way that does not ensure any type of stability, i.e., not even representing a local energy minimum on the potential energy surface. - For example, arbitrarily placed atoms that have not been locally optimized, non-equilibrium snapshots, and outcomes of AI models for which the predictive power is deemed insufficient for the earlier categories, all qualify for this category. + * :val:`global`: the structure has been optimized using a theoretical technique based on a reasonable energy model in a way that takes into account the global energy surface. + The structure has been optimized into the global energy minimum or into a local minimum within an energy range of the global minimum commonly considered for potential metastability (typically on the scale of 100 meV/atom). + A common technique for this type of optimization is to construct the convex hull of thermodynamical stability from the known minima and dismiss structures outside the relevant energy range. + + * :val:`local`: the structure has been optimized using a theoretical technique based on a reasonable energy model into a local minimum of the energy surface. + For example, structures relaxed using *ab initio* calculations without consideration of the convex hull of thermodynamical stability qualify for this category. - * :val:`indeterminate`: the database provider has determined that it is unable to classify the origin of the structural data into these categories, e.g., because the source of the data provides no such information. - There is a subtle, but relevant, distinction between this value and and not assigning the property any value (i.e, the field is missing or has value :val:`null`, making the property unknown in the sense discussed in the section `Properties with an unknown value`_). - The value "indeterminate" communicates that the database provider has intentionally classified the structure into this category, i.e., it states that it is known that its origin is not known, in contrast to the database not providing any data value for classifying the structure. + * :val:`none`: the structural has not undergone an optimization process and is thus, in some sense, arbitrary. + Structures of this kind can come from, e.g., randomly generated coordinates or non-equilibrium snapshots. + + * :val:`indeterminate`: the database declares that the type of optimization used for this specific entry cannot be determined, e.g., because that information is missing. + This value represents a stronger statement - it is known that optimization is unknown - than an omitted classification (i.e, the field is missing or has value :val:`null`) that marks the property unknown only in the sense discussed in the section `Properties with an unknown value`_.) - * :val:`other`: the origin of the structural information is known, but is not correctly described by any of the above categories. + * :val:`other`: the structure is the result of some optimization process, but none of the other categories correctly represents the type of optimization used. - - Database-specific strings using a database provider prefix (e.g., `_exmpl_experimental_at_extreme_pressure`) MAY be used but are strongly discouraged. + Other strings prefixed by a database-specific prefix, e.g., `_exmpl_optimized_on_fixed_grid`. SHOULD NOT be used. + Other non-standard strings MUST NOT be used. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`. + + Structures produced by AI models and other techniques that have been reasonably tested to reliably generate results equivalent with structural optimization using energy models SHOULD be classified the same as if that type of energy model had been used. - **Examples**: - For a structure entry directly encoding structural information obtained from a neutron diffraction experiment: :val:`"experimental"`. - - For a structure entry that encodes the structural information from a theoretical relaxation of an :val:`"experimental"` entry using computational software that implements density functional theory: :val:`"derived"`. + + - For a structure entry that encodes the structural information from a theoretical relaxation of an :val:`"experimental"` entry using computational software that implements density functional theory: :val:`"hybrid"`. Calculations Entries -------------------- From 74b459caa5f08266edc84e52cdfbc9872f04d357 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 16:36:15 +0100 Subject: [PATCH 28/33] Minor language and grammar corrections --- optimade.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/optimade.rst b/optimade.rst index 0f89d1f0d..05b2cc16a 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2867,6 +2867,7 @@ optimization\_type - **Type**: string - **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. @@ -2874,11 +2875,11 @@ optimization\_type - If present and not :val:`null`, the property SHOULD take one of the following values: - * :val:`experimental`: the structure is the result of an optimization or refinement process part of an experimental technique, e.g., minimization of the discrepancy between observed and predicted scattered amplitudes from diffraction data. + * :val:`experimental`: the structure results from an optimization or refinement process part of an experimental technique, e.g., minimization of the discrepancy between observed and predicted scattered amplitudes from diffraction data. - * :val:`hybrid`: the structure is the result of the combination of an experiment and further optimization based on a reasonable theoretical energy model in such a way that it remains a fair representation of the original experimental structure. + * :val:`hybrid`: the structure is the result of the combination of an experiment and further optimization based on a reasonable theoretical energy model so that it remains a fair representation of the original experimental structure. For example, experimental structures relaxed using *ab initio* calculations are in this category. - Structures where the experimental coordinates are kept, but one or more elements are substituted for other elements are not included in this category. + Structures where the experimental coordinates are kept, but one or more elements are substituted for other elements, are not included in this category. * :val:`global`: the structure has been optimized using a theoretical technique based on a reasonable energy model in a way that takes into account the global energy surface. The structure has been optimized into the global energy minimum or into a local minimum within an energy range of the global minimum commonly considered for potential metastability (typically on the scale of 100 meV/atom). @@ -2887,11 +2888,11 @@ optimization\_type * :val:`local`: the structure has been optimized using a theoretical technique based on a reasonable energy model into a local minimum of the energy surface. For example, structures relaxed using *ab initio* calculations without consideration of the convex hull of thermodynamical stability qualify for this category. - * :val:`none`: the structural has not undergone an optimization process and is thus, in some sense, arbitrary. + * :val:`none`: the structure has not undergone an optimization process and is thus, in some sense, arbitrary. Structures of this kind can come from, e.g., randomly generated coordinates or non-equilibrium snapshots. * :val:`indeterminate`: the database declares that the type of optimization used for this specific entry cannot be determined, e.g., because that information is missing. - This value represents a stronger statement - it is known that optimization is unknown - than an omitted classification (i.e, the field is missing or has value :val:`null`) that marks the property unknown only in the sense discussed in the section `Properties with an unknown value`_.) + This value represents a stronger statement (that the database knows that the type of optimization is not known) than an omitted classification (i.e., the field is missing or has the value :val:`null`) which communicates that the property is unknown only in the sense discussed in the section `Properties with an unknown value`_.) * :val:`other`: the structure is the result of some optimization process, but none of the other categories correctly represents the type of optimization used. @@ -2899,7 +2900,7 @@ optimization\_type Other non-standard strings MUST NOT be used. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`. - Structures produced by AI models and other techniques that have been reasonably tested to reliably generate results equivalent with structural optimization using energy models SHOULD be classified the same as if that type of energy model had been used. + Structures produced by AI models and other techniques that have been reasonably tested to reliably generate results equivalent to structural optimization using energy models SHOULD be classified the same as if that type of energy model had been used. - **Examples**: From 0747f467efc9957cebecae3fc16b7fd5d04179dd Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 16:38:27 +0100 Subject: [PATCH 29/33] Remove trailing whitespace --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 05b2cc16a..4789d81a4 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2883,7 +2883,7 @@ optimization\_type * :val:`global`: the structure has been optimized using a theoretical technique based on a reasonable energy model in a way that takes into account the global energy surface. The structure has been optimized into the global energy minimum or into a local minimum within an energy range of the global minimum commonly considered for potential metastability (typically on the scale of 100 meV/atom). - A common technique for this type of optimization is to construct the convex hull of thermodynamical stability from the known minima and dismiss structures outside the relevant energy range. + A common technique for this type of optimization is to construct the convex hull of thermodynamical stability from the known minima and dismiss structures outside the relevant energy range. * :val:`local`: the structure has been optimized using a theoretical technique based on a reasonable energy model into a local minimum of the energy surface. For example, structures relaxed using *ab initio* calculations without consideration of the convex hull of thermodynamical stability qualify for this category. @@ -2900,7 +2900,7 @@ optimization\_type Other non-standard strings MUST NOT be used. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`. - Structures produced by AI models and other techniques that have been reasonably tested to reliably generate results equivalent to structural optimization using energy models SHOULD be classified the same as if that type of energy model had been used. + Structures produced by AI models and other techniques that have been reasonably tested to reliably generate results equivalent to structural optimization using energy models SHOULD be classified the same as if that type of energy model had been used. - **Examples**: From 69fdc58016e940cd53aeb72f354620c1537c8e03 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 16:45:58 +0100 Subject: [PATCH 30/33] Remove whitespace --- optimade.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index 8aef47533..7adfae3b7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3202,13 +3202,13 @@ optimization\_type * :val:`global`: the structure has been optimized using a theoretical technique based on a reasonable energy model in a way that takes into account the global energy surface. The structure has been optimized into the global energy minimum or into a local minimum within an energy range of the global minimum commonly considered for potential metastability (typically on the scale of 100 meV/atom). A common technique for this type of optimization is to construct the convex hull of thermodynamical stability from the known minima and dismiss structures outside the relevant energy range. - + * :val:`local`: the structure has been optimized using a theoretical technique based on a reasonable energy model into a local minimum of the energy surface. For example, structures relaxed using *ab initio* calculations without consideration of the convex hull of thermodynamical stability qualify for this category. * :val:`none`: the structure has not undergone an optimization process and is thus, in some sense, arbitrary. Structures of this kind can come from, e.g., randomly generated coordinates or non-equilibrium snapshots. - + * :val:`indeterminate`: the database declares that the type of optimization used for this specific entry cannot be determined, e.g., because that information is missing. This value represents a stronger statement (that the database knows that the type of optimization is not known) than an omitted classification (i.e., the field is missing or has the value :val:`null`) which communicates that the property is unknown only in the sense discussed in the section `Properties with an unknown value`_.) @@ -3217,13 +3217,13 @@ optimization\_type Other strings prefixed by a database-specific prefix, e.g., `_exmpl_optimized_on_fixed_grid`. SHOULD NOT be used. Other non-standard strings MUST NOT be used. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`. - + Structures produced by AI models and other techniques that have been reasonably tested to reliably generate results equivalent to structural optimization using energy models SHOULD be classified the same as if that type of energy model had been used. - **Examples**: - For a structure entry directly encoding structural information obtained from a neutron diffraction experiment: :val:`"experimental"`. - + - For a structure entry that encodes the structural information from a theoretical relaxation of an :val:`"experimental"` entry using computational software that implements density functional theory: :val:`"hybrid"`. Calculations Entries From 4a0dcd59f997004c187dd6be9db3c58dfe1fe570 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 16:58:17 +0100 Subject: [PATCH 31/33] Slight adjustment of a formulation --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 7adfae3b7..4e2530047 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3204,7 +3204,7 @@ optimization\_type A common technique for this type of optimization is to construct the convex hull of thermodynamical stability from the known minima and dismiss structures outside the relevant energy range. * :val:`local`: the structure has been optimized using a theoretical technique based on a reasonable energy model into a local minimum of the energy surface. - For example, structures relaxed using *ab initio* calculations without consideration of the convex hull of thermodynamical stability qualify for this category. + For example, structures relaxed using *ab initio* calculations without consideration of the energy of other minima in configuration space qualify for this category. * :val:`none`: the structure has not undergone an optimization process and is thus, in some sense, arbitrary. Structures of this kind can come from, e.g., randomly generated coordinates or non-equilibrium snapshots. From 0e324d3a2f582fcb9fc658b2b7743b71f4fd9ca7 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 16:59:59 +0100 Subject: [PATCH 32/33] Fix punctuation --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 4e2530047..87d01010d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3214,7 +3214,7 @@ optimization\_type * :val:`other`: the structure is the result of some optimization process, but none of the other categories correctly represents the type of optimization used. - Other strings prefixed by a database-specific prefix, e.g., `_exmpl_optimized_on_fixed_grid`. SHOULD NOT be used. + Other strings prefixed by a database-specific prefix, e.g., `_exmpl_optimized_on_fixed_grid` SHOULD NOT be used. Other non-standard strings MUST NOT be used. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`. From 3d7675147c0b35ceb77792a0a480c829d7912d33 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 10 Jan 2024 17:44:36 +0100 Subject: [PATCH 33/33] Fix punctuation Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 87d01010d..c9942adfb 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3214,7 +3214,7 @@ optimization\_type * :val:`other`: the structure is the result of some optimization process, but none of the other categories correctly represents the type of optimization used. - Other strings prefixed by a database-specific prefix, e.g., `_exmpl_optimized_on_fixed_grid` SHOULD NOT be used. + Other strings prefixed by a database-specific prefix, e.g., `_exmpl_optimized_on_fixed_grid`, SHOULD NOT be used. Other non-standard strings MUST NOT be used. Clients encountering unrecognized strings SHOULD treat them to mean the same as the field having the value :val:`"other"`.