@mat3ra/wode 2025.10.1-0

package/src/subworkflows/create.js

@@ -0,0 +1,201 @@
+import ApplicationRegistry from "@exabyte-io/ade.js/dist/js/ApplicationRegistry";
+import {
+    default_methods as MethodConfigs,
+    default_models as ModelConfigs,
+    MethodFactory,
+    ModelFactory,
+} from "@exabyte-io/mode.js";
+import { workflowSubforkflowMapByApplication } from "@mat3ra/standata";
+import _ from "lodash";
+
+import { UnitFactory } from "../units";
+import { builders } from "../units/builders";
+import { applyConfig } from "../utils";
+import { dynamicSubworkflowsByApp, getSurfaceEnergySubworkflowUnits } from "./dynamic";
+import { Subworkflow } from "./subworkflow";
+
+// NOTE: DFTModel => DFTModelConfig, configs should have the same name as the model/method class + "Config" at the end
+function _getConfigFromModelOrMethodName(name, kind) {
+    const configs = kind === "Model" ? ModelConfigs : MethodConfigs;
+    if (!configs[`${name}Config`]) {
+        // eslint-disable-next-line no-param-reassign
+        name = `Unknown${kind}`;
+    }
+    return configs[`${name}Config`];
+}
+
+/**
+ * @summary Create model from subworkflow data
+ * @param config {Object} model config
+ * @param modelFactoryCls {any} model factory to use
+ * @returns {DFTModel|Model}
+ */
+function createModel({ config, modelFactoryCls }) {
+    const { name, config: modelConfig = {} } = config;
+    const defaultConfig = _getConfigFromModelOrMethodName(name, "Model");
+    return modelFactoryCls.create({ ...defaultConfig, ...modelConfig });
+}
+
+/**
+ * @summary Create method from subworkflow data
+ * @param config {Object} method configuration
+ * @param methodFactoryCls {any}
+ * @returns {{method, setSearchText}}
+ */
+function createMethod({ config, methodFactoryCls }) {
+    const { name, setSearchText = null, config: methodConfig = {} } = config;
+    const defaultConfig = _getConfigFromModelOrMethodName(name, "Method");
+    const method = methodFactoryCls.create({ ...defaultConfig, ...methodConfig });
+    return { method, setSearchText };
+}
+
+/**
+ * @summary Create top-level objects used in subworkflow initialization
+ * @param subworkflowData {Object} subworkflow data
+ * @param AppRegistry
+ * @param modelFactoryCls {any} model factory class
+ * @param methodFactoryCls {any} method factory class
+ * @returns {{application: *, method: *, model: (DFTModel|Model), setSearchText: String|null}}
+ */
+function createTopLevel({ subworkflowData, modelFactoryCls, methodFactoryCls, AppRegistry }) {
+    const { application: appConfig, model: modelConfig, method: methodConfig } = subworkflowData;
+    const application = AppRegistry.createApplication(appConfig);
+    const model = createModel({ config: modelConfig, modelFactoryCls });
+    const { method, setSearchText } = createMethod({ config: methodConfig, methodFactoryCls });
+    return {
+        application,
+        model,
+        method,
+        setSearchText,
+    };
+}
+
+/**
+ * @summary Create workflow unit from JSON configuration
+ *      Supports applying functions to the builder prior to building via "functions"
+ *      Supports applying attributes to the builder after building via "attributes"
+ * @param config {Object} unit config
+ * @param application {*} application
+ * @param unitBuilders {Object} workflow unit builders
+ * @param unitFactoryCls {*} workflow unit class factory
+ * @returns {*|{head: boolean, preProcessors: [], postProcessors: [], name: *, flowchartId: *, type: *, results: [], monitors: []}}
+ */
+export function createUnit({ config, application, unitBuilders, unitFactoryCls }) {
+    const { type, config: unitConfig } = config;
+    if (type === "executionBuilder") {
+        const { name, execName, flavorName, flowchartId } = unitConfig;
+        const builder = new unitBuilders.ExecutionUnitConfigBuilder(
+            name,
+            application,
+            execName,
+            flavorName,
+            flowchartId,
+        );
+
+        // config should contain "functions" and "attributes"
+        const cfg = applyConfig({ obj: builder, config, callBuild: true });
+        return unitFactoryCls.create(cfg);
+    }
+
+    return unitFactoryCls.create({ type, ...unitConfig });
+}
+
+/**
+ * @summary Dynamically create subworkflow units
+ * @param dynamicSubworkflow {String} name of unit creation function
+ * @param units {Array} configured units to provide to dynamic unit creation
+ * @param unitBuilders {Object} unit configuration builders
+ * @param unitFactoryCls {*} unit factory class
+ * @param application {*} application (optional)
+ * @returns {*}
+ */
+function createDynamicUnits({
+    dynamicSubworkflow,
+    units,
+    unitBuilders,
+    unitFactoryCls,
+    application = null,
+}) {
+    const { name, subfolder } = dynamicSubworkflow;
+    const func = subfolder && _.get(dynamicSubworkflowsByApp, `${subfolder}.${name}`, () => {});
+    switch (name) {
+        case "surfaceEnergy":
+            // eslint-disable-next-line no-case-declarations
+            const [scfUnit] = units;
+            return getSurfaceEnergySubworkflowUnits({ scfUnit, unitBuilders });
+        case "getQpointIrrep":
+            return func({ unitBuilders, unitFactoryCls, application });
+        default:
+            throw new Error(`dynamicSubworkflow=${name} not recognized`);
+    }
+}
+
+function createSubworkflow({
+    subworkflowData,
+    AppRegistry = ApplicationRegistry,
+    modelFactoryCls = ModelFactory,
+    methodFactoryCls = MethodFactory,
+    subworkflowCls = Subworkflow,
+    unitFactoryCls = UnitFactory,
+    unitBuilders = builders,
+}) {
+    const { application, model, method, setSearchText } = createTopLevel({
+        subworkflowData,
+        AppRegistry,
+        modelFactoryCls,
+        methodFactoryCls,
+    });
+
+    let units = [];
+    const { name, units: unitConfigs, config = {}, dynamicSubworkflow = null } = subworkflowData;
+    unitConfigs.forEach((_config) => {
+        units.push(
+            createUnit({
+                config: _config,
+                application,
+                unitBuilders,
+                unitFactoryCls,
+            }),
+        );
+    });
+    if (dynamicSubworkflow) {
+        units = createDynamicUnits({
+            dynamicSubworkflow,
+            units,
+            unitBuilders,
+            unitFactoryCls,
+            application,
+        });
+    }
+
+    const { functions = {}, attributes = {}, ...cfg } = config;
+    let subworkflow = subworkflowCls.fromArguments(application, model, method, name, units, cfg);
+    subworkflow = applyConfig({ obj: subworkflow, config: { functions, attributes } });
+    if (setSearchText) subworkflow.model.method.setSearchText(setSearchText);
+    return subworkflow;
+}
+
+/**
+ * @summary Convenience wrapper around createSubworkflow to create by app name and swf name
+ * @param appName {String} application name
+ * @param swfName {String} subworkflow name (snake_case.yml)
+ * @param workflowSubworkflowMapByApplication {Object} object containing all workflow/subworkflow map by application
+ * @param swArgs {Object} classes for instantiation
+ * @returns {*} subworkflow object
+ */
+function createSubworkflowByName({
+    appName,
+    swfName,
+    workflowSubworkflowMapByApplication = workflowSubforkflowMapByApplication,
+    ...swArgs
+}) {
+    const { subworkflows } = workflowSubworkflowMapByApplication;
+    const { [appName]: allSubworkflowData } = subworkflows;
+    const { [swfName]: subworkflowData } = allSubworkflowData;
+    return createSubworkflow({
+        subworkflowData,
+        ...swArgs,
+    });
+}
+
+export { createSubworkflow, createSubworkflowByName };

