# fusioncomputinglab/freegsnke architecture

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

- Interactive diagram: https://gitdiagram.com/fusioncomputinglab/freegsnke
- Repository: https://github.com/fusioncomputinglab/freegsnke

## Overview

##### Project Type and Purpose
- FreeGSNKE is an **open-source scientific Python library** for **simulating free-boundary tokamak plasma equilibria**.
- It provides **static** and **evolutive** Grad–Shafranov solvers, building on FreeGS/FreeGS4E, and includes examples, documentation, and CI/CD pipelines.

##### File Structure
- Top-level directories:
- `.github/` → CI/CD workflows and custom GitHub Actions
- `docs/` → Sphinx documentation source and build scripts
- `examples/` → Jupyter notebooks demonstrating API usage
- `freegsnke/` → core Python package modules and unit tests
- `machine_configs/` → pickled tokamak geometry datasets
- Key files:
- `pyproject.toml`, `requirements*.txt` → packaging & dependencies
- `README.md` → high-level project overview
- `.gitlab-ci.yml` plus GitHub workflows → multi-platform CI/CD
- Architectural indications:
- Modular Python package (`freegsnke/` subdivided by solver functionality)
- Data assets separated (`machine_configs/`)
- Documentation and examples decoupled from core code

##### README for Additional Insights
- Core functionality: static forward/inverse and evolutive solvers
- External integrations: FreeGS4E, optionally UDA, JAX on the roadmap
- CI/CD: tests via pytest, docs publishing, PyPI release

a. Main Components
1. User Interface
- Python API (import freegsnke)
- Jupyter notebooks in `examples/`
2. Core Library (`freegsnke/`)
- Solver modules (e.g., GSstaticsolver.py, implicit_euler.py, nonlinear_solve.py)
- Builder/Update modules (e.g., build_machine.py, equilibrium_update.py)
- Configuration loaders (`machine_config.py`)
3. Data Assets (`machine_configs/`)
- Tokamak geometries (active coils, passive coils, limiters, probes, walls)
4. External Dependencies
- FreeGS4E solver
- NumPy, SciPy, PyTest
- Optional JAX, UDA
5. Documentation Pipeline (`docs/`)
- Sphinx sources, build scripts
6. CI/CD Infrastructure (`.github/`, `.gitlab-ci.yml`)
- Linting & formatting (pre-commit, black, isort)
- Testing (pytest workflows)
- Docs build & deploy
- PyPI publishing

b. Relationships & Interactions
- User calls Python API → core library loads machine configurations → invokes solver modules → may delegate lower-level routines to FreeGS4E → results returned to user (arrays, plots).
- Examples reference both API and `machine_configs/` → demonstrate typical workflows.
- Docs pipeline reads Python source & example notebooks → generates HTML docs.
- CI/CD pipelines run tests on core library, validate docs builds, enforce code style, and publish package.

c. Architectural Patterns & Design Principles
- **Modular Package**: clear separation between solver logic, configuration management, and utilities.
- **Separation of Concerns**: data assets (machine_configs) are decoupled from code.
- **Dependency Injection**: external solver implementations (FreeGS4E, UDA) loaded via extras.
- **CI/CD as Code**: workflows defined in YAML to ensure reproducibility.
- **Documentation-as-Code**: Sphinx + examples drive user guide.

d. Key Technologies & Frameworks
- Python 3.10+, NumPy, SciPy
- FreeGS4E (external equilibrium solver)
- Jupyter Notebooks (examples)
- Sphinx (docs)
- PyTest (testing)
- pre-commit (Black, isort)
- GitHub Actions / GitLab CI
- pip/conda for packaging & installation

##### Elements
- **Clear Labels**: name each module/directory (e.g., “freegsnke.solver”, “machine_configs”).
- User → API → Solver Modules → FreeGS4E → Results
- Code → CI/CD Workflows → PyPI
- Code & Examples → Docs Generator → HTML Site
- Core components (rectangles, e.g., blue)
- External dependencies (ovals, e.g., gray)
- CI/CD & Docs pipelines (parallelograms, e.g., orange)

