CQL3DUI 0.0.10

A small UI for running CQL3D

CQL3DUI

A simple user-interface for the Bounce-Averaged Fokker-Planck code CQL3D.

Author: Matthew Poulos (CompX) Email: [e-mail]

---

Overview

CQL3DUI is a simple Python/Tkinter-based GUI for the Fortran-based code CQL3D. The interface allows users to:

1. Import, export, view, and edit cqlinput files (Fortran namelists).
2. Compile, load and run CQL3D executables.
3. Plot and visualize the resulting output (NetCDF) from CQL3D.

Detailed information and documentation on CQL3D can be found at:

• GitHub Repository
• CompX Website

---

Installation

To install CQL3DUI, open a terminal and run:

pip install cql3dui

To run CQL3DUI, simply type:

cqlui

---

Compiling CQL3D

Prerequisite: You must have NetCDF, PGPLOT, and gfortran downloaded and installed.

Click the button labeled Compile CQL3D located in the lower left corner of the UI. A new interface called CQL3D Compiler will pop up. The interface will attempt to automatically detect the necessary NetCDF library and PGPLOT path. It will indicate if these files are successfully found in the Compilation Output. Click the button GENERATE MAKEFILE & COMPILE and the UI will automatically create a makefile and attemt to compile CQL3D using gfortran. A message box will appear indicating successful compilation. Once CQL3D is successfully compiled, exit the CQL3D Compiler interface to return to the main UI.

Optional: To load a pre-compiled CQL3D executable, click the button labeled Load Exec.

---

Running Example Tests

A set of example tests are provided in the package contents. On initial startup, the UI will automatically load with the namelist for Test 1.0 loaded and will automatically point to the correct auxiliary file folder to run all of the provided test cases.

---

Workflow

1. Import, View, and Edit Namelists

To import a test case, click the Import Namelist button in the top left of the UI and select any of the test files.

Editing Features:

• Navigation: Use the GUI tabs to navigate through the file.
• Documentation: Click on any variable to highlight it within the cqlinput_help documentation (displayed in the right panel).
• Tooltips: Hover the cursor over any namelist variable to see a short description.
• Export: Click Export Namelist to save the variables currently in the UI to a cqlinput (fortran namelist) file.

Keyboard Shortcuts:

Shortcut	Action
Up / Down	Move between variables in the left panel.
Ctrl + Left / Right	Move between GUI tabs (Windows/Linux).
Cmd + Left / Right	Move between GUI tabs (macOS).
Shift + Left / Right	Move between instances of the highlighted variable in the help documentation.

2. Run CQL3D

Click the Run CQL3D button.

• A runs folder is created in the current directory where the ui was launched from.
• A subfolder labeled by the date and time is created inside runs.
• The current namelist variables are saved to a cqlinput file inside that subfolder.
• File Linking: The code checks if auxiliary files (eqdsk, rffile, etc.) are required.
  • It looks in the chosen auxiliary file folder for these files
  • If found, it creates symbolic links in the newly created run folder to the required files.
• A separate thread is launched to execute CQL3D.
• After completion, a window pops up showing the output and any errors.

3. Plot and Visualize Output

Once CQL3D has successfully completed:

1. Click the Plot Results button (lower right).
2. By default, the UI loads the NetCDF (.nc) file from the last successful run.
3. Optional: If no .nc file exists or you wish to view a different run, click Load .nc file (top left) in the plotting interface.
4. Navigate through the various options to visualize the physics results.
5. Press the left/right arrow keys in the 2D velocity-space contours to cycle through flux surfaces.