@mat3ra/esse 2025.5.17-2 → 2025.6.14-0

package/example/apse/materials/builders/slab/pymatgen/parameters.json

@@ -1,5 +1,5 @@
 {
-    "min_vacuum_size": 1,
+    "min_vacuum_size": 0,
     "in_unit_planes": true,
     "reorient_lattice": true,
     "symmetrize": false

package/example/materials_category/pristine_structures/two-dimensional/slab.json

@@ -0,0 +1,38 @@
+{
+    "stack_components": [
+        {
+            "crystal": {
+                "...": "include(../../../material.json)"
+            },
+            "miller_indices": [
+                0,
+                0,
+                1
+            ],
+            "use_conventional_cell": true,
+            "termination_top": {
+                "chemical_elements": "Si",
+                "space_group_symmetry_label": "P4/mmm_2"
+            },
+            "number_of_repetitions": 5
+        },
+        {
+            "direction": "z",
+            "size": 10,
+            "crystal": {
+                "...": "include(../../../material.json)"
+            }
+        }
+    ],
+    "direction": "z",
+    "xy_supercell_matrix": [
+        [
+            2,
+            0
+        ],
+        [
+            0,
+            2
+        ]
+    ]
+}

package/example/materials_category_components/entities/auxiliary/three-dimensional/supercell_matrix_3d.json

@@ -0,0 +1,5 @@
+[
+    [2, 0, 0],
+    [0, 2, 0],
+    [0, 0, 2]
+] 

package/example/materials_category_components/entities/auxiliary/two-dimensional/miller_indices.json

@@ -0,0 +1 @@
+[0, 0, 1] 

package/example/materials_category_components/entities/auxiliary/two-dimensional/supercell_matrix_2d.json

@@ -0,0 +1,4 @@
+[
+    [2, 0],
+    [0, 2]
+] 

package/example/{material/reusable/slab → materials_category_components/entities/auxiliary/two-dimensional}/termination.json

@@ -1,4 +1,4 @@
 {
     "chemical_elements": "Si",
     "space_group_symmetry_label": "P4/mmm_2"
-}
+} 

package/example/materials_category_components/entities/auxiliary/zero-dimensional/crystal_site.json

@@ -0,0 +1,3 @@
+{
+    "coordinate": [0.25, 0.25, 0.25]
+} 

package/example/materials_category_components/entities/core/three-dimensional/crystal.json

@@ -0,0 +1,3 @@
+{
+    "...": "include(../../../../material.json)"
+} 

package/example/materials_category_components/entities/core/three-dimensional/void.json

@@ -0,0 +1,8 @@
+{
+    "center_coordinate": [ 0.5,
+        0.5,
+        0.5 ],
+    "shape": {
+        "...": "include(../../../../core/reusable/coordinate_conditions/box.json)"
+    }
+}

package/example/materials_category_components/entities/core/two-dimensional/vacuum.json

@@ -0,0 +1,7 @@
+{
+    "direction": "z",
+    "size": 10,
+    "crystal": {
+        "...": "include(../../../../material.json)"
+    }
+}

package/example/materials_category_components/entities/core/zero-dimensional/atom.json

@@ -0,0 +1,3 @@
+{
+    "chemical_element": "Si"
+} 

package/example/materials_category_components/entities/reusable/repetitions.json

@@ -0,0 +1 @@
+[2, 2, 1] 

package/example/materials_category_components/operations/core/combinations/merge.json

@@ -0,0 +1,11 @@
+{
+    "merge_components": [
+        {
+            "...": "include(../../../entities/core/three-dimensional/crystal.json)"
+        },
+        {
+            "...": "include(../../../entities/core/two-dimensional/vacuum.json)"
+        }
+    ],
+    "method": "add"
+} 

package/example/materials_category_components/operations/core/combinations/stack.json

