# ordern/conquest-release architecture

> Architecture diagram of the GitHub repository ordern/conquest-release, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ordern/conquest-release
- Repository: https://github.com/ordern/conquest-release

## Overview

##### Project type and purpose
- CONQUEST is a high-performance, large-scale DFT (density functional theory) simulation code written in Fortran.
- It is a computational engine (no GUI or web frontend), designed to read atomic configurations & pseudopotentials, perform SCF, diagonalisation, MD, structural relaxations, etc., and output energies, forces, densities.
- It integrates with external libraries (MPI, ScaLAPACK, FFT libraries, LibXC) and tools (ONCVPSP pseudopotential generator, ASE).

##### File structure
Top-level components:
- src/: the core Fortran modules and main.f90 (the simulation engine).
- pseudo-and-pao/: repository of pseudopotentials and PAO definitions (data store).
- tools/: standalone Fortran utilities (BasisGeneration, PostProcessing).
- testsuite/: regression tests driving input files → CONQUEST binary → compare outputs.
- benchmarks/: sample inputs & outputs for performance testing.
- docs/: user manual and API docs (RST sources).
- .github/, CI workflows: build & test automation.
- Makefiles in src/ and system/: cluster-specific build configurations.

##### README for additional insights
- Describes capabilities (static, MD, ensembles, linear-scaling).
- External integrations: LibXC, ONCVPSP, ASE.
- Scalability targets (up to millions of atoms, hundreds of thousands of cores).

##### Elements
- Clear labels: “Build System,” “Core Engine,” “Pseudopotential DB,” “MPI/ScaLAPACK,” “CLI/ASE,” “Tests & Benchmarks,” “Utilities,” “Docs”
- Rectangles for code components (src/, tools/)
- Clouds for external dependencies (MPI, LibXC, FFT libs)
- Parallelograms for I/O (Conquest_input, output files)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        CLI["CLI (conquest)"]:::process
        ASE["Python ASE Wrapper"]:::process
    end

    %% Build System
    subgraph "Build System"
        Makefile["Makefile"]:::code
        SysConfig["Cluster Configs"]:::code
    end

    %% Continuous Integration
    CI["CI/CD Pipeline"]:::process

    %% Core Engine
    subgraph "Core Engine"
        SCF["SCF Module"]:::code
        Diag["Diagonalisation Module"]:::code
        MD["MD Integrator"]:::code
        IO["I/O Layer"]:::code
        Comms["Parallel Comms (MPI)"]:::code
        Scalapack["ScaLAPACK Interface"]:::code
        FFT["FFT Support"]:::code
        LibXC["LibXC Modules"]:::code
    end

    %% Data Repository
    PseudoDB["Pseudopotential & PAO DB"]:::data

    %% External Libraries
    subgraph "External Libraries"
        MPI["MPI"]:::external
        ScaLAPACK["ScaLAPACK"]:::external
        FFTLibs["FFT Libraries"]:::external
        LibXCExt["LibXC"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        BasisGen["Basis Generation Tool"]:::code
        PostProc["Post-Processing Tool"]:::code
        PyUtils["Python Analysis Scripts"]:::code
    end

    %% Testing & Benchmarking
    subgraph "Tests & Benchmarks"
        Tests["Regression Tests"]:::data
        Bench["Benchmark Sets"]:::data
    end

    %% Documentation
    subgraph "Documentation"
        DocsSrc["Docs Source"]:::data
        ASEDocs["ASE Wrapper Docs"]:::data
        DocsMake["Docs Makefile"]:::code
        README["README.md"]:::data
        Contrib["CONTRIBUTING.md"]:::data
    end

    %% Connections
    CI --> Makefile
    CI --> Tests

    Makefile -->|compiles| CoreEngine["Binary"]:::process
    SysConfig --> CoreEngine

    CLI -->|runs| CoreEngine
    ASE -->|wraps| CoreEngine

    CoreEngine -->|reads| PseudoDB
    CoreEngine -->|calls| MPI
    CoreEngine -->|calls| ScaLAPACKExt
    CoreEngine -->|calls| FFTLibs
    CoreEngine -->|calls| LibXCExt

    CoreEngine -->|outputs| Tests
    CoreEngine -->|outputs| Bench
    CoreEngine -->|produces| OutputFiles["Output Files"]:::process

    OutputFiles -->|analyzed by| BasisGen
    OutputFiles -->|analyzed by| PostProc
    OutputFiles -->|analyzed by| PyUtils

    DocsSrc -->|builds with| DocsMake
    DocsSrc --> README
    DocsSrc --> Contrib
    DocsSrc --> ASEDocs

    %% Click Events
    click CLI "https://github.com/ordern/conquest-release/blob/master/src/main.f90"
    click Makefile "https://github.com/ordern/conquest-release/tree/master/src/Makefile"
    click SysConfig "https://github.com/ordern/conquest-release/blob/master/src/system/system.example.make"
    click CI "https://github.com/ordern/conquest-release/blob/master/.github/workflows/makefile.yml"
    click SCF "https://github.com/ordern/conquest-release/blob/master/src/SelfCon_module.f90"
    click Diag "https://github.com/ordern/conquest-release/blob/master/src/DiagModule.f90"
    click MD "https://github.com/ordern/conquest-release/blob/master/src/Integrators_module.f90"
    click IO "https://github.com/ordern/conquest-release/blob/master/src/io_module.f90"
    click Comms "https://github.com/ordern/conquest-release/blob/master/src/mpi.f90"
    click Scalapack "https://github.com/ordern/conquest-release/blob/master/src/ScalapackFormat.f90"
    click FFT "https://github.com/ordern/conquest-release/blob/master/src/fft_module.f90"
    click LibXC "https://github.com/ordern/conquest-release/blob/master/src/XC_LibXC_v4_module.f90"
    click PseudoDB "https://github.com/ordern/conquest-release/tree/master/pseudo-and-pao/"
    click BasisGen "https://github.com/ordern/conquest-release/tree/master/tools/BasisGeneration/"
    click PostProc "https://github.com/ordern/conquest-release/tree/master/tools/PostProcessing/"
    click PyUtils "https://github.com/ordern/conquest-release/blob/master/src/utilities/frame.py"
    click Tests "https://github.com/ordern/conquest-release/tree/master/testsuite/"
    click Bench "https://github.com/ordern/conquest-release/tree/master/benchmarks/"
    click DocsSrc "https://github.com/ordern/conquest-release/tree/master/docs/"
    click ASEDocs "https://github.com/ordern/conquest-release/blob/master/docs/ase-conquest.rst"
    click DocsMake "https://github.com/ordern/conquest-release/tree/master/docs/Makefile"
    click README "https://github.com/ordern/conquest-release/blob/master/README.md"
    click Contrib "https://github.com/ordern/conquest-release/blob/master/CONTRIBUTING.md"

    %% Styles
    classDef code fill:#e2e8f0,stroke:#1e3a8a,color:#1e3a8a;
    classDef data fill:#f0fdf4,stroke:#065f46,color:#065f46;
    classDef external fill:#f0f9ff,stroke:#1e40af,color:#1e40af,stroke-dasharray: 5 5;
    classDef process fill:#fff7ed,stroke:#c2410c,color:#c2410c;
```
