@mat3ra/made 2024.3.22-0

package/dist/tools/surface.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lattice_bravais_1 = require("../lattice/lattice_bravais");
+const math_1 = __importDefault(require("../math"));
+const supercell_1 = __importDefault(require("./supercell"));
+const MULT = math_1.default.multiply;
+const ADD = math_1.default.add;
+const DOT = math_1.default.product;
+const getMatrixInLeftHandedRepresentation = (matrix) => {
+    return math_1.default.det(matrix) < 0 ? MULT(matrix, -1) : matrix;
+};
+/**
+ * Helper function for extended GCD.
+ * Inspired by https://gitlab.com/ase/ase/blob/master/ase/build/general_surface.py
+ * @param {Number} a
+ * @param {Number} b
+ * @return {Array}
+ */
+function extGCD(a, b) {
+    if (b === 0)
+        return [1, 0];
+    if (math_1.default.mod(a, b) === 0)
+        return [0, 1];
+    const [x, y] = extGCD(b, math_1.default.mod(a, b));
+    return [y, x - y * math_1.default.floor(a, b)];
+}
+/**
+ * Generates a slab scaling matrix for the specified cell based on miller indices.
+ * Inspired by from https://gitlab.com/ase/ase/blob/master/ase/build/general_surface.py.
+ * @param cell {Cell}
+ * @param millerIndices {Number[]}
+ * @param tol {Number} Zero-value tolerance
+ * @return {Number[][]}
+ */
+function getMillerScalingMatrix(cell, millerIndices, tol = 1e-8) {
+    if (!millerIndices.reduce((a, b) => math_1.default.abs(a) + math_1.default.abs(b)))
+        throw new Error("Miller indices are zeros.");
+    let scalingMatrix;
+    const [h, k, l] = millerIndices;
+    const [h0, k0, l0] = millerIndices.map((i) => i === 0);
+    if ((h0 && k0) || (h0 && l0) || (k0 && l0)) {
+        // if any two indices are zero
+        if (!h0) {
+            scalingMatrix = [
+                [0, 1, 0],
+                [0, 0, 1],
+                [1, 0, 0],
+            ];
+        }
+        if (!k0) {
+            scalingMatrix = [
+                [0, 0, 1],
+                [1, 0, 0],
+                [0, 1, 0],
+            ];
+        }
+        if (!l0) {
+            scalingMatrix = [
+                [1, 0, 0],
+                [0, 1, 0],
+                [0, 0, 1],
+            ];
+        }
+    }
+    else {
+        const [a1, a2, a3] = cell.vectorsAsArray;
+        // z1 = (k * a1 - h * a2)
+        // z2 = (l * a1 - h * a3)
+        // z3 = l * a2 - k * a3)
+        const z1 = ADD(MULT(k, a1), MULT(-1, h, a2));
+        const z2 = ADD(MULT(l, a1), MULT(-1, h, a3));
+        const z3 = ADD(MULT(l, a2), MULT(-1, k, a3));
+        let [p, q] = extGCD(k, l);
+        const k1 = DOT(ADD(MULT(p, z1), MULT(q, z2)), z3);
+        const k2 = DOT(ADD(MULT(l, z1), MULT(-1, k, z2)), z3);
+        if (math_1.default.abs(k2) > tol) {
+            const i = -parseInt(math_1.default.round(k1 / k2), 10);
+            [p, q] = [p + i * l, q - i * k];
+        }
+        const [a, b] = extGCD(p * k + q * l, h);
+        const c1 = [p * k + q * l, -p * h, -q * h];
+        const c2 = [0, l, -k].map((c) => math_1.default.trunc(c / math_1.default.gcd(l, k))); // floor division
+        const c3 = [b, a * p, a * q];
+        scalingMatrix = [c1, c2, c3];
+    }
+    return getMatrixInLeftHandedRepresentation(scalingMatrix);
+}
+/**
+ * Scale the surface cell in out-of-plane direction according to thickness
+ *  and construct the lateral supercell from vx/vy parameters.
+ * @param bulkCell {Cell}
+ * @param surfaceCell {Cell}
+ * @param outOfPlaneAxisIndex {Number} Index of the cell vector most collinear with the out-of-surface-plane vector
+ * @param thickness {Number} Surface (Slab) thickness in layers (Positive Integer).
+ * @param vx {Number} Size of lateral supercell along the direction of the first (x) cell vector (Positive Integer).
+ * @param vy {Number} Size of lateral supercell along the direction of the second (y) cell vector (Positive Integer).
+ * @return {Number[][]}
+ */
+function getDimensionsScalingMatrix(bulkCell, surfaceCell, outOfPlaneAxisIndex, thickness, vx, vy) {
+    const transformationMatrix = math_1.default.eye(3).toArray();
+    const vxIndex = outOfPlaneAxisIndex === 2 ? 0 : outOfPlaneAxisIndex + 1;
+    const vyIndex = vxIndex === 2 ? 0 : vxIndex + 1;
+    transformationMatrix[outOfPlaneAxisIndex] = MULT(thickness, transformationMatrix[outOfPlaneAxisIndex]);
+    transformationMatrix[vxIndex] = MULT(vx, transformationMatrix[vxIndex]);
+    transformationMatrix[vyIndex] = MULT(vy, transformationMatrix[vyIndex]);
+    return transformationMatrix;
+}
+/*
+ * Generate a config object for a surface based on a set of parameters.
+ * @param material {Material} The parent material (bulk) this surface is constructed from
+ * @param millerIndices {Number[]} Miller Indices that define the surface cleavage.
+ * @param numberOfLayers {Number} Surface (Slab) thickness in layers (Positive Integer).
+ * @param vx {Number} Size of lateral supercell along the direction of the first (x) cell vector (Positive Integer).
+ * @param vy {Number} Size of lateral supercell along the direction of the second (y) cell vector (Positive Integer).
+ * @return {Object}
+ */
+function generateConfig(material, millerIndices, numberOfLayers = 1, vx = 1, vy = 1) {
+    if (numberOfLayers < 1)
+        throw new Error("Made.tools.surface.generateConfig: number of layers < 1.");
+    const cell = material.Lattice.Cell;
+    const millerScalingMatrix = getMillerScalingMatrix(cell, millerIndices);
+    const millerSupercell = cell.cloneAndScaleByMatrix(millerScalingMatrix);
+    const millerPlanePseudoNormal = cell.convertPointToCartesian(millerIndices);
+    const outOfPlaneAxisIndex = millerSupercell.getMostCollinearVectorIndex(millerPlanePseudoNormal);
+    const dimensionsScalingMatrix = getDimensionsScalingMatrix(cell, millerSupercell, outOfPlaneAxisIndex, numberOfLayers, vx, vy);
+    const supercellMatrix = MULT(dimensionsScalingMatrix, millerScalingMatrix);
+    const supercell = millerSupercell.cloneAndScaleByMatrix(dimensionsScalingMatrix);
+    const newBasis = supercell_1.default.generateNewBasisWithinSupercell(material.Basis, cell, supercell, supercellMatrix);
+    const newLattice = lattice_bravais_1.LatticeBravais.fromVectors({
+        a: supercell.vector1,
+        b: supercell.vector2,
+        c: supercell.vector3,
+    });
+    return {
+        name: `${material.name} - slab ${JSON.stringify(millerIndices)}`,
+        basis: newBasis.toJSON(),
+        lattice: newLattice.toJSON(),
+        // extra parameter for use in creating vacuum etc.
+        outOfPlaneAxisIndex,
+    };
+}
+exports.default = {
+    generateConfig,
+};

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+import { AnyObject } from "@exabyte-io/code.js/dist/entity/in_memory";
+import { MaterialSchema } from "@mat3ra/esse/lib/js/types";
+export type MaterialJSON = MaterialSchema & AnyObject;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,89 @@
+{
+    "name": "@mat3ra/made",
+    "version": "2024.3.22-0",
+    "description": "MAterials DEsign library",
+    "scripts": {
+        "lint": "eslint --cache src/js tests/js && prettier --write src/js tests/js",
+        "lint:fix": "eslint --fix --cache src/js tests/js && prettier --write src/js tests/js",
+        "lint:staged": "lint-staged",
+        "postinstall": "npm run transpile",
+        "prepare": "husky install",
+        "prettier": "prettier --check src/js tests/js",
+        "test": "nyc --reporter=text mocha --recursive --bail tests/js",
+        "transpile": "tsc"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Exabyte-io/made.git"
+    },
+    "main": "dist/made.js",
+    "author": "Exabyte Inc.",
+    "bugs": {
+        "url": "https://github.com/Exabyte-io/made/issues"
+    },
+    "license": "Apache-2.0",
+    "homepage": "https://github.com/Exabyte-io/made",
+    "engines": {
+        "node": ">=0.14"
+    },
+    "devDependencies": {
+        "@babel/eslint-parser": "^7.16.3",
+        "@babel/plugin-proposal-class-properties": "^7.16.0",
+        "@babel/preset-env": "^7.16.4",
+        "@babel/preset-react": "^7.16.7",
+        "@babel/register": "^7.22.15",
+        "@babel/runtime-corejs3": "^7.16.8",
+        "@exabyte-io/code.js": "2024.2.29-0",
+        "@exabyte-io/eslint-config": "^2023.8.29-1",
+        "@mat3ra/esse": "2024.3.20-0",
+        "@mat3ra/tsconfig": "^2024.3.21-5",
+        "@types/crypto-js": "^4.2.2",
+        "@types/mathjs": "^3.21.1",
+        "@typescript-eslint/eslint-plugin": "^5.9.1",
+        "@typescript-eslint/parser": "^5.9.1",
+        "chai": "^4.3.4",
+        "chai-almost": "^1.0.1",
+        "eslint": "^7.32.0",
+        "eslint-config-airbnb": "^19.0.2",
+        "eslint-config-prettier": "^8.5.0",
+        "eslint-import-resolver-exports": "^1.0.0-beta.5",
+        "eslint-import-resolver-meteor": "^0.4.0",
+        "eslint-import-resolver-node": "^0.3.9",
+        "eslint-plugin-import": "^2.25.3",
+        "eslint-plugin-jsdoc": "^37.1.0",
+        "eslint-plugin-jsx-a11y": "^6.5.1",
+        "eslint-plugin-mui-path-imports": "0.0.15",
+        "eslint-plugin-prettier": "^4.2.1",
+        "eslint-plugin-react": "^7.30.0",
+        "eslint-plugin-simple-import-sort": "^7.0.0",
+        "husky": "^7.0.4",
+        "lint-staged": "^12.1.2",
+        "mocha": "10.3.0",
+        "prettier": "^2.5.1",
+        "nyc": "^15.1.0"
+    },
+    "dependencies": {
+        "@babel/core": "7.24.1",
+        "@exabyte-io/periodic-table.js": "2022.5.28-0",
+        "@types/chai": "^4.3.5",
+        "@types/mocha": "^10.0.1",
+        "@types/node": "^20.4.2",
+        "@types/underscore": "^1.11.6",
+        "@types/underscore.string": "^0.0.40",
+        "array-almost-equal": "^1.0.0",
+        "crypto-js": "4.2.0",
+        "lodash": "^4.17.*",
+        "mathjs": "12.4.1",
+        "typescript": "^4.5.5",
+        "underscore": "^1.8.3",
+        "underscore.string": "^3.3.4"
+    },
+    "peerDependencies": {
+        "@exabyte-io/code.js": "*",
+        "@mat3ra/esse": "*"
+    },
+    "lint-staged": {
+        "*.js": "eslint --cache --fix",
+        "*.{js,css}": "prettier --write"
+    }
+}

