Input Options

This page contains all the input options available to the user, their definition/allowed values, and finally the default values that each variable takes on.

Last Update: 8/22/25 (commit XXX)

Input Options

Variable	Description	Default
case_name	Name of the simulation	“undefined”
gkyl_dir	Full path to the directory containing all the Gkeyll files	“undefined”
gkyl_casename	Gkeyll simulation name within gkyl_dir	“undefined”
gkyl_frame_start	Starting frame index	0
gkyl_frame_end	Ending frame index	1
gkyl_elec_name	Electron species name in Gkeyll simulation	“elc”
gkyl_ion_name	Ion species name in Gkeyll simulation	“ion”
gkyl_elec_mass_amu	Electron mass (amu)	0.000548
gkyl_ion_mass_amu	Ion mass (amu)	2.014
gkyl_file_type	Gkeyll file format	“binary”
gkyl_moment_type	Moment type used	“bimaxwellian”
lcfs_x	LCFS x-location in Gkeyll simulation (if applicable)	0.0
imp_xbound_buffer	Move absorbing x boundary condition off boundary by this much	0.0
min_xbound_type	Min x-bound condition	“absorbing”
imp_atom_num	Impurity atomic number	74
imp_mass_amu	Impurity mass (amu)	183.84
imp_init_charge	Initial impurity charge	1
imp_num	Number of primary impurities to follow	1
imp_tstart_opt	Time start option	“single_value”
imp_tstart_val	Time start value when imp_tstart_opt = “single_value”	0.0
imp_trange_min	Time range minimum when imp_tstart_opt = “range”	0.0
imp_trange_max	Time range maximum when imp_tstart_opt = “range”	0.0
imp_xstart_opt	x start option	“single_value”
imp_xstart_val	x start value when imp_xstart_opt = “single_value”	0.0
imp_xrange_min	x range minimum when imp_xstart_opt = “range”	0.0
imp_xrange_max	x range maximum when imp_xstart_opt = “range”	0.0
imp_ystart_opt	y start option	“single_value”
imp_ystart_val	y start value when imp_ystart_opt = “single_value”	0.0
imp_yrange_min	y range minimum when imp_ystart_opt = “range”	0.0
imp_yrange_max	y range maximum when imp_ystart_opt = “range”	0.0
imp_zstart_opt	z start option	“single_value”
imp_zstart_val	z start value when imp_zstart_opt = “single_value”	0.0
imp_zrange_min	z range minimum when imp_zstart_opt = “range”	0.0
imp_zrange_max	z range maximum when imp_zstart_opt = “range”	0.0
imp_collisions	Impurity collisions with background toggle	“on”
imp_time_step_opt	Time step option	“constant”
imp_time_step	Time step value	1e-8
imp_time_step_min	Minimum time step	1e-12
imp_source_scale_fact	Source scaling factor	1.0
imp_vel_stats	Velocity statistics toggle	“on”
imp_iz_recomb	Ionization/recombination toggle	“on”
print_interval	Print interval	10
var_red_split	Variance reduction split particles toggle	“off”
var_red_import	Importance method for variance reduction	“median”
var_red_freq	Frequency at which variance reduction is recalculated	0.1
var_red_min_weight	Minimum allowed weight in variance reduction scheme	0.1
var_red_med_mod	Modifier to consider a fraction of median below which variance reduction occurs	1.0
var_red_rusrol	Variance reduction Russian roulette toggle	“off”
var_red_rusrol_prob	Russian roulette probability in low-statistic regions	0.5
openadas_root	OpenADAS root path	“undefined”
openadas_year	OpenADAS year	50

case_name

This is only used when naming the NetCDf file. Useful when doing parameter scans, since it allows the user to reuse the same background files for different iterations of the same simulation.

gkyl_dir

Must be the full path to the directory containing the Gkeyll background files, e.g., “/home/zamp/gkyldir/my_gkyl_sim”.

gkyl_casename

Name of the Gkeyll simulation contained within gkyl_dir. All files must share the same case name.

gkyl_frame_start

Gkeyll frame at which the Flan simulation starts from.

gkyl_frame_end

Gkeyll frame at which the Flan simulation ends at (inclusive).

gkyl_elec_name

Name of the electron species in the Gkeyll simulation, e.g., “elc”.

gkyl_ion_name

Name of the ion species in the Gkeyll simulation, e.g., “ion”.

gkyl_elec_mass_amu

Mass of electron in Gkeyll simulation in atomic mass units, e.g., 0.000548.

gkyl_ion_mass_amu

Mass of ion in Gkeyll simulation in atomic mass units, e.g., 2.014.

gkyl_file_type

(Slated for removal) The format the Gkeyll files are saved in. Currently, only “binary” (.gkyl) is supported and there is no expectation to extend support beyond this. This is the format output by gkylzero.

gkyl_moment_type

(Slated for removal) The type of moments output by Gkeyll. Right now, only “bimaxwellian” is really supported. You can run with “maxwellian”, but the collision model will be incomplete.

