@mat3ra/made 2024.3.22-0

package/src/js/lattice/lattice_bravais.ts

@@ -0,0 +1,170 @@
+import { LatticeImplicitSchema, LatticeTypeSchema } from "@mat3ra/esse/lib/js/types";
+
+import constants from "../constants";
+import math from "../math";
+import { LATTICE_TYPE_CONFIGS, Vector, VectorsAsArray } from "./types";
+
+export type Units = Required<LatticeImplicitSchema>["units"];
+
+export interface FromVectorsProps {
+    a: Vector; // vector of the lattice.
+    b: Vector; // vector of the lattice.
+    c: Vector; // vector of the lattice.
+    alat?: number; // scaling factor for the vector coordinates, defaults to 1.
+    units?: Units["length"]; // units for the coordinates (eg. angstrom, crystal).
+    type?: LatticeTypeSchema; // type of the lattice to be created, defaults to TRI when not provided.
+    skipRounding?: boolean; // whether to skip rounding the resulting lattice values, defaults to `false`.
+}
+
+/*
+ * @summary: class that holds parameters of a Bravais Lattice: a, b, c, alpha, beta, gamma + corresponding units.
+ * When stored as class variables units for lengths are always "angstrom"s, angle - "degree"s
+ */
+export class LatticeBravais implements LatticeImplicitSchema {
+    a: number;
+
+    b: number;
+
+    c: number;
+
+    alpha: number;
+
+    beta: number;
+
+    gamma: number;
+
+    units: Units;
+
+    type: LatticeImplicitSchema["type"];
+
+    /**
+     * Create a Bravais lattice.
+     */
+    constructor(config: Partial<LatticeImplicitSchema>) {
+        const {
+            a = 1, // default lattice is cubic with unity in edge sizes
+            b = a,
+            c = a,
+            alpha = 90,
+            beta = alpha,
+            gamma = alpha,
+            // if we do not know what lattice type this is => set to TRI
+            type = "TRI",
+            units = {
+                length: "angstrom",
+                angle: "degree",
+            },
+        } = config;
+
+        const k =
+            constants.units.bohr === units.length ? constants.coefficients.BOHR_TO_ANGSTROM : 1;
+
+        this.a = a * k;
+        this.b = b * k;
+        this.c = c * k;
+        this.alpha = alpha;
+        this.beta = beta;
+        this.gamma = gamma;
+        this.type = type;
+        this.units = units;
+    }
+
+    static _roundValue(x: number): number {
+        return math.precise(math.roundToZero(x));
+    }
+
+    /**
+     * Create a Bravais lattice from vectors.
+     */
+    static fromVectors({
+        a,
+        b,
+        c,
+        alat = 1,
+        units = "angstrom",
+        type = "TRI",
+        skipRounding = false,
+    }: FromVectorsProps) {
+        const roundValue = skipRounding ? (x: number) => x : this._roundValue;
+
+        return new (this.prototype.constructor as typeof LatticeBravais)({
+            // @ts-ignore
+            a: roundValue(math.vlen(a) * alat),
+            // @ts-ignore
+            b: roundValue(math.vlen(b) * alat),
+            // @ts-ignore
+            c: roundValue(math.vlen(c) * alat),
+            alpha: roundValue(math.angle(b, c, "deg")),
+            beta: roundValue(math.angle(a, c, "deg")),
+            gamma: roundValue(math.angle(a, b, "deg")),
+            // initially we do not know what lattice type this is => set to TRI
+            type,
+            units: {
+                length: units,
+                angle: "degree",
+            },
+        });
+    }
+
+    /**
+     * See fromVectors above.
+     */
+    static fromVectorArrays(array: VectorsAsArray, type: LatticeTypeSchema, skipRounding = true) {
+        return this.fromVectors({
+            a: array[0],
+            b: array[1],
+            c: array[2],
+            type,
+            skipRounding, // do not round the values to avoid loosing precision by default
+        });
+    }
+
+    /**
+     * Get the list of editable keys (eg. 'a', 'alpha') for the current lattice.
+     * @return {Object}
+     * @example {a: true, b: false, c: false, alpha: true, beta: false, gamma: false}
+     */
+    get editables() {
+        const object = {};
+        const editablesList = LATTICE_TYPE_CONFIGS.find(
+            (entry) => entry.code === this.type,
+        )?.editables;
+        // ["a", "gamma"] => {a: true, gamma: true}
+        if (editablesList) {
+            editablesList.forEach((element) => {
+                Object.assign(object, {
+                    [element]: true,
+                });
+            });
+        }
+
+        return object;
+    }
+
+    /**
+     * 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"
+         }
+     */
+    toJSON(): LatticeImplicitSchema {
+        return {
+            ...this,
+            units: {
+                length: this.units.length,
+                angle: this.units.angle,
+            },
+        };
+    }
+}

