@mat3ra/made 2024.3.22-0

package/dist/parsers/poscar.d.ts

@@ -0,0 +1,31 @@
+import { MaterialJSON } from "../types";
+/**
+ * Obtain a textual representation of a material in POSCAR format.
+ * @param materialOrConfig - material class instance or config object.
+ * @param omitConstraints - whether to discard constraints passed with material.
+ */
+declare function toPoscar(materialOrConfig: MaterialJSON, omitConstraints?: boolean): string;
+/**
+ * @summary calculates the number of atoms in a poscar file based on the summation of the numbers in line 7 of the file.
+ * Poscar file formatting: https://www.vasp.at/wiki/index.php/POSCAR
+ */
+export declare function atomsCount(poscarFileContent: string): number;
+/**
+ * Parses POSCAR file into a Material config object.
+ * @param fileContent - POSCAR file content.
+ * @return Material config.
+ */
+declare function fromPoscar(fileContent: string): object;
+/**
+ * @summary Checks if a string has a POSCAR format (first 8 lines are read)
+ * @param text - string to check
+ */
+declare function isPoscar(text: string): boolean;
+declare const _default: {
+    isPoscar: typeof isPoscar;
+    toPoscar: typeof toPoscar;
+    fromPoscar: typeof fromPoscar;
+    atomicConstraintsCharFromBool: (bool: boolean) => string;
+    atomsCount: typeof atomsCount;
+};
+export default _default;

