# hherpa/hea_l12 architecture

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

- Interactive diagram: https://gitdiagram.com/hherpa/hea_l12
- Repository: https://github.com/hherpa/hea_l12

## Overview

#### Purpose and scope
This is a notebook- and file-driven computational-materials workflow for the L1₂ strengthening phase of the Al–Co–Cr–Fe–Ni–Ti high-entropy alloy. It progresses from disordered crystal-structure generation through first-principles calculations to MEAM-based molecular dynamics. It is not an application service; execution entry points are Jupyter notebooks and simulator input/run files.

#### Structure generation
SQS generation produces L1₂ CIF structures at 32, 64, and 128 atoms, providing the principal structural inputs for downstream simulation:
- `CIF/SQS generator/HEA_L12_SQS_32atoms.ipynb`
- `CIF/SQS generator/HEA_L12_SQS_128atoms.cif`
- `CIF/SQS generator/README.md`

The key boundary is exported CIF: it captures lattice, atomic positions, species, and sublattice disorder independently of the generating notebook. An archived alternative uses pymatgen random structures: `CIF/archive_random_pymatgen_structure/HEA_L12_random_pymatgen_structure.ipynb`.

#### DFT workflow
The primary DFT entry point is `DFT/HEA_L12_QE_32atoms.ipynb`, which represents a 32-atom Quantum ESPRESSO calculation path. QE consumes structure-derived inputs and local pseudopotentials from:
- `DFT/pseudo/`
- `DFT/pseudo/Al.pbesol-n-kjpaw_psl.1.0.0.UPF`
- `DFT/pseudo/Ni.upf`

GPU-oriented GPAW, PySCF, and QE notebooks are explicitly archived, so they are alternative/prototype backends rather than the primary path: `DFT/archive_DFT_GPU/`.

#### Reference-system DFT and analysis
Ni, Al, and Ni₃Al are maintained as interpretable reference calculations for validating formation/electronic-property workflows. QE inputs, results, and analysis are colocated:
- `DFT/example_Ni3Al/QE_run_01/QE_run.ipynb`
- `DFT/example_Ni3Al/QE_run_01/Ni3Al/Ni3Al.pw.in`
- `DFT/example_Ni3Al/QE_run_01/Ni3Al_QE_analysis.ipynb`

QE output boundaries include optimized structures (`*_opt.cif`), XML, charge/Hartree fields, and projected DOS, enabling postprocessing without rerunning the solver.

#### VASP calculation corpus
A separate VASP-based reference corpus organizes multiple runs by material and calculation stage. Each case has standard VASP inputs, a shell execution entry point, and persisted outputs:
- `DFT/example_Ni3Al/run_01/Ni3Al/run.sh`
- `DFT/example_Ni3Al/run_02/Ni3Al/INCAR`
- `DFT/example_Ni3Al/run_06/run_06_VASP_analysis.ipynb`

This is parallel to, not automatically integrated with, the QE workflow. `CONTCAR`, `DOSCAR`, `OUTCAR`, `vasprun.xml`, and—where present—charge/local-potential files form the interface to analysis.

#### Molecular dynamics
LAMMPS performs thermal treatment and uniaxial tensile simulation using a multicomponent MEAM potential. The executable input is:
- `LAMMPS/run.hea`
- `LAMMPS/FeMnNiTiCuCrCoAl.meam`
- `LAMMPS/library.meam`

Its flow is anneal/cool/load simulation → trajectory/log and tabular measurements → notebook postprocessing. Existing outputs, including per-stage CSV files and stress–strain data, are retained in `LAMMPS/logs/`.

#### Runtime and integration boundaries
Required material-science runtimes are Python/Jupyter, `sqsgenerator`, pymatgen, Quantum ESPRESSO, and LAMMPS; GPAW/PySCF and VASP appear as supported experimental/reference backends. Compute infrastructure is external to the repository: notebooks are suitable for local/Colab execution, while `run.sh` files imply shell/HPC-style VASP execution. Data handoffs are file based—CIF/POSCAR structures, DFT solver inputs/outputs, and LAMMPS potential/trajectory/CSV artifacts—with no orchestrator that automates the full pipeline.