package/src/subworkflows/dynamic/espresso/getQpointIrrep.js

@@ -0,0 +1,35 @@
+import { UNIT_TYPES } from "../../../enums";
+
+/**
+ * @summary Get QptIrr units used in phonon map calculations
+ * @param unitBuilders {Object} unit builders
+ * @param unitFactoryCls {*} unit factory class
+ * @param application {*} application instance
+ * @returns {[{head: boolean, preProcessors: [], postProcessors: [], name: *, flowchartId: *, type: *, results: [], monitors: []},*]}
+ */
+function getQpointIrrep({ unitBuilders, unitFactoryCls, application }) {
+    const { ExecutionUnitConfigBuilder } = unitBuilders;
+
+    const pythonUnit = new ExecutionUnitConfigBuilder(
+        "python",
+        application,
+        "python",
+        "espresso_xml_get_qpt_irr",
+    ).build();
+
+    const assignmentUnit = unitFactoryCls.create({
+        type: UNIT_TYPES.assignment,
+        input: [
+            {
+                scope: pythonUnit.flowchartId,
+                name: "STDOUT",
+            },
+        ],
+        operand: "Q_POINTS",
+        value: "json.loads(STDOUT)",
+    });
+
+    return [pythonUnit, assignmentUnit];
+}
+
+export { getQpointIrrep };

