Add space_group_hall and space_group_it_number to structure model

Author: ml-evs

openapi/openapi.json

@@ -3359,9 +3359,9 @@
               "type": "number"
             },
             "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.",
+            "x-optimade-unit": "a.m.u.",
             "x-optimade-queryable": "optional",
-            "x-optimade-support": "optional",
-            "x-optimade-unit": "a.m.u."
+            "x-optimade-support": "optional"
           },
           "original_name": {
             "title": "Original Name",
@@ -3639,9 +3639,25 @@
             },
             "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT 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    - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n      (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n    - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n    - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n      The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n      The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n    - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n        If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n    - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.",
             "nullable": true,
+            "x-optimade-unit": "\u00c5",
+            "x-optimade-queryable": "optional",
+            "x-optimade-support": "should"
+          },
+          "space_group_hall": {
+            "title": "Space Group Hall",
+            "type": "string",
+            "description": "A Hall space group symbol representing the symmetry of the structure as defined in Hall, S. R. (1981), Acta Cryst. A37, 517-525 and erratum (1981), A37, 921.\n\n- **Type**: string\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  - Each component of the Hall symbol MUST be separated by a single space symbol.\n  - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n  - MUST be null if `nperiodic_dimensions` is not equal to 3.",
             "x-optimade-queryable": "optional",
-            "x-optimade-support": "should",
-            "x-optimade-unit": "\u00c5"
+            "x-optimade-support": "optional"
+          },
+          "space_group_it_number": {
+            "title": "Space Group It Number",
+            "maximum": 230.0,
+            "minimum": 1.0,
+            "type": "integer",
+            "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\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  - The integer value MUST be between 1 and 230.\n  - MUST be null if `nperiodic_dimensions` is not equal to 3.",
+            "x-optimade-queryable": "optional",
+            "x-optimade-support": "optional"
           },
           "cartesian_site_positions": {
             "title": "Cartesian Site Positions",
@@ -3656,9 +3672,9 @@
             },
             "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT 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    - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n    - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n    - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.",
             "nullable": true,
+            "x-optimade-unit": "\u00c5",
             "x-optimade-queryable": "optional",
-            "x-optimade-support": "should",
-            "x-optimade-unit": "\u00c5"
+            "x-optimade-support": "should"
           },
           "nsites": {
             "title": "Nsites",

optimade/models/structures.py

@@ -7,7 +7,7 @@
 from functools import reduce
 from typing import List, Optional, Union
 
-from pydantic import BaseModel, conlist, root_validator, validator
+from pydantic import BaseModel, conint, conlist, root_validator, validator
 
 from optimade.models.entries import EntryResource, EntryResourceAttributes
 from optimade.models.utils import (
@@ -525,6 +525,36 @@ class StructureResourceAttributes(EntryResourceAttributes):
         queryable=SupportLevel.OPTIONAL,
     )
 
+    space_group_hall: Optional[str] = OptimadeField(
+        None,
+        description="""A Hall space group symbol representing the symmetry of the structure as defined in Hall, S. R. (1981), Acta Cryst. A37, 517-525 and erratum (1981), A37, 921.
+
+- **Type**: string
+
+- **Requirements/Conventions**:
+  - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.
+  - **Query**: Support for queries on this property is OPTIONAL.
+  - Each component of the Hall symbol MUST be separated by a single space symbol.
+  - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.
+  - MUST be null if `nperiodic_dimensions` is not equal to 3.""",
+        support=SupportLevel.OPTIONAL,
+        queryable=SupportLevel.OPTIONAL,
+    )
+
+    space_group_it_number: Optional[conint(ge=1, le=230)] = OptimadeField(  # type: ignore[valid-type]
+        None,
+        description="""Space group number for the structure assigned by the International Tables for Crystallography Vol. A.
+- **Type**: integer
+
+- **Requirements/Conventions**:
+  - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.
+  - **Query**: Support for queries on this property is OPTIONAL.
+  - The integer value MUST be between 1 and 230.
+  - MUST be null if `nperiodic_dimensions` is not equal to 3.""",
+        support=SupportLevel.OPTIONAL,
+        queryable=SupportLevel.OPTIONAL,
+    )
+
     cartesian_site_positions: Optional[List[Vector3D]] = OptimadeField(  # type: ignore[valid-type]
         ...,
         description="""Cartesian positions of each site in the structure.
@@ -950,6 +980,12 @@ def check_periodic_dimensions(cls, v, values):
 
         return v
 
+    @validator("space_group_hall", "space_group_it_number")
+    def check_space_group_vs_nperiodic_dimensions(cls, v, values, field):
+        if v is not None and values.get("nperiodic_dimensions", 3) != 3:
+            raise ValueError(f"{field.name} provided but `nperiodic_dimensions!=3`")
+        return v
+
     @validator("lattice_vectors", always=True)
     def required_if_dimension_types_has_one(cls, v, values):
         if v is None: