@mat3ra/made 2026.8.13-0 → 2026.8.26-0

package/src/js/parsers/xyz_combinatorial_basis.ts

@@ -1,268 +0,0 @@
-import { BasisSchema } from "@mat3ra/esse/dist/js/types";
-import { Utils } from "@mat3ra/utils";
-import { chain, last, map } from "lodash";
-import * as s from "underscore.string";
-
-import { ElementsAndCoordinatesConfig } from "../basis/basis";
-import { AtomicCoordinateValue } from "../basis/coordinates";
-import { AtomicElementValue } from "../basis/elements";
-import { Cell } from "../cell/cell";
-
-/**
- * @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,
-};
-
-// TODO: rename `coordinates` to `coordinate`
-export type ElementWithCoordinate = {
-    element: AtomicElementValue;
-    coordinate: AtomicCoordinateValue;
-};
-
-export class WrongBasisFormat extends Error {
-    xyz: string;
-
-    constructor(xyz: string, message: string, code: number) {
-        super(message);
-        this.xyz = xyz;
-        console.log(`Wrong basis format: ${message}, code: ${code}`);
-    }
-}
-
-export class CombinatorialBasis {
-    _xyz: string;
-
-    _lines: any[];
-
-    _hasPermutationLine: boolean;
-
-    _hasCombinationLine: boolean;
-
-    constructor(eXYZ: string) {
-        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: string, index: number) {
-        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 coordinate = [parseFloat(words[1]), parseFloat(words[2]), parseFloat(words[3])];
-
-        return {
-            // TODO: define as a type
-            displayName: `ELEMENT_${index}`,
-            isCombination: containsCombination,
-            isPermutation: containsPermutation,
-            elements,
-            coordinate,
-        };
-    }
-
-    /**
-     * Returns array of ALL unique elements used in basis.
-     * @return {String[]}
-     */
-    get uniqueElements() {
-        return chain(this._lines)
-            .map((line) => line.elements)
-            .flatten()
-            .uniq()
-            .value()
-            .sort();
-    }
-
-    static toBasisConfigForElementsAndCoordinates(
-        array: ElementWithCoordinate[],
-        units = "crystal" as BasisSchema["units"],
-        cell = new Cell(),
-    ): ElementsAndCoordinatesConfig {
-        return {
-            elements: map(array, "element"),
-            coordinates: map(array, "coordinate"),
-            units,
-            cell,
-        };
-    }
-
-    /**
-     * Returns array of regular bases extracted from current combinatorial basis.
-     * @return {Basis[]|Object[]}
-     */
-    get allBasisConfigs() {
-        let result: ElementWithCoordinate[][] = [];
-        if (this._hasPermutationLine) {
-            result = this._permutation();
-        } else if (this._hasCombinationLine) {
-            result = this._combination();
-        } else {
-            const items: ElementWithCoordinate[] = [];
-            this._lines.forEach((line) => {
-                items.push({
-                    element: line.elements[0],
-                    coordinate: line.coordinate,
-                });
-            });
-            result = [items];
-        }
-        return result.map((x) => CombinatorialBasis.toBasisConfigForElementsAndCoordinates(x));
-    }
-
-    /**
-     * Returns array of regular bases extracted from current combinatorial basis with combinations.
-     * @private
-     */
-    _combination(): ElementWithCoordinate[][] {
-        const dimensions: ElementWithCoordinate[][] = [];
-        this._lines.forEach((line) => {
-            const itemsSet: ElementWithCoordinate[] = [];
-            line.elements.forEach((element: AtomicElementValue) => {
-                // omit vacancy characters
-                itemsSet.push({
-                    element,
-                    coordinate: line.coordinate,
-                });
-            });
-            dimensions.push(itemsSet);
-        });
-        // @ts-ignore // We're multiplying objects with math, not numbers. No type casting will help.
-        const basisSet = Utils.math.cartesianProduct.apply(
-            null,
-            // @ts-ignore
-            dimensions,
-        ) as ElementWithCoordinate[][];
-        return basisSet.map((basis: ElementWithCoordinate[]) =>
-            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: ElementWithCoordinate[] = [];
-            this._lines.forEach((line) => {
-                const element = line.elements.length <= i ? last(line.elements) : line.elements[i];
-                if (element !== VACANCY_CHARACTER) {
-                    items.push({
-                        element,
-                        coordinate: line.coordinate,
-                    });
-                }
-            });
-            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.ts

@@ -1,131 +0,0 @@
-import { Coordinate3DSchema } from "@mat3ra/esse/dist/js/types";
-import { Utils } from "@mat3ra/utils";
-import { chunk, flatten } from "lodash";
-
-import { Basis } from "../basis/basis";
-import { AtomicCoordinateValue, Coordinate } from "../basis/coordinates";
-
-const ADD = Utils.math.add;
-const MULT = Utils.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: Basis, repetitions: number[]): Basis {
-    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.getCoordinateValueByIndex(index);
-                    // only add atoms if shifts are non-zero
-                    if (shiftI || shiftJ || shiftK) {
-                        const coordinateInstance = Coordinate.fromValueAndId(coord);
-                        const translatedCoordinateInstance = coordinateInstance.translateByVector([
-                            shiftI,
-                            shiftJ,
-                            shiftK,
-                        ]);
-                        newBasis.addAtom({
-                            element: element.value,
-                            coordinate: translatedCoordinateInstance.value,
-                        });
-                    }
-                });
-                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 initialCoordinate {Array} - b.
- * @param delta {Array} - x.
- * @param normalizedStepIndex {Number} - k.
- * @return {Basis[]} List of all bases.
- */
-function _linearInterpolation(
-    initialCoordinate: AtomicCoordinateValue,
-    delta: Coordinate3DSchema,
-    normalizedStepIndex: number,
-): number[] {
-    return ADD(initialCoordinate, MULT(delta, normalizedStepIndex)) as number[];
-}
-
-/**
- * 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: Basis, finalBasis: Basis, 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: number[] = _linearInterpolation(
-            initialCoordinates as AtomicCoordinateValue,
-            delta as AtomicCoordinateValue,
-            normalizedStepIndex,
-        );
-        const vectorSize = 3;
-        const intermediateCoordinatesAsNestedArray = chunk(intermediateCoordinates, vectorSize);
-        const intermediateBasis = initialBasis.clone();
-        intermediateBasis.coordinates = intermediateCoordinatesAsNestedArray.map(
-            (coordinate, index) => ({
-                id: index,
-                value: coordinate as AtomicCoordinateValue,
-            }),
-        );
-
-        resultingListOfBases.push(intermediateBasis);
-    }
-
-    return resultingListOfBases;
-}
-
-export default {
-    repeat,
-    interpolate,
-};

package/src/js/tools/cell.ts

@@ -1,40 +0,0 @@
-import { Coordinate3DSchema, Matrix3X3Schema } from "@mat3ra/esse/dist/js/types";
-import { Utils } from "@mat3ra/utils";
-
-import { Cell } from "../cell/cell";
-
-/**
- * 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: Matrix3X3Schema) {
-    const supercell = Cell.fromVectorsArray(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((point) =>
-        supercell.convertPointToCartesian(point as Coordinate3DSchema),
-    );
-    const mins = [0, 1, 2].map((i) => Utils.math.min(...d_points.map((p) => p[i])));
-    const maxes = [0, 1, 2].map((i) => Utils.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.convertPointToCrystal([i, j, k]));
-            }
-        }
-    }
-    return points;
-}
-
-export default {
-    latticePointsInSupercell,
-};

package/src/js/tools/index.ts

@@ -1,11 +0,0 @@
-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.ts

@@ -1,64 +0,0 @@
-import { LatticeSchema, Vector3DSchema } from "@mat3ra/esse/dist/js/types";
-import { Utils } from "@mat3ra/utils";
-
-import { ATOMIC_COORD_UNITS } from "../constants";
-import { Lattice } from "../lattice/lattice";
-import Material from "../Material";
-
-/**
- * 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: Material, key: "a" | "b" | "c" = "a", factor = 1.0) {
-    const lattice = { ...material.lattice };
-    if (lattice.vectors === undefined) {
-        throw new Error("Lattice vectors are undefined");
-    }
-    lattice.vectors[key] = lattice.vectors[key].map((v) => v * factor) as Vector3DSchema;
-
-    material.setLattice(Lattice.fromVectors(lattice.vectors).toJSON());
-}
-
-/**
- * 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) {
-    material.setLattice(
-        Lattice.fromConfigPartial({
-            a: material.getBasis().getMinimumLatticeSize(),
-            type: "CUB",
-        } as LatticeSchema).toJSON(),
-    );
-}
-
-/**
- * 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 translateAtomsToCenter(material: Material) {
-    const basis = material.getBasis();
-    const originalUnits = basis.units;
-    material.toCartesian();
-    const updatedBasis = basis.toCartesian();
-    const centerOfCoordinates = updatedBasis.centerOfCoordinatesPoint;
-    const centerOfLattice = Utils.math.multiply(
-        0.5,
-        material.getLattice().vectorArrays.reduce((a, b) => Utils.math.add(a, b) as Vector3DSchema),
-    );
-    const translationVector = Utils.math.subtract(centerOfLattice, centerOfCoordinates);
-    updatedBasis.translateByVector(translationVector as Vector3DSchema);
-    material.setBasis(updatedBasis.toJSON());
-    if (originalUnits !== ATOMIC_COORD_UNITS.cartesian) material.toCrystal();
-}
-
-export default {
-    scaleOneLatticeVector,
-    scaleLatticeToMakeNonPeriodic,
-    translateAtomsToCenter,
-};

package/src/js/tools/supercell.ts

@@ -1,89 +0,0 @@
-import { Coordinate3DSchema, Matrix3X3Schema } from "@mat3ra/esse/dist/js/types";
-import { Utils } from "@mat3ra/utils";
-
-import { Basis } from "../basis/basis";
-import { ConstrainedBasis } from "../basis/constrained_basis";
-import { Cell } from "../cell/cell";
-import { Lattice } from "../lattice/lattice";
-import type { MaterialSchemaMap } from "../Material";
-import type Material from "../Material";
-import cellTools from "./cell";
-
-const ADD = Utils.math.add;
-
-/**
- * @summary Generates new basis for a supercell. For each site from basis generates shifts that are within supercell.
- */
-function generateNewBasisWithinSupercell(
-    basis: Basis | ConstrainedBasis,
-    cell: Cell,
-    supercell: Cell,
-    supercellMatrix: Matrix3X3Schema,
-): Basis {
-    const oldBasis = basis.clone();
-    const newBasis = basis.clone();
-    newBasis.removeAllAtoms();
-
-    oldBasis.toCrystal();
-    newBasis.toCrystal();
-
-    oldBasis.elements.forEach((element) => {
-        const coordinate = oldBasis.getCoordinateValueById(element.id);
-        const cartesianCoordinate = cell.convertPointToCartesian(coordinate);
-        const shifts = cellTools.latticePointsInSupercell(supercellMatrix);
-        shifts.forEach((combination) => {
-            // "combination" is effectively a point in fractional coordinates here, hence the below
-            const newPoint = ADD(
-                cartesianCoordinate,
-                supercell.convertPointToCartesian(combination),
-            );
-            if (supercell.isPointInsideCell(newPoint as Coordinate3DSchema)) {
-                newBasis.addAtom({
-                    element: element.value,
-                    coordinate: supercell.convertPointToCrystal(
-                        newPoint as Coordinate3DSchema,
-                    ) as Coordinate3DSchema,
-                });
-            }
-        });
-    });
-
-    return newBasis as Basis;
-}
-
-/**
- * @summary Generates supercell config for the specified material.
- */
-function generateConfig<Schemas extends MaterialSchemaMap = MaterialSchemaMap>(
-    material: Material<Schemas>,
-    supercellMatrix: Matrix3X3Schema,
-) {
-    const det = Utils.math.det(supercellMatrix);
-    if (det === 0) {
-        throw new Error("Scaling matrix is degenerate.");
-    }
-    const cell = material.getLattice().vectors;
-    const supercell = cell.cloneAndScaleByMatrix(supercellMatrix);
-    const newBasis = generateNewBasisWithinSupercell(
-        material.getBasis(),
-        cell,
-        supercell,
-        supercellMatrix,
-    );
-    const newLattice = Lattice.fromVectors({
-        a: supercell.a,
-        b: supercell.b,
-        c: supercell.c,
-    });
-
-    return {
-        name: `${material.name} - supercell ${JSON.stringify(supercellMatrix)}`,
-        basis: newBasis.toJSON(),
-        lattice: newLattice.toJSON(),
-    };
-}
-
-export default {
-    generateConfig,
-    generateNewBasisWithinSupercell,
-};