@mat3ra/esse 2025.5.17-0 → 2025.5.17-2

package/example/core/reusable/coordinate_conditions/box.json

@@ -0,0 +1,13 @@
+{
+    "shape": "box",
+    "min_coordinate": [
+        0.0,
+        0.0,
+        0.0
+    ],
+    "max_coordinate": [
+        0.5,
+        0.5,
+        0.5
+    ]
+}

package/example/material/reusable/slab_configuration_with_termination.json

@@ -0,0 +1,8 @@
+{
+    "slab_configuration": {
+        "...": "include(../../materials_category/single_material/two_dimensional/slab/configuration.json)"
+    },
+    "termination": {
+        "...": "include(./slab/termination.json)"
+    }
+}

package/example/material/reusable/supercell/supercell_matrix_3d.json

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

package/example/materials_category/defects/by_host/two-dimensional/{configuration.json → point/configuration.json}

@@ -1,5 +1,5 @@
 {
-    "...": "include(../../configuration.json)",
+    "...": "include(../../../configuration.json)",
     "position_on_surface": [
         0.25,
         0.25

package/example/materials_category/defects/one-dimensional/terrace/configuration.json

@@ -0,0 +1,19 @@
+{
+    "host": {
+        "...": "include(../../../../material.json)"
+    },
+    "number_of_added_layers": 3,
+    "defect_type": "terrace",
+    "cut_direction": [
+        1,
+        0,
+        0
+    ],
+    "pivot_coordinate": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "use_cartesian_coordinates": false,
+    "rotate_to_match_pbc": true
+}

package/example/materials_category/defects/two-dimensional/grain_boundary_plane/configuration.json

@@ -0,0 +1,21 @@
+{
+    "stack_slab_configurations": [
+        {
+            "...": "include(../../../../material/reusable/slab_configuration_with_termination.json)",
+            "stack_component": "phase1",
+            "distance_to_next_slab": 3.0
+        },
+        {
+            "...": "include(../../../../material/reusable/slab_configuration_with_termination.json)",
+            "stack_component": "phase2",
+            "distance_to_next_slab": 3.0
+        }
+    ],
+    "stacking_direction": "x",
+    "slab_configuration": {
+        "...": "include(../../../single_material/two_dimensional/slab/configuration.json)"
+    },
+    "termination": {
+        "...": "include(../../../../material/reusable/slab/termination.json)"
+    }
+}

package/example/materials_category/defects/zero-dimensional/complex/pair/configuration.json

@@ -0,0 +1,9 @@
+{
+    "...": "include(../../../configuration.json)",
+    "point_defect_configuration_1": {
+        "...": "include(../../point/configuration.json)"
+    },
+    "point_defect_configuration_2": {
+        "...": "include(../../point/configuration.json)"
+    }
+}

package/example/materials_category/defects/zero-dimensional/point/configuration.json

@@ -7,5 +7,5 @@
         0.25
     ],
     "use_cartesian_coordinates": false,
-    "placement_method": "crystal_site"
+    "placement_method": "coordinate"
 }

package/example/materials_category/defects/zero-dimensional/point/interstitial/configuration.json

@@ -0,0 +1,14 @@
+{
+    "type": "interstitial",
+    "isExternal": true,
+    "chemical_element": "P",
+    "coordinate": [
+        0,
+        0,
+        0
+    ],
+    "use_cartesian_coordinates": false,
+    "host": {
+        "...": "include(../../../../../material.json)"
+    }
+}

package/example/materials_category/defects/zero-dimensional/point/substitution/configuration.json

@@ -0,0 +1,13 @@
+{
+    "type": "substitution",
+    "chemical_element": "C",
+    "coordinate": [
+        0,
+        0,
+        0
+    ],
+    "use_cartesian_coordinates": false,
+    "host": {
+        "...": "include(../../../../../material.json)"
+    }
+}

package/example/materials_category/defects/zero-dimensional/point/vacancy/configuration.json

@@ -0,0 +1,12 @@
+{
+    "type": "vacancy",
+    "coordinate": [
+        0,
+        0,
+        0
+    ],
+    "use_cartesian_coordinates": false,
+    "host": {
+        "...": "include(../../../../../material.json)"
+    }
+}

package/package.json

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

package/schema/core/primitive/axis_3d_names_enum.json

@@ -0,0 +1,12 @@
+{
+    "$id": "core/reusable/axis-enum",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Axis Enum",
+    "type": "string",
+    "description": "Enum for axis types",
+    "enum": [
+        "x",
+        "y",
+        "z"
+    ]
+}

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

@@ -0,0 +1,15 @@
+{
+    "$id": "core/reusable/coordinate-conditions/base",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Coordinate Condition Schema",
+    "description": "Base interface for coordinate shape filters",
+    "type": "object",
+    "properties": {
+        "shape": {
+            "$ref": "enum.json"
+        }
+    },
+    "required": [
+        "shape"
+    ]
+}

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

@@ -0,0 +1,25 @@
+{
+    "$id": "core/reusable/coordinate-conditions/box",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Box Coordinate Condition Schema",
+    "allOf": [
+        {
+            "$ref": "base.json"
+        }
+    ],
+    "properties": {
+        "shape": {
+            "const": "box"
+        },
+        "min_coordinate": {
+            "$ref": "../../abstract/coordinate_3d.json"
+        },
+        "max_coordinate": {
+            "$ref": "../../abstract/coordinate_3d.json"
+        }
+    },
+    "required": [
+        "min_coordinate",
+        "max_coordinate"
+    ]
+}

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

@@ -0,0 +1,13 @@
+{
+    "$id": "core/reusable/coordinate-conditions/enum",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Coordinate Shape Enum",
+    "type": "string",
+    "enum": [
+        "cylinder",
+        "sphere",
+        "box",
+        "triangular_prism",
+        "plane"
+    ]
+}

package/schema/material/reusable/slab_configuration_with_termination.json

@@ -0,0 +1,19 @@
+{
+    "$id": "material/reusable/slab-configuration-with-termination",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Slab Configuration With Termination Schema",
+    "description": "Configuration for a slab with termination",
+    "type": "object",
+    "properties": {
+        "slab_configuration": {
+            "$ref": "../../materials_category/single_material/two_dimensional/slab/configuration.json"
+        },
+        "termination": {
+            "$ref": "slab/termination.json"
+        }
+    },
+    "required": [
+        "slab_configuration",
+        "termination"
+    ]
+}

package/schema/material/reusable/stack/slab_in_stack.json

@@ -0,0 +1,26 @@
+{
+    "$id": "material/reusable/stack/slab-in-stack",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Slab in Stack Configuration Schema",
+    "description": "Configuration for a slab in a stack with termination",
+    "allOf": [
+        {
+            "$ref": "../slab_configuration_with_termination.json"
+        }
+    ],
+    "properties": {
+        "stack_component": {
+            "type": "string",
+            "description": "Component of the stack (e.g., slab1, slab2)"
+        },
+        "distance_to_next_slab": {
+            "type": "number",
+            "description": "Distance to the next slab in the stack, in Angstroms",
+            "default": 3.0
+        }
+    },
+    "required": [
+        "slab_configuration",
+        "termination"
+    ]
+}

package/schema/material/reusable/stack/stack_of_slabs.json

@@ -0,0 +1,31 @@
+{
+    "$id": "material/reusable/stack/stack-of-slabs",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Stack of Slabs Configuration Schema",
+    "description": "Configuration for a stack of multiple slabs.",
+    "properties": {
+        "stack_slab_configurations": {
+            "type": "array",
+            "description": "List of slab configurations for the slabs in the stack",
+            "items": {
+                "$ref": "./slab_in_stack.json"
+            },
+            "minItems": 2
+        },
+        "stacking_direction": {
+            "type": "string",
+            "description": "The axis along which the slabs are stacked",
+            "allOf": [
+                {
+                    "$ref": "../../../core/primitive/axis_3d_names_enum.json"
+                }
+            ],
+            "default": "z"
+        }
+    },
+    "required": [
+        "stack_slab_configurations"
+    ]
+}
+
+

package/schema/material/reusable/stack/stack_of_two_slabs.json

