Input File Reference

This page describes the following files:

• HEAT input file, usually called X_input.csv where X is the machine name

• PFC input file, which is used for defining which PFCs to perform calculations on

• radiated power input file, which is used as an emission source for photon tracing

• batchFile, which is used to tell HEAT which simulations to run in terminal mode

• filament input file, which is used to prescibe individual filaments for the filament tracer

• elmer input file, which is used to prescribe the inputs for Elmer

X_input.csv File Description

Below is a description of the input file variables that can be found in the X_input.csv file, where X is the machine name.

ioClass.IO_HEAT.allowed_class_vars(self)

IO Variables:

vtpMeshOut:

True or False. Set to true to write VTP mesh files in HEAT output

vtpPCOut:

True or False. Set to true to write VTP point cloud (PC) files in HEAT output

csvOut:

True or False. Set to true to write csv point cloud files in HEAT output

CADClass.CAD.allowed_class_vars(self)

CAD Variables:

gridRes:

can be a number in [mm] or ‘standard’. Defines the intersection mesh grid resolution. If set to a number, uses Mefisto mesher to generate a mesh with triangle edge lengths smaller than number. If set to standard, uses the FreeCAD standard mesher. Recommended to use standard unless you know what you are doing.

overWrite:

can be True or False. If True, overWrite existing STPs and STLs. If False, recycle previous CAD unless there is a timestep mismatch.

xT:

global translation of entire ROI in x direction [mm]

yT:

global translation of entire ROI in y direction [mm]

zT:

global translation of entire ROI in z direction [mm]

MHDClass.MHD.allowed_class_vars(self)

MHD EQ Variables:

shot:

integer pulse number

tmin:

minimum timestep of any MHD equilibrium in simulation [s]

tmax:

maximum timestep of any MHD equilibrium in simulation [s]

traceLength:

number of steps to trace along magnetic field lines looking for intersections

dpinit:

toroidal length of each trace step up magnetic field line [degrees]

heatfluxClass.heatFlux.allowed_class_vars(self)

Optical Heat Flux Variables:

hfmode:

selects the mode for defining the q|| function. options are: eich, multiExp, limiter, tophat, qFile. eich uses an Eich #15 profile [1] where exponential is convoluted with a Gaussian of width, S. multiExp uses a superposition of 4 exponential decays, like the work by Brunner [2], with two in the private flux region and two in the common flux region. limiter uses a double exponential decay, with flux tubes in the core (private flux region) set to 0. tophat uses a tophat profile of user defined width. qFile allows HEAT to read a previous HEAT run output tree and load the heat flux profiles without performing any new calculations. Depending upon the hfmode, various other variables in this section may be required.

lqCN:

Heat flux width (or decay length) in the common near region [mm]. For eich profile and tophat profile this is the only used heat flux width. Used by all hfmodes.

lqCF:

Heat flux width in the common far region [mm]. Used by the multiExp and limiter profiles.

lqPN:

Heat flux width in the private flux near region [mm]. Used by multiExp profile.

lqPF:

Heat flux width in the private flux far region [mm]. Used by multiExp profile.

lqCNmode:

sets the method used to calculate lqCN. Can be eich or user. eich uses Eich’s regression #15 and overrides any lqCN defined in the input file. user directly parses value from input file defined for lqCN.

lqCFmode:

sets the method used to calculate lqCF. Can be horacek or user. horacek uses the scaling from [3] and overrides any lqCF defined in the input file. user directly parses value from input file defined for lqCF.

lqPNmode:

sets the method used to calculate lqPN. Can only be user. user directly parses value from input file defined for lqPN.

lqPFmode:

sets the method used to calculate lqPF. Can only be user. user directly parses value from input file defined for lqPF.

S:

Gaussian spreading term [mm]. Used when hfmode is eich.

Smode:

sets the method used to calculate S. can be makowski or user. makowski uses Figure 6 from [4], and requires the Greenwald density fraction to be defined, fG, see below. user directly parses value from input file defined for S.

