ALPS Input

This is a reference for the key input parameters used by ALPS.

Namelists in execution input files.

The following namelists and associated input parameters are read in by ALPS from the input file.

&system

General system parameters.

profile_startup Optional logical in &system, default .false.. When enabled, rank 0 reports elapsed wall time in seconds using MPI_Wtime. This includes

• VDF input,
• original-grid processing,
• relativistic preparation (if applicable),
• spline matrix/solve/evaluation,
• postprocessing,
• diagnostic output,
• analytic-continuation fitting, and total
• VDF startup before the first dispersion calculation.

Species timings are summed. The total starts after parameter input and includes MPI distribution and harmonic/Bessel setup. Normalization and derivatives are completed before diagnostic output; their time is included in postprocessing. Fitting time includes its diagnostic output. These are wall times, not CPU times, and detailed reporting is independent of writeOut.

kperp
Initial perpendicular wavevector $k_{\perp} d_{ref}$.

kpar
Initial parallel wavevector $k_{\parallel} d_{ref}$.

nspec
Number of plasma species.

nroots
Number of dispersion solutions to find and follow.

use_map
Choice of:

• True: Searching for roots over a map in complex frequency space (see &maps_1 namelist).
• False: Input nroots guesses for solutions (see &guess_1 namelist).

writeOut
Write or suppress output to screen.

nperp
Perpendicular momentum space resolution, $N_{\perp}$. The input file must have $N_{\perp}+1$ values spanning parallel momentum space.

npar
Parallel momentum space resolution, $N_{\parallel}$. The input file must have $N_{\parallel}+1$ values spanning parallel momentum space.

vA
Reference Alfven velocity, normalized to the speed of light, $v_{A,ref}/c$.

arrayName
Name of input array, located in 'distribution' folder.

Bessel_zero
Maximum amplitude of Bessel function to determine nmax.

secant_method
Selection for root finding method. 0: secant method from NHDS 1: rtsec method from PLUME 2: Improved secant method to reduce oscillations around solutions.

numiter
Maximum number of iterations in secant method.

kperp_norm
Choice of:

• True: Follow's Stix (10-57) normalization convention.
• False: Multiplies Stix (10-57) by $k_{\perp}^2 d_{ref}^2$.

Depending on the user's choice of normalization, D_threshold needs to be adjusted to account for additional factors of $k_{\perp}^6 d_{ref}^6$.

D_threshold
Minimum threshold for secant method.

D_prec
Size of bounding region for secant method.

D_gap
Size of allowable difference between roots.

D_tol
Tolerance for secant method = 1, rtsec.

positions_principal
Number of parallel momentum steps distant from the resonant momentum included in the numerical calculation of Eqn 3.5, $M_{I}$.

n_resonance_interval
How many steps should be used to integrate around the resonance, $M_{P}$, used for integrating near poles (see section 3.1).

Tlim
Threshold for analytical principal-value integration, $t_{\mathrm{lim}}$.

maxsteps_fit
Maximum number of fitting iterations.

lambda_initial_fit
Inital Levenberg-Marquardt damping parameter.

lambdafac_fit
Adjustment factor for Levenberg-Marquardt damping parameter.

epsilon_fit
Convergence for Levenberg-Marquardt fit.

fit_check
If true, output fitted functions for each species to file in distribution directory.

determine_minima
If true, after map search, determine minima and refine solutions.

scan_option
Select case for wavevector scans:

• 1: Consecutive scans along input paths in wavevector space,
• 2: Double scan over wavevector plane.

n_scan
Number of wavevector scans.
0 turns off wavevector scans.
Must be 1 or larger for scan_option=1.
Must be set to 2 for scan_option=2.

&relativistic_params

Optional settings shared by all relativistic species. ALPS reads this group only when any &spec_* block sets relat=T, after reading all species and before sizing fit arrays. The group may appear anywhere in the file; its header is case-insensitive, may be indented, and may have assignments on the same line. Only one active block is allowed. A present malformed or truncated block is an error, not a request to use defaults.

&relativistic_params
  ngamma = 500
  npparbar = 500
  rel_cache = 'auto'
  rel_cache_dir = 'distribution/'
/

The cache is a reusable snapshot of the completed relativistic interpolation. ALPS still reads the original ASCII VDF, but with rel_cache='auto' it first checks whether it has already calculated the transformed grids, normalized distribution, and derivatives for those inputs. These arrays are saved in a binary file, which preserves every floating-point bit without rounding values into ASCII text. The long filename is an automatically generated fingerprint of the VDF contents, interpolation settings, and computational build. Matching inputs can reuse the same file across runs or species; changing relevant inputs produces a different fingerprint. Before loading, ALPS checks compatibility and a checksum to detect damage. If the cache is missing or invalid, ALPS simply calculates the interpolation again and saves a fresh copy. Your original VDF files remain the authoritative inputs, and fitting and dispersion calculations continue normally.

An absent or empty group uses ngamma=100, npparbar=200, rel_cache='off', and rel_cache_dir='distribution/'. Partial groups retain defaults for omitted fields. When no species is relativistic, the entire group is ignored, including validation.