@@ -0,0 +1,17 @@
+{
+    "$id": "material/reusable/stack/stack-of-two-slabs",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Stack Of Two Slabs Configuration Schema",
+    "description": "Configuration for two slabs stacked on top of each other.",
+    "allOf": [
+        {
+            "$ref": "./stack_of_slabs.json"
+        }
+    ],
+    "properties": {
+        "stack_slab_configurations": {
+            "minItems": 2,
+            "maxItems": 2
+        }
+    }
+}

package/schema/material/reusable/{supercell_matrix_2d.json → supercell/supercell_matrix_2d.json}

@@ -1,5 +1,5 @@
 {
-    "$id": "material/reusable/supercell-matrix-2d",
+    "$id": "material/reusable/supercell/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/{supercell_matrix_3d.json → supercell/supercell_matrix_3d.json}

@@ -1,5 +1,5 @@
 {
-    "$id": "material/reusable/supercell-matrix-3d",
+    "$id": "material/reusable/supercell/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",

package/schema/materials_category/defects/by_host/two-dimensional/layered/configuration.json

@@ -0,0 +1,16 @@
+{
+    "$id": "materials-category/defects/by-host/two-dimensional/layered/configuration",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Two Dimensional Layered Defect Configuration Schema",
+    "description": "Two Dimensional Layered Defect Configuration Schema",
+    "allOf": [
+        {
+            "$ref": "../../../configuration.json"
+        }
+    ],
+    "properties": {
+        "number_of_added_layers": {
+            "$ref": "../../../../../material/reusable/slab/number_of_layers.json"
+        }
+    }
+}

package/schema/materials_category/defects/by_host/two-dimensional/{configuration.json → point/configuration.json}

@@ -1,17 +1,17 @@
 {
-    "$id": "materials-category/defects/by-host/two-dimensional/configuration",
+    "$id": "materials-category/defects/by-host/two-dimensional/point/configuration",
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "Two Dimensional Defect Configuration Schema",
     "description": "Configuration for defects in two-dimensional hosts",
     "allOf": [
         {
-            "$ref": "../../../defects/configuration.json"
+            "$ref": "../../../../defects/configuration.json"
         }
     ],
     "properties": {
         "position_on_surface": {
             "description": "Position on the surface in 2D crystal coordinates",
-            "$ref": "../../../../core/abstract/coordinate_2d.json"
+            "$ref": "../../../../../core/abstract/coordinate_2d.json"
         },
         "distance_z": {
             "description": "Distance from the surface in Angstroms",

package/schema/materials_category/defects/configuration.json

@@ -17,6 +17,11 @@
                 }
             ]
         },
+        "use_cartesian_coordinates": {
+            "description": "Whether to use Cartesian coordinates",
+            "type": "boolean",
+            "default": false
+        },
         "isExternal": {
             "description": "Whether the defect is external to the host material",
             "type": "boolean",

package/schema/materials_category/defects/one-dimensional/terrace/configuration.json

@@ -0,0 +1,44 @@
+{
+    "$id": "materials-category/defects/one-dimensional/terrace/configuration",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Terrace Configuration Schema",
+    "description": "Configuration for creating a terrace",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "../../by_host/two-dimensional/layered/configuration.json"
+        }
+    ],
+    "properties": {
+        "cut_direction": {
+            "allOf": [
+                {
+                    "$ref": "../../../../material/reusable/slab/miller_indices.json"
+                }
+            ],
+            "default": [
+                1,
+                0,
+                0
+            ]
+        },
+        "pivot_coordinate": {
+            "description": "Pivot coordinate where the cut plane passes through",
+            "allOf": [
+                {
+                    "$ref": "../../../../core/abstract/coordinate_3d.json"
+                }
+            ],
+            "default": [
+                0.5,
+                0.5,
+                0.5
+            ]
+        },
+        "rotate_to_match_pbc": {
+            "description": "Whether to rotate the slab to match periodic boundary conditions",
+            "type": "boolean",
+            "default": true
+        }
+    }
+}

package/schema/materials_category/defects/two-dimensional/grain_boundary_plane/configuration.json

@@ -0,0 +1,20 @@
+{
+    "$id": "materials-category/defects/two-dimensional/grain-boundary-plane/configuration",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Grain Boundary Plane Configuration Schema",
+    "description": "Configuration for a grain boundary between two phases with different surfaces facing each other",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "../../../../material/reusable/slab_configuration_with_termination.json"
+        },
+        {
+            "$ref": "../../../../material/reusable/stack/stack_of_two_slabs.json"
+        }
+    ],
+    "properties": {
+        "stacking_direction": {
+            "default": "x"
+        }
+    }
+}

