@mat3ra/wode 2026.5.23-0 → 2026.6.5-0

package/src/js/context/providers/PointsPath/QPathFormDataManager.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 = "qpath";
+type Schema = PathContextItemSchema;
+
+export default class QPathFormDataManager extends PointsPathFormDataProvider<Name> {
+    readonly name = "qpath" as const;
+
+    static createFromUnitContext(
+        unitContext: UnitContext,
+        externalContext: PointsPathFormDataProviderExternalContext,
+    ) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "qpath");
+
+        return new QPathFormDataManager(contextItem, externalContext);
+    }
+}

package/src/js/context/providers/base/ContextProvider.ts

@@ -0,0 +1,150 @@
+import { type ContextItemSchema } from "@mat3ra/esse/dist/js/types";
+import { Utils } from "@mat3ra/utils";
+
+export type UnitContext = ContextItemSchema[];
+export type ContextName = ContextItemSchema["name"];
+export type ContextExtraData = ContextItemSchema["extraData"];
+export type ContextData = ContextItemSchema["data"];
+
+export type ContextItem<
+    D extends ContextData = ContextData,
+    ED extends ContextExtraData = ContextExtraData,
+> = {
+    data?: D;
+    extraData?: ED;
+    isEdited?: boolean;
+};
+
+/** Context item with template-facing `data` (may be a superset of persisted `S["data"]`). */
+export type ContextItemForRendering<
+    S extends ContextItemSchema = ContextItemSchema,
+    R = S["data"],
+> = Omit<S, "data"> & { data: R };
+
+export type Domain = "executable" | "important";
+
+export type EntityName = "unit" | "subworkflow";
+
+/** Minimal bound for provider external context; the full contract is ExternalContext in context/providers/index.ts */
+export type BaseExternalContext = object;
+
+/**
+ * Context providers expose three data layers. Keep them separate.
+ *
+ *   1. Persistent data — user input / defaults. Stored in the DB as the context item's `data`,
+ *      and bound to RJSForm as `formData`.
+ *        API: `getData()` / `setData(data)` / `getContextItemData()`
+ *
+ *   2. Patched persistent (rendering) data — persistent data plus fields derived from external
+ *      context (material, application, …) that must NOT be stored or shown in the form.
+ *      Default = identity, override `patchForRendering` when the template needs extra fields.
+ *        API: `getDataForRendering()` / `getContextItemDataForRendering()`
+ *      If the rendering shape is a proper superset of the persistent shape, declare it via the
+ *      third generic `DataForRendering` and pair with a dedicated ESSE schema (see
+ *      `PointsPathFormDataProvider` + `points_path_data_provider_rendering.json`).
+ *
+ *   3. Full rendering context — `{ ...patchedItemByName, ...externalContext }` fed to Jinja.
+ *      Built by `ExecutionUnit.render` from `getContextItemDataForRendering()` results.
+ *
+ * Rules:
+ *   - Never bake derived fields into `setData`/`getDefaultData` just to reach templates.
+ *   - `setData` may normalize legacy payloads to the current persistent schema.
+ *   - `ExecutionUnit.render` MUST call `getContextItemData()` for `this.context` (DB) and
+ *     `getContextItemDataForRendering()` for `this.renderingContext` (Jinja) separately.
+ *
+ * See `.cursor/rules/context-provider-data-layers.mdc` for the full guidance.
+ */
+abstract class ContextProvider<
+    S extends ContextItemSchema = ContextItemSchema,
+    EC extends BaseExternalContext = BaseExternalContext,
+    /** Data passed to templates; defaults to persisted `S["data"]` (identity `patchForRendering`). */
+    DataForRendering = S["data"],
+> {
+    abstract name: S["name"];
+
+    abstract readonly domain: Domain;
+
+    abstract readonly entityName: EntityName;
+
+    protected abstract getDefaultData(): S["data"];
+
+    protected data?: S["data"];
+
+    /** Seeded from persisted context; material providers refresh via `updateMaterialHash()`. */
+    extraData?: S["extraData"];
+
+    readonly externalContext: EC;
+
+    isEdited: boolean;
+
+    constructor(contextItem: Partial<S>, externalContext: EC) {
+        this.externalContext = externalContext;
+        this.isEdited = contextItem.isEdited || false;
+
+        if (contextItem.data !== undefined) {
+            this.data = Utils.clone.deepClone(contextItem.data);
+        }
+
+        if (contextItem.extraData !== undefined) {
+            this.extraData = Utils.clone.deepClone(contextItem.extraData);
+        }
+    }
+
+    setIsEdited(isEdited: boolean) {
+        this.isEdited = isEdited;
+    }
+
+    getData(): S["data"] {
+        if (this.data !== undefined) {
+            return Utils.clone.deepClone(this.data);
+        }
+        return this.getDefaultData();
+    }
+
+    setData(data: S["data"]) {
+        this.data = Utils.clone.deepClone(data);
+    }
+
+    /**
+     * Derive template-facing `data` from persisted `data`. Override when the template needs fields
+     * that must not be stored (e.g. coordinates from symmetry point names + lattice).
+     */
+    // eslint-disable-next-line class-methods-use-this
+    protected patchForRendering(data: S["data"]): DataForRendering {
+        return data as DataForRendering;
+    }
+
+    getDataForRendering(): DataForRendering {
+        return this.patchForRendering(this.getData());
+    }
+
+    getContextItemData(): S {
+        return {
+            name: this.name,
+            isEdited: this.isEdited,
+            data: this.getData(),
+            extraData: this.extraData,
+        } as S;
+    }
+
+    getContextItemDataForRendering(): ContextItemForRendering<S, DataForRendering> {
+        return {
+            ...this.getContextItemData(),
+            data: this.getDataForRendering(),
+        };
+    }
+
+    /**
+     * Helper method to find a context item from a unit context array by name.
+     * Returns a partial schema object that can be safely passed to constructors.
+     */
+    protected static findContextItem<S extends ContextItemSchema>(
+        unitContext: UnitContext,
+        contextName: ContextName,
+    ): Partial<S> {
+        const item = unitContext.find((item): item is S => item.name === contextName);
+        return item || {};
+    }
+}
+
+export default ContextProvider;

package/src/js/context/providers/base/JSONSchemaDataProvider.ts

@@ -0,0 +1,31 @@
+import type { JSONSchema } from "@mat3ra/esse/dist/js/esse/utils";
+import type { ContextItemSchema } from "@mat3ra/esse/dist/js/types";
+
+import ContextProvider from "./ContextProvider";
+
+export interface JinjaExternalContext {
+    isUsingJinjaVariables?: boolean;
+}
+
+/**
+ * @summary Provides jsonSchema only.
+ */
+abstract class JSONSchemaDataProvider<
+    S extends ContextItemSchema = ContextItemSchema,
+    EC extends JinjaExternalContext = JinjaExternalContext,
+    DataForRendering = S["data"],
+    // eslint-disable-next-line prettier/prettier
+> extends ContextProvider<S, EC, DataForRendering> {
+    abstract readonly jsonSchema: JSONSchema;
+
+    readonly entityName = "unit" as const;
+
+    isUsingJinjaVariables: boolean;
+
+    constructor(contextItem: Partial<S>, externalContext: EC) {
+        super(contextItem, externalContext);
+        this.isUsingJinjaVariables = Boolean(externalContext?.isUsingJinjaVariables);
+    }
+}
+
+export default JSONSchemaDataProvider;

package/src/js/context/providers/base/JSONSchemaFormDataProvider.ts

@@ -0,0 +1,38 @@
+import type { ContextItemSchema } from "@mat3ra/esse/dist/js/types";
+import type { UiSchema } from "react-jsonschema-form";
+
+import JSONSchemaDataProvider, { type JinjaExternalContext } from "./JSONSchemaDataProvider";
+
+/**
+ * @summary Provides jsonSchema and uiSchema for generating react-jsonschema-form
+ *          See https://github.com/mozilla-services/react-jsonschema-form for Form UI.
+ *          Form generation example:
+ * ```
+ * <Form schema={provider.jsonSchema}
+ *      uiSchema={provider.uiSchema}
+ *      formData={provider.getData(unit.important)} />
+ * ```
+ */
+abstract class JSONSchemaFormDataProvider<
+    S extends ContextItemSchema = ContextItemSchema,
+    EC extends JinjaExternalContext = JinjaExternalContext,
+    DataForRendering = S["data"],
+> extends JSONSchemaDataProvider<S, EC, DataForRendering> {
+    fields: object = {};
+
+    protected abstract uiSchema: UiSchema;
+
+    get uiSchemaStyled(): UiSchema {
+        return Object.fromEntries(
+            Object.entries(this.uiSchema).map(([key, value]) => [
+                key,
+                {
+                    ...value,
+                    classNames: `${value.classNames || ""}`,
+                },
+            ]),
+        );
+    }
+}
+
+export default JSONSchemaFormDataProvider;

package/src/js/context/providers/by_application/espresso/QENEBInputDataManager.ts

@@ -0,0 +1,107 @@
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type {
+    InputContextItemSchema,
+    QENEBContextProviderSchema,
+} from "@mat3ra/esse/dist/js/types";
+import type { JSONSchema7 } from "json-schema";
+
+import materialContextMixin, {
+    type MaterialContextMixin,
+    type MaterialExternalContext,
+} from "../../../mixins/MaterialContextMixin";
+import materialsContextMixin, {
+    type MaterialsContextMixin,
+    type MaterialsExternalContext,
+} from "../../../mixins/MaterialsContextMixin";
+import materialsSetContextMixin, {
+    type MaterialsSetContextMixin,
+    type MaterialsSetExternalContext,
+} from "../../../mixins/MaterialsSetContextMixin";
+import type { UnitContext } from "../../base/ContextProvider";
+import JSONSchemaDataProvider, {
+    type JinjaExternalContext,
+} from "../../base/JSONSchemaDataProvider";
+import QEPWXInputDataManager, {
+    type JobExternalContext,
+    type MethodDataExternalContext,
+    type WorkflowExternalContext,
+} from "./QEPWXInputDataManager";
+
+const jsonSchemaId = "context-providers-directory/by-application/qe-neb-context-provider";
+
+type Data = QENEBContextProviderSchema;
+type Schema = InputContextItemSchema & { data: Data };
+type ExternalContext = JinjaExternalContext &
+    WorkflowExternalContext &
+    JobExternalContext &
+    MaterialsExternalContext &
+    MethodDataExternalContext &
+    MaterialsSetExternalContext &
+    MaterialExternalContext;
+
+interface QENEBInputDataManager
+    extends MaterialContextMixin,
+        MaterialsContextMixin,
+        MaterialsSetContextMixin {}
+
+class QENEBInputDataManager extends JSONSchemaDataProvider<Schema, ExternalContext> {
+    readonly name = "input" as const;
+
+    readonly domain = "executable" as const;
+
+    readonly entityName = "unit" as const;
+
+    isEdited = false;
+
+    static createFromUnitContext(unitContext: UnitContext, externalContext: ExternalContext) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "input");
+
+        return new QENEBInputDataManager(contextItem, externalContext);
+    }
+
+    readonly jsonSchema: JSONSchema7;
+
+    constructor(config: Partial<Schema>, externalContext: ExternalContext) {
+        super(config, externalContext);
+        this.initMaterialsContextMixin(externalContext);
+        this.initMaterialContextMixin(externalContext);
+        this.initMaterialsSetContextMixin(externalContext);
+
+        const jsonSchema = JSONSchemasInterface.getSchemaById(jsonSchemaId);
+
+        if (!jsonSchema) {
+            throw new Error("Failed to get JSON schema");
+        }
+
+        this.jsonSchema = jsonSchema;
+    }
+
+    getDefaultData(): Data {
+        const PWXContexts = this.sortMaterialsByIndexInSet(this.materials).map((material) => {
+            return new QEPWXInputDataManager({}, { ...this.externalContext, material }).getData();
+        });
+
+        const {
+            ATOMIC_POSITIONS,
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            ATOMIC_POSITIONS_WITHOUT_CONSTRAINTS: _,
+            ...rest
+        } = PWXContexts[0];
+
+        return {
+            ...rest,
+            FIRST_IMAGE: ATOMIC_POSITIONS,
+            LAST_IMAGE: PWXContexts[PWXContexts.length - 1].ATOMIC_POSITIONS,
+            INTERMEDIATE_IMAGES: PWXContexts.slice(1, PWXContexts.length - 1).map((data) => {
+                return data.ATOMIC_POSITIONS;
+            }),
+            contextProviderName: "qe-neb" as const,
+        };
+    }
+}
+
+materialContextMixin(QENEBInputDataManager.prototype);
+materialsContextMixin(QENEBInputDataManager.prototype);
+materialsSetContextMixin(QENEBInputDataManager.prototype);
+
+export default QENEBInputDataManager;

package/src/js/context/providers/by_application/espresso/QEPWXInputDataManager.ts

@@ -0,0 +1,178 @@
+import { PERIODIC_TABLE } from "@exabyte-io/periodic-table.js";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type {
+    BaseMethod,
+    InputContextItemSchema,
+    QEPwxContextProviderSchema,
+} from "@mat3ra/esse/dist/js/types";
+import type { Material } from "@mat3ra/made";
+import type { AtomicElementValue } from "@mat3ra/made/dist/js/basis/elements";
+import type { JSONSchema7 } from "json-schema";
+import path from "path";
+
+import materialContextMixin, {
+    type MaterialContextMixin,
+    type MaterialExternalContext,
+} from "../../../mixins/MaterialContextMixin";
+import materialsContextMixin, {
+    type MaterialsContextMixin,
+    type MaterialsExternalContext,
+} from "../../../mixins/MaterialsContextMixin";
+import type { UnitContext } from "../../base/ContextProvider";
+import JSONSchemaDataProvider, {
+    type JinjaExternalContext,
+} from "../../base/JSONSchemaDataProvider";
+
+// TODO: create a task to define correct type for MethodData
+type MethodData = BaseMethod["data"] & {
+    pseudo?: { element: AtomicElementValue; filename?: string; path?: string }[];
+};
+
+export type MethodDataExternalContext = {
+    methodData?: MethodData;
+};
+
+export type JobExternalContext = {
+    jobHasParent: boolean;
+};
+
+export type WorkflowExternalContext = {
+    workflowHasRelaxation: boolean;
+};
+
+type Data = QEPwxContextProviderSchema;
+type Schema = InputContextItemSchema & { data: Data };
+type ExternalContext = JinjaExternalContext &
+    WorkflowExternalContext &
+    MaterialExternalContext &
+    JobExternalContext &
+    MethodDataExternalContext &
+    MaterialsExternalContext;
+
+interface QEPWXInputDataManager extends MaterialContextMixin, MaterialsContextMixin {}
+
+const jsonSchemaId = "context-providers-directory/by-application/qe-pwx-context-provider";
+
+class QEPWXInputDataManager extends JSONSchemaDataProvider<Schema, ExternalContext> {
+    readonly name = "input" as const;
+
+    readonly domain = "executable" as const;
+
+    readonly entityName = "unit" as const;
+
+    isEdited = false;
+
+    methodData?: MethodData;
+
+    jobHasParent: boolean;
+
+    workflowHasRelaxation: boolean;
+
+    static createFromUnitContext(unitContext: UnitContext, externalContext: ExternalContext) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "input");
+
+        return new QEPWXInputDataManager(contextItem, externalContext);
+    }
+
+    readonly jsonSchema: JSONSchema7;
+
+    constructor(config: Partial<Schema>, externalContext: ExternalContext) {
+        super(config, externalContext);
+        this.initMaterialsContextMixin(externalContext);
+        this.initMaterialContextMixin(externalContext);
+
+        this.methodData = externalContext.methodData || {};
+        this.jobHasParent = externalContext.jobHasParent;
+        this.workflowHasRelaxation = externalContext.workflowHasRelaxation;
+
+        const jsonSchema = JSONSchemasInterface.getSchemaById(jsonSchemaId);
+
+        if (!jsonSchema) {
+            throw new Error("Failed to get JSON schema");
+        }
+
+        this.jsonSchema = jsonSchema;
+    }
+
+    private buildQEPWXContext(material: Material): Data {
+        const { Basis: basis, Lattice: lattice } = material;
+        const { jobHasParent, workflowHasRelaxation } = this;
+
+        const ATOMIC_SPECIES = basis.uniqueElements.map((symbol) => {
+            const pseudo = (this.methodData?.pseudo || []).find((p) => p.element === symbol);
+            return {
+                X: symbol,
+                Mass_X: PERIODIC_TABLE[symbol].atomic_mass,
+                PseudoPot_X: pseudo?.filename || path.basename(pseudo?.path || ""),
+            };
+        });
+
+        const uniqueElementsWithLabels = [...new Set(basis.elementsWithLabelsArray)];
+
+        const ATOMIC_SPECIES_WITH_LABELS = uniqueElementsWithLabels.map((symbol) => {
+            const symbolWithoutLabel = symbol.replace(/\d$/, "") as AtomicElementValue;
+            const label = symbol.match(/\d$/g) ? symbol.match(/\d$/g)?.[0] : "";
+            const pseudo = (this.methodData?.pseudo || []).find(
+                (p) => p.element === symbolWithoutLabel,
+            );
+            return {
+                X: `${symbolWithoutLabel}${label}`,
+                Mass_X: PERIODIC_TABLE[symbol].atomic_mass,
+                PseudoPot_X: pseudo?.filename || path.basename(pseudo?.path || ""),
+            };
+        });
+
+        const CELL_PARAMETERS = {
+            v1: lattice.vectorArrays[0],
+            v2: lattice.vectorArrays[1],
+            v3: lattice.vectorArrays[2],
+        };
+
+        const ATOMIC_POSITIONS = basis.elementsCoordinatesConstraintsArray.map(
+            ([element, label, coordinate, constraint]) => {
+                return {
+                    X: `${element}${label}`,
+                    x: coordinate[0],
+                    y: coordinate[1],
+                    z: coordinate[2],
+                    "if_pos(1)": constraint[0] ? 1 : 0,
+                    "if_pos(2)": constraint[1] ? 1 : 0,
+                    "if_pos(3)": constraint[2] ? 1 : 0,
+                };
+            },
+        );
+
+        return {
+            IBRAV: 0,
+            RESTART_MODE: jobHasParent || workflowHasRelaxation ? "restart" : "from_scratch",
+            ATOMIC_SPECIES,
+            ATOMIC_SPECIES_WITH_LABELS,
+            NAT: basis.atomicPositions.length,
+            NTYP: basis.uniqueElements.length,
+            NTYP_WITH_LABELS: uniqueElementsWithLabels.length,
+            ATOMIC_POSITIONS,
+            ATOMIC_POSITIONS_WITHOUT_CONSTRAINTS: basis.atomicPositions.join("\n"),
+            CELL_PARAMETERS,
+            contextProviderName: "qe-pwx" as const,
+        };
+    }
+
+    getDefaultData() {
+        // the below values are read from PlanewaveDataManager instead
+        // ECUTWFC = 40;
+        // ECUTRHO = 200;
+
+        return {
+            ...this.buildQEPWXContext(this.material),
+            perMaterial: this.materials.map((material) => this.buildQEPWXContext(material)),
+        };
+    }
+}
+
+materialContextMixin(QEPWXInputDataManager.prototype);
+materialsContextMixin(QEPWXInputDataManager.prototype);
+// methodDataContextMixin(QEPWXInputDataManager.prototype);
+// workflowContextMixin(QEPWXInputDataManager.prototype);
+// jobContextMixin(QEPWXInputDataManager.prototype);
+
+export default QEPWXInputDataManager;

