| 1 |
$$schema: "https://schemas.optimade.org/meta/v1.2/optimade/property_definition" |
| 2 |
$id: "https://schemas.optimade.org/defs/v1.2/properties/optimade/structures/assemblies" |
| 3 |
title: "assemblies" |
| 4 |
x-optimade-type: "dictionary" |
| 5 |
x-optimade-definition: |
| 6 |
label: "assemblies_optimade_structures" |
| 7 |
kind: "property" |
| 8 |
version: "1.2.0" |
| 9 |
format: "1.2" |
| 10 |
name: "assemblies" |
| 11 |
type: |
| 12 |
- "object" |
| 13 |
- "null" |
| 14 |
description: |- |
| 15 |
A description of groups of sites that are statistically correlated. |
| 16 |
|
| 17 |
**Requirements/Conventions**: |
| 18 |
|
| 19 |
- The property SHOULD be `null` for entries that have no partial occupancies. |
| 20 |
- If present, the correct flag MUST be set in the list `structure_features` (see property `structure_features`). |
| 21 |
- Client implementations MUST check its presence (as its presence changes the interpretation of the structure). |
| 22 |
- If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys: |
| 23 |
|
| 24 |
- **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly. |
| 25 |
|
| 26 |
Example: `[[1], [2]]`: two groups, one with the second site, one with the third. |
| 27 |
Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth. |
| 28 |
|
| 29 |
- **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`. |
| 30 |
It SHOULD sum to one. |
| 31 |
See below for examples of how to specify the probability of the occurrence of a vacancy. |
| 32 |
The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`, see property `species`. |
| 33 |
|
| 34 |
- If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified). |
| 35 |
- A site MUST NOT appear in more than one group. |
| 36 |
|
| 37 |
**Explained examples**: |
| 38 |
|
| 39 |
- `{"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. |
| 40 |
Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. |
| 41 |
- `{"sites_in_groups": [[1,2], [3]], "group_probabilities": [0.3, 0.7]}`: the second and third sites are either present together or not present; they form the first group of atoms for this assembly. |
| 42 |
The second group is formed by the fourth site. |
| 43 |
Sites of the first group (the second and the third) are never present at the same time as the fourth site. |
| 44 |
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). |
| 45 |
|
| 46 |
**Notes**: |
| 47 |
|
| 48 |
- Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites). |
| 49 |
- 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 is present in two conformations). |
| 50 |
- 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. |
| 51 |
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: |
| 52 |
|
| 53 |
- Using a single species: |
| 54 |
|
| 55 |
{ |
| 56 |
"cartesian_site_positions": [[0,0,0]], |
| 57 |
"species_at_sites": ["SiGe-vac"], |
| 58 |
"species": [ |
| 59 |
{ |
| 60 |
"name": "SiGe-vac", |
| 61 |
"chemical_symbols": ["Si", "Ge", "vacancy"], |
| 62 |
"concentration": [0.3, 0.5, 0.2] |
| 63 |
} |
| 64 |
] |
| 65 |
// ... |
| 66 |
} |
| 67 |
|
| 68 |
|
| 69 |
|
| 70 |
- Using multiple species and the assemblies: |
| 71 |
|
| 72 |
{ |
| 73 |
"cartesian_site_positions": [ [0,0,0], [0,0,0], [0,0,0] ], |
| 74 |
"species_at_sites": ["Si", "Ge", "vac"], |
| 75 |
"species": [ |
| 76 |
{ "name": "Si", "chemical_symbols": ["Si"], "concentration": [1.0] }, |
| 77 |
{ "name": "Ge", "chemical_symbols": ["Ge"], "concentration": [1.0] }, |
| 78 |
{ "name": "vac", "chemical_symbols": ["vacancy"], "concentration": [1.0] } |
| 79 |
], |
| 80 |
"assemblies": [ |
| 81 |
{ |
| 82 |
"sites_in_groups": [ [0], [1], [2] ], |
| 83 |
"group_probabilities": [0.3, 0.5, 0.2] |
| 84 |
} |
| 85 |
] |
| 86 |
// ... |
| 87 |
} |
| 88 |
|
| 89 |
- 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. |
| 90 |
However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it. |
| 91 |
- The probabilities of occurrence of different assemblies are uncorrelated. |
| 92 |
So, for instance in the following case with two assemblies: |
| 93 |
|
| 94 |
{ |
| 95 |
"assemblies": [ |
| 96 |
{ |
| 97 |
"sites_in_groups": [ [0], [1] ], |
| 98 |
"group_probabilities": [0.2, 0.8] |
| 99 |
}, |
| 100 |
{ |
| 101 |
"sites_in_groups": [ [2], [3] ], |
| 102 |
"group_probabilities": [0.3, 0.7] |
| 103 |
} |
| 104 |
] |
| 105 |
} |
| 106 |
|
| 107 |
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 %. |
| 108 |
These two sites are correlated (either site 2 or 3 is present). |
| 109 |
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). |
| 110 |
examples: |
| 111 |
- {"sites_in_groups": [[0], [1]], "group_probabilities": [0.3, 0.7]} |
| 112 |
- {"sites_in_groups": [[1,2], [3]], "group_probabilities": [0.3, 0.7]} |
| 113 |
x-optimade-unit: "inapplicable" |
| 114 |
properties: |
| 115 |
sites_in_groups: |
| 116 |
title: "sites in groups" |
| 117 |
x-optimade-type: "list" |
| 118 |
x-optimade-dimensions: |
| 119 |
names: ["dim_assembly_groups", "dim_assembly_groups_sites"] |
| 120 |
type: |
| 121 |
- "array" |
| 122 |
description: |- |
| 123 |
Index of the sites (0-based) that belong to each group for each assembly. |
| 124 |
|
| 125 |
**Explained examples**: |
| 126 |
|
| 127 |
- `[[1], [2]]`: two groups, one with the second site, one with the third. |
| 128 |
- `[[1,2], [3]]`: one group with the second and third site, one with the fourth. |
| 129 |
examples: |
| 130 |
- [[1], [2]] |
| 131 |
- [[1,2], [3]] |
| 132 |
x-optimade-unit: "inapplicable" |
| 133 |
items: |
| 134 |
title: "group of sites" |
| 135 |
x-optimade-type: "list" |
| 136 |
x-optimade-dimensions: |
| 137 |
names: ["dim_assembly_groups_sites"] |
| 138 |
type: |
| 139 |
- "array" |
| 140 |
description: |- |
| 141 |
A list of sites that belong to one group in the assembly. |
| 142 |
examples: |
| 143 |
- [1] |
| 144 |
- [1,2] |
| 145 |
x-optimade-unit: "inapplicable" |
| 146 |
items: |
| 147 |
title: "a site reference" |
| 148 |
x-optimade-type: "integer" |
| 149 |
type: |
| 150 |
- "integer" |
| 151 |
description: |- |
| 152 |
An integer that refers to a site by index (0-based). |
| 153 |
examples: |
| 154 |
- 2 |
| 155 |
x-optimade-unit: "inapplicable" |
| 156 |
group_probabilities: |
| 157 |
title: "group probabilities" |
| 158 |
x-optimade-type: "list" |
| 159 |
x-optimade-dimensions: |
| 160 |
names: ["dim_assembly_groups"] |
| 161 |
type: |
| 162 |
- "array" |
| 163 |
description: |- |
| 164 |
Statistical probability of each group. |
| 165 |
|
| 166 |
**Requirements/Conventions**: |
| 167 |
|
| 168 |
- It MUST have the same length as `sites_in_groups`. |
| 169 |
- It SHOULD sum to one. |
| 170 |
- The possible reasons for the values not to sum to one are the same as specified in the `concentration` field of the `species` property. |
| 171 |
examples: |
| 172 |
- [0.3, 0.7] |
| 173 |
x-optimade-unit: "inapplicable" |
| 174 |
items: |
| 175 |
title: "a concentration" |
| 176 |
x-optimade-type: "float" |
| 177 |
type: |
| 178 |
- "number" |
| 179 |
description: |- |
| 180 |
A float that specifies the statistical probability of a group in the description of assemblies. |
| 181 |
examples: |
| 182 |
- 0.4 |
| 183 |
x-optimade-unit: "dimensionless" |
| 184 |
required: |
| 185 |
- "sites_in_groups" |
| 186 |
- "group_probabilities" |