@mat3ra/wode 2025.10.1-0

package/.babelrc

@@ -0,0 +1,17 @@
+{
+    "presets": [
+        [
+            "@babel/preset-env",
+            {
+                "targets": {
+                    "node": "current"
+                }
+            }
+        ],
+        "@babel/preset-react",
+    ],
+    "plugins": [
+        "@babel/plugin-proposal-class-properties"
+    ]
+}
+

package/LICENSE.md

@@ -0,0 +1,15 @@
+# LICENSE
+
+Copyright 2022 Exabyte Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,164 @@
+[![npm version](https://badge.fury.io/js/%40exabyte-io%2Fwode.js.svg)](https://badge.fury.io/js/%40exabyte-io%2Fwode.js)
+[![License: Apache](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+# wode.js
+
+WOrkflow DEfinitions in JavaScript - wode.js - houses entity definitions for use in the Mat3ra platform.
+
+
+## Installation
+
+For usage within a javascript project:
+
+```bash
+npm install @exabyte-io/wode.js
+```
+
+For development:
+
+```bash
+git clone https://github.com/Exabyte-io/wode.js.git
+```
+
+
+## Contribution
+
+This repository is an [open-source](LICENSE.md) work-in-progress and we welcome contributions.
+
+We regularly deploy the latest code containing all accepted contributions online as part of the
+[Mat3ra.com](https://mat3ra.com) platform, so contributors will see their code in action there.
+
+See [ESSE](https://github.com/Exabyte-io/esse) for additional context regarding the data schemas used here.
+
+Useful commands for development:
+
+```bash
+# run linter without persistence
+npm run lint
+
+# run linter and save edits
+npm run lint:fix
+
+# compile the library
+npm run transpile
+
+# run tests
+npm run test
+```
+
+## Using Linter
+
+Linter setup will prevent committing files that don't adhere to the code standard. It will
+attempt to fix what it can automatically prior to the commit in order to reduce diff noise. This can lead to "unexpected" behavior where a
+file that is staged for commit is not identical to the file that actually gets committed. This happens
+in the `lint-staged` directive of the `package.json` file (by using a `husky` pre-commit hook). For example,
+if you add extra whitespace to a file, stage it, and try to commit it, you will see the following:
+
+```bash
+➜  repo-js git:(feature/cool-feature) ✗ git commit -m "Awesome feature works great"
+✔ Preparing...
+✔ Running tasks...
+✖ Prevented an empty git commit!
+✔ Reverting to original state because of errors...
+✔ Cleaning up...
+
+  ⚠ lint-staged prevented an empty git commit.
+  Use the --allow-empty option to continue, or check your task configuration
+
+husky - pre-commit hook exited with code 1 (error)
+```
+
+The staged change may remain but will not have been committed. Then it will look like you still have a staged
+change to commit, but the pre-commit hook will not actually commit it for you, quite frustrating! Styling can
+be applied manually and fixed by running:
+
+```bash
+npm run lint:fix
+```
+
+In which case, you may need to then add the linter edits to your staging, which in the example above, puts the
+file back to identical with the base branch, resulting in no staged changes whatsoever.
+
+
+WoDe
+====
+
+The`WoDe` package synthesizes other entity definition (`De`) libraries
+in the Mat3ra workflow ecosystem and implements the following entities:
+
+- `Workflow` - a workflow to be executed on the Mat3ra platform
+- `Subworkflow` - a logical collection of units of work defined by a unique `Applidation`
+- `Units` - one of the following:
+  - `AssertionUnit` - assert an expression
+  - `AssignmentUnit` - assign a value
+  - `ConditionUnit` - evaluate a condition
+  - `IOUnit` - Read or write data
+  - `ExecutionUnit` - execute an `ADe` `Application`
+  - `MapUnit` - create a dynamic number of units based on output of a previous unit
+  - `ReduceUnit` - collect the results of a fanned out operation
+
+Workflow configurations are processed at build time using `build_workflows.js` and compiled into
+a single JS file so that workflow configurations can be accessed in the browser runtime, not just
+in a NodeJS process.
+
+
+Workflow Spec
+-------------
+
+Workflows defined as configuration conform to the following specification:
+
+- `Workflow: Object` - The workflow configuration itself
+  - `name: String` - a human readable name describing the functionality of the workflow
+  - `units: Array` - a list of workflow units where each unit takes the following shape *Not == Unit*
+    - `name: String` - the snake_case name of a subworkflow or another workflow that must exist
+    - `config: Optional[Object]` - see `Config` defined below
+    - `type: String` - one of:
+      - `subworkflow|workflow`
+        - **Note:** workflow units may specify `mapUnit: true` in their config
+    - `units: Optional[Array]` - if `type == workflow` see above (recursively defined)
+  - `config: Optional[Object]` - see `Config` defined below
+- `Subworkflow: Object` - a logical collection of workflow units
+  - `application: Object` - an application specification
+    - `name: String` - an application name recognized by ADe
+    - `version: Optional[String]` - (often a semver) application version string supported by ADe
+    - `build: Optional[String]` - application build string supported by ADe
+  - `method: Object` - a method specification
+    - `name: String` - a named method class exported from MeDe
+    - `config: Optional[Object]` - see `Config` defined below
+  - `model: Object` - a model specification 
+    - `name: String` - a named model class exported from MeDe
+    - `config: Optional[Object]` - see `Config` defined below
+  - `config: Optional[Object]` - see `Config` defined below
+  - `units: Array` - a list of subworkflow units where each unit is a Unit defined below
+- `Unit: Object` - a unit of computational work in a workflow
+  - `type: String` - one of:
+    - `execution|assignment|condition|io|processing|map|subworkflow|assertion`
+      - **Note:** optionally may have `Builder` appended to type to use unit builders instead of units directly
+        - `executionBuilder` is the primary use case for this
+  - `config: Object` - arguments to pass to constructor based on type
+  - `functions: Object` - similar to `Config`.functions defined below
+    - in the case of builders, functions are applied before calling build
+  - `attributes: Object` - similar to `Config`.attributes defined below
+    - in the case of builders, attributes are applied after calling build
+- `Config: Object` - custom configuration to apply to an entity
+  - **Note:** `functions` and `attributes` may not be supported for all entities, please check the implementation
+  - `functions: Object` - collection of functions defined on the entity to run
+    - `[key]: {{functionName}}: String` - name of function to run
+    - `[value]: {{args}}: Any` - arguments matching the call signature
+  - `attributes: Object` - collection of attributes to assign to the entity on creation
+    - `[key]: {{attributeName}}: String` - name of function to run
+    - `[value]: {{value}}: Any` - value to assign to attribute
+  - `[key]: {{constructorArgument}}: String` - parameter passed to constructor
+  - `[value]: {{constructorValue}}: Any` - value for a given constructor parameter
+
+
+Workflow Creation
+-----------------
+
+The Workflow instances associated with the workflow configurations are built by
+the `createWorkflows` function traversing all three levels (workflow, subworkflow, unit):
+![Workflow Generation Diagram](https://user-images.githubusercontent.com/10773967/196579112-d249cafb-d775-4834-b146-e3dedc796174.jpg)
+
+## Links
+
+1. Workflows explained in Mat3ra documentation: https://docs.mat3ra.com/workflows/overview/

package/assets/subworkflows/deepmd/deepmd.yml

@@ -0,0 +1,31 @@
+application:
+  name: deepmd
+  version: "2.0.2"
+method:
+  name: UnknownMethod
+model:
+  name: UnknownModel
+name: DeePMD
+units:
+  - config:
+      execName: python
+      flavorName: espresso_cp_to_deepmd
+      name: espresso_cp_to_deepmd
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      execName: dp
+      flavorName: dp_train_se_e2_r
+      name: dp_train_se_e2_r
+    type: executionBuilder
+  - config:
+      execName: python
+      flavorName: espresso_to_lammps_structure
+      name: espresso_to_lammps_structure
+    type: executionBuilder
+  - config:
+      execName: lmp
+      flavorName: lammps_md
+      name: lammps_md
+    type: executionBuilder

package/assets/subworkflows/deepmd/espresso_cp_md.yml

@@ -0,0 +1,16 @@
+application:
+  name: espresso
+  version: "7.2"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: CP-MD
+units:
+  - config:
+      execName: cp.x
+      flavorName: cp
+      name: cp
+    functions:
+      head: true
+    type: executionBuilder

package/assets/subworkflows/espresso/average_electrostatic_potential_find_minima.yml

@@ -0,0 +1,27 @@
+# Note: this subworkflow is assumed to be used as part of the valence band offset workflow
+# and is this NOT self-sufficient!
+# Furthermore, this subworkflow expects the following variable(s) to exist in the global context:
+# array_from_context
+application:
+  name: python
+  version: 3.10.13
+method:
+  name: UnknownMethod
+model:
+  name: UnknownModel
+name: Find ESP Value
+units:
+  - config:
+      name: Find Extrema
+      execName: python
+      flavorName: generic:processing:find_extrema:scipy
+      flowchartId: python-find-extrema
+    type: executionBuilder
+  - config:
+      name: Set Average ESP Value
+      operand: AVG_ESP
+      value: "json.loads(STDOUT)['minima']"
+      input:
+        - name: STDOUT
+          scope: python-find-extrema
+    type: assignment

package/assets/subworkflows/espresso/average_electrostatic_potential_via_band_structure.yml

@@ -0,0 +1,67 @@
+config:
+  isMultiMaterial: true
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Band Structure + average ESP
+units:
+  - config:
+      name: Set Material Index
+      operand: MATERIAL_INDEX
+      value: 0
+    type: assignment
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_bands
+      name: pw_bands
+      flowchartId: pw-bands-calculate-band-gap
+    type: executionBuilder
+    attributes:
+      results:
+        - name: band_gaps
+  - config:
+      name: Select indirect band gap
+      operand: BAND_GAP_INDIRECT
+      value: "[bandgap for bandgap in band_gaps['values'] if bandgap['type'] == 'indirect'][0]"
+      input:
+        - name: band_gaps
+          scope: pw-bands-calculate-band-gap
+    type: assignment
+  - config:
+      name: Set Valence Band Maximum
+      operand: VBM
+      value: "BAND_GAP_INDIRECT['eigenvalueValence']"
+    type: assignment
+  - config:
+      execName: bands.x
+      flavorName: bands
+      name: bands
+    type: executionBuilder
+  - config:
+      execName: pp.x
+      flavorName: pp_electrostatic_potential
+      name: Electrostatic Potential (ESP)
+    type: executionBuilder
+  - config:
+      execName: average.x
+      flavorName: average_potential
+      name: average ESP
+      flowchartId: average-electrostatic-potential
+    type: executionBuilder
+  - config:
+      name: Set Macroscopically Averaged ESP Data
+      operand: array_from_context
+      value: "average_potential_profile['yDataSeries'][1]"
+      input:
+        - name: average_potential_profile
+          scope: average-electrostatic-potential
+    type: assignment

package/assets/subworkflows/espresso/band_gap.yml

@@ -0,0 +1,21 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Band Gap
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_nscf
+      name: pw_nscf
+    type: executionBuilder

package/assets/subworkflows/espresso/band_gap_hse_dos.yml

@@ -0,0 +1,30 @@
+name: HSE Band Gap
+application:
+  name: espresso
+  version: "6.3"
+model:
+  name: DFTModel
+  config:
+    type: dft
+    subtype: hybrid
+    functional:
+      name: hse06
+      slug: hse06
+method:
+  name: PseudopotentialMethod
+  config:
+    type: pseudopotential
+    subtype: us
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf_hse
+      name: pw_scf_hse
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      execName: projwfc.x
+      flavorName: projwfc
+      name: projwfc
+    type: executionBuilder

package/assets/subworkflows/espresso/band_structure.yml

@@ -0,0 +1,26 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Band Structure
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_bands
+      name: pw_bands
+    type: executionBuilder
+  - config:
+      execName: bands.x
+      flavorName: bands
+      name: bands
+    type: executionBuilder

package/assets/subworkflows/espresso/band_structure_dos.yml

@@ -0,0 +1,34 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Band Structure + Density of States
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_bands
+      name: pw_bands
+    type: executionBuilder
+  - config:
+      execName: bands.x
+      flavorName: bands
+      name: bands
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_nscf
+      name: pw_nscf
+    type: executionBuilder
+  - config:
+      execName: projwfc.x
+      flavorName: projwfc
+      name: projwfc
+    type: executionBuilder

package/assets/subworkflows/espresso/band_structure_hse.yml

@@ -0,0 +1,30 @@
+# Note: this subworkflow is assumed to be part of the "Band Structure - HSE" workflow
+# and is this NOT self-sufficient!
+name: Band Structure - HSE
+application:
+  name: espresso
+  version: "6.3"
+model:
+  name: DFTModel
+  config:
+    type: dft
+    subtype: hybrid
+    functional:
+      name: hse06
+      slug: hse06
+method:
+  name: PseudopotentialMethod
+  config:
+    type: pseudopotential
+    subtype: us
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf_bands_hse
+      name: pw_scf_bands_hse
+    type: executionBuilder
+  - config:
+      execName: bands.x
+      flavorName: bands
+      name: bands
+    type: executionBuilder

package/assets/subworkflows/espresso/band_structure_magn.yml

@@ -0,0 +1,31 @@
+name: Spin magnetic bandstructure
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf_magn
+      name: pw_scf_magn
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_bands_magn
+      name: pw_bands_magn
+    type: executionBuilder
+  - config:
+      execName: bands.x
+      flavorName: bands_spin_up
+      name: bands_spin_up
+    type: executionBuilder
+  - config:
+      execName: bands.x
+      flavorName: bands_spin_dn
+      name: bands_spin_dn
+    type: executionBuilder

package/assets/subworkflows/espresso/band_structure_soc.yml

@@ -0,0 +1,30 @@
+name: Spin orbit coupling bandstructure
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+  setSearchText: nc-fr
+  config:
+    type: pseudopotential
+    subtype: nc-fr
+model:
+  name: DFTModel
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf_soc
+      name: pw_scf_soc
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_bands_soc
+      name: pw_bands_soc
+    type: executionBuilder
+  - config:
+      execName: bands.x
+      flavorName: bands
+      name: bands
+    type: executionBuilder

package/assets/subworkflows/espresso/dielectric_tensor.yml

@@ -0,0 +1,35 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  config:
+    data: {}
+    subtype: nc
+    type: pseudopotential
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Compute Dielectric Function
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    functions:
+      head: true
+    type: executionBuilder
+  - config:
+      name: Set No-Symmetry Flag
+      operand: NO_SYMMETRY_NO_INVERSION
+      value: True # yamllint disable-line rule:truthy
+    type: assignment
+  - config:
+      execName: pw.x
+      flavorName: pw_nscf
+      name: pw_nscf
+    type: executionBuilder
+  - config:
+      execName: epsilon.x
+      flavorName: dielectric_tensor
+      name: Compute dielectric function
+    type: executionBuilder

package/assets/subworkflows/espresso/dos.yml

@@ -0,0 +1,24 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Density of States
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    type: executionBuilder
+  - config:
+      execName: pw.x
+      flavorName: pw_nscf
+      name: pw_nscf
+    type: executionBuilder
+  - config:
+      execName: projwfc.x
+      flavorName: projwfc
+      name: projwfc
+    type: executionBuilder

package/assets/subworkflows/espresso/electronic_density_mesh.yml

@@ -0,0 +1,19 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Electronic Density Mesh
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_scf
+      name: pw_scf
+    type: executionBuilder
+  - config:
+      execName: pp.x
+      flavorName: pp_density
+      name: pp_density
+    type: executionBuilder

package/assets/subworkflows/espresso/esm.yml

@@ -0,0 +1,14 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Effective Screening Medium (ESM)
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_esm
+      name: pw_esm
+    type: executionBuilder

package/assets/subworkflows/espresso/esm_relax.yml

@@ -0,0 +1,14 @@
+application:
+  name: espresso
+  version: "6.3"
+method:
+  name: PseudopotentialMethod
+model:
+  name: DFTModel
+name: Effective Screening Medium (ESM) Relax
+units:
+  - config:
+      execName: pw.x
+      flavorName: pw_esm_relax
+      name: pw_esm_relax
+    type: executionBuilder

package/assets/subworkflows/espresso/espresso_extract_kpoints.yml

@@ -0,0 +1,16 @@
+# Note: this subworkflow is assumed to be run after a pw_scf unit
+# and is this NOT self-sufficient!
+name: Extract KPOINTS
+application:
+  name: python
+  version: 3.10.13
+method:
+  name: UnknownMethod
+model:
+  name: UnknownModel
+units:
+  - config:
+      name: Extract kpoints
+      execName: python
+      flavorName: espresso_extract_kpoints
+    type: executionBuilder