# m3g/packmol architecture

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

- Interactive diagram: https://gitdiagram.com/m3g/packmol
- Repository: https://github.com/m3g/packmol

## Overview

##### Project type and purpose
- This is a scientific, command-line, monolithic Fortran application (“Packmol”) whose goal is to build initial configurations for molecular‐dynamics simulations by packing molecules under spatial constraints.
- It is not a web or full-stack app; rather, it is a high-performance CLI tool with an extensible Fortran code base, multiple build scripts (Makefile, CMake, fpm), and a test harness.

##### File structure
- Top-level directories and files:
- .github/workflows/actions.yml – CI pipeline for builds/tests
- CMakeLists.txt, Makefile, configure, compile_cmake.sh, fpm.toml – different build entry points
- app/packmol.f90, solvate.tcl – main application wrapper and auxiliary scripts
- header/ – Fortran module interface definitions
- src/ – dozens of Fortran implementation files, each module handling a specific algorithmic piece (e.g., cell_indexing, heuristics, random, pbc)
- testing/ – Julia and shell‐based test harness, reference inputs and outputs
- Notice: monolithic module structure, no frontend/backend separation; the architecture is “modular monolith.”

##### README for additional insights
- Confirms CLI usage, supported formats (PDB, TINKER, XYZ).
- Outlines two main build flows: classic make/configure and fpm.
- References external dependencies: Fortran compilers (gfortran, ifort), Julia (for tests), GitHub Actions.

##### Detail without overthinking
- Every logical module group (I/O, geometry, heuristics, random number, boundary conditions, utilities).
- Every build script variant and test pathway.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment"
        HD["header/"]:::env
        SC["src/"]:::env
    end

    subgraph "Build System"
        subgraph "Classic Make"
            CFG["configure"]:::build
            MK["Makefile"]:::build
            RS["release.sh"]:::build
            CFG & MK & RS --> COMPILER
        end
        subgraph "CMake"
            CML["CMakeLists.txt"]:::build
            CCS["compile_cmake.sh"]:::build
            CML --> CCS --> COMPILER
        end
        subgraph "FPM"
            FPMT["fpm.toml"]:::build
            FPM_TOOL["FPM"]:::build
            FPMT --> FPM_TOOL --> COMPILER
        end
        COMPILER["Fortran Compiler"]:::build
        COMPILER --> EXEC["packmol Executable"]:::runtime
    end

    subgraph "Runtime / CLI"
        CLI["packmol"]:::runtime
        AUX["solvate.tcl"]:::runtime
        CLI -->|"invokes"| AUX

        subgraph "Parsing"
            P1["getinp.f90"]:::runtime
            P2["input.f90"]:::runtime
            CLI --> P1 --> P2
        end

        subgraph "Core Packing Engine"
            H["heuristics.f90"]:::runtime
            CI_MOD["cell_indexing.f90"]:::runtime
            ST["swaptypemod.f90"]:::runtime
            RND["random.f90"]:::runtime
            P2 --> H --> CI_MOD --> ST --> RND
        end

        subgraph "Boundary Conditions"
            PBC["pbc.f90"]:::runtime
            RC["resetcells.f90"]:::runtime
            RND --> PBC --> RC
        end

        subgraph "Output Generation"
            OUT["output.f90"]:::runtime
            WS["writesuccess.f90"]:::runtime
            RC --> OUT --> WS
        end

        subgraph "Utilities"
            CMAS["cenmass.f90"]:::runtime
            JAC["jacobi.f90"]:::runtime
            FLASH["flashsort.f90"]:::runtime
            WS --> CMAS & JAC & FLASH
        end
    end

    subgraph "Testing & CI"
        CIWF[".github/workflows/actions.yml"]:::testing
        REF_IN["testing/input_files/"]:::testing
        REF_STR["testing/structure_files/"]:::testing
        TH["testing/runtests.jl"]:::testing
        TS["testing/test.sh"]:::testing
        REF_OUT["testing/output_files/"]:::testing

        REF_IN & REF_STR --> TH & TS --> CLI --> REF_OUT
        CIWF -->|"runs build and tests"| CFG
        CIWF -->|"runs build and tests"| CML
        CIWF -->|"runs build and tests"| FPMT
        CIWF -->|"runs tests"| TH
    end

    click HD "https://github.com/m3g/packmol/tree/master/header/"
    click SC "https://github.com/m3g/packmol/tree/master/src/"
    click CFG "https://github.com/m3g/packmol/tree/master/configure"
    click MK "https://github.com/m3g/packmol/tree/master/Makefile"
    click RS "https://github.com/m3g/packmol/blob/master/release.sh"
    click CML "https://github.com/m3g/packmol/blob/master/CMakeLists.txt"
    click CCS "https://github.com/m3g/packmol/blob/master/compile_cmake.sh"
    click FPMT "https://github.com/m3g/packmol/blob/master/fpm.toml"
    click CIWF "https://github.com/m3g/packmol/blob/master/.github/workflows/actions.yml"
    click CLI "https://github.com/m3g/packmol/blob/master/app/packmol.f90"
    click AUX "https://github.com/m3g/packmol/blob/master/solvate.tcl"
    click P1 "https://github.com/m3g/packmol/blob/master/src/getinp.f90"
    click P2 "https://github.com/m3g/packmol/blob/master/src/input.f90"
    click H "https://github.com/m3g/packmol/blob/master/src/heuristics.f90"
    click CI_MOD "https://github.com/m3g/packmol/blob/master/src/cell_indexing.f90"
    click ST "https://github.com/m3g/packmol/blob/master/src/swaptypemod.f90"
    click RND "https://github.com/m3g/packmol/blob/master/src/random.f90"
    click PBC "https://github.com/m3g/packmol/blob/master/src/pbc.f90"
    click RC "https://github.com/m3g/packmol/blob/master/src/resetcells.f90"
    click OUT "https://github.com/m3g/packmol/blob/master/src/output.f90"
    click WS "https://github.com/m3g/packmol/blob/master/src/writesuccess.f90"
    click CMAS "https://github.com/m3g/packmol/blob/master/src/cenmass.f90"
    click JAC "https://github.com/m3g/packmol/blob/master/src/jacobi.f90"
    click FLASH "https://github.com/m3g/packmol/blob/master/src/flashsort.f90"
    click TH "https://github.com/m3g/packmol/blob/master/testing/runtests.jl"
    click TS "https://github.com/m3g/packmol/blob/master/testing/test.sh"
    click REF_IN "https://github.com/m3g/packmol/tree/master/testing/input_files/"
    click REF_STR "https://github.com/m3g/packmol/tree/master/testing/structure_files/"
    click REF_OUT "https://github.com/m3g/packmol/tree/master/testing/output_files/"

    classDef env fill:#E0B3FF,stroke:#9055A2,font-weight:bold
    classDef build fill:#B3D9FF,stroke:#5590B8,font-weight:bold
    classDef runtime fill:#B3FFB3,stroke:#5A955A,font-weight:bold
    classDef testing fill:#FFD9B3,stroke:#B8752F,font-weight:bold
```
