# formingworlds/aragog architecture

> Architecture diagram of the GitHub repository formingworlds/aragog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/formingworlds/aragog
- Repository: https://github.com/formingworlds/aragog

## Overview

##### Project Type & Purpose
Aragog is an open-source Python library (with a CLI) for simulating 1D rocky-mantle dynamics (solid/liquid/mixed phases). It’s a configuration-driven numerical solver pipeline, meant for both interactive use (via notebooks or API) and batch runs (via CLI).

##### High-Level File Structure & Patterns
- aragog/
– core modules: parser.py, mesh.py, phase.py, solver.py, core.py
– I/O: data.py, output.py, interfaces.py, utilities.py
– CLI entry point: cli.py
– configuration templates: cfg/*.cfg
- data/ – lookup tables & test data
- scripts/ – data-conversion utilities
- notebooks/ – tutorials & examples
- docs/ – Sphinx documentation
- tests/ – pytest suite & reference outputs
- .github/ – CI/CD workflows (unit tests, publishing)
- pyproject.toml, readthedocs.yaml, .github workflows – build & deploy config

Architectural patterns:
– Pipeline stages (input → setup → compute → output)
– Configuration-driven experiments (.cfg files)
– Clear separation of concerns (parsing, physics, I/O)
– Dual interface (CLI + importable API)
– Automated testing & CI

##### Relationships & Data Flow
1. User → CLI or API import
2. CLI/API → Setup Layer (parser & interfaces)
3. Setup → Run Layer (mesh → phase → solver → core)
4. Run → Output Layer (output.py → files, console)
5. Output → Post-processing (notebooks/scripts)
6. Tests/CI monitor Setup, Run, and Output correctness

##### Key Technologies & Services
- Python 3.10+
- pytest (unit tests)
- Sphinx & ReadTheDocs (documentation)
- GitHub Actions (CI/CD)
- Poetry or pip (packaging)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry
    User["User"]:::side
    User -->|"via CLI"| CLI
    User -->|"via API import"| Parser

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        CFG["aragog/cfg/*.cfg"]:::dataLayer
        Lookup["data/test/*.dat"]:::dataLayer
        Preprocess["scripts/convert_datatables.py"]:::dataLayer
        RefOutput["tests/reference/*.dat"]:::dataLayer
    end

    %% Setup Layer
    subgraph "Setup Layer"
        direction TB
        Parser["aragog/parser.py"]:::setupLayer
        Interfaces["aragog/interfaces.py"]:::setupLayer
        Utilities["aragog/utilities.py"]:::setupLayer
    end

    %% Run Layer
    subgraph "Run Layer"
        direction TB
        Mesh["aragog/mesh.py"]:::runLayer
        Phase["aragog/phase.py"]:::runLayer
        Solver["aragog/solver.py"]:::runLayer
        Core["aragog/core.py"]:::runLayer
    end

    %% Output Layer
    subgraph "Output Layer"
        direction TB
        Output["aragog/output.py"]:::outputLayer
        CLI["aragog/cli.py"]:::outputLayer
        PostProc["notebooks/"]:::outputLayer
    end

    %% Testing & CI Sideflows
    subgraph "Testing & CI"
        direction TB
        Tests["tests/*.py"]:::side
        TestRef["tests/reference/"]:::side
        CI[".github/workflows/ci_tests.yml"]:::side
    end

    %% Data → Setup
    CFG -->|provides config| Parser
    Lookup -->|provides tables| Parser
    Preprocess -->|generates lookup| Lookup
    RefOutput -.->|baseline data| Tests

    %% Setup → Run
    Parser -->|builds model| Mesh
    Interfaces -->|connects I/O| Core
    Utilities -->|helper functions| Core

    Mesh -->|grid data| Phase
    Phase -->|properties| Solver
    Solver -->|timesteps| Core

    %% Run → Output
    Core -->|results| Output
    Output -->|logs & files| PostProc
    Core -->|status| CLI

    %% Tests & CI flows
    Tests -->|run suite| Core
    CI -->|executes| Tests

    %% Click Events
    click CFG "https://github.com/formingworlds/aragog/blob/main/aragog/cfg/*.cfg"
    click Lookup "https://github.com/formingworlds/aragog/blob/main/data/test/*.dat"
    click Preprocess "https://github.com/formingworlds/aragog/blob/main/scripts/convert_datatables.py"
    click RefOutput "https://github.com/formingworlds/aragog/blob/main/tests/reference/*.dat"
    click Parser "https://github.com/formingworlds/aragog/blob/main/aragog/parser.py"
    click Interfaces "https://github.com/formingworlds/aragog/blob/main/aragog/interfaces.py"
    click Utilities "https://github.com/formingworlds/aragog/blob/main/aragog/utilities.py"
    click Mesh "https://github.com/formingworlds/aragog/blob/main/aragog/mesh.py"
    click Phase "https://github.com/formingworlds/aragog/blob/main/aragog/phase.py"
    click Solver "https://github.com/formingworlds/aragog/blob/main/aragog/solver.py"
    click Core "https://github.com/formingworlds/aragog/blob/main/aragog/core.py"
    click Output "https://github.com/formingworlds/aragog/blob/main/aragog/output.py"
    click CLI "https://github.com/formingworlds/aragog/blob/main/aragog/cli.py"
    click PostProc "https://github.com/formingworlds/aragog/tree/main/notebooks/"
    click Tests "https://github.com/formingworlds/aragog/blob/main/tests/*.py"
    click TestRef "https://github.com/formingworlds/aragog/tree/main/tests/reference/"
    click CI "https://github.com/formingworlds/aragog/blob/main/.github/workflows/ci_tests.yml"

    %% Styles
    classDef dataLayer fill:#cce5ff,stroke:#004085,color:#004085;
    classDef setupLayer fill:#d4edda,stroke:#155724,color:#155724;
    classDef runLayer fill:#fff3cd,stroke:#856404,color:#856404;
    classDef outputLayer fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef side fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