@@ -0,0 +1,11 @@
+{
+    "stack_components": [
+        {
+            "...": "include(../../../entities/core/three-dimensional/crystal.json)"
+        },
+        {
+            "...": "include(../../../entities/core/two-dimensional/vacuum.json)"
+        }
+    ],
+    "direction": "z"
+} 

package/example/materials_category_components/operations/core/combinations/stack_component.json

@@ -0,0 +1,3 @@
+{
+    "...": "include(../../../entities/core/three-dimensional/crystal.json)"
+} 

package/example/materials_category_components/operations/core/modifications/repeat.json

@@ -0,0 +1,13 @@
+{
+    "matrix": [
+        [ 2,
+            0,
+            0 ],
+        [ 0,
+            2,
+            0 ],
+        [ 0,
+            0,
+            2 ]
+    ]
+}

package/example/materials_category_components/operations/core/modifications/strain.json

@@ -0,0 +1,7 @@
+{
+    "matrix": [
+        [1.02, 0.0, 0.0],
+        [0.0, 1.02, 0.0],
+        [0.0, 0.0, 0.98]
+    ]
+} 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/esse",
-    "version": "2025.5.17-2",
+    "version": "2025.6.14-0",
     "description": "Mat3ra's Excellent Source of Schemas and Examples (ESSE) for Digital Materials R&D",
     "scripts": {
         "transpile": "tsc -p tsconfig-transpile.json",

package/schema/apse/materials/builders/slab/pymatgen/parameters.json

@@ -12,15 +12,15 @@
                 "number"
             ],
             "minimum": 0,
-            "default": 1
+            "default": 0
         },
         "in_unit_planes": {
-            "description": "Whether to cleave in unit planes",
+            "description": "Whether to use unit planes for the vacuum and slab size",
             "type": "boolean",
             "default": true
         },
         "reorient_lattice": {
-            "description": "Whether to reorient the lattice",
+            "description": "Whether to reorient the lattice to have c vector along the z-axis",
             "type": "boolean",
             "default": true
         },

package/schema/core/primitive/array_of_3_integers.json

@@ -0,0 +1,11 @@
+{
+    "$id": "core/primitive/array-of-3-integers",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "array of 3 integer elements schema",
+    "type": "array",
+    "items": {
+        "type": "integer"
+    },
+    "minItems": 3,
+    "maxItems": 3
+} 

package/schema/core/reusable/coordinate_conditions/index.json

@@ -0,0 +1,11 @@
+{
+    "$id": "core/reusable/coordinate-conditions",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Coordinate Conditions Schema",
+    "description": "Combined schema for all coordinate condition types",
+    "oneOf": [
+        {
+            "$ref": "box.json"
+        }
+    ]
+} 

package/schema/materials_category/manifest.yaml

