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]

mergedPFCs:

boolean. if True, runs the intersection calculations for all PFCs at once rather than running each PFC individually. This is usually faster, but occasionally comes with a RAM limitation.

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]

psiMult:

multiplier to apply to all psi quantities (psiSep, psiAxis, psiRZ) for normalization (ie the dreaded 2pi) in EQ

BtMult:

multiplier to apply to toroidal field quantities (Bt0, Fpol) in EQ

IpMult:

multiplier to apply to plasma current, Ip in EQ

BtraceFile:

path to file to be used for field line tracing

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.

radFrac:

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-radFrac).

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.

rzqFile:

Path for the rzqprofile that contains a csv file with columns R(m),Z(m),q||(W/m2)

rayTracer:

defines which render engine to use for ray tracing. Options are {mitsuba_gpu, mitsuba_cpu, open3d, heat}. ‘mitsuba_gpu’ requires cuda installation. ‘heat’ is legacy and slow.

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.

rayTracer:

defines which ray tracer to use. can be open3d (default), mitsuba_cpu, mitsuba_gpu, or heat (legacy and slow)

Prad_mult:

multiplier to apply to the R,Z,Prad emission source points

saveRadFrac:

boolean that determines if we should save a matrix with the mapping between emission source points and each mesh triangle. Will save a Ni x Nj matrix where Ni is number of emission source points and Nj is target mesh triangles. The elements of the matrix are the fractions of the emission source, i, assigned to mesh triangle j. For now this only works with Open3D ray tracing.

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.

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.

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 for writing output (csv, vtp, etc.)

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.