package/src/subworkflows/dynamic/index.js

@@ -0,0 +1,8 @@
+import { getQpointIrrep } from "./espresso/getQpointIrrep";
+import { getSurfaceEnergySubworkflowUnits } from "./surfaceEnergy";
+
+const dynamicSubworkflowsByApp = {
+    espresso: { getQpointIrrep },
+};
+
+export { getSurfaceEnergySubworkflowUnits, dynamicSubworkflowsByApp };

package/src/subworkflows/dynamic/surfaceEnergy.js

@@ -0,0 +1,124 @@
+import { Utils } from "@mat3ra/utils";
+
+function getIOUnitEndpointOptions(query, projection = "{}") {
+    return {
+        params: {
+            query,
+            projection,
+        },
+    };
+}
+
+function getAssignmentUnitInput(unit, name) {
+    return [
+        {
+            name,
+            scope: unit.flowchartId,
+        },
+    ];
+}
+
+function getSurfaceEnergySubworkflowUnits({ scfUnit, unitBuilders }) {
+    const { IOUnitConfigBuilder, AssignmentUnitConfigBuilder, AssertionUnitConfigBuilder } =
+        unitBuilders;
+
+    let input, endpointOptions;
+    endpointOptions = getIOUnitEndpointOptions("{'_id': MATERIAL_ID}");
+    const getSlabUnit = new IOUnitConfigBuilder("io-slab", "materials", endpointOptions).build();
+
+    input = getAssignmentUnitInput(getSlabUnit, "DATA");
+    const setSlabUnit = new AssignmentUnitConfigBuilder("slab", "SLAB", "DATA[0]", input).build();
+
+    endpointOptions = getIOUnitEndpointOptions("{'_id': SLAB.metadata.bulkId}");
+    const getBulkUnit = new IOUnitConfigBuilder("io-bulk", "materials", endpointOptions).build();
+
+    const BULKValue = "DATA[0] if DATA else None";
+    input = getAssignmentUnitInput(getBulkUnit, "DATA");
+    const setBulkUnit = new AssignmentUnitConfigBuilder("bulk", "BULK", BULKValue, input).build();
+
+    const assertBulkUnit = new AssertionUnitConfigBuilder(
+        "assert-bulk",
+        "BULK != None",
+        "Bulk material does not exist!",
+    ).build();
+
+    const query = Utils.str.removeNewLinesAndExtraSpaces(`{
+        'exabyteId': BULK.exabyteId,
+        'data.name': 'total_energy',
+        'group': {'$regex': ''.join((SUBWORKFLOW.application.shortName, ':'))}
+    }`);
+    // Do not confuse `sort` with `$sort`. `sort` is used in meteor collections and `$sort` is used in Mongo queries.
+    const projection = "{'sort': {'precision.value': -1}, 'limit': 1}";
+    endpointOptions = getIOUnitEndpointOptions(query, projection);
+    const getEBulkUnit = new IOUnitConfigBuilder(
+        "io-e-bulk",
+        "refined-properties",
+        endpointOptions,
+    ).build();
+
+    input = getAssignmentUnitInput(getEBulkUnit, "DATA");
+    const EBULKValue = "DATA[0].data.value if DATA else None";
+    const setEBulkUnit = new AssignmentUnitConfigBuilder(
+        "e-bulk",
+        "E_BULK",
+        EBULKValue,
+        input,
+    ).build();
+
+    const assertEBulkUnit = new AssertionUnitConfigBuilder(
+        "assert-e-bulk",
+        "E_BULK != None",
+        "E_BULK does not exist!",
+    ).build();
+
+    const AValue = "np.linalg.norm(np.cross(SLAB.lattice.vectors.a, SLAB.lattice.vectors.b))";
+    const setSurfaceUnit = new AssignmentUnitConfigBuilder("surface", "A", AValue).build();
+
+    const setNBulkUnit = new AssignmentUnitConfigBuilder(
+        "n-bulk",
+        "N_BULK",
+        "len(BULK.basis.elements)",
+    ).build();
+    const setNSlabUnit = new AssignmentUnitConfigBuilder(
+        "n-slab",
+        "N_SLAB",
+        "len(SLAB.basis.elements)",
+    ).build();
+
+    input = getAssignmentUnitInput(scfUnit, "total_energy");
+    const setESlabUnit = new AssignmentUnitConfigBuilder(
+        "e-slab",
+        "E_SLAB",
+        "total_energy",
+        input,
+    ).build();
+
+    const results = [{ name: "surface_energy" }];
+    const SEValue = "1 / (2 * A) * (E_SLAB - E_BULK * (N_SLAB/N_BULK))";
+    const surfaceEnergyUnit = new AssignmentUnitConfigBuilder(
+        "surface-energy",
+        "SURFACE_ENERGY",
+        SEValue,
+        [],
+        results,
+    ).build();
+
+    return [
+        getSlabUnit,
+        setSlabUnit,
+        getBulkUnit,
+        setBulkUnit,
+        assertBulkUnit,
+        getEBulkUnit,
+        setEBulkUnit,
+        assertEBulkUnit,
+        setSurfaceUnit,
+        setNBulkUnit,
+        setNSlabUnit,
+        scfUnit,
+        setESlabUnit,
+        surfaceEnergyUnit,
+    ];
+}
+
+export { getSurfaceEnergySubworkflowUnits };

