@mat3ra/wode 2026.5.23-0 → 2026.6.5-0

package/src/js/Workflow.ts

@@ -0,0 +1,390 @@
+import { type NamedInMemoryEntity, InMemoryEntity } from "@mat3ra/code/dist/js/entity";
+import {
+    type Defaultable,
+    defaultableEntityMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/DefaultableMixin";
+import {
+    type HasDescription,
+    hasDescriptionMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/HasDescriptionMixin";
+import {
+    type HashedEntity,
+    hashedEntityMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/HashedEntityMixin";
+import { namedEntityMixin } from "@mat3ra/code/dist/js/entity/mixins/NamedEntityMixin";
+import { Taggable, taggableMixin } from "@mat3ra/code/dist/js/entity/mixins/TaggableMixin";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type {
+    ApplicationSchema,
+    SubworkflowSchema,
+    WorkflowSchema,
+} from "@mat3ra/esse/dist/js/types";
+import { ComputedEntityMixin, computedEntityMixin } from "@mat3ra/ide/dist/js/compute";
+import type { Material } from "@mat3ra/made";
+import type { MetaPropertyHolder } from "@mat3ra/prode";
+import { setUnitLinks, SubworkflowStandata } from "@mat3ra/standata";
+import { Utils } from "@mat3ra/utils";
+
+import type { MaterialExternalContext } from "./context/mixins/MaterialContextMixin";
+import type { MaterialsExternalContext } from "./context/mixins/MaterialsContextMixin";
+import type { MaterialsSetExternalContext } from "./context/mixins/MaterialsSetContextMixin";
+import type { JobExternalContext } from "./context/providers/by_application/espresso/QEPWXInputDataManager";
+import { UnitType } from "./enums";
+import { type WorkflowSchemaMixin, workflowSchemaMixin } from "./generated/WorkflowSchemaMixin";
+import Subworkflow from "./Subworkflow";
+import { MapUnit } from "./units";
+import { type AnyWorkflowUnit, UnitFactory } from "./units/factory";
+import {
+    getDefaultDescription,
+    getHumanReadableProperties,
+    getHumanReadableUsedModels,
+    getProperties,
+    getSystemName,
+    getUsedApplications,
+    getUsedModels,
+} from "./utils/workflow";
+import defaultWorkflowConfig from "./workflows/default";
+
+interface Workflow
+    extends Defaultable,
+        NamedInMemoryEntity,
+        WorkflowSchemaMixin,
+        Taggable,
+        HashedEntity,
+        ComputedEntityMixin,
+        HasDescription {
+    // TODO: fix ComputedEntityMixin and remove this
+    compute: WorkflowSchema["compute"];
+}
+
+/** Context passed to Workflow.render() before `workflowHasRelaxation` is injected for subworkflows. */
+export type WorkflowRenderContext = MaterialExternalContext &
+    MaterialsExternalContext &
+    MaterialsSetExternalContext &
+    JobExternalContext;
+
+class Workflow extends InMemoryEntity implements WorkflowSchema {
+    declare createDefault: () => Workflow;
+
+    static readonly defaultConfig = defaultWorkflowConfig;
+
+    declare _json: WorkflowSchema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow");
+    }
+
+    subworkflowInstances: Subworkflow[];
+
+    unitInstances!: AnyWorkflowUnit[];
+
+    workflowInstances: Workflow[];
+
+    repetition = 0;
+
+    totalRepetitions = 1;
+
+    setTotalRepetitions(totalRepetition: number) {
+        this.totalRepetitions = totalRepetition;
+    }
+
+    setRepetition(repetition: number) {
+        this.repetition = repetition;
+        this.unitInstances.forEach((u) => u.setRepetition(repetition));
+        this.subworkflowInstances.forEach((sw) => sw.setRepetition(repetition));
+        this.workflowInstances.forEach((wf) => wf.setRepetition(repetition));
+    }
+
+    static fromSubworkflow(subworkflow: Subworkflow) {
+        const config = {
+            name: subworkflow.name,
+            subworkflows: [subworkflow.toJSON()],
+            units: [subworkflow.getAsUnit().toJSON()],
+            properties: subworkflow.properties,
+            applicationName: subworkflow.application.name,
+            workflows: [] as WorkflowSchema[],
+        };
+        return new this(config);
+    }
+
+    constructor(config: WorkflowSchema & { applicationName?: string }) {
+        super({
+            ...config,
+            _id: config._id || Utils.uuid.getUUID(),
+        });
+
+        this.subworkflowInstances = this.subworkflows.map((x) => new Subworkflow(x));
+        this.workflowInstances = this.workflows?.map((x) => new Workflow(x)) || [];
+        this.setUnits(this.units.map((unit) => UnitFactory.createInWorkflow(unit)));
+    }
+
+    get workflows() {
+        return this.requiredProp<WorkflowSchema[]>("workflows");
+    }
+
+    set workflows(value: WorkflowSchema[]) {
+        this.setProp("workflows", value);
+    }
+
+    addSubworkflow(subworkflow: Subworkflow, head = false, index = -1) {
+        const subworkflowUnit = subworkflow.getAsUnit();
+
+        if (head) {
+            this.subworkflowInstances.unshift(subworkflow);
+            this.addUnit(subworkflowUnit, head, index);
+        } else {
+            this.subworkflowInstances.push(subworkflow);
+            this.addUnit(subworkflowUnit, head, index);
+        }
+    }
+
+    updateMethodData(materials: Material[], metaProperties: MetaPropertyHolder[]) {
+        this.subworkflowInstances.forEach((sw) => {
+            sw.updateMethodData(materials, metaProperties);
+        });
+    }
+
+    removeSubworkflow(id: string) {
+        const subworkflowUnit = this.unitInstances.find((u) => u.id === id);
+
+        if (subworkflowUnit) {
+            this.removeUnit(subworkflowUnit.flowchartId);
+        }
+    }
+
+    setUnits(arr: AnyWorkflowUnit[]) {
+        this.unitInstances = setUnitLinks(arr);
+        this.units = this.unitInstances.map((u) => u.toJSON());
+    }
+
+    /**
+     * A top-level subworkflow branch is represented twice: a {@link UnitType.subworkflow} unit in
+     * `unitInstances` (flowchart card) and a full {@link Subworkflow} in `subworkflowInstances`
+     * (linked by the same `id` as {@link Subworkflow.getAsUnit}). Their display names must match
+     * so `toJSON()` and editors stay consistent. Call this after mutating a subworkflow unit's
+     * `name` (and updating `unitInstances` via {@link setUnits}).
+     */
+    syncLinkedSubworkflowNameFromUnit(unit: AnyWorkflowUnit): void {
+        if (unit.type !== UnitType.subworkflow) return;
+        const linked = this.subworkflowInstances.find((s) => s.id === unit.id);
+        linked?.setName(unit.name);
+    }
+
+    render(context: WorkflowRenderContext) {
+        this.subworkflowInstances.forEach((sw) => {
+            sw.render({
+                ...context,
+                workflowHasRelaxation: this.hasRelaxation,
+            });
+        });
+        this.workflowInstances.forEach((wf) => {
+            wf.render(context);
+        });
+    }
+
+    get usedApplications(): ApplicationSchema[] {
+        return getUsedApplications(this);
+    }
+
+    // return application names
+    get usedApplicationNames() {
+        return this.usedApplications.map((a) => a.name);
+    }
+
+    get usedApplicationVersions() {
+        return this.usedApplications.map((a) => a.version);
+    }
+
+    get usedApplicationNamesWithVersions() {
+        return this.usedApplications.map((a) => `${a.name} ${a.version}`);
+    }
+
+    getUsedModels() {
+        return getUsedModels(this);
+    }
+
+    getHumanReadableUsedModels() {
+        return getHumanReadableUsedModels(this);
+    }
+
+    toJSON(): WorkflowSchema & AnyObject {
+        return {
+            ...super.toJSON(),
+            name: this.name,
+            properties: getProperties(this),
+            units: this.unitInstances.map((x) => x.toJSON()),
+            subworkflows: this.subworkflowInstances.map((x) => x.toJSON()),
+            workflows: this.workflowInstances.map((x) => x.toJSON()),
+        };
+    }
+
+    getHumanReadableProperties() {
+        return getHumanReadableProperties(this);
+    }
+
+    getProperties() {
+        return getProperties(this);
+    }
+
+    getSystemName() {
+        return getSystemName(this);
+    }
+
+    getDefaultDescription() {
+        return getDefaultDescription(this);
+    }
+
+    private addUnit(unit: AnyWorkflowUnit, head = false, index = -1) {
+        const [...unitInstances] = this.unitInstances;
+
+        if (unitInstances.length === 0) {
+            this.setUnits([unit]);
+        } else {
+            if (head) {
+                unitInstances.unshift(unit);
+            } else if (index >= 0) {
+                unitInstances.splice(index, 0, unit);
+            } else {
+                unitInstances.push(unit);
+            }
+            this.setUnits(unitInstances);
+        }
+    }
+
+    removeUnit(flowchartId: string) {
+        if (this.units.length < 2) {
+            return;
+        }
+
+        const unit = this.unitInstances.find((x) => x.flowchartId === flowchartId);
+        if (!unit) {
+            return;
+        }
+
+        const previousUnit = this.unitInstances.find((x) => x.next === unit.flowchartId);
+        if (previousUnit) {
+            delete previousUnit.next;
+        }
+
+        this.subworkflowInstances = this.subworkflowInstances.filter((x) => x.id !== unit.id);
+
+        this.setUnits(this.unitInstances.filter((x) => x.flowchartId !== flowchartId));
+    }
+
+    /*
+     * @param type {String|Object} Unit type, map or subworkflow
+     * @param head {Boolean}
+     * @param index {Number} Index at which the unit will be added. -1 by default (ignored).
+     */
+    addUnitType(type: UnitType, head = false, index = -1) {
+        switch (type) {
+            case UnitType.map: {
+                const mapWorkflowConfig = {
+                    ...defaultWorkflowConfig,
+                    _id: Utils.uuid.getUUID(),
+                };
+                const mapUnit = new MapUnit({
+                    workflowId: mapWorkflowConfig._id,
+                });
+
+                this.workflows = [...(this.workflows || []), mapWorkflowConfig];
+                this.workflowInstances = this.workflows.map((x) => new Workflow(x));
+
+                this.addUnit(mapUnit, head, index);
+
+                break;
+            }
+            case UnitType.subworkflow:
+                this.addSubworkflow(Subworkflow.createDefault(), head, index);
+                break;
+            default:
+                console.log(`unit_type=${type} unrecognized, skipping.`);
+        }
+    }
+
+    addMapUnit(mapUnit: MapUnit, mapWorkflow: Workflow) {
+        const mapWorkflowConfig = {
+            _id: Utils.uuid.getUUID(),
+            ...mapWorkflow.toJSON(),
+        };
+
+        mapUnit.setWorkflowId(mapWorkflowConfig._id);
+        this.addUnit(mapUnit);
+
+        this.workflows = [...(this.workflows || []), mapWorkflowConfig];
+        this.workflowInstances = this.workflows.map((x) => new Workflow(x));
+    }
+
+    get allSubworkflows() {
+        const subworkflowsList: Subworkflow[] = [];
+        this.subworkflowInstances.forEach((sw) => subworkflowsList.push(sw));
+        this.workflowInstances.forEach((workflow) => {
+            return Array.prototype.push.apply(subworkflowsList, workflow.allSubworkflows);
+        });
+        return subworkflowsList;
+    }
+
+    get hasRelaxation() {
+        return Boolean(this.getRelaxationSubworkflow());
+    }
+
+    toggleRelaxation() {
+        const relaxSubworkflow = this.getRelaxationSubworkflow();
+        if (relaxSubworkflow?._id) {
+            this.removeSubworkflow(relaxSubworkflow._id);
+        } else {
+            const vcRelax = this.getStandataRelaxationSubworkflow();
+            if (vcRelax) {
+                this.addSubworkflow(new Subworkflow(vcRelax), true);
+            }
+        }
+    }
+
+    getHashObject() {
+        return {
+            units: this.unitInstances.map((u) => u.calculateHash()).join(),
+            subworkflows: this.subworkflowInstances.map((sw) => sw.calculateHash()).join(),
+            workflows: this.workflowInstances.map((w) => w.calculateHash()).join(),
+        };
+    }
+
+    private getStandataRelaxationSubworkflow() {
+        // TODO: fix standata type
+        const subworkflow = new SubworkflowStandata().getRelaxationSubworkflowByApplication(
+            this.subworkflowInstances[0].application.name,
+        ) as unknown as SubworkflowSchema | undefined;
+
+        if (!subworkflow) {
+            return undefined;
+        }
+
+        const executionUnit = subworkflow.units.find((unit) => unit.type === UnitType.execution);
+        if (!executionUnit) {
+            throw new Error("Relaxation subworkflow is missing an execution unit");
+        }
+
+        return {
+            ...subworkflow,
+            application: executionUnit.application,
+        };
+    }
+
+    private getRelaxationSubworkflow() {
+        const standataSubworkflow = this.getStandataRelaxationSubworkflow();
+
+        return this.subworkflowInstances.find((sw) => {
+            return standataSubworkflow && standataSubworkflow.systemName === sw.systemName;
+        });
+    }
+}
+
+namedEntityMixin(Workflow.prototype);
+workflowSchemaMixin(Workflow.prototype);
+taggableMixin(Workflow.prototype);
+computedEntityMixin(Workflow.prototype);
+defaultableEntityMixin(Workflow);
+hashedEntityMixin(Workflow.prototype);
+hasDescriptionMixin(Workflow.prototype);
+
+export default Workflow;

package/src/js/context/mixins/ApplicationContextMixin.ts

@@ -0,0 +1,21 @@
+import type { ApplicationSchema } from "@mat3ra/esse/dist/js/types";
+
+import type ContextProvider from "../providers/base/ContextProvider";
+
+export type ApplicationContextMixin = {
+    application: ApplicationSchema;
+    initApplicationContextMixin(externalContext: ApplicationExternalContext): void;
+};
+
+export type ApplicationExternalContext = { application: ApplicationSchema };
+
+export default function applicationContextMixin(item: ContextProvider) {
+    // @ts-expect-error
+    const properties: ContextProvider & ApplicationContextMixin = {
+        initApplicationContextMixin(externalContext: ApplicationExternalContext) {
+            this.application = externalContext.application;
+        },
+    };
+
+    Object.defineProperties(item, Object.getOwnPropertyDescriptors(properties));
+}

package/src/js/context/mixins/MaterialContextMixin.ts

@@ -0,0 +1,35 @@
+import type { OrderedInMemoryEntityInSet } from "@mat3ra/code/dist/js/entity/set/ordered/OrderedInMemoryEntityInSetMixin";
+import { Material } from "@mat3ra/made/dist/js/material";
+
+import type ContextProvider from "../providers/base/ContextProvider";
+
+export type OrderedMaterial = OrderedInMemoryEntityInSet & Material;
+
+export type MaterialContextMixin = {
+    readonly isMaterialCreatedDefault: boolean;
+    readonly isMaterialUpdated: boolean;
+    material: OrderedMaterial;
+    extraData?: { materialHash: string };
+    initMaterialContextMixin(externalContext: MaterialExternalContext): void;
+    updateMaterialHash(): void;
+};
+
+export type MaterialExternalContext = {
+    material: OrderedMaterial;
+};
+
+export default function materialContextMixin(item: ContextProvider) {
+    // @ts-expect-error
+    const properties: ContextProvider & MaterialContextMixin = {
+        updateMaterialHash() {
+            this.extraData = { materialHash: this.material.hash };
+        },
+
+        initMaterialContextMixin(externalContext: MaterialExternalContext) {
+            this.material = externalContext.material;
+            this.updateMaterialHash();
+        },
+    };
+
+    Object.defineProperties(item, Object.getOwnPropertyDescriptors(properties));
+}

package/src/js/context/mixins/MaterialsContextMixin.ts

@@ -0,0 +1,24 @@
+import type ContextProvider from "../providers/base/ContextProvider";
+import type { OrderedMaterial } from "./MaterialContextMixin";
+
+export type MaterialsContextMixin = {
+    materials: OrderedMaterial[];
+    initMaterialsContextMixin(externalContext: MaterialsExternalContext): void;
+};
+
+export type MaterialsExternalContext = {
+    materials: OrderedMaterial[];
+};
+
+export default function materialsContextMixin(item: ContextProvider) {
+    // @ts-expect-error
+    const properties: ContextProvider & MaterialsContextMixin = {
+        materials: [],
+
+        initMaterialsContextMixin(externalContext: MaterialsExternalContext) {
+            this.materials = externalContext.materials;
+        },
+    };
+
+    Object.defineProperties(item, Object.getOwnPropertyDescriptors(properties));
+}

package/src/js/context/mixins/MaterialsSetContextMixin.ts

@@ -0,0 +1,42 @@
+import { compareEntitiesInOrderedSetForSorting } from "@mat3ra/code/dist/js/entity/set/ordered/utils";
+
+import type ContextProvider from "../providers/base/ContextProvider";
+import type { OrderedMaterial } from "./MaterialContextMixin";
+
+export type MaterialsSet = {
+    _id: string;
+};
+
+export type MaterialsSetExternalContext = {
+    materialsSet?: MaterialsSet;
+};
+
+export type MaterialsSetContextMixin = {
+    materialsSet?: MaterialsSet;
+    initMaterialsSetContextMixin(externalContext: MaterialsSetExternalContext): void;
+    sortMaterialsByIndexInSet(materials?: OrderedMaterial[]): OrderedMaterial[];
+};
+
+export default function materialsSetContextMixin(item: ContextProvider) {
+    // @ts-expect-error
+    const properties: ContextProvider & MaterialsSetContextMixin = {
+        initMaterialsSetContextMixin(externalContext: MaterialsSetExternalContext) {
+            this.materialsSet = externalContext.materialsSet;
+        },
+
+        sortMaterialsByIndexInSet(materials: OrderedMaterial[] = []) {
+            const { materialsSet } = this;
+
+            if (!materialsSet) {
+                return materials;
+            }
+
+            // DO NOT SORT IN PLACE AS IT CHANGES THE ORDER IN `this.materials` AND HAS SIDE EFFECTS (MaterialViewer).
+            return [...materials].sort((a, b) => {
+                return compareEntitiesInOrderedSetForSorting(a, b, materialsSet._id, false);
+            });
+        },
+    };
+
+    Object.defineProperties(item, Object.getOwnPropertyDescriptors(properties));
+}

package/src/js/context/providers/BoundaryConditionsFormDataManager.ts

@@ -0,0 +1,88 @@
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { JSONSchema } from "@mat3ra/esse/dist/js/esse/utils";
+import type {
+    BoundaryConditionsContextItemSchema,
+    MaterialMetadataBoundaryConditions,
+} from "@mat3ra/esse/dist/js/types";
+
+import materialContextMixin, {
+    type MaterialContextMixin,
+    type MaterialExternalContext,
+} from "../mixins/MaterialContextMixin";
+import type { UnitContext } from "./base/ContextProvider";
+import JSONSchemaDataProvider, { type JinjaExternalContext } from "./base/JSONSchemaDataProvider";
+
+type Schema = BoundaryConditionsContextItemSchema;
+type ExternalContext = JinjaExternalContext & MaterialExternalContext;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface BoundaryConditionsFormDataManager extends MaterialContextMixin {}
+
+const jsonSchemaId = "context-providers-directory/boundary-conditions-data-provider";
+
+// TODO: move to esse
+enum BoundaryConditionsType {
+    pbc = "pbc",
+    bc1 = "bc1",
+    bc2 = "bc2",
+    bc3 = "bc3",
+}
+
+class BoundaryConditionsFormDataManager extends JSONSchemaDataProvider<Schema, ExternalContext> {
+    readonly name = "boundaryConditions" as const;
+
+    readonly domain = "important" as const;
+
+    readonly entityName = "unit" as const;
+
+    static createFromUnitContext(unitContext: UnitContext, externalContext: ExternalContext) {
+        const contextItem = this.findContextItem<Schema>(unitContext, "boundaryConditions");
+
+        return new BoundaryConditionsFormDataManager(contextItem, externalContext);
+    }
+
+    readonly humanName = "Boundary Conditions" as const;
+
+    readonly uiSchema = {
+        type: { "ui:disabled": true },
+        offset: { "ui:disabled": true },
+        electricField: {},
+        targetFermiEnergy: {},
+    } as const;
+
+    constructor(contextItem: Partial<Schema>, externalContext: ExternalContext) {
+        super(contextItem, externalContext);
+        this.initMaterialContextMixin(externalContext);
+    }
+
+    getDefaultData(): Schema["data"] {
+        const metadata = this.material?.metadata as MaterialMetadataBoundaryConditions | undefined;
+
+        return {
+            type: metadata?.boundaryConditions?.type || BoundaryConditionsType.pbc,
+            offset: metadata?.boundaryConditions?.offset || 0,
+            electricField: 0,
+            targetFermiEnergy: 0,
+        };
+    }
+
+    get jsonSchema(): JSONSchema {
+        const defaults = this.getDefaultData();
+        const jsonSchema = JSONSchemasInterface.getPatchedSchemaById(jsonSchemaId, {
+            type: { default: defaults.type },
+            offset: { default: defaults.offset },
+            electricField: { default: defaults.electricField },
+            targetFermiEnergy: { default: defaults.targetFermiEnergy },
+        });
+
+        if (!jsonSchema) {
+            throw new Error("Failed to get patched JSON schema");
+        }
+
+        return jsonSchema;
+    }
+}
+
+materialContextMixin(BoundaryConditionsFormDataManager.prototype);
+
+export default BoundaryConditionsFormDataManager;