Skip to content

Architecture Outline

DeWorks is organised as a modular workflow framework designed to manage materials data, computational processes, and project-level orchestration. Its architecture is structured around several major components, each responsible for a specific stage of the workflow lifecycle. The separation of concerns makes the system extensible, maintainable, and suitable for both small-scale and large-scale computational studies.

Core Architectural Principles

1. Material-Centric Design

At the heart of DeWorks is the concept of a material record, which captures:

  • immutable metadata,

  • the full history of calculations performed,

  • and all computed properties.

Every workflow operates around this central object.

2. Process-Driven Workflows

Each type of calculation (e.g., relaxation, Bader analysis, phonon calculations) is implemented as a process subclass responsible for:

  • generating inputs,

  • launching jobs,

  • tracking progress,

  • and extracting results.

Processes are modular and can be extended to support new methods or back-ends.

3. Project-Level Orchestration

A Project coordinates many materials simultaneously. It manages:

  • record initialisation,

  • shared calculations across many materials,

  • bulk submission,

  • and aggregated result collection.

This supports high-throughput studies across chemical systems.

4. Declarative Models

All major objects (materials, records, processes, properties) are defined using Pydantic models, providing:

  • validation,

  • serialisation,

  • automatic ID generation,

  • and consistent structure.

Package Structure Overview

The major parts of the codebase are organised as follows: 

DeWorks/
│
├── calculations/        # Calculation workflows and utilities
│   ├── processes/       # Individual process subclasses (Relax, Bader, ML_Relax, etc.)
│   ├── cal_util/        # Calculator backends and VASP parameter sets
│   ├── annotations.py   # Type annotations and helper definitions
│   └── base.py          # Abstract process base class
│
├── materials/ (in API docs; partly merged into schema in code)
│
├── Property/            # Property definitions and result handling
│   ├── properties/      # Specific property subclasses (relax, elf, phonon, etc.)
│   └── base.py          # PROPERTY base class
│
├── schema/              # Core data models
│   ├── info.py          # Immutable material metadata
│   ├── record.py        # Material record containing history + results
│   └── project.py       # Project-level coordinator
│
├── util/                # Support utilities
│   ├── parallel.py      # Parallel processing helpers
│   ├── Deep_functions.py
│   ├── Numpy_process.py
│   └── util.py          # Helper functions
│
├── typing.py            # Custom types and literal definitions
├── resolve.py           # Resolution helpers for dynamic loading
└── __init__.py

Component-Level Architecture

1. Schema Layer

Location: schema/ Purpose: Define the persistent data structures that represent materials and projects.

Key classes:

  • Info – immutable metadata describing a material

  • Record – stores calculation history and computed properties

  • Project – manages collections of records and orchestrates multi-material workflows

This layer ensures all data entering the system is well-structured and serialisable.

2. Process Layer

Location: calculations/ Purpose: Implement the logic for computational workflows.

Includes:

  • a base abstract process class,

  • calculator utilities (local, remote, VASP, ML),

  • and specialised processes under processes/.

Processes follow a standard lifecycle:

  1. make() – prepare calculation objects

  2. submit() – send jobs to local or remote execution backends

  3. progress() – monitor job states

  4. output_collate() – extract outputs

  5. write_property() – produce property objects

This ensures consistency across all calculation types.

3. Property Layer

Location: Property/ Purpose: Represent the outputs of workflows in a standardised way.

Properties define:

  • validation rules,

  • serialisation methods,

  • human-readable representations,

  • and integration with records.

Examples include:

  • relaxed geometry,

  • ELF data,

  • phonon properties,

  • convergence metrics.

4. Project Orchestration Layer

Location: schema/project.py Purpose: Coordinate workflows across many materials.

Capabilities include:

  • initiating project directories,

  • preparing all material records,

  • launching calculations across materials,

  • collecting and comparing results,

  • parallel processing during loading and saving.

This enables high-throughput studies across chemical systems such as Fe-O, Li-Si, etc.

5. Utility Layer

Location: util/ Provides additional functionality such as:

  • multiprocessing,

  • deep dictionary manipulation,

  • data transformation,

  • file handling,

  • and numpy-based helpers.

This layer supports the core modules without coupling logic too tightly.

Execution Flow Summary

A typical workflow proceeds through the following stages:

  1. Project initialisation A chemical system is defined, materials are loaded, and records are created.

  2. Process creation For each material, a process (e.g., Relax) is instantiated and attached to the record.

  3. Job generation and submission Jobs are created and submitted to local/remote execution backends.

  4. Monitoring Job states are tracked using jobflow/jobflow_remote.

  5. Result extraction Completed jobs are parsed; results are converted into property objects.

  6. Record update The record is updated with new history entries and properties.

  7. Aggregation Projects collate results across all materials for analysis or export.

This architecture supports reproducibility, parallelisation, and high-throughput execution.