@mat3ra/made 2024.3.22-0

package/src/js/parsers/xyz_combinatorial_basis.js

@@ -0,0 +1,243 @@
+/* eslint-disable max-classes-per-file */
+import _ from "underscore";
+import * as s from "underscore.string";
+
+import { Basis } from "../basis/basis";
+import math from "../math";
+
+/**
+ * @summary Combinatorial XYZ basis class and related. Create and get all information about basis and elements in it.
+ * Constructor accepts string in extended XYZ format. Extended XYZ format is as follows:
+ *
+ * 1. Regular XYZ
+ * ```
+ *      Si 0.0 0.0 0.0
+ *      Li 0.5 0.5 0.5
+ * ```
+ * 2. Permutation (slash-separated)
+ * ```
+ *      Si/Ge/As 0.0 0.0 0.0
+ *      Si/Ge    0.5 0.5 0.0
+ * ```
+ * 3. Combination (comma-separated)
+ * ```
+ *      Si,Ge,As 0.0 0.0 0.0
+ *      Si,Ge    0.5 0.5 0.0
+ * ```
+ * More at: https://exabyte.atlassian.net/wiki/display/PD/Combinatorial+materials+set
+ */
+
+/**
+ * Regular expression for basis line.
+ * @type {RegExp}
+ */
+// eslint-disable-next-line max-len
+const LINE_REGEX =
+    /^([A-Z][a-z]?\/?,?)+\s+(-?\d+\.?\d*|\.\d+)\s+(-?\d+\.?\d*|\.\d+)\s+(-?\d+\.?\d*|\.\d+)\s*$/gi;
+// vacancy characters will be used to create vacancies on basis generation
+const VACANCY_CHARACTER = "VAC";
+const COMBINATION_DELIMITER = ",";
+const PERMUTATION_DELIMITER = "/";
+/**
+ * Basis validation error codes.
+ * @type {{MIXING_IN_SINGLE_LINE: number, MIXING_IN_MULTI_LINES: number, REGEX_NOT_PASSED: number}}
+ */
+const ERROR_CODES = {
+    MIXING_IN_SINGLE_LINE: 1,
+    MIXING_IN_MULTI_LINES: 2,
+    REGEX_NOT_PASSED: 3,
+};
+
+export class WrongBasisFormat extends Error {
+    constructor(xyz, message, type) {
+        super(message, type);
+        this.xyz = xyz;
+    }
+}
+
+export class CombinatorialBasis {
+    /**
+     * Creates Combinatorial basis
+     * @param eXYZ
+     */
+    constructor(eXYZ) {
+        this._xyz = eXYZ;
+        this._lines = s
+            .lines(eXYZ)
+            .map((x) => x.trim())
+            .filter((x) => x !== "")
+            .map(this._parseBasisLine);
+
+        this._hasPermutationLine = this._lines.reduce((mem, a) => {
+            return mem || a.isPermutation;
+        }, false);
+        this._hasCombinationLine = this._lines.reduce((mem, a) => {
+            return mem || a.isCombination;
+        }, false);
+
+        if (this._hasPermutationLine && this._hasCombinationLine) {
+            throw new WrongBasisFormat(
+                this._xyz,
+                "Basis contains mixed permutation and combination.",
+                ERROR_CODES.MIXING_IN_MULTI_LINES,
+            );
+        }
+    }
+
+    /**
+     * Parses combinatorial basis line and returns result as Object. Throws exception if line is not valid:
+     * - does not meet RegExp
+     * - mixes permutation and combination
+     * @param str {String} Combinatorial basis' line
+     * @param index {Number} order of the
+     * @return {{displayName: string, isCombination: boolean, isPermutation: boolean, elements: Array, coordinates: *[]}}
+     * @private
+     */
+    _parseBasisLine(str, index) {
+        if (!str.match(LINE_REGEX)) {
+            throw new WrongBasisFormat(
+                this._xyz,
+                `Line #${index + 1}: "${str}" contains errors. ` +
+                    'Allowed formats: "Si 0 0 0", "Si/Li 0.5 0.5 0.5", "Si,Ge 0.7 0.7 0.8"',
+                ERROR_CODES.REGEX_NOT_PASSED,
+            );
+        }
+
+        const containsPermutation = str.indexOf(PERMUTATION_DELIMITER) > -1;
+        const containsCombination = str.indexOf(COMBINATION_DELIMITER) > -1;
+
+        if (containsCombination && containsPermutation) {
+            throw new WrongBasisFormat(
+                this._xyz,
+                `Line #${index} contains mixed permutation and combination.`,
+                ERROR_CODES.MIXING_IN_SINGLE_LINE,
+            );
+        }
+
+        let elements = [];
+
+        const words = s
+            .words(str)
+            .map((x) => x.trim())
+            .filter((x) => x != null);
+
+        if (containsCombination) {
+            elements = words[0].split(COMBINATION_DELIMITER).map((x) => x.trim());
+        } else if (containsPermutation) {
+            elements = words[0].split(PERMUTATION_DELIMITER).map((x) => x.trim());
+        } else {
+            elements = [words[0]];
+        }
+
+        const coordinates = [parseFloat(words[1]), parseFloat(words[2]), parseFloat(words[3])];
+
+        return {
+            displayName: `ELEMENT_${index}`,
+            isCombination: containsCombination,
+            isPermutation: containsPermutation,
+            elements,
+            coordinates,
+        };
+    }
+
+    /**
+     * Returns array of ALL unique elements used in basis.
+     * @return {String[]}
+     */
+    get uniqueElements() {
+        return _.chain(this._lines)
+            .map((line) => line.elements)
+            .flatten()
+            .unique()
+            .value()
+            .sort();
+    }
+
+    static toBasisConfig(array, units = "crystal", cell = Basis.defaultCell) {
+        return {
+            elements: _.pluck(array, "element"),
+            coordinates: _.pluck(array, "coordinates"),
+            units,
+            cell,
+        };
+    }
+
+    /**
+     * Returns array of regular bases extracted from current combinatorial basis.
+     * @return {Basis[]|Object[]}
+     */
+    get allBasisConfigs() {
+        let result = [];
+        if (this._hasPermutationLine) {
+            result = this._permutation();
+        } else if (this._hasCombinationLine) {
+            result = this._combination();
+        } else {
+            const items = [];
+            this._lines.forEach((line) => {
+                items.push({
+                    element: line.elements[0],
+                    coordinates: line.coordinates,
+                });
+            });
+            result = [items];
+        }
+        return result.map((x) => CombinatorialBasis.toBasisConfig(x));
+    }
+
+    /**
+     * Returns array of regular bases extracted from current combinatorial basis with combinations.
+     * @private
+     */
+    _combination() {
+        const dimensions = [];
+        this._lines.forEach((line) => {
+            const itemsSet = [];
+            line.elements.forEach((element) => {
+                // omit vacancy characters
+                itemsSet.push({
+                    element,
+                    coordinates: line.coordinates,
+                });
+            });
+            dimensions.push(itemsSet);
+        });
+        const basisSet = math.cartesianProduct.apply(null, dimensions);
+        return basisSet.map((basis) =>
+            basis.filter((entry) => entry.element !== VACANCY_CHARACTER),
+        );
+    }
+
+    /**
+     * Returns array of regular bases extracted from current combinatorial basis with permutations.
+     * @return {Basis[]}
+     * @private
+     */
+    _permutation() {
+        const maxLen = Math.max(...this._lines.map((x) => x.elements.length));
+        const bases = [];
+        for (let i = 0; i < maxLen; i++) {
+            const items = [];
+            this._lines.forEach((line) => {
+                const element =
+                    line.elements.length <= i ? _.last(line.elements) : line.elements[i];
+                if (element !== VACANCY_CHARACTER) {
+                    items.push({
+                        element,
+                        coordinates: line.coordinates,
+                    });
+                }
+            });
+            bases.push(items);
+        }
+        return bases;
+    }
+
+    /**
+     * Returns true if current combinatorial basis contains more than one regular basis.
+     * @return {Boolean}
+     */
+    isCombinatorial() {
+        return this._hasCombinationLine || this._hasPermutationLine;
+    }
+}