package/dist/parsers/poscar.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomsCount = void 0;
+const underscore_string_1 = __importDefault(require("underscore.string"));
+const constrained_basis_1 = require("../basis/constrained_basis");
+const constants_1 = require("../constants");
+const lattice_1 = require("../lattice/lattice");
+const math_1 = __importDefault(require("../math"));
+const _print = (x, printFormat = "%14.9f") => underscore_string_1.default.sprintf(printFormat, math_1.default.precise(x));
+const _latticeVectorsToString = (vectors) => vectors.map((v) => v.map((c) => _print(c)).join("\t")).join("\n");
+const atomicConstraintsCharFromBool = (bool) => (bool ? "T" : "F");
+/**
+ * Obtain a textual representation of a material in POSCAR format.
+ * @param materialOrConfig - material class instance or config object.
+ * @param omitConstraints - whether to discard constraints passed with material.
+ */
+function toPoscar(materialOrConfig, omitConstraints = false) {
+    const lattice = new lattice_1.Lattice(materialOrConfig.lattice);
+    const vectorsAsString = _latticeVectorsToString(lattice.vectorArrays);
+    // @ts-ignore
+    const basis = new constrained_basis_1.ConstrainedBasis({
+        ...materialOrConfig.basis,
+        cell: lattice.vectorArrays,
+    });
+    const BasisLines = [];
+    let addSelectiveDynamics = false;
+    basis._elements.array.forEach((item, idx) => {
+        const coord = basis.getCoordinateByIndex(idx).map((x) => _print(x));
+        const constraintsAsString = omitConstraints
+            ? ""
+            : basis.AtomicConstraints.getAsStringByIndex(idx, atomicConstraintsCharFromBool);
+        if (constraintsAsString && !omitConstraints)
+            addSelectiveDynamics = true;
+        BasisLines.push([coord.join(" "), constraintsAsString, item].join(" "));
+    });
+    const basisContent = BasisLines.join("\n");
+    const elementsLine = basis.elementCounts.map((e) => e.value).join(" ");
+    const countsLine = basis.elementCounts.map((e) => parseInt(`${e.count}`, 10)).join(" ");
+    const coordsType = materialOrConfig.basis.units === constants_1.ATOMIC_COORD_UNITS.cartesian ? "cartesian" : "direct";
+    return [
+        materialOrConfig.name,
+        "1.0",
+        vectorsAsString,
+        elementsLine,
+        countsLine,
+        // add selective dynamics only if there are some constraints!
+        ...(addSelectiveDynamics ? ["Selective dynamics"] : []),
+        coordsType,
+        basisContent,
+    ].join("\n");
+}
+/**
+ * @summary calculates the number of atoms in a poscar file based on the summation of the numbers in line 7 of the file.
+ * Poscar file formatting: https://www.vasp.at/wiki/index.php/POSCAR
+ */
+function atomsCount(poscarFileContent) {
+    const atomsLine = poscarFileContent.split("\n")[6].split(/\s+/);
+    return atomsLine.map((x) => parseInt(x, 10)).reduce((a, b) => a + b);
+}
+exports.atomsCount = atomsCount;
+/**
+ * Parses POSCAR file into a Material config object.
+ * @param fileContent - POSCAR file content.
+ * @return Material config.
+ */
+function fromPoscar(fileContent) {
+    const lines = fileContent.split("\n");
+    const comment = lines[0];
+    const latticeConstant = parseFloat(lines[1].trim());
+    // Atom symbols and counts
+    const atomSymbols = lines[5].trim().split(/\s+/);
+    const atomCounts = lines[6].trim().split(/\s+/).map(Number);
+    // Check if selective dynamics and coordinates type is used
+    let selectiveDynamics = false;
+    let coordinateType = "";
+    let startLine = 7;
+    if (lines[startLine].trim()[0].toLowerCase() === "s") {
+        selectiveDynamics = true;
+        coordinateType = lines[8].trim()[0].toLowerCase();
+        startLine = 9;
+    }
+    else {
+        coordinateType = lines[7].trim()[0].toLowerCase();
+        startLine = 8;
+    }
+    const elements = atomSymbols
+        .map((symbol, i) => Array(atomCounts[i]).fill(symbol))
+        .reduce((a, b) => a.concat(b), []);
+    // Atom coordinates and constraints
+    const coordinates = [];
+    const constraints = [];
+    let atomIndex = 0;
+    for (let i = 0; i < atomSymbols.length; i++) {
+        for (let j = 0; j < atomCounts[i]; j++) {
+            const lineComponents = lines[startLine + atomIndex].trim().split(/\s+/);
+            const coordinate = [
+                parseFloat(lineComponents[0]),
+                parseFloat(lineComponents[1]),
+                parseFloat(lineComponents[2]),
+            ];
+            coordinates.push(coordinate);
+            // Add constraints if selective dynamics is used
+            if (selectiveDynamics) {
+                const constraint = [
+                    lineComponents[3] === "T",
+                    lineComponents[4] === "T",
+                    lineComponents[5] === "T",
+                ];
+                constraints.push({ id: j, value: constraint });
+            }
+            atomIndex += 1;
+        }
+    }
+    const lattice = lattice_1.Lattice.fromVectors({
+        a: lines[2].trim().split(/\s+/).map(Number),
+        b: lines[3].trim().split(/\s+/).map(Number),
+        c: lines[4].trim().split(/\s+/).map(Number),
+        alat: latticeConstant,
+        units: "angstrom",
+    });
+    const basis = new constrained_basis_1.ConstrainedBasis({
+        elements,
+        coordinates,
+        units: coordinateType === "c" ? constants_1.ATOMIC_COORD_UNITS.cartesian : constants_1.ATOMIC_COORD_UNITS.crystal,
+        cell: lattice.vectorArrays,
+        constraints,
+    });
+    const materialConfig = {
+        lattice: lattice.toJSON(),
+        basis: basis.toJSON(),
+        name: comment,
+        isNonPeriodic: false,
+    };
+    return materialConfig;
+}
+/**
+ * @summary Checks if a string has a POSCAR format (first 8 lines are read)
+ * @param text - string to check
+ */
+function isPoscar(text) {
+    const lines = text.split("\n");
+    // Checking number of lines, minimum requirement for POSCAR
+    if (lines.length < 7) {
+        return false;
+    }
+    // Check the lattice constant (a single floating point number)
+    if (!/^[+-]?[\d.]+$/.test(lines[1].trim())) {
+        return false;
+    }
+    // Check the lattice vectors (three lines, each with three floating point numbers)
+    for (let i = 2; i <= 4; i++) {
+        if (!/^[-+]?\d*\.\d+\s+[-+]?\d*\.\d+\s+[-+]?\d*\.\d+$/.test(lines[i].trim())) {
+            return false;
+        }
+    }
+    // Check the atomic species line (alphabetic characters, space-separated)
+    if (!/^[a-zA-Z\s]+$/.test(lines[5].trim())) {
+        return false;
+    }
+    // Check the number of atoms per species line (digits, space-separated)
+    if (!/^[\d\s]+$/.test(lines[6].trim())) {
+        return false;
+    }
+    // Check the coordinate type line (only first character is neccessary, "s" or "S" for "Selective dynamics",
+    // "d" or "D" for "Direct", or "c" or "C" for "Cartesian")
+    if (!/^[sdc]/.test(lines[7].trim().toLowerCase())) {
+        return false;
+    }
+    return true;
+}
+exports.default = {
+    isPoscar,
+    toPoscar,
+    fromPoscar,
+    atomicConstraintsCharFromBool,
+    atomsCount,
+};

