# mala-project/mala architecture

> Architecture diagram of the GitHub repository mala-project/mala, 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/mala
- Repository: https://github.com/mala-project/mala

## Overview

MALA builds machine-learning surrogates for density-functional-theory data. Users configure descriptor and target calculations, prepare snapshots into scaled datasets, train or optimize a neural network, then predict physical quantities; predictions can also feed an ASE calculator. The graph preserves the documented preprocessing, modeling, and postprocessing capabilities. Some components are supported by the source index or README rather than excerpts, so their relationships are omitted or marked unverified where necessary.

Main entry points: [`mala/descriptors/descriptor.py`](https://github.com/mala-project/mala/blob/develop/mala/descriptors/descriptor.py) (Descriptor base), [`mala/network/runner.py`](https://github.com/mala-project/mala/blob/develop/mala/network/runner.py) (Runner), [`mala/datahandling/data_handler.py`](https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_handler.py) (Data handler), [`mala/targets/target.py`](https://github.com/mala-project/mala/blob/develop/mala/targets/target.py) (Target base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration &amp; runtime"]
  node_parameters["Parameters<br/>[parameters.py]"]
  node_parallel["Parallel runtime<br/>[parallelizer.py]"]
end

subgraph group_physics["Physical data"]
  node_physical_base["Physical data I/O<br/>[physical_data.py]"]
  node_descriptor["Descriptor base<br/>[descriptor.py]"]
  node_bispectrum["Bispectrum<br/>[bispectrum.py]"]
  node_atomic_density["Atomic density<br/>[atomic_density.py]"]
  node_ace["ACE descriptors<br/>[ace.py]"]
  node_ace_coupling["ACE coupling<br/>[coupling_utils.py]"]
  node_targets["Target base<br/>[target.py]"]
  node_ldos["LDOS targets<br/>[ldos.py]"]
  node_dos["DOS targets<br/>[dos.py]"]
  node_density["Density targets<br/>[density.py]"]
  node_calc_helpers["Calculation helpers"]
end

subgraph group_preparation["Data preparation"]
  node_data_handler["Data handler<br/>[data_handler.py]"]
  node_handler_base["Handler base"]
  node_scaler["Data scaler<br/>[data_scaler.py]"]
  node_tensor_data["Tensor datasets"]
  node_converter["Data converter<br/>[data_converter.py]"]
end

subgraph group_learning["Modeling"]
  node_network["Neural network<br/>[network.py]"]
  node_trainer["Trainer<br/>[trainer.py]"]
  node_runner["Runner<br/>[runner.py]"]
  node_predictor["Predictor<br/>[predictor.py]"]
  node_hyperopt["Hyperparameter optimization<br/>[hyper_opt.py]"]
  node_descriptor_scoring["Descriptor scoring"]
end

subgraph group_application["Applications"]
  node_trajectory["Trajectory analysis"]
  node_ofdft["OF-DFT initialization"]
  node_ase["ASE calculator<br/>[ase_calculator.py]"]
end

node_user(("User"))
node_dft(("DFT calculations"))

node_user -->|"configures"| node_parameters
node_handler_base -->|"reads settings"| node_parameters
node_data_handler -->|"extends"| node_handler_base
node_data_handler -->|"uses"| node_scaler
node_data_handler -->|"loads datasets"| node_tensor_data
node_handler_base -->|"creates calculator"| node_descriptor
node_handler_base -->|"creates calculator"| node_targets
node_descriptor -->|"reads settings"| node_parameters
node_descriptor -->|"dispatches descriptor"| node_bispectrum
node_descriptor -->|"dispatches descriptor"| node_atomic_density
node_descriptor -->|"dispatches descriptor"| node_ace
node_ace -->|"uses coupling"| node_ace_coupling
node_targets -->|"dispatches target"| node_ldos
node_targets -->|"dispatches target"| node_dos
node_targets -->|"dispatches target"| node_density
node_targets -->|"uses calculations"| node_calc_helpers
node_ldos -->|"uses target"| node_dos
node_ldos -->|"uses target"| node_density
node_density -->|"uses calculations"| node_calc_helpers
node_physical_base -->|"uses runtime"| node_parallel
node_user -.->|"prepares data"| node_data_handler
node_user -.->|"trains model"| node_trainer
node_trainer -->|"uses runner"| node_runner
node_runner -->|"runs network"| node_network
node_runner -->|"consumes data"| node_data_handler
node_runner -->|"scales data"| node_scaler
node_runner -->|"batches data"| node_tensor_data
node_predictor -.->|"uses runner"| node_runner
node_user -.->|"optimizes model"| node_hyperopt
node_descriptor_scoring -->|"converts data"| node_converter
node_descriptor_scoring -->|"uses optimizer"| node_hyperopt
node_trajectory -->|"uses descriptors"| node_descriptor
node_trajectory -->|"reads settings"| node_parameters
node_user -.->|"analyzes trajectories"| node_trajectory
node_user -.->|"initializes OF-DFT"| node_ofdft
node_ase -.->|"interfaces with"| node_dft
node_user -.->|"runs predictions"| node_ase
node_dft -.->|"provides reference data"| node_data_handler

click node_parameters "https://github.com/mala-project/mala/blob/develop/mala/common/parameters.py"
click node_parallel "https://github.com/mala-project/mala/blob/develop/mala/common/parallelizer.py"
click node_physical_base "https://github.com/mala-project/mala/blob/develop/mala/common/physical_data.py"
click node_descriptor "https://github.com/mala-project/mala/blob/develop/mala/descriptors/descriptor.py"
click node_bispectrum "https://github.com/mala-project/mala/blob/develop/mala/descriptors/bispectrum.py"
click node_atomic_density "https://github.com/mala-project/mala/blob/develop/mala/descriptors/atomic_density.py"
click node_ace "https://github.com/mala-project/mala/blob/develop/mala/descriptors/ace.py"
click node_ace_coupling "https://github.com/mala-project/mala/blob/develop/mala/descriptors/acelib/coupling_utils.py"
click node_targets "https://github.com/mala-project/mala/blob/develop/mala/targets/target.py"
click node_ldos "https://github.com/mala-project/mala/blob/develop/mala/targets/ldos.py"
click node_dos "https://github.com/mala-project/mala/blob/develop/mala/targets/dos.py"
click node_density "https://github.com/mala-project/mala/blob/develop/mala/targets/density.py"
click node_calc_helpers "https://github.com/mala-project/mala/blob/develop/mala/targets/calculation_helpers.py"
click node_data_handler "https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_handler.py"
click node_handler_base "https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_handler_base.py"
click node_scaler "https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_scaler.py"
click node_tensor_data "https://github.com/mala-project/mala/blob/develop/mala/datahandling/fast_tensor_dataset.py"
click node_converter "https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_converter.py"
click node_network "https://github.com/mala-project/mala/blob/develop/mala/network/network.py"
click node_trainer "https://github.com/mala-project/mala/blob/develop/mala/network/trainer.py"
click node_runner "https://github.com/mala-project/mala/blob/develop/mala/network/runner.py"
click node_predictor "https://github.com/mala-project/mala/blob/develop/mala/network/predictor.py"
click node_hyperopt "https://github.com/mala-project/mala/blob/develop/mala/network/hyper_opt.py"
click node_descriptor_scoring "https://github.com/mala-project/mala/blob/develop/mala/network/descriptor_scoring_optimizer.py"
click node_trajectory "https://github.com/mala-project/mala/blob/develop/mala/datageneration/trajectory_analyzer.py"
click node_ofdft "https://github.com/mala-project/mala/blob/develop/mala/datageneration/ofdft_initializer.py"
click node_ase "https://github.com/mala-project/mala/blob/develop/mala/interfaces/ase_calculator.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_parameters,node_parallel,node_user toneBlue
class node_physical_base,node_descriptor,node_bispectrum,node_atomic_density,node_ace,node_ace_coupling,node_targets,node_ldos,node_dos,node_density,node_calc_helpers toneAmber
class node_data_handler,node_handler_base,node_scaler,node_tensor_data,node_converter toneMint
class node_network,node_trainer,node_runner,node_predictor,node_hyperopt,node_descriptor_scoring toneRose
class node_trajectory,node_ofdft,node_ase,node_dft toneIndigo
```

## Components

### Configuration & runtime

- [Parameters](https://github.com/mala-project/mala/blob/develop/mala/common/parameters.py): `mala/common/parameters.py`
- [Parallel runtime](https://github.com/mala-project/mala/blob/develop/mala/common/parallelizer.py): `mala/common/parallelizer.py`

### Physical data

- [Physical data I/O](https://github.com/mala-project/mala/blob/develop/mala/common/physical_data.py): `mala/common/physical_data.py`
- [Descriptor base](https://github.com/mala-project/mala/blob/develop/mala/descriptors/descriptor.py): `mala/descriptors/descriptor.py`
- [Bispectrum](https://github.com/mala-project/mala/blob/develop/mala/descriptors/bispectrum.py): `mala/descriptors/bispectrum.py`
- [Atomic density](https://github.com/mala-project/mala/blob/develop/mala/descriptors/atomic_density.py): `mala/descriptors/atomic_density.py`
- [ACE descriptors](https://github.com/mala-project/mala/blob/develop/mala/descriptors/ace.py): `mala/descriptors/ace.py`
- [ACE coupling](https://github.com/mala-project/mala/blob/develop/mala/descriptors/acelib/coupling_utils.py): `mala/descriptors/acelib/coupling_utils.py`
- [Target base](https://github.com/mala-project/mala/blob/develop/mala/targets/target.py): `mala/targets/target.py`
- [LDOS targets](https://github.com/mala-project/mala/blob/develop/mala/targets/ldos.py): `mala/targets/ldos.py`
- [DOS targets](https://github.com/mala-project/mala/blob/develop/mala/targets/dos.py): `mala/targets/dos.py`
- [Density targets](https://github.com/mala-project/mala/blob/develop/mala/targets/density.py): `mala/targets/density.py`
- [Calculation helpers](https://github.com/mala-project/mala/blob/develop/mala/targets/calculation_helpers.py): `mala/targets/calculation_helpers.py`

### Data preparation

- [Data handler](https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_handler.py): `mala/datahandling/data_handler.py`
- [Handler base](https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_handler_base.py): `mala/datahandling/data_handler_base.py`
- [Data scaler](https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_scaler.py): `mala/datahandling/data_scaler.py`
- [Tensor datasets](https://github.com/mala-project/mala/blob/develop/mala/datahandling/fast_tensor_dataset.py): `mala/datahandling/fast_tensor_dataset.py`
- [Data converter](https://github.com/mala-project/mala/blob/develop/mala/datahandling/data_converter.py): `mala/datahandling/data_converter.py`

### Modeling

- [Neural network](https://github.com/mala-project/mala/blob/develop/mala/network/network.py): `mala/network/network.py`
- [Trainer](https://github.com/mala-project/mala/blob/develop/mala/network/trainer.py): `mala/network/trainer.py`
- [Runner](https://github.com/mala-project/mala/blob/develop/mala/network/runner.py): `mala/network/runner.py`
- [Predictor](https://github.com/mala-project/mala/blob/develop/mala/network/predictor.py): `mala/network/predictor.py`
- [Hyperparameter optimization](https://github.com/mala-project/mala/blob/develop/mala/network/hyper_opt.py): `mala/network/hyper_opt.py`
- [Descriptor scoring](https://github.com/mala-project/mala/blob/develop/mala/network/descriptor_scoring_optimizer.py): `mala/network/descriptor_scoring_optimizer.py`

### Applications

- [Trajectory analysis](https://github.com/mala-project/mala/blob/develop/mala/datageneration/trajectory_analyzer.py): `mala/datageneration/trajectory_analyzer.py`
- [OF-DFT initialization](https://github.com/mala-project/mala/blob/develop/mala/datageneration/ofdft_initializer.py): `mala/datageneration/ofdft_initializer.py`
- [ASE calculator](https://github.com/mala-project/mala/blob/develop/mala/interfaces/ase_calculator.py): `mala/interfaces/ase_calculator.py`

### Other components

- **User**
- **DFT calculations**

## Connections

- User → Parameters: configures (evidence: `README.md`)
- Handler base → Parameters: reads settings (evidence: `mala/datahandling/data_handler_base.py`)
- Data handler → Handler base: extends (evidence: `mala/datahandling/data_handler.py`)
- Data handler → Data scaler: uses (evidence: `mala/datahandling/data_handler.py`)
- Data handler → Tensor datasets: loads datasets (evidence: `mala/datahandling/data_handler.py`)
- Handler base → Descriptor base: creates calculator (evidence: `mala/datahandling/data_handler_base.py`)
- Handler base → Target base: creates calculator (evidence: `mala/datahandling/data_handler_base.py`)
- Descriptor base → Parameters: reads settings (evidence: `mala/descriptors/descriptor.py`)
- Descriptor base → Bispectrum: dispatches descriptor (evidence: `mala/descriptors/descriptor.py`)
- Descriptor base → Atomic density: dispatches descriptor (evidence: `mala/descriptors/descriptor.py`)
- Descriptor base → ACE descriptors: dispatches descriptor (evidence: `mala/descriptors/descriptor.py`)
- ACE descriptors → ACE coupling: uses coupling (evidence: `mala/descriptors/ace.py`)
- Target base → LDOS targets: dispatches target (evidence: `mala/targets/target.py`)
- Target base → DOS targets: dispatches target (evidence: `mala/targets/target.py`)
- Target base → Density targets: dispatches target (evidence: `mala/targets/target.py`)
- Target base → Calculation helpers: uses calculations (evidence: `mala/targets/target.py`)
- LDOS targets → DOS targets: uses target (evidence: `mala/targets/ldos.py`)
- LDOS targets → Density targets: uses target (evidence: `mala/targets/ldos.py`)
- Density targets → Calculation helpers: uses calculations (evidence: `mala/targets/density.py`)
- Physical data I/O → Parallel runtime: uses runtime (evidence: `mala/common/physical_data.py`)
- User → Data handler: prepares data (evidence: `README.md`)
- User → Trainer: trains model (evidence: `README.md`)
- Trainer → Runner: uses runner (evidence: `mala/network/trainer.py`)
- Runner → Neural network: runs network (evidence: `mala/network/runner.py`)
- Runner → Data handler: consumes data (evidence: `mala/network/runner.py`)
- Runner → Data scaler: scales data (evidence: `mala/network/runner.py`)
- Runner → Tensor datasets: batches data (evidence: `mala/network/runner.py`)
- Predictor → Runner: uses runner
- User → Hyperparameter optimization: optimizes model
- Descriptor scoring → Data converter: converts data (evidence: `mala/network/descriptor_scoring_optimizer.py`)
- Descriptor scoring → Hyperparameter optimization: uses optimizer (evidence: `mala/network/descriptor_scoring_optimizer.py`)
- Trajectory analysis → Descriptor base: uses descriptors (evidence: `mala/datageneration/trajectory_analyzer.py`)
- Trajectory analysis → Parameters: reads settings (evidence: `mala/datageneration/trajectory_analyzer.py`)
- User → Trajectory analysis: analyzes trajectories (evidence: `README.md`)
- User → OF-DFT initialization: initializes OF-DFT (evidence: `README.md`)
- ASE calculator → DFT calculations: interfaces with
- User → ASE calculator: runs predictions (evidence: `README.md`)
- DFT calculations → Data handler: provides reference data
