@mat3ra/made 2024.3.22-0

package/src/js/basis/types.ts

@@ -0,0 +1 @@
+export type Coordinate = [number, number, number];

package/src/js/cell/cell.ts

@@ -0,0 +1,109 @@
+import { math } from "@exabyte-io/code.js/dist/math";
+
+import { Coordinate } from "../basis/types";
+import constants from "../constants";
+import { Vector, VectorsAsArray } from "../lattice/types";
+
+const MATRIX = math.matrix;
+const MULT = math.multiply;
+const INV = math.inv;
+// @ts-ignore
+const MATRIX_MULT = (...args) => MULT(...args.map((x) => MATRIX(x))).toArray();
+
+type Point = Coordinate | math.Matrix | math.MathType;
+
+/*
+ * Cell represents a unit cell in geometrical form: 3x3 matrix where rows are cell vectors.
+ * Example: [[1, 0, 0], [0, 1, 0], [0, 0, 1]].
+ */
+export class Cell {
+    tolerance = 1;
+
+    vector1: Vector;
+
+    vector2: Vector;
+
+    vector3: Vector;
+
+    /**
+     * Create a cell.
+     * @param nestedArray {Number[][]} is an array of cell vectors in cartesian Angstrom units.
+     */
+    constructor(nestedArray: VectorsAsArray) {
+        [this.vector1, this.vector2, this.vector3] = nestedArray;
+    }
+
+    /**
+     * Get cell vectors as (a nested) array.
+     * @example [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+     */
+    get vectorsAsArray(): VectorsAsArray {
+        return [
+            this.vector1,
+            this.vector2,
+            this.vector3,
+            // assert that no near-zero artifacts are present (ie. 1.6 x 10^-16) before attempting inversion
+            // @param tolerance {Number} Maximum tolerance to small numbers, used to avoid artifacts on matrix inversion
+        ].map((v) => v.map((c) => (math.abs(c) < constants.tolerance.lengthAngstrom ? 0 : c))) as [
+            Vector,
+            Vector,
+            Vector,
+        ];
+    }
+
+    clone(): Cell {
+        return new (this.constructor as typeof Cell)(this.vectorsAsArray);
+    }
+
+    cloneAndScaleByMatrix(matrix: number[][]) {
+        const newCell = this.clone();
+        newCell.scaleByMatrix(matrix);
+        return newCell;
+    }
+
+    /**
+     * Convert a point (in crystal coordinates) to cartesian.
+     */
+    convertPointToCartesian(point: Point) {
+        return MULT(point, this.vectorsAsArray);
+    }
+
+    /**
+     * Convert a point (in cartesian coordinates) to crystal (fractional).
+     */
+    convertPointToFractional(point: Point): Coordinate {
+        return MULT(point, INV(this.vectorsAsArray)) as Coordinate;
+    }
+
+    /**
+     * Check whether a point is inside the cell.
+     * @param point - the point to conduct the check for.
+     * @param tolerance - numerical tolerance.
+     */
+    isPointInsideCell(point: Point, tolerance = constants.tolerance.length): boolean {
+        return (
+            this.convertPointToFractional(point)
+                .map((c: number) => math.isBetweenZeroInclusiveAndOne(c, tolerance))
+                // @ts-ignore
+                .reduce((a: boolean, b: boolean): boolean => a && b)
+        );
+    }
+
+    /**
+     * Returns the index of the cell vector, most collinear with the testVector.
+     * @param testVector
+     */
+    getMostCollinearVectorIndex(testVector: Vector): number {
+        // @ts-ignore
+        const angles = this.vectorsAsArray.map((v) => math.angleUpTo90(v, testVector));
+        return angles.findIndex((el) => el === math.min(angles));
+    }
+
+    /**
+     * Scale this cell by right-multiplying it to a matrix (nested array)
+     */
+    scaleByMatrix(matrix: number[][]) {
+        // @ts-ignore
+        [this.vector1, this.vector2, this.vector3] = MATRIX_MULT(matrix, this.vectorsAsArray);
+    }
+}

