@mat3ra/wode 2026.5.23-0 → 2026.6.5-0

package/src/js/context/providers/PointsGrid/PointsGridFormDataProvider.ts

@@ -0,0 +1,371 @@
+import { Units } from "@mat3ra/code/dist/js/constants";
+import { math as codeJSMath } from "@mat3ra/code/dist/js/math";
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import type {
+    GridContextItemSchema,
+    PointsGridDataProviderSchema,
+    Vector3DSchema,
+} from "@mat3ra/esse/dist/js/types";
+import { type ReciprocalLattice, Made } from "@mat3ra/made";
+import type { JSONSchema7 } from "json-schema";
+
+import materialContextMixin, {
+    type MaterialContextMixin,
+    type MaterialExternalContext,
+} from "../../mixins/MaterialContextMixin";
+import type { JinjaExternalContext } from "../base/JSONSchemaDataProvider";
+import JSONSchemaFormDataProvider from "../base/JSONSchemaFormDataProvider";
+import { globalSettings } from "../settings";
+
+type Schema = GridContextItemSchema;
+type Data = PointsGridDataProviderSchema;
+export type ExternalContext = JinjaExternalContext & MaterialExternalContext;
+
+type Base = typeof JSONSchemaFormDataProvider<Schema, ExternalContext> &
+    Constructor<MaterialContextMixin>;
+
+type GridMetricType = Data["gridMetricType"];
+
+const vector = (
+    defaultValue: string | number | readonly number[] | readonly string[],
+    isStringType = false,
+) => {
+    const isArray = Array.isArray(defaultValue);
+
+    return {
+        type: "array",
+        items: {
+            type: isStringType ? "string" : "number",
+            ...(isArray ? {} : { default: defaultValue }),
+        },
+        minItems: 3,
+        maxItems: 3,
+        ...(isArray ? { default: defaultValue } : {}),
+    };
+};
+
+const defaultShift = 0;
+const defaultShifts: Vector3DSchema = [defaultShift, defaultShift, defaultShift];
+
+abstract class PointsGridFormDataProvider<
+    N extends Schema["name"],
+> extends (JSONSchemaFormDataProvider as Base) {
+    abstract readonly name: N;
+
+    readonly domain = "important" as const;
+
+    readonly entityName = "unit" as const;
+
+    readonly jsonSchemaId = "context-providers-directory/points-grid-data-provider";
+
+    public dimensions!: Data["dimensions"];
+
+    public shifts!: Data["shifts"];
+
+    private reciprocalLattice!: ReciprocalLattice;
+
+    private gridMetricType!: Data["gridMetricType"];
+
+    private gridMetricValue!: number;
+
+    private preferGridMetric!: boolean;
+
+    private defaultDimensions!: Vector3DSchema;
+
+    private reciprocalVectorRatios!: Vector3DSchema;
+
+    readonly divisor: number;
+
+    protected defaultMetric!: {
+        type: GridMetricType;
+        value: number;
+    };
+
+    abstract readonly jsonSchema: JSONSchema7;
+
+    constructor(contextItem: Partial<Schema>, externalContext: ExternalContext, divisor: number) {
+        super(contextItem, externalContext);
+        this.divisor = divisor;
+        this.initMaterialContextMixin(externalContext);
+        this.initInstanceFields();
+    }
+
+    private initInstanceFields() {
+        this.defaultMetric = {
+            type: "KPPRA" as const,
+            value: this.getDefaultGridMetricValue("KPPRA"),
+        };
+
+        this.shifts = this.data?.shifts || [...defaultShifts];
+        this.gridMetricType = this.data?.gridMetricType || this.defaultMetric.type;
+        this.gridMetricValue = this.data?.gridMetricValue || this.defaultMetric.value;
+        this.preferGridMetric = this.data?.preferGridMetric || false;
+
+        this.reciprocalLattice = new Made.ReciprocalLattice(this.material.lattice);
+        this.defaultDimensions = this.calculateDimensions(
+            this.defaultMetric.type,
+            this.defaultMetric.value,
+        );
+        this.dimensions = this.data?.dimensions || this.defaultDimensions;
+        this.reciprocalVectorRatios = this.reciprocalLattice.reciprocalVectorRatios.map((r) =>
+            Number(codeJSMath.numberToPrecision(r, 3)),
+        ) as Vector3DSchema;
+    }
+
+    // TODO: move default values to be extracted from ESSE
+    private getDefaultGridMetricValue(metric: GridMetricType) {
+        switch (metric) {
+            case "KPPRA":
+                if (!globalSettings.defaultKPPRA) {
+                    throw new Error("globalSettings.defaultKPPRA is not set");
+                }
+                return Math.floor(globalSettings.defaultKPPRA / this.divisor);
+            case "spacing":
+                return 0.3;
+            default:
+                console.error("Metric type not recognized!");
+                return -1;
+        }
+    }
+
+    private resolveGridMetricValue(gridMetricType: GridMetricType, gridMetricValue: number) {
+        const isValid = gridMetricType === "KPPRA" ? gridMetricValue >= 1 : gridMetricValue > 0;
+
+        return isValid ? gridMetricValue : this.getDefaultGridMetricValue(gridMetricType);
+    }
+
+    getData(): Data {
+        const data = super.getData();
+        const { preferGridMetric, gridMetricType, gridMetricValue } = data;
+
+        if (!preferGridMetric || !gridMetricType) {
+            return data;
+        }
+
+        const effectiveValue = this.resolveGridMetricValue(gridMetricType, gridMetricValue);
+
+        return {
+            ...data,
+            gridMetricValue: effectiveValue,
+            dimensions: this.calculateDimensions(gridMetricType, effectiveValue),
+        };
+    }
+
+    getDefaultData() {
+        const defaultData: Data = {
+            dimensions: this.defaultDimensions,
+            shifts: defaultShifts,
+            gridMetricType: this.defaultMetric.type,
+            gridMetricValue: this.defaultMetric.value,
+            preferGridMetric: false,
+            reciprocalVectorRatios: this.reciprocalVectorRatios,
+        };
+
+        if (this.material) {
+            const { gridMetricType, gridMetricValue } = this;
+            // if `data` is present and material is updated, prioritize `data` when `preferGridMetric` is not set
+            return this.preferGridMetric
+                ? {
+                      dimensions: this.calculateDimensions(gridMetricType, gridMetricValue),
+                      shifts: defaultShifts,
+                      gridMetricType,
+                      gridMetricValue,
+                  }
+                : this.data || defaultData;
+        }
+
+        return defaultData;
+    }
+
+    protected get jsonSchemaPatchConfig() {
+        const metricDescription = {
+            KPPRA: `${this.name.toUpperCase()}PPRA (${this.name}pt per reciprocal atom)`, // KPPRA or QPPRA
+            spacing: "grid spacing",
+        };
+
+        const gridMetricType = this.data?.gridMetricType || this.defaultMetric.type;
+
+        return {
+            dimensions: vector(this.defaultDimensions, this.isUsingJinjaVariables),
+            shifts: vector(defaultShifts),
+            reciprocalVectorRatios: vector(this.reciprocalVectorRatios),
+            gridMetricType: { default: this.defaultMetric.type },
+            description: `3D grid with shifts. Default min value for ${
+                metricDescription[gridMetricType]
+            } is ${this.getDefaultGridMetricValue(gridMetricType)}.`,
+            required: ["dimensions", "shifts"],
+            dependencies: {
+                gridMetricType: {
+                    oneOf: [
+                        {
+                            properties: {
+                                gridMetricType: { enum: ["KPPRA"] },
+                                gridMetricValue: {
+                                    type: "integer",
+                                    minimum: 1,
+                                    title: "Value",
+                                    default: this.gridMetricValue,
+                                },
+                                preferGridMetric: {
+                                    type: "boolean",
+                                    title: "prefer KPPRA",
+                                    default: this.preferGridMetric,
+                                },
+                            },
+                        },
+                        {
+                            properties: {
+                                gridMetricType: { enum: ["spacing"] },
+                                gridMetricValue: {
+                                    type: "number",
+                                    exclusiveMinimum: 0,
+                                    title: "Value [1/Å]",
+                                    default: this.gridMetricValue,
+                                },
+                                preferGridMetric: {
+                                    type: "boolean",
+                                    title: "prefer spacing",
+                                    default: this.preferGridMetric,
+                                },
+                            },
+                        },
+                    ],
+                },
+            },
+        };
+    }
+
+    /** Prefer persisted `data` — `setData` runs before React re-inits the provider on render. */
+    private get preferGridMetricForUi() {
+        return this.data?.preferGridMetric ?? this.preferGridMetric;
+    }
+
+    get uiSchema() {
+        const preferGridMetric = this.preferGridMetricForUi;
+        const gridMetricValueForUi = this.data?.gridMetricValue ?? this.gridMetricValue;
+
+        const arraySubStyle = (emptyValue = 0) => {
+            return {
+                "ui:options": {
+                    addable: false,
+                    orderable: false,
+                    removable: false,
+                },
+                items: {
+                    "ui:disabled": preferGridMetric,
+                    // TODO: extract the actual current values from context
+                    "ui:placeholder": "1",
+                    "ui:emptyValue": emptyValue,
+                    "ui:label": false,
+                },
+            } as const;
+        };
+
+        return {
+            dimensions: arraySubStyle(1),
+            shifts: arraySubStyle(0),
+            gridMetricType: {
+                "ui:title": "Grid Metric",
+            },
+            gridMetricValue: {
+                "ui:disabled": !preferGridMetric,
+                "ui:emptyValue": gridMetricValueForUi,
+                "ui:placeholder": gridMetricValueForUi.toString(), // make string to prevent prop type error
+            },
+            preferGridMetric: {
+                "ui:emptyValue": true,
+                "ui:disabled": this.isUsingJinjaVariables,
+            },
+            reciprocalVectorRatios: {
+                "ui:title": "reciprocal vector ratios",
+                "ui:orderable": false,
+                "ui:removable": false,
+                "ui:readonly": true,
+                items: {
+                    "ui:label": false,
+                },
+            },
+        };
+    }
+
+    private calculateDimensions(
+        gridMetricType: GridMetricType,
+        gridMetricValue: number,
+        // units = Units.angstrom,
+    ): Vector3DSchema {
+        switch (gridMetricType) {
+            case "KPPRA": {
+                const nAtoms = this.material ? this.material.Basis.nAtoms : 1;
+                return this.reciprocalLattice.getDimensionsFromPointsCount(
+                    gridMetricValue / nAtoms,
+                );
+            }
+            case "spacing":
+                return this.reciprocalLattice.getDimensionsFromSpacing(
+                    gridMetricValue,
+                    Units.angstrom,
+                );
+            default:
+                return [1, 1, 1];
+        }
+    }
+
+    private calculateGridMetric(gridMetricType: GridMetricType, dimensions: Vector3DSchema) {
+        switch (gridMetricType) {
+            case "KPPRA": {
+                const nAtoms = this.material ? this.material.Basis.nAtoms : 1;
+                return dimensions.reduce((a, b) => a * b) * nAtoms;
+            }
+            case "spacing":
+                return Number(
+                    this.reciprocalLattice
+                        .getSpacingFromDimensions(dimensions, Units.angstrom)
+                        .toFixed(3),
+                );
+            default:
+                return 1;
+        }
+    }
+
+    setData(data: Data) {
+        const { dimensions, gridMetricType, preferGridMetric, gridMetricValue } = data;
+
+        if (preferGridMetric !== undefined) {
+            this.preferGridMetric = preferGridMetric;
+        }
+        if (gridMetricType !== undefined) {
+            this.gridMetricType = gridMetricType;
+        }
+
+        if (preferGridMetric && gridMetricType) {
+            const effectiveValue = this.resolveGridMetricValue(gridMetricType, gridMetricValue);
+            this.gridMetricValue = effectiveValue;
+
+            return super.setData({
+                ...data,
+                gridMetricValue: effectiveValue,
+                dimensions: this.calculateDimensions(gridMetricType, effectiveValue),
+            });
+        }
+
+        if (!preferGridMetric && dimensions.every((d) => typeof d === "number")) {
+            const derivedMetric = this.calculateGridMetric(gridMetricType, dimensions);
+            this.gridMetricValue = derivedMetric;
+
+            return super.setData({
+                ...data,
+                gridMetricValue: derivedMetric,
+            });
+        }
+
+        if (gridMetricValue !== undefined) {
+            this.gridMetricValue = gridMetricValue;
+        }
+
+        return super.setData(data);
+    }
+}
+
+materialContextMixin(PointsGridFormDataProvider.prototype);
+
+export default PointsGridFormDataProvider;

package/src/js/context/providers/PointsGrid/QGridFormDataManager.ts

@@ -0,0 +1,36 @@
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { GridContextItemSchema } from "@mat3ra/esse/dist/js/types";
+import type { JSONSchema7 } from "json-schema";
+
+import type { UnitContext } from "../base/ContextProvider";
+import PointsGridFormDataProvider, { type ExternalContext } from "./PointsGridFormDataProvider";
+
+type Name = "qgrid";
+type Schema = GridContextItemSchema;
+
+export default class QGridFormDataManager extends PointsGridFormDataProvider<Name> {
+    readonly name = "qgrid" as const;
+
+    readonly jsonSchema: JSONSchema7;
+
+    constructor(contextItem: Partial<Schema>, externalContext: ExternalContext) {
+        super(contextItem, externalContext, 5);
+
+        const jsonSchema = JSONSchemasInterface.getPatchedSchemaById(
+            this.jsonSchemaId,
+            this.jsonSchemaPatchConfig,
+        );
+
+        if (!jsonSchema) {
+            throw new Error("Failed to get patched JSON schema");
+        }
+
+        this.jsonSchema = jsonSchema;
+    }
+
+    static createFromUnitContext(unitContext: UnitContext, externalContext: ExternalContext) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "qgrid");
+
+        return new QGridFormDataManager(contextItem, externalContext);
+    }
+}