package/src/js/tools/basis.js

@@ -0,0 +1,116 @@
+import _ from "underscore";
+
+// eslint-disable-next-line no-unused-vars
+import { Basis } from "../basis/basis";
+import math from "../math";
+
+const ADD = math.add;
+const MULT = math.multiply;
+
+/**
+ * Returns a repeated basis of a crystal.
+ * @param basis {Basis} Original basis.
+ * @param repetitions{Number[]} Repetition vector `[x, y, z]`, in each spatial dimension.
+ * @return {Basis} New Basis.
+ */
+function repeat(basis, repetitions) {
+    let i, j, k;
+    let shiftI = 0;
+    let shiftJ = 0;
+    let shiftK = 0;
+
+    // clone original basis and assert it is in cartesian coordinates
+    const newBasis = basis.clone();
+    const basisCloneInCrystalCoordinates = basis.clone();
+
+    newBasis.toCrystal();
+    basisCloneInCrystalCoordinates.toCrystal();
+
+    for (i = 1; i <= repetitions[0]; i += 1) {
+        for (j = 1; j <= repetitions[1]; j += 1) {
+            for (k = 1; k <= repetitions[2]; k += 1) {
+                // for each atom in original basis add one with a repetition
+                // eslint-disable-next-line no-loop-func
+                basisCloneInCrystalCoordinates.elements.forEach((element, index) => {
+                    const coord = basisCloneInCrystalCoordinates.getCoordinateByIndex(index);
+                    // only add atoms if shifts are non-zero
+                    if (shiftI || shiftJ || shiftK) {
+                        newBasis.addAtom({
+                            element,
+                            coordinate: [coord[0] + shiftI, coord[1] + shiftJ, coord[2] + shiftK],
+                        });
+                    }
+                });
+                shiftK += 1;
+            }
+            shiftK = 0;
+            shiftJ += 1;
+        }
+        shiftJ = 0;
+        shiftI += 1;
+    }
+
+    if (basis.isInCartesianUnits) newBasis.toCartesian();
+
+    return newBasis;
+}
+
+/**
+ * Calculates linear function `y = kx + b` for vectors. Isolated for modularity.
+ * @param initialCoordinates {Array} - b.
+ * @param delta {Array} - x.
+ * @param normalizedStepIndex {Number} - k.
+ * @return {Basis[]} List of all bases.
+ */
+function _linearInterpolation(initialCoordinates, delta, normalizedStepIndex) {
+    return ADD(initialCoordinates, MULT(delta, normalizedStepIndex));
+}
+
+/**
+ * Returns a set of Bases for a crystal interpolated from initial to final crystal.
+ *          Can be used to generate atomic configurations along a chemical reaction path, for example.
+ * @param initialBasis {Basis} Original initialBasis.
+ * @param finalBasis {Basis} Final initialBasis.
+ * @param numberOfSteps{Number} Number of intermediate steps.
+ * @return {Basis[]} List of all bases.
+ */
+function interpolate(initialBasis, finalBasis, numberOfSteps = 1) {
+    // check that initial and final basis have the same cell
+    if (!initialBasis.hasEquivalentCellTo(finalBasis))
+        throw new Error("basis.interpolate: Basis cells are not equal");
+
+    // clone original initialBasis and assert it is in cartesian coordinates
+    const initialBasisCopy = initialBasis.clone();
+    const finalBasisCopy = finalBasis.clone();
+
+    initialBasisCopy.toCrystal();
+    finalBasisCopy.toCrystal();
+
+    const initialCoordinates = _.flatten(initialBasisCopy.coordinatesAsArray);
+    const finalCoordinates = _.flatten(finalBasisCopy.coordinatesAsArray);
+    const delta = ADD(finalCoordinates, MULT(initialCoordinates, -1));
+    const resultingListOfBases = [];
+
+    for (let i = 1; i <= numberOfSteps; i++) {
+        const normalizedStepIndex = i / (numberOfSteps + 1);
+        const intermediateCoordinates = _linearInterpolation(
+            initialCoordinates,
+            delta,
+            normalizedStepIndex,
+        );
+        const vectorSize = 3;
+        const intermediateCoordinatesAsNestedArray = _.toArray(
+            _.groupBy(intermediateCoordinates, (a, b) => Math.floor(b / vectorSize)),
+        );
+        const intermediateBasis = initialBasis.clone();
+        intermediateBasis.coordinates = intermediateCoordinatesAsNestedArray;
+        resultingListOfBases.push(intermediateBasis);
+    }
+
+    return resultingListOfBases;
+}
+
+export default {
+    repeat,
+    interpolate,
+};