package/src/js/cell/conventional_cell.ts

@@ -0,0 +1,89 @@
+import { LatticeTypeSchema } from "@mat3ra/esse/lib/js/types";
+
+/**
+ * Routines for calculating conventional cell vectors from primitive cell Bravais parameters.
+ * Following Setyawan, W., & Curtarolo, S. (2010). doi:10.1016/j.commatsci.2010.05.010
+ */
+
+const unitMatrix = [
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+];
+
+// (Conventional cellVectors) = (Primitive cellVectors) * (PRIMITIVE_TO_CONVENTIONAL_CELL_MULTIPLIER matrix)
+export const PRIMITIVE_TO_CONVENTIONAL_CELL_MULTIPLIERS = {
+    // PRIMITIVE    =>  CONVENTIONAL
+    CUB: unitMatrix,
+    FCC: [
+        [-1, 1, 1],
+        [1, -1, 1],
+        [1, 1, -1],
+    ],
+    BCC: [
+        [0, 1, 1],
+        [1, 0, 1],
+        [1, 1, 0],
+    ],
+    TET: unitMatrix,
+    BCT: [
+        [0, 1, 1],
+        [1, 0, 1],
+        [1, 1, 0],
+    ],
+    ORC: unitMatrix,
+    ORCF: [
+        [-1, 1, 1],
+        [1, -1, 1],
+        [1, 1, -1],
+    ],
+    ORCI: [
+        [0, 1, 1],
+        [1, 0, 1],
+        [1, 1, 0],
+    ],
+    ORCC: [
+        [1, -1, 0],
+        [1, 1, 0],
+        [0, 0, 1],
+    ],
+    HEX: unitMatrix,
+    RHL: unitMatrix,
+    MCL: unitMatrix,
+    MCLC: [
+        [1, -1, 0],
+        [1, 1, 0],
+        [0, 0, 1],
+    ],
+    TRI: unitMatrix,
+    TRIalt: unitMatrix,
+};
+
+export const PRIMITIVE_TO_CONVENTIONAL_CELL_LATTICE_TYPES: {
+    [key in LatticeTypeSchema | "TRIalt"]: LatticeTypeSchema;
+} = {
+    // PRIMITIVE    =>  CONVENTIONAL
+    CUB: "CUB",
+    FCC: "CUB",
+    BCC: "CUB",
+    TET: "TET",
+    BCT: "TET",
+    ORC: "ORC",
+    ORCF: "ORC",
+    ORCI: "ORC",
+    ORCC: "ORC",
+    HEX: "HEX",
+    RHL: "RHL",
+    MCL: "MCL",
+    MCLC: "MCL",
+    TRI: "TRI",
+    // TODO: Legacy `TRI_alt` type, assert not used and remove
+    TRIalt: "TRI",
+};
+
+export function isConventionalCellSameAsPrimitiveForLatticeType(
+    latticeType: LatticeTypeSchema,
+): boolean {
+    const multiplier = PRIMITIVE_TO_CONVENTIONAL_CELL_MULTIPLIERS[latticeType || "TRI"];
+    return multiplier === unitMatrix;
+}

package/src/js/cell/primitive_cell.ts