fracCN:

fraction of total power going to the common flux near region (0,1)

fracCF:

fraction of total power going to the common flux far region (0,1)

fracPN:

fraction of total power going to the private flux near region (0,1)

fracPF:

fraction of total power going to the private flux far region (0,1)

fracUI:

fraction of power going to the upper inner divertor (0,1)

fracUO:

fraction of power going to the upper outer divertor (0,1)

fracLI:

fraction of power going to the lower outer divertor (0,1)

fracLO:

fraction of power going to the lower outer divertor (0,1)

P:

Total source power [MW]. Depending upon the context, P signifies different things. For optical and gyro orbit simulations, P represents PSOL or Psep, the power crossing the separatrix and being conducted to the target. For photon radiation calculation, P represents the total emitted power over the entire torus.

lossFrac:

fraction of P to be removed. Useful for prescribing a reduction to P that arises from various effects. Power that will be used in the calculation is P*(1-lossFrac).

qBG:

Background heat flux applied to all surfaces when using an Eich profile [MW/m^2]. Note that this also applies flux on the backs of tiles.

fG:

Greenwald density fraction [5] to be used when using Makowski S scaling.

qFilePath:

Path to a HEAT results directory (ie /path/to/HEAT/data/nstx_000001) that contains a tree (timestep and PFC directories) with heat flux data in them. HEAT will use this tree and read the .csv files to generate a heat flux profile. This is for when a user wants to recycle a previous HEAT run without re-running the heat flux calculation. Set to None when no file should be read.

qFileTag:

When reading heat flux data from a file in qFilePath, defines the tag that should be used for the heat flux files. For example, to read a previous HEAT runs photon radiation data, tag would be HF_rad and HEAT would read files named HF_rad.csv. Set to None when no file should be read.

gyroClass.GYRO.allowed_class_vars(self)

Gyro Orbit Heat Flux Variables:

N_gyroSteps:

number of discrete line segments per helical gyro period [integer]. Higher values mean better approximation of the helical trajectory but come at the cost of longer computation times.

gyroTraceLength:

number of steps to trace for gyro orbit calculation [integer]. Step width is defined by the MHD EQ variable dpinit. Should really change this name to gyroTraceLength as it is not directly related to degrees. Total toroidal distance of trace is gyroTraceLength * dpinit

gyroT_eV:

Plasma ion temperature [eV]. This temperature corresponds to the mean total velocity in the ion velocity distribution function.

N_vSlice:

Number of macroparticle samples to take from the velocity distribution function [integer]. Each sample defines the ion energies.

N_vPhase:

Number of macroparticle samples to take from the velocity phase distribution function [integer]. Each sample the ion vPerp and v|| components.

N_gyroPhase:

Number of macroparticle gyroPhase samples to take from a uniform 2pi distribution [integer]. Each sample corresponds to birth phase angle of particles about guiding center.

ionMassAMU:

Ion mass in atomic mass units [AMU].

vMode:

determines if single temperature is defined for entire PFC or if each element on PFC mesh has a unique plasma temperature. Can be single or mesh. For now, only single works.

ionFrac:

fraction of PSOL carried by ions (as opposed to electrons) [0-1]. Power carried by the ions will be P*ionFrac

gyroSources:

name of CAD object to be used as the gyro source plane.

For more information on the gyro orbit module and corresponding physics, see [6].

radClass.RAD.allowed_class_vars(self)

Photon Radiation Heat Flux Variables:

radFile:

CSV file path where the photon emission data is stored. Photon emission data should be provided in a CSV file with columns R,Z,MW, corresonding to an axisymmetric photon emission profile given in [MW]. Path should be absolute path.

Ntor:

Number of times the axisymmetric profile is repeated toroidally. In the limit that Ntor goes to infinity, emission profile becomes toroidally continuous.

Nref:

Number of reflections to trace for. Currently reflections are not implemented in HEAT so this should be set to 1

phiMin:

Minimum toroidal angle of emission extent [degrees]. The emission profile read from a file will be duplicated Ntor times between phiMin and phiMax.

phiMax:

Maximum toroidal angle of emission extent [degrees]. The emission profile read from a file will be duplicated Ntor times between phiMin and phiMax.

plasma3DClass.plasma3D.allowed_class_vars(self)

plasma3D Variables:

plasma3Dmask:

boolean that determines if 3D plasmas should be turned on If True, uses M3DC1 equilibrium

itt:

integer number of toroidal iterations for the MAFOT ‘heatlaminar_mpi’ run

response:

integer to select the M3D-C1 time_xxx.h5 file to use. For linear M3D-C1, time_001.h5 includes the plasma response and time_000.h5 is the vacuum field only

selectField:

integer to switch between g-file (-1) or M3D-C1 (2) in MAFOT run

useIcoil:

integer to turn on vacuum field perturbation coils, default is 0

sigma:

integer to switch between tracing field lines (0), co-passing (+1) or counter-passing (-1) particles in MAFOT

charge:

integer, charge of particles, -1 for electrons, >0 for ions ignored for sigma = 0

Ekin:

float, inetic energy of particles in keV; ignored for sigma = 0

Lambda:

float, ratio of perpendicular to parallel particle velocity ignored for sigma = 0

Mass:

integer, mass number of particles, 1 for electrons and H, 2 for D, 4 for He ignored for sigma = 0

loadHF:

boolean, True means load previous heat flux results instead of running MAFOT, False means run MAFOT

loadBasePath:

string, Path for find previous results if loadHF is True

NCPUs:

integer, number of CPUs to use in MAFOT, default is 10

plasma3DClass.heatflux3D.allowed_class_vars(self)

heatflux3D Variables:

Lcmin:

float, maximum scrape-off-layer connection length

lcfs:

float, <= 1, normalized poloidal flux of last closed flux surface location

lqCN:

float, heat flux layer width lambda_q in mm for Eich profile same as in 2D, see heatfluxClass.py

S:

float, spread width in mm into private flux region for Eich profile same as in 2D, see heatfluxClass.py

P:

float, total power in MW into SOL; same as in 2D, see heatfluxClass.py

radFrac:

float, 0<=x<=1, fraction of radiative power same as in 2D, see heatfluxClass.py

qBG:

float, background heat flux in MW/m^2; same as in 2D, see heatfluxClass.py

teProfileData:

None (defaults to 2.0) or string (Name of Te data file) or float (scaler for generic Te profile) or comma-separated array (Te data vs psi=linspace(0,1.1,len(Te)))

neProfileData:

None (defaults to 0.5) or string (Name of ne data file) or float (scaler for generic ne profile) or comma-separated array (ne data vs psi=linspace(0,1.1,len(ne)))

kappa:

float, electron heat conductivity

model:

string in [layer, conductive, convective] to select heat flux model

NCPUs:

integer, number of CPUs to use in MAFOT, default is 10 same as in plasma3D class

openFOAMclass.OpenFOAM.allowed_class_vars(self)

OpenFOAM Variables:

OFtMin:

minimum timestep of openFOAM simulation [s]

OFtMax:

maximum timestep of openFOAM simulation [s]

deltaT:

timestep size for simulation [s]

writeDeltaT:

timestep size for writing simulation [s]. Currently must be set to same value as deltaT.

STLscale:

scales points in STL mesh up/down by scalar value [float]. Can be used for unit conversions on meshes.

meshMinLevel:

minimum number of refinement iterations to be completed when snapping a volume mesh to a surface mesh [integrer]. Increasing this value creates a finer volume mesh but takes longer. Cannot be larger than meshMaxLevel.

meshMaxLevel:

maximum number of refinement iterations to be completed when snapping a volume mesh to a surface mesh [integrer]. Increasing this value creates a finer volume mesh but takes longer. Cannot be smaller than meshMinLevel.

elmerClass.FEM.allowed_class_vars(self)

Elmer Variables:

meshFEMmaxRes:

float that indicated maximum mesh size in [mm]. 0.0 means auto meshing

meshFEMminRes:

float that indicated minimum mesh size in [mm]. 0.0 means auto meshing

elmerDir:

path to the Elmer case directory. In container should be location that is bind mounted into container. Requires full path.

elmerFile:

CSV file that contains information about the Elmer run. See function “readElmerFile()” for more information. This file should be location in the elmerDir.

elmerHEATlib:

Fortan shared object (.so) file that is called from the SIF. This file should be located in the elmerDir. We allow this file to be dynamically loaded by the user so that they can employ any Elmer User Defined Function.

References:

1. T Eich et al, 2013 Nuclear Fusion, vol53 no9

2. D Brunner et al, 2013 Nuclear Fusion, vol58 no9

3. J Horacek et al, 2016 Plasma Phys. Control. Fusion 58

4. M Makowski et al, 2012 Physics of Plasmas 19, 056122

5. M Greenwald et al, 2002, Plasma Phys. Control. Fusion, vol44 no8

6. T Looby et al 2022 Nuclear Fusion 62 106020

7. 13. Malinen and P. Råback, Multiscale Modelling Methods for Applications in Material Science, pages 101-113. Chapter: Elmer finite element solver for multiphysics and multiscale problems, Forschungszentrum Juelich, Editors: Ivan Kondov, Godehart Sutmann, 2013.

PFC File Description

The HEAT PFC file is a csv that describes which CAD objects we want to include in the calculation, the resolution of the meshes, and some other variables related to magnetic shadowing. This file contains a separate line for each object in the CAD file that we want to use in the calculation.

engineClass.engineObj.readPFCfile(self, infile)

The HEAT PFC File:

The PFC file defines which CAD objects comprise the region of interest (ROI), as well as various parameters for each ROI object. The PFC file is a CSV file in which each row corresponds to a separate ROI object. The columns in the PFC file are as follows:

timesteps:

the timesteps during which we should calculate quantities on this ROI object

PFCname:

the name of the CAD object as it appears in the CAD file

resolution:

the maximum length [mm] of any triangular mesh element for this ROI object. This is a proxy for the resolution.

DivCode:

divertor code. This can be: LO, LI, UO, UI, which correspond to: Lower Outer, Lower Inner, Upper Outer, Upper Inner. These codes are how each PFC in the ROI get flagged as belonging to a specific divertor, and will affect their power later (Psol * powerFrac). The fractions for each region are defined in the X_input.csv file

intersectName:

name of the PFCs that may cast a magnetic shadow upon the ROI object we are calculating power on. If we launch field lines from the PFCname part and follow them up the SOL, we may hit one of these intersectName PFCs. If the user is unsure of this value, “all” can be specified to check against all parts in the CAD. Multiple PFCs can be specified by using “:” between part names.

excludeName:

name of PFCs to exclude in the intersection check. This can be useful when we use the “all” switch for intersectName and want to exclude some obvious PFCs (for example a gyroSourcePlane)

Photon Emission File Description

The photon emission file is used for photon radiation flux calculations. The contents of this file are described in a comment of the read function:

radClass.RAD.read2DSourceFile(self, file)

Reads a comma delimited file that describes the radiated power on an R,Z grid. This point cloud (pc) should represent the axisymmetric plasma radiated power across a single poloidal plane (ie sliced at phi). The power defined at each RZ point is the radiated photon power.

It is assumed that the RZ points are located at the centroids of mesh elements

Each row of this file corresponds to a separate source point. The columns of the file are:

R:

Radial coordinate of the source point [m]

Z:

Z coordinate of the source point [m]

MW:

The power [MW] associated with that mesh point. This power represents the toroidally integrated power. In other words, the total power of a toroidally revolved mesh element centered at R,Z

Batch File Description

The batchFile is used to run HEAT in batch mode (terminal mode). Running HEAT in batch mode is usually much faster, and can be used to perform a large number of HEAT runs serially with a single command. The following comment describes the batchFile used by HEAT. For more information about running in batch mode, see the TUI Tutorial section.

terminalUI.TUI.simulationSchedule(self, batchFile)

determines what simulations need to be run and their correct grouping via a batchFile

The fist line of every batchFile should be: MachFlag, Tag, GEQDSK, CAD, PFC, Input, Output

Column variables are defined as follows

MachFlag:

machine specific flag. can be ‘d3d’,’nstx’,’st40’,’step’,’sparc’,’west’,’kstar’

Tag:

user specified tag to label the simulation by. Tags represent independent HEAT runs. For time varying discharges with multiple

GEQDSK files, tag should be repeated on multiple lines with the TimeStep column changing.

Shot:

pulse number to use for saving HEAT output (MachFlag_Shot). Default is to allow for 6 sig figs of shot numbers. SigFigs can be changed in engineClass object initialization function call.

TimeStep:

Timestep that the equilibrium defined in “GEQDSK” column corresponds to. GEQDSKs can be named in multiple formats, but the TimeStep in this row is what is used by HEAT. For time varying discharges, tag should be repeated on multiple lines with the TimeStep column changing. Timestep units are [s]. Default is to allow for 9 SigFigs after the radix, which corresponds to nanosecond resolution (defined in engineClass initialization function call)

GEQDSK:

magnetic equilibrium file (ie EFIT) in GEQDSK format. Psi should be in units of Wb/rad (divided by 2pi) and the Bt0, Fpol, Psi and Ip values should reflect COCOS.

CAD:

CAD file for the tag. Note that HEAT will use the first CAD file provided in for each tag. Subsequent lines in that tag are ignored. In other words, there can only be one CAD file per tag. Can be STEP, IGES, or FCStd formats.

PFC:

PFC file for the tag. Note that HEAT will use the first PFC file provided in for each tag. Subsequent lines in that tag are ignored. In other words, there can only be one PFC file per tag.

INPUT:

Input file for the tag. Input files can be time varying, but only the HF Variables will be read at each timestep.

Output:

Defines what output HEAT should calculate. Options are: :hfOpt: optical heat flux point cloud :hfGyro: gyro orbit heat flux point cloud :hfRad: radiated power heat flux point cloud :hfFil: filament heat flux point cloud :B: magnetic field glyph cloud :psiN: normalized poloidal flux point cloud :pwrDir: powerDir point cloud :bdotn: bdotn point cloud :norm: normal vector glyph cloud :T: temperature using openFoam :elmer: FEM analysis using Elmer FEM

for multiple outputs, separate options with : (ie hfOpt:psi:T). Note that HEAT will use the first options list provided for each tag. Subsequent lines in that tag are ignored. In other words, there can only be one set of options per tag.

Once you have a batchFile, you need to save all input files in the following directory structure, where <path> is wherever the batchFile is:

• <path>/batchFile.dat

• <path>/MachFlag/GEQDSK

• <path>/MachFlag/CAD

• <path>/MachFlag/PFC

• <path>/MachFlag/Input

Example line for an NSTX-U run for pulse 204118 timestep 4ms:

MachFlag, Tag, Shot, TimeStep, GEQDSK, CAD, PFC, Input, Output

nstx,run1, 204118, 0.004, geqdsk.00004, IBDH_2tiles.step, PFCs_run1.csv, NSTXU_input.csv, B:hfOpt

And the directory structure would look like this

• <path>/batchFile.dat

• <path>/nstx/g204118.00004

• <path>/nstx/IBDH_2tiles.step

• <path>/nstx/PFCs_run1.csv

