Namelists

ballstab_knobs

Used to represent the input configuration of ballstab

Name Type Default Description

beta_div

real

1.0

The minimum in scans is beta_prime_equilibrium/beta_div

beta_mul

real

1.0

The maximum in scans is beta_prime_equilibrium*beta_mul

diff

real

0.0

Controls decentring used in the numerical integration used for solving the ballooning equation. Recommended values are either 0 (default) or 1/3.

make_salpha

logical

.false.

Not currently used for anything.

n_beta

integer

1

How many values should be used in s-alpha type scans.

n_shat

integer

1

How many values should be used in s-alpha type scans.

shat_max

real

0.0

The maximum value of to use in s-alpha type scans.

shat_min

real

0.0

The minimum value of to use in s-alpha type scans.

theta0

real

0.0

The theta0 value to use in solving the ideal ballooning problem. We don't currently provide a means to study multiple theta0 in a single run. This may change in the future.

collisions_knobs

Used to represent the input configuration of collisions

Name Type Default Description

adjust

logical

.true.

If true (default) then transform from the gyro-averaged distribution function evolved by GS2 to the non-Boltzmann part of , (), when applying the collision operator. This is the physically appropriate choice, this parameter is primarily for numerical testing.

cfac

real

1.0

Factor multipyling the finite Larmor radius terms in the collision operator. This term is essentially just classical diffusion. Set cfac to 0 to turn off this diffusion.

collision_model

character(len = 20)

'default'

Selects the collision model used in the simulation. Can be one of

  • 'default' : Include both pitch angle scattering and energy diffusion.
  • 'collisionless' : Disable the collision operator.
  • 'none' : Equivalent to 'collisionless'.
  • 'lorentz' : Only pitch angle scattering.
  • 'lorentz-test' : Only pitch angle scattering. For testing, disables some components of the operator.
  • 'ediffuse' : Only energy diffusion.

If no species have a non-zero collision frequency, vnewk, then the collision operator is also automatically disabled.

conservative

logical

.true.

If true (default) then guarantee exact conservation properties.

conserve_forbid_zero

logical

.true.

If true (default) then forces conservation corrections to zero in the forbidden region to avoid introducing unphysical non-zero values for the distribution function in the forbidden region of trapped particles.

conserve_moments

logical

.true.

If true (default) then guarantee collision operator conserves momentum and energy.

const_v

logical

.false.

If true (not the default) then use the thermal velocity to evaluate the collision frequencies to be used. This results in an energy independent collision frequency being used for all species.

ediff_scheme

character(len = 20)

'default'

Controls how the coefficients in the matrix representing the energy diffusion operator are obtained. Can be one of

  • 'default' : Use a conservative scheme.
  • 'old' : Use the original non-conservative scheme.

ei_coll_only

logical

.false.

If true (not the default) then force the collision frequency used for all non-electron species to zero and force all electron-electron terms to zero.

etol

real

2.e-2

Only used in get_verr as a part of the adaptive collisionality algorithm. Sets the maximum relative error allowed, above which the collision frequency must be increased.

etola

real

2.e-2

Only used in get_verr as a part of the adaptive collisionality algorithm. Sets the maximum absolute error allowed, above which the collision frequency must be increased.

ewindow

real

1.e-2

Only used in get_verr as a part of the adaptive collisionality algorithm. Sets an offset to apply to the relative error limit set by etol. This is used to provide hysteresis is the adaptive collisionality algorithm so to avoid adjusting the collision frequency up and down every step (similar to delt_cushion).

ewindowa

real

1.e-2

Only used in get_verr as a part of the adaptive collisionality algorithm. Sets an offset to apply to the absolute error limit set by etola. This is used to provide hysteresis is the adaptive collisionality algorithm so to avoid adjusting the collision frequency up and down every step (similar to the delt_cushion).

force_collisions

logical

.false.

Currently we skip the application of the selected collision operator for species with zero collision frequency and disable collisions entirely if no species have non-zero collision frequency. This is generally sensible, but it can be useful to force the use of the collisional code path in some situations such as in code testing. Setting this flag to .true. forces the selected collision model operator to be applied even if the collision frequency is zero.

heating

logical

.false.

If true (not the default) then calculate collisional heating when applying the collion operator. This is purely a diagnostic calculation. It should not change the evolution.

hypermult

logical

.false.

If true (not the default) then multiply the hyper collision frequency by the species' collision frequency nu_h. This only impacts the pitch angle scattering operator.

lorentz_scheme

character(len = 20)

'default'

Controls how the coefficients in the matrix representing the pitch angle scattering operator are obtained. Can be one of

  • 'default' : Use a conservative scheme.
  • 'old' : Use the original non-conservative scheme.

ncheck

integer

100

Used as a part of the adaptive collisionality algorithm. When active we check the velocity space error with get_verr every ncheck time steps. This check can be relatively expensive so it is recommended to avoid small values of ncheck.

resistivity

logical

.true.

If true (default) then potentially include the drag term in the pitch angle scattering operator. This is a necessary but not sufficient criteria. For the drag term to be included we also require , more than one simulated species and finite perturbations included in the simulation (i.e. fapar /= 0).

special_wfb_lorentz

logical

.false.

If true (not the default) then use special handling for the wfb particle in the pitch angle scattering operator.

split_collisions

logical

.false.

If true (not the default) then remove the collision operator from the usual time advance algorithm. Instead the collision operator is only applied every timesteps_between_collisions timesteps. This can potentially substantially speed up collisional simulations, both in the initialisation and advance phases.

test

logical

.false.

If true (not the default) then performs some additional checks of the data redistribution routines associated with transforming being the standard and collisional data decompositions.

timesteps_between_collisions

integer

1

Should set the number of timesteps between application of the collision operator if split_collisions is true. Currently this is ignored.

use_le_layout

logical

.true.

If true (default) then use a data decomposition for collisions that brings both pitch angle and energy local to a processor. This is typically the most efficient option, however for collisional simulations that only use part of the collision operator (either energy diffusion or pitch angle scattering) then it may be beneficial to set this flag to false such that we use a decomposition that only brings either energy or pitch angle local.

vary_vnew

logical

.false.

Set to true (not the default) to activate the adaptive collisionality algorithm.

vnfac

real

1.1

If the collisionality is to be increased as a part of the adaptive collisionality algorithm then increase it by this factor.

vnslow

real

0.9

If the collisionality is to be decreased as a part of the adaptive collisionality algorithm then decrease it by this factor.

vpar_zero_mean

logical

.true.

Controls how the duplicate vpar = 0 point is handled. When vpar_zero_mean = .true. (the default) the average of g(vpar = 0) for both signs of the parallel velcoity (isgn) is used in the collision operator instead of just g(vpar = 0) at isgn=2. This is seen to suppress a numerical instability when special_wfb_lorentz =.false.. With these defaults pitch angle scattering at is now being handled physically i.e. vpar = 0 at this theta location is no longer being skipped.

dist_fn_knobs

Used to represent the input configuration of dist_fn

Name Type Default Description

adiabatic_option

character(len = 30)

'default'

The form of the adiabatic response (if a species is being modeled as adiabatic). Ignored if there are electrons in the species list.

  • 'no-field-line-average-term' Adiabatic species has n = Phi. Appropriate for single-species ETG simulations.
  • 'default' Same as 'no-field-line-average-term'
  • 'iphi00=0' Same as 'no-field-line-average-term'
  • 'iphi00=1' Same as 'no-field-line-average-term'
  • 'field-line-average-term' Adiabatic species has n=Phi-< Phi >. Appropriate for single-species ITG simulations.
  • 'iphi00=2' Same as field-line-average-term'
  • 'iphi00=3' Adiabatic species has n=Phi-< Phi >_y. Incorrect implementation of field-line-average-term.

afilter

real

0.0

For debugging only.

apfac

real

1.0

Leave as unity. For debugging.

boundary_off_grid

logical

.false.

If true then attempt to enforce gnew == 0 at a half grid point past the end of the grid rather than on the last grid point. This is an experimental feature which has been seen to help suppress grid scale oscillations near the boundary.

boundary_option

character(len = 20)

'default'

Sets the boundary condition along the field line (i.e. the boundary conditions at in flux-tube simulations or in ballooning space). Possible values are:

  • 'default' - "Smart" default -- equivalent to 'zero' except if kt_grids:grid_option='box' in which case equivalent to 'linked'. In simulations with suffifienctly small shear default boundaries correspond to 'periodic'.
  • 'zero', 'unconnected' - Use Kotschenreuther boundary condition at endpoints of theta grid
  • 'self-periodic', 'periodic', 'kperiod=1' - Each mode is periodic in theta with itself.
  • 'linked' - Twist and shift boundary conditions (used for kt_grids:grid_option='box')
  • 'alternate-zero' - Ignored

See also nonad_zero

btor_slab

real

0.0

Overrides the itor_over_B internal parameter, meant only for slab runs where it sets the angle between the magnetic field and the toroidal flow.

def_parity

logical

.false.

True only allows solutions of single parity as determined by the input even.

driftknob

real

1.0

Leave as unity for physical runs can be used for debugging. Multiplies the passing particle drifts (also see tpdriftknob).

esv

logical

.false.

If esv=.true. and boundary_option='linked' (i.e. flux tube simulation) then at every time step we ensure the fields are exactly single valued by replacing the field at one of the repeated boundary points with the value at the other boundary (i.e. of the two array locations which should be storing the field at the same point in space we pick one and set the other equal to the one we picked). This can be important in correctly tracking the amplitude of damped modes to very small values. Also see clean_init.

even

logical

.true.

If def_parity is true, determines allowed parity.

exponential_boundary

logical

.false.

If true then attempt to enforce an exponential decay boundary condition on gnew or hnew (depending on nonad_zero). Decay rate scaled by exponential_boundary_factor

exponential_boundary_factor

real

1.0

Factor scaling the exponential decay boundary condition

g_exb

real

0.0

where is toroidal angular velocity normalised to the reference frequency and is the normalised flux label which has value on the local surface.

g_exb_error_limit

real

0.0

With flow shear in single mode, constrains relative error in phi^2.

g_exb_start_time

real

-1

Flow shear switched on when simulation time exceeds this time.

g_exb_start_timestep

integer

-1

Flow shear switched on when simulation timestep exceeds this timestep.

g_exbfac

real

1.0

Multiplies g_exb in the perpendicular shearing term but not in the parallel drive term. Can be used to construct simulations with purely parallel flow.

gf_lo_integrate

logical

.false.

Perform velocity space integration using gf_lo, rather than g_lo, data decomposition if true. If used without field_option = 'gf_local' in fields_knobs it is likely to give poor performance. If field_option = 'gf_local' in fields_knobs then this needs to be present and set to .true..

gridfac

real

1.0

Affects boundary condition at end of theta grid. Recommended value: 1. _

hyper_in_initialisation

logical

.true.

Determines if we include the hyperviscosity term during the initialisation of the response matrix or not.

lf_decompose

logical

.false.

Set up lowflow term

lf_default

logical

.true.

Treatment of radial variation of temperature in NEO energy variable:

  • (true, default) take it into account when constructing distribution function, i.e. H(EGS2, r)
  • (false) construct H(ENEO) and deal with it later by including a temp gradient term in wstarfac in dist_fn.fpp

mach

real

0.0

Number multiplying the coriolis drift.

mult_imp

logical

.false.

Allow different species to have different values of bakdif. Forced false for nonlinear runs.

nonad_zero

logical

.true.

If true switches on "new" parallel boundary condition where h=0 at incoming boundary instead of g=0. This is considered the correct boundary condition but old behaviour retained for experimentation.

omprimfac

real

1.0

Factor multiplying the parallel shearing drive term when running with non-zero g_exb

opt_source

logical

.false.

If true then use an optimised linear source calculation which uses pre-calculated coefficients, calculates both sigma together and skips work associated with empty fields. Can contribute at least 10-25% savings for linear electrostatic collisionless simulations. For more complicated runs the savings may be less. If enabled memory usage will increase due to using an additional array of size 2-4 times gnew.

poisfac

real

0.0

If non-zero, quasineutrality is not enforced, poisfac=

start_from_previous_solution

logical

.false.