package/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "mat3ra-made"
+dynamic = ["version"]
+description = "MAterials DEfinitions and/or MAterials DEsign library."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {file = "LICENSE.md"}
+authors = [
+    {name = "Exabyte Inc.", email = "info@mat3ra.com"}
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Development Status :: 3 - Alpha",
+    "Topic :: Software Development",
+]
+dependencies = [
+    # add requirements here
+    "numpy"
+]
+
+[project.optional-dependencies]
+tests = [
+    "coverage[toml]>=5.3",
+    "pre-commit",
+    "black",
+    "ruff",
+    "isort",
+    "mypy",
+    "pip-tools"
+]
+all = ["mat3ra-made[tests]"]
+
+# Entrypoint scripts can be defined here, see examples below.
+[project.scripts]
+# my-script = "my_package.my_module:my_function"
+
+
+[build-system]
+requires = [
+    "setuptools>=42",
+    "setuptools-scm[toml]>=3.4"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+git_describe_command = "git describe --tags --long"
+
+[tool.setuptools.packages.find]
+where = ["src/py"]
+
+[tool.black]
+line-length = 120
+target-version = ['py38']
+# 'extend-exclude' excludes files or directories in addition to the defaults
+extend-exclude = '''
+(
+    examples\/.*\/.*\.py
+  | other\/.*\/.*\.(py|ipynb)
+)
+'''
+
+[tool.ruff]
+# Exclude a variety of commonly ignored directories.
+extend-exclude = [
+    "src/js"
+]
+line-length = 120
+target-version = "py38"
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+include_trailing_comma = true

package/src/js/abstract/array_with_ids.ts

@@ -0,0 +1,100 @@
+import _ from "underscore";
+
+import {
+    isObjectWithIdAndValue,
+    ObjectWithIdAndValue,
+    ScalarWithId,
+    ValueOrObject,
+} from "./scalar_with_id";
+
+type Predicate<T> = (o: T) => boolean;
+
+type MapFunction<T> = (value: T, index: number, array: T[]) => T;
+
+export function isArrayOfObjectsWithIdAndValue<T>(
+    valueOrObjects: ValueOrObject<T>[],
+): valueOrObjects is ObjectWithIdAndValue<T>[] {
+    return isObjectWithIdAndValue(valueOrObjects[0]);
+}
+
+/**
+ * Helper class representing an ArrayWithIds. Used to explicitly track values assigned to atoms, for example.
+ */
+export class ArrayWithIds<T> {
+    array: T[];
+
+    /**
+     * Create a an array with ids.
+     * @param {Array} array - Either regular array or ArrayWithIds (see @example above)
+     */
+    constructor(array: ObjectWithIdAndValue<T>[] | T[] = []) {
+        if (!_.isArray(array)) {
+            throw new Error("ArrayWithIds.constructor: pass array on initialization");
+        }
+        // if passed an array with ids as config, only store the values in array
+        if (isArrayOfObjectsWithIdAndValue<T>(array)) {
+            this.array = array.sort((a, b) => a.id - b.id).map((element) => element.value);
+        } else {
+            this.array = [...array];
+        }
+    }
+
+    /**
+     * Serialize class instance to JSON.
+     * @example [{"id" : 0, "value" : "Si" }, {"id" : 1, "value" : "Si" }]
+     */
+    toJSON(): ObjectWithIdAndValue<T>[] {
+        // from ["a", "b"] to [{id: 0, value: "a"}, {id: 1, value: "b"}]
+        return this.array.map((el, idx) => new ScalarWithId<T>(el, idx).toJSON());
+    }
+
+    /**
+     * Apply function fn to each element of the array and replace `array` with the result.
+     * @param fn - The function to be applied to each array element.
+     */
+    mapArrayInPlace(fn: MapFunction<T>) {
+        if (!_.isFunction(fn)) {
+            throw new Error("ArrayWithIds.mapArray: must pass function as argument");
+        }
+
+        this.array = this.array.map(fn);
+    }
+
+    getArrayElementByIndex(idx: number) {
+        return this.array[idx];
+    }
+
+    /**
+     * Get the index of the array element that passes the predicate.
+     * @param {Function} predicate - The function to be applied to each array element.
+     */
+    getArrayIndexByPredicate(predicate: Predicate<T>) {
+        return this.array.findIndex((el) => predicate(el));
+    }
+
+    /**
+     * Add an entity to array.
+     * @param el - The entity to be added to array. If Object with 'value' key, its value will be added.
+     */
+    addElement(el: ValueOrObject<T>) {
+        const value = isObjectWithIdAndValue(el) ? el.value : el;
+        if (el) this.array.push(value);
+    }
+
+    /**
+     * Remove an entity to array. Either by passing the entity, or the corresponding index.
+     * @param el - The entity to be added to array. If Object with 'value' key, its value will be added.
+     * @param idx - The entity to be added to array. If Object with 'value' key, its value will be added.
+     */
+    removeElement(el: ValueOrObject<T> | null, idx?: number) {
+        let _idx;
+        if (idx === undefined) {
+            _idx = this.array.findIndex((elm) => elm === el);
+        } else {
+            _idx = idx;
+        }
+        if (_idx !== undefined) {
+            this.array.splice(_idx, 1);
+        }
+    }
+}

package/src/js/abstract/scalar_with_id.ts

@@ -0,0 +1,53 @@
+import _ from "underscore";
+
+export interface ObjectWithIdAndValue<T> {
+    id: number;
+    value: T;
+}
+
+export type ValueOrObject<T> = ObjectWithIdAndValue<T> | T;
+
+export type ValueOrObjectArray<T> = ObjectWithIdAndValue<T>[] | T[];
+
+export function isObjectWithIdAndValue<T>(
+    valueOrObject: ValueOrObject<T>,
+): valueOrObject is ObjectWithIdAndValue<T> {
+    return Boolean(_.isObject(valueOrObject) && !_.isArray(valueOrObject) && valueOrObject.value);
+}
+
+/**
+ * Helper class representing a scalar with an associated id.
+ */
+export class ScalarWithId<T> {
+    id: number;
+
+    value: T;
+
+    /**
+     * Create a an array with ids.
+     * @param valueOrObject - a ScalarWithID, or any other type.
+     * @param id - numerical id (Integer).
+     */
+    constructor(valueOrObject: ValueOrObject<T>, id = 0) {
+        // if already passing a ScalarWithId => preserve original
+        if (isObjectWithIdAndValue(valueOrObject)) {
+            // NOTE - Arrays are Objects too
+            this.id = valueOrObject.id;
+            this.value = valueOrObject.value;
+        } else {
+            this.id = id;
+            this.value = valueOrObject;
+        }
+    }
+
+    /**
+     * Serialize class instance to JSON.
+     * @example {"id" : 0, "value" : "Si" }
+     */
+    toJSON(): ObjectWithIdAndValue<T> {
+        return {
+            id: this.id,
+            value: this.value,
+        };
+    }
+}