Use Tuple over List for constrained lists

Co-authored-by: Shyam Dwaraknath <[email protected]>

openapi/openapi.json

@@ -2653,37 +2653,79 @@
           },
           "dimension_types": {
             "title": "Dimension Types",
-            "maxItems": 3,
-            "minItems": 3,
             "type": "array",
-            "items": {
-              "enum": [
-                0,
-                1
-              ],
-              "type": "integer"
-            },
+            "items": [
+              {
+                "enum": [
+                  0,
+                  1
+                ],
+                "type": "integer"
+              },
+              {
+                "enum": [
+                  0,
+                  1
+                ],
+                "type": "integer"
+              },
+              {
+                "enum": [
+                  0,
+                  1
+                ],
+                "type": "integer"
+              }
+            ],
             "description": "List of three integers.\n  For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`_).\n  This list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`).\n  Note: the elements in this list each refer to the direction of the corresponding entry in property `lattice_vectors`_ and *not* the Cartesian x, y, z directions.\n- **Type**: list of integers.\n- **Requirements/Conventions**:\n\n  - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n  - **Query**: MUST be a queryable property. Support for equality comparison is REQUIRED, support for other comparison operators are OPTIONAL.\n  - MUST be a list of length 3.\n  - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n\n  - For a molecule: :val:`[0, 0, 0]`\n  - For a wire along the direction specified by the third lattice vector: :val:`[0, 0, 1]`\n  - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: :val:`[1, 0, 1]`\n  - For a bulk 3D system: :val:`[1, 1, 1]`"
           },
           "lattice_vectors": {
             "title": "Lattice Vectors",
-            "maxItems": 3,
-            "minItems": 3,
             "type": "array",
-            "items": {
-              "type": "array",
-              "items": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "number"
-                }
-              ]
-            },
+            "items": [
+              {
+                "type": "array",
+                "items": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ]
+              },
+              {
+                "type": "array",
+                "items": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ]
+              },
+              {
+                "type": "array",
+                "items": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ]
+              }
+            ],
             "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n- **Type**: list of list of floats.\n- **Requirements/Conventions**:\n\n  - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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  - This property MUST be an array of dimensions 3 times 3 regardless of the elements of :property:`dimension_types`.\n    The vectors SHOULD by convention be chosen so the determinant of the :property:`lattice_vectors` matrix is different from zero.\n    The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n  - All three elements of the inner lists of floats MAY be :val:`null` for non-periodic dimensions, i.e., those dimensions for which :property:`dimension_types` is :val:`0`.\n\n- **Examples**:\n\n  - :val:`[[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 :val:`(4, 0, 0)`, i.e., a vector aligned along the :val:`x` axis of length 4 \u00c5; the second vector is :val:`(0, 4, 0)`; and the third vector is :val:`(0, 1, 4)`."
           },
           "cartesian_site_positions": {

optimade/models/structures.py

@@ -18,6 +18,9 @@
 EPS = float_info.epsilon
 
 
+Vector3D = Tuple[Union[float, None], Union[float, None], Union[float, None]]
+
+
 class Periodicity(IntEnum):
     APERIODIC = 0
     PERIODIC = 1
@@ -313,7 +316,7 @@ class StructureResourceAttributes(EntryResourceAttributes):
   - A filter that matches an exactly given formula is :filter:`chemical_formula_anonymous="A2B"`.""",
     )
 
-    dimension_types: List[Periodicity] = Field(
+    dimension_types: Tuple[Periodicity, Periodicity, Periodicity] = Field(
         ...,
         description="""List of three integers.
   For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`_).
@@ -333,13 +336,9 @@ class StructureResourceAttributes(EntryResourceAttributes):
   - For a wire along the direction specified by the third lattice vector: :val:`[0, 0, 1]`
   - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: :val:`[1, 0, 1]`
   - For a bulk 3D system: :val:`[1, 1, 1]`""",
-        min_items=3,
-        max_items=3,
     )
 
-    lattice_vectors: Optional[
-        List[Tuple[Union[float, None], Union[float, None], Union[float, None]]]
-    ] = Field(
+    lattice_vectors: Optional[Tuple[Vector3D, Vector3D, Vector3D]] = Field(
         None,
         description="""The three lattice vectors in Cartesian coordinates, in ångström (Å).
 - **Type**: list of list of floats.
@@ -360,13 +359,9 @@ class StructureResourceAttributes(EntryResourceAttributes):
 
   - :val:`[[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 :val:`(4, 0, 0)`, i.e., a vector aligned along the :val:`x` axis of length 4 Å; the second vector is :val:`(0, 4, 0)`; and the third vector is :val:`(0, 1, 4)`.""",
         unit="Å",
-        min_items=3,
-        max_items=3,
     )
 
-    cartesian_site_positions: List[
-        Tuple[Union[float, None], Union[float, None], Union[float, None]]
-    ] = Field(
+    cartesian_site_positions: List[Vector3D] = Field(
         ...,
         description="""Cartesian positions of each site. A site is an atom, a site potentially occupied by an atom, or a placeholder for a virtual mixture of atoms (e.g., in a virtual crystal approximation).
 - **Type**: list of list of floats and/or unknown values