Determines if we set gnew = 0 (if flag is false) or gnew = g in invert_rhs_1 or not. This is currently considered experimental, but the intention is to change the default to true.

tpdriftknob

real

-9.9e9

For debugging only. Multiplies the trapped particle drifts (also see driftknob).

vparknob

real

1.0

For debugging only. Scales the calculated vparallel.

wfb

real

1.0

For debugging only. Sets the boundary value for the barely trapped/passing particle.

wfbbc_option

character(len = 20)

'unset'

Deprecated option, moved to le_grids. Setting will lead to an error message and abort. To be removed entirely in future release

zero_forbid

logical

.false.

If true then force gnew=0 in the forbidden region at the end of invert_rhs_1 (this is the original behaviour). Nothing should depend on the forbidden region so g should be 0 here and if it is not for some reason then it shouldn't impact on results. If the results of your simulation depend upon this flag then something has likely gone wrong somewhere.

dist_fn_species_knobs

Used to represent the input configuration of dist_fn_species. There should be one of this namelist for each species simulated.

Name Type Default Description

bakdif

real

0.0

Spatial implicitness parameter. Any value greater than 0 adds numerical dissipation which is often necessary to avoid grid scale oscillations. When bakdif = 0.0 (default) we use a order grid centered approach in the parallel direction. When bakdif = 1.0 this becomes a fully upwinded method. Recommended value is 0.05 for electrostatic simulations and 0.0 for electromagnetic.

fexpr

real

0.4

Sets the real part of the temporal implicitness parameter. Any value smaller than 0.5 adds numerical dissipation. When fexpr = 0.5 we have a order time centered approach. If fexpr = 0.0 this reduces to a fully implicit backward Euler method. When fexpr = 1.0 this instead becomes a fully explicit forward Euler method (not recommended). The recommended value is 0.48.

driver

Used to represent the input configuration of driver. See the documentation of the antenna module for more details.

Name Type Default Description

amplitude

real

0.0

Amplitude of Langevin antenna.

ant_off

logical

.false.

Overrides all other options and turns off antenna if true.

nk_stir

integer

1

Number of independent Fourier modes driven by antenna.

restarting

logical

.false.

If true then try to get initial antenna amplitudes from the restart file. If not found in restart file then will be set to 0.

t0

real

-1.0

Sets the time at which the antenna frequency changes from constant w_antenna to linearly varying, with linear piece proprtional to w_dot multiplied by time - t0.

w_antenna

complex

(1.0, 0.0)

Frequency of Langevin antenna. Sets the constant part of the complex antenna frequency.

w_dot

real

0.0

Sets the coefficient in front of the time varying antenna frequency (real) component activated when time > t0.

write_antenna

logical

.false.

Write antenna amplitudes to ASCII file for debugging.

eigval_knobs

Used to represent the input configuration of eigval. Several of these options are controlling SLEPc settings, which can also be set using the SLEPc command line flags.

Name Type Default Description

analyse_ddt_operator

logical

.false.

Determines which operator SLEPc is finding eigenvalues of. If .false. then SLEPc analyses the time advance operator, so internally works with the eigenvalue exp(-i*omega*nadv*dt). If .true. then SLEPc analyses a time derivative operator, so internally works with the eigenvalue -i*omega. Note we form a first order one sided approximation of the time derivative (e.g. (g_{n+nadv}-g_{n})/(nadv*code_dt)) to be analysed.

extraction_option

character(len = 20)

'default'

Sets the extraction technique, must be one of:

  • 'default' (use SLEPC default)
  • 'slepc_default' (use SLEPC default)
  • 'ritz'
  • 'harmonic'
  • 'harmonic_relative'
  • 'harmonic_right'
  • 'harmonic_largest'
  • 'refined'
  • 'refined_harmonic'

max_iter

integer

PETSC_DECIDE

Sets the maximum number of SLEPC iterations used. If not set (recommended) then let SLEPC decide what to use (varies with different options).

n_eig

integer

1

The number of eigenmodes to search for. The actual number of modes found may be larger than this.

nadv

integer

1

How many GS2 timesteps to take each time SLEPc wants to advance the distribution function. Useful to separate closely spaced eigenvalues without changing delt.

save_restarts

logical

.false.

If true then we save a set of restart files for each eigenmode found. These are named as the standard restart file (i.e. influenced by the restart_file input), but have eig_<id> appended near the end, where <id> is an integer representing the eigenmode id. If save_distfn of gs2_diagnostics_knobs is true then will also save the distribution function files.

solver_option

character(len = 20)

'default'

Sets the type of solver to use, must be one of:

  • 'default' (Krylov-Schur)
  • 'slepc_default' (Krylov-Schur)
  • 'power'
  • 'subspace'
  • 'arnoldi'
  • 'lanczos'
  • 'krylov'
  • 'GD'
  • 'JD'
  • 'RQCG'
  • 'CISS'
  • 'lapack'
  • 'arpack'
  • 'blzpack'
  • 'trlan'
  • 'blopex'
  • 'primme'
  • 'feast'

Not all solver types are compatible with other eigenvalue options, some options may not be supported in older SLEPC versions and some may require certain flags to be set when SLEPC is compiled.

targ_im

real

0.5

Imaginary part of the eigenvalue target. Often beneficial to set this fairly large (e.g. 10) when looking for unstable modes. Used with the target_* which_option mode.

targ_re

real

0.5

Real part of the eigenvalue target. Often beneficial to set this fairly small (e.g. ~0). Used with the target_* which_option mode.

tolerance

real

1.0d-6

Sets tolerance on SLEPC eigenmode search. Used to determine when an eigenmode has been found. Note this is the tolerance based on the SLEPc eigenvalue, which is the time advance eigenvalue rather than the GS2 eigenvalue, .

transform_option

character(len = 20)

'default'

Sets the type of spectral transform to be used. This can help extract interior eigenvalues. Must be one of

  • 'default' (let SLEPC decide)
  • 'slepc_default' (let SLEPC decide)
  • 'shell'
  • 'shift'
  • 'invert'
  • 'cayley'
  • 'fold'
  • 'precond' (not implemented)

Not all options are available in all versions of the library.

use_ginit

logical

.false.

If true then provide an initial guess for the eigenmode based on using init_g routines to initialise g. Can be helpful in accelerating initial phase of eigensolver. Can also be quite useful with ginit_option='many' (etc.) to start an eigenvalue search from a previously obtained solution, allowing both eigenmode refinement and sub-dominant mode detection.

which_option

character(len = 20)

'default'

Sets SLEPC mode of operation (i.e. what sort of eigenvalues it looks for). Note that this refers to the SLEPc eigenvalue, i.e. the time advance eigenvalue . In other words one should select 'largest_real' to search for modes with the largest growth rate. Must be one of

  • 'default' (equivalent to 'target_magnitude')
  • 'slepc_default' (let SLEPC decide)
  • 'largest_magnitude'
  • 'smallest_magnitude'
  • 'largest_real'
  • 'smallest_real'
  • 'largest_imaginary'
  • 'smallest_imaginary'
  • 'target_magnitude' (complex eigenvalue magnitude closest to magnitude of target)
  • 'target_real'
  • 'target_imaginary'
  • 'all' (only some solver types, e.g. lapack) -- not supported
  • 'user' (will use a user specified function to pick between eigenmodes, note not currently implemented)

fields_knobs

Used to represent the input configuration of fields

Name Type Default Description

do_smart_update

logical

.false.

Used with field_option='local'. If true and x/y are distributed then in time advance only update local part of field in operations like phinew=phinew+phi etc.

dump_response

logical

.false.

Writes files containing the field response matrix after initialisation. This currently works for field_option='implicit' or 'local'. We write to netcdf files by default but fall back to fortran unformatted (binary) files (which are not really portable) in the absence of netcdf.

field_local_allreduce

logical

.false.

Set to true to use an allreduce (on mp_comm) in field calculation (field_option='local' only) rather than a reduction on a sub-communicator followed by a global broadcast. Typically a little faster than default performance but may depend on MPI implementation.

field_local_allreduce_sub

logical

.false.

Set to true, along with field_local_allreduce and intspec_sub , to replace the allreduce used in the field calculation with an allreduce on a sub-communicator followed by a reduction on a "perpendicular" communicator. Typically a bit faster than default and scales slightly more efficiently. Note if this option is active only proc0 has knowledge of the full field arrays. Other processors know the full field for any supercell (connected x-y domains) for which it has any of the xy indices local in the g_lo layout.

field_local_nonblocking_collectives

logical

.false.

If true then use nonblocking collective operations in the fields_local field calculation. This may or may not improve performance.

field_local_tuneminnrow

logical

.false.

Set to true when using field_option='local' to automatically tune and select the best performing minimum block size (in a single supercell) assigned to a single processor. This can improve performance, but is not guaranteed to.

field_option

character(len = 20)

'default'

The field_option variable controls which time-advance algorithm is used for the linear terms. Allowed values are:

  • 'implicit' Advance linear terms with Kotschenreuther's implicit algorithm.
  • 'default' Same as 'implicit'.
  • 'implicit_local' the same as 'local'.
  • 'local' Same implicit algorithm as 'implicit' but with different data decomposition (typically much faster for flux tube runs).
  • 'gf_local' Same as 'local' but with gf_lo field decomposition. To use this you also need to set gf_lo_integrate= .true. in dist_fn_knobs and gf_local_fields = .true. in layouts_knobs.
  • 'test' Use for debugging.

field_subgath

logical

.false.

Set to true to use allgatherv to fetch parts of the field update vector calculated on other procs. When false uses a sum_allreduce instead. This doesn't rely on sub-communicators so should work for any layout and processor count. Note: This only impacts field_option='implicit'

force_maxwell_reinit

logical

.true.

If true then recalculate the fields from the distribution function using get_init_field when restarting a simulation rather than using the values in the restart file.

minnrow

integer

16

Used with field_option='local' to set the minimum block size (in a single supercell) assigned to a single processor. Tuning this parameter changes the balance between work parallelisation and communication. As this value is lowered, more communication needs to be done, but more processors get assigned work. This may reduce the time spent in computation at the cost of time spent in communication. The optimal value is likely to depend upon the size of the problem and the number of processors being used. Furthermore it will affect intialisation and advance in different ways. Can be automatically tuned using field_local_tuneminnrow.

read_response

logical

.false.

Reads files containing the field response matrix and uses to initialise GS2s response matrix rather than using the usual initialisation process.

remove_zonal_flows_switch

logical

.false.

Delete zonal flows at every timestep.

response_dir

character(len = 256)

''

Sets location in which to store/look for response dump files. We don't currently check that this location exists before attempting to use it, which could cause problems. The default is to save them in the working directory.

response_file

character(len = 256)

''

Allows customisation of the base filename to be used for response files. If not set then we use run_name derived from the input file name.

gs2_diagnostics_knobs

Used to represent the input configuration of gs2_diagnostics. This is the version used by the original diagnostics module.

Name Type Default Description

append_old

logical

.false.

Append output data to a previous output file <run name>.out.nc if it already exists. Grid sizes must be unchanged.

conv_max_step

integer

80000

Used for Trinity nonlinear convergence check (use_nonlin_convergence). The maximum number of time steps, after which consider the run converged regardless.

conv_min_step

integer

4000

Used for the Trinity nonlinear convergence check (use_nonlin_convergence). The minimum number of time steps before convergence condition can trigger an exit.

conv_nstep_av

integer

4000

Used for the Trinity nonlinear convergence check (use_nonlin_convergence). The number of timesteps the convergence condition averages over

conv_nsteps_converged

integer

10000

Used for the Trinity nonlinear convergence check (use_nonlin_convergence). The number of steps where convergence is true before convergence is accepted

conv_test_multiplier

real

4e-1

Used for the Trinity nonlinear convergence check (use_nonlin_convergence). Multiplier for the cumulative average of the heat flux

dump_check1

logical

.false.

Write out the field-line average of to dump.check1. This option is usually used for Rosenbluth-Hinton calculations.

dump_check2

logical

.false.

Write out at igomega to <run name>.dc2.

dump_fields_periodically

logical

.false.

Write out to dump.fields.t=(time) every 10 * nwrite timesteps.

enable_parallel

logical

.false.

