# molmod/stacie architecture

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

- Interactive diagram: https://gitdiagram.com/molmod/stacie
- Repository: https://github.com/molmod/stacie

## Overview

##### Project type and purpose
- STACIE is a Python package and command-line algorithm library to compute time integrals of autocorrelation functions, primarily for post-processing molecular-dynamics simulation data.
- It has four main “faces”:
a. Core library modules (src/stacie)
b. CLI/tools (tools/*.py)
c. Documentation (docs/)
d. CI & release pipelines (.github/, pyproject.toml)

##### High-level components
- Core Library
- Modules under src/stacie: conditioning, cost, cutoff, estimate, model, plot, spectrum, synthetic, utils
- Exposes functions and classes for computing integrals, modeling, and plotting results
- CLI & Helper Scripts
- tools/gensynth.py, quick.py, logo.py – example/script entry points to generate synthetic data or quick runs
- tests/inputs – sample data for regression tests
- Documentation
- docs/source – Sphinx sources, examples, tutorials, theory, references
- docs/compile_*.sh, docs/release_docs.sh – build scripts (HTML/PDF)
- Packaging & Publishing
- pyproject.toml – build configuration for setuptools/poetry
- CITATION.cff, LICENSE files
- Continuous Integration & Release
- .github/workflows/pytest.yaml – test suite on push/PR
- .github/workflows/release.yaml – release to PyPI/Zenodo
- .github/scripts/extract-notes.sh – release-note automation

##### Interactions and Data Flows
- User → CLI/tools → Core Library
- Core Library ↔ Data Inputs
- Data (numpy .npz) flows into spectrum module, processed through model/cutoff/estimate pipeline
- Core Library → Plot module → Output (graphs/files)
- Tests (pytest) → Core Library & CLI
- tests/conftest.py sets up fixtures, test_*.py validate each module
- Documentation Builder → docs/source → Sphinx → HTML/PDF → GitHub Pages
- CI Pipelines → run tests, build docs, publish package

##### Architectural Patterns & Design Principles
- Modular design: each concern (estimation, modeling, plotting) in its own module
- Separation of concerns: core logic vs. CLI vs. docs vs. CI
- Extensibility: new estimators or models can plug into core via utils and synthetic data functions
- Standard Python packaging and CI best practices

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    U["User / Researcher"]:::user

    %% CLI & Tools
    subgraph "CLI & Helper Scripts"
        G["gensynth.py"]:::cli
        Q["quick.py"]:::cli
        L["logo.py"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        C1["conditioning"]:::core
        C2["cost"]:::core
        C3["cutoff"]:::core
        C4["estimate"]:::core
        C5["model"]:::core
        C6["spectrum"]:::core
        C7["synthetic"]:::core
        C8["plot"]:::core
        C9["utils"]:::core
    end

    %% Data Layer
    DI(["Data Inputs (.npz)"]):::data

    %% Output
    O(["Output Files (plots)"]):::data

    %% Testing
    subgraph "Testing / Pytest"
        TF["conftest.py"]:::infra
        T1["test_conditioning.py"]:::infra
        T2["test_cost.py"]:::infra
        T3["test_cutoff.py"]:::infra
        T4["test_model.py"]:::infra
        T5["test_spectrum.py"]:::infra
        T6["test_synthetic.py"]:::infra
        T7["test_utils.py"]:::infra
        TR["test_regression.py"]:::infra
    end

    %% Documentation
    subgraph "Documentation"
        DocsSrc["docs/source/"]:::docs
        BuildHTML["compile_html.sh"]:::docs
        BuildPDF["compile_pdf.sh"]:::docs
        ReleaseDocs["release_docs.sh"]:::docs
        CleanDocs["clean.sh"]:::docs
        Sph["HTML/PDF"]:::docs_output
    end

    %% Packaging & Publishing
    Pkg["pyproject.toml"]:::infra
    Citation["CITATION.cff"]:::infra
    Lic1["LICENSE-CC-BY-SA-4.0.txt"]:::infra
    Lic2["LICENSE-LGPL-3.0-or-later.txt"]:::infra

    %% CI & Release
    subgraph "CI & Release"
        CItest["pytest.yaml"]:::infra
        CIrelease["release.yaml"]:::infra
        ExtractNotes["extract-notes.sh"]:::infra
        PyPI["PyPI/Zenodo"]:::infra_output
    end

    %% Relationships
    U -->|invokes| G
    U -->|invokes| Q
    U -->|invokes| L

    G -->|calls| C7
    Q -->|calls| C4
    L -->|calls| C9

    DI -->|loads .npz| C6
    C6 -->|data| C5
    C5 -->|params| C3
    C3 -->|filtered| C4
    C4 -->|results| C8
    C8 -->|plots| O

    TF --> C1
    TF --> C2
    TF --> C3
    TF --> C5
    TF --> C6
    TF --> C7
    TF --> C9

    T1 --> C1
    T2 --> C2
    T3 --> C3
    T4 --> C5
    T5 --> C6
    T6 --> C7
    T7 --> C9
    TR --> DI

    DocsSrc -->|build| BuildHTML
    DocsSrc -->|build| BuildPDF
    BuildHTML --> Sph
    BuildPDF --> Sph
    ReleaseDocs --> Sph
    CleanDocs --> DocsSrc

    CItest --> TF
    CItest -->|build docs| BuildHTML
    CItest -->|build docs| BuildPDF
    CIrelease --> PyPI
    ExtractNotes --> CIrelease

    CItest -.-> Pkg
    CIrelease -.-> Pkg

    %% Click Events
    click C1 "https://github.com/molmod/stacie/blob/main/src/stacie/conditioning.py"
    click C2 "https://github.com/molmod/stacie/blob/main/src/stacie/cost.py"
    click C3 "https://github.com/molmod/stacie/blob/main/src/stacie/cutoff.py"
    click C4 "https://github.com/molmod/stacie/blob/main/src/stacie/estimate.py"
    click C5 "https://github.com/molmod/stacie/blob/main/src/stacie/model.py"
    click C6 "https://github.com/molmod/stacie/blob/main/src/stacie/spectrum.py"
    click C7 "https://github.com/molmod/stacie/blob/main/src/stacie/synthetic.py"
    click C8 "https://github.com/molmod/stacie/blob/main/src/stacie/plot.py"
    click C9 "https://github.com/molmod/stacie/blob/main/src/stacie/utils.py"
    click G "https://github.com/molmod/stacie/blob/main/tools/gensynth.py"
    click Q "https://github.com/molmod/stacie/blob/main/tools/quick.py"
    click L "https://github.com/molmod/stacie/blob/main/tools/logo.py"
    click TF "https://github.com/molmod/stacie/blob/main/tests/conftest.py"
    click T1 "https://github.com/molmod/stacie/blob/main/tests/test_conditioning.py"
    click T2 "https://github.com/molmod/stacie/blob/main/tests/test_cost.py"
    click T3 "https://github.com/molmod/stacie/blob/main/tests/test_cutoff.py"
    click T4 "https://github.com/molmod/stacie/blob/main/tests/test_model.py"
    click T5 "https://github.com/molmod/stacie/blob/main/tests/test_spectrum.py"
    click T6 "https://github.com/molmod/stacie/blob/main/tests/test_synthetic.py"
    click T7 "https://github.com/molmod/stacie/blob/main/tests/test_utils.py"
    click TR "https://github.com/molmod/stacie/blob/main/tests/test_regression.py"
    click DocsSrc "https://github.com/molmod/stacie/tree/main/docs/source/"
    click BuildHTML "https://github.com/molmod/stacie/blob/main/docs/compile_html.sh"
    click BuildPDF "https://github.com/molmod/stacie/blob/main/docs/compile_pdf.sh"
    click ReleaseDocs "https://github.com/molmod/stacie/blob/main/docs/release_docs.sh"
    click CleanDocs "https://github.com/molmod/stacie/blob/main/docs/clean.sh"
    click Pkg "https://github.com/molmod/stacie/blob/main/pyproject.toml"
    click Citation "https://github.com/molmod/stacie/blob/main/CITATION.cff"
    click Lic1 "https://github.com/molmod/stacie/blob/main/LICENSE-CC-BY-SA-4.0.txt"
    click Lic2 "https://github.com/molmod/stacie/blob/main/LICENSE-LGPL-3.0-or-later.txt"
    click CItest "https://github.com/molmod/stacie/blob/main/.github/workflows/pytest.yaml"
    click CIrelease "https://github.com/molmod/stacie/blob/main/.github/workflows/release.yaml"
    click ExtractNotes "https://github.com/molmod/stacie/blob/main/.github/scripts/extract-notes.sh"

    %% Styles
    classDef core fill:#c8e6c9,stroke:#2e7d32
    classDef cli fill:#bbdefb,stroke:#0d47a1
    classDef data fill:#f0f4c3,stroke:#827717
    classDef docs fill:#ffe0b2,stroke:#e65100
    classDef infra fill:#eceff1,stroke:#37474f
    classDef docs_output fill:#fff3e0,stroke:#e65100
    classDef infra_output fill:#cfd8dc,stroke:#37474f
    classDef user fill:#f5f5f5,stroke:#000000
```
