How molarverse/pq works
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.