Enable parallel IO in the .out.nc file. Currently disabled by default and doesn't activate feature when set to true as we hard code that parallel IO isn't supported for the .out.nc file.

exit_when_converged

logical

.true.

Exit when the run has reached convergence

file_safety_check

logical

.true.

Verify that the restart file(s) can be written before starting the run

igomega

integer

0

Index in to measure various diagnostics at. By default, this is the outboard midplane , but it may be useful to set this to a non-zero value for tearing parity modes.

make_movie

logical

.false.

Write out in real space over time, suitable for creating animations. Timestep period is controlled with nmovie

navg

integer

10

Number of timesteps to average over for time-averaged diagnostics

nc_sync_freq

integer

10

Sets the number of output steps between syncing the netcdf file. Higher values may reduce disk overheads but increase the risk of data loss on unclean exit.

ncheck

integer

10

FIXME: Timestep period of which to check velocity space resolution and correction by varying collisionality. But doesn't happen on timesteps when diagnostics are written.

nmovie

integer

-1

Timestep period to write real space fields

nsave

integer

-1

Timestep period for writing restart data if save_for_restart is .true.. Negative values disable the periodic checkpoints.

nwrite

integer

10

Timestep period for writing outputs

nwrite_mult

integer

10

Timestep period multiplier for certain "large" diagnostics, which are written every nwrite_mult * nwrite timesteps.

FIXME: What datasets? phicorr_sum, phiextend_sum in old diagnostics, f and fyx in new diagnostics?

ob_midplane

logical

.false.

If .true., write moments at the outboard midplane only, as opposed to along the entire flux surface

omegatinst

real

1.0e6

Threshold complex frequency () for detecting a numerical instability. If averaged over navg timesteps is greater than omegatinst, abort the run.

omegatol

real

1e-3

Frequency () convergence tolerance. Consider the simulation converged and finish the run if has changed by less than omegatol over the last navg timesteps.

More explicitly, the convergence criterion is:

where is averaged over the last navg timesteps.

print_flux_line

logical

.false.

Print the instantaneous fluxes to screen/stdout every nwrite timesteps

print_line

logical

.false.

Print estimated frequencies and growth rates to screen/stdout every nwrite timesteps

save_distfn

logical

.false.

Write the distribution function to <rootname>.nc.dfn.<processor> files. Only written at end of simulation

save_for_restart

logical

.false.

Write restart files at the end of the simulation. If nsave is positive, then also enable checkpoints by writing restart files every nsave timesteps.

save_glo_info_and_grids

logical

.false.

Save some layout and distribution information in restart files

save_many

logical

.false.

If .true., write one restart file per processor, otherwise write a single restart file.

If gs2 has not been built with parallel netCDF, save_many is ignored and there is always one file per processor (equivalent to save_many = .true.).

If write_many is enabled, you probably want to also set read_many in order to restart from multiple files.

save_velocities

logical

.false.

Save parallel and perpendicular velocities in final restart and/or distribution function files

serial_netcdf4

logical

.false.

use_nonlin_convergence

logical

.false.

For nonlinear runs, stop the run when the averaged differential of the summed averaged heat flux drops below a threshold for a period of time, controlled by conv_test_multiplier, conv_nsteps_converged, gs2_diagnostics_knobs, conv_max_step, and conv_min_step.

write_any

logical

.true.

If .false., skip writing any diagnostics

write_apar_over_time

logical

.false.

Write the entire field every nwrite timesteps

write_ascii

logical

.true.

Write diagnostics to text files. Generally this creates a different text file for each diagnostic. Note that this independent of whether or not netCDF files are used.

FIXME: Verify old and new diagnostics write these files in same format

write_avg_moments

logical

.false.

Write flux surface averaged low-order moments of every nwrite timesteps

write_bpar_over_time

logical

.false.

Write the entire field every nwrite timesteps

write_cerr

logical

.false.

Write the collision error every nwrite timesteps to text file with suffix .cres

FIXME: What does this mean?

write_collisional

logical

.false.

Write collisional heating (collisional and hyper viscous rate of loss of free energy for each mode) every nwrite timesteps

write_correlation

logical

.true.

Write two point parallel correlation function calculated from the electric potential as a function of and parallel separation every nwrite timesteps

write_correlation_extend

logical

.false.

Write two point parallel correlation function calculated from the electric potential as a function of and parallel separation, time averaged and calculated along the extended domain every nwrite timesteps once istep > nstep/4.

write_cross_phase

logical

.false.

Write the cross phase between electron density and perpendicular electron temperature every nwrite timesteps. Calculated at both the outboard midplane, averaged across and ; and averaged across all space

write_density_over_time

logical

.false.

Write the whole non-adiabatic part of the density moment every nwrite timesteps

write_eigenfunc

logical

.false.

Write normalised to the value of at the outboard midplane every nwrite timesteps.

If write_ascii is enabled, the text file is <runname>.eigenfunc.

write_fields

logical

.true.

Enable writing every nwrite timesteps

write_final_antot

logical

.false.

Write the right-hand sides of the field equations at the final timestep. If write_ascii is enabled, the file suffix is .antot

write_final_db

logical

.false.

Write at the final timestep. If write_ascii is enabled, the file suffix is .db

write_final_epar

logical

.false.

Write at the final timestep. If write_ascii is enabled, the file suffix is .epar

write_final_fields

logical

.false.

Write at the final timestep. If write_ascii is enabled, the file suffix is .fields

write_final_moments

logical

.false.

Write various moments (densities, parallel and perpendicular velocities and temperatures, and heat and momentum fluxes) at the final timestep. If write_ascii is enabled, the file suffix is .fields and contains the moments, their magnitudes, and field-line averages. The netCDF output has only the values.

write_flux_line

logical

.false.

Write instantaneous fluxes to output file every nwrite timesteps

write_fluxes

logical

.false.

Write fluxes (heat, momentum and particle; total and per-species) every nwrite timesteps.

If run is nonlinear, this defaults to true

write_fluxes_by_mode

logical

.false.

Write fluxes (heat, momentum and particle; total and per-species) as a function of Fourier mode every nwrite timesteps.

If run is nonlinear, this defaults to true

write_full_moments_notgc

logical

.false.

Write moments (density, parallel flow, and parallel and perpendicular temperatures) in non-guiding centre coordinates every nwrite timesteps

write_g

logical

.false.

Write at ik=it=is=1, ig=0 to text file <runname>.dist

write_gs

logical

.false.

FIXME: Add documentation

write_gyx

logical

.false.

Write as a function of real space every nmovie timesteps to text file ".yxdist"

write_heating

logical

.false.

Write out various heating, free energy and energy injection diagnostics. Text file extension is .heat

write_jext

logical

.false.

Write time averaged external current in the antenna, , as a function of . File suffix is .jext

write_kinetic_energy_transfer

logical

.false.

Calculates and writes the electrostatic drive of zonal flows every nwrite timesteps. The output kinetic_energy_transfer_theta resolves this over only. kinetic_energy_transfer_theta_kxsource, kinetic_energy_transfer_theta_kxtarget, and kinetic_energy_transfer_theta_kysource give additional insights by resolving over individual source or target scales.

write_kpar

logical

.false.

Write the parallel spectrum of at final timestep. File suffix is .kpar

write_line

logical

.true.

Print estimated frequencies and growth rates to text file every nwrite timesteps

write_lorentzian

logical

.false.

Write antenna_w every nwrite timesteps

FIXME: Define antenna_w

write_max_verr

logical

.false.

Write the estimated maximum error from velocity space integrals for various quantities

write_moments

logical

.true.

Write various moments (total and non-adiabatic part of perturbed species density, perturbed parallel flow, perturbed parallel and perpendicular temperatures, parallel heat flux, particule flux and heat flux) every nwrite timesteps

write_nl_flux_dist

logical

.false.

Write the poloidal distributions of the fluxes of particles, parallel momentum, perpendicular momentum, and energy every nwrite timesteps.

See section 3.1 and appendix A of Ball et al. PPCF 58 (2016) 045023 as well as section 5 of "GS2 analytic geometry specification"

write_ntot_over_time

logical

.false.

Write the whole total density moment every nwrite timesteps

write_omavg

logical

.true.

Write time-averaged growth rate and frequency to the output text file every nwrite timesteps. Time average is rolling window over the previous navg timesteps

write_omega

logical

.true.

Write instantaneous growth rate and frequency every nwrite timesteps

write_parity

logical

.false.

Write parities in distribution and particle fluxes to text file with the suffix .parity

FIXME: Clarify what this means

write_pflux_sym

logical

.false.

Write particle flux density as a function of and velocity space every nwrite timesteps. Used for looking at the effect of asymmetry. See Parra et al POP 18 062501 2011 and ask Jung-Pyo Lee

write_pflux_tormom

logical

.false.

Write toroidal angular momentum flux carried by particle flux every nwrite timesteps. Only calculated if gs2 is built with LOWFLOW on.

write_phi_over_time

logical

.false.

Write the entire field every nwrite timesteps

write_ql_metric

logical

.true.

Write a simple quasi-linear metric to netcdf.

write_symmetry

logical

.false.

Write the particle and momentum flux as a function of and velocity space. See write_pflux_sym and write_pflux_tormom

write_tperp_over_time

logical

.false.

Write the whole perturbed perpendicular temperature moment every nwrite timesteps

write_upar_over_time

logical

.false.

Write the whole perturbed parallel velocity moment every nwrite timesteps

write_verr

logical

.false.

Write estimates of error resulting from velocity space integrals in the calculation of various quantities every nwrite timesteps.

write_zonal_transfer

logical

.false.

Write the transfer of free energy, , as a function of , averaged over , every nwrite timesteps

hyper_knobs

Used to represent the input configuration of hyper

Name Type Default Description

const_amp

logical

.false.

Determines whether hyperviscosity includes time dependent amplitude factor when calculating damping rate. Recommend true for linear runs and false for nolinear runs, since amplutide of turbulence grows linearly with time in linear run.

d_hyper

real

-10.0

If hyper_option = 'both' is used then this sets both the hyperresistivity and hyperviscosity damping coefficients. Can override the individual coefficients with d_hyperres and d_hypervisc.

d_hyper3d

real

-10.

Used with the simple3D hyperviscosity model of the form D_hyper3D * (|kperp|/ max |kperp|)^P_hyper3D and ky_cut, kx_cut set max |kperp|

d_hyperres

real

-10.0

Sets hyperresistivity parameter multiplying damping term.

d_hypervisc

real

-10.0

Sets hyperviscosity parameter multiplying damping term. See E. Belli (2006) thesis for more information.

damp_zonal_only

logical

.false.

If true then hyperdissipation only applied to the zonal mode.

gridnorm

logical

.true.

If true (default) then set wavenumber parameters entering the models based on the maximum ky and kx included in the current simulation. If false then these values are set to 1.

hyper_option

character(len = 9)

'default'

Selects the type of hyper terms included. Should be one of

include_kpar

logical

.false.

Not used.

isotropic_model

logical

.true.

if true damp zonal and drift waves with same dissipation formula

isotropic_shear

logical

.true.

If true then use isotropic shear model.

kx_cut

real

-10.

Used with the simple3D hyperviscosity model of the form D_hyper3D * (|kperp|/ max |kperp|)^P_hyper3D and ky_cut, kx_cut set max |kperp|

ky_cut

real

-10.

Used with the simple3D hyperviscosity model of the form D_hyper3D * (|kperp|/ max |kperp|)^P_hyper3D and ky_cut, kx_cut set max |kperp|

nexp

integer

2

Sets the power to which is raised in the dissipation filter.

omega_osc

real

0.4

Sets a parameter in the anisotropic shearing rate calculation.

p_hyper3d

real

4.

Used with the simple3D hyperviscosity model of the form D_hyper3D * (|kperp|/ max |kperp|)^P_hyper3D and ky_cut, kx_cut set max |kperp|

ingen_knobs

Used to represent the input configuration of ingen

Name Type Default Description

ncut

integer

100000

This sets the minimum number of local elements for which processor recommendations will be given. In other words, if the total number of elements is nmesh = (2*ntgrid+1)*2*nlambda*negrid*ntheta0*naky*nspec, then the largest processor count that ingen will recommend would be nmesh/ncut.

npmax