Main entry points: [`DFT/HEA_L12_QE_32atoms.ipynb`](https://github.com/hherpa/hea_l12/blob/main/DFT/HEA_L12_QE_32atoms.ipynb) (HEA QE calculation), [`CIF/SQS generator/HEA_L12_SQS_128atoms.cif`](https://github.com/hherpa/hea_l12/blob/main/CIF/SQS%20generator/HEA_L12_SQS_128atoms.cif) (L1₂ SQS CIFs), [`DFT/example_Ni3Al/QE_run_01/QE_run.ipynb`](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/QE_run.ipynb) (Ni₃Al QE reference), [`DFT/example_Ni3Al/run_01/Ni3Al/run.sh`](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_01/Ni3Al/run.sh) (VASP shell run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_structure["Structure generation"]
  node_sqs_notebook["SQS generator<br/>Jupyter notebook"]
  node_cif_exports["L1₂ SQS CIFs<br/>structure artifacts"]
  node_random_structure_archive["pymatgen prototype<br/>archived notebook"]
end

subgraph group_dft["First-principles workflows"]
  node_hea_qe_notebook["HEA QE calculation<br/>QE notebook"]
  node_pseudopotentials["QE pseudopotentials<br/>solver inputs"]
  node_qe_outputs[("QE result artifacts<br/>solver outputs")]
  node_ni3al_qe_run["Ni₃Al QE reference<br/>QE notebook<br/>[QE_run.ipynb]"]
  node_ni3al_qe_input["Ni₃Al QE input<br/>pw.x input<br/>[Ni3Al.pw.in]"]
  node_ni3al_qe_analysis["Ni₃Al QE analysis<br/>Jupyter notebook"]
  node_gpu_dft_archive["GPU DFT prototypes<br/>archived backends"]
end

subgraph group_vasp["VASP reference corpus"]
  node_vasp_run_script["VASP shell run<br/>execution script<br/>[run.sh]"]
  node_vasp_inputs["VASP case inputs<br/>VASP inputs"]
  node_vasp_outputs[("VASP result artifacts<br/>solver outputs")]
  node_vasp_analysis["VASP analysis<br/>Jupyter notebook"]
end

subgraph group_md["Molecular dynamics"]
  node_lammps_input["Thermal and tensile run<br/>LAMMPS input<br/>[run.hea]"]
  node_meam_potentials["MEAM potential set<br/>potential files"]
  node_lammps_outputs[("MD logs and measurements<br/>trajectory and CSV artifacts")]
  node_md_postprocessing["MD postprocessing<br/>notebook analysis"]
end

node_sqs_notebook -->|"exports"| node_cif_exports
node_random_structure_archive -.->|"alternative export"| node_cif_exports
node_cif_exports -->|"structure input"| node_hea_qe_notebook
node_pseudopotentials -->|"solver input"| node_hea_qe_notebook
node_hea_qe_notebook -->|"runs QE"| node_qe_outputs
node_ni3al_qe_input -->|"calculation input"| node_ni3al_qe_run
node_ni3al_qe_run -->|"produces reference results"| node_qe_outputs
node_qe_outputs -->|"postprocesses"| node_ni3al_qe_analysis
node_gpu_dft_archive -.->|"alternative backend"| node_hea_qe_notebook
node_vasp_inputs -->|"run inputs"| node_vasp_run_script
node_vasp_run_script -->|"executes VASP"| node_vasp_outputs
node_vasp_outputs -->|"postprocesses"| node_vasp_analysis
node_meam_potentials -->|"potential input"| node_lammps_input
node_lammps_input -->|"anneal, cool, load"| node_lammps_outputs
node_lammps_outputs -->|"trajectory and CSV"| node_md_postprocessing

click node_sqs_notebook "https://github.com/hherpa/hea_l12/blob/main/CIF/SQS%20generator/HEA_L12_SQS_32atoms.ipynb"
click node_cif_exports "https://github.com/hherpa/hea_l12/blob/main/CIF/SQS%20generator/HEA_L12_SQS_128atoms.cif"
click node_random_structure_archive "https://github.com/hherpa/hea_l12/blob/main/CIF/archive_random_pymatgen_structure/HEA_L12_random_pymatgen_structure.ipynb"
click node_hea_qe_notebook "https://github.com/hherpa/hea_l12/blob/main/DFT/HEA_L12_QE_32atoms.ipynb"
click node_ni3al_qe_run "https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/QE_run.ipynb"
click node_ni3al_qe_input "https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/Ni3Al/Ni3Al.pw.in"
click node_ni3al_qe_analysis "https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/Ni3Al_QE_analysis.ipynb"
click node_vasp_run_script "https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_01/Ni3Al/run.sh"
click node_vasp_inputs "https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_02/Ni3Al/INCAR"
click node_vasp_analysis "https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_06/run_06_VASP_analysis.ipynb"
click node_lammps_input "https://github.com/hherpa/hea_l12/blob/main/LAMMPS/run.hea"
click node_meam_potentials "https://github.com/hherpa/hea_l12/blob/main/LAMMPS/FeMnNiTiCuCrCoAl.meam"

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_sqs_notebook,node_cif_exports,node_random_structure_archive toneBlue
class node_hea_qe_notebook,node_pseudopotentials,node_qe_outputs,node_ni3al_qe_run,node_ni3al_qe_input,node_ni3al_qe_analysis,node_gpu_dft_archive toneAmber
class node_vasp_run_script,node_vasp_inputs,node_vasp_outputs,node_vasp_analysis toneMint
class node_lammps_input,node_meam_potentials,node_lammps_outputs,node_md_postprocessing toneRose
```

## Components

### Structure generation

- [SQS generator](https://github.com/hherpa/hea_l12/blob/main/CIF/SQS%20generator/HEA_L12_SQS_32atoms.ipynb): Jupyter notebook · Generates disordered L1₂ structures. · `CIF/SQS generator/HEA_L12_SQS_32atoms.ipynb`
- [L1₂ SQS CIFs](https://github.com/hherpa/hea_l12/blob/main/CIF/SQS%20generator/HEA_L12_SQS_128atoms.cif): structure artifacts · 32-, 64-, and 128-atom structural handoff boundary. · `CIF/SQS generator/HEA_L12_SQS_128atoms.cif`
- [pymatgen prototype](https://github.com/hherpa/hea_l12/blob/main/CIF/archive_random_pymatgen_structure/HEA_L12_random_pymatgen_structure.ipynb): archived notebook · Alternative random-structure generator. · `CIF/archive_random_pymatgen_structure/HEA_L12_random_pymatgen_structure.ipynb`

### First-principles workflows

- [HEA QE calculation](https://github.com/hherpa/hea_l12/blob/main/DFT/HEA_L12_QE_32atoms.ipynb): QE notebook · Primary 32-atom first-principles path. · `DFT/HEA_L12_QE_32atoms.ipynb`
- **QE pseudopotentials**: solver inputs
- **QE result artifacts**: solver outputs · Optimized CIF, XML, fields, and projected DOS support postprocessing.
- [Ni₃Al QE reference](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/QE_run.ipynb): QE notebook · Interpretable reference calculation. · `DFT/example_Ni3Al/QE_run_01/QE_run.ipynb`
- [Ni₃Al QE input](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/Ni3Al/Ni3Al.pw.in): pw.x input · `DFT/example_Ni3Al/QE_run_01/Ni3Al/Ni3Al.pw.in`
- [Ni₃Al QE analysis](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/QE_run_01/Ni3Al_QE_analysis.ipynb): Jupyter notebook · `DFT/example_Ni3Al/QE_run_01/Ni3Al_QE_analysis.ipynb`
- **GPU DFT prototypes**: archived backends · GPAW, PySCF, and alternative QE experiments.

### VASP reference corpus

- [VASP shell run](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_01/Ni3Al/run.sh): execution script · Shell/HPC-style VASP entry point. · `DFT/example_Ni3Al/run_01/Ni3Al/run.sh`
- [VASP case inputs](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_02/Ni3Al/INCAR): VASP inputs · Material and calculation-stage specific inputs. · `DFT/example_Ni3Al/run_02/Ni3Al/INCAR`
- **VASP result artifacts**: solver outputs · CONTCAR, DOSCAR, OUTCAR, vasprun.xml, and field files.
- [VASP analysis](https://github.com/hherpa/hea_l12/blob/main/DFT/example_Ni3Al/run_06/run_06_VASP_analysis.ipynb): Jupyter notebook · `DFT/example_Ni3Al/run_06/run_06_VASP_analysis.ipynb`

### Molecular dynamics

- [Thermal and tensile run](https://github.com/hherpa/hea_l12/blob/main/LAMMPS/run.hea): LAMMPS input · Defines anneal, cooling, and uniaxial loading. · `LAMMPS/run.hea`
- [MEAM potential set](https://github.com/hherpa/hea_l12/blob/main/LAMMPS/FeMnNiTiCuCrCoAl.meam): potential files · Multicomponent alloy interaction model. · `LAMMPS/FeMnNiTiCuCrCoAl.meam`
- **MD logs and measurements**: trajectory and CSV artifacts · Per-stage measurements and stress–strain data.
- **MD postprocessing**: notebook analysis

## Connections

- SQS generator → L1₂ SQS CIFs: exports
- pymatgen prototype → L1₂ SQS CIFs: alternative export
- L1₂ SQS CIFs → HEA QE calculation: structure input
- QE pseudopotentials → HEA QE calculation: solver input
- HEA QE calculation → QE result artifacts: runs QE
- Ni₃Al QE input → Ni₃Al QE reference: calculation input
- Ni₃Al QE reference → QE result artifacts: produces reference results
- QE result artifacts → Ni₃Al QE analysis: postprocesses
- GPU DFT prototypes → HEA QE calculation: alternative backend
- VASP case inputs → VASP shell run: run inputs
- VASP shell run → VASP result artifacts: executes VASP
- VASP result artifacts → VASP analysis: postprocesses
- MEAM potential set → Thermal and tensile run: potential input
- Thermal and tensile run → MD logs and measurements: anneal, cool, load
- MD logs and measurements → MD postprocessing: trajectory and CSV