@@ -0,0 +1,189 @@
+/* eslint no-unused-vars: 0 */
+import { LatticeImplicitSchema } from "@mat3ra/esse/lib/js/types";
+
+import { VectorsAsArray } from "../lattice/types";
+import math from "../math";
+
+/**
+ * Routines for calculating primitive cell vectors from conventional cell Bravais parameters.
+ * Following Setyawan, W., & Curtarolo, S. (2010). doi:10.1016/j.commatsci.2010.05.010
+ */
+const PRIMITIVE_CELLS = {
+    CUB: ({ a }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [a, 0, 0],
+            [0, a, 0],
+            [0, 0, a],
+        ];
+    },
+
+    FCC: ({ a }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [0.0, a / 2, a / 2],
+            [a / 2, 0.0, a / 2],
+            [a / 2, a / 2, 0.0],
+        ];
+    },
+
+    BCC: ({ a }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [-a / 2, a / 2, a / 2],
+            [a / 2, -a / 2, a / 2],
+            [a / 2, a / 2, -a / 2],
+        ];
+    },
+
+    TET: ({ a, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [a, 0, 0],
+            [0, a, 0],
+            [0, 0, c],
+        ];
+    },
+
+    BCT: ({ a, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [-a / 2, a / 2, c / 2],
+            [a / 2, -a / 2, c / 2],
+            [a / 2, a / 2, -c / 2],
+        ];
+    },
+
+    ORC: ({ a, b, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [a, 0, 0],
+            [0, b, 0],
+            [0, 0, c],
+        ];
+    },
+
+    ORCF: ({ a, b, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [0, b / 2, c / 2],
+            [a / 2, 0, c / 2],
+            [a / 2, b / 2, 0],
+        ];
+    },
+
+    ORCI: ({ a, b, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [-a / 2, b / 2, c / 2],
+            [a / 2, -b / 2, c / 2],
+            [a / 2, b / 2, -c / 2],
+        ];
+    },
+
+    ORCC: ({ a, b, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [a / 2, b / 2, 0],
+            [-a / 2, b / 2, 0],
+            [0, 0, c],
+        ];
+    },
+
+    HEX: ({ a, c }: LatticeImplicitSchema): VectorsAsArray => {
+        return [
+            [a / 2, (-a * math.sqrt(3)) / 2, 0],
+            [a / 2, (a * math.sqrt(3)) / 2, 0],
+            [0, 0, c],
+        ];
+    },
+
+    RHL: ({ a, alpha }: LatticeImplicitSchema): VectorsAsArray => {
+        const cosAlpha = math.cos((alpha / 180) * math.PI);
+        const cosHalfAlpha = math.sqrt((1 / 2) * (1 + cosAlpha));
+        const sinHalfAlpha = math.sqrt((1 / 2) * (1 - cosAlpha));
+        return [
+            [a * cosHalfAlpha, -a * sinHalfAlpha, 0.0],
+            [a * cosHalfAlpha, a * sinHalfAlpha, 0.0],
+            [
+                (a * cosAlpha) / cosHalfAlpha,
+                0.0,
+                a * math.sqrt(1 - (cosAlpha * cosAlpha) / (cosHalfAlpha * cosHalfAlpha)),
+            ],
+        ];
+    },
+
+    MCL: ({ a, b, c, alpha }: LatticeImplicitSchema): VectorsAsArray => {
+        const cosAlpha = math.cos((alpha / 180) * math.PI);
+        return [
+            [a, 0, 0],
+            [0, b, 0],
+            [0, c * cosAlpha, c * math.sqrt(1 - cosAlpha * cosAlpha)],
+        ];
+    },
+
+    MCLC: ({ a, b, c, alpha }: LatticeImplicitSchema): VectorsAsArray => {
+        const cosAlpha = math.cos((alpha / 180) * math.PI);
+        return [
+            [a / 2, b / 2, 0],
+            [-a / 2, b / 2, 0],
+            [0, c * cosAlpha, c * math.sqrt(1 - cosAlpha * cosAlpha)],
+        ];
+    },
+
+    // Algorithm from http://pymatgen.org/_modules/pymatgen/core/lattice.html (from_params)
+    TRI: ({ a, b, c, alpha, beta, gamma }: LatticeImplicitSchema): VectorsAsArray => {
+        // convert angles to Radians
+        // eslint-disable-next-line no-param-reassign
+        [alpha, beta, gamma] = [alpha, beta, gamma].map(
+            // @ts-ignore
+            (x) => math.unit(x, "degree").to("rad").value,
+        );
+
+        const [cosAlpha, cosBeta, cosGamma] = [alpha, beta, gamma].map((x) => math.cos(x));
+        const [sinAlpha, sinBeta] = [alpha, beta].map((x) => math.sin(x));
+        const gammaStar = math.acos((cosAlpha * cosBeta - cosGamma) / (sinAlpha * sinBeta));
+        const cosGammaStar = math.cos(gammaStar);
+        const sinGammaStar = math.sin(gammaStar);
+
+        return [
+            [a * sinBeta, 0.0, a * cosBeta],
+            [-b * sinAlpha * cosGammaStar, b * sinAlpha * sinGammaStar, b * cosAlpha],
+            [0.0, 0.0, c],
+        ];
+    },
+
+    // alternative implementation
+    TRIalt: ({ a, b, c, alpha, beta, gamma }: LatticeImplicitSchema): VectorsAsArray => {
+        const cosAlpha = math.cos((alpha / 180) * math.PI);
+        const cosBeta = math.cos((beta / 180) * math.PI);
+        const cosGamma = math.cos((gamma / 180) * math.PI);
+        const sinGamma = math.sqrt(1 - cosGamma * cosGamma);
+        return [
+            [a, 0.0, 0.0],
+            [b * cosGamma, b * sinGamma, 0.0],
+            [
+                c * cosBeta,
+                (c / sinGamma) * (cosAlpha - cosBeta * cosGamma),
+                (c / sinGamma) *
+                    math.sqrt(
+                        sinGamma * sinGamma -
+                            cosAlpha * cosAlpha -
+                            cosBeta * cosBeta +
+                            2 * cosAlpha * cosBeta * cosGamma,
+                    ),
+            ],
+        ];
+    },
+};
+
+/**
+ * Returns lattice vectors for a primitive cell for a lattice.
+ * @param lattice - Lattice instance.
+ * @param  skipRounding - whether to skip rounding the lattice vectors.
+ * @return Cell.vectorsAsArray
+ */
+export function primitiveCell(
+    lattice: LatticeImplicitSchema,
+    skipRounding = false,
+): VectorsAsArray {
+    const [vectorA, vectorB, vectorC] = PRIMITIVE_CELLS[lattice.type || "TRI"](lattice);
+    // set precision and remove JS floating point artifacts
+    if (!skipRounding) {
+        [vectorA, vectorB, vectorC].map((vec) =>
+            vec.map((c) => math.precise(c)).map(math.roundToZero),
+        );
+    }
+    return [vectorA, vectorB, vectorC];
+}