@@ -0,0 +1,268 @@
+# This is a temporary manifest file to describe the folder structure of materials-related content.
+# The following notation is used:
+#
+# `<filename>:` - any key can be a schema file or a directory
+# ` - key` - array components represent the keys inside a schema file content
+# ` - key?` - optional file content key
+# ` - key = ` - file content assignment to types of values
+# `[value1, value2]` - list of values "value1 or value2"
+# `[value, ...]` - list of multiple values "value"
+# `( x | y | z ){1,2}` - a set of values "1 or 2 of any of the three"
+#
+
+materials_category_components:
+  entities:
+    core:
+      three-dimensional:
+        crystal:
+        void:
+          # can be placed into a crystal centered around specified crystal_site, all atoms inside are removed
+          - center_coordinate
+          - shape
+      two-dimensional:
+        vacuum:
+          # is applied along the specified direction, adds vacuum "slab", breaks periodicity in that direction, lowers dimensionality
+          - direction
+          - size
+        termination:
+          - stoichiometry
+          - symmetry
+        miller_indices: [ h, k, l ]
+      one-dimensional:
+      zero-dimensional:
+        crystal_site:
+          # created by reference to some crystal, can be populated with atom, vacancy, void, can be merged with a crystal of the same lattice
+          - coordinate
+          - id? # site id in the host crystal
+        atom:
+          - chemical_element
+    auxiliary: # auxiliary entities, not used in the main material creation
+      three-dimensional:
+        supercell_matrix_3d:
+      two-dimensional:
+        miller_indices: [ h, k ] # 2D Miller indices
+      one-dimensional:
+        edge_direction: [ u, v ] # 2D Miller indices for 1D structures
+      zero-dimensional:
+        shape_function: f(x, y, z) # function that defines the shape of the object
+    reusable:
+      three-dimensional:
+        supercell:
+          # created from a crystal, can be used to create a supercell of any size
+          - crystal = material
+          - matrix = integer_matrix # matrix of integers, defines the size of the supercell
+        strained_uniform:
+          - crystal = ref:/primitive/base/crystal
+          - strain_percentage
+        strained_non-uniform:
+          - crystal = ref:/primitive/base/crystal
+          - strain_matrix
+
+      two-dimensional:
+        crystal_lattice_planes:
+          - crystal = material
+          - miller_indices = ref:/primitive/two-dimensional/miller_indices
+          - use_conventional_cell = bool # if true, the conventional cell is used to generate the planes
+        atomic_layers_unique:
+          # Generated from the crystal_lattice_planes, together would form a full periodic structure
+          - crystal = material
+          - miller_indices = ref:/primitive/two-dimensional/miller_indices
+          - terminations = [ termination, ... ] # all possible terminations for that orientation
+        atomic_layers_unique_repeated:
+          # atomic_layers_unique with an integer number of repetitions, form a full periodic structure with top layer specified by the termination
+          - crystal = material
+          - miller_indices = ref:/primitive/two-dimensional/miller_indices
+          - termination_top = termination
+          - number_of_repetitions = int # number of repetitions of the unique atomic layers, they are shifted according to the termination
+        atomic_layers:
+          # Created from atomic_layers_unique in any order defined by terminations
+          - crystal = material
+          - miller_indices = ref:/primitive/two-dimensional/miller_indices
+          - terminations = [ termination, ... ] # any number of any terminations in the order for the layers to occur
+        atomic_layer:
+          # Created from atomic_layers_unique with a single termination
+          - crystal = material
+          - miller_indices = ref:/primitive/two-dimensional/miller_indices
+          - termination = termination
+        slab_unit_cell:
+          - stack_components = [ atomic_layers, vacuum ]
+          - direction = "z"
+      one-dimensional:
+        ribbon_section:
+          - monolayer = ref:/.../monolayer
+          - edge_direction = [ u, v ] # 2D MI, works for ANY 2‑D lattice (unlike zigzag and armchair)
+          - width = int # number of unit cells
+        ribbon_section_hex:
+          - monolayer = ref:/.../monolayer
+          - edge_type = ("zigzag" | "armchair"){1}
+          - width = int | float # number of unit cells, can be in 0.5 increments
+          - length = int | float # number of unit cells
+        wire_section:
+          # we created a supercell, cut the shape
+          - shape = function(x, y, z) # in angstroms, supercell inferred to fit
+          - orientation = [h, k, l]
+      zero-dimensional:
+        nanoparticle:
+          # we created a supercell, cut the shape and added vacuum on all sides
+          - supercell = ref:/.../supercell
+          - shape = function(x, y, z)
+          - orientation = [h, k, l] # to align specific plane perpendicular the z-axis
+
+  operations:
+    core:
+      modifications:
+        strain:
+          # can be applied to a crystal, modifies the lattice parameters and preserves basis in crystal coordinates
+          - matrix
+        repeat:
+          - integer_matrix
+        perturb:
+          # changes coordinates of atoms by applying the function, intended for local displacements
+          - function = ∂r -> f(x,y,z)
+          - is_isometric = bool  # distance preservation -- isometric transformation -- only makes sense in 2D and 1D thin structures
+        fold:
+          # maps 2D flat plane to a curved surface in 3D space
+          - function = f(x, y) -> f(x, y, z)
+          - is_isometric = bool
+      combinations:
+        stack_component: (material | vacuum)
+        stack:
+          - stack_components = [ stack_component, ... ] # vacuum is added between to add a gap/distance between components
+          - direction = ("x" | "y" | "z")|("-x" | "-y" | "-z"){1} # sign indicates the order of the stacking
+        merge_component: ( material | vacuum | crystal_site )
+        merge:
+          - merge_structures = [ material ]
+          - method = ("add" | "replace" | "yield" | "smart"){1}
+
+material_categories:
+  pristine_structures:
+    three-dimensional:
+      ideal_crystal: ref:/primitive/base/crystal
+
+    two-dimensional:
+      monolayer:
+        - stack_components = [ (atomic_layer | atomic_layers), vacuum ]
+        - direction = "z"
+      slab:
+        - stack_components = [ atomic_layers, vacuum ]
+        - direction = "z"
+        - supercell_xy?
+      slab_with_reconstruction:
+        - slab = ref:/pristine_structures/two-dimensional/slab
+        - has_reconstruction = bool
+        - reconstruction_type? # Enum that applies an algorithm
+        - reconstruction_function? # Function that changes coordinates of atoms
+
+    one-dimensional:
+      nanotape:
+        # we created a supercell from monolayer, cut the shape and added vacuum on one side
+        - stack_components = [ ribbon_section, vacuum ]
+        - direction = (x | y){1}
+      nanowire:
+        # we created a supercell, cut the shape and added vacuum on two sides
+        - stack_components = [ wire_section, vacuum ]
+        - direction = (x | y | z){2} # 2 sides
+
+    zero-dimensional:
+      nanoparticle_with_vacuum:
+        - stack_components = [ nanoparticle, vacuum ]
+        - direction = (x | y | z){3} # all sides vacuum
+      nanoribbon:
+        # we created a monolayer supercell, cut the shape and added vacuum on all sides
+        - stack_components =  [ ribbon_section, vacuum ]
+        - direction = (x | y | z){2} # 2 sides
+      nanoribbon_hex:
+        - stack_components = [ ribbon_section_hex, vacuum ]
+        - direction = (x | y | z){2} # 2 sides
+
+  compound_pristine_structures:
+    two-dimensional:
+      multi-layer:
+        - crystal = ref:/primitive/base/crystal
+        # In the code properties below can be supplied externally or generated based on the above with a wizard
+        - stacking_order? = ("natural" | "AB" | "ABC" | ...){1} # Natural by default, can be described as a ABC... configurations based on the symmetry
+      heterostack:
+        - stack_components = [ slab, vacuum, ... ]
+        - direction = (x | y | z){1}
+      interfaces:
+        with_no_vacuum:
+          - stack_components = [ (slab | monolayer), (slab | monolayer)]
+          - direction = "z"
+        with_vacuum:
+          - stack_components = [ (slab | monolayer), (slab | monolayer), vacuum ]
+          - direction = "z"
+        with_gap_and_vacuum:
+          - stack_components = [ (slab | monolayer), (slab | monolayer), vacuum ]
+          - direction = "z"
+          - gap = float # use precise distance between top and bottom layers of the slabs
+        commensurate_slabs:
+          - stack_components = [ slab, slab, vacuum ]
+          - direction = "z"
+        commensurate_monolayers_along_x:
+          - stack_components = [ monolayer, monolayer, vacuum ]
+          - direction = "x"
+        twisted_nanoribbons:
+          - stack_components = [ nanoribbon, nanoribbon, vacuum ]
+          - direction = "z"
+          - twist_angle = float
+
+  defective_structures:
+    three-dimensional:
+      amorphous:
+        - crystal = ref:/primitive/base/crystal
+        - function = f(x, y, z) # annealing function
+    two-dimensional:
+      adatom:
+        - merged_structures = [ slab, crystal_site(atom) ]
+      island:
+        - merged_structures = [ slab, nanoparticle ]
+      terrace:
+        - added_layers
+        - cut (plane + pivot_point)
+        - merged_structures = [ slab, nanotape ]
+        - is_symmetric = bool
+        - is_periodic = bool
+      grain_boundary_planar:
+        - stack_components = [ slab, slab ]
+        - direction = (x | y | z){1}
+      grain_boundary_planar_with_vacuum:
+        # inherits grain_boundary_planar and slab
+        - stack_components = [ slab, slab, vacuum ]
+        - direction = "z"
+        - number_of_layers
+        - terminations = [ termination, termination ]
+    one-dimensional:
+      grain_boundary_line:
+        # A GB between two slabs or monolayers, vacuum in z should be already present
+        - stack_components = [ (slab | monolayer), (slab | monolayer) ]
+        - direction = (x | y | z){1}
+        - angle = float # angle between the two phases
+    zero-dimensional:
+      vacancy:
+        - merged_structures = [ crystal, crystal_site(vacancy) ]
+        - method = "replace"
+      substitution:
+        - merged_structures = [ crystal, crystal_site(atom) ]
+        - method = "replace"
+      interstitial:
+        - merged_structures = [ crystal, crystal_site(atom) ]
+        - method = "add"
+      defect_pair:
+        - merged_structures = [ (vacancy | substitution | interstitial), (vacancy | substitution | interstitial) ]
+        - method = "replace
+
+  processed_structures:
+    two-dimensional:
+      passivated_surface_2d:
+        # we should configure the condition for exposed atoms and then the bond vector for passivation
+        - merged_structures = [ slab, crystal_site(atom|particle) ]
+        - bond_length = float # can be a map of bond lengths for different elements
+    one-dimensional:
+      passivated_edge_1d:
+        - merged_structures = [ nanotape, crystal_site(atom|particle) ]
+        - bond_length = float # can be a map of bond lengths for different elements
+    zero-dimensional:
+      passivated_edge_0d:
+        # Passivation of a particle or a nanoribbon
+        - merged_structures = [ nanoparticle, crystal_site(atom|particle) ]
+        - bond_length = float

