# dogusariturk/materialsframework architecture

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

- Interactive diagram: https://gitdiagram.com/dogusariturk/materialsframework
- Repository: https://github.com/dogusariturk/materialsframework

## Overview

#### Purpose and public entry points
MaterialsFramework is a Python 3.12 materials-simulation library that normalizes access to 20+ ML interatomic potentials plus VASP. Its public package entry points are the domain subpackages: calculators, analysis, transformations, tools, and I/O under `src/materialsframework/__init__.py`, `src/materialsframework/calculators/__init__.py`, and `src/materialsframework/analysis/__init__.py`.

#### Calculator abstraction and backend adapters
The primary execution boundary is the shared calculator API: backend-specific adapters accept ASE structures and generally pymatgen structures/molecules, then expose consistent single-point calculation and relaxation behavior. Adapter implementations isolate optional MLIP dependencies and backend conventions in files such as `src/materialsframework/calculators/chgnet.py`, `src/materialsframework/calculators/mace.py`, and `src/materialsframework/calculators/vasp.py`. VASP is the external licensed backend; MLIP adapters depend on separately installed optional packages.

#### Dynamics and execution observation
MD-capable calculators extend the calculation layer with NVE and NVT/NPT execution. The MD orchestration and calculator-facing utility boundary live in `src/materialsframework/tools/md.py` and `src/materialsframework/tools/calculator.py`; trajectory capture is represented by `src/materialsframework/tools/trajectory.py`. This stage takes an initial structure plus ensemble/runtime settings and returns final structures and sampled calculation data.

#### Lazy registries and plugin selection
Registries allow lookup by name without importing every heavyweight backend, making them the main dependency-loading control point. The central and domain registries are `src/materialsframework/_registry.py`, `src/materialsframework/calculators/registry.py`, and `src/materialsframework/analysis/registry.py`. Equivalent registries exist for transformations and tools, supporting runtime substitution of calculators and workflows.

#### Transformation → calculation → analysis workflows
Property workflows are deliberately split into paired transformations and analyzers. A transformation generates strained, displaced, slab, defect, path, or other derived structures; the analyzer invokes a supplied calculator over those structures and reduces results into a physical property. This separation is represented by `src/materialsframework/transformations/elastic_constants.py`, `src/materialsframework/analysis/elastic_constants.py`, and `src/materialsframework/analysis/base.py`. Parallel pairs cover EOS, phonons, NEB, formation energy, surface energies, stacking faults, and related analyses.

#### Standalone materials tools
Tools implement higher-level generation, modeling, and postprocessing outside the analyzer pipeline: SQS generation, cluster expansion, Cahn–Hilliard phase fields, stability maps, and CALPHAD-oriented conversion. Architecturally central implementations include `src/materialsframework/tools/sqsgen.py`, `src/materialsframework/tools/cluster_expansion.py`, and `src/materialsframework/tools/cahn_hilliard.py`. These may produce structures or scientific datasets consumed by calculators or external workflows.

#### Data formats, dependencies, and delivery
ASE is the core atomistic execution representation, while pymatgen inputs are supported at the public boundary; parsing support is under `src/materialsframework/io/file_parser.py`. Python package metadata and optional MLIP extras are defined in `pyproject.toml`; the resolved environment is `uv.lock`. Documentation is built with MkDocs (`mkdocs.yml`) and published through GitHub Pages (`.github/workflows/gh-pages.yml`); CI tests, linting, and releases run in GitHub Actions.

