# mala-project/malada architecture

> Architecture diagram of the GitHub repository mala-project/malada, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mala-project/malada
- Repository: https://github.com/mala-project/malada

## Overview

MALADA automates materials-science data acquisition: a user configures parameters and runs a pipeline that prepares a crystal and supercell, converges calculation settings, generates molecular-dynamics data and snapshots, tunes LDOS settings, and performs final DFT calculations. Providers implement the domain stages; runners execute calculations or prepare SLURM submissions. The README describes reproducible dataset generation, while the sampled pipeline confirms the principal stage calls. Some provider and runner internals were not excerpted, so uncertain integration links are omitted or marked unverified.

Main entry points: [`malada/pipeline/pipeline.py`](https://github.com/mala-project/malada/blob/main/malada/pipeline/pipeline.py) (Data pipeline), [`malada/providers/provider.py`](https://github.com/mala-project/malada/blob/main/malada/providers/provider.py) (Provider base), [`malada/providers/dftconvergence.py`](https://github.com/mala-project/malada/blob/main/malada/providers/dftconvergence.py) (DFT convergence), [`malada/providers/dft.py`](https://github.com/mala-project/malada/blob/main/malada/providers/dft.py) (DFT calculations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Acquisition workflow"]
  node_pipeline["Data pipeline<br/>[pipeline.py]"]
end

subgraph group_providers["Data providers"]
  node_crystal["Crystal structure"]
  node_supercell["Supercell<br/>[supercell.py]"]
  node_dftconv["DFT convergence<br/>[dftconvergence.py]"]
  node_mdperf["MD performance<br/>[mdperformance.py]"]
  node_md["MD trajectory<br/>[md.py]"]
  node_snapshots["Snapshot extraction<br/>[snapshots.py]"]
  node_ldosconv["LDOS convergence<br/>[ldosconvergence.py]"]
  node_dft["DFT calculations<br/>[dft.py]"]
  node_providerbase["Provider base<br/>[provider.py]"]
end

subgraph group_execution["Simulation execution"]
  node_runnerinterface["Runner interface"]
  node_bashrunner["Bash runner<br/>[bashrunner.py]"]
  node_slurmrunner["SLURM creator<br/>[slurm_creator.py]"]
  node_runnerbase["Runner base<br/>[runner.py]"]
end

subgraph group_support["Configuration and utilities"]
  node_params["Parameters<br/>[parameters.py]"]
  node_slurmparams["SLURM parameters<br/>[slurmparams.py]"]
  node_convergenceguesses["Convergence guesses"]
  node_converter["Unit converters"]
  node_vasputils["VASP utilities<br/>[vasp_utils.py]"]
end

node_user(("Researcher"))
node_externalcalc["QE or VASP"]
node_dataset["Generated data"]

node_user -->|"configures"| node_params
node_user -->|"runs"| node_pipeline
node_pipeline -->|"uses"| node_params
node_pipeline -->|"requests structure"| node_crystal
node_pipeline -->|"builds supercell"| node_supercell
node_pipeline -->|"converges DFT"| node_dftconv
node_pipeline -->|"checks performance"| node_mdperf
node_pipeline -->|"generates trajectory"| node_md
node_pipeline -->|"extracts snapshots"| node_snapshots
node_pipeline -->|"tunes LDOS"| node_ldosconv
node_pipeline -->|"calculates DFT"| node_dft
node_crystal -->|"inherits"| node_providerbase
node_supercell -->|"inherits"| node_providerbase
node_dftconv -->|"inherits"| node_providerbase
node_mdperf -->|"inherits"| node_providerbase
node_md -->|"inherits"| node_providerbase
node_snapshots -->|"inherits"| node_providerbase
node_ldosconv -->|"inherits"| node_providerbase
node_dft -->|"inherits"| node_providerbase
node_dftconv -->|"uses"| node_convergenceguesses
node_dftconv -->|"uses"| node_converter
node_dftconv -->|"uses"| node_vasputils
node_dft -->|"uses"| node_vasputils
node_dft -->|"dispatches through"| node_runnerinterface
node_dftconv -.->|"runs folders through"| node_runnerinterface
node_runnerinterface -.->|"selects runner"| node_bashrunner
node_runnerinterface -.->|"selects runner"| node_slurmrunner
node_bashrunner -->|"inherits"| node_runnerbase
node_slurmrunner -->|"inherits"| node_runnerbase
node_slurmrunner -->|"reads settings"| node_slurmparams
node_bashrunner -->|"executes"| node_externalcalc
node_slurmrunner -->|"writes job commands"| node_externalcalc
node_pipeline -->|"produces"| node_dataset

click node_params "https://github.com/mala-project/malada/blob/main/malada/utils/parameters.py"
click node_pipeline "https://github.com/mala-project/malada/blob/main/malada/pipeline/pipeline.py"
click node_crystal "https://github.com/mala-project/malada/blob/main/malada/providers/crystalstructure.py"
click node_supercell "https://github.com/mala-project/malada/blob/main/malada/providers/supercell.py"
click node_dftconv "https://github.com/mala-project/malada/blob/main/malada/providers/dftconvergence.py"
click node_mdperf "https://github.com/mala-project/malada/blob/main/malada/providers/mdperformance.py"
click node_md "https://github.com/mala-project/malada/blob/main/malada/providers/md.py"
click node_snapshots "https://github.com/mala-project/malada/blob/main/malada/providers/snapshots.py"
click node_ldosconv "https://github.com/mala-project/malada/blob/main/malada/providers/ldosconvergence.py"
click node_dft "https://github.com/mala-project/malada/blob/main/malada/providers/dft.py"
click node_providerbase "https://github.com/mala-project/malada/blob/main/malada/providers/provider.py"
click node_runnerinterface "https://github.com/mala-project/malada/blob/main/malada/runners/runner_interface.py"
click node_bashrunner "https://github.com/mala-project/malada/blob/main/malada/runners/bashrunner.py"
click node_slurmrunner "https://github.com/mala-project/malada/blob/main/malada/runners/slurm_creator.py"
click node_runnerbase "https://github.com/mala-project/malada/blob/main/malada/runners/runner.py"
click node_slurmparams "https://github.com/mala-project/malada/blob/main/malada/utils/slurmparams.py"
click node_convergenceguesses "https://github.com/mala-project/malada/blob/main/malada/utils/convergence_guesses.py"
click node_converter "https://github.com/mala-project/malada/blob/main/malada/utils/custom_converter.py"
click node_vasputils "https://github.com/mala-project/malada/blob/main/malada/utils/vasp_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipeline toneBlue
class node_crystal,node_supercell,node_dftconv,node_mdperf,node_md,node_snapshots,node_ldosconv,node_dft,node_providerbase toneAmber
class node_runnerinterface,node_bashrunner,node_slurmrunner,node_runnerbase toneMint
class node_params,node_slurmparams,node_convergenceguesses,node_converter,node_vasputils toneRose
class node_user,node_externalcalc,node_dataset toneIndigo
```

## Components

### Acquisition workflow

- [Data pipeline](https://github.com/mala-project/malada/blob/main/malada/pipeline/pipeline.py): `malada/pipeline/pipeline.py`

### Data providers

- [Crystal structure](https://github.com/mala-project/malada/blob/main/malada/providers/crystalstructure.py): `malada/providers/crystalstructure.py`
- [Supercell](https://github.com/mala-project/malada/blob/main/malada/providers/supercell.py): `malada/providers/supercell.py`
- [DFT convergence](https://github.com/mala-project/malada/blob/main/malada/providers/dftconvergence.py): `malada/providers/dftconvergence.py`
- [MD performance](https://github.com/mala-project/malada/blob/main/malada/providers/mdperformance.py): `malada/providers/mdperformance.py`
- [MD trajectory](https://github.com/mala-project/malada/blob/main/malada/providers/md.py): `malada/providers/md.py`
- [Snapshot extraction](https://github.com/mala-project/malada/blob/main/malada/providers/snapshots.py): `malada/providers/snapshots.py`
- [LDOS convergence](https://github.com/mala-project/malada/blob/main/malada/providers/ldosconvergence.py): `malada/providers/ldosconvergence.py`
- [DFT calculations](https://github.com/mala-project/malada/blob/main/malada/providers/dft.py): `malada/providers/dft.py`
- [Provider base](https://github.com/mala-project/malada/blob/main/malada/providers/provider.py): `malada/providers/provider.py`

### Simulation execution

- [Runner interface](https://github.com/mala-project/malada/blob/main/malada/runners/runner_interface.py): `malada/runners/runner_interface.py`
- [Bash runner](https://github.com/mala-project/malada/blob/main/malada/runners/bashrunner.py): `malada/runners/bashrunner.py`
- [SLURM creator](https://github.com/mala-project/malada/blob/main/malada/runners/slurm_creator.py): `malada/runners/slurm_creator.py`
- [Runner base](https://github.com/mala-project/malada/blob/main/malada/runners/runner.py): `malada/runners/runner.py`

### Configuration and utilities

- [Parameters](https://github.com/mala-project/malada/blob/main/malada/utils/parameters.py): `malada/utils/parameters.py`
- [SLURM parameters](https://github.com/mala-project/malada/blob/main/malada/utils/slurmparams.py): `malada/utils/slurmparams.py`
- [Convergence guesses](https://github.com/mala-project/malada/blob/main/malada/utils/convergence_guesses.py): `malada/utils/convergence_guesses.py`
- [Unit converters](https://github.com/mala-project/malada/blob/main/malada/utils/custom_converter.py): `malada/utils/custom_converter.py`
- [VASP utilities](https://github.com/mala-project/malada/blob/main/malada/utils/vasp_utils.py): `malada/utils/vasp_utils.py`

### Other components

- **Researcher**
- **QE or VASP**
- **Generated data**

## Connections

- Researcher → Parameters: configures (evidence: `README.md`)
- Researcher → Data pipeline: runs (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → Parameters: uses (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → Crystal structure: requests structure (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → Supercell: builds supercell (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → DFT convergence: converges DFT (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → MD performance: checks performance (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → MD trajectory: generates trajectory (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → Snapshot extraction: extracts snapshots (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → LDOS convergence: tunes LDOS (evidence: `malada/pipeline/pipeline.py`)
- Data pipeline → DFT calculations: calculates DFT (evidence: `malada/pipeline/pipeline.py`)
- Crystal structure → Provider base: inherits (evidence: `malada/providers/crystalstructure.py`)
- Supercell → Provider base: inherits (evidence: `malada/providers/__init__.py`)
- DFT convergence → Provider base: inherits (evidence: `malada/providers/dftconvergence.py`)
- MD performance → Provider base: inherits (evidence: `malada/providers/__init__.py`)
- MD trajectory → Provider base: inherits (evidence: `malada/providers/__init__.py`)
- Snapshot extraction → Provider base: inherits (evidence: `malada/providers/__init__.py`)
- LDOS convergence → Provider base: inherits (evidence: `malada/providers/ldosconvergence.py`)
- DFT calculations → Provider base: inherits (evidence: `malada/providers/dft.py`)
- DFT convergence → Convergence guesses: uses (evidence: `malada/providers/dftconvergence.py`)
- DFT convergence → Unit converters: uses (evidence: `malada/providers/dftconvergence.py`)
- DFT convergence → VASP utilities: uses (evidence: `malada/providers/dftconvergence.py`)
- DFT calculations → VASP utilities: uses (evidence: `malada/providers/dft.py`)
- DFT calculations → Runner interface: dispatches through (evidence: `malada/providers/dft.py`)
- DFT convergence → Runner interface: runs folders through
- Runner interface → Bash runner: selects runner (evidence: `malada/runners/runner_interface.py`)
- Runner interface → SLURM creator: selects runner (evidence: `malada/runners/runner_interface.py`)
- Bash runner → Runner base: inherits (evidence: `malada/runners/bashrunner.py`)
- SLURM creator → Runner base: inherits (evidence: `malada/runners/slurm_creator.py`)
- SLURM creator → SLURM parameters: reads settings (evidence: `malada/runners/slurm_creator.py`)
- Bash runner → QE or VASP: executes (evidence: `malada/runners/bashrunner.py`)
- SLURM creator → QE or VASP: writes job commands (evidence: `malada/runners/slurm_creator.py`)
- Data pipeline → Generated data: produces (evidence: `malada/pipeline/pipeline.py`)
