How fusioncomputinglab/freegsnke works
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.