package/src/js/lattice/lattice_vectors.ts

@@ -0,0 +1,126 @@
+import { LatticeExplicitUnit, LatticeImplicitSchema } from "@mat3ra/esse/lib/js/types";
+
+import { primitiveCell } from "../cell/primitive_cell";
+import constants from "../constants";
+import math from "../math";
+import { Vector } from "./types";
+
+type RequiredLatticeExplicitUnit = Required<LatticeExplicitUnit>;
+
+export interface BravaisConfigProps extends Partial<LatticeImplicitSchema> {
+    isConventional?: boolean;
+}
+
+/*
+ * @summary: class that holds parameters of a Bravais Lattice: a, b, c, alpha, beta, gamma + corresponding units.
+ * When stored as class variables units for lengths are always "angstrom"s, angle - "degree"s
+ */
+export class LatticeVectors implements RequiredLatticeExplicitUnit {
+    a: RequiredLatticeExplicitUnit["a"];
+
+    b: RequiredLatticeExplicitUnit["b"];
+
+    c: RequiredLatticeExplicitUnit["c"];
+
+    alat: RequiredLatticeExplicitUnit["alat"];
+
+    units: RequiredLatticeExplicitUnit["units"];
+
+    /**
+     * Create a Bravais lattice.
+     */
+    constructor(config: LatticeExplicitUnit) {
+        const { a, b, c, alat = 1, units = "angstrom" } = config;
+        const k = constants.units.bohr === units ? constants.coefficients.BOHR_TO_ANGSTROM : 1;
+
+        this.a = a.map((x) => x * k) as Vector;
+        this.b = b.map((x) => x * k) as Vector;
+        this.c = c.map((x) => x * k) as Vector;
+        this.alat = alat;
+        this.units = "angstrom";
+    }
+
+    static _roundValue(arr: number[]): number[] {
+        return arr.map((el) => math.precise(math.roundToZero(el)));
+    }
+
+    /*
+     * Constructs a Bravais lattice from lattice vectors
+     * Supports conventional lattice as parameters and primitive too.
+     * Algorithm from http://pymatgen.org/_modules/pymatgen/core/lattice.html (from_params)
+     * For parameters see `LatticeBravais.constructor`.
+     */
+    static fromBravais({
+        a = 1, // default lattice is cubic with unity in edge sizes
+        b = a,
+        c = a,
+        alpha = 90,
+        beta = 90,
+        gamma = 90,
+        units = {
+            length: "angstrom",
+            angle: "degree",
+        },
+        type = "TRI",
+        isConventional = false,
+    }: BravaisConfigProps) {
+        // use "direct" lattice constructor for primitive lattice
+        // eslint-disable-next-line no-param-reassign
+        if (!isConventional) type = "TRI";
+
+        // set precision and remove JS floating point artifacts
+        const [vectorA, vectorB, vectorC] = primitiveCell({
+            a,
+            b,
+            c,
+            alpha,
+            beta,
+            gamma,
+            units,
+            type,
+        });
+
+        return new LatticeVectors({
+            a: vectorA,
+            b: vectorB,
+            c: vectorC,
+            alat: 1,
+        });
+    }
+
+    get vectorArrays(): [Vector, Vector, Vector] {
+        return [this.a, this.b, this.c];
+    }
+
+    /**
+     * Serialize class instance to JSON.
+     * @example As below:
+     {
+            "a" : [
+                3.34892,
+                0,
+                1.9335
+            ],
+            "b" : [
+                1.116307,
+                3.157392,
+                1.9335
+            ],
+            "c" : [
+                0,
+                0,
+                3.867
+            ],
+            "alat" : 1,
+            "units" : "angstrom"
+        }
+     */
+    toJSON(): RequiredLatticeExplicitUnit {
+        return {
+            ...this,
+            a: LatticeVectors._roundValue(this.a),
+            b: LatticeVectors._roundValue(this.b),
+            c: LatticeVectors._roundValue(this.c),
+        };
+    }
+}