package/src/js/tools/cell.js

@@ -0,0 +1,36 @@
+import { Cell } from "../cell/cell";
+import math from "../math";
+
+/**
+ * Returns the list of points on the original lattice contained in the supercell in fractional coordinates.
+ * Source: https://pymatgen.org/_modules/pymatgen/util/coord.html
+ */
+function latticePointsInSupercell(supercellMatrix) {
+    const supercell = new Cell(supercellMatrix);
+    const diagonals = [
+        [0, 0, 0],
+        [0, 0, 1],
+        [0, 1, 0],
+        [0, 1, 1],
+        [1, 0, 0],
+        [1, 0, 1],
+        [1, 1, 0],
+        [1, 1, 1],
+    ];
+    const d_points = diagonals.map((p) => supercell.convertPointToCartesian(p));
+    const mins = [0, 1, 2].map((i) => math.min(...d_points.map((p) => p[i])));
+    const maxes = [0, 1, 2].map((i) => math.max(...d_points.map((p) => p[i])) + 1);
+    const points = [];
+    for (let i = mins[0]; i <= maxes[0]; i++) {
+        for (let j = mins[1]; j <= maxes[1]; j++) {
+            for (let k = mins[2]; k <= maxes[2]; k++) {
+                points.push(supercell.convertPointToFractional([i, j, k]));
+            }
+        }
+    }
+    return points;
+}
+
+export default {
+    latticePointsInSupercell,
+};

