# tomrobin-teschner/pygcs architecture

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

- Interactive diagram: https://gitdiagram.com/tomrobin-teschner/pygcs
- Repository: https://github.com/tomrobin-teschner/pygcs

## Overview

**pyGCS** is a **Python library/package** (published on PyPI) for performing **Grid Convergence Studies** and computing **Grid Convergence Index (GCI)** metrics from numerical simulation results.

- the public API surface (what users import and call),
- the internal computation engine,
- the output/rendering paths (Markdown/LaTeX/Word text),
- packaging + tests as supporting components.

##### Repository into architectural blocks (from the file tree)
Top-level signals:

- `src/pyGCS/` → the actual library code
- `GCS.py` → **high-level API**: multi-grid study, pretty table outputs
- `GCI.py` → **low-level engine**: core computations + getters/setters
- `__init__.py` → exports public classes (import surface)
- `tests/` → unit tests validating both APIs (`test_GCI.py`, `test_GCS.py`)
- `pyproject.toml`, `setup.py`, `setup.cfg` → packaging/build metadata (distribution architecture)
- `images/` → documentation artifacts (not runtime)
- `README.md` → usage-driven architecture: explains the two-tier API, supported outputs, optional Oberkampf-Roy correction, and how multi-grid is decomposed into successive 3-grid studies.

**Key architectural insight from README:**
- There are **two primary components**: `GCS` (orchestrator + presentation) and `GCI` (calculation kernel).
- `GCS` **calls `GCI` internally**, especially when the user provides **>3 grids** (it runs multiple 3-grid GCI evaluations).
- Output formats are **text/table renderers** (Markdown/LaTeX/Word-friendly tab-separated text) generated via `GCS.print_table(...)`.

##### What to include as “main components”
For this project, the main components are:

##### External Actor
- **User / Client Code** (CFD/FEA pipeline, notebook, scripts)

##### Public Library API (what the user touches)
- `pyGCS.GCS` (high-level)
- `pyGCS.GCI` (low-level)

##### Core computation engine
- “GCI computation kernel” (implemented by `GCI`):
- inputs: `cells`, `solution`, plus either `grid_size` or `volume` + `dimension`
- optional behavior: `oberkampf_correction`
- outputs/derived values: `gci`, `asymptotic_gci`, `apparent_order`, `refinement_ratio`, `extrapolated_value`, etc.
- dynamic behavior: `set(key,value)` invalidates state; `get(key)` triggers recomputation when out-of-date

##### Output artifacts (important in data-flow even though they’re “just files”)
- `table.md`, `table.tex`, `table.txt` (Word tab-separated instructions)

##### Quality + Distribution (supporting architecture)
- Unit tests: `tests/test_GCI.py`, `tests/test_GCS.py`
- Packaging: `pyproject.toml`, `setup.py`, `setup.cfg` (PyPI distribution)

##### User → GCS constructor
- passes: `dimension`, `simulation_order`, `cells[]`, `solution[]`, and either:
- `grid_size[]` OR
- `volume` (scalar or list)
- optional: `oberkampf_correction`

##### GCS → GCI (internal instantiation/calls)
- For exactly 3 grids: one GCI evaluation
- For >3 grids: multiple GCI evaluations on successive triples
- “creates GCI(dimension, order, cells[...], solution[...])”
- “iterates across grid windows (3 at a time)”

##### User → GCI (direct low-level usage path)
- calls `get('gci')`, `get('asymptotic_gci')`, etc.
- calls `set('volume', ...)` etc. → marks state stale → recompute on next `get(...)`

##### GCS → Output Files
- `print_table(output_type='markdown'|'latex'|'word', output_path=...)`
- “renders table” → “writes file”

##### (Optional but useful) Tests → GCI/GCS
- unit tests import and validate computations/formatting

##### Architectural patterns worth explicitly calling out

- **Layering / API tiers**
- High-level “workflow + rendering” (`GCS`)
- Low-level “calculation kernel” (`GCI`)

- **Composition**
- `GCS` composes/uses `GCI` rather than duplicating math.

- **Stateful computation with invalidation**
- `GCI` supports setters/getters and recomputes when stale (`gci_up_to_date` concept from README).

- **Sliding-window strategy for N-grid studies**
- Multi-grid studies decomposed into multiple 3-grid GCI computations.

- **Strategy-like output selection**

##### Don’t overthink it: split into as many components as possible (but still true)
- `GCS`:
- Input normalization/validation
- Grid-window iterator (N-grids → triples)
- Result aggregation
- Output selection + writers (3 writers)
- `GCI`:
- Input storage
- Apparent order iterative solver
- Refinement ratio computation
- Relative error computation
- GCI computation + safety factor
- Oberkampf-Roy correction path
- Extrapolation computation
- Getter/setter + stale-flag logic

Even if these are all in one file/class, diagramming them as subcomponents is still accurate as an *architectural view* because they are real responsibilities and change points.

