# petrusen/pomsimulator architecture

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

- Interactive diagram: https://gitdiagram.com/petrusen/pomsimulator
- Repository: https://github.com/petrusen/pomsimulator

## Overview

##### Project type and purpose
- POMSimulator is a Python-based scientific simulation tool (a modular monolithic full-stack Python package with command-line entrypoints).
- Its purpose is to read quantum-chemistry output files (ADF), build reaction networks via graph algorithms, solve non-linear speciation equations, and produce both raw results and analysis/plots for polyoxometalate self-assembly.

##### File structure
- Top-level:
- `.github/` (CI/CD workflows)
- `inputs/` (raw QM ADF output and auxiliary config files)
- `outputs/` (generated reaction network and formation constants)
- `pomsimulator/` (core Python package)
- `simulations/` (user-facing scripts that tie inputs → core engine → outputs)
- `utilities/` (post-processing and plotting scripts)
- `setup.py` (packaging, console script entrypoints)
- Within `pomsimulator/modules/`:
- `DataBase.py` (data model/IO)
- `graph_module.py` (reaction network construction via NetworkX)
- `helper_module.py`, `msce_module.py` (math, solvers)
- `plotting_module.py`, `stats_module.py`, `text_module.py`

##### README for additional insights
- Workflow image (`docs/.img/pom_workflow.png`) outlines high-level flow: Inputs → Reaction map generation → Equation solving → Outputs → Scaling → Plotting.
- Dependencies (implied): Python 3.8–3.12, SciPy, NumPy, NetworkX, Matplotlib, Sphinx for docs.

##### Main components and their interactions
a. **Components**
1. Input layer
- Raw QM files (`inputs/***.out`)
- Configuration files (`*.pomsim`)
2. Core engine (`pomsimulator` package)
- Data parsers (DataBase)
- Graph builder (graph_module)
- Solver (msce_module, helper_module)
- Output writers (text_module, DataBase)
3. Simulation scripts (`simulations/*.py`)
- Instantiate core engine
- Point at specific input sets (W_Set_PBE, PMo_Set)
- Invoke engine run → generate outputs in `outputs/`
4. Post-processing utilities (`utilities/*.py`)
- Scaling (`scale_constants.py`)
- Clustering and statistical analyses (`SM_clusterization.py`, `stats_module`)
5. Documentation & CI/CD
- `docs/` for user manuals and architecture docs
- `.github/workflows/` for tests and publishing

b. **Data flow & Dependencies**
- Inputs → Simulation script → Core engine modules → Outputs
- Outputs + scaling parameters → Utilities → Plots/analysis
- Core engine depends on external Python libs (NumPy, SciPy, NetworkX, Matplotlib)
- Packaging via `setup.py` exposes console scripts

##### Architectural patterns & principles
- Modular separation: core logic (in `pomsimulator/modules`) vs. orchestration (`simulations`) vs. post-processing (`utilities`).
- Single monolithic codebase, no microservices.
- Clear layering: IO layer, processing layer, output layer.
- Use of Graph Theory (NetworkX) for reaction network modeling; numerical solvers for non-linear systems.