lcfs_x

The x coordinate that corresponds to the last closed flux surface, when applicable. This has implications on the boundary conditions, since boundary conditions in the core are treated differently from those in the SOL. When using a geometry that is only in the SOL, leave as 0.0 (or more technically, something below the minimum x bound). Conversely, if a simulation only takes place in the core, set this to a value above the maximum x bound. This assumes the x coordinate is the radial coordinate, which is traditional but not necessarily required in Gkeyll.

Note: This introduces potential pitfalls for the user if they are not aware of this option. Could be likely be improved.

imp_xbound_buffer

(Slated for removal) This is mostly an experimental option. It is possible that the Gkeyll plasma behaves strangely at the x bounds due to artificial boundary conditions. If this input option is a value greater than zero, then Flan will trigger the x boundary conditions when the impurity is within that much distance of either x boundary. This is a bit of a hack option, and hasn’t really been necessary so it will probably be removed.

min_xbound_type

Type of boundary condition to impose at the minimum x boundary.

• “absorbing”: Particle following is ended when encountering minimum x boundary.

• “core”: Particle is teleported to a random y,z cell along the minimum x boundary. This mimics a particle entering the not-simulated core region and coming out at some other location instantaneously. This is fine for steady-state simulations, but for time-varying simulations (e.g., simulating a pellet injection) one should consider that in the real world some amount of time will pass before the particle is ejected from the not-simulated core region.

imp_atom_num

Atomic number of impurity.

imp_mass_amu

Atomic mass of the impurity.

imp_init_charge

Initial charge of the impurity.

imp_num

Number of primary impurities to follow. If a variance reduction scheme is on, then secondary impurities could be generated and thus the number of followed particles could be significantly larger than the value entered here.

imp_tstart_opt

Option for where the particle starts in time. t=0 corresponds to the start of the Flan simulation (NOT the start of the Gkeyll simulation).

• “single_value”: Particle starts at a specific time designated by imp_tstart_opt. Typical for time-varying simulations.

• “range”: Particle is uniformily distributed between imp_trange_min and imp_trange_max. Typical for time-varying simulations.

• “full_range”: Particle is uniformily distributed between the full time range of the simulation. Typical for steady-state simulations.

imp_tstart_val

Starting time value in seconds when imp_tstart_opt = “single_value”.

imp_trange_min

Minimum time value in seconds when imp_tstart_opt = “range”.

imp_trange_max

Maximum time value in seconds when imp_tstart_opt = “range”.

imp_xstart_opt

Option for what x the particle starts.

• “single_value”: Particle starts at a specific x designated by imp_xstart_opt.

• “range”: Particle is uniformily distributed between imp_xrange_min and imp_xrange_max.

• “full_range”: Particle is uniformily distributed between the full x range of the simulation.

imp_xstart_val

Starting x value when imp_xstart_opt = “single_value”.

imp_xrange_min

Minimum x value when imp_xstart_opt = “range”.

imp_xrange_max

Maximum x value when imp_xstart_opt = “range”.

imp_ystart_opt

Option for what y the particle starts.

• “single_value”: Particle starts at a specific y designated by imp_ystart_opt.

• “range”: Particle is uniformily distributed between imp_yrange_min and imp_yrange_max.

• “full_range”: Particle is uniformily distributed between the full y range of the simulation.

imp_ystart_val

Starting y value when imp_ystart_opt = “single_value”.

imp_yrange_min

Minimum y value when imp_ystart_opt = “range”.

imp_yrange_max

Maximum y value when imp_ystart_opt = “range”.

imp_zstart_opt

Option for what z the particle starts.

• “single_value”: Particle starts at a specific z designated by imp_zstart_opt.

• “range”: Particle is uniformily distributed between imp_zrange_min and imp_zrange_max.

• “full_range”: Particle is uniformily distributed between the full z range of the simulation.

imp_zstart_val

Starting z value when imp_zstart_opt = “single_value”.

imp_zrange_min

Minimum z value when imp_zstart_opt = “range”.

imp_zrange_max

Maximum z value when imp_zstart_opt = “range”.

imp_collisions

Toggle for if collisions with the background plasma should be included. The collision model is an implementation of the Nanbu collision model for cumulative small angle collisions. It is a very general collision model that should be applicable to all regions of the plasma. The only approximation within the model is assuming that the impurity ions are in thermal equlibrium with the ions but only when calculating the Coloumb logarithm, which is likely has a negligible impact.

Nanbu, K. Theory of cumulative small-angle collisions in plasmas. Phys. Rev. E 55, 4642–4652 (1997).

• “off”: Collision model turned off.

• “on”: Collision model turned on.

imp_time_step_opt

(Slated for removal) Leave as “constant”.

imp_time_step

Time step for the simulation in seconds. The time spent following impurities is inversely proportional to the time step. The correct time step depends on the simulation, but it is unlikely one would need to go below \(10^{-10}\) seconds.

