# anish9435/fmo-cc architecture

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

- Interactive diagram: https://gitdiagram.com/anish9435/fmo-cc
- Repository: https://github.com/anish9435/fmo-cc

## Overview

##### Project Type and Purpose
- This is a Python-based CLI application and library for high-accuracy quantum chemical calculations using the Fragment Molecular Orbital (FMO) framework with Coupled Cluster (CC) and MP2 methods.
- It is a modular, pipeline-oriented scientific tool that (a) parses GAMESS output files, (b) builds fragments and configures calculations, (c) executes energy computations (RHF, MP2, CC), and (d) handles parallelization and logging.

##### File Structure
- **Entry Points / Scripts** (Scripts/run_fmo_cc.py, __main__.py)
- **Core Package** (src/fmocc/):
- fmo_config.py – loads JSON input and sets up parameters
- fmo_extractor.py – reads GAMESS output (`.dat`, `_2eint.dat`)
- fmo_processor.py – orchestrates per-fragment workflow
- fmo_calculator.py – computes fragment energies (RHF, CC)
- MP2.py – specialized MP2 routines
- main_parallel.py – manages multiprocessing of CC tasks
- utils.py – logging, caching, helpers
- **Support Files**: input.json (example config), setup.sh, pyproject.toml, wrapper scripts for GAMESS.

##### README for Insights
- Emphasis on configurability via JSON, multiprocess parallelism, modular design, and GAMESS integration.
- No GUI or front-end—pure back-end computational pipeline.

##### Main Components and Their Relationships
A. **User/CLI Layer**
- run_fmo_cc.py or python -m fmocc
↓
B. **Configuration Loader** (fmo_config.py)
- Reads input.json or custom JSON
- Validates parameters (method, basis_set, fragment definitions)
↓
C. **Data Extraction Layer** (fmo_extractor.py)
- Parses GAMESS output files for integrals, MO coefficients, energies
↓
D. **Workflow Orchestrator** (fmo_processor.py)
- Divides the molecule into fragments (FMO1/FMO2)
- Calls the calculator or dispatches to parallel manager
↓
E. **Computation Engines**
- **Serial / MP2 Engine** (MP2.py)
↓
F. **Parallelization Manager** (main_parallel.py)
- Spawns worker processes, collects partial energies
↓
G. **Result Aggregation & Logging** (utils.py)
- Merges energies, writes rotating log files, outputs final results

External Service: GAMESS (invoked via run_gamess.sh)
Storage: File system (input .dat files, intermediate caches, final energy reports)

##### Architectural Patterns and Design Principles
- **Modular Pipeline**: clear separation of concerns across extraction, configuration, processing, computation, and logging.
- **Adapter Pattern**: for GAMESS outputs to internal data structures.
- **Worker Pool / Fork–Join**: for parallel CC/MP2 computations.
- **Configuration-Driven**: all run parameters flow from JSON into fmo_config.

##### Technologies, Frameworks, and Libraries
- Python 3.8+
- Standard Library: multiprocessing, logging, json
- External Tool: GAMESS (via shell wrapper scripts)
- Packaging: pyproject.toml (PEP 621)
- Shell scripts: run_gamess.sh, twoeint_process.sh

##### Essential Details to Capture
- The **order** of steps in the FMO-CC pipeline.
- The **multiprocessing** boundary in main_parallel.py.
- The **two external interactions**: (a) reading GAMESS outputs, (b) writing logs/results.
- The **module-to-module** dependencies within `src/fmocc`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User/CLI Layer
    subgraph "User/CLI Layer"
        CLI1["run_fmo_cc.py"]:::entry
        CLI2["__main__.py"]:::entry
    end

    %% Configuration Loader
    subgraph "Configuration Loader"
        Config["fmo_config.py"]:::core
        Input["input.json"]:::external
    end

    %% Data Extraction Layer
    subgraph "Data Extraction Layer"
        Extractor["fmo_extractor.py"]:::core
        DAT1["water-4_RHF_621g.dat"]:::external
        DAT2["water-4_RHF_621g_2eint.dat"]:::external
    end

    %% Workflow Orchestrator
    subgraph "Workflow Orchestrator"
        Processor["fmo_processor.py"]:::core
    end

    %% Computation Engines
    subgraph "Computation Engines"
        MP2["MP2.py"]:::core
        CC["fmo_calculator.py"]:::core
        Diag["diagrams.py"]:::core
    end

    %% Parallelization Manager
    subgraph "Parallelization Manager"
        Parallel["main_parallel.py"]:::core
    end

    %% Result Aggregation & Logging
    subgraph "Result Aggregation & Logging"
        Utils["utils.py"]:::core
    end

    %% External Tools & Support
    subgraph "External Tools & Support"
        GAM1["run_gamess.sh"]:::external
        GAM2["twoeint_process.sh"]:::external
        Pj["pyproject.toml"]:::external
        Setup["setup.sh"]:::external
    end

    %% Storage
    DB[(File System)]:::external

    %% Connections
    CLI1 -->|"launch CLI"| Config
    CLI2 -->|"launch CLI"| Config
    CLI1 -->|"invoke GAMESS"| GAM1

    Input -->|"config JSON"| Config
    Config -->|"parameters"| Processor

    DAT1 -->|"GAMESS output"| Extractor
    DAT2 -->|"integral data"| Extractor
    Extractor -->|"parsed data"| Processor

    Processor -->|"dispatch tasks"| Parallel
    Parallel -->|"MP2 tasks"| MP2
    Parallel -->|"CC tasks"| CC
    CC -->|"uses expansions"| Diag
    MP2 -->|"partial energies"| Parallel
    CC -->|"partial energies"| Parallel
    Parallel -->|"collected energies"| Processor

    Processor -->|"results"| Utils
    Utils -->|"logs & reports"| DB

    %% Click Events
    click CLI1 "https://github.com/anish9435/fmo-cc/blob/main/Scripts/run_fmo_cc.py"
    click CLI2 "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/__main__.py"
    click Config "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/fmo_config.py"
    click Input "https://github.com/anish9435/fmo-cc/blob/main/input.json"
    click Extractor "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/fmo_extractor.py"
    click DAT1 "https://github.com/anish9435/fmo-cc/blob/main/water-4_RHF_621g.dat"
    click DAT2 "https://github.com/anish9435/fmo-cc/blob/main/water-4_RHF_621g_2eint.dat"
    click Processor "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/fmo_processor.py"
    click MP2 "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/MP2.py"
    click CC "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/fmo_calculator.py"
    click Diag "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/diagrams.py"
    click Parallel "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/main_parallel.py"
    click Utils "https://github.com/anish9435/fmo-cc/blob/main/src/fmocc/utils.py"
    click GAM1 "https://github.com/anish9435/fmo-cc/blob/main/Scripts/run_gamess.sh"
    click GAM2 "https://github.com/anish9435/fmo-cc/blob/main/Scripts/twoeint_process.sh"
    click Pj "https://github.com/anish9435/fmo-cc/blob/main/pyproject.toml"
    click Setup "https://github.com/anish9435/fmo-cc/blob/main/setup.sh"

    %% Styles
    classDef entry fill:#a8f0c6,stroke:#333;
    classDef core fill:#a0d1f5,stroke:#333;
    classDef external fill:#f5b461,stroke:#333;
```