package/dist/parsers/xyz.d.ts

@@ -0,0 +1,62 @@
+import { MaterialSchema } from "@mat3ra/esse/lib/js/types";
+import { ConstrainedBasis } from "../basis/constrained_basis";
+import { Constraint } from "../constraints/constraints";
+import { Vector } from "../lattice/types";
+import { CombinatorialBasis } from "./xyz_combinatorial_basis";
+/**
+ * Validates that passed string is well-formed XYZ file.
+ */
+export declare function validate(xyzTxt: string): void;
+export interface ParsedObject {
+    element: string;
+    coordinates: Vector;
+    constraints: [boolean, boolean, boolean];
+    label?: number;
+}
+export interface BasisConfig {
+    elements: {
+        id: number;
+        value: string;
+    }[];
+    labels?: {
+        id: number;
+        value: number;
+    }[];
+    coordinates: {
+        id: number;
+        value: Vector;
+    }[];
+    units: string;
+    cell: Vector[];
+    constraints: Constraint[];
+}
+/**
+ * Parse XYZ text for basis.
+ * @param txt Text
+ * @param units Coordinate units
+ * @param cell Basis Cell
+ */
+declare function toBasisConfig(txt: string, units?: string, cell?: [import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema, import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema, import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema]): BasisConfig;
+/**
+ * Create XYZ from Basis class instance.
+ * @param basisClsInstance Basis class instance.
+ * @param printFormat Output format for coordinates.
+ * @param skipRounding Whether to round the numbers (ie. to avoid negative zeros).
+ * @return Basis string in XYZ format
+ */
+declare function fromBasis(basisClsInstance: ConstrainedBasis, printFormat?: string, skipRounding?: boolean): string;
+/**
+ * Create XYZ from Material class instance (or its JSON config).
+ * @param materialOrConfig Material.
+ * @param fractional Coordinate units as fractional.
+ * @return Class Instance
+ */
+declare function fromMaterial(materialOrConfig: MaterialSchema, fractional?: boolean): string;
+declare const _default: {
+    validate: typeof validate;
+    fromMaterial: typeof fromMaterial;
+    toBasisConfig: typeof toBasisConfig;
+    fromBasis: typeof fromBasis;
+    CombinatorialBasis: typeof CombinatorialBasis;
+};
+export default _default;

package/dist/parsers/xyz.js

