How tomrobin-teschner/pygcs works
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.