##### Final Advice
- Essential elements: API entry points, solver core, data files, external libs, pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    subgraph "User Interface" 
        API["Python API Entry\n(freegsnke/__init__.py)"]:::ui
        Examples["Jupyter Notebooks\n(examples/)"]:::ui
    end

    %% Core Library
    subgraph "Core Library" 
        subgraph "Static Solver Modules"
            GSstaticsolver["GSstaticsolver.py"]:::core
            inverse["inverse.py"]:::core
            simplified_solve["simplified_solve.py"]:::core
        end
        subgraph "Evolutive Solver Modules"
            implicit_euler["implicit_euler.py"]:::core
            equilibrium_update["equilibrium_update.py"]:::core
            nonlinear_solve["nonlinear_solve.py"]:::core
            jtor_refinement["jtor_refinement.py"]:::core
            jtor_update["jtor_update.py"]:::core
        end
        subgraph "Machine Builder & Updater"
            build_machine["build_machine.py"]:::core
            Myy_builder["Myy_builder.py"]:::core
            machine_config["machine_config.py"]:::core
            machine_update["machine_update.py"]:::core
        end
        subgraph "Auxiliary Physics Modules"
            circuit_eq_plasma["circuit_eq_plasma.py"]:::core
            circuit_eq_metal["circuit_eq_metal.py"]:::core
            magnetic_probes["magnetic_probes.py"]:::core
            passive_structure["passive_structure.py"]:::core
            refine_passive["refine_passive.py"]:::core
            limiter_func["limiter_func.py"]:::core
            normal_modes["normal_modes.py"]:::core
            virtual_circuits["virtual_circuits.py"]:::core
            switch_profile["switch_profile.py"]:::core
        end
        subgraph "Linear Solvers & Tools"
            linear_solve["linear_solve.py"]:::core
            nk_solver_H["nk_solver_H.py"]:::core
            mastu_tools["mastu_tools.py"]:::core
        end
        subgraph "Unit Tests"
            tests["tests/"]:::tests
        end
    end

    %% Data Assets
    Data["Tokamak Geometry Datasets\n(machine_configs/)"]:::data

    %% External Dependencies
    subgraph "External Dependencies"
        FreeGS4E("FreeGS4E Solver"):::external
        NumPy("NumPy & SciPy"):::external
        PyTest("PyTest"):::external
        JAX("JAX (Optional)"):::externalDashed
        UDA("UDA (Optional)"):::externalDashed
    end

    %% Documentation Pipeline
    Docs["Sphinx Docs Pipeline\n(docs/)"]:::pipeline

    %% CI/CD Infrastructure
    subgraph "CI/CD Infrastructure"
        GitHubActions["GitHub Actions\n(.github/)"]:::pipeline
        GitLabCI["GitLab CI\n(.gitlab-ci.yml)"]:::pipeline
    end

    %% Packaging & Dependencies
    subgraph "Packaging & Metadata"
        PyProject["pyproject.toml"]:::packaging
        Requirements["requirements.txt"]:::packaging
        ReqFreeGS4E["requirements-freegs4e.txt"]:::packaging
        ReqUDA["requirements-uda.txt"]:::packaging
        README["README.md & LICENSE"]:::packaging
    end

    %% Relationships
    API -->|"imports modules of"| GSstaticsolver
    API --> implicit_euler
    API --> build_machine
    API --> machine_config
    API --> linear_solve

    API --> Data
    Examples --> API
    Examples --> Data

    GSstaticsolver --> FreeGS4E
    equilibrium_update --> FreeGS4E
    implicit_euler --> nonlinear_solve
    nonlinear_solve --> FreeGS4E

    API --> Docs
    Examples --> Docs
    Docs -->|"generates HTML"| docsSite["HTML Site"]:::external

    GitHubActions --> tests
    GitHubActions --> Docs
    GitHubActions --> PyProject
    GitLabCI --> tests
    GitLabCI --> Docs
    GitLabCI --> PyProject

    tests --> PyTest
    build_machine --> Data
    machine_config --> Data
    GSstaticsolver --> NumPy
    implicit_euler --> SciPy["SciPy"]:::external

    %% Click Events
    click API "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/__init__.py"
    click Examples "https://github.com/fusioncomputinglab/freegsnke/tree/main/examples/"
    click GSstaticsolver "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/GSstaticsolver.py"
    click inverse "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/inverse.py"
    click simplified_solve "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/simplified_solve.py"
    click implicit_euler "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/implicit_euler.py"
    click equilibrium_update "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/equilibrium_update.py"
    click nonlinear_solve "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/nonlinear_solve.py"
    click jtor_refinement "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/jtor_refinement.py"
    click jtor_update "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/jtor_update.py"
    click build_machine "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/build_machine.py"
    click Myy_builder "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/Myy_builder.py"
    click machine_config "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/machine_config.py"
    click machine_update "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/machine_update.py"
    click circuit_eq_plasma "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/circuit_eq_plasma.py"
    click circuit_eq_metal "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/circuit_eq_metal.py"
    click magnetic_probes "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/magnetic_probes.py"
    click passive_structure "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/passive_structure.py"
    click refine_passive "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/refine_passive.py"
    click limiter_func "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/limiter_func.py"
    click normal_modes "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/normal_modes.py"
    click virtual_circuits "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/virtual_circuits.py"
    click switch_profile "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/switch_profile.py"
    click linear_solve "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/linear_solve.py"
    click nk_solver_H "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/nk_solver_H.py"
    click mastu_tools "https://github.com/fusioncomputinglab/freegsnke/blob/main/freegsnke/mastu_tools.py"
    click tests "https://github.com/fusioncomputinglab/freegsnke/tree/main/freegsnke/tests/"
    click Data "https://github.com/fusioncomputinglab/freegsnke/tree/main/machine_configs/"
    click Docs "https://github.com/fusioncomputinglab/freegsnke/tree/main/docs/"
    click GitHubActions "https://github.com/fusioncomputinglab/freegsnke/tree/main/.github/"
    click GitLabCI "https://github.com/fusioncomputinglab/freegsnke/blob/main/.gitlab-ci.yml"
    click PyProject "https://github.com/fusioncomputinglab/freegsnke/blob/main/pyproject.toml"
    click Requirements "https://github.com/fusioncomputinglab/freegsnke/blob/main/requirements.txt"
    click ReqFreeGS4E "https://github.com/fusioncomputinglab/freegsnke/blob/main/requirements-freegs4e.txt"
    click ReqUDA "https://github.com/fusioncomputinglab/freegsnke/blob/main/requirements-uda.txt"
    click README "https://github.com/fusioncomputinglab/freegsnke/blob/main/README.md"
    click docsSite "https://github.com/fusioncomputinglab/freegsnke/tree/main/docs/"

    %% Styles
    classDef ui fill:#D0E6F6,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E8F1FF,stroke:#1F78B4,color:#1F78B4;
    classDef data fill:#E6F4EA,stroke:#34A853,color:#34A853;
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555;
    classDef externalDashed fill:#F0F0F0,stroke:#888888,color:#555555,stroke-dasharray: 5 5;
    classDef pipeline fill:#FFF4E5,stroke:#FB8C00,color:#FB8C00;
    classDef packaging fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA;
    classDef tests fill:#F5F5F5,stroke:#9E9E9E,color:#757575;
```