ngamma Relativistic momentum space resolution, $N_{\Gamma}$. Requires ngamma >= 2 when a relativistic species is present.

npparbar Relativistic parallel momentum space resolution, $N_{\bar{p}_{\parallel}}$. Requires npparbar >= 4 to keep the existing three-point resonance stencil in the interior.

rel_cache Optional &relativistic_params character parameter, default 'off'. Modes are case-insensitive:

• 'off': construct the relativistic representation normally, without cache identity or file access.
• 'auto': load a fully validated entry, or construct and save one on a miss.
• 'refresh': construct every relativistic species and atomically replace its entry.

rel_cache_dir Optional &relativistic_params character parameter, default 'distribution/'. The directory must already exist. Only rank 0 accesses entries. Missing/unwritable storage, incompatible entries, and integrity failures fall back to normal calculation. Invalid modes are input errors. Existing relativistic diagnostic files are still written, including on cache hits and when writeOut=.false.. Analytic-continuation fitting is always performed normally.

Entries are identified by numerical VDF contents, coordinates, construction settings, and strict executable/library compatibility, independently of filenames and species indices.

&guess_m

Initial guess of complex frequency for $m$th solution.
Only used when use_map=.false.
Need to have number of name lists equal to nroots.

g_om
Guess for real solution $\omega_{r}/\Omega_{ref} $.

g_gam
Guess for imaginary solution $\gamma/\Omega_{ref} $.

&maps_1

Range of complex frequencies for map_scan subroutine.
Only used when use_map=.true.

loggridw
Linear (F) or Log (T) spacing for $\omega_{r}/\Omega_{ref}$ map search. Spacing automatically calculated between omi and omf.

loggridg
Linear (F) or Log (T) spacing for $\gamma/\Omega_{ref}$ map search. Spacing automatically calculated between gami and gamf

omi
Smallest $\omega_{r}/\Omega_{ref}$ value for complex map search.

omf
Largest $\omega_{r}/\Omega_{ref}$ value for complex map search.

gami
Smallest $\gamma/\Omega_{ref}$ value for complex map search.

gamf
Largest $\gamma/\Omega_{ref}$ value for complex map search.

ni
Number of $\gamma/\Omega_{p}$ points in frequency grid.

nr
Number of $\omega_{r}/\Omega_{ref}$ points in frequency grid.

&spec_j

Species parameters list for distribution $f_{j}$. The first species is set as the reference.

nn
Relative density $n_{j}/n_{ref}$.

qq
Relative charge $q_{j}/q_{ref}$.

mm
Relative mass $m_{j}/m_{ref}$.

ff
Number of fitted functions for analytical continuation calculation.

relat
Treat $f_{j}$ as non-relativistic or relativistic.

log_fit
Use linear or $\log_{10}$ fitting routine.

use_bM
Use actual numerical integration (F) or bi-Maxwellian/cold-plasma proxy via NHDS routines, with parameters read in from &bM_spec_j namelist.

AC_method
Choose the method for the evaluation of the analytic continuation:

• 0: Use the function that is defined analytically in distribution/distribution_analyt.f90
• 1: Use the fit routine as defined in the &ffit_j_k namelist.
• 2: Use a polynomial basis representation as defined in the &poly_spec_j namelist. This method should only be used if $|\gamma|\ll |\omega_{r}|$.

&ffit_j_k

Initial Fit Values for species $j$, function $k$.

fit_type_in
Kind of fit function:

• 1: Maxwellian,

$$F_M(\hat{p}\_{\parallel})=u_{1}\mathrm{exp}[-y{\hat{p}}^2\_{\perp}-u_{2}(\hat{p}\_{\parallel}-u_{3})^2]$$

• 2: Kappa,

$$F_{\kappa}(\hat{p}\_{\parallel})=u_{1}[1+u_2({\hat{p}}\_{\parallel}-u_{3})^2+yu_{5} {\hat{p}}^2\_{\perp}]^{u_{4}}.$$

• 3: Juettner with $p_{\perp},p_{\parallel}$,

$$F_{J}(\hat{p}\_{\perp},\hat{p}\_{\parallel})= u_{1}\mathrm{exp}\left[-u_{2}\sqrt{1+\frac{\hat{p}^2\_{\perp}+(\hat{p}^2\_{\parallel}-u_3)^2 v_A^2}{m_{j}^2 c^2}}\right].$$

• 4: Juettner with variable $\Gamma$, constant $\bar{p}_{\parallel}$,

$$F_{J}(\Gamma)= u_{1} \mathrm{exp}[-y \Gamma].$$

• 5: Juettner with $p_{\perp},p_{\parallel}$; variable $\bar{p}_{\parallel}$,

$$F_{\kappa}(\hat{p}\_{\perp},\hat{p}\_{\parallel})=u_{1}\mathrm{exp}[-y \hat{p}\_{\perp}]\mathrm{exp}[-u_{2}*(\hat{p}\_{\parallel}-u_{3})^2].$$

• 6: Bi-Moyal distribution

