# molarverse/pq architecture

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

- Interactive diagram: https://gitdiagram.com/molarverse/pq
- Repository: https://github.com/molarverse/pq

## Overview

##### Main Components
- Application/Executable Layer: The “apps” directory (with PQ.cpp) and the build configuration indicate that the user interacts with the PQ executable. This is your entry point.
- Input Parser & Configuration: The directories “include/input” and “src/input” (with various submodules such as inputFileParser, parameterFileReader, restartFileReader, topologyFileReader, etc.) are responsible for parsing different input files and command line arguments.
- Simulation Engine: The “engine” subdirectory (“include/engine” and “src/engine”) consists of multiple simulation engines (e.g., MD, QMMD, QMMM, hybrid, ring polymer engines) that perform the core computation.
- Force Field & Potentials: The “forceField” and “potential” directories indicate classes and modules that compute forces acting on atoms, including Coulomb interactions, Lennard-Jones potentials, and other physics-based methods.
- System Components: Other fundamental modules include “simulationBox” (for atoms, molecules, cell lists), “thermostat”, and “constraints” (applying bond or distance constraints).
- Supporting Utilities: There are directories for linear algebra, integration, physical data, settings, and even exceptions – all of which support the main simulation workflow.
- Output System: Modules under “include/output” and “src/output” capture the simulation results (energy, trajectories, stresses) and prepare them for logging or further analysis.
- Testing & Examples: Integration tests, unit tests, and examples (in “tests”, “integration_tests”, “examples”) are also present and represent separate concerns for validation, but they are not part of the runtime production system.

##### Component Relationships & Data Flow
- The user starts by calling the PQ executable (in “apps/PQ.cpp”) with a specified input file.
- The Input Layer (using various input file parsers) processes the input file and extracts simulation preconfiguration.
- The Simulation Engine drives the simulation loop. This engine (or one of several engines such as mdEngine, qmmdEngine, etc.) is responsible for iterating over time steps and integrating the equations of motion.
- The Force Field and Potential modules are consulted to compute forces based on current atom positions.
- Throughout the simulation, the Output Module logs energy, stress, trajectories, and other data.
- Exception handling, configuration constants, and utility functions support this workflow, ensuring error handling and modularity.
- Optional external libraries (e.g., MPI for parallel runs, Kokkos for performance) integrate with certain modules, as indicated by numerous CMake configuration files and MPI/Kokkos-specific source files.

##### Architectural Patterns & Principles
- Modularity & Separation of Concerns: The code is clearly modularized by domain (input, output, simulation engine, force field, etc.), favoring reusability.
- Layered Approach: There is a clear separation between the input/parsing layer, the simulation computation layer, and the output/communication layer.
- Extensibility: With multiple “runner” classes (e.g., QM runners for different external packages such as dftbplus, pyscf, turbomole) and several input parsers, the design supports extension for additional simulation techniques.
- Dependency Injection/Configuration: Using CMake for configuration, as well as dedicated settings files under “include/settings” and “src/settings”, the project emphasizes configurable simulation parameters.
- Testing-Driven Development: The rich “tests” and “integration_tests” directories indicate that the design is validated via comprehensive testing.

##### Technology and Frameworks
- The project is written in C++ and leverages CMake as its build system, which is reflected by the top-level CMakeLists.txt and numerous cmake configuration modules.
- MPI, Kokkos, and pybind11 are integrated (as noted by corresponding cmake scripts and directories), suggesting parallel computation and Python interoperability.
- External libraries (googletest, progressbar, toml++) support testing, user interface, and configuration file parsing.