package/src/js/tools/index.js

@@ -0,0 +1,11 @@
+import BasisTools from "./basis";
+import MaterialTools from "./material";
+import SupercellTools from "./supercell";
+import SurfaceTools from "./surface";
+
+export default {
+    surface: SurfaceTools,
+    supercell: SupercellTools,
+    material: MaterialTools,
+    basis: BasisTools,
+};

package/src/js/tools/material.js

@@ -0,0 +1,60 @@
+import math from "mathjs";
+
+import { ATOMIC_COORD_UNITS } from "../constants";
+import { Lattice } from "../lattice/lattice";
+
+/**
+ * Scales one lattice vector for the given material
+ * @param material {Material} The material acted upon.
+ * @param key {String} Lattice vector key.
+ * @param factor {Number} Float scaling factor.
+ */
+
+function scaleOneLatticeVector(material, key = "a", factor = 1.0) {
+    material.toCartesian();
+
+    const { lattice } = material;
+    lattice[key] *= factor;
+
+    material.lattice = lattice;
+
+    material.toCrystal();
+}
+
+/**
+ * Updates the size of a materials lattice using the minimumLatticeSize function.
+ * The new size of the material is calculated based on the materials basis.
+ * @param material {Material}
+ */
+function scaleLatticeToMakeNonPeriodic(material) {
+    material.lattice = new Lattice({
+        a: material.Basis.getMinimumLatticeSize(),
+        type: "CUB",
+    });
+}
+
+/**
+ * Updates the basis of a material by translating the coordinates
+ * so that the center of the material and lattice are aligned.
+ * @param material {Material}
+ * */
+function getBasisConfigTranslatedToCenter(material) {
+    const originalUnits = material.Basis.units;
+    material.toCartesian();
+    const updatedBasis = material.Basis;
+    const centerOfCoordinates = updatedBasis.centerOfCoordinatesPoint;
+    const centerOfLattice = math.multiply(
+        0.5,
+        material.Lattice.vectorArrays.reduce((a, b) => math.add(a, b)),
+    );
+    const translationVector = math.subtract(centerOfLattice, centerOfCoordinates);
+    updatedBasis.translateByVector(translationVector);
+    material.setBasis(updatedBasis.toJSON());
+    if (originalUnits !== ATOMIC_COORD_UNITS.cartesian) material.toCrystal();
+}
+
+export default {
+    scaleOneLatticeVector,
+    scaleLatticeToMakeNonPeriodic,
+    getBasisConfigTranslatedToCenter,
+};