integer

100000

Sets the maximum processor count considered when calculating sweetspots.

scan

logical

.false.

If true then alongside standard ingen report allows the creation of various types of scans. This will involve user interaction if stdin is true.

stdin

logical

.true.

If true (default) then ask for input from stdin when using ingen to produce parameters for scans (scan = .true.). If false then will look in file named .<run_name>.pythonin instead.

init_g_knobs

Used to represent the input configuration of init_g

Name Type Default Description

a0

real

0.0

Amplitude of equilibrium Apara: if a0 is non-zero, is rescaled to give this Apara amplitude

adj_spec

integer

0

Used by ginit_option "recon3": adjust input parameter of this species; if = 0, just warn if given conditions are not satisfied

FIXME: What input parameter, what conditions?

apar0

real

0.0

Used by ginit_option "nl3r": set amplitude of apar if width0 is negative

aparamp

complex, dimension(3)

cmplx(0.0,0.0)

Used in initialization for the Orszag-Tang 2D vortex problem (ginit_option "ot"). Controls size of jpar term. FIXME: Reference equations?

b0

real

0.0

Amplitude of equilibrium By: if b0 is non-zero, is rescaled to give this By amplitude by overriding a0

chop_side

logical

.true.

Rarely needed. Forces asymmetry into initial condition. Warning: This does not behave as one may expect in flux tube simulations (see clean_init), this can be important as the default is to use chop_side

clean_init

logical

.true.

Used with ginit_option "noise". Ensures that in flux tube simulations the connected boundary points are initialised to the same value. Also allows for chop_side to behave correctly in flux tube simulations.

constant_random_flag

logical

.false.

Use the constant_random number generator, which always gives the same random numbers. Useful for testing.

den0

real

1.0

Amplitude of zeroth density perturbation for ginit_option options:

den1

real

0.0

Amplitude of first density perturbation for ginit_option options:

den2

real

0.0

Amplitude of second density perturbation for ginit_option options:

dphiinit

real

1.0

Amplitude of for "nl7" (see ginit_nl7)

eq_mode_n

integer

0

Mode number in for the sinusoidal equilbrium option of ginit_option "recon3" (see ginit_recon3), applies to density and temperatures

eq_mode_u

integer

1

Mode number in for the sinusoidal equilbrium option of ginit_option "recon3" (see ginit_recon3), applies to parallel velocity

eq_type

character(len = 20)

'sinusoidal'

Equilbrium choice for ginit_option "recon3" (see ginit_recon3). Choices are:

  • "sinusoidal"
  • "porcelli"
  • "doubleharris"

even

logical

.true.

Sometimes initial conditions have definite parity; this picks the parity in those cases. Affects the following choices of ginit_option:

ginit_option

character(len = 20)

"default"

Method for initialising g. There are many possible options, but the typical ones are:

  • "default": Gaussian in . See phiinit, width0, chop_side
  • "default_odd": Guassian in multiplied by . See phiinit, width0, chop_side
  • "noise": Noise along field line. The recommended (but not default) selection. See phiinit, zf_init
  • "restart", "many": Restart, using g from restart files.
  • "single_parallel_mode": Initialise only with a single parallel mode specified by either ikpar_init for periodic boundary conditions or kpar_init for linked boundary conditions. Intended for linear calculations.
  • "eig_restart": Uses the restart files written by the eigensolver. Also see restart_eig_id.
  • "random_sine": This option is notable as it attempts to make sure that the initial condition satisfies the parallel boundary condition.

All the options are detailed further in the initialisation options documentation

ikk

integer, dimension(2)

[1, 2]

indices of two modes to initialise for certain options

ikkk

integer, dimension(3)

[1, 2, 2]

indices of three modes to initialise for certain options

ikpar_init

integer

0

Parallel mode number to initialise for ginit_option "single_parallel_mode" with periodic boundary conditions

ikx_init

integer

-1

If greater than zero, initialise only the given with ginit_option "noise". This is useful for linear runs with flow shear, to track the evolution of a single Lagrangian mode.

imfac

real

0.0

Amplitude of imaginary part of for various ginit_option options

include_explicit_source_in_restart

logical

.true.

Do we want to include the explicit source terms and related timesteps when saving/restoring from the restart file.

init_spec_pow

real

0.0

Initial spectrum power index. with ginit_option "noise".

initial_condition_is_nonadiabatic_dfn

logical

.false.

If true then the initial condition is used to set the non-adiabatic distribution function rather than the g evolved by GS2.

input_check_recon

logical

.false.

Print some debug information for ginit_option "recon3"

itt

integer, dimension(2)

[1, 2]

indices of two modes to initialise for certain options

ittt

integer, dimension(3)

[1, 2, 2]

indices of three modes to initialise for certain options

kpar_init

real

0.0

Parallel mode number to initialise for ginit_option "single_parallel_mode" with linked boundary conditions

left

logical

.true.

If chop_side is true, chop out left side in theta if true, right side if false. Applies to: FIXME: list of initial conditions

max_mode

integer

128

The maximum mode number to initialise for ginit_option "random_sine". Actual maximum used will be lower of max_mode and ntheta/8

new_field_init

logical

.true.

Change fields implicit initialisation somehow

FIXME: Add documentation

null_apar

logical

.false.

"Nullify fields". Used by ginit_option "recon3"

FIXME: Add documentation

null_bpar

logical

.false.

"Nullify fields". Used by ginit_option "recon3"

FIXME: Add documentation

null_phi

logical

.false.

"Nullify fields". Used by ginit_option "recon3"

FIXME: Add documentation

phiamp

complex, dimension(3)

cmplx(0.0,0.0)

Used in initialization for the Orszag-Tang 2D vortex problem.

FIXME: expand

phifrac

real

0.1

If doing multiple flux tube calculations, multiply phiinit by (job * phifrac + 1). Allows for ensemble averaging of multiple flux tube calculations

phiinit

real

1.0

Average amplitude of initial perturbation of each Fourier mode. Used by most ginit_option options

phiinit0

real

0.0

Amplitude of equilibrium. Used by ginit_option "recon3"

phiinit_rand

real

0.0

Amplitude of random perturbation. Used by ginit_option "recon3"

proc_to_save_fields

integer

0

Which processor is responsible for saving/reading potentials to/from restart files. If <0 then all procs write to restart files. If >= nproc then set to proc_to_save_fields = mod(proc_to_save_fields, nproc)

prof_width

real

-0.1

Width of "porcelli", "doubleharris" profiles in ginit_option "recon3". If negative, this gives the ratio to the box size

read_many

logical

.false.

Restart from many restart files. If false, use a single restart file: this requires GS2 to have been built with parallel netCDF.

refac

real

1.0

Amplitude of real part of for various ginit_option options

restart_dir

character(len = 150)

"./"

Directory to read/write restart files to/from. Make sure this exists before running (see file_safety_check)

restart_eig_id

integer

0

Used to select with eigensolver generated restart file to load. Sets <id> in restart_file//eig_<id>//.<proc> string used to set filename. Note that this is zero indexed.

restart_file

character(len = run_name_size)

"restart_file_not_set.nc"

Basename of restart files

scale

real

1.0

Rescale amplitudes of fields for restart ginit_option options such as "restart". Note that if scale is negative, the fields are scaled by -scale / max(abs(phi))!

tpar0

real

0.0

Amplitude of zeroth parallel temperature perturbation for ginit_option options:

tpar1

real

0.0

Amplitude of first parallel temperature perturbation for ginit_option options:

tpar2

real

0.0

Amplitude of second parallel temperature perturbation for ginit_option options:

tperp0

real

0.0

Amplitude of zeroth perpendicular temperature perturbation for ginit_option options:

tperp1

real

0.0

Amplitude of first perpendicular temperature perturbation for ginit_option options:

tperp2

real

0.0

Amplitude of second perpendicular temperature perturbation for ginit_option options:

tstart

real

0.0

Force t = tstart at beginning of run

ukxy_pt

complex, dimension(3)

cmplx(0.,0.)

Perturbation amplitude of parallel velocity? Used by ginit_option "recon3"

FIXME: Add documentation

upar0

real

0.0

Amplitude of zeroth parallel velocity perturbation for ginit_option options:

upar1

real

0.0

Amplitude of first parallel velocity perturbation for ginit_option options:

upar2

real

0.0

Amplitude of second parallel velocity perturbation for ginit_option options:

width0

real

-3.5

Width of initial perturbation Gaussian envelope in

zf_init

real

1.0

Amplitude of initial zonal flow perturbations relative to other modes

knobs

Used to represent the input configuration of run_parameters through "knobs"

Name Type Default Description

avail_cpu_time

real

1.0e10

The maximum wall clock time available to GS2

beta

real

0.0

is the ratio of the reference pressure to the reference magnetic energy density, .

delt

real

0.1

Initial timestep

delt_option

character(len = 20)

'default'

Determines how initial timestep is set. Possible options are:

  • "default" or "set_by_hand": use timestep from input file
  • "check_restart": read timestep(s) from restart file

If "check_restart" is used but the restart files aren't present for any reason (for instance, the current run is not a restart), GS2 will error when trying to read the timesteps. You can run the ingen tool on your input file to check this issue before running your job

do_eigsolve

logical

.false.

If true then use eigensolver instead of initial value solver.

eqzip_option

character(len = 20)

'none'

Advanced option to freeze evolution of certain modes. Possible values are:

  • "secondary": don't evolve ik == 2, it == 1;
  • "tertiary": dont' evolve ik == 1, it == 2 or ntheta0;
  • "harris": don't evolve ik == 1.

Only used in dist_fn, should be moved to dist_fn_knobs.

fapar

real

0.0

Multiplies throughout.

fbpar

real

-1.0

Multiplies throughout.

fphi

real

1.0

Multiplies throughout.

immediate_reset

logical

.true.

Determines the behaviour when the CFL condition is broken in the nonlinear term:

k0

real

1.0

Used in ginit_option "harris" and "convect". Should be moved to init_g namelist.

margin_cpu_time

real

300.0

How close to avail_cpu_time can we go before trying to stop the run cleanly

max_sim_time

real

1.0e6

The simulation time after which the run should stop.

ncheck_stop

integer

5

Sets the time step interval at which check for the existence of the .stop file.

neo_test

logical

.false.

Lowflow only. If true, GS2 exits after writing out neoclassical quantities of interest

nstep

integer

100

Maximum number of steps to take

progress_frequency

integer

0

How frequently, in integer steps, do we display a progress message. If <= 0 then no progress messages are displayed

rhostar

real

3.0e-3

Normalised gyro-radius, only used for low flow builds

save_init_times

logical

.false.

If true then save init timer information to .init_times.

save_timer_statistics

logical

.true.

If true then save some extra timer information to .timing_stats giving min/max/mean values.

seed

integer

0

Used to set the random seed used in the random number generators provided by ran. If this input is 0 (the default) then we don't set the seed and use the system default instead.

tite

real

1.0

Only used when there is an adiabatic species. Sets n q ^2 / T of the adiabatic species, normalised to the reference values.

use_old_diagnostics

logical

.false.

If true use original diagnostics rather than new form

user_comments

character(len = 65000)

''

Custom description of run to be added to netcdf output (new diagnostics only)

wstar_units

logical

.false.

If true makes timestep proportional to ky*rho. Only sensible for linear runs.

zeff

real

1.0

Effective ionic charge appearing in electron collision frequency

kt_grids_box_parameters

Used to represent the input configuration of kt_grids_box

Name Type Default Description

jtwist

integer

1

For finite magnetic shear determines the box size in the x direction according to . This also affects the number of connections at each ky when linked boundary conditions are selected in the dist_fn_knobs namelist.

This gets a smart default Initialised to jtwist = max(int(2*pi*shat+0.5,1)) so that . If the magnetic shear is less than around 0.16 then jtwist will default to the minimum allowed value of 1.

ly

real

0.0

Sets the box size in the y direction. If set to 0 (the default) then we set ly=2*pi*y0.

n0

integer

0

If set greater than zero (the default) then this sets the toroidal mode number of the first non-zero ky by overriding the value given for y0 through y0 = 1.0/(n0*rhostar_box*drhodpsi) where drhodpsi is determined during geometry setup.

naky

integer