Main entry points: [`src/materialsframework/calculators/__init__.py`](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/__init__.py) (Calculator API), [`src/materialsframework/__init__.py`](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/__init__.py) (MaterialsFramework package), [`src/materialsframework/calculators/registry.py`](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/registry.py) (Calculator registry), [`src/materialsframework/analysis/registry.py`](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/registry.py) (Analysis registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_package["MaterialsFramework package<br/>Python package<br/>[__init__.py]"]
  node_io_parser["File parser<br/>I/O boundary<br/>[file_parser.py]"]
end

subgraph group_execution["Calculation &amp; dynamics"]
  node_calculator_api["Calculator API<br/>calculation abstraction<br/>[__init__.py]"]
  node_calculator_registry{{"Calculator registry<br/>lazy registry<br/>[registry.py]"}}
  node_registry_core{{"Registry core<br/>plugin infrastructure<br/>[_registry.py]"}}
  node_mlip_adapters["MLIP adapters<br/>backend adapters<br/>[chgnet.py]"]
  node_vasp_adapter["VASP adapter<br/>external backend adapter<br/>[vasp.py]"]
  node_md_orchestration["MD orchestration<br/>dynamics workflow<br/>[md.py]"]
  node_trajectory["Trajectory capture<br/>simulation data<br/>[trajectory.py]"]
end

subgraph group_workflows["Property workflows"]
  node_transformations["Structure transformations<br/>workflow inputs"]
  node_analysis_base["Analyzer base<br/>analysis abstraction<br/>[base.py]"]
  node_elastic_analysis["Property analyzers<br/>physical-property workflows"]
  node_analysis_registry{{"Analysis registry<br/>lazy registry<br/>[registry.py]"}}
end

subgraph group_tools["Scientific tools"]
  node_scientific_tools["Materials modeling tools<br/>scientific workflows<br/>[sqsgen.py]"]
end

subgraph group_delivery["Packaging &amp; delivery"]
  node_packaging["Package extras<br/>Python packaging<br/>[pyproject.toml]"]
  node_docs_delivery["Documentation publishing<br/>MkDocs and GitHub Pages<br/>[mkdocs.yml]"]
  node_gh_pages["GitHub Pages workflow<br/>deployment automation<br/>[gh-pages.yml]"]
end

node_atomistic_inputs[("ASE &amp; pymatgen structures<br/>external data model")]
node_optional_backends["Optional MLIP packages<br/>external dependencies"]
node_vasp["VASP<br/>licensed external engine"]

node_package -->|"exports"| node_calculator_api
node_package -->|"exports"| node_analysis_registry
node_package -->|"exports"| node_io_parser
node_atomistic_inputs -->|"structures"| node_calculator_api
node_io_parser -->|"parses"| node_atomistic_inputs
node_calculator_registry -->|"uses"| node_registry_core
node_analysis_registry -->|"uses"| node_registry_core
node_calculator_registry -.->|"lazily loads"| node_mlip_adapters
node_calculator_registry -.->|"selects"| node_vasp_adapter
node_mlip_adapters -.->|"depends on"| node_optional_backends
node_vasp_adapter -->|"executes"| node_vasp
node_md_orchestration -->|"drives"| node_calculator_api
node_md_orchestration -->|"records"| node_trajectory
node_transformations -->|"derived structures"| node_analysis_base
node_analysis_base -->|"invokes"| node_calculator_api
node_elastic_analysis -->|"implements"| node_analysis_base
node_analysis_registry -.->|"selects"| node_elastic_analysis
node_scientific_tools -->|"produces or consumes"| node_atomistic_inputs
node_scientific_tools -.->|"can consume"| node_calculator_api
node_packaging -->|"declares extras"| node_optional_backends
node_docs_delivery -->|"published by"| node_gh_pages

click node_package "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/__init__.py"
click node_calculator_api "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/__init__.py"
click node_calculator_registry "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/registry.py"
click node_registry_core "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/_registry.py"
click node_mlip_adapters "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/chgnet.py"
click node_vasp_adapter "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/vasp.py"
click node_md_orchestration "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/tools/md.py"
click node_trajectory "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/tools/trajectory.py"
click node_transformations "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/transformations/elastic_constants.py"
click node_analysis_base "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/base.py"
click node_elastic_analysis "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/elastic_constants.py"
click node_analysis_registry "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/registry.py"
click node_scientific_tools "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/tools/sqsgen.py"
click node_io_parser "https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/io/file_parser.py"
click node_packaging "https://github.com/dogusariturk/materialsframework/blob/main/pyproject.toml"
click node_docs_delivery "https://github.com/dogusariturk/materialsframework/blob/main/mkdocs.yml"
click node_gh_pages "https://github.com/dogusariturk/materialsframework/blob/main/.github/workflows/gh-pages.yml"

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_package,node_io_parser toneBlue
class node_calculator_api,node_calculator_registry,node_registry_core,node_mlip_adapters,node_vasp_adapter,node_md_orchestration,node_trajectory toneAmber
class node_transformations,node_analysis_base,node_elastic_analysis,node_analysis_registry toneMint
class node_scientific_tools toneRose
class node_packaging,node_docs_delivery,node_gh_pages toneIndigo
class node_atomistic_inputs,node_optional_backends,node_vasp toneNeutral
```

## Components

### Public API

- [MaterialsFramework package](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/__init__.py): Python package · Domain subpackages expose the public library API. · `src/materialsframework/__init__.py`
- [File parser](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/io/file_parser.py): I/O boundary · Parses supported materials input formats. · `src/materialsframework/io/file_parser.py`

### Calculation & dynamics

- [Calculator API](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/__init__.py): calculation abstraction · Normalizes single-point and relaxation operations across backends. · `src/materialsframework/calculators/__init__.py`
- [Calculator registry](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/registry.py): lazy registry · Selects named backends without eagerly importing optional dependencies. · `src/materialsframework/calculators/registry.py`
- [Registry core](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/_registry.py): plugin infrastructure · `src/materialsframework/_registry.py`
- [MLIP adapters](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/chgnet.py): backend adapters · CHGNet, MACE, and related optional-potential integrations. · `src/materialsframework/calculators/chgnet.py`
- [VASP adapter](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/calculators/vasp.py): external backend adapter · Integrates the licensed VASP execution backend. · `src/materialsframework/calculators/vasp.py`
- [MD orchestration](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/tools/md.py): dynamics workflow · Runs NVE and NVT/NPT dynamics from structures and runtime settings. · `src/materialsframework/tools/md.py`
- [Trajectory capture](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/tools/trajectory.py): simulation data · Collects sampled calculation data and final structures. · `src/materialsframework/tools/trajectory.py`

### Property workflows

- [Structure transformations](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/transformations/elastic_constants.py): workflow inputs · Generates derived strained, displaced, slab, defect, and path structures. · `src/materialsframework/transformations/elastic_constants.py`
- [Analyzer base](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/base.py): analysis abstraction · Runs supplied calculators over derived structures and reduces results. · `src/materialsframework/analysis/base.py`
- [Property analyzers](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/elastic_constants.py): physical-property workflows · Elastic constants and parallel EOS, phonon, NEB, and surface-property analyses. · `src/materialsframework/analysis/elastic_constants.py`
- [Analysis registry](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/analysis/registry.py): lazy registry · Provides runtime selection of analysis workflows. · `src/materialsframework/analysis/registry.py`

### Scientific tools

- [Materials modeling tools](https://github.com/dogusariturk/materialsframework/blob/main/src/materialsframework/tools/sqsgen.py): scientific workflows · SQS generation, cluster expansion, and Cahn–Hilliard modeling. · `src/materialsframework/tools/sqsgen.py`

### Packaging & delivery

- [Package extras](https://github.com/dogusariturk/materialsframework/blob/main/pyproject.toml): Python packaging · Defines Python metadata and optional MLIP dependency extras. · `pyproject.toml`
- [Documentation publishing](https://github.com/dogusariturk/materialsframework/blob/main/mkdocs.yml): MkDocs and GitHub Pages · `mkdocs.yml`
- [GitHub Pages workflow](https://github.com/dogusariturk/materialsframework/blob/main/.github/workflows/gh-pages.yml): deployment automation · `.github/workflows/gh-pages.yml`

### Other components

- **ASE & pymatgen structures**: external data model · ASE is the execution representation; pymatgen is accepted at the public boundary.
- **Optional MLIP packages**: external dependencies
- **VASP**: licensed external engine

## Connections

- MaterialsFramework package → Calculator API: exports
- MaterialsFramework package → Analysis registry: exports
- MaterialsFramework package → File parser: exports
- ASE & pymatgen structures → Calculator API: structures
- File parser → ASE & pymatgen structures: parses
- Calculator registry → Registry core: uses
- Analysis registry → Registry core: uses
- Calculator registry → MLIP adapters: lazily loads
- Calculator registry → VASP adapter: selects
- MLIP adapters → Optional MLIP packages: depends on
- VASP adapter → VASP: executes
- MD orchestration → Calculator API: drives
- MD orchestration → Trajectory capture: records
- Structure transformations → Analyzer base: derived structures
- Analyzer base → Calculator API: invokes
- Property analyzers → Analyzer base: implements
- Analysis registry → Property analyzers: selects
- Materials modeling tools → ASE & pymatgen structures: produces or consumes
- Materials modeling tools → Calculator API: can consume
- Package extras → Optional MLIP packages: declares extras
- Documentation publishing → GitHub Pages workflow: published by
