Developer Guide

This section includes information for developers who want to contribute to the project. It includes information about the project structure, how to run the tests, and how to build the documentation. It also includes information about the project’s coding style and how to contribute to the project.

Project Structure

PQ is a C++ molecular dynamics simulation engine with Python bindings, organized into a modular architecture. The project follows standard C++ project conventions with clear separation between headers, source code, applications, tests, and documentation.

Core Directory Layout

The main directories are organized as follows:

Source Code:

• src/ - Implementation files (.cpp) containing the core functionality

• include/ - Header files (.hpp) defining interfaces and declarations

• apps/ - Main application executable (PQ.cpp)

Build System:

• CMakeLists.txt - Main CMake configuration file

Testing:

• tests/ - Unit tests for individual components

• integration_tests/ - Integration tests using pytest

Documentation:

• docs/ - Sphinx documentation source files and build configuration

• README.md - Project overview and installation instructions

External Dependencies:

• external/ - Third-party libraries (googletest, progressbar, toml++)

Utilities:

• scripts/ - Build scripts, Singularity definition files, and utility scripts

• examples/ - Example simulation input files

• config/ - License headers

Core Architecture

The PQ codebase is organized into functional modules, each contained in its own directory within both src/ and include/:

Simulation Engine:

• engine/ - Main simulation engine and orchestration

• integrator/ - Numerical integration algorithms

• thermostat/ - Temperature control algorithms

• manostat/ - Pressure control algorithms

Physical Models:

• forceField/ - MM bonded interactions

• intraNonBonded/ - MM intramolecular non-bonded interactions

• potential/ - MM intermolecular non-bonded interactions

• QM/ - Interface to QM runner programs

System Setup:

• input/ - Input and setup file parsing

• setup/ - System initialization and configuration

• simulationBox/ - Simulation cell, molecule and atom handling

• connectivity/ - Molecular topology and bonding information

Data Management:

• box/ - Simulation box geometry and periodic boundary conditions

• physicalData/ - Physical constants and unit conversions

• output/ - Output file generation and data writing

Computational Infrastructure:

• linearAlgebra/ - Vector and matrix operations

• utilities/ - General utility functions and helpers

• kernels/ - Computational kernels and optimized routines

• timings/ - Performance profiling and timing utilities

Advanced Features:

• constraints/ - Constraint algorithms (SHAKE, RATTLE, etc.)

• maxwellBoltzmann/ - Maxwell-Boltzmann velocity initialization

• resetKinetics/ - Kinetic energy manipulation

• virial/ - Virial stress tensor calculations

• mpi/ - MPI parallelization support

• python/ - Python bindings and interface

• opt/ - Optimization algorithms

Design Patterns:

• concepts/ - C++20 concepts for template constraints

• exceptions/ - Custom exception classes

• settings/ - Configuration and settings management

Build Configuration

The project uses CMake as its build system:

• Root CMakeLists.txt configures the overall project

• Each major directory contains its own CMakeLists.txt for modular compilation

• External dependencies are managed through CMake’s FetchContent or find_package

• Support for different build types (Debug, Release) and optional features (MPI support)

Software Tests

Unit Testing

Unit tests are located in the PQ/tests/ directory. After building the project, the unit tests can be run by executing the command make test from within the build directory.

Integration Testing

Integration tests are located in the PQ/integration_tests/ directory. To run these tests, ensure the following Python packages are installed:

• pytest

• pytest-cov

• pqanalysis

• ase

• pyscf

In addition, the DFTB+ program package has to be installed. You can then run the integration tests with the command pytest PQ/integration_tests.

GitHub Actions

The software workflow — from building the project to running unit and integration tests — is validated by continuous integration (CI) using GitHub Actions. The corresponding workflow configuration files are located in the PQ/.github/workflows/ directory.

Documentation

This documentation is written as reStructuredText files .rst and converted to HTML website files by Sphinx . The respective source files are located in PQ/docs/sphinx/src/. In order to compile the files locally you need to install the following Python packages:

• Sphinx

• sphinx_sitemap

• breathe

• sphinx_rtd_theme

The project is built by running make html in the folder PQ/docs/sphinx/. The resulting website can be viewed by opening the file PQ/docs/sphinx/_build/html/index.html via your favorite browser.

How to Contribute

For anyone willing to contribute to the project, it is important to understand the branching model used by the project. The project uses the git-flow branching model. Furthermore, git hooks for commit messages need to be enabled. In order to contribute to the project, please follow these steps:

1. Fork the project on GitHub. (not necessary if you are a member of the project)

2. Clone your fork locally:

   $ git clone https://github.com/MolarVerse/PQ.git
   

3. Enable automated commit message validation by installing the provided git hook:

   $ cp .githooks/commit-msg .git/hooks/
   

4. Initialize git-flow and use the following settings (if not specified default settings are used)

   $ git flow init
   [master] main
   [develop] dev
   [version tag prefix] v
   

5. Create a feature branch for your contribution:

   $ git flow feature start <feature_branch_name>
   

6. Commit your changes to your feature branch and publish your feature branch:

   $ git add <files>
   $ git commit -m "commit message"
   $ git flow feature publish <feature_branch_name>
   

7. Create a pull request on GitHub.