##### Detailed capture of essential elements
- Modules by functionality in the Core Engine container.
- That `setup.py` defines console entrypoints for the simulation scripts.
- Explicitly call out the two phases:
1. Simulation phase (Inputs → Reaction network & constants)
2. Analysis phase (Scaling → Speciation & phase plotting)
- That all components live in a single codebase but follow a layered data-flow design.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        Inputs["Inputs (QM .out, .pomsim)"]:::fs
    end
    click Inputs "https://github.com/petrusen/pomsimulator/tree/main/inputs/"

    %% Simulation Orchestrator
    subgraph "Simulation Orchestrator"
        SimHPA["simulation_hpa.py"]:::script
        SimIPA["simulation_ipa.py"]:::script
    end
    click SimHPA "https://github.com/petrusen/pomsimulator/blob/main/simulations/simulation_hpa.py"
    click SimIPA "https://github.com/petrusen/pomsimulator/blob/main/simulations/simulation_ipa.py"

    %% Core Engine
    subgraph "Core Engine"
        subgraph "Data Parsing"
            DB["DataBase.py"]:::core
        end
        subgraph "Network Builder"
            Graph["graph_module.py"]:::core
        end
        subgraph "Solver"
            MSC["msce_module.py"]:::core
            Helper["helper_module.py"]:::core
        end
        subgraph "Output Writer"
            Text["text_module.py"]:::core
        end
        subgraph "Statistics"
            Stats["stats_module.py"]:::core
        end
        subgraph "Plotting"
            PlotCore["plotting_module.py"]:::core
        end
    end
    click DB "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/DataBase.py"
    click Graph "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/graph_module.py"
    click MSC "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/msce_module.py"
    click Helper "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/helper_module.py"
    click Text "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/text_module.py"
    click Stats "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/stats_module.py"
    click PlotCore "https://github.com/petrusen/pomsimulator/blob/main/pomsimulator/modules/plotting_module.py"

    %% Raw Outputs
    Outputs["Outputs (.txt)"]:::fs
    click Outputs "https://github.com/petrusen/pomsimulator/tree/main/outputs/"

    %% Post-Processing Utilities
    subgraph "Post-Processing Utilities"
        Scale["scale_constants.py"]:::script
        HPA_Spec["hpa_speciation.py"]:::script
        HPA_Phase["hpa_phase.py"]:::script
        MapHPA["plot_reac_map_hpa.py"]:::script
        PhaseHPA["plot_phase_diagram_hpa.py"]:::script
        IPA_Spec["ipa_speciation.py"]:::script
        IPA_Phase["ipa_phase.py"]:::script
        MapIPA["plot_reac_map_ipa.py"]:::script
        SpecGen["plot_speciation_diagram.py"]:::script
        Cluster1["SM_clusterization.py"]:::script
        Cluster2["cluster_model_selection.py"]:::script
        Cluster3["clust_boxplot_filtering.py"]:::script
        Iso["compute_isomorphism.py"]:::script
        Mol["generate_mol_file.py"]:::script
    end
    click Scale "https://github.com/petrusen/pomsimulator/blob/main/utilities/scale_constants.py"
    click HPA_Spec "https://github.com/petrusen/pomsimulator/blob/main/utilities/hpa_speciation.py"
    click HPA_Phase "https://github.com/petrusen/pomsimulator/blob/main/utilities/hpa_phase.py"
    click MapHPA "https://github.com/petrusen/pomsimulator/blob/main/utilities/plot_reac_map_hpa.py"
    click PhaseHPA "https://github.com/petrusen/pomsimulator/blob/main/utilities/plot_phase_diagram_hpa.py"
    click IPA_Spec "https://github.com/petrusen/pomsimulator/blob/main/utilities/ipa_speciation.py"
    click IPA_Phase "https://github.com/petrusen/pomsimulator/blob/main/utilities/ipa_phase.py"
    click MapIPA "https://github.com/petrusen/pomsimulator/blob/main/utilities/plot_reac_map_ipa.py"
    click SpecGen "https://github.com/petrusen/pomsimulator/blob/main/utilities/plot_speciation_diagram.py"
    click Cluster1 "https://github.com/petrusen/pomsimulator/blob/main/utilities/SM_clusterization.py"
    click Cluster2 "https://github.com/petrusen/pomsimulator/blob/main/utilities/cluster_model_selection.py"
    click Cluster3 "https://github.com/petrusen/pomsimulator/blob/main/utilities/clust_boxplot_filtering.py"
    click Iso "https://github.com/petrusen/pomsimulator/blob/main/utilities/compute_isomorphism.py"
    click Mol "https://github.com/petrusen/pomsimulator/blob/main/utilities/generate_mol_file.py"

    %% Plots & Analysis
    Plots["Generated Figures"]:::fs

    %% Documentation & CI/CD
    subgraph "Documentation & CI/CD"
        Docs["docs/"]:::fs
        CI[".github/workflows/"]:::fs
    end
    click Docs "https://github.com/petrusen/pomsimulator/tree/main/docs/"
    click CI "https://github.com/petrusen/pomsimulator/blob/main/.github/workflows/python-publish.yml"
    click CI "https://github.com/petrusen/pomsimulator/blob/main/.github/workflows/test-pomsimulator.yml"

    %% Packaging & Entry-Points
    Setup["setup.py"]:::script
    click Setup "https://github.com/petrusen/pomsimulator/blob/main/setup.py"

    %% External Dependencies
    subgraph "External Dependencies"
        Python["Python 3.8–3.12"]:::ext
        NumPy["NumPy"]:::ext
        SciPy["SciPy"]:::ext
        NetworkX["NetworkX"]:::ext
        Matplotlib["Matplotlib"]:::ext
    end

    %% Data Flow
    Inputs --> SimHPA
    Inputs --> SimIPA
    Setup --> SimHPA
    Setup --> SimIPA

    SimHPA --> DB
    SimIPA --> DB
    DB --> Graph
    Graph --> MSC
    Helper --> MSC
    MSC --> Text
    Text --> Outputs

    Outputs --> Scale
    Scale --> HPA_Spec
    Scale --> IPA_Spec
    HPA_Spec --> Plots
    HPA_Phase --> Plots
    MapHPA --> Plots
    PhaseHPA --> Plots
    IPA_Spec --> Plots
    IPA_Phase --> Plots
    MapIPA --> Plots
    SpecGen --> Plots
    Cluster1 --> Plots
    Cluster2 --> Plots
    Cluster3 --> Plots
    Iso --> Plots
    Mol --> Plots

    %% Dependency Arrows
    Python -.-> Setup
    Python -.-> DB
    Python -.-> MSC
    NumPy -.-> DB
    SciPy -.-> MSC
    NetworkX -.-> Graph
    Matplotlib -.-> PlotCore
    Matplotlib -.-> HPA_Spec
    Matplotlib -.-> HPA_Phase
    Matplotlib -.-> MapHPA
    Matplotlib -.-> PhaseHPA
    Matplotlib -.-> IPA_Spec
    Matplotlib -.-> IPA_Phase
    Matplotlib -.-> MapIPA
    Matplotlib -.-> SpecGen

    %% Styles
    classDef core fill:#ADD8E6,stroke:#004080,color:#000000
    classDef fs fill:#90EE90,stroke:#006400,color:#000000,shape:folder
    classDef script fill:#FFA500,stroke:#FF8C00,color:#000000
    classDef ext fill:#D3D3D3,stroke:#696969,color:#000000,stroke-dasharray: 2 2
```