package/src/js/lattice/reciprocal/lattice_reciprocal.js

@@ -0,0 +1,155 @@
+import { ATOMIC_COORD_UNITS, units as UNITS } from "@exabyte-io/code.js/dist/constants";
+import almostEqual from "array-almost-equal";
+import lodash from "lodash";
+
+import math from "../../math";
+import { Lattice } from "../lattice";
+import { paths } from "./paths";
+import { symmetryPoints } from "./symmetry_points";
+
+export class ReciprocalLattice extends Lattice {
+    /**
+     * Get reciprocal vectors for the current Lattice in cartesian (2pi / a) units
+     * @return {Array[]}
+     */
+    get reciprocalVectors() {
+        const vectors_ = this.vectors.vectorArrays;
+        const a = math.vlen(vectors_[0]);
+        const divider = math.multiply(vectors_[0], math.cross(vectors_[1], vectors_[2])) / a;
+        return [
+            math.multiply(math.cross(vectors_[1], vectors_[2]), 1 / divider),
+            math.multiply(math.cross(vectors_[2], vectors_[0]), 1 / divider),
+            math.multiply(math.cross(vectors_[0], vectors_[1]), 1 / divider),
+        ];
+    }
+
+    /**
+     * Norms of reciprocal vectors.
+     * @return {number[]}
+     */
+    get reciprocalVectorNorms() {
+        return this.reciprocalVectors.map((vec) => math.norm(vec));
+    }
+
+    /**
+     * Ratio of reciprocal vector norms scaled by the inverse of the largest component.
+     * @return {number[]}
+     */
+    get reciprocalVectorRatios() {
+        const norms = this.reciprocalVectorNorms;
+        const maxNorm = math.max(...norms);
+        return norms.map((n) => n / maxNorm);
+    }
+
+    /**
+     * Get point (in crystal coordinates) in cartesian coordinates.
+     * @param {Array} point - point in 3D space
+     * @return {Array}
+     */
+    getCartesianCoordinates(point) {
+        return math.multiply(point, this.reciprocalVectors);
+    }
+
+    /**
+     * Get the list of high-symmetry points for the current lattice.
+     * @return {Object[]}
+     */
+    get symmetryPoints() {
+        return symmetryPoints(this);
+    }
+
+    /**
+     * Get the default path in reciprocal space for the current lattice.
+     * @return {Array[]}
+     */
+    get defaultKpointPath() {
+        return paths[this.typeExtended] || paths[this.type];
+    }
+
+    /**
+     * Find/mark the high symmetry points on a list with raw data and return the edited list.
+     * @param {Array} dataPoints - list of point coordinates
+     * @return {Object[]}
+     */
+    extractKpointPath(dataPoints = []) {
+        const kpointPath = [];
+        const symmPoints = this.symmetryPoints;
+
+        dataPoints.forEach((point, index) => {
+            const symmPoint = symmPoints.find((x) => {
+                return almostEqual(x.coordinates, point, 1e-4);
+            });
+            if (symmPoint) {
+                kpointPath.push({
+                    point: symmPoint.point,
+                    steps: index,
+                    coordinates: symmPoint.coordinates,
+                });
+            }
+        });
+        return kpointPath;
+    }
+
+    /**
+     * Calculate grid dimension based on reciprocal lattice vectors.
+     * @param {number} nPoints - Total number of points
+     * @param {number} index - Index of reciprocal vector
+     * @return {number} - Grid dimension in direction of reciprocal vector
+     * @todo This could be moved to a separate KGrid class.
+     */
+    calculateDimension(nPoints, index) {
+        const norms = this.reciprocalVectorNorms;
+        const [j, k] = [0, 1, 2].filter((i) => i !== index); // get indices of other two dimensions
+        const N = math.cbrt((nPoints * norms[index] ** 2) / (norms[j] * norms[k]));
+        return math.max(1, math.ceil(N));
+    }
+
+    /**
+     * Calculate grid dimensions from total number of k-points.
+     * @param {number} nKpoints - Total number of k-points.
+     * @return {number[]} - Grid dimensions
+     */
+    getDimensionsFromPointsCount(nKpoints) {
+        const indices = [0, 1, 2];
+        return indices.map((i) => this.calculateDimension(nKpoints, i));
+    }
+
+    get conversionTable() {
+        const { a } = this;
+        return {
+            [ATOMIC_COORD_UNITS.cartesian]: {
+                [UNITS.angstrom]: (2 * math.PI) / a,
+            },
+            [UNITS.angstrom]: {
+                [ATOMIC_COORD_UNITS.cartesian]: a / (2 * math.PI),
+            },
+        };
+    }
+
+    /**
+     * Calculate grid dimensions from k-point spacing, i.e.
+     * the maximum distance between adjacent points along a reciprocal axis.
+     * Note: just as the lattice vectors spacing is in cartesian (2pi / a) units by default
+     * @param {number} spacing - maximum Spacing between k-points
+     * @param {string} units - units of spacing parameter (default: 2pi / a)
+     * @return {number[]}
+     */
+    getDimensionsFromSpacing(spacing, units = ATOMIC_COORD_UNITS.cartesian) {
+        const factor = this.conversionTable[units][ATOMIC_COORD_UNITS.cartesian] || 1;
+        return this.reciprocalVectorNorms.map((norm) => {
+            return math.max(1, math.ceil(lodash.round(norm / (spacing * factor), 4)));
+        });
+    }
+
+    /**
+     * Calculate grid spacing as average of spacing along individual reciprocal axes.
+     * @param {number[]} dimensions - Array of dimensions
+     * @param {string} units - units of spacing parameter (default: 2pi / a)
+     * @return {number} - average grid spacing
+     */
+    getSpacingFromDimensions(dimensions, units = ATOMIC_COORD_UNITS.cartesian) {
+        const factor = this.conversionTable[ATOMIC_COORD_UNITS.cartesian][units] || 1;
+        const norms = this.reciprocalVectorNorms;
+        return factor * math.mean(dimensions.map((dim, i) => norms[i] / math.max(1, dim)));
+    }
+}