package/src/js/constants.js

@@ -0,0 +1,4 @@
+// TODO: adjust the imports and remove the need for re-exporting
+export * from "@exabyte-io/code.js/dist/constants";
+// eslint-disable-next-line no-restricted-exports
+export { default } from "@exabyte-io/code.js/dist/constants";

package/src/js/constraints/constraints.ts

@@ -0,0 +1,63 @@
+import { ArrayWithIds } from "../abstract/array_with_ids";
+import { ObjectWithIdAndValue } from "../abstract/scalar_with_id";
+
+export interface ConstraintValue extends Array<boolean> {
+    0: boolean;
+    1: boolean;
+    2: boolean;
+}
+
+export type Constraint = ObjectWithIdAndValue<ConstraintValue>;
+
+export class AtomicConstraints {
+    name: string;
+
+    values: ArrayWithIds<ConstraintValue>;
+
+    static fromArray(array: ConstraintValue[]) {
+        return new AtomicConstraints({ values: array });
+    }
+
+    /**
+     * Create atomic constraints.
+     * @param {Object} config
+     * @param {ArrayWithIds|Array} config.values
+     */
+    constructor({ values }: { values?: ConstraintValue[] }) {
+        this.name = "atomic_constraints";
+        this.values = new ArrayWithIds(values || []);
+    }
+
+    /**
+     * @example As below:
+        [
+            {
+                "id" : 0,
+                "value" : [
+                    1,
+                    1,
+                    1
+                ]
+            }
+        ]
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            values: this.values.toJSON(),
+        };
+    }
+
+    getByIndex(idx: number): ConstraintValue {
+        return this.values.getArrayElementByIndex(idx) || [];
+    }
+
+    /**
+     * Get constraints for an atom with index as string.
+     * @param idx - atom index.
+     * @param mapFn (OPTIONAL) - a function to be applied to each constraint. By default 0 or 1 is returned.
+     */
+    getAsStringByIndex(idx: number, mapFn = (val: boolean): string => (val ? "1" : "0")): string {
+        return this.getByIndex(idx).map(mapFn).join(" ");
+    }
+}