$$F_{bMo}(\hat{p}\_{\perp},\hat{p}\_{\parallel})= u_{1} \mathrm{exp}[0.5 (y u_4 \hat{p}^2\_{\perp} + u_{2} (\hat{p}\_{\parallel} -u_{3})^2 -\mathrm{exp}(y u_{4} \hat{p}^2\_{\perp} + u_{2} (\hat{p}\_{\parallel}-u_{3})^2) )].$$

fit_1-fit_5
Fit parameters, $u_{1}$ - $u_{5}$, defined in the above equations for each of the types of fit functions. Not all parameters will be used for all functions.
Suggested values for parameters generated by generate_distribution.

perpcorr
This parameter, $y$ in Eqn. B1, compensates for the strong $p_{\perp}$ dependence of $u_1$, making the fit more reliable.

&bM_spec_j

Bi-Maxwellian/cold-plasma parameters; for species j. Only used if use_bM=T.

bM_nmaxs
Maximum number of resonances to consider.

bM_Bessel
Precision threshold for $I_n$.

bM_betas
$\beta_{\parallel,j}$ of bi-Maxwellian distribution $f_{j}$. If this variable is set to 0.d0, then the code will treat the given species with the susceptibility from cold-plasma theory.

bM_alphas
$T_{\perp,j}/T_{\parallel,j}$ of bi-Maxwellian distribution $f_{j}$.

bM_pdrifts
Relative drift of bi-Maxwellian distribution $f_{j}$ or the cold plasma species in units of $m_{ref} v_{A,ref}$.

&poly_spec_j

Input for the polynomial representation of the input distribution for the analytical continuation. Only used if AC_method=2.

kind
Type of the basis polynomial:

• 1: Chebychev

order
Maximum order of the basis polynomial.

log_max
When using logfit for the polynomial representation, set all output values to zero if the log(fit_function_poly) is greater than this variable.

derivative_type
Controls how derivative in Landau integral is performed when using polynomial expansion for the analytic continuation of $f$.

• 0: Finite Difference Derivative
• 1: Analytic Derivative of Polynomial Basis Function

&scan_input_l

Inputs for scanning parameter space for $l$th scan.

scan_type
Type of parameter scan:

• 0: Current value of $\textbf{k}$ to $k_{\perp}$=swi and $k_{\parallel}$ =swf.
• 1: $\theta_0 \rightarrow \theta_1$ at fixed $|k|$ from current value of $\theta=\mathrm{atan}(k_{\perp}/k_{\parallel})$ to swf.
• 2: Wavevector scan at fixed angle $\theta_{k,B}$ to $|k|$ =swf.
• 3: $k_{\perp}$ scan with constant $k_{\parallel}$ to $k_{\perp}$=swf.
• 4: $k_{\parallel}$ scan with constant $k_{\perp}$ to $k_{\parallel}$=swf.

swi
Scan variable to define end of scan through wavevector space (only for scan_type=1).

swf
Scan variable to define end of scan through wavevector space.

swlog
Use $\log_{10}$ (T) or linear (F) spacing.

ns
Number of output scan values.

nres
Resolution between output scan values.

heating
Calculates heating rates if true.

eigen
Calculates eigenfunctions if true.

Namelists in distribution input files.

The following namelists and associated input parameters are read in by the routine generate_distribution from input files. This generates nspec arrays of distributions that are read in by ALPS

&system

General system parameters.

nspec

Number of plasma species.

beta

Reference plasma beta.

vA

Reference Alfven velocity, normalized to the speed of light, $v_{A,ref}/c$.

nperp

Perpendicular momentum space resolution, $N_{\perp}$. The input file will have $N_{\perp}+1$ values spanning parallel momentum space. Set the same values of nperp in both the distribution input file and ALPS execution input file.

npar

Parallel momentum space resolution, $N_{\parallel}$. The input file will have $N_{\parallel}+1$ values spanning parallel momentum space. Set the same values of npar in both the distribution input file and ALPS execution input file.

maxP

Maximum value of reference Alfven momentum, $m_{ref} v_{A,ref}$.

writeName

Name of output arrays.

&spec_j

ms_read

Mass ratio $m_j/m_{ref}$.

taus

Temperature ratio $T_{\parallel,j}/T_{\parallel,ref}$.

alphs

Temperature anisotropy $T_{\perp,j}/T_{\parallel,j}$.

ps

Normalized drift momentum $m_j v_{drift}/m_{ref} v_{A,ref}$.

kappas

$\kappa$ index. Only used if distribution=2.

distributions

Type of distribution:

• 0: Use distribution from distribution_analyt.
• 1: Bi-Maxwellian distribution.
• 2: Bi-Kappa distribution.
• 3: Anisotropic Juettner distribution.
• 4: Bi-Moyal distribution.

autoscaleS

If autoscaleS=.true., define maximum momentum for each array automatically using global value maxP.

maxPperpS

If autoscaleS=.false., force maximum perpendicular momentum for species array.

maxPparS

If autoscaleS=.false., force maximum parallel momentum for species array.