imp_time_step_min

(Slated for removal) Leave as \(10^{-12}\) seconds.

imp_source_scale_fact

The meaning of this variable depends on what type of situation the simulation represents, but it is used to convert the Monte Carlo weight density in each cell to actual density in (\(m^{-3}\)). Internally, every density value is just multiplied by this value. One could equally run a simulation with this set to 1.0 and multiply the impurity density by this value in post-processing if they wanted to.

• Steady-state simulations: This value represents a particle source rate in units of particles/s. Generally used when imp_tstart_opt = “full_range”.

• Time-dependent: This value represents the total number of particles in the real world. For example, if the source represents the instantaneous source from a pellet, one would calculate the number of atoms in the pellet and set this option equal to that. Generally used when imp_tstart_opt = “single_value” or “range”.

imp_vel_stats

Toggle to include the average Cartesian impurity velocity components in each cell. This exists just because each component is a 4D array that can take up substantial memory and isn’t always needed. If you aren’t memory-bound, you can just set this to “on” and forget about it.

• “off”: Do not track average Cartesian velocity components.

• “on”: The average Cartesian velocity components are tracked and saved in the NetCDF file as imp_vX, imp_vY and imp_vZ.

imp_iz_recomb

Toggle to turn on/off impurity ionization and recombination (for whatever reason, if you want to do that you can). Ionization/recombination probabilities are calculated within the code by loading the corresponding rate coefficients at a given ne, Te and converting it to a probability of ionizing/recombining via prob = rate_coef * ne * imp_time_step. If imp_time_step is too large, probabilities above 1.0 could occur and the results should be treated with caution (a warning will be output if this happens). The solution is to just use a smaller time step.

• “off”: Particles remain at their initial charge state determined by imp_init_charge.

• “on”: Particles are free to ionize and recombine according to probabilities calculated from ADAS.

print_interval

A number telling Flan how often to print how many impurities have been followed. 10 would be every 10%, 100 would be every 1%, etc.

var_red_split

Turn on the particle splitting variance reduction scheme. If a particle is deemed in a “high importance” (low-count) region, the particle is split into two. The weight of the split particles are assigned proportional to the probability of ionizing or recombing, whichever is greater. For example, say a particle’s intial weight is 0.4, and it’s probability of ionizing is 0.25 and recombining is 0.1. If it is in a high-importance region, the original particle’s weight will be reduced by 0.4*0.25=0.1 and “given” to the split particle, which will also be one charge state higher (because ionizing had a greater probability). The end result is a 0.3 weight particle and a 0.1 weight particle with one higher charge state. This process repeats until the starting particle weight is below var_red_min_weight.

• “off”: Variance reduction is turned off.

• “iz_rec”: Described above. imp_iz_recomb must be turned on for this to work (an error will be issued if not).

• “coll”: (Not implemented yet)

var_red_import

This option determines what counts as a high-importance” region. Right now only median is implemented. It only matters when var_red_split or var_red_rusrol is in use.

• “median”: High-importance region is anywhere with counts less than var_red_med_mod * (median counts). Median counts is just the median number of counts across every cell in the simulation volume for each frame.

• “exp_dist”: (Not implemented yet)

• “exp_time”: (Not implemented yet)

var_red_freq

The frequency at which to update the high-importance regions. What this means is how often you want Flan to recalculate the criteria in var_red_import. For instance, 10 recalculates it every 10% of particles, 100 would do it every 1% of particles, etc.

var_red_min_weight

Minimum allowed weight of a particle below which variance reduction is not performed. This is needed, otherwise the particle would continue to be split forever.

var_red_med_mod

Scalar that the median number of counts for each frame is multiplied by to determine the threshold for what is considered a high-importance (low count) region.

var_red_rusrol

Switch to turn on Russian roulette variance reduction. Russian roulette variance reduction encourages a simulation to spend more computational time in high-importance regions by “killing” off particles in low importance regions. If a particle is in a low-importance region, it will have a probability of var_red_rusrol_prob of being killed. If it survives, then its weight is increased by weight / var_red_rusrol_prob. This is a traditional Monte Carlo scheme, and the implementation in Flan is rather straightforward.

The criteria for a high-importance region is determined with var_red_import.

• “off”: Russian roulette is turned off.

• “on”: Russian roulette is turned on.

var_red_rusrol_prob

Probability used in Russian roulette scheme when var_red_rusrol is “on”.

openadas_root

Full path to the directory containing ADAS data. In this directory should be subdirectories of the acd and scd files. E.g., if openadas_year = 89, then the directories acd89 and scd89 should exist within openadas_root.

openadas_year

The year of the ADAS data. Specifically, the scd and acd data from the ADF11 data type. The files should be saved in the standard naming convention. E.g., if simulating tungsten and using ADAS data from year 50, then the files [openadas_root]/acd50/acd50_w.dat and [openadas_root]/scd50/scd50_w.dat should exist.