CQL3DUI 0.0.8

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. Load and run pre-compiled 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 from within any directory, simply type:

cqlui

---

Running Example Tests

A set of example tests are provided in the folder cql3dtests in the source distribution (.tar.gz), available for download at:

• [PyPI] (https://pypi.org/project/CQL3DUI/#files)

Once downloaded, open a terminal and navigate to the folder /cql3dtests, then run the ui by typing cqlui.

Directory Structure

The contents of the test folder are organized as follows:

cql3dtests/
├── cqlinput_folder/                                        # Namelist files
│   ├── test1_cqlinput_eoved_.16_multi-flux-surface_test1.0
│   ├── test2_cqlinput_freidberg_full_eps.3_short_w_sxr_201024
│   ├── test3_cqlinput_96143_one_ray.1_short_201024
│   ├── test4_cqlinput_MAST-like_test.0
│   ├── test5_cqlinput_H0.short_mmsv8_adjust.4
│   ├── test6_cqlinput_eoved_.16_multi-flux-surface0.2.11
    └── test7_cqlinput_cmod1101201020_AF.26
└──additional_files/           
    ├── eqdsk                                             # Equilibrium/RF files
    ├── eqdsk_freidberg_full_eps
    ├── eqdsk_MAST-like
    ├── g096143.01440
    ├── g122080.03100
    ├── genray_test4.nc
    ├── genrayfw_18rays.nc
    ├── fpld_dsk
    └── rayech

---

Workflow

1. Import, View, and Edit Namelists

To import a test case (e.g., Test 1.0):

1. Click the Import Namelist button in the top left.
2. Navigate to cql3dtests/cqlinput_folder/.
3. Select any of the test files.

Editing Features:

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

2. Load and Run CQL3D

Prerequisite: You must have a pre-compiled CQL3D Fortran executable.

1. Click the Select CQL3D Executable button (lower left) and navigate to your compiled executable. The UI will remember this location for future runs.
2. Click the Run CQL3D button (lower right).

What happens next?

• A runs folder is created in the current directory (if it doesn't exist).
• 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, ect.) are required.
  • It looks for the subfolder additional_files in the original working directory.
  • If found, it creates symbolic links in the run folder for the required files.
• A separate thread is launched to execute CQL3D.
• After completion, a terminal 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).

Navigate through the various options to visualize the physics results. Press the left/right arrow keys in the 2D velocity-space contours to cycle through flux surfaces.