package/src/subworkflows/index.js

@@ -0,0 +1,2 @@
+export { Subworkflow } from "./subworkflow";
+export { createSubworkflowByName } from "./create";

package/src/subworkflows/subworkflow.js

@@ -0,0 +1,329 @@
+import { Application } from "@exabyte-io/ade.js";
+import { Model, ModelFactory } from "@exabyte-io/mode.js";
+import {
+    ContextAndRenderFieldsMixin,
+    NamedDefaultableRepetitionImportantSettingsInMemoryEntity,
+} from "@mat3ra/code/dist/js/entity";
+import { Utils } from "@mat3ra/utils";
+import lodash from "lodash";
+import { mix } from "mixwith";
+import _ from "underscore";
+
+import { UNIT_TYPES } from "../enums";
+import { UnitFactory } from "../units";
+import { setNextLinks, setUnitsHead } from "../utils";
+import { ConvergenceMixin } from "./convergence";
+
+/* eslint max-classes-per-file:0 */
+
+class BaseSubworkflow extends mix(NamedDefaultableRepetitionImportantSettingsInMemoryEntity).with(
+    ConvergenceMixin,
+    ContextAndRenderFieldsMixin,
+) {}
+
+export class Subworkflow extends BaseSubworkflow {
+    static usePredefinedIds = false;
+
+    constructor(config) {
+        super(config);
+        this._Application = Application;
+        this._ModelFactory = ModelFactory;
+        this._UnitFactory = UnitFactory;
+        this.initialize();
+    }
+
+    initialize() {
+        this._application = new this._Application(this.prop("application"));
+        this._model = this._ModelFactory.create({
+            ...this.prop("model"),
+            application: this.prop("application"),
+        });
+        this._units = setNextLinks(setUnitsHead(this.prop("units", [])), this.id).map((cfg) =>
+            this._UnitFactory.create(
+                Object.assign(cfg, { application: this.application.toJSON() }),
+            ),
+        );
+    }
+
+    static generateSubworkflowId(...args) {
+        args[0] = `subworkflow-${args[0]}`;
+        if (this.usePredefinedIds) return Utils.uuid.getUUIDFromNamespace(...args);
+        return Utils.uuid.getUUID();
+    }
+
+    static get defaultConfig() {
+        const defaultName = "New Subworkflow";
+        return {
+            _id: this.generateSubworkflowId(defaultName),
+            name: defaultName,
+            application: Application.defaultConfig,
+            model: Model.defaultConfig,
+            properties: [],
+            units: [],
+        };
+    }
+
+    /*
+     * @returns {SubworkflowUnit}
+     */
+    getAsUnit() {
+        return this._UnitFactory.create({
+            type: UNIT_TYPES.subworkflow,
+            _id: this.id,
+            name: this.name,
+        });
+    }
+
+    /*
+     * @summary Used to generate initial application tree, therefore omit setting application.
+     */
+    static fromArguments(
+        application,
+        model,
+        method,
+        name,
+        units = [],
+        config = {},
+        Cls = Subworkflow,
+    ) {
+        return new Cls({
+            ...config,
+            _id: Cls.generateSubworkflowId(name),
+            name,
+            application: application.toJSON(),
+            properties: lodash.sortedUniq(
+                lodash.flatten(units.filter((x) => x.resultNames).map((x) => x.resultNames)),
+            ),
+            model: {
+                ...model.toJSON(),
+                method: method.toJSON(),
+            },
+            units: units.map((unit) => (unit.toJSON ? unit.toJSON() : unit)),
+        });
+    }
+
+    get application() {
+        return this._application;
+    }
+
+    setApplication(application) {
+        // TODO: adjust the logic above to take into account whether units need re-rendering after version change etc.
+        // reset units if application name changes
+        const previousApplicationName = this.application.name;
+        this._application = application;
+
+        if (previousApplicationName !== application.name) {
+            // TODO: figure out how to set a default unit per new application instead of removing all
+            this.setUnits([]);
+        } else {
+            // propagate new application version to all units
+            this.units
+                .filter((unit) => typeof unit.setApplication === "function")
+                .forEach((unit) => unit.setApplication(application, true));
+        }
+
+        this.setProp("application", application.toJSON());
+        // set model to the default one for the application selected
+        this.setModel(
+            this._ModelFactory.createFromApplication({
+                application: this.prop("application"),
+            }),
+        );
+    }
+
+    get model() {
+        return this._model;
+    }
+
+    setModel(model) {
+        this._model = model;
+    }
+
+    get units() {
+        return this._units;
+    }
+
+    setUnits(units) {
+        this._units = units;
+    }
+
+    toJSON(exclude = []) {
+        return {
+            ...super.toJSON(exclude),
+            model: this.model.toJSON(),
+            units: this.units.map((x) => x.toJSON()),
+            ...(this.compute ? { compute: this.compute } : {}), // {"compute": null } won't pass esse validation
+        };
+    }
+
+    get contextProviders() {
+        const unitsWithContextProviders = this.units.filter(
+            (u) => u.allContextProviders && u.allContextProviders.length,
+        );
+        const allContextProviders = _.flatten(
+            unitsWithContextProviders.map((u) => u.allContextProviders),
+        );
+        const subworkflowContextProviders = allContextProviders.filter(
+            (p) => p.isSubworkflowContextProvider,
+        );
+        return _.uniq(subworkflowContextProviders, (p) => p.name);
+    }
+
+    /**
+     * Extracts a reduced version of the entity config to be stored inside redux state.
+     * This is used to track changes to context, monitors, properties, etc. when multiple materials are in state.
+     */
+    extractReducedExternalDependentConfig() {
+        return {
+            id: this.id,
+            context: this.context || {},
+            units: this.units.map((unit) => unit.extractReducedExternalDependentConfig()),
+        };
+    }
+
+    /**
+     * Applies the reduced config obtained from extractReducedExternalDependentConfig on the entity.
+     */
+    applyReducedExternalDependentConfig(config) {
+        this.context = config.context || {};
+        this.units.forEach((unit) => {
+            const unitConfig = (config.units || []).find((c) => c.id === unit.flowchartId);
+            unit.applyReducedExternalDependentConfig(unitConfig || {});
+        });
+    }
+
+    get contextFromAssignmentUnits() {
+        const ctx = {};
+        this.units
+            .filter((u) => u.type === UNIT_TYPES.assignment)
+            .forEach((u) => {
+                ctx[u.operand] = u.value;
+            });
+        return ctx;
+    }
+
+    render(context = {}) {
+        const ctx = {
+            ...context,
+            application: this.application,
+            methodData: this.model.method.data,
+            model: this.model.toJSON(),
+            // context below is assembled from context providers and passed to units to override theirs
+            ...this.context,
+            subworkflowContext: this.contextFromAssignmentUnits,
+        };
+
+        this.units.forEach((u) => u.render(ctx));
+    }
+
+    /**
+     * TODO: reuse workflow function instead
+     * @param unit {Unit}
+     * @param head {Boolean}
+     * @param index {Number}
+     */
+    addUnit(unit, index = -1) {
+        const { units } = this;
+        if (units.length === 0) {
+            unit.head = true;
+            this.setUnits([unit]);
+        } else {
+            if (index >= 0) units.splice(index, 0, unit);
+            else units.push(unit);
+            this.setUnits(setNextLinks(setUnitsHead(units)));
+        }
+    }
+
+    removeUnit(flowchartId) {
+        const previousUnit = this.units.find((x) => x.next === flowchartId);
+        if (previousUnit) previousUnit.unsetProp("next");
+        // TODO: remove the setNextLinks and setUnitsHead and handle the logic via flowchart designer
+        this.setUnits(
+            setNextLinks(setUnitsHead(this.units.filter((x) => x.flowchartId !== flowchartId))),
+        );
+    }
+
+    get properties() {
+        return lodash.flatten(this.units.map((x) => x.resultNames));
+    }
+
+    getUnit(flowchartId) {
+        return this.units.find((x) => x.flowchartId === flowchartId);
+    }
+
+    unitIndex(flowchartId) {
+        return lodash.findIndex(this.units, (unit) => {
+            return unit.flowchartId === flowchartId;
+        });
+    }
+
+    replaceUnit(index, unit) {
+        this.units[index] = unit;
+        this.setUnits(setNextLinks(setUnitsHead(this.units)));
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    get scopeVariables() {
+        return ["N_k", "N_k_nonuniform"];
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    get scalarResults() {
+        return ["total_energy", "pressure"];
+    }
+
+    get isMultiMaterial() {
+        return this.prop("isMultiMaterial", false);
+    }
+
+    get isDraft() {
+        return this.prop("isDraft", false);
+    }
+
+    setIsDraft(bool) {
+        return this.setProp("isDraft", bool);
+    }
+
+    get methodData() {
+        return this.model.method.data;
+    }
+
+    /**
+     * @summary Calculates hash of the subworkflow. Meaningful fields are units, app and model.
+     * units must be sorted topologically before hashing (already sorted).
+     */
+    calculateHash() {
+        const config = this.toJSON();
+        const meaningfulFields = {
+            application: Utils.specific.removeTimestampableKeysFromConfig(config.application),
+            model: this._calculateModelHash(),
+            units: _.map(this.units, (u) => u.calculateHash()).join(),
+        };
+        return Utils.hash.calculateHashFromObject(meaningfulFields);
+    }
+
+    _calculateModelHash() {
+        const { model } = this.toJSON();
+        // ignore empty data object
+        if (this.model.method.omitInHashCalculation) delete model.method.data;
+        return Utils.hash.calculateHashFromObject(model);
+    }
+
+    findUnitById(id) {
+        // TODO: come back and refactor after converting flowchartId to id
+        return this.units.find((u) => u.flowchartId === id);
+    }
+
+    findUnitKeyById(id) {
+        const index = this.units.findIndex((u) => u.flowchartId === id);
+        return `units.${index}`;
+    }
+
+    findUnitWithTag(tag) {
+        return this.units.find((unit) => unit.tags.includes(tag));
+    }
+
+    get hasConvergence() {
+        return !!this.convergenceParam && !!this.convergenceResult && !!this.convergenceSeries;
+    }
+}