Debian Codegraph @

externals/OPTIMADE/schemas/src/defs/v1.2/properties/optimade/structures/species.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/species"
3 title: "species"
4 x-optimade-type: "list"
5 x-optimade-definition:
6 label: "species_optimade_structures"
7 kind: "property"
8 version: "1.2.0"
9 format: "1.2"
10 name: "species"
11 x-optimade-dimensions:
12 names: ["dim_species"]
13 x-optimade-unit-definitions:
14 - $$inherit: "/v1.2/units/si/general/atomicmassunit"
15 type:
16 - "array"
17 - "null"
18 description: |-
19 A list describing the species of the sites of this structure. Species can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).
20
21 **Requirements/Conventions**:
22
23 - Each list member MUST be a dictionary with the following keys:
24
25 - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;
26
27 - **chemical\_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:
28
29 - a valid chemical-element symbol, or
30 - the special value `"X"` to represent a non-chemical element, or
31 - the special value `"vacancy"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).
32
33 If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features` (see property `structure_features`).
34
35 - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species.
36 The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:
37
38 - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.
39 - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.
40
41 Note that concentrations are uncorrelated between different sites (even of the same species).
42
43 - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or "X" for a non-chemical element.
44 - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.
45
46 The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.
47 Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.
48
49 - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.
50 Elements denoting vacancies MUST have masses equal to 0.
51 - **original\_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.
52
53 **Note**: With regard to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.
54 The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).
55
56 - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `"Ti"` for titanium, `"O"` for oxygen, etc.)
57 However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.
58 This means that a species `{"name": "C", "chemical_symbols": ["Ti"], "concentration": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).
59 - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.
60
61 **Explained examples**:
62
63 - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom.
64 - `[ {"name": "Ti", "chemical_symbols": ["Ti", "vacancy"], "concentration": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.
65 - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability.
66 - `[ {"name": "C12", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.
67 - `[ {"name": "C13", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.
68 - `[ {"name": "CH3", "chemical_symbols": ["C"], "concentration": [1.0], "attached": ["H"], "nattached": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.
69 examples:
70 - [ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]
71 - [ {"name": "Ti", "chemical_symbols": ["Ti", "vacancy"], "concentration": [0.9, 0.1]} ]
72 - [ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": [0.0, 137.327, 40.078]} ]
73 - [ {"name": "C12", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [12.0]} ]
74 - [ {"name": "C13", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [13.0]} ]
75 - [ {"name": "CH3", "chemical_symbols": ["C"], "concentration": [1.0], "attached": ["H"], "nattached": [3]} ]
76 x-optimade-unit: "inapplicable"
77 items:
78 title: "species declaration"
79 x-optimade-type: "dictionary"
80 description: |-
81 A declaration of a species of the sites of this structure. Species can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).
82 x-optimade-unit: inapplicable
83 type:
84 - "object"
85 properties:
86 name:
87 $$inherit: "/v1.2/properties/optimade/common/species_name"
88 chemical_symbols:
89 title: "chemical symbols"
90 x-optimade-type: "list"
91 x-optimade-dimensions:
92 names: ["dim_species_chemical_symbols"]
93 type:
94 - "array"
95 description: |-
96 The chemical symbols for the elements composing this species.
97
98 **Requirements/Conventions**:
99
100 - MUST be a list of strings of all chemical elements composing this species.
101 Each item of the list MUST be one of the following:
102
103 - a valid chemical-element symbol, or
104 - the special value `"X"` to represent a non-chemical element, or
105 - the special value `"vacancy"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).
106
107 If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features` (see property `structure_features`).
108 examples:
109 - ["Na", "Cl"]
110 - ["Si", "Mn", "X", "vacancy"]
111 x-optimade-unit: "inapplicable"
112 items:
113 $$inherit: "/v1.2/properties/optimade/common/chemical_symbol_or_vacancy"
114 concentration:
115 title: "concentration"
116 x-optimade-type: "list"
117 x-optimade-dimensions:
118 names: ["dim_species_chemical_symbols"]
119 type:
120 - "array"
121 description: |-
122 A list of the relative concentrations of the elements composing this species.
123
124 **Requirements/Conventions**:
125
126 - MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species.
127 - The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:
128
129 - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.
130 - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.
131
132 Note that concentrations are uncorrelated between different sites (even of the same species).
133 examples:
134 - [1.0]
135 - [0.3333333333333333, 0.2222222222222222, 0.4444444444444444]
136 x-optimade-unit: "inapplicable"
137 items:
138 x-optimade-type: "float"
139 type:
140 - "number"
141 x-optimade-unit: "dimensionless"
142 minimum: 0.0
143 maximum: 1.0
144 attached:
145 title: "attached chemical symbols"
146 x-optimade-type: "list"
147 x-optimade-dimensions:
148 names: ["dim_species_attached"]
149 type:
150 - "array"
151 description: |-
152 The chemical symbols of the elements or non-chemical elements attached to a site that has been assinged this species.
153
154 **Requirements/Conventions**:
155
156 - MUST be a list of strings of all chemical elements composing this species.
157 Each item of the list MUST be one of the following:
158
159 - a valid chemical-element symbol.
160 - the special value `"X"` to represent a non-chemical element.
161
162 If any one entry in the `species` list has a `attached` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features` (see property `structure_features`).
163 examples:
164 - ["Na", "Cl"]
165 - ["Si", "Mn", "X"]
166 x-optimade-unit: "inapplicable"
167 items:
168 $$inherit: "/v1.2/properties/optimade/common/chemical_symbol"
169 nattached:
170 title: "number of attached entities"
171 x-optimade-type: "list"
172 x-optimade-dimensions:
173 names: ["dim_species_attached"]
174 type:
175 - "array"
176 description: |-
177 MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.
178
179 **Requirements/Conventions**:
180
181 - The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.
182 Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.
183 examples:
184 - [1, 2, 5, 7]
185 x-optimade-unit: "inapplicable"
186 items:
187 x-optimade-type: "integer"
188 type:
189 - "integer"
190 x-optimade-unit: "dimensionless"
191 minimum: 0
192 mass:
193 title: "masses of the entities composing the species"
194 x-optimade-type: "list"
195 x-optimade-dimensions:
196 names: ["dim_species_chemical_symbols"]
197 type:
198 - "array"
199 description: |-
200 MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.
201
202 **Requirements/Conventions**:
203
204 - Elements denoting vacancies MUST have masses equal to 0.
205 examples:
206 - [58.933195, 28.0855]
207 x-optimade-unit: "inapplicable"
208 items:
209 x-optimade-type: "float"
210 type:
211 - "number"
212 x-optimade-unit: "dalton"
213 minimum: 0.0
214 original_name:
215 title: "original name"
216 x-optimade-type: "string"
217 type:
218 - "string"
219 description: |-
220 A name for the species that derives from the source database.
221
222 **Requirements/Conventions**:
223
224 - Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.
225
226 **Note**: With regard to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.
227 The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).
228 examples:
229 - "Na[49385]"
230 x-optimade-unit: "inapplicable"
231 required:
232 - "name"
233 - "chemical_symbols"
234 - "concentration"