Debian Codegraph @

externals/OPTIMADE/schemas/src/defs/v1.2/properties/optimade/structures/assemblies.yaml

raw
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"