0

The actual number of ky modes. For nonlinear runs it is generally recommended to use ny instead. If set to 0 (the default) this will be automatically set to 1 + (ny-1)/3. If both ny and naky are set then GS2 will check that ny is sufficiently high to ensure de-aliasing. It can be larger than this minimum value. Setting both values can be useful to allow values to be selected which are performant for the FFTs and provide a good range of sweetspots.

ntheta0

integer

0

The actual number of theta0 modes. For nonlinear runs it is generally recommended to use nx instead. If set to 0 (the default) this will be automatically set to 1 + 2*(nx-1)/3. If both nx and ntheta0 are set then GS2 will check that nx is sufficiently high to ensure de-aliasing. It can be larger than this minimum value. Setting both values can be useful to allow values to be selected which are performant for the FFTs and provide a good range of sweetspots.

nx

integer

0

The number of kx points in inputs to the fft routines, and hence the number of radial points used in real space calculations. This differs from the actual number of kx points simulated in the rest of the code due to the need to prevent aliasing. The number of kx modes actually simulated (ntheta0) is, by default, equal to 1 + 2*(nx - 1)/3.

ny

integer

0

The number of ky points in inputs to the fft routines, and hence the number of binormal points used in real space calculations. This differs from the actual number of ky points simulated in the rest of the code due to the need to prevent aliasing. The number of ky modes actually simulated (naky) is, by default, equal to 1 + (ny - 1)/3.

rhostar_box

real

0.0

The rhostar (rhoref/Lref) to use. Only used if n0 also set greater than zero. If rhostar_box and n0 are greater than zero then y0=1.0/(n0*rhostar_box*drhodpsi), which effectively sets the minimum non-zero ky used in the simulation.

rtwist

real

0.0

Expert usage only -- more documentation required.

Used to control the kx spacing in simulations with effectively zero shear () where linked boundaries are not appropriate so periodic boundaries are used. Also only used if x0 has been set to zero (the default). If rtwist is set to 0.0 (the default) then it is set to the value of jtwist. Effectively ends up setting the box size in the x direction, as if rtwist > 0 and if rtwist < 0. See x0 for an alternative.

x0

real

0.

Controls the box length in the x direction (measured in the reference Larmour radius) if the magnetic shear is small (). The box size in the x direction is given by . See rtwist for an alternative.

y0

real

2.0

Controls the box length in the y direction (measured in the reference Larmour radius). The box size in the y direction is given by . Note if y0 is set negative then, it is replaced with -1/y0 and Effectively sets the minimum wavelength captured by the box.

kt_grids_knobs

Used to represent the input configuration of kt_grids

Name Type Default Description

grid_option

character(len = 20)

"default"

Controls the type of perpendicular wavenumber grid to use. Can be one of

kt_grids_range_parameters

Used to represent the input configuration of kt_grids_range

Name Type Default Description

akx_max

real

0.0

Max kx for periodic finite kx ballooning space runs with .

akx_min

real

0.0

Min kx for periodic finite kx ballooning space runs with .

aky_max

real

0.0

Upper limit of range. Should set to something other than zero.

aky_min

real

0.0

Lower limit of range. Should typically set to something other than zero.

kyspacing_option

character(len = 20)

'default'

Sets the type of spacing between ky grid points, available options are :

  • 'default' : Same as 'linear'
  • 'exponential' : Evenly spaced in log(ky).
  • 'linear' : Evenly spaced in ky.

n0_max

integer

0

Maximum toroidal mode number. Can use instead of aky_max.

n0_min

integer

0

Minimum toroidal mode number. Can use instead of aky_min.

naky

integer

1

The number of 'actual' ky modes.

nn0

integer

1

Number of toroidal modes, only used if n0_min>0. Overrides naky in kt_grids_range_parameters. Note if the number of modes isn't compatible with the requested min and max toroidal mode numbers then we just run with one mode, determined by n0_max.

ntheta0

integer

1

Number of (kx) modes

rhostar_range

real

1.0e-4

Used to convert n0_min, n0_max range into aky_min, aky_max, if n0_min>0. If n0_min is set, aky_min=n0_min*drhodpsi*rhostar_range and aky_max=n0_max*drhodpsi*rhostar_range where drhodpsi is calculated as a part of the geometry setup.

theta0_max

real

0.0

Upper limit of theta_0 range

theta0_min

real

0.0

Lower limit of theta_0 range

kt_grids_single_parameters

Used to represent the input configuration of kt_grids_single

Name Type Default Description

akx

real

default_unset_value

for the reference species (but recommended to set theta0 instead).

aky

real

0.4

for the reference species.

n0

integer

0

if n0>0 use toroidal mode number to override aky and set aky=n0*drhodpsi*rhostar_single where drhodpsi is calculated as a part of the geometry setup.

rhostar_single

real

1.0e-4

Used in conjunction with n0: aky=n0*drhodpsi*rhostar_single (if n0 is set) where drhodpsi is calculated as a part of the geometry setup.

theta0

real

0.0

is the ballooning angle, sets the point in where the radial wavenumber is zero

kt_grids_specified_element

Used to represent the input configuration of a specific specified wavenumber pair

Name Type Default Description

akx

real

0.0

Sets the value for this wavenumber element (but should set theta0 instead).

aky

real

0.4

Sets the value for this wavenumber element.

theta0

real

0.0

Sets the value for this wavenumber element.

kt_grids_specified_parameters

Used to represent the input configuration of kt_grids_specified

Name Type Default Description

naky

integer

1

The number of ky values evolved. The total number of modes evolved is given by the maximum of naky and ntheta0. One must also set up the appropriate number of kt_grids_specified_element_<i> namelists.

ntheta0

integer

1

The number of theta0 values evolved. The total number of modes evolved is given by the maximum of naky and ntheta0. One must also set up the appropriate number of kt_grids_specified_element_<i> namelists.

nx

integer

0

Mostly ignored. Does not set the number of modes used.

ny

integer

0

Mostly ignored. Does not set the number of modes used.

layouts_knobs

Used to represent the input configuration of layouts

Name Type Default Description

fft_measure_plan

logical

.false.

If false then fftw will use heuristics to determine the best fft plan. If true then timing measurements will be made to determine an optimal plan. When true it can take somewhat longer to initialise the fft plans.

fft_use_wisdom

logical

.true.

Try to load and save wisdom about fftw plans to fft_wisdom_file. This can speed up the fft initialisation when running new cases with the same grid sizes as previous runs.

fft_wisdom_file

character(len = run_name_size)

'default'

Location of fftw wisdom file, if left as default, this is set to run_name//'.fftw_wisdom', unless overriden by the environment variable GK_FFTW3_WISDOM. If set to anything other than default, overrides GK_FFTW3_WISDOM.

gf_local_fields

logical

.false.

If true then perform initial decomposition setup related to the gf_local field approach, setting up the gf_lo decomposition. This is forced to false if the number of processors is less than naky * ntheta0. See also the field_option input of fields_knobs.

intmom_sub

logical

.false.

