From 5e96ac1323808b1357ae3b1bd5470335457c9daa Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 17 Nov 2020 11:25:40 +0000 Subject: [PATCH] Fixed 'assemblies' description example from (https://github.com/Materials-Consortia/OPTIMADE/pull/338) --- openapi/openapi.json | 2 +- optimade/models/structures.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi/openapi.json b/openapi/openapi.json index e5184409e..7748588b5 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -3150,7 +3150,7 @@ "items": { "$ref": "#/components/schemas/Assembly" }, - "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": {\n \"Si\": { \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n \"Ge\": { \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n \"vac\": { \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n },\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability)." + "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n },\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability)." }, "structure_features": { "title": "Structure Features", diff --git a/optimade/models/structures.py b/optimade/models/structures.py index 78cab79ba..9774b2b9d 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -709,10 +709,10 @@ class StructureResourceAttributes(EntryResourceAttributes): { "cartesian_site_positions": [ [0,0,0], [0,0,0], [0,0,0] ], "species_at_sites": ["Si", "Ge", "vac"], - "species": { - "Si": { "chemical_symbols": ["Si"], "concentration": [1.0] }, - "Ge": { "chemical_symbols": ["Ge"], "concentration": [1.0] }, - "vac": { "chemical_symbols": ["vacancy"], "concentration": [1.0] } + "species": [ + { "name": "Si", "chemical_symbols": ["Si"], "concentration": [1.0] }, + { "name": "Ge", "chemical_symbols": ["Ge"], "concentration": [1.0] }, + { "name": "vac", "chemical_symbols": ["vacancy"], "concentration": [1.0] } }, "assemblies": [ {