package/schema/materials_category/defects/two-dimensional/island/condition.json

@@ -0,0 +1,9 @@
+{
+    "$id": "materials-category/defects/two-dimensional/island/condition.json",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "anyOf": [
+        {
+            "$ref": "../../../../core/reusable/coordinate_conditions/box.json"
+        }
+    ]
+}

package/schema/materials_category/defects/two-dimensional/island/configuration.json

@@ -0,0 +1,18 @@
+{
+    "$id": "materials-category/defects/two-dimensional/island/configuration",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Island Slab Defect Configuration Schema",
+    "description": "Configuration for an island defect on a slab surface",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "../../by_host/two-dimensional/layered/configuration.json"
+        }
+    ],
+    "properties": {
+        "condition": {
+            "description": "Coordinate condition for the island defect",
+            "$ref": "./condition.json"
+        }
+    }
+}

package/schema/materials_category/defects/zero-dimensional/complex/{pair.json → pair/configuration.json}

@@ -1,20 +1,20 @@
 {
-    "$id": "materials-category/defects/zero-dimensional/complex/pair",
+    "$id": "materials-category/defects/zero-dimensional/complex/pair/configuration",
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "Pair Defect Schema",
     "description": "Schema for pair defects, which are a type of zero-dimensional defect",
     "type": "object",
     "allOf": [
         {
-            "$ref": "../../configuration.json"
+            "$ref": "../../../configuration.json"
         }
     ],
     "properties": {
         "point_defect_configuration_1": {
-            "$ref": "../point/configuration.json"
+            "$ref": "../../point/configuration.json"
         },
         "point_defect_configuration_2": {
-            "$ref": "../point/configuration.json"
+            "$ref": "../../point/configuration.json"
         }
     }
 }

package/schema/materials_category/multi-material/interfaces/configuration.json

@@ -0,0 +1,12 @@
+{
+    "$id": "materials-category/multi-material/interfaces/configuration",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Interface Configuration Schema",
+    "description": "Configuration for an interface between two materials",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "../../../material/reusable/stack/stack_of_two_slabs.json"
+        }
+    ]
+}

package/schema/materials_category/single_material/two_dimensional/slab/configuration.json

@@ -18,25 +18,19 @@
             "$ref": "../../../../material/reusable/slab/vacuum.json"
         },
         "xy_supercell_matrix": {
-            "$ref": "../../../../material/reusable/supercell_matrix_2d.json"
+            "$ref": "../../../../material/reusable/supercell/supercell_matrix_2d.json"
         },
         "use_conventional_cell": {
             "title": "Use Conventional Cell",
-            "description": "Whether to use conventional cell",
+            "description": "Whether to use conventional cell when generating the slab.",
             "type": "boolean",
             "default": true
         },
         "use_orthogonal_z": {
             "title": "Use Orthogonal Z",
-            "description": "Whether to make z-axis orthogonal",
+            "description": "Whether to make vector c orthogonal to ab plane for the slab cell.",
             "type": "boolean",
-            "default": false
-        },
-        "make_primitive": {
-            "title": "Make Primitive",
-            "description": "Whether to make the slab primitive",
-            "type": "boolean",
-            "default": false
+            "default": true
         }
     }
 }

package/src/js/json_include/index.ts

@@ -64,6 +64,7 @@ export class JSONInclude {
      */
     parseIncludeStatements(filePath: string) {
         const data: CacheObject[] = safeParseJSON(fs.readFileSync(filePath, "utf8"));
+        console.log("Parsing file: ", filePath);
         if (OBJECT_ONLY && !isInstanceOf(data, "Object")) {
             throw new Error(
                 "The JSON file being included should always be a dict rather than a list",

package/example/material/reusable/supercell_matrix_3d.json

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