• <path>/nstx/NSTXU_input.csv

Filament Input File

filamentClass.filament.readFilamentFile(self, path: str)

The HEAT filament file

HEAT calculates filament transport using a model developed by Fundamenski, the so-called Free Streaming Model (FSM) [W Fundamenski, Plasma Phys. Control. Fusion 48 109, 2006]. The FSM assumes that the filament plasma is transported directly along the field lines, corresponding to advection. It ignores collisionality and Coulomb effects.

Filaments are born at user defined timesteps, and then are evolved according to the parameters defined in the filament file. The filaments are born as 3D field aligned Gaussians, and are discretized in space and time using macroparticles. Macroparticles are synthetic “particles” that each originate at some spatial location and with a finite value of energy. HEAT traces each macroparticle along the magnetic field lines. Filaments can be sourced as a function of time or as delta functions in time.

The filament file describes filaments that will be traced in HEAT using the filament module. Each row in the file corresponds to an additional filament that will be traced. The rows describe the filament location and birth parameters, as well as the simulation parameters (ie timesteps).

Each column in the file is described below:

id:

a unique string tag (or name) that is assigned to the filament. example: fil1pt

tMin[s]:

time in seconds of filament birth. example: 1000e-6

tMax[s]:

time in seconds of filament birth. example: 1500e-6

dt[s]:

timestep size in seconds

decay_t[s]:

decay constant for filament birth energy. The filament can be born over a series of timesteps. If N_src_t is > 1, this variable describes the exponential decay. At each of the birth timesteps, HEAT sources particles with a decaying total energy, which is prescribed by this exponential decay constant. See function gaussianAtPts() for more information.

N_src_t:

number of birth timesteps over which we source particles. if set to 1, particles are all born instantaneously.

rCtr[m]:

radial coordinate in meters of filament centroid at birth

zCtr[m]:

vertical coordinate in meters of filament centroid at birth

phiCtr[deg]:

toroidal coordinate in degrees of filament centroid at birth

sig_r[m]:

Gaussian width of filament in radial direction in meters

N_sig_r:

Width of filament radial Gaussian in units of sig_r

N_r:

Number of discrete birth locations in radial direction

sig_p[m]:

Gaussian width of filament in poloidal direction in meters

N_sig_p:

Width of filament poloidal Gaussian in units of sig_p

N_p:

Number of discrete birth locations in poloidal direction

sig_b[m]:

Gaussian width of filament in along field line in meters

N_sig_b:

Width of filament Gaussian along field line in units of sig_b

N_b:

Number of discrete birth locations along field line

N_vS:

Number of samples from the parallel velocity distribution function

v_r[m/s]:

bulk velocity of filament in radial direction [m/s]

v_t[m/s]:

bulk velocity of filament in toroidal direction [m/s]

E0[J]:

total energy of filament across all birth timesteps [J]

T0[eV]:

plasma temperature in filament at birth [eV]. assumed to be uniform.

traceDir:

direction of filament tracing. 1 (-1) for positive (negative) toroidal direction. 0 for both directions.

Elmer Input File

elmerClass.FEM.readElmerFile(self)

The HEAT Elmer File:

The elmerFile is a file that describes the Elmer FEM analysis to run. It defines which PFCs to run through the FEM solver, as well as the Elmer FEM Solver Input Files (.SIF) for each PFC. The columns are:

PFCname:

the name of the PFC to solve on. Should match the CAD.

SIF:

the name of the .SIF file to use. The SIF must be saved in the Elmer Directory as declared in the HEAT input file.

meshFile:

if the user wants to supply a FEM mesh in universal mesh (.unv) format, then they may include the name of the file here. The meshFile must be saved in the Elmer Directory as declared in the HEAT input file. If the user wants HEAT to create a FEM mesh, then leave this field blank or write ‘None’. Keep in mind that if HEAT creates the mesh file autonomously, then there will not be boundary groups used to constrain the model.