package/src/js/context/providers/PointsPath/ExplicitKPath2PIBAFormDataManager.ts

@@ -0,0 +1,26 @@
+import type { PathContextItemSchema } from "@mat3ra/esse/dist/js/types";
+
+import type { UnitContext } from "../base/ContextProvider";
+import PointsPathFormDataProvider, {
+    type PointsPathFormDataProviderExternalContext,
+} from "./PointsPathFormDataProvider";
+
+type Name = "explicitKPath2PIBA";
+type Schema = PathContextItemSchema;
+
+export default class ExplicitKPath2PIBAFormDataManager extends PointsPathFormDataProvider<Name> {
+    readonly name = "explicitKPath2PIBA" as const;
+
+    readonly is2PIBA = true;
+
+    readonly useExplicitPath = true;
+
+    static createFromUnitContext(
+        unitContext: UnitContext,
+        externalContext: PointsPathFormDataProviderExternalContext,
+    ) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "explicitKPath2PIBA");
+
+        return new ExplicitKPath2PIBAFormDataManager(contextItem, externalContext);
+    }
+}

package/src/js/context/providers/PointsPath/ExplicitKPathFormDataManager.ts

@@ -0,0 +1,24 @@
+import type { PathContextItemSchema } from "@mat3ra/esse/dist/js/types";
+
+import type { UnitContext } from "../base/ContextProvider";
+import PointsPathFormDataProvider, {
+    type PointsPathFormDataProviderExternalContext,
+} from "./PointsPathFormDataProvider";
+
+type Name = "explicitKPath";
+type Schema = PathContextItemSchema;
+
+export default class ExplicitKPathFormDataManager extends PointsPathFormDataProvider<Name> {
+    readonly name = "explicitKPath" as const;
+
+    readonly useExplicitPath = true;
+
+    static createFromUnitContext(
+        unitContext: UnitContext,
+        externalContext: PointsPathFormDataProviderExternalContext,
+    ) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "explicitKPath");
+
+        return new ExplicitKPathFormDataManager(contextItem, externalContext);
+    }
+}