When set to true use sub-communicators in the velocity space integration routines associated with taking moments of the distribution function. The sub-communicator involves all processors with a given xys part of the domain (i.e. the same range in theta0, ky and species dimensions). As such this is forced to false if one or more of these three dimensions are not split "nicely" (typically meaning if we're not using an appropriate sweetspot). Can provide a small performance improvement when true in certain cases.

intspec_sub

logical

.false.

When set to true use sub-communicators in the velocity space integration routines associated with taking species summed moments of the distribution function. The sub-communicator involves all processors with a given xy part of the domain (i.e. the same range in theta0 and ky dimensions). As such this is forced to false if one or more of these two dimensions are not split "nicely" (typically meaning if we're not using an appropriate sweetspot). Can provide a small performance improvement when true in certain cases.

layout

character(len = 5)

'lxyes'

This string determines how the distributed dimensions (k)x, (k)y, l(ambda), e(nergy) and s(pecies) are laid out in (global) memory. The rightmost dimensions are parallelised first, with the leftmost dimension being most local. This can strongly impact performance and the sweetspots suggested by ingen.

Valid options are:

  • 'lxyes'
  • 'xyles'
  • 'yxles'
  • 'lexys'
  • 'lyxes'

The optimal choice depends on the type of simulation being run. It is typically expensive to parallelise x in simulations using the box kt_grids type with linked boundary conditions, including all nonlinear simulations, so xyles is a good choice for these cases. Furthermore for nonlinear cases we must Fourier transform in x and y, so again xyles of yxles are good options. For collisional cases, especially those using the le_lo layout, can benefit from using lexys. Collisional nonlinear simulations therefore have two/three competing choices and it is advisable to test both (remembering that the most suitable number of processors may also change when the layout is changed).

local_field_solve

logical

.false.

Can strongly affect initialization time on some parallel computers. Recommendation: Set true on computers with slow communication networks. It's probably worth trying changing this on your favourite machine to see how much difference it makes for you.

max_unbalanced_xxf

real

0.0

Sets maximum allowable fractional imbalance between the two different blocksizes used in the xxf_lo decomposition used in the nonlinear term calculation if unbalanced_xxf is true. See Adrian Jackson's DCSE report for more details.

max_unbalanced_yxf

real

0.0

Sets maximum allowable fractional imbalance between the two different blocksizes used in the yxf_lo decomposition used in the nonlinear term calculation if unbalanced_yxf is true. See Adrian Jackson's DCSE report for more details.

nproc_e_lo

integer

0

The number of processors to use in e_lo layout. Capped to number of processors in comm world. If not set (<=0) defaults to global nproc.

nproc_g_lo

integer

0

The number of processors to use in g_lo layout. Capped to number of processors in comm world. If not set (<=0) defaults to global nproc.

nproc_le_lo

integer

0

The number of processors to use in le_lo layout. Capped to number of processors in comm world. If not set (<=0) defaults to global nproc.

nproc_lz_lo

integer

0

The number of processors to use in lz_lo layout. Capped to number of processors in comm world. If not set (<=0) defaults to global nproc.

nproc_xxf_lo

integer

0

The number of processors to use in xxf_lo layout. Capped to number of processors in comm world. If not set (<=0) defaults to global nproc.

nproc_yxf_lo

integer

0

The number of processors to use in yxf_lo layout. Capped to number of processors in comm world. If not set (<=0) defaults to global nproc.

opt_local_copy

logical

.false.

Setting to true enables optimising redistribute code, used in FFTs for evaluating nonlinear terms, that avoids indirect addressing. This can introduces worthwhile savings in nonlinear GS2 simulations at lower core counts. See Adrian Jackson's DCSE report for more details.

opt_redist_nbk

logical

.true.

Set to true to use non-blocking communications in the redistribute routines. This is generally more performant but has been observed to be slower in one or two rare cases.

opt_redist_persist

logical

.false.

Set to true to use persistent (non-blocking) communications in the redistribute routines. Requires opt_redist_nbk to be true. Can help improve scaling efficiency at large core counts.

opt_redist_persist_overlap

logical

.false.

Set to true to try to overlap the mpi and local parts of the gather/scatter routines. Should only be used with opt_redist_persist. This is typically not seen to have any impact on performance. See optimising your runs for more details.

simple_gf_decomposition

logical

.true.

When in gf_lo, if there are fewer points than processors , then assign the points to the first and leave the rest of the processors empty

unbalanced_xxf

logical

.false.

Setting to true allows GS2 to adopt a more flexible domain decomposition of the xxf data decomposition (used in nonlinear FFTs). By default GS2 allocates each MPI task with the same uniform blocksize in xxf_lo, one task may have a smaller block of data, and other tasks may be empty. There is no attempt to keep both x and y as local as possible, and sometimes large MPI data transfers are required to map from xxf to yxf and vice-versa during FFTs. With unbalanced_xxf = .true., two slightly different blocksizes are chosen in order to keep both x and y as local as possible, and avoid this potentially large MPI communication overhead. The level of imbalance is limited by max_unbalanced_xxf.

Note ingen can provide data on the imbalance and communication required.

See Adrian Jackson's DCSE report for more details.

unbalanced_yxf

logical

.false.

Setting to true allows GS2 to adopt a more flexible domain decomposition of the yxf data decomposition (used in nonlinear FFTs). By default GS2 allocates each MPI task with the same uniform blocksize in yxf_lo, one task may have a smaller block of data, and other tasks may be empty. There is no attempt to keep both x and y as local as possible, and sometimes large MPI data transfers are required to map from xxf to yxf and vice-versa during FFTs. With unbalanced_yxf = .true., two slightly different blocksizes are chosen in order to keep both x and y as local as possible, and avoid this potentially large MPI communication overhead. The level of imbalance is limited by max_unbalanced_yxf.

Note ingen can provide data on the imbalance and communication required.

See Adrian Jackson's DCSE report for more details.

le_grids_knobs

Used to represent the input configuration of le_grids

Name Type Default Description

bouncefuzz

real

10*epsilon(0.0)

Acts as a small tolerance in deciding if a particular pitch angle is forbidden at a particular theta grid point. Rather than considering particles to be forbidden if 1.0 - lambda * B(theta) < 0 we treat them as forbidden if 1.0 - lambda * B(theta) < -bouncefuzz. This provides a small "buffer" to account for floating round off in the calculation of lambda and B.

genquad

logical

.false.

If true use generalised quadrature scheme for velocity integrals and energy grid. See G. Wilkie thesis.

negrid

integer

-10

Sets the number of energy grid points to use. If specified then overrides values of nesuper = min(negrid/10 + 1, 4) and nesub = negrid - nesuper. If not set then the total number of energy grid points is just negrid = nesub + nesuper. The energy grid is split into two regions at a point controlled by vcut.

nesub

integer

8

Sets the number of energy grid points below the cutoff.

nesuper

integer

2

Sets the number of energy grid points above the cutoff.

new_trap_int

logical

.false.

If true then use a more accurate integration method for the trapped pitch angle contribution to velocity integrals. The default uses a simple, but potentially less accurate, finite difference method.

new_trap_int_split

logical

.false.

If true then split the trapped region into two symmetric regions when calculating the integration weights associated with the new_trap_int approach.

ngauss

integer

5

The number of untrapped pitch-angles moving in one direction along field line is 2*ngauss if npassing is not set. Note that the number of trapped pitch angles is directly related to the number of theta grid points (per ) and is ntheta/2 + 1.

nmax

integer

500

Influences the minimum number of grid points in an integration subinterval used in calculating the integration grid weights. When using high ntheta with new_trap_int active it is possible that numerical instability can arise. Dropping nmax < ntheta can sometimes help in such situations.

npassing

integer

-1

The number of untrapped pitch-angles moving in one direction along field line.

radau_gauss_grid

logical

.true.

The default lambda grid is now gauss-radau, for passing particles up to and including the passing-trapped boundary (wfb). The grid gives finite weight to the class of particles which bounce at theta = +/- pi (wfb) in the passing integral Note that the old gauss-legendre is used in the case that trapped_particles =.false.

split_passing_region

logical

.false.

If true then we split the passing region into two separate regions for the purpose of choosing the integration weights. The split point is determined automatically by an attempt to minimise the passing weights error.

test

logical

.false.

If true then just does a few tests and writes pitch angle and energy grids to screen before aborting the simulation.

trapped_particles

logical

.true.

If set to false then the lambda grid weighting wl is set to zero for trapped pitch angles. This means that integrals over velocity space do not include a contribution from trapped particles which is equivalent to the situation where eps<=0.0. Trapped particle drifts are not set to zero so "trapped" particles still enter the source term through wdfac. At least for s-alpha the drifts are the main difference (please correct if not true) between the eps<=0.0 and the trapped_particles = .false. cases as Bmag is not a function of theta in the eps<=0.0 case whilst it is in the trapped_particles = .false. case.

vcut

real

2.5

No. of standard deviations from the standard Maxwellian beyond which the distribution function will be set to 0.

wfbbc_option

character(len = 20)

'default'

Set boundary condition for WFB in the linear/parallel solve:

  • "default", "mixed": The previous default boundary condition which mixes the passing and trapped boundary conditions
  • "passing": Treats the WFB using a passing particle boundary condition
  • "trapped": Treats the WFB using a trapped particle boundary condition

wgt_fac

real

10.0

Influences the maximum integration weight allowed.

nonlinear_terms_knobs

Used to represent the input configuration of nonlinear_terms

Name Type Default Description

cfl

real

0.1

Scales the estimate CFL limit used to determine when the timestep should be changed. The maximum allowed timestep satisfies delt < cfl * min(Delta_perp/v_perp) where v_perp * delt is the maximum distance travelled in a single timestep.

error_target

real

0.1

Set the error threshold used to determine when the timestep should change if use_order_based_error is true.

include_apar

logical

.true.

Flag for testing. If false do not include apar contribution to nonlinear term.

include_bpar

logical

.true.

Flag for testing. If false do not include bpar contribution to nonlinear term.

include_phi

logical

.true.

Flag for testing. If false do not include phi contribution to nonlinear term.

istep_error_start

integer

30

Set the first timestep for which the order based error checks are made if use_order_based_error is true.

nl_forbid_force_zero

logical

.true.

If true (default) then forces the nonlinear source term to zero in the forbidden region.

nonlinear_mode

character(len = 20)

'default'

Determines if the nonlinear terms should be calculated. Must be one of:

  • 'none' - Do not include nonlinear terms, i.e. run a linear calculation.
  • 'default' - The same as 'none'
  • 'off' - The same as 'none'
  • 'on' - Include nonlinear terms.

Could consider changing this to a logical.

split_nonlinear

logical

.false.

Do we evolve the nonlinear term separately from the linear terms (true) or include the nonlinear term as a source in the standard algorithm (false).

use_cfl_limit

logical

.true.

If true then use the cfl limit to set the maximum timestep allowed.

use_order_based_error

logical

.false.

If true then use an error estimate from comparing the nonlinear source calculated using 2nd and 3rd order Adams-Bashforth schemes to control the timestep in use. This does not disable the CFL estimate.

zip

logical

.false.

Not currently used, should consider removing. Original documentation was "Experts only (for secondary/tertiary calculations)." which suggests a close relation to the eqzip option of knobs.

normalisations_knobs

Used to represent the input configuration of normalisations. These values are not used for anything but will be written to the output file to aid post processing etc.

Name Type Default Description

aref

real

default_value

Reference length in

bref

real

default_value

Reference magnetic field in

mref

real

default_value

Reference mass in atomic mass units

nref

real

default_value

Reference density in

rhoref

real

default_value

Reference Larmor radius in

tref

real

default_value

Reference temperature in

vref

real

default_value

Reference (thermal) velocity in

zref

real

default_value

Reference charge in units of the elementary charge

optimisation_config

Used to represent the input configuration for GS2's optimisation procedure. When turned on, GS2 performs a scan for the given input file, varying different optimisation flags. Results of this scan are reported in .optim. The optimal parameters are stored, allowing a user to run the same input file with optimised parameters in the same execution. A user can also choose to continue with a less-than-optimal set of parameters which satisfy other constraints.

Name Type Default Description

auto

logical

.true.

When true, automatically continues GS2 to run the input file with the optimised parameters.

estimate_timing_error

logical

.true.

Estimate the absolute and relative errors in timing data FIXME: Why would we want this to be false? On small core counts it doesn't seem like a big overhead.

max_imbalance

real

-1.0

The maximum fraction of unused procs to allow in the optimisation scan.

max_unused_procs

integer

0

The maximum number of unused procs to allow in the optimisation scan.

measure_all

logical

.false.

When true, use the "advance" timer. When false, use the "timestep" timer.

min_efficiency

real

-1.0

The minimum efficiency (relative to the optimal parameters) considered when looking for a constrained set of parameters. A negative value implies only the optimal parameters are considered.

nstep_measure

integer

5

The number of timestep to use in the timing experiments. Must be greater than 1

on

logical

.false.

Set true to turn on optimisation procedure

warm_up

logical

.false.

When true, perform a few runs before beginning the timing experiment

parameter_scan_knobs

Used to represent the input configuration of parameter_scan

Name Type Default Description

delta_t_inc

real

0.0

When the increment condition is "delta_t", the parameter will be changed every time delta_t_inc time has elapsed.

delta_t_init

real

0.0

When the increment condition is "delta_t", the parameter will not be changed until delta_t_init time has elapsed from the beginning of the simulation. Note, that if the simulation is restarted, this parameter will measure from beginning of original simulation.

inc_con

character(len = 20)

'delta_t'

Specifies the condition for incrementing the parameter. Possible values are:

  • "n_timesteps": change the parameter after a given number of time steps
  • "delta_t": change the parameter after an elapsed time
  • "saturated": change the parameter after the simulation has reached a saturated state (determined using the target parameter) at the current value of the parameter

nstep_inc

integer

0

When the increment condition is 'n_timesteps', the parameter will be changed every nstep_inc.

nstep_init

integer

0

When the increment condition is 'n_timesteps' or 'saturated', the parameter will not be changed until nstep_init have elapsed from the beginning of the simulation. Note that if the simulation is restarted, this parameter will measure from the restart.

par_end

real

0.0

If the scan is being run in 'range' mode, specifies the value of the parameter that will be reached.

par_inc

real

0.0

If the parameter scan is being run in 'range' or 'target' modes, specifies the amount by which the parameter is varied at one go.

par_start

real

0.0

Specifies the starting value for the parameter scan.

scan_par

character(len = 20)

'tprim'

Specify the parameter to be varied. If the parameter pertains to a species, the scan_spec must be specified as well.

scan_restarted

logical

.false.

Specify the parameter to be varied. If the parameter pertains to a species, the scan_spec must be specified as well.

scan_spec

integer

1

When parameter pertains to a species, specifies the index of the species.

scan_type

character(len = 20)

'none'

Specifies the way that the parameter scan is conducted. Possible values are:

  • 'none': do not conduct a parameter scan (default)
  • 'range': vary parameter in constant increments between 2 values: par_start and par_end. The step size is given by par_inc.
  • 'target': start with the parameter at par_start, and then change the parameter by par_inc until the target parameter has reached the target value
  • 'root_finding': the same as target, but the increment is changed intelligently using a Newton-like method.

target_par

character(len = 20)

'hflux_tot'

If the scan is being run in 'target' or 'root_finding' mode, specifies the target parameter. Possible values are:

  • 'hflux_tot'
  • 'momflux_tot'
  • 'phi2_tot'

target_val

real

0.0

reinit_knobs

Used to represent the input configuration of reinit

Name Type Default Description

abort_rapid_time_step_change

logical

.true.

If true (default), exit if time step changes rapidly, that is, if the time step changes at four consecutive time steps.

delt_adj

real

2.0

When the time step needs to be changed it is adjusted by this factor, i.e dt --> dt/delt_adj or dt --> dt*delt_adj when reducing/increasing the timestep. For non-linear runs good choice of delt_adj can make a moderate difference to efficiency. Need to balance time taken to reinitialise against frequency of time step adjustments (i.e. if your run takes a long time to initialise you probably want to set delt_adj to be reasonably large).

delt_cushion

real

1.5

Used in deciding when to increase the time step to help prevent oscillations in time step around some value. We only increase the time step when it is less than the scaled cfl estimate divided by delt_adj*delt_cushion whilst we decrease it as soon as the time step is larger than the scaled cfl estimate.

delt_minimum

real

1.e-5

The minimum time step allowed is delt_minimum. If the code wants to drop below this value then the run will end.

dt0

real

0.0

Sets the maximum value the time step can take.

in_memory

logical

.false.

If true then attempts to create temporary copies of the distribution fn and fields in memory to be restored after the time step reset rather than dumping to fields. This could be faster on machines with slow file systems. If the required memory allocation fails then we set in_memory=.false. and fall back to the traditional file based approach.

source_knobs

Used to represent the input configuration of source

Name Type Default Description

gamma0

real

0.0

Growth rate of non-standard source used with source_option = 'phiext_full'.

omega0

real

0.0

Frequency of non-standard source used with source_option = 'phiext_full'.

phi_ext

real

0.0

Amplitude of external phi added as source term with source_option = 'phiext_full'. If zero (default) then no extra term included in the source.

source0

real

1.0

Amplitude of non-standard source used with source_option = 'phiext_full' when time >= t0.

source_option

character(len = 20)

'default'

Controls the source term used in the time advance. Should be one of:

  • 'source_option_full' : Solve GK equation in standard form (with no artificial sources)
  • 'default' : Same as 'source_option_full'
  • 'phiext_full' : Solve GK equation with additional source proportional to phi_ext*F_0.
  • 'homogeneous' : Solve the homogeneous equation, i.e. no potential related sources.

t0

real

100.0

Turn on any artificial sources after time = t0. Only used with source_option = 'phiext_full'.

species_knobs

Used to represent the input configuration of species

Name Type Default Description

me

real

-1.0

Specifies the electron mass used in calculating the slowing down parameters in simulations without kinetic electrons.

nspec

integer

2

Number of kinetic species to evolve.

zi_fac

real

-1.0

Specify the ion charge factor used in calculating the slowing down parameters. If not specified that will attempt to calculate from the kinetic ion species.

species_parameters

Used to represent the input configuration of species

Name Type Default Description

bess_fac

real

1.0

Multiplies the argument of the Bessel function for this species. Useful for exploring the effect of the Bessel functions.

dens

real

1.0

Set the normalised density for this species

dens0

real

1.0

Parameter used for a few specific initial condition types.

f0type

character(len = 20)

"default"

Select which type of background distribution should be assumed for this species. Must be one of:

  • 'default' : equivalent to maxwellian
  • 'maxwellian' : Standard maxwellian
  • 'tabulated' : A general tabulated form
  • 'sdanalytic' : A analytic slowing down form.

See G. Wilkie thesis.

fprim

real

2.2

Normalised inverse density gradient: (Note here is the normalised radius .

mass

real

1.0

Normalised mass of this species

nu_h

real

0.0

Set the species hyper collision frequency used in the pitch angle scattering collision operator if [[collision_knobs::hypermult]] is true.

temp

real

1.0

Set the normalised species temperature

tpar0

real

0.

Parameter used for a few specific initial condition types.

tperp0

real

0.

Parameter used for a few specific initial condition types.

tprim

real

6.9

Normalised inverse temperature gradient: (Note here is the normalised radius .

type

character(len = 20)

"default"

Sets the characterisation of the species. Should be one of

  • 'ion' : Thermal ion species
  • 'default' : Same as 'ion'
  • 'electron' : Thermal electron species
  • 'e' : Same as 'electron'
  • 'trace' : Tracer species
  • 'hybrid_electron' : Adiabatic passing electrons, full trapped electron treatment. NOTE: This option is currently considered experimental and is intended for use in electrostatic simulations.

This primarily controls the treatment in the collision operator, the detection of adiabatic species. Tracer species do not contribute to velocity space integrals.

u0

real

1.0

Parameter used for a few specific initial condition types.

uprim

real

0.0

Controls an energy independent part of a source term.

uprim2

real

0.0

Controls an energy dependent part of a source term.

vcprim

real

-999.9

Part of the sdanalytic slowing down model. See G. Wilkie thesis.

vcrit

real

-1.0

Part of the sdanalytic slowing down model. See G. Wilkie thesis.

vnewk

real

0.0

Sets the normalised species-species collisionality frequency. For species s, vnewk = nu_ss Lref/vref where Lref is the reference length, vref is the reference thermal speed (not the thermal speed of species s!), is a dimensional collision frequency, e is the proton charge, is the Coloumb logarithm, and are the (charge, temperature, density, mass) of species s. (The dimensional collision frequency given here is in Gaussian units. For SI units, include an extra factor in the denominator of the definition of .

z

real

1.0

Normalised species charge

split_nonlinear_terms_knobs

Used to represent the input configuration of split_nonlinear_terms

Name Type Default Description

absolute_tolerance

real

1.0e-3

The absolute tolerance used in error controlled schemes. Attempt to adjust time step to keep error below this tolerance.

advance_nonadiabatic_dfn

logical

.false.

If true then nonlinear integrator advances the nonadiabatic dfn, h, rather than the modified distribution function, g.

convergence_tolerance

real

1.0e-1

The tolerance used in convergence checks. Currently only used for halting the fixed-point iteration in the beuler method

relative_tolerance

real

1.0e-2

The relative tolerance used in error controlled schemes. Attempt to adjust time step to keep error below this tolerance.

rk_method

character(len = 20)

'default'

Choose which specific RK scheme to use in the RK method. Generally if the tolerances are small a higher order scheme will be more effective than low order. At loose tolerances low order schemes are generally more efficient Valid options include:

  • 'cashkarp' -- Cash-Karp scheme of order 4(5)
  • 'default' -- Same as heun
  • 'heun' -- Heun scheme of order 1(2)

See rk_schemes for other options.

show_statistics

logical

.false.

If true then reports the number of right hand side (NL term) calculations, the number of failed internal steps and the number of successful steps at the end of each linear size step.

split_method

character(len = 20)

'default'

What algorithm do we use to advance the nonlinear term if split_nonlinear is true. Valid options include:

  • 'AB3' -- Adams-Bashforth (up to) 3rd order. CLF controlled time step.
  • 'beuler' -- Backwards Euler. Relative and absolute error controlled time step. Newton iteration controlled by convergence_tolerance.
  • 'default' -- The same as 'RK'.
  • 'RK' -- RK scheme with embedded error estimate. Exact scheme can be switched out using rk_method switch. Relative and absolute error controlled time step.
  • 'picard' -- Use simple Picard iteration. Not generally recommended but available for experimentation.

strang_split

logical

.false.

If true then indicates that we want to use a strang split approach where we advance the NL operator by a half step, linear by a full step and then NL by another half step. This should be second order accurate whilst the regular split is only first order accurate.

time_step_safety_factor

real

0.9

Multiplies the new time step calculated from either the error or cfl limits. Smaller values are more conservative but may help avoid repeated violation of the error/cfl limits and hence reduce the number of failed steps.

stir

Used to represent the input configuration of stir. See the documentation of the antenna module for more details.

Name Type Default Description

a

real

-1.0

Initial amplitude of right-moving component. It is not necessary to set a and b unless you are doing restarts, which are rather clunky at the moment with the antenna included.

b

real

-1.0

Initial amplitude of left-moving component. It is not necessary to set a and b unless you are doing restarts, which are rather clunky at the moment with the antenna included.

kx

integer

1

Mode number for stirring.

ky

integer

1

Mode number for stirring.

kz

integer

1

Mode number for stirring.

travel

logical

.true.

Launches traveling wave if true (default) or standing wave if false.

theta_grid_eik_knobs

Used to represent the input configuration of theta_grid

Name Type Default Description

alpha_input

real

0.0

Used in calculation of dp_new = -alpha_input/qval**2/rmaj*drhodpsi

beta_prime_input

real

0.0

The gradient of the pressure. Strictly speaking this parameter is not but : in other words, the gradient of the magnetic field is ignored. Used only if bishop = 4 or 9.

bishop

integer

5

Use Bishop relations to generate metric coefficients.

  • 0: Use high-aspect ratio coefficients (only for debugging)
  • 1: Use actual equilibrium values of shat, p' recommended
  • 2: Use numerical equilibrium + s_hat_input and p_prime_input
  • 3: Use numerical equilibrium + s_hat_input and inv_Lp_input
  • 4: Use numerical equilibrium + s_hat_input and beta_prime_input
  • 5: Use numerical equilibrium + s_hat_input and alpha_input
  • 6: Use numerical equilibrium + beta_prime_input
  • 7: Use numerical equilibrium and multiply pressure gradient by dp_mult
  • 8: Use numerical equilibrium + s_hat_input and multiply pressure gradient by dp_mult
  • 9: Use numerical equilibrium + s_hat_input and beta_prime_input
  • Otherwise: Use magnetic shear and pressure gradient as set elsewhere.

chs_eq

logical

.false.

Use equilbrium data from the CHEASE file ogyropsi.dat

delrho

real

1e-3

Step size for radial derivatives, . Should be "small enough", typically 0.001.

dfit_eq

logical

.false.

Vacuum magnetic dipole geometry

dp_mult

real

1.0

Used to scale the pressure gradient, only if bishop = 7 or 8.

efit_eq

logical

.false.

Use EFIT equilibrium (EFIT, codes with eqdsk format)

eqfile

character(len = eqfile_length)

"default_unset_value"

Name of file with numerical equilibrium data (if required)

eqnormfile

character(len = eqfile_length)

"default_unset_value"

Name of file with numerical equilibrium normalization data (if required) currently, only used for dipole equilibrium (deq)

equal_arc

logical

.true.

Change field-line coordinate. Recommended value: F

force_sym

logical

.false.

If true then forces up-down symmetry in some geometrical quantities

gen_eq

logical

.false.

Use Toq-style NetCDF equilibrium (TOQ)

gs2d_eq

logical

.false.

Read Colin Roach's GS2D equilibrium file

idfit_eq

logical

.false.

Unknown equilibrium file. You probably don't want this. FIXME: Add documentation

iflux

integer

-1

Deprecated -- redundant information.

invlp_input

real

0.

Used with bishop == 3: controls pressure length scale by multiplying

irho

integer

2

Choose definition of flux surface coordinate

  • 1: rho == sqrt(toroidal flux)/sqrt(toroidal flux of LCFS)
  • 2: rho == midplane diameter/LCFS diameter - Recommended
  • 3: rho == poloidal flux/poloidal flux of LCFS
  • 4: rho == rho_mid (vacuum ring dipole, dfit_eq = T, only)

NB For consistency fprim, tprim, shat, uprim, g_exb etc must be computed using same radial variable, i.e. depend on choice of irho!

isym

integer

-1

Deprecated, see force_sym instead

itor

integer

-1

Deprecated, see use_large_aspect instead

local_eq

logical

.true.

If .true. use Miller-style local equilibrium else use other numerical equilibrium types

ntheta_geometry

integer

-1

The number of theta grid points to use in eikcoefs calls. Currently may not have an effect for all equilibrium types. If not set then defaults to ntheta

ppl_eq

logical

.false.

Use Menard-style NetCDF equilibrium (JSOLVER)

s_hat_input

real

0.0

Used to overrides s_hat prescribed by the numerical equilibrium, but only if bishop=2,3,4,5,8, or 9.

transp_eq

logical

.false.

Use PPL NetCDF equilibrium (psipqgrz equilibrium from TRANSP/TRXPL)

use_large_aspect

logical

.false.

If true use large aspect ratio expansions in eik geometry to get ~s-alpha

writelots

logical

.false.

Write a little extra about geometry to the screen.

theta_grid_file_knobs

Used to represent the input configuration of theta_grid

Name Type Default Description

gridout_file

character(len = run_name_size)

"grid.out"

Name of file with output from rungridgen.

no_geo_info

logical

.false.

If false, read Rplot, Rprime, Zplot, Zprime, aplot, aprime from gridout_file.

theta_grid_gridgen_knobs

Used to represent the input configuration of theta_grid_gridgen

Name Type Default Description

alknob

real

0.0

Relative weighting of pitch-angle metric to metric

bpknob

real

1.e-8

Consider when the right grid point is equal to the target bmag.

FIXME: What does this mean?

deltaw

real

0.0

Parameter for weighted resolution in theta. Each theta grid point contributes to the resolution metric according to the function which has peaks at theta = +/- thetamax and deltaw controls the relative weighting of the theta dependent contribution.

epsknob

real

1e-5

Maximum difference between neighbouring points for determining if a point is an extremum.

extrknob

real

0.0

Used to set a "bonus" contribtion to resolution at B extrema with an even number of theta grid points. Those with an odd number of points and the assumed extrema at -pi have a metric of 1e20. Here extrknob can be used to bias the algorithm towards keeping extrema with an even number of points.

npadd

integer

2

Number of points between original grid points to oversample by

regrid_tension

real

-1.0

Tension to use in interpolating splines for regrid of geometrical quantities Defaults to tension if not set.

skip_gridgen

logical

.false.

If true then skip gridgen call and instead just use the existing grid.

tension

real

1.0

Tension for spline

thetamax

real

0.0

Parameter for weighted resolution in theta. Each theta grid point contributes to the resolution metric according to the function which has peaks at theta = +/- thetamax.

widthw

real

1.0

Parameter for weighted resolution in theta. Each theta grid point contributes to the resolution metric according to the function which has peaks at theta = +/- thetamax and widthw controls the scale length of the peaks.

theta_grid_knobs

Used to represent the input configuration of theta_grid

Name Type Default Description

cvdriftknob

real

1.0

Scales the curvature drift.

equilibrium_option

character(len = 20)

"default"

The equilibrium_option variable controls which geometric assumptions are used in the run. Additional namelists determine the geometric parameters according to the choice made here. Allowed values are:

  • 'eik' Use routines from the geometry module, controlled mainly by the subsidiary namelists theta_grid_parameters and theta_grid_eik_knob. This includes options for Miller as well as a range of different numerical equilibrium file formats.
  • 'default' Same as 'eik'
  • 's-alpha' Use high aspect-ratio toroidal equilbrium (which can be simplified to slab or cylinder), controlled by the subsidiary namelist theta_grid_parameters and theta_grid_salpha_knob
  • 'file' Use output from rungridgen code directly. Controlled by theta_grid_file_knobs. Note: in this case, the variables nperiod and ntheta (from the theta_grid_parameters namelist) are ignored.
  • 'grid.out' Same as 'file'
  • 'ncfile' Similar to 'file' but using a netcdf file input instead of ascii.

gb_to_cv

logical

.false.

If true then force grad-B drift to be equal to curvature drift. This is not recommended when fbpar is not 0.

gbdriftknob

real

1.0

Scales the grad-B drift.

theta_grid_parameters

Used to represent the input configuration of theta_grid. Sets a number of parameters used by the different theta grid implementations. Not all parameters are active for a given theta grid type.

Name Type Default Description

akappa

real

1.0

The flux surface elongation (only used when geoType=0, which selects the Generalised Miller analytic geometry specification).

akappri

real

0.0

The radial gradient flux surface elongation (only used when geoType=0, which selects the Generalised Miller analytic geometry specification). akappri =

alpmhd

real

0.0

Used in conjunction with alpmhdfac to override shift, set as shift=-alpmhd*alpmhdfac. Do not use unless you know what you are doing.

asurf

real

1.0

Minor radius of the flux surface that receives the specified shaping (only used when geoType=1, which selects the Global MHD analytic geometry specification). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

btor_slab

real

0.0

In the slab limit, determines the angle between the field and the background flow (which flows in an imaginary toroidal direction). It is effectively equal to . btor_slab = btor/bpol defines direction of a flow relative to B in slab geometry, where flow is by definition in the toroidal direction.

c0_mxh

real

0.0

Zeroth cosine moment for the MXH local equilibrum. See geoType and local_eq

c_mxh

real, dimension(mxh_max_moments)

0.0

Cosine moments for the MXH local equilibrum. See geoType and local_eq

dc_mxh_dr

real, dimension(mxh_max_moments)

0.0

Radial derivatives of cosine moments for the MXH local equilibrum. See geoType and local_eq

delta2

real

1.0

The elongation of the flux surface labeled by aSurf (only used when geoType=1, which selects the Global MHD analytic geometry specifications). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

delta3

real

1.0

The triangularity of the flux surface labeled by aSurf (only used when geoType=1, which selects the Global MHD analytic geometry specifications). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

deltam

real

1.0

The magnitude of the mMode shaping effect (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

deltampri

real

0.0

Radial derivative of the magnitude of the mMode shaping effect (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

deltan

real

1.0

The magnitude of the nMode shaping effect (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

deltanpri

real

0.0

Radial derivative of the magnitude of the nMode shaping effect (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

ds_mxh_dr

real, dimension(mxh_max_moments)

0.0

Radial derivatives of sine moments for the MXH local equilibrum. See geoType and local_eq

eps

real

0.3

Controls particle trapping (among other things) in simple geometric models.

epsl

real

0.3

Sets curvature drift in s-alpha model, where is the GS2 equilibrium reference normalisation length and is the major radius at the centre of the flux surface.

geotype

integer

0

Selects between different analytic geometry specifications (only used when local_eq = T):

  • geoType = 0: Generalised Miller
  • geoType = 1: Global MHD
  • geoType = 2: Generalised Elongation
  • geoType = 3: Fourier specification.
  • geoType = 4: Miller Extended Harmonic (MXH)

See Section 2.1 of the Analytic Geometry Specification documentation for more details on options 0-3, and PPCF 63 (2021) 012001 (5pp) for details of 4 (MXH).

kp

real

-1.0

kp sets parallel wavenumber and box length in slab geometry. .

  • always use kp instead of pk in slab geometry (if kp > 0 then gs2 sets pk = 2*kp)
  • in slab limit : nb if kp = 1, , where is the magnetic shear scale length.

mmode

integer

2

First flux surface shaping mode number (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

n_mxh

integer

0

Number of moments for the MXH local equilibrum. Maximum value is mxh_max_moments. See geoType and local_eq for more details.

nmode

integer

3

Second flux surface shaping mode number (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

nperiod

integer

2

Sets the number of segments along equilibrium magnetic field to include in simulation domain. . Ignored in some cases

ntheta

integer

24

Rough number of grid points along equilibrium magnetic field between . Actual number of grid points determined as follows:

  • number of points in GS2 theta grid always odd because grid must contain both bounce points of trapped particles and one grid point at . For even values, an extra point is added
  • theta grid in code runs from -ntgrid:ntgrid, with ntgrid=int(ntheta/2) for nperiod=1.
  • ntheta is used for local equilibria, s-alpha, and EFIT, and ignored for all other numerical equilibria

pk

real

0.3

Sets , the magnetic safety factor, and therefore also sets the connection length, i.e. the length of the box in the parallel direction, in terms of . Used only in high aspect ratio equilibrium model.

qinp

real

1.5

Sets value of the safety factor when using local toroidal equilibrium model.

r_geo

real

3.0

When not local_eq: Centerpoint of LCFS (normalized to ) - When local_eq: Major radius of magnetic field reference point (normalized to ). Specifically, the reference magnetic field is defined to be the value of the toroidal magnetic field at R=r_geo on the flux surface labeled by rhoc.

raxis

real

3.0

Major radial location of the magnetic axis (only used when geoType=1, which selects the Global MHD analytic geometry specification). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

rhoc

real

0.5

rhoc is the flux surface label (0< rhoc< 1). Its exact meaning depends on irho. Usually rho = midplane diameter/midplane diameter of LCFS (here, "LCFS" refers to the flux surface at a radius of . If using Miller geometry with , this is not the physical last closed flux surface.

  • When irho = 1, rhoc = sqrt(toroidal flux)/sqrt(toroidal flux of LCFS)
  • When irho = 2, rhoc = midplane diameter/(midplane diameter of LCFS). recommended
  • When irho = 3, rhoc = poloidal flux/(poloidal flux of LCFS)

rmaj

real

3.0

When not local_eq: Position of magnetic axis (normalized to ). When local_eq: Major radius of the centre of the flux surface of interest (normalized to )

s_mxh

real, dimension(mxh_max_moments)

0.0

Sine moments for the MXH local equilibrum. See geoType and local_eq

shat

real

0.75

Sets value of magnetic shear in simple geometric models. Over-ridden by s_hat_input in theta_grid_eik_knobs for most values of bishop.

shift

real

0.0

shift is related to minor radial derivatives of the major radial location of the flux surface centers (i.e. the Shafranov shift), but this input variable has different physical definitions in s-alpha and other analytic equilbrium models:

  • In s-alpha (i.e. equilibrium_option='s-alpha'), shift is a parameter for local (and not which is constant):
  • In other analytic specifications (i.e. equilibrium_option='eik' and geoType=0, 2, or 3), shift is a parameter for local (and NOT for ):

NB in Miller shift contains the 1st radial derivative of the Shafranov shift, BUT in s-alpha shift is related to a 2nd radial derivative of the Shafranov shift.

  • in s-alpha(i.e. equilibrium_option='s-alpha'), no additional parameter is required as the piece of p' is specified by shift.
  • in other analytic specifications (i.e. equilibrium_option='eik'), an additional parameter(beta_prime) is required to specify the piece of p'

shiftvert

real

0.0

Minor radial derivative of the axial location of the flux surface centers (i.e. the vertical Shafranov shift). It is only used when equilibrium_option='eik' and geoType=0, 2, or 3 (which selects the Generalised Miller, Generalised Elongation, or Fourier analytic geometry specifications). See Sections 2.1.1, 2.1.3, and 2.1.4 of the Analytic Geometry Specification documentation for more details.

theta2

real

0.0

The tilt angle of the elongation of the flux surface labeled by aSurf (only used when geoType=1, which selects the Global MHD analytic geometry specification). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

theta3

real

0.0

The tilt angle of the triangularity of the flux surface labeled by aSurf (only used when geoType=1, which selects the Global MHD analytic geometry specification). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

thetad

real

0.0

The tilt angle of the triangularity (only used when geoType=0, which selects the Generalised Miller specification). See Section 2.1.1 of the Analytic Geometry Specification documentation for more details.

thetak

real

0.0

The tilt angle of the elongation (only used when geoType=0, which selects the Generalised Miller specification). See Section 2.1.1 of the Analytic Geometry Specification documentation for more details.

thetam

real

0.0

The tilt angle of the mMode shaping effect (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

thetan

real

0.0

The tilt angle of the nMode shaping effect (only used when geoType=2 or 3, which selects the Generalised Elongation or Fourier analytic geometry specifications). See Sections 2.1.3 and 2.1.4 of the Analytic Geometry Specification documentation for more details.

tri

real

0.0

The flux surface triangularity (only used when geoType=0, which selects the Generalised Miller analytic geometry specification). triangularity is tri = arcsin[(R(max(Z))-R_major)/r_mid]

tripri

real

0.0

The radial gradient of the flux surface triangularity (only used when geoType=0, which selects the Generalised Miller analytic geometry specification). tripri = dtri/drho

zaxis

real

0.0

Axial location of the magnetic axis (only used when geoType=1, which selects the Global MHD analytic geometry specification). See Section 2.1.2 of the Analytic Geometry Specification documentation for more details.

theta_grid_salpha_knobs

Used to represent the input configuration of theta_grid_salpha

Name Type Default Description

alpha1

real

0.0

Coefficient in model when model_option='alpha1' has been selected.

alpmhdfac

real

0.0

Used in conjunction with alpmhd to override shift, set as shift=-alpmhd*alpmhdfac.

model_option

character(len = 20)

"default"

Sets the particular model for the magnetic field and related drifts. NB: All options have gbdrift = cvdrift except where noted. Can be one of

  • 's-alpha' - High aspect ratio toroidal equilibrium
  • 'default' - Same as 's-alpha'
  • 'alpha1' - Mainly same as 's-alpha' but with different definition of bmag and bset
  • 'rogers' - (aka. model_eps) From ingen output: "This model differs from the normal s-alpha model only in the curv and grad_B drifts." Indeed, cvdrift and gbdrift have an extra term, -(epsl*eps), while cvdrift0 and gbdrift0 are the same as 's-alpha'
  • 'b2' - From ingen output: "This model differs from the normal s-alpha model by an additional factor of 1/B(theta)**2 in the curv and grad_B drifts." Definition of bmag is also different.
  • 'normal_only' - Different definition of cvdrift (shat and shift terms removed) and cvdrift0 set to zero. Presumably this means that only the component of the curvature drift normal to the flux surface is retained while the component on the surface is 0. Useful for picking apart the effect of parameters on drifts and the effects of drifts on other quantities such as stability.
  • 'const-curv' - From ingen output: "Constant curvature is assumed. The grad-B and curvature drifts are both = epsl", i.e. shape = 'cylinder' NB: in contradiction to ingen output, gbdrift is not equal to cvdrift since cvdrift = epsl but gbdrift = cvdrift*(1.-shift). However, gbdrift0 = cvdrift0 = 0.
  • 'no-curvature' - From ingen output "Zero curvature is assumed", i.e. shape = 'slab'. NB: cvdrift = cvdrift0 = gbdrift0 = 0 but gbdrift is not 0 (gbdrift = epsl). NB: This does not yield the same result as cvdriftknob=0 in 's-alpha' model with non-zero epsl

NB: For the final two options here ('const-curv' and 'no-curvature') (See also ingen output and contents of theta_grid.f90 for further details