@mat3ra/made 2026.8.7-0 → 2026.8.18-0

package/src/js/tools/basis.ts

@@ -1,132 +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,41 +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,62 +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.lattice = 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.lattice = Lattice.fromConfigPartial({
-        a: material.Basis.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 originalUnits = material.Basis.units;
-    material.toCartesian();
-    const updatedBasis = material.Basis;
-    const centerOfCoordinates = updatedBasis.centerOfCoordinatesPoint;
-    const centerOfLattice = Utils.math.multiply(
-        0.5,
-        material.Lattice.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,88 +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 { 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.
- * @param material
- * @param supercellMatrix {Number[][]}
- */
-function generateConfig(material: Material, supercellMatrix: Matrix3X3Schema) {
-    const det = Utils.math.det(supercellMatrix);
-    if (det === 0) {
-        throw new Error("Scaling matrix is degenerate.");
-    }
-    const cell = material.Lattice.vectors;
-    const supercell = cell.cloneAndScaleByMatrix(supercellMatrix);
-    const newBasis = generateNewBasisWithinSupercell(
-        material.Basis,
-        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,
-};

package/src/js/tools/surface.ts

@@ -1,223 +0,0 @@
-import {
-    Coordinate3DSchema,
-    MaterialSchema,
-    Matrix3X3Schema,
-    Vector3DSchema,
-} from "@mat3ra/esse/dist/js/types";
-import { Utils } from "@mat3ra/utils";
-
-import { Cell } from "../cell/cell";
-import { Lattice } from "../lattice/lattice";
-import { Material } from "../material";
-import SupercellTools from "./supercell";
-
-const MULT = Utils.math.multiply;
-const ADD = Utils.math.add;
-const DOT = Utils.math.product;
-const getMatrixInLeftHandedRepresentation = (matrix: Matrix3X3Schema) => {
-    return Utils.math.det(matrix) < 0 ? MULT(matrix, -1) : matrix;
-};
-
-/**
- * Helper function for extended GCD.
- * Inspired by https://gitlab.com/ase/ase/-/blob/20401e2596821a85f17ced1cb18f32c508e35fb0/ase/build/general_surface.py
- * @param {Number} a
- * @param {Number} b
- * @return {Array}
- */
-function extGCD(a: number, b: number): [number, number] {
-    if (b === 0) return [1, 0];
-    if (Utils.math.mod(a, b) === 0) return [0, 1];
-
-    const [x, y] = extGCD(b, Utils.math.mod(a, b));
-    return [y, x - y * Utils.math.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: Cell,
-    millerIndices: Coordinate3DSchema,
-    tol = 1e-8,
-): Matrix3X3Schema {
-    if (!millerIndices.reduce((a, b) => Utils.math.abs(a) + Utils.math.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.vectorArrays;
-        // z1 = (k * a1 - h * a2)
-        // z2 = (l * a1 - h * a3)
-        // z3 = l * a2 - k * a3)
-        const z1 = ADD(MULT(k, a1), -MULT(h, a2));
-        const z2 = ADD(MULT(l, a1), -MULT(h, a3));
-        const z3 = ADD(MULT(l, a2), -MULT(k, a3));
-
-        let [p, q] = extGCD(k, l);
-
-        // @ts-ignore
-        const k1 = DOT(ADD(MULT(p, z1), MULT(q, z2)), z3);
-        // @ts-ignore
-        const k2 = DOT(ADD(MULT(l, z1), -MULT(k, z2)), z3);
-
-        // @ts-ignore
-        if (Utils.math.abs(k2) > tol) {
-            // For mathjs version 3.20: round(-0.5) = -0
-            // For mathjs version 5.10: round(-0.5) = -1
-            // Here we specify rounding method to Bankers
-            // For Python 3.11: round(-0.5) = 0
-            // @ts-ignore - mathjs v12 dot return type
-            const value = k1 / k2;
-            const roundedValue = Utils.math.roundCustom(
-                value,
-                0,
-                Utils.math.RoundingMethod.Bankers,
-            );
-            const i = -roundedValue;
-            [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) => Utils.math.trunc(c / Utils.math.gcd(l, k))); // floor division
-        const c3 = [b, a * p, a * q];
-
-        scalingMatrix = [c1, c2, c3];
-    }
-
-    // @ts-ignore
-    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(
-    outOfPlaneAxisIndex: number,
-    thickness: number,
-    vx: number,
-    vy: number,
-): Matrix3X3Schema {
-    const transformationMatrix = [
-        [1, 0, 0],
-        [0, 1, 0],
-        [0, 0, 1],
-    ] as Matrix3X3Schema;
-    const vxIndex = outOfPlaneAxisIndex === 2 ? 0 : outOfPlaneAxisIndex + 1;
-    const vyIndex = vxIndex === 2 ? 0 : vxIndex + 1;
-
-    transformationMatrix[outOfPlaneAxisIndex] = MULT(
-        thickness,
-        transformationMatrix[outOfPlaneAxisIndex],
-    ) as Vector3DSchema;
-    transformationMatrix[vxIndex] = MULT(vx, transformationMatrix[vxIndex]) as Vector3DSchema;
-    transformationMatrix[vyIndex] = MULT(vy, transformationMatrix[vyIndex]) as Vector3DSchema;
-
-    return transformationMatrix as Matrix3X3Schema;
-}
-
-export type SlabConfigSchema = MaterialSchema & {
-    outOfPlaneAxisIndex: number;
-};
-
-/*
- * 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: Material,
-    millerIndices: Coordinate3DSchema,
-    numberOfLayers = 1,
-    vx = 1,
-    vy = 1,
-): SlabConfigSchema {
-    if (numberOfLayers < 1)
-        throw new Error("Made.tools.surface.generateConfig: number of layers < 1.");
-
-    const cell = material.Lattice.vectors;
-    const millerScalingMatrix = getMillerScalingMatrix(cell, millerIndices);
-    const millerSupercell = cell.cloneAndScaleByMatrix(millerScalingMatrix);
-    const millerPlanePseudoNormal = cell.convertPointToCartesian(millerIndices);
-    const outOfPlaneAxisIndex =
-        millerSupercell.getMostCollinearVectorIndex(millerPlanePseudoNormal);
-    const dimensionsScalingMatrix = getDimensionsScalingMatrix(
-        outOfPlaneAxisIndex,
-        numberOfLayers,
-        vx,
-        vy,
-    );
-    const supercellMatrix = MULT(dimensionsScalingMatrix, millerScalingMatrix);
-    const supercell = millerSupercell.cloneAndScaleByMatrix(dimensionsScalingMatrix);
-    const tempBasis = material.Basis.clone();
-    const newBasis = SupercellTools.generateNewBasisWithinSupercell(
-        tempBasis,
-        cell,
-        supercell,
-        supercellMatrix as Matrix3X3Schema,
-    );
-    const newLattice = Lattice.fromVectors({
-        a: supercell.vectorArrays[0],
-        b: supercell.vectorArrays[1],
-        c: supercell.vectorArrays[2],
-    });
-
-    return {
-        name: `${material.name} - slab ${JSON.stringify(millerIndices)}`,
-        basis: newBasis.toJSON(),
-        lattice: newLattice.toJSON(),
-        // extra parameter for use in creating vacuum etc.
-        outOfPlaneAxisIndex,
-        metadata: {},
-    };
-}
-
-export default {
-    generateConfig,
-};

package/src/py/mat3ra/__init__.py

@@ -1 +0,0 @@
-__path__ = __import__("pkgutil").extend_path(__path__, __name__)

package/src/py/mat3ra/made/__init__.py

@@ -1,7 +0,0 @@
-import warnings
-
-from pydantic.warnings import PydanticDeprecatedSince20
-
-warnings.filterwarnings("ignore", category=DeprecationWarning, module="typing_extensions")
-warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")
-warnings.filterwarnings("ignore", category=PydanticDeprecatedSince20)