@@ -0,0 +1,167 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = void 0;
+const underscore_1 = __importDefault(require("underscore"));
+const underscore_string_1 = __importDefault(require("underscore.string"));
+const basis_1 = require("../basis/basis");
+const constrained_basis_1 = require("../basis/constrained_basis");
+const lattice_1 = require("../lattice/lattice");
+const math_1 = __importDefault(require("../math"));
+const errors_1 = require("./errors");
+const xyz_combinatorial_basis_1 = require("./xyz_combinatorial_basis");
+// Regular expression for an XYZ line with atomic constraints, eg. Si    0.000000    0.500000    0.446678 1 1 1`
+// eslint-disable-next-line max-len
+const XYZ_LINE_REGEX = /[A-Z][a-z]?(\d)?\s+((-?\d+\.?\d*|\.\d+)\s+(-?\d+\.?\d*|\.\d+)\s+(-?\d+\.?\d*|\.\d+)(\s+)?(\s+[0-1]\s+[0-1]\s+[0-1](\s+)?)?)$/;
+/**
+ * Validates XYZ file's line. Line should be in following format "Si 0.5 0.5 0.5".
+ * Raises an error if line is in wrong format.
+ */
+function validateLine(xyzLine, index) {
+    const words = xyzLine.split(" ").filter((x) => x.trim() !== "");
+    if (!xyzLine.match(XYZ_LINE_REGEX)) {
+        throw new errors_1.InvalidLineError(index, xyzLine);
+    }
+    const coordinates = [parseFloat(words[1]), parseFloat(words[2]), parseFloat(words[3])];
+    coordinates.forEach((num, i) => {
+        if (underscore_1.default.isNaN(num)) {
+            throw new Error(`Coordinates should be a number. Possible error in ${i} coordinate`);
+        }
+    });
+}
+/**
+ * Validates that passed string is well-formed XYZ file.
+ */
+function validate(xyzTxt) {
+    // The @types/underscore.string package does not provide interfaces for function chaining at the moment. Disable TS here
+    // @ts-ignore
+    (0, underscore_string_1.default)(xyzTxt)
+        .trim()
+        .lines()
+        .filter((x) => x.trim() !== "")
+        .forEach(validateLine);
+}
+exports.validate = validate;
+/**
+ * Parses XYZ line and returns an object.
+ * @param line - line of text
+ */
+function _parseXYZLineAsWords(line) {
+    const words = underscore_string_1.default.words(line);
+    const elementWithOptionalLabel = words[0];
+    const element = elementWithOptionalLabel.replace(/\d$/, ""); // Fe1 => Fe
+    const constraint = (n) => parseInt(`${n}`, 10) !== 0;
+    const basisLineConfig = {
+        element,
+        coordinates: [+words[1], +words[2], +words[3]],
+        // Below maps zero values to false (atom is fixed) and non-zero values to true (atom is moving)
+        constraints: [constraint(+words[4]), constraint(+words[5]), constraint(+words[6])],
+    };
+    if (elementWithOptionalLabel !== element) {
+        return {
+            ...basisLineConfig,
+            label: parseInt(elementWithOptionalLabel[elementWithOptionalLabel.length - 1], 10),
+        };
+    }
+    return basisLineConfig;
+}
+/**
+ * Parse XYZ text for basis.
+ * @param txt Text
+ * @param units Coordinate units
+ * @param cell Basis Cell
+ */
+function toBasisConfig(txt, units = "angstrom", cell = basis_1.Basis.defaultCell) {
+    // @ts-ignore
+    const lines = (0, underscore_string_1.default)(txt).trim().lines();
+    const listOfObjects = underscore_1.default.map(lines, _parseXYZLineAsWords);
+    const basisConfig = {
+        elements: listOfObjects.map((elm, idx) => {
+            return {
+                id: idx,
+                value: elm.element,
+            };
+        }),
+        coordinates: listOfObjects.map((elm, idx) => {
+            return {
+                id: idx,
+                value: elm.coordinates,
+            };
+        }),
+        units,
+        cell,
+        constraints: listOfObjects.map((elm, idx) => {
+            return {
+                id: idx,
+                value: elm.constraints,
+            };
+        }),
+    };
+    const labels = [];
+    listOfObjects.forEach((elm, idx) => {
+        if (elm.label) {
+            labels.push({
+                id: idx,
+                value: elm.label,
+            });
+        }
+    });
+    if (!underscore_1.default.isEmpty(labels)) {
+        return {
+            ...basisConfig,
+            labels,
+        };
+    }
+    return basisConfig;
+}
+/**
+ * Create XYZ from Basis class instance.
+ * @param basisClsInstance Basis class instance.
+ * @param printFormat Output format for coordinates.
+ * @param skipRounding Whether to round the numbers (ie. to avoid negative zeros).
+ * @return Basis string in XYZ format
+ */
+function fromBasis(basisClsInstance, printFormat = "%9.5f", skipRounding = false) {
+    const XYZArray = [];
+    basisClsInstance._elements.array.forEach((item, idx) => {
+        // assume that _elements and _coordinates are indexed equivalently
+        const atomicLabel = basisClsInstance.atomicLabelsArray[idx];
+        const elementWithLabel = item + atomicLabel;
+        const element = underscore_string_1.default.sprintf("%-3s", elementWithLabel);
+        const coordinates = basisClsInstance.getCoordinateByIndex(idx).map((x) => {
+            return underscore_string_1.default.sprintf(printFormat, skipRounding ? x : math_1.default.precise(math_1.default.roundToZero(x)));
+        });
+        const constraints = basisClsInstance.constraints
+            ? basisClsInstance.AtomicConstraints.getAsStringByIndex(idx)
+            : "";
+        XYZArray.push([element, coordinates.join(" "), constraints].join(" "));
+    });
+    return `${XYZArray.join("\n")}\n`;
+}
+/**
+ * Create XYZ from Material class instance (or its JSON config).
+ * @param materialOrConfig Material.
+ * @param fractional Coordinate units as fractional.
+ * @return Class Instance
+ */
+function fromMaterial(materialOrConfig, fractional = false) {
+    const lattice = new lattice_1.Lattice(materialOrConfig.lattice);
+    // @ts-ignore
+    const basis = new constrained_basis_1.ConstrainedBasis({
+        ...materialOrConfig.basis,
+        cell: lattice.vectorArrays,
+    });
+    if (fractional) {
+        basis.toCrystal();
+    }
+    return fromBasis(basis, "%11.6f");
+}
+exports.default = {
+    validate,
+    fromMaterial,
+    toBasisConfig,
+    fromBasis,
+    CombinatorialBasis: xyz_combinatorial_basis_1.CombinatorialBasis,
+};