package/src/js/lattice/reciprocal/paths.js

@@ -0,0 +1,134 @@
+import _ from "underscore";
+
+/**
+ * Default kpoing paths according to:
+ *  [AFLOW](https://arxiv.org/abs/1004.2974) methodology.
+ *  Paths are split in parts for clarity.
+ */
+const points = {
+    CUB: [
+        ["Г", "X", "M", "Г", "R", "X"],
+        ["M", "R"],
+    ],
+    BCC: [
+        ["Г", "H", "N", "Г", "P", "H"],
+        ["P", "N"],
+    ],
+    FCC: [
+        ["Г", "X", "W", "K", "Г", "L", "U", "W", "L"],
+        ["U", "X"],
+    ],
+    TET: [
+        ["Г", "X", "M", "Г", "Z", "R", "A", "Z"],
+        ["X", "R"],
+        ["M", "A"],
+    ],
+    "BCT-1": [
+        ["Г", "X", "M", "Г", "Z", "P", "N", "Z1", "M"],
+        ["X", "P"],
+    ],
+    "BCT-2": [
+        ["Г", "X", "Y", "∑", "Г", "Z", "∑1", "N", "P", "Y1", "Z"],
+        ["X", "P"],
+    ],
+    ORC: [
+        ["Г", "X", "S", "Y", "Г", "Z", "U", "R", "T", "Z"],
+        ["Y", "T"],
+        ["U", "X"],
+        ["S", "R"],
+    ],
+    "ORCF-1": [
+        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
+        ["T", "X1"],
+        ["X", "A", "Z"],
+        ["L", "Г"],
+    ],
+    "ORCF-2": [
+        ["Г", "Y", "C", "D", "X", "Г", "Z", "D1", "H", "C"],
+        ["C1", "Z"],
+        ["X", "H1"],
+        ["H", "Y"],
+        ["L", "Г"],
+    ],
+    "ORCF-3": [
+        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
+        ["X", "A", "Z"],
+        ["L", "Г"],
+    ],
+    ORCI: [
+        ["Г", "X", "L", "T", "W", "R", "X1", "Z", "Г", "Y", "S", "W"],
+        ["L1", "Y"],
+        ["Y1", "Z"],
+    ],
+    ORCC: [
+        ["Г", "X", "S", "R", "A", "Z", "Г", "Y", "X1", "A1", "T", "Y"],
+        ["Z", "T"],
+    ],
+    HEX: [
+        ["Г", "M", "K", "Г", "A", "L", "H", "A"],
+        ["L", "M"],
+        ["K", "H"],
+    ],
+    "RHL-1": [
+        ["Г", "L", "B1"],
+        ["B", "Z", "Г", "X"],
+        ["Q", "F", "P1", "Z"],
+        ["L", "P"],
+    ],
+    "RHL-2": [["Г", "P", "Z", "Q", "Г", "F", "P1", "Q1", "L", "Z"]],
+    MCL: [
+        ["Г", "Y", "H", "C", "E", "M1", "A", "X", "H1"],
+        ["M", "D", "Z"],
+        ["Y", "D"],
+    ],
+    "MCLC-1": [
+        ["Г", "Y", "Г", "L", "I"],
+        ["I1", "Z", "F1"],
+        ["Y", "X1"],
+        ["X", "Г", "N"],
+        ["M", "Г"],
+    ],
+    "MCLC-2": [
+        ["Г", "Y", "F", "L", "I"],
+        ["I1", "Z", "F1"],
+        ["N", "Г", "M"],
+    ],
+    "MCLC-3": [
+        ["Г", "Y", "F", "H", "Z", "I", "F1"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"],
+    ],
+    "MCLC-4": [
+        ["Г", "Y", "F", "H", "Z", "I"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"],
+    ],
+    "MCLC-5": [
+        ["Г", "Y", "F", "L", "I"],
+        ["I1", "Z", "H", "F1"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"],
+    ],
+    TRI: [
+        ["X", "Г", "Y"],
+        ["L", "Г", "Z"],
+        ["N", "Г", "M"],
+        ["R", "Г"],
+    ],
+};
+
+export const paths = _.each(points, (val, key, obj) => {
+    // merge sub-arrays
+    // eslint-disable-next-line no-param-reassign
+    val = val.reduce((a, b) => a.concat(b));
+
+    _.each(val, (el, idx, list) => {
+        list[idx] = {
+            point: el,
+            // TODO: calculate number of steps based on distance in k-space
+            steps: 10,
+        };
+    });
+
+    obj[key] = val;
+});