“pyGCS Library Architecture: High-level Grid Convergence Study (GCS) orchestrating Low-level GCI Computation (GCI) and Rendering Outputs”

That title matches the README’s intent and the code layout.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% Diagram 1: Runtime / Usage Data-Flow (Library Architecture)
    %% =========================================================

    subgraph "Runtime / Usage Data-Flow"
        direction TB

        User["User / Client Code\n(notebook, scripts, CFD/FEA pipeline)"]:::actor

        subgraph "pyGCS Public API"
            direction TB
            API["pyGCS package\n(import surface)"]:::pkg
            GCS["GCS (High-level)\nGrid Study Orchestrator + Presentation"]:::module
            GCI["GCI (Low-level)\nComputation Kernel"]:::module
        end

        subgraph "GCS internals (responsibilities)"
            direction TB
            GCSValidate["Input normalization + validation\n(dimension, order, cells[], solution[], volume|grid_size)"]:::process
            GCSWindow["3-grid window iterator\n(N grids → successive triples)"]:::process
            GCSAggregate["Aggregate results\n(across windows)"]:::process
            GCSOutputSelect["Output selection\n(output_type)"]:::process

            subgraph "Table Renderers / Writers"
                direction TB
                RendMD["Markdown table writer"]:::renderer
                RendTeX["LaTeX table writer"]:::renderer
                RendWord["Word-friendly table writer\n(tab-separated text)"]:::renderer
            end
        end

        subgraph "GCI internals (responsibilities)"
            direction TB
            GCIState["Input storage + state\n(set/get)"]:::process
            GCIStale["Stale-flag invalidation\n(set(...) → mark stale)\nget(...) → recompute if stale"]:::process
            GCIRefine["Refinement ratio computation"]:::process
            GCIOrder["Apparent order solver\n(iterative)"]:::process
            GCIError["Relative error computation"]:::process
            GCIGCICalc["GCI computation\n(+ safety factor)"]:::process
            GCIOber["Optional Oberkampf-Roy correction\n(when enabled)"]:::process
            GCIExtrap["Extrapolation computation\n(phi_extrapolated)"]:::process
            GCIOutputs["Derived outputs\n(gci, asymptotic_gci, p,\nrefinement_ratio, extrapolated_value, ...)"]:::data
        end

        subgraph "Output Artifacts (files)"
            direction TB
            OutMD["table.md"]:::doc
            OutTeX["table.tex"]:::doc
            OutTXT["table.txt"]:::doc
        end

        %% --- User interactions ---
        User -->|"import: GCS,GCI"| API
        API -->|"exposes"| GCS
        API -->|"exposes"| GCI

        User -->|"construct(GCS): dimension,simulation_order,cells[],solution[],volume|grid_size,oberkampf_correction"| GCS
        User -->|"construct(GCI): dimension,simulation_order,cells,solution,volume|grid_size,oberkampf_correction"| GCI

        User -->|"set(key,value) → invalidate"| GCIState
        User -->|"get(metric) → triggers recompute if stale"| GCIStale

        %% --- GCS orchestration ---
        GCS -->|"normalize/validate inputs"| GCSValidate
        GCSValidate -->|"prepare arrays for N≥3 grids"| GCSWindow
        GCSWindow -->|"for each 3-grid triple: create/use GCI"| GCI
        GCI -->|"compute: gci,p,asymptotic_gci,phi_extrapolated"| GCSAggregate
        GCSAggregate -->|"render_table(output_type)"| GCSOutputSelect

        GCSOutputSelect -->|"markdown"| RendMD
        GCSOutputSelect -->|"latex"| RendTeX
        GCSOutputSelect -->|"word"| RendWord

        RendMD -.->|"write artifact"| OutMD
        RendTeX -.->|"write artifact"| OutTeX
        RendWord -.->|"write artifact"| OutTXT

        %% --- GCI kernel dataflow ---
        GCI -->|"stores inputs"| GCIState
        GCIState -->|"get(...) checks stale"| GCIStale
        GCIStale -->|"recompute pipeline"| GCIRefine
        GCIRefine -->|"feeds"| GCIOrder
        GCIOrder -->|"feeds"| GCIError
        GCIError -->|"feeds"| GCIGCICalc
        GCIGCICalc -->|"optional correction"| GCIOber
        GCIOber -->|"feeds"| GCIExtrap
        GCIExtrap -->|"publish metrics"| GCIOutputs
        GCIOutputs -->|"returned via get(...)"| User
    end

    %% =========================================================
    %% Diagram 2: Repo / Module Boundaries (Codebase Architecture)
    %% =========================================================

    subgraph "Repository / Module Boundaries"
        direction TB

        subgraph "Source (runtime code)"
            direction TB
            SRCROOT["src/pyGCS/"]:::folder
            INIT["__init__.py\n(exports public API)"]:::file
            MODGCS["GCS.py\n(orchestrator + presentation)"]:::file
            MODGCI["GCI.py\n(computation kernel)"]:::file
        end

        subgraph "Tests (quality)"
            direction TB
            TINIT["tests/__init__.py"]:::testfile
            TGCI["tests/test_GCI.py"]:::testfile
            TGCS["tests/test_GCS.py"]:::testfile
        end

        subgraph "Packaging / Distribution"
            direction TB
            PYPROJ["pyproject.toml"]:::meta
            SETUPPY["setup.py"]:::meta
            SETUPCFG["setup.cfg"]:::meta
            DIST["PyPI Distribution Artifact\n(wheel/sdist)"]:::artifact
        end

        subgraph "Documentation"
            direction TB
            README["README.md\n(usage + architecture)"]:::docfile
            IMAGES["images/"]:::folder
        end

        %% --- Static dependencies ---
        SRCROOT -->|"contains"| INIT
        SRCROOT -->|"contains"| MODGCS
        SRCROOT -->|"contains"| MODGCI

        INIT -->|"exports"| MODGCS
        INIT -->|"exports"| MODGCI
        MODGCS -->|"imports/uses"| MODGCI

        TGCI -->|"imports/tests"| MODGCI
        TGCS -->|"imports/tests"| MODGCS
        TINIT -->|"enables test discovery"| TGCI
        TINIT -->|"enables test discovery"| TGCS

        PYPROJ -->|"build metadata"| DIST
        SETUPPY -->|"build metadata"| DIST
        SETUPCFG -->|"build metadata"| DIST

        README -->|"documents API & examples"| INIT
        IMAGES -->|"referenced by"| README
    end

    %% =========================================================
    %% Click events (from component_mapping)
    %% =========================================================
    click API "https://github.com/tomrobin-teschner/pygcs/blob/development/src/pyGCS/__init__.py"
    click GCS "https://github.com/tomrobin-teschner/pygcs/blob/development/src/pyGCS/GCS.py"
    click GCI "https://github.com/tomrobin-teschner/pygcs/blob/development/src/pyGCS/GCI.py"

    click SRCROOT "https://github.com/tomrobin-teschner/pygcs/tree/development/src/pyGCS/"
    click INIT "https://github.com/tomrobin-teschner/pygcs/blob/development/src/pyGCS/__init__.py"
    click MODGCS "https://github.com/tomrobin-teschner/pygcs/blob/development/src/pyGCS/GCS.py"
    click MODGCI "https://github.com/tomrobin-teschner/pygcs/blob/development/src/pyGCS/GCI.py"

    click TGCI "https://github.com/tomrobin-teschner/pygcs/blob/development/tests/test_GCI.py"
    click TGCS "https://github.com/tomrobin-teschner/pygcs/blob/development/tests/test_GCS.py"
    click TINIT "https://github.com/tomrobin-teschner/pygcs/blob/development/tests/__init__.py"

    click PYPROJ "https://github.com/tomrobin-teschner/pygcs/blob/development/pyproject.toml"
    click SETUPPY "https://github.com/tomrobin-teschner/pygcs/blob/development/setup.py"
    click SETUPCFG "https://github.com/tomrobin-teschner/pygcs/blob/development/setup.cfg"

    click README "https://github.com/tomrobin-teschner/pygcs/blob/development/README.md"
    click IMAGES "https://github.com/tomrobin-teschner/pygcs/tree/development/images/"

    %% =========================================================
    %% Styles (color is critical)
    %% =========================================================
    classDef actor fill:#2ecc71,stroke:#1e8449,stroke-width:2px,color:#0b2e13
    classDef pkg fill:#74b9ff,stroke:#2d6cdf,stroke-width:2px,color:#0b1b3a
    classDef module fill:#4aa3ff,stroke:#1f5aa6,stroke-width:2px,color:#06213f
    classDef process fill:#dfe6e9,stroke:#636e72,stroke-width:1.5px,color:#2d3436
    classDef renderer fill:#f8c291,stroke:#e67e22,stroke-width:2px,color:#4a2a00
    classDef data fill:#c8f7c5,stroke:#27ae60,stroke-width:1.5px,color:#0f2d16
    classDef doc fill:#ffffff,stroke:#2d3436,stroke-width:1.5px,color:#2d3436
    classDef folder fill:#b2bec3,stroke:#2d3436,stroke-width:1.5px,color:#2d3436
    classDef file fill:#a9d6ff,stroke:#1f5aa6,stroke-width:1.5px,color:#06213f
    classDef testfile fill:#d6c2ff,stroke:#6c5ce7,stroke-width:2px,color:#1f1247
    classDef meta fill:#caa6ff,stroke:#8e44ad,stroke-width:2px,color:#1f0d2b
    classDef artifact fill:#b388ff,stroke:#5e35b1,stroke-width:2px,color:#160a2a
    classDef docfile fill:#fff3cd,stroke:#b8860b,stroke-width:2px,color:#3d2f00
```