package/schema/materials_category/pristine_structures/three-dimensional/ideal_crystal.json

@@ -0,0 +1,11 @@
+{
+    "$id": "materials-category/pristine-structures/three-dimensional/ideal-crystal",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Ideal Crystal Schema",
+    "description": "An ideal, perfect crystal structure",
+    "allOf": [
+        {
+            "$ref": "../../../materials_category_components/entities/core/three-dimensional/crystal.json"
+        }
+    ]
+}

package/schema/materials_category/pristine_structures/two-dimensional/slab.json

@@ -0,0 +1,17 @@
+{
+    "$id": "materials-category/pristine-structures/two-dimensional/slab",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Slab Configuration Schema",
+    "description": "A slab structure configuration that can optionally include a supercell transformation in the xy plane",
+    "allOf": [
+        {
+            "$ref": "../../../materials_category_components/entities/reusable/two-dimensional/slab_unit_cell.json"
+        }
+    ],
+    "properties": {
+        "xy_supercell_matrix": {
+            "$ref": "../../../materials_category_components/entities/auxiliary/two-dimensional/supercell_matrix_2d.json",
+            "description": "Optional 2x2 transformation matrix for creating a supercell in the xy plane"
+        }
+    }
+} 

package/schema/{material/reusable/supercell → materials_category_components/entities/auxiliary/three-dimensional}/supercell_matrix_3d.json