- A branch for “Output System” that receives simulation results from the engine.
- A separate section or note that testing (integration tests, unit tests, examples) validates the behavior of each layer, though testing may be drawn differently from production components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface/Executable Layer"
        PQ["PQ Executable (Apps)"]:::executable
    end

    subgraph "Input Parser & Configuration"
        I1["Include Input"]:::input
        I2["Src Input"]:::input
    end

    subgraph "Setup & Initialization"
        S1["Include Setup"]:::setup
        S2["Src Setup"]:::setup
    end

    subgraph "Simulation Engine"
        E1["Include Engine"]:::simulation
        E2["Src Engine"]:::simulation
        subgraph "Simulation Engines Types"
            ME["MD Engine"]:::simulation
            QE["QMMD Engine"]:::simulation
            RE["Ring Polymer Engine"]:::simulation
        end
    end

    subgraph "Force Field & Potentials"
        FF1["Include Force Field"]:::force
        FF2["Src Force Field"]:::force
        P1["Include Potential"]:::force
        P2["Src Potential"]:::force
    end

    subgraph "System Components"
        SB1["Simulation Box-Include"]:::system
        SB2["Simulation Box-Src"]:::system
        T1["Thermostat-Include"]:::system
        T2["Thermostat-Src"]:::system
        C1["Constraints-Include"]:::system
        C2["Constraints-Src"]:::system
    end

    subgraph "Supporting Utilities"
        U1["Utilities"]:::utilities
        Cfg["Config"]:::utilities
        LA["Linear Algebra"]:::utilities
        MPII["MPI Include"]:::utilities
        MPIS["MPI Src"]:::utilities
    end

    subgraph "Output System"
        O1["Include Output"]:::output
        O2["Src Output"]:::output
    end

    %% Main Data Flow
    PQ -->|"start"| I1
    I1 -->|"parsed input"| S1
    S1 -->|"initialized simulation"| E1
    E1 -->|"select engine"| ME
    E1 --> QE
    E1 --> RE
    E1 -->|"force computation"| FF1
    E1 --> P1
    E1 -->|"system setup"| SB1
    E1 --> T1
    E1 --> C1
    FF1 -->|"returns forces"| E1
    P1 --> E1
    SB1 --> E1
    T1 --> E1
    C1 --> E1
    E1 -->|"simulation result"| O1

    %% Supporting Utilities connections (dashed lines)
    U1 -.-> S1
    U1 -.-> E1
    Cfg -.-> S1
    Cfg -.-> E1
    LA -.-> E1
    MPII -.-> E1
    MPIS -.-> E1

    %% Click Events
    click PQ "https://github.com/molarverse/pq/blob/main/apps/PQ.cpp"
    click I1 "https://github.com/molarverse/pq/tree/main/include/input/"
    click I2 "https://github.com/molarverse/pq/tree/main/src/input/"
    click S1 "https://github.com/molarverse/pq/tree/main/include/setup/"
    click S2 "https://github.com/molarverse/pq/tree/main/src/setup/"
    click E1 "https://github.com/molarverse/pq/tree/main/include/engine/"
    click E2 "https://github.com/molarverse/pq/tree/main/src/engine/"
    click FF1 "https://github.com/molarverse/pq/tree/main/include/forceField/"
    click FF2 "https://github.com/molarverse/pq/tree/main/src/forceField/"
    click P1 "https://github.com/molarverse/pq/tree/main/include/potential/"
    click P2 "https://github.com/molarverse/pq/tree/main/src/potential/"
    click SB1 "https://github.com/molarverse/pq/tree/main/include/simulationBox/"
    click SB2 "https://github.com/molarverse/pq/tree/main/src/simulationBox/"
    click T1 "https://github.com/molarverse/pq/tree/main/include/thermostat/"
    click T2 "https://github.com/molarverse/pq/tree/main/src/thermostat/"
    click C1 "https://github.com/molarverse/pq/tree/main/include/constraints/"
    click C2 "https://github.com/molarverse/pq/tree/main/src/constraints/"
    click U1 "https://github.com/molarverse/pq/tree/main/include/utilities/"
    click Cfg "https://github.com/molarverse/pq/tree/main/include/config/"
    click LA "https://github.com/molarverse/pq/tree/main/include/linearAlgebra/"
    click MPII "https://github.com/molarverse/pq/tree/main/include/mpi/"
    click MPIS "https://github.com/molarverse/pq/tree/main/src/mpi/"
    click O1 "https://github.com/molarverse/pq/tree/main/include/output/"
    click O2 "https://github.com/molarverse/pq/tree/main/src/output/"

    %% Styles
    classDef executable fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef input fill:#adebad,stroke:#333,stroke-width:2px;
    classDef setup fill:#9fdfff,stroke:#333,stroke-width:2px;
    classDef simulation fill:#9fcfff,stroke:#333,stroke-width:2px;
    classDef force fill:#ffbb99,stroke:#333,stroke-width:2px;
    classDef system fill:#cccccc,stroke:#333,stroke-width:2px;
    classDef utilities fill:#dddddd,stroke:#333,stroke-width:2px;
    classDef output fill:#ffdd88,stroke:#333,stroke-width:2px;
```