package/src/js/tools/supercell.ts

@@ -0,0 +1,80 @@
+import { Basis } from "../basis/basis";
+import { Coordinate } from "../basis/types";
+import { Cell } from "../cell/cell";
+import { LatticeBravais } from "../lattice/lattice_bravais";
+// eslint-disable-next-line import/no-cycle
+import { Material } from "../material";
+import math from "../math";
+import cellTools from "./cell";
+
+const ADD = math.add;
+
+/**
+ * @summary Generates new basis for a supercell. For each site from basis generates shifts that are within supercell.
+ */
+function generateNewBasisWithinSupercell(
+    basis: Basis,
+    cell: Cell,
+    supercell: Cell,
+    supercellMatrix: number[][],
+): Basis {
+    const oldBasis = basis.clone();
+    const newBasis = basis.clone({ isEmpty: true });
+
+    oldBasis.toCrystal();
+    newBasis.toCrystal();
+
+    oldBasis.elements.forEach((element) => {
+        const coordinate = oldBasis.getCoordinateByIndex(element.id);
+        const cartesianCoordinate = cell.convertPointToCartesian(coordinate);
+        const shifts = cellTools.latticePointsInSupercell(supercellMatrix);
+        shifts.forEach((comb) => {
+            // "combination" is effectively a point in fractional coordinates here, hence the below
+            const newPoint = ADD(cartesianCoordinate, supercell.convertPointToCartesian(comb));
+            if (supercell.isPointInsideCell(newPoint)) {
+                newBasis.addAtom({
+                    element: element.value,
+                    coordinate: supercell.convertPointToFractional(newPoint) as Coordinate,
+                });
+            }
+        });
+    });
+
+    return newBasis;
+}
+
+/**
+ * @summary Generates supercell config for the specified material.
+ * @param material
+ * @param supercellMatrix {Number[][]}
+ */
+function generateConfig(material: Material, supercellMatrix: number[][]) {
+    const det = math.det(supercellMatrix);
+    if (det === 0) {
+        throw new Error("Scaling matrix is degenerate.");
+    }
+    const cell = material.Lattice.Cell;
+    const supercell = cell.cloneAndScaleByMatrix(supercellMatrix);
+    const newBasis = generateNewBasisWithinSupercell(
+        material.Basis,
+        cell,
+        supercell,
+        supercellMatrix,
+    );
+    const newLattice = LatticeBravais.fromVectors({
+        a: supercell.vector1,
+        b: supercell.vector2,
+        c: supercell.vector3,
+    });
+
+    return {
+        name: `${material.name} - supercell ${JSON.stringify(supercellMatrix)}`,
+        basis: newBasis.toJSON(),
+        lattice: newLattice.toJSON(),
+    };
+}
+
+export default {
+    generateConfig,
+    generateNewBasisWithinSupercell,
+};