package/src/js/context/providers/PointsPath/IPathFormDataManager.ts

@@ -0,0 +1,22 @@
+import type { PathContextItemSchema } from "@mat3ra/esse/dist/js/types";
+
+import type { UnitContext } from "../base/ContextProvider";
+import PointsPathFormDataProvider, {
+    type PointsPathFormDataProviderExternalContext,
+} from "./PointsPathFormDataProvider";
+
+type Name = "ipath";
+type Schema = PathContextItemSchema;
+
+export default class IPathFormDataManager extends PointsPathFormDataProvider<Name> {
+    readonly name = "ipath" as const;
+
+    static createFromUnitContext(
+        unitContext: UnitContext,
+        externalContext: PointsPathFormDataProviderExternalContext,
+    ) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "ipath");
+
+        return new IPathFormDataManager(contextItem, externalContext);
+    }
+}

package/src/js/context/providers/PointsPath/KPathFormDataManager.ts

@@ -0,0 +1,22 @@
+import type { PathContextItemSchema } from "@mat3ra/esse/dist/js/types";
+
+import type { UnitContext } from "../base/ContextProvider";
+import PointsPathFormDataProvider, {
+    type PointsPathFormDataProviderExternalContext,
+} from "./PointsPathFormDataProvider";
+
+type Name = "kpath";
+type Schema = PathContextItemSchema;
+
+export default class KPathFormDataManager extends PointsPathFormDataProvider<Name> {
+    readonly name = "kpath" as const;
+
+    static createFromUnitContext(
+        unitContext: UnitContext,
+        externalContext: PointsPathFormDataProviderExternalContext,
+    ) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "kpath");
+
+        return new KPathFormDataManager(contextItem, externalContext);
+    }
+}

