How petrusen/pomsimulator works
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.