@@ -1,16 +1,11 @@
 {
-    "$id": "material/reusable/supercell/supercell-matrix-3d",
+    "$id": "materials-category-components/entities/auxiliary/three-dimensional/supercell-matrix-3d",
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "Supercell Matrix 3D Schema",
     "description": "3x3 matrix of integers for transforming a unit cell into a supercell",
     "type": "array",
     "items": {
-        "type": "array",
-        "items": {
-            "type": "integer"
-        },
-        "minItems": 3,
-        "maxItems": 3
+        "$ref": "../../../../core/primitive/array_of_3_integers.json"
     },
     "minItems": 3,
     "maxItems": 3,

package/schema/materials_category_components/entities/auxiliary/two-dimensional/miller_indices.json

@@ -0,0 +1,16 @@
+{
+    "$id": "materials-category-components/entities/auxiliary/two-dimensional/miller-indices",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Miller Indices Schema",
+    "description": "Miller indices [h, k, l] defining crystallographic planes",
+    "allOf": [
+        {
+            "$ref": "../../../../core/primitive/array_of_3_integers.json"
+        }
+    ],
+    "default": [
+        0,
+        0,
+        1
+    ]
+}

package/schema/{material/reusable/supercell → materials_category_components/entities/auxiliary/two-dimensional}/supercell_matrix_2d.json

@@ -1,5 +1,5 @@
 {
-    "$id": "material/reusable/supercell/supercell-matrix-2d",
+    "$id": "materials-category-components/entities/auxiliary/two-dimensional/supercell-matrix-2d",
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "Supercell Matrix 2D Schema",
     "description": "Supercell matrix for xy plane transformations",

package/schema/{material/reusable/slab → materials_category_components/entities/auxiliary/two-dimensional}/termination.json

@@ -1,5 +1,5 @@
 {
-    "$id": "material/reusable/slab/termination",
+    "$id": "materials-category-components/entities/auxiliary/two-dimensional/termination",
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "Termination Schema",
     "description": "Defines a specific termination of a slab",
@@ -15,11 +15,11 @@
             "type": "string",
             "anyOf": [
                 {
-                    "$ref": "../../../definitions/chemical_elements.json#/periodic_table"
+                    "$ref": "../../../../definitions/chemical_elements.json#/periodic_table"
                 },
                 {
                     "type": "string",
-                    "pattern": "^[A-Z][a-z]?([A-Z][a-z]?)*$"
+                    "pattern": "^([A-Z][a-z]?[0-9]*)+$"
                 }
             ]
         },

package/schema/materials_category_components/entities/auxiliary/zero-dimensional/crystal_site.json

@@ -0,0 +1,15 @@
+{
+    "$id": "materials-category-components/entities/auxiliary/zero-dimensional/crystal-site",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Crystal Site Schema",
+    "description": "A site in a crystal that can be populated with an atom, vacancy, or void. Should be place in a target basis.",
+    "type": "object",
+    "properties": {
+        "coordinate": {
+            "$ref": "../../../../core/abstract/coordinate_3d.json"
+        }
+    },
+    "required": [
+        "coordinate"
+    ]
+}

package/schema/materials_category_components/entities/core/three-dimensional/crystal.json

@@ -0,0 +1,11 @@
+{
+    "$id": "materials-category-components/entities/core/three-dimensional/crystal",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Crystal Schema",
+    "description": "A crystal structure, referencing the base material schema",
+    "allOf": [
+        {
+            "$ref": "../../../../material.json"
+        }
+    ]
+} 

package/schema/materials_category_components/entities/core/three-dimensional/void.json

@@ -0,0 +1,19 @@
+{
+    "$id": "materials-category-components/entities/core/three-dimensional/void",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Void Schema",
+    "description": "A void that can be placed into a crystal, removing all atoms inside",
+    "type": "object",
+    "properties": {
+        "center_coordinate": {
+            "$ref": "../../../../core/abstract/coordinate_3d.json"
+        },
+        "shape": {
+            "$ref": "../../../../core/reusable/coordinate_conditions/index.json"
+        }
+    },
+    "required": [
+        "center_coordinate",
+        "shape"
+    ]
+}