package/src/js/lattice/lattice.ts

@@ -0,0 +1,229 @@
+import {
+    LatticeImplicitSchema,
+    LatticeSchema,
+    LatticeTypeExtendedSchema,
+} from "@mat3ra/esse/lib/js/types";
+import lodash from "lodash";
+import _ from "underscore";
+
+import { Cell } from "../cell/cell";
+import { primitiveCell } from "../cell/primitive_cell";
+import { HASH_TOLERANCE } from "../constants";
+import math from "../math";
+import { FromVectorsProps, LatticeBravais } from "./lattice_bravais";
+import { BravaisConfigProps, LatticeVectors } from "./lattice_vectors";
+import { LATTICE_TYPE_CONFIGS } from "./types";
+import { UnitCell, UnitCellProps } from "./unit_cell";
+
+/**
+ * Scaling factor used to calculate the new lattice size for non-periodic systems.
+ * The scaling factor ensures that a non-periodic structure will have have a lattice greater than the structures size.
+ */
+export const nonPeriodicLatticeScalingFactor = 2.0;
+
+/*
+ * Container class for crystal lattice and associated methods.
+ * Follows Bravais convention for lattice types and contains lattice vectors within.
+ * Units for lattice vector coordinates are "angstroms", and "degrees" for the corresponding angles.
+ */
+export class Lattice extends LatticeBravais implements LatticeSchema {
+    vectors: LatticeVectors;
+
+    /**
+     * Create a Lattice class from a config object.
+     * @param {Object} config - Config object. See LatticeVectors.fromBravais.
+     */
+    constructor(config: Partial<LatticeImplicitSchema> = {}) {
+        super(config);
+        this.vectors = LatticeVectors.fromBravais(config);
+    }
+
+    /**
+     * Create a Lattice class from a list of vectors.
+     * @param {Object} config - Config object. See LatticeBravais.fromVectors.
+     */
+    static fromVectors(config: FromVectorsProps) {
+        return new Lattice(LatticeBravais.fromVectors(config).toJSON());
+    }
+
+    /**
+     * Serialize class instance to JSON.
+     * @example As below:
+         {
+            "a" : 3.867,
+            "b" : 3.867,
+            "c" : 3.867,
+            "alpha" : 60,
+            "beta" : 60,
+            "gamma" : 60,
+            "units" : {
+                "length" : "angstrom",
+                "angle" : "degree"
+            },
+            "type" : "FCC",
+            "vectors" : {
+                "a" : [
+                    3.34892,
+                    0,
+                    1.9335
+                ],
+                "b" : [
+                    1.116307,
+                    3.157392,
+                    1.9335
+                ],
+                "c" : [
+                    0,
+                    0,
+                    3.867
+                ],
+                "alat" : 1,
+                "units" : "angstrom"
+            }
+        }
+     */
+    toJSON(skipRounding = false): LatticeSchema {
+        const round = skipRounding ? (x: number) => x : Lattice._roundValue; // round values by default
+
+        return {
+            a: round(this.a),
+            b: round(this.b),
+            c: round(this.c),
+            alpha: round(this.alpha),
+            beta: round(this.beta),
+            gamma: round(this.gamma),
+            units: {
+                length: this.units.length,
+                angle: this.units.angle,
+            },
+            type: this.type,
+            vectors: this.vectors.toJSON(),
+        };
+    }
+
+    clone(extraContext: BravaisConfigProps) {
+        return new (this.constructor as typeof Lattice)({ ...this.toJSON(), ...extraContext });
+    }
+
+    /**
+     * Get lattice vectors as a nested array
+     */
+    get vectorArrays() {
+        return this.vectors.vectorArrays;
+    }
+
+    get Cell() {
+        return new Cell(this.vectorArrays);
+    }
+
+    /**
+     * Get a short label for the type of the lattice, eg. "MCLC".
+     */
+    get typeLabel(): string {
+        return lodash.get(
+            LATTICE_TYPE_CONFIGS.find((c) => c.code === this.type),
+            "label",
+            "Unknown",
+        );
+    }
+
+    /**
+     * Get a short label for the extended type of the lattice, eg. "MCLC-5".
+     */
+    get typeExtended(): LatticeTypeExtendedSchema {
+        const { a, b, c, alpha, beta, gamma, type } = this;
+        const cosAlpha = math.cos((alpha / 180) * math.PI);
+
+        switch (type) {
+            case "BCT":
+                return c < a ? "BCT-1" : "BCT-2";
+            case "ORCF":
+                if (1 / (a * a) >= 1 / (b * b) + 1 / (c * c)) {
+                    return "ORCF-1";
+                }
+                return "ORCF-2";
+            case "RHL":
+                return cosAlpha > 0 ? "RHL-1" : "RHL-2";
+            case "MCLC":
+                if (gamma >= 90) {
+                    // MCLC-1,2
+                    return "MCLC-1";
+                }
+                if ((b / c) * cosAlpha + ((b * b) / (a * a)) * (1 - cosAlpha * cosAlpha) <= 1) {
+                    // MCLC-3,4
+                    return "MCLC-3";
+                }
+                return "MCLC-5";
+            case "TRI":
+                if (alpha > 90 && beta > 90 && gamma >= 90) {
+                    // TRI-1a,2a
+                    return "TRI_1a";
+                }
+                return "TRI_1b";
+            default:
+                return type;
+        }
+    }
+
+    /**
+     * Calculate the volume of the lattice cell.
+     */
+    get volume(): number {
+        return math.abs(math.det(this.vectorArrays));
+    }
+
+    /*
+     * Returns a "default" primitive lattice by type, with lattice parameters scaled by the length of "a",
+     * @param latticeConfig {Object} LatticeBravais config (see constructor)
+     */
+    static getDefaultPrimitiveLatticeConfigByType(latticeConfig: LatticeImplicitSchema) {
+        const f_ = Lattice._roundValue;
+        // construct new primitive cell using lattice parameters and skip rounding the vectors
+        const pCell = primitiveCell(latticeConfig, true);
+        // create new lattice from primitive cell
+        const newLattice = { ...Lattice.fromVectorArrays(pCell, latticeConfig.type) };
+        // preserve the new type and scale back the lattice parameters
+        const k = latticeConfig.a / newLattice.a;
+
+        return Object.assign(newLattice, {
+            a: f_(newLattice.a * k),
+            b: f_(newLattice.b * k),
+            c: f_(newLattice.c * k),
+            alpha: f_(newLattice.alpha),
+            beta: f_(newLattice.beta),
+            gamma: f_(newLattice.gamma),
+        });
+    }
+
+    // TODO: remove
+    get unitCell() {
+        const vectors = [..._.flatten(this.vectorArrays), this.units.length] as UnitCellProps;
+        return new UnitCell(vectors);
+    }
+
+    /**
+     * Returns a string further used for the calculation of an unique hash.
+     * @param isScaled - Whether to scale the vectors by the length of the first vector initially.
+     */
+    getHashString(isScaled = false): string {
+        // lattice vectors must be measured in angstroms
+        const scaleK = isScaled ? this.a : 1;
+        const scaledLattice = {
+            ...this,
+            a: this.a / scaleK,
+            b: this.b / scaleK,
+            c: this.c / scaleK,
+        };
+        // form lattice string
+        return `${[
+            scaledLattice.a,
+            scaledLattice.b,
+            scaledLattice.c,
+            scaledLattice.alpha,
+            scaledLattice.beta,
+            scaledLattice.gamma,
+        ]
+            .map((x) => math.round(x, HASH_TOLERANCE))
+            .join(";")};`;
+    }
+}