package/src/js/context/providers/PointsPath/PointsPathFormDataProvider.ts

@@ -0,0 +1,192 @@
+import { math as codeJSMath } from "@mat3ra/code/dist/js/math";
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { JSONSchema } from "@mat3ra/esse/dist/js/esse/utils";
+import type {
+    PathContextItemSchema,
+    PointsPathDataProviderRenderingSchema,
+    PointsPathDataProviderSchema,
+} from "@mat3ra/esse/dist/js/types";
+import { type ReciprocalLattice, Made } from "@mat3ra/made";
+
+import applicationContextMixin, {
+    type ApplicationContextMixin,
+    type ApplicationExternalContext,
+} from "../../mixins/ApplicationContextMixin";
+import materialContextMixin, {
+    type MaterialContextMixin,
+    type MaterialExternalContext,
+} from "../../mixins/MaterialContextMixin";
+import JSONSchemaDataProvider, { type JinjaExternalContext } from "../base/JSONSchemaDataProvider";
+
+const defaultPoint = "Г" as const;
+const defaultSteps = 10 as const;
+
+export type PointsPathFormDataProviderData = PointsPathDataProviderSchema;
+export type PointsPathFormDataProviderRenderingData = PointsPathDataProviderRenderingSchema;
+export type PointsPathFormDataProviderExternalContext = JinjaExternalContext &
+    MaterialExternalContext &
+    ApplicationExternalContext;
+
+type Data = PointsPathFormDataProviderData;
+type RenderingData = PointsPathFormDataProviderRenderingData;
+type RenderingDataItem = RenderingData[0];
+type Schema = PathContextItemSchema;
+type ExternalContext = PointsPathFormDataProviderExternalContext;
+
+const jsonSchemaId = "context-providers-directory/points-path-data-provider";
+
+type Base = typeof JSONSchemaDataProvider<Schema, ExternalContext, RenderingData> &
+    Constructor<MaterialContextMixin> &
+    Constructor<ApplicationContextMixin>;
+
+abstract class MixinsContextProvider extends (JSONSchemaDataProvider as Base) {
+    constructor(contextItem: Partial<Schema>, externalContext: ExternalContext) {
+        super(contextItem, externalContext);
+        this.initMaterialContextMixin(externalContext);
+        this.initApplicationContextMixin(externalContext);
+    }
+}
+
+materialContextMixin(MixinsContextProvider.prototype);
+applicationContextMixin(MixinsContextProvider.prototype);
+
+abstract class PointsPathFormDataProvider<N extends Schema["name"]> extends MixinsContextProvider {
+    abstract name: N;
+
+    readonly domain = "important" as const;
+
+    readonly entityName = "unit" as const;
+
+    private reciprocalLattice: ReciprocalLattice;
+
+    readonly useExplicitPath: boolean;
+
+    readonly is2PIBA: boolean = false;
+
+    constructor(config: Partial<Schema>, externalContext: ExternalContext) {
+        super(config, externalContext);
+        this.reciprocalLattice = new Made.ReciprocalLattice(this.material.lattice);
+        this.useExplicitPath = this.application.name === "vasp";
+    }
+
+    getDefaultData(): Data {
+        return this.reciprocalLattice.defaultKpointPath as Data;
+    }
+
+    updateMaterialHash() {
+        const previousMaterialHash = this.extraData?.materialHash;
+
+        super.updateMaterialHash();
+
+        // Reset path only when the material actually changed (hash). Do not clear `isEdited` just
+        // because the material has no id (common default material in designers): that ran every
+        // render, wiped isEdited, and savePersistentContext dropped k-path/Q-path from `unit.context`.
+        if (previousMaterialHash && previousMaterialHash !== this.material.hash) {
+            this.isEdited = false;
+        }
+    }
+
+    get jsonSchema(): JSONSchema {
+        const jsonSchema = JSONSchemasInterface.getPatchedSchemaById(jsonSchemaId, {
+            "items.properties.point": {
+                default: defaultPoint,
+                enum: this.reciprocalLattice.symmetryPoints.map((x) => x.point),
+            },
+            "items.properties.steps": {
+                default: defaultSteps,
+            },
+        });
+
+        if (!jsonSchema) {
+            throw new Error("Failed to get patched JSON schema");
+        }
+
+        return jsonSchema;
+    }
+
+    readonly uiSchemaStyled = {
+        items: {
+            point: {},
+            steps: {},
+        },
+    };
+
+    protected patchForRendering(data: Data): RenderingData {
+        return this.addCoordinates(data);
+    }
+
+    private addCoordinates(path: Data): RenderingData {
+        const rawData: RenderingDataItem[] = path.map((pathItem) => {
+            const point = this.reciprocalLattice.symmetryPoints.find((sp) => {
+                return sp.point === pathItem.point;
+            });
+            if (!point) {
+                throw new Error(`Point ${pathItem.point} not found in reciprocal lattice`);
+            }
+            return { ...pathItem, coordinates: point.coordinates };
+        });
+
+        const processedData = this.useExplicitPath ? this.convertToExplicitPath(rawData) : rawData;
+
+        const mapped = processedData.map((p) => {
+            const coordinates = this.is2PIBA
+                ? this.reciprocalLattice.getCartesianCoordinates(p.coordinates)
+                : p.coordinates;
+
+            return {
+                ...p,
+                coordinates: coordinates.map((c) => Number(c.toFixed(9))),
+            };
+        });
+
+        return mapped as RenderingData;
+    }
+
+    // Initially, path contains symmetry points with steps counts.
+    // This function explicitly calculates each point between symmetry points by step counts.
+    // eslint-disable-next-line class-methods-use-this
+    private convertToExplicitPath(path: RenderingDataItem[]): RenderingDataItem[] {
+        return path.reduce<RenderingDataItem[]>((acc, startPoint, index) => {
+            const nextPoint = path[index + 1];
+
+            if (!nextPoint) {
+                return acc;
+            }
+
+            const middlePoints = codeJSMath.calculateSegmentsBetweenPoints3D(
+                startPoint.coordinates,
+                nextPoint.coordinates,
+                startPoint.steps,
+            );
+
+            const steps = 1;
+
+            acc.push(
+                {
+                    steps,
+                    coordinates: startPoint.coordinates,
+                    point: startPoint.point,
+                },
+                ...middlePoints.map((coordinates) => ({
+                    steps,
+                    coordinates,
+                    point: startPoint.point,
+                })),
+            );
+
+            // nextPoint is the last point in the path
+            if (path.length - 2 === index) {
+                acc.push({
+                    steps,
+                    coordinates: nextPoint.coordinates,
+                    point: nextPoint.point,
+                });
+            }
+
+            return acc;
+        }, []);
+    }
+}
+
+export default PointsPathFormDataProvider;