package/dist/parsers/xyz_combinatorial_basis.d.ts

@@ -0,0 +1,64 @@
+export class WrongBasisFormat extends Error {
+    constructor(xyz: any, message: any, type: any);
+    xyz: any;
+}
+export class CombinatorialBasis {
+    static toBasisConfig(array: any, units?: string, cell?: [import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema, import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema, import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema]): {
+        elements: any[];
+        coordinates: any[];
+        units: string;
+        cell: [import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema, import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema, import("@mat3ra/esse/lib/js/types").ArrayOf3NumberElementsSchema];
+    };
+    /**
+     * Creates Combinatorial basis
+     * @param eXYZ
+     */
+    constructor(eXYZ: any);
+    _xyz: any;
+    _lines: {
+        displayName: string;
+        isCombination: boolean;
+        isPermutation: boolean;
+        elements: any[];
+        coordinates: any[];
+    }[];
+    _hasPermutationLine: boolean;
+    _hasCombinationLine: boolean;
+    /**
+     * 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
+     */
+    private _parseBasisLine;
+    /**
+     * Returns array of ALL unique elements used in basis.
+     * @return {String[]}
+     */
+    get uniqueElements(): string[];
+    /**
+     * Returns array of regular bases extracted from current combinatorial basis.
+     * @return {Basis[]|Object[]}
+     */
+    get allBasisConfigs(): Object[] | Basis[];
+    /**
+     * Returns array of regular bases extracted from current combinatorial basis with combinations.
+     * @private
+     */
+    private _combination;
+    /**
+     * Returns array of regular bases extracted from current combinatorial basis with permutations.
+     * @return {Basis[]}
+     * @private
+     */
+    private _permutation;
+    /**
+     * Returns true if current combinatorial basis contains more than one regular basis.
+     * @return {Boolean}
+     */
+    isCombinatorial(): boolean;
+}
+import { Basis } from "../basis/basis";