package/src/js/context/providers/by_application/nwchem/NWChemInputDataManager.ts

@@ -0,0 +1,93 @@
+import { PERIODIC_TABLE } from "@exabyte-io/periodic-table.js";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type {
+    InputContextItemSchema,
+    NWChemTotalEnergyContextProviderSchema,
+} from "@mat3ra/esse/dist/js/types";
+import type { JSONSchema7 } from "json-schema";
+
+import materialContextMixin, {
+    type MaterialContextMixin,
+    type MaterialExternalContext,
+} from "../../../mixins/MaterialContextMixin";
+import type { UnitContext } from "../../base/ContextProvider";
+import JSONSchemaDataProvider, {
+    type JinjaExternalContext,
+} from "../../base/JSONSchemaDataProvider";
+
+type Data = NWChemTotalEnergyContextProviderSchema;
+type Schema = InputContextItemSchema & { data: Data };
+type ExternalContext = JinjaExternalContext & MaterialExternalContext;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface NWChemInputDataManager extends MaterialContextMixin {}
+
+const jsonSchemaId =
+    "context-providers-directory/by-application/nwchem-total-energy-context-provider";
+
+class NWChemInputDataManager extends JSONSchemaDataProvider<Schema, ExternalContext> {
+    readonly name = "input" as const;
+
+    readonly domain = "executable" as const;
+
+    readonly entityName = "unit" as const;
+
+    isEdited = false;
+
+    static createFromUnitContext(unitContext: UnitContext, externalContext: ExternalContext) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "input");
+
+        return new NWChemInputDataManager(contextItem, externalContext);
+    }
+
+    readonly contextProviderName = "nwchem-total-energy" as const;
+
+    readonly jsonSchema: JSONSchema7;
+
+    constructor(config: Partial<Schema>, externalContext: ExternalContext) {
+        super(config, externalContext);
+        this.initMaterialContextMixin(externalContext);
+
+        const jsonSchema = JSONSchemasInterface.getSchemaById(jsonSchemaId);
+
+        if (!jsonSchema) {
+            throw new Error("Failed to get JSON schema");
+        }
+
+        this.jsonSchema = jsonSchema;
+    }
+
+    /*
+     * TODO: Create ability for user to define CHARGE, MULT, BASIS and FUNCTIONAL parameters.
+     */
+    getDefaultData() {
+        const basis = this.material.Basis;
+
+        const NTYP = basis.uniqueElements.length;
+        const ATOMIC_POSITIONS_WITHOUT_CONSTRAINTS = basis.atomicPositions.join("\n") || "";
+        const ATOMIC_SPECIES = basis.uniqueElements
+            .map((symbol) => `${symbol} ${PERIODIC_TABLE[symbol].atomic_mass} `)
+            .join("\n");
+
+        basis.toCartesian();
+        const atomicPositions = basis.getAtomicPositionsWithConstraintsAsStrings();
+
+        return {
+            CHARGE: 0,
+            MULT: 1,
+            BASIS: "6-31G",
+            NAT: atomicPositions.length,
+            NTYP,
+            ATOMIC_POSITIONS: atomicPositions.join("\n"),
+            ATOMIC_POSITIONS_WITHOUT_CONSTRAINTS,
+            ATOMIC_SPECIES,
+            FUNCTIONAL: "B3LYP",
+            CARTESIAN: basis.toCartesian !== undefined,
+            contextProviderName: this.contextProviderName,
+        };
+    }
+}
+
+materialContextMixin(NWChemInputDataManager.prototype);
+
+export default NWChemInputDataManager;