Skip to content

Issue #33: add executable onboarding and smoke-test scripts for the core repo #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
01stamat wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Issue #33: add executable onboarding and smoke-test scripts for the core repo #34

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2352fa4
Added example target to Makefile
01stamat Apr 10, 2026
57281b1
moved example section above usage and tutorial sections
01stamat Apr 13, 2026
418eb15
fixed path to executable
01stamat Apr 13, 2026
4669a62
added expected-output validation
01stamat Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ CONFIG ?= Release
BUILD_DIR := BUILD
BUILD_NINJA := $(BUILD_DIR)/build.ninja

.PHONY: all configure reconfigure build test install clean

.PHONY: all configure reconfigure build test install clean example
all: build

$(BUILD_NINJA):
Expand All @@ -23,4 +24,12 @@ doc: configure
cmake --build --preset default --target doc

clean:
rm -rf $(BUILD_DIR)
rm -rf $(BUILD_DIR)

example: build
@if [ -z "$(EXAMPLE)" ]; then \
echo "Usage: make example EXAMPLE=<number>"; \
echo "Example: make example EXAMPLE=1"; \
exit 1; \
fi
bash run_example.sh $(EXAMPLE)
8 changes: 4 additions & 4 deletions PYTHON/plotting_tutorial.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"source": [
"With the plotting option of GORILLA it is possible to compute and plot the orbit of a particle in a toroidal magnetic fusion device. For the visualization of the orbit, Poincare plots are used. The program also computes various constants of motion to check how the obtained results behave with respect to numerical accuracy. \n",
"\n",
"This tutorial guides through different input options of the code and shows a way how to execute the code with PYTHON. In principle one could change the repective options in the namelist-files like `gorilla.inp` or `tetra_grid.inp` per hand and then start the main executable `test_gorilla-main.x`. However, here we will show how one can instead control these options dynamically in a PYTHON script using the the *f90nml*-namelist package."
"This tutorial guides through different input options of the code and shows a way how to execute the code with PYTHON. In principle one could change the repective options in the namelist-files like `gorilla.inp` or `tetra_grid.inp` per hand and then start the main executable `test_gorilla_main.x`. However, here we will show how one can instead control these options dynamically in a PYTHON script using the the *f90nml*-namelist package."
]
},
{
Expand All @@ -29,7 +29,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"First we load the *f90nml* package after installing it e.g. using pip. Additionally we load the default module *os* (this is used to execute shell commands in PYTHON such as getting the current working directory path, creating folders and starting the main executable of GORILLA). We want to note that the default module *subprocess* is general considered preferable to *os*. However, for our very limited interaction with the operating system, *os* completly suffices."
"First we load the *f90nml* package after installing it e.g. using pip. Additionally we load the default module *os* (this is used to execute shell commands in PYTHON such as getting the current working directory path, creating folders and starting the main executable of GORILLA). We want to note that the default module *subprocess* is general considered preferable to *os*. However, for our very limited interaction with the operating system, *os* completely suffices."
]
},
{
Expand Down Expand Up @@ -2085,8 +2085,8 @@
"source": [
"if os.path.exists(path_main + '/test_gorilla_main.x'):\n",
" os.system('ln -s ../../../test_gorilla_main.x .')\n",
"elif os.path.exists(path_main + '/BUILD/SRC/test_gorilla_main.x'):\n",
" os.system('ln -s ../../../BUILD/SRC/test_gorilla_main.x .') \n",
"elif os.path.exists(path_main + '/BUILD/test_gorilla_main.x'):\n",
" os.system('ln -s ../../../BUILD/test_gorilla_main.x .') \n",
"else:\n",
" print('GORILLA not built, exiting the PYTHON script')\n",
" raise SystemExit(0)\n",
Expand Down
89 changes: 46 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,52 +109,13 @@ This will produce `test_gorilla_main.x` in the folder BUILD/SRC/ required to run

To get additional tests and code coverage, build GORILLA with `build_coverage.sh`. This requires the additional tools and a correct set PFUNIT_DIR. See the pFUnit github [project page](https://github.com/Goddard-Fortran-Ecosystem/pFUnit) for additional information.

## Examples

## Usage

GORILLA currently runs on a single node with OpenMP shared memory parallelization with one particle per thread and background fields residing in main memory.

The main executable is `test_gorilla_main.x`.
As an input it takes ....

... the following input files which can be found in the folder `INPUT/`
* `tetra_grid.inp` (Input file for settings of the tetrahedronal grid used in GORLLA)
* `gorilla.inp` (Input file for settings of GORILLA)
* `gorilla_plot.inp` (Input file for the program for the analysis of guiding-center orbits)
* `field_divB0.inp` (Input file for loading g-file equilibria - Do not change this file.)
* `preload_for_SYNCH.inp` (Input file for splining magnetic field data of g-file equilibria - Do not change this file.)

... and the MHD equilibrium files which can be found in the folder `MHD_EQUILIBRIA/`
* `netcdf_file_for_test.nc`: VMEC NetCDF equlibrium (File name can be specified in `tetra_grid.inp`.)
* `g_file_for_test` or `g_file_for_test_WEST`: g-file equilibrium (File name can be specified in `tetra_grid.inp`.)

For compability with WEST geometry of SOLEDGE3X-EIRENE, additional input files describing the original 2D mesh are needed. Those can be found in `MHD_EQUILIBRIA/MESH_SOLEDGE3X_EIRENE`

* `knots_for_test.dat`: coordinates ($R$, $Z$) of the vertices making up the 2D grid (File name can be specified in `tetra_grid.inp`.)
* `triangles_for_test.dat`: association of above mentioned vertices to triangles (triples of vertices) covering the 2D plane (File name can be specified in `tetra_grid.inp`.)

To produce these files (including the g-file equilibrium) oneself from files provided by SOLEDGE3X-EIRENE, a set of prepocessing MATLAB scripts are at disposal in `REPROCESSING/SOLEDGE3X_EIRENE/MESH` and `REPROCESSING/SOLEDGE3X_EIRENE/MHD_EQUILIBRIUM` respectively.

## Tutorial

A tutorial for running GORILLA and plotting Poincaré cuts, full guiding-center orbits and the appropriate time evolution of invariants of motion is realized redundantly in both MATLAB and Python.

### Step-by-step plotting tutorial in MATLAB
* MATLAB Live Script with the name `plotting_tutorial.mlx` is at disposal in `MATLAB` as a step-by-step tutorial for all plotting features of GORILLA.

### Step-by-step plotting tutorial in Python
* Jupyter Notebook with the name `plotting_tutorial.ipynb` is at disposal in `PYTHON` as a step-by-step tutorial for all plotting features of GORILLA.

For the Jupyter Notebook as well as the Python scripts used for the examples, some Python packages are needed, including the fortran namelist package [f90nml](https://github.com/marshallward/f90nml). To install the necessary packages use for example [pip](https://pip.pypa.io/en/stable/).
Seven examples for plotting Poincaré cuts, full guiding-center orbits (in plasma core or edge regions) and the appropriate time evolution of invariants of motion can be found in `EXAMPLES/example_1` - `EXAMPLES/example_7`. Further details on usage of GORILLA and plotting results follow below. To automatically build GORILLA, run one of the examples and plot the results from GORILLA root directory using make, use
```
python -m pip install --upgrade pip
pip install f90nml numpy matplotlib
make example EXAMPLE=<example number>
```
However, GORILLA itself can be run without these packages. They are only used to incorporate GORILLA properly into Python scripts.

## Examples

Seven examples for plotting Poincaré cuts, full guiding-center orbits (in plasma core or edge regions) and the appropriate time evolution of invariants of motion can be found in `EXAMPLES/example_1` - `EXAMPLES/example_7`. There, the necessary soft links are already created and the input files are given, and runs are started with
For manual execution, the necessary soft links are already created and the input files are given in `EXAMPLES/example_1` - `EXAMPLES/example_7` and runs are started with
```
./test_gorilla_main.x #if the build was done with make
```
Expand Down Expand Up @@ -223,6 +184,48 @@ A detailed explanation of all examples (1-7) including the generation of the app
Here, the results of GORILLA with different polynominal orders K=2,3,4 and Runge-Kutta 4 are compared in case of examples 1-3. For examples 5-6 orbits for both trapped and passing particles are calculated. For example 7 an additional, in-depth comparison between adaptive and non-adaptive scheme is performed. The last example, example 8, is currently only available via the MATLAB script `example_8.m`. A redundant version in PYTHON, as well as a corresponding example-folder with an appropriate script for plotting will follow in the future.


## Usage

GORILLA currently runs on a single node with OpenMP shared memory parallelization with one particle per thread and background fields residing in main memory.

The main executable is `test_gorilla_main.x`.
As an input it takes ....

... the following input files which can be found in the folder `INPUT/`
* `tetra_grid.inp` (Input file for settings of the tetrahedronal grid used in GORLLA)
* `gorilla.inp` (Input file for settings of GORILLA)
* `gorilla_plot.inp` (Input file for the program for the analysis of guiding-center orbits)
* `field_divB0.inp` (Input file for loading g-file equilibria - Do not change this file.)
* `preload_for_SYNCH.inp` (Input file for splining magnetic field data of g-file equilibria - Do not change this file.)

... and the MHD equilibrium files which can be found in the folder `MHD_EQUILIBRIA/`
* `netcdf_file_for_test.nc`: VMEC NetCDF equlibrium (File name can be specified in `tetra_grid.inp`.)
* `g_file_for_test` or `g_file_for_test_WEST`: g-file equilibrium (File name can be specified in `tetra_grid.inp`.)

For compability with WEST geometry of SOLEDGE3X-EIRENE, additional input files describing the original 2D mesh are needed. Those can be found in `MHD_EQUILIBRIA/MESH_SOLEDGE3X_EIRENE`

* `knots_for_test.dat`: coordinates ($R$, $Z$) of the vertices making up the 2D grid (File name can be specified in `tetra_grid.inp`.)
* `triangles_for_test.dat`: association of above mentioned vertices to triangles (triples of vertices) covering the 2D plane (File name can be specified in `tetra_grid.inp`.)

To produce these files (including the g-file equilibrium) oneself from files provided by SOLEDGE3X-EIRENE, a set of prepocessing MATLAB scripts are at disposal in `PREPROCESSING/SOLEDGE3X_EIRENE/MESH` and `PREPROCESSING/SOLEDGE3X_EIRENE/MHD_EQUILIBRIUM` respectively.

## Tutorial

A tutorial for running GORILLA and plotting Poincaré cuts, full guiding-center orbits and the appropriate time evolution of invariants of motion is realized redundantly in both MATLAB and Python.

### Step-by-step plotting tutorial in MATLAB
* MATLAB Live Script with the name `plotting_tutorial.mlx` is at disposal in `MATLAB` as a step-by-step tutorial for all plotting features of GORILLA.

### Step-by-step plotting tutorial in Python
* Jupyter Notebook with the name `plotting_tutorial.ipynb` is at disposal in `PYTHON` as a step-by-step tutorial for all plotting features of GORILLA.

For the Jupyter Notebook as well as the Python scripts used for the examples, some Python packages are needed, including the fortran namelist package [f90nml](https://github.com/marshallward/f90nml). To install the necessary packages use for example [pip](https://pip.pypa.io/en/stable/).
```
python -m pip install --upgrade pip
pip install f90nml numpy matplotlib
```
However, GORILLA itself can be run without these packages. They are only used to incorporate GORILLA properly into Python scripts.

## Tests and coverage

Tests are implemented with pFUnit. The generation of coverage files are done with the compiler option `--coverage` and the evaluation of the files is implemented with lcov. To see the coverage report, build with `build_coverage.sh` and open `index.html` in the folder /BUILD/COVERAGE or take a look in the github workflows `Ubuntu` or `Mac`.
Expand Down
40 changes: 40 additions & 0 deletions run_example.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
#!/bin/bash

# Script to run a GORILLA example
# Usage: ./run_example.sh <example_number>

Copy link
Copy Markdown

@qodo-code-review qodo-code-review Bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

3. Runner not under scripts/ 📎 Requirement gap ⚙ Maintainability

The added smoke-test runner is placed at repo root (run_example.sh) rather than under EXAMPLES/
or scripts/ as required. This does not meet the checklist’s location requirement for repo-native
smoke-test runners.
Agent Prompt 
## Issue description
The smoke-test/onboarding runner script is not located under `EXAMPLES/` or `scripts/`.

## Issue Context
The compliance checklist explicitly requires one or two smoke-test runners to live under `EXAMPLES/` or `scripts/`.

## Fix Focus Areas
- run_example.sh[1-40]
- Makefile[29-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

if [ -z "$1" ]; then
echo "Usage: $0 <example_number>"
echo "Example: $0 1"
exit 1
fi

EXAMPLE_NUM=$1
EXAMPLE_DIR="EXAMPLES/example_$EXAMPLE_NUM"

# Check if example directory exists
if [ ! -d "$EXAMPLE_DIR" ]; then
echo "Error: $EXAMPLE_DIR does not exist"
exit 1
fi

# Check if executable exists
if [ ! -f "BUILD/test_gorilla_main.x" ]; then
echo "Error: Executable BUILD/SRC/test_gorilla_main.x not found. Please run 'make build' first."
exit 1
fi

echo "Running example $EXAMPLE_NUM from $EXAMPLE_DIR"
cd "$EXAMPLE_DIR"
./test_gorilla_main.x

Copy link
Copy Markdown

@qodo-code-review qodo-code-review Bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. run_example.sh runs wrong binary 📎 Requirement gap ☼ Reliability

The script checks for BUILD/test_gorilla_main.x but then executes ./test_gorilla_main.x inside
the example directory without creating/linking it, so the documented make example EXAMPLE=<n>
bootstrap is likely to fail from a clean checkout. This violates the requirement that the single
entrypoint builds and runs an example to completion.
Agent Prompt 
## Issue description
`run_example.sh` checks for `BUILD/test_gorilla_main.x` but then runs `./test_gorilla_main.x` within the example directory without ensuring that file exists.

## Issue Context
The README documents `make example EXAMPLE=<n>` as an onboarding bootstrap command, and the Makefile calls `bash run_example.sh $(EXAMPLE)`. For a clean checkout, the script must run the built executable reliably.

## Fix Focus Areas
- run_example.sh[21-36]
- Makefile[29-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

if [ $? -eq 0 ]; then
echo "Example $EXAMPLE_NUM completed successfully"
else
echo "Error: Example $EXAMPLE_NUM failed"
exit 1
fi

echo "Plotting results for example $EXAMPLE_NUM from $EXAMPLE_DIR"
cd ../../PYTHON
python3 plot_example_$EXAMPLE_NUM.py
Copy link
Copy Markdown

@qodo-code-review qodo-code-review Bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

2. No expected-output validation 📎 Requirement gap ☼ Reliability

run_example.sh does not check for expected orbit/output artifacts after the example run (or after
plotting), so it can report success without verifying outputs exist. This violates the requirement
that onboarding/smoke-test entrypoints explicitly detect missing outputs and fail nonzero.
Agent Prompt 
## Issue description
The new onboarding runner does not validate that the example produced the expected output files/artifacts, and the plotting step is not producing a deterministic artifact that can be checked.

## Issue Context
Compliance requires deterministic, self-checking smoke-test behavior that fails nonzero when outputs are missing. The current runner only checks the executable exit code and then launches interactive plotting.

## Fix Focus Areas
- run_example.sh[27-40]
- PYTHON/plot_example_1.py[20-56]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Loading