The INGRID parameter file
Background
INGRID has been designed to be controlled from a single configuration/parameter file when operating in GUI mode. This specially formatted YAML file is similar to Fortran namelist files due to the key-value structure it contains.
Here is a snippet of what a YAML formatted file can look like.
# Comments are supported and follow python convention!
# YAML entries are a mapping of the form:
#
# key: value
#
# It follows that python interprets the YAML file as a dict
my_YAML_entry:
# YAML file use spaces as indentation.
# 2 or 4 spaces (pick one and stick to it) indicate a nested item.
# Here we use 4 spaces.
my_str_key: 'Hello, YAML!' # my_str_key = 'Hello, YAML!'
my_int_key: 32 # my_int_key = 32
some_float: 3.14159 # some_float = 3.14159
my_true_bool: true # bool case-insensitive
my_false_bool: 0 # '1' '0' bool values supported.
# Empty lines within file are ok.
# Just remember it's the spaces that matter.
my_sub_dict: # Nested dicts are supported.
another_key: ending my example code-block here.
# The above value entry will be interpreted as a string
# (no quotations needed)
Although the INGRID parameter file contains many controls for a user, it does not stray from the patterns illustrated above (no advanced YAML knowledge required).
Tip
While operating INGRID in GUI mode, keep your favorite text-editor handy with the parameter-file in use loaded. You will be making frequent edits to this core parameter/configuration file.
Although not necessary for following tutorial, detailed documentation of the INGRID parameter-file can be found here.
A single-null example file
Users of INGRID have plenty of controls available for fine-tuning their final grid. This section explains how to navigate some key controls within the INGRID parameter file.
We will be using the pre-populated INGRID parameter file DIIID_SNL.yml
from the example_files
directory in the single-null walk-through. Open this file in your preferred text-editor. At the time of writing this documentation, the parameter file DIIID_SNL.yml
contains the following:
# ---------------------------------------------------
# User data directories
# ---------------------------------------------------
dir_settings:
eqdsk: ../data/SNL/DIII-D/ # dir containing eqdsk
limiter: . # dir containing limiter
patch_data: ../data/SNL/DIII-D/ # dir containing patch data
target_plates: ../data/SNL/DIII-D/ # dir containing target plates
# ---------------------------------------------------
# eqdsk file name
# ---------------------------------------------------
eqdsk: neqdsk
# ---------------------------------------------------
# General grid settings
# ---------------------------------------------------
grid_settings:
# ----------------------------------------------------------------------------
# Settings for grid generation (num cells, transforms, distortion_correction)
# ----------------------------------------------------------------------------
grid_generation:
distortion_correction:
all:
active: True # true, 1 also valid.
resolution: 1000
theta_max: 120.0
theta_min: 80.0
np_default: 3
nr_default: 3
poloidal_f_default: x, x
radial_f_default: x, x
# ---------------------------------------------------
# guard cell size
# ---------------------------------------------------
guard_cell_eps: 0.001
# ---------------------------------------------------
# num levels in efit plot
# ---------------------------------------------------
nlevs: 30
# ---------------------------------------------------
# num xpts
# ---------------------------------------------------
num_xpt: 1
patch_generation:
strike_pt_loc: target_plates # 'limiter' or 'target_plates'
rmagx_shift: 0.0
zmagx_shift: 0.0
# ---------------------------------------------------
# Psi levels
# ---------------------------------------------------
psi_1: 1.066
psi_core: 0.95
psi_pf_1: 0.975
# ---------------------------------------------------
# magx coordinates
# ---------------------------------------------------
rmagx: 1.75785604
zmagx: -0.0292478683
# ---------------------------------------------------
# xpt coordinates
# ---------------------------------------------------
rxpt: 1.300094032687
zxpt: -1.133159375302
# ---------------------------------------------------
# Filled contours vs contour lines
# ---------------------------------------------------
view_mode: filled
# ---------------------------------------------------
# Saved patch settings
# ---------------------------------------------------
patch_data:
file: LSN_patches_1597099640.npy
preferences:
new_file: true
new_fname: LSN_patches_1597099640.npy
use_file: false
# ---------------------------------------------------
# Integrator
# ---------------------------------------------------
integrator_settings:
dt: 0.01
eps: 5.0e-06
first_step: 5.0e-05
max_step: 0.064
step_ratio: 0.02
tol: 0.005
# ---------------------------------------------------
# Limiter settings
# ---------------------------------------------------
limiter:
file: ''
use_efit_bounds: false
# ---------------------------------------------------
# target plate settings
# ---------------------------------------------------
target_plates:
plate_E1:
file: d3d_otp.txt
zshift: -1.6
auto_order: True
plate_W1:
file: d3d_itp.txt
zshift: -1.6
auto_order: True
Let’s highlight some important entries that are often used when operating INGRID for single-null cases (basic usage). Advanced tutorials will also be provided.
Setting data paths
A user can provide a string that indicates the path to certain data. This is used to tell INGRID where to look for EFIT data, target plate coordinate, limiter coordinates, and patch-data (for reconstruction). We can set these paths by editing the entry:
# ---------------------------------------------------
# User data directories
# ---------------------------------------------------
dir_settings:
eqdsk: ../data/SNL/DIII-D/ # dir containing eqdsk
limiter: . # dir containing limiter
patch_data: ../data/SNL/DIII-D/ # dir containing patch data
target_plates: ../data/SNL/DIII-D/ # dir containing target plates
Note
INGRID supports both absolute paths and paths relative to where INGRID has been launched.
If dir_settings
is missing any entries, INGRID will (internally) set the missing values to a default value of '.'
(current working directory). This holds even if dir_settings
is omitted from the parameter file.
Note
dir_settings
entries are the directory to look for data and NOT the file itself.
Providing an EQDSK file
The user provides the actual EQDSK file name separate from the dir_settings
entry. We provide this at the global YAML level under entry eqdsk
. That is:
# ---------------------------------------------------
# eqdsk file name
# ---------------------------------------------------
eqdsk: neqdsk
Note
In this example, INGRID searches for the file neqdsk
within the directory ../data/SNL/DIII-D/
(relative to the launch point) since dir_settings['eqdsk']
was set to ../data/SNL/DIII-D/
(see above).
Defining target plates
All target plate settings are under the global INGRID parameter file entry target_plates
. We see this as:
# ---------------------------------------------------
# target plate settings
# ---------------------------------------------------
target_plates:
plate_E1:
file: d3d_otp.txt
zshift: -1.6
auto_order: True
plate_W1:
file: d3d_itp.txt
zshift: -1.6
auto_order: True
INGRID adopts a N-S-E-W compass direction notation in order to help generalize and simplify grid generation. It is important for a user to eventually learn these conventions. A detailed discussion of INGRID’s naming conventions can be found here.
For now (in the case of a lower single-null configuration), note that entries plate_E1
and plate_W1
correspond to the outer and inner target plates, respectively.
Each plate entry recognizes sub-entries such as file
(file name to load), zshift
(z-translation),
rshift
(r-translation, not utilized and internal to INGRID defaults to 0.0
), and auto_order
(INGRID geometry pre-processor).
An especially important note on target plate geometries
In order to automate and simplify much of the grid generation process, INGRID needs to perform format checks and pre-processing of user inputs.
In general, a user provided geometry file (target plate or limiter) can be a text file with (r, z)
coordinates on each line,
or a numpy file representing a saved numpy array of shape (N, 2)
.
Provided a geometry file, INGRID performs a crucial pre-processing step that attempts to order the provided coordinates clock-wise around the magnetic-axis. This operation is performed automatically by default, and must be done for visualization and Patch Map generation purposes. The clock-wise convention and Patch Map generation is dicussed in the documented example pages.
Note
The ordering operation performed automatically can be turned off by setting the auto_order
flag to False
within a specific target_plate entry.
Warning
Although disabling auto_order
can be useful for dealing with tricky geometries in which INGRID’s ordering algorithm fails, the user MUST ensure the clock-wise orientation of the provided geometry file themselves.
Defining x-points, magnetic-axis, and psi-levels
Settings for x-point coordinates, magnetic-axis coordinates, and psi-levels are found under the global INGRID parameter file entry grid_settings
.
# ---------------------------------------------------
# General grid settings
# ---------------------------------------------------
grid_settings:
# ...
# ...
# Other items currently not of interest...
# ...
# ...
# ---------------------------------------------------
# num xpts
# ---------------------------------------------------
num_xpt: 1
# ---------------------------------------------------
# Psi levels
# ---------------------------------------------------
psi_1: 1.066 # SOL
psi_core: 0.95 # CORE
psi_pf_1: 0.975 # PRIVATE-FLUX
# ---------------------------------------------------
# magx coordinates
# ---------------------------------------------------
rmagx: 1.75785604
zmagx: -0.0292478683
# ---------------------------------------------------
# primary xpt coordinates
# ---------------------------------------------------
rxpt: 1.300094032687
zxpt: -1.133159375302
Warning
The entry num_xpt
is one of the most important entries in the INGRID parameter file since it determines INGRID’s method of analysis. Dealing with more than one x-point requires a more in-depth understanding of the parameter file, so ensure this is set to the correct number of x-points.