gyrokinetics / gs2 / 2021218321

module diagnostics_configuration

  use abstract_config, only: abstract_config_type, CONFIG_MAX_NAME_LEN

  implicit none

  private

  public :: diagnostics_config, warn_about_nonfunctional_selection

  public :: diagnostics_config_type, set_diagnostics_config, get_diagnostics_config

  !> Used to represent the input configuration of

  !> gs2_diagnostics. This is the version used by the original

  !> diagnostics module.

  type, extends(abstract_config_type) :: diagnostics_config_type

    ! namelist : gs2_diagnostics_knobs

    ! indexed : false

    !> Append output data to a previous output file `<run name>.out.nc` if it

    !> already exists. Grid sizes must be unchanged.

    logical :: append_old = .false.

    !> Used for nonlinear convergence check

    !> ([[gs2_diagnostics_knobs:use_nonlin_convergence]]). The maximum number

    !> of time steps, after which consider the run converged regardless.

    integer :: conv_max_step = 80000

    !> Used for the nonlinear convergence check

    !> ([[gs2_diagnostics_knobs:use_nonlin_convergence]]). The minimum number

    !> of time steps before convergence condition can trigger an exit.

    integer :: conv_min_step = 4000

    !> Used for the nonlinear convergence check

    !> ([[gs2_diagnostics_knobs:use_nonlin_convergence]]). The number of

    !> timesteps the convergence condition averages over

    integer :: conv_nstep_av = 4000

    !> Used for the nonlinear convergence check

    !> ([[gs2_diagnostics_knobs:use_nonlin_convergence]]). The number of steps

    !> where convergence is true before convergence is accepted

    integer :: conv_nsteps_converged = 10000

    !> Used for the nonlinear convergence check

    !> ([[gs2_diagnostics_knobs:use_nonlin_convergence]]). Multiplier for the

    !> cumulative average of the heat flux

    real :: conv_test_multiplier = 4e-1

    !> Sets a threshold on the maximum damping rate. If all modes are more strongly

    !> damped over the entire [[gs2_diagnostics_knobs:navg]] period then the simulation

    !> will exit.

    real :: damped_threshold = -9e38

    !> Exit when the run has reached convergence

    logical :: exit_when_converged = .true.

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

    logical :: file_safety_check = .true.

    !> Index in \(\theta\) to measure various diagnostics at. By default, this

    !> is the outboard midplane \(\theta = 0\), but it may be useful to set

    !> this to a non-zero value for tearing parity modes.

    integer :: igomega = 0

    !> Write out \(\phi, A_\parallel, B_\parallel\) in real space over time,

    !> suitable for creating animations. Timestep period is controlled with

    !> [[gs2_diagnostics_knobs:nmovie]]

    !>

    !>

    !> @warning This option can write a lot of data! Consider doing the Fourier

    !> transforms of the fields in post-processing instead.

    !>

    !> @warning In new diagnostics, the timestep period is controlled with

    !> [[gs2_diagnostics_knobs:nwrite]]

    logical :: make_movie = .false.

    !> Try to create the restart directory if initial attempts to write there

    !> fail. This is supposed to help with the common mistake where a user

    !> has set [[init_g_knobs:restart_dir]] but has forgotten to create it.

    logical :: make_restart_dir = .true.

    !> Number of timesteps to average over for time-averaged diagnostics

    !>

    !> @warning Default value differs between old (100) and new (10)

    !> diagnostics

    integer :: navg = 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.

    integer :: nc_sync_freq = 10

    !> Timestep period to write real space fields \(\phi, A_\parallel,

    !> B_\parallel\)

    !>

    !> @warning Non-functional in new diagnostics. Instead use

    !> [[gs2_diagnostics_knobs:nwrite]]

    !>

    !> @warning Default value differs between old (1000) and new (-1)

    !> diagnostics

    integer :: nmovie = -1

    !> Timestep period for writing restart data if

    !> [[gs2_diagnostics_knobs:save_for_restart]] is `.true.`. Negative values

    !> disable the periodic checkpoints.

    integer :: nsave = -1

    !> Timestep period for writing outputs

    !>

    !> @warning Default value differs between old (`== 100`) and new (`== 10`)

    !> diagnostics!

    integer :: nwrite = 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?

    !>

    !> @warning Controls different diagnostics in new diagnostics

    integer :: nwrite_mult = 10

    !> If `.true.`, write moments at the outboard midplane only, as opposed to

    !> along the entire flux surface

    !>

    !> @warning Non-functional in new diagnostics

    !>

    !> @warning Default value differs between old (.true.) and new (.false.) diagnostics

    logical :: ob_midplane = .false.

    !> Only perform tests of omega behaviour (convergence etc.) once the simulation time

    !> is at least this value

    real :: omega_checks_start = 0.0

    !> Threshold complex frequency (\(\Omega\)) for detecting a numerical

    !> instability. If \(\abs(\Omega)\) averaged over

    !> [[gs2_diagnostics_knobs:navg]] timesteps is greater than `omegatinst`,

    !> abort the run.

    !>

    !> @warning Default value differs between old (1.0) and new (1.0e6)

    !> diagnostics

    real :: omegatinst = 1.0e6

    !> Frequency (\(\omega\)) convergence tolerance. Consider the simulation

    !> converged and finish the run if \(\omega\) has changed by less than

    !> `omegatol` over the last [[gs2_diagnostics_knobs:navg]] timesteps.

    !>

    !> More explicitly, the convergence criterion is:

    !>

    !> $$\sqrt{\sum_t^{n_{avg}} |\bar{\omega} - \omega|^2} < \min{\bar{\omega}, 1.0}\cdot\omega_{tol}$$

    !>

    !> where \(\bar{\omega}\) is \(\omega\) averaged over the last `navg`

    !> timesteps.

    real :: omegatol = 1e-3

    !> Print the instantaneous fluxes to screen/stdout every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    logical :: print_flux_line = .false.

    !> Print estimated frequencies and growth rates to screen/stdout every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Default value differs between old (`.true.`) and new

    !> (`.false.`) diagnostics

    logical :: print_line = .false.

    !> Write the distribution function to `<rootname>.nc.dfn.<processor>`

    !> files. Only written at end of simulation

    logical :: save_distfn = .false.

    !> Write restart files at the end of the simulation. If

    !> [[gs2_diagnostics_knobs:nsave]] is positive, then also enable

    !> checkpoints by writing restart files every `nsave` timesteps.

    logical :: save_for_restart = .false.

    !> Save some layout and distribution information in restart files

    logical :: save_glo_info_and_grids = .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

    !> [[init_g_knobs:read_many]] in order to restart from multiple files.

    logical :: save_many = .false.

    !> Save parallel and perpendicular velocities in final restart and/or

    !> distribution function files

    logical :: save_velocities = .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 [[gs2_diagnostics_knobs:conv_test_multiplier]],

    !> [[gs2_diagnostics_knobs:conv_nsteps_converged]],

    !> [[gs2_diagnostics_knobs:conv_nsteps_av]],

    !> [[gs2_diagnostics_knobs:conv_max_step]], and

    !> [[gs2_diagnostics_knobs:conv_min_step]].

    logical :: use_nonlin_convergence = .false.

    !> If `.false.`, skip writing any diagnostics

    !>

    !> @warning Only in new diagnostics

    !>

    !> @warning This also turns off checking the linear convergence

    logical :: write_any = .true.

    !> Write the entire \(A_\parallel\) field every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning New diagnostics requires

    !> [[gs2_diagnostics_knobs:write_fields]] to also be `.true.`

    !> (the default) to enable this

    logical :: write_apar_over_time = .false.

    !> 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

    logical :: write_ascii = .true.

    !> Write flux surface averaged low-order moments of \(g\) every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Prints a warning that this is ignored unless

    !> `grid_option==box`, but this doesn't appear to be the case?

    logical :: write_avg_moments = .false.

    !> Write the entire \(B_\parallel\) field every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning New diagnostics requires

    !> [[gs2_diagnostics_knobs:write_fields]] to also be `.true.`

    !> (the default) to enable this

    logical :: write_bpar_over_time = .false.

    !> Write the collision error every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps to text file with suffix `.cres`

    !>

    !> FIXME: What does this mean?

    !>

    !> @warning In new diagnostics, only writes to ascii

    !>

    !> @warning This is expensive

    logical :: write_cerr = .false.

    !> Write collisional heating (collisional and hyper viscous rate of loss of

    !> free energy for each mode) every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps

    !>

    !> @warning Only in new diagnostics

    logical :: write_collisional = .false.

    !> Write two point parallel correlation function calculated from the

    !> electric potential as a function of \(k_y\) and parallel separation

    !> every [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Default value differs between old (`.false.`) and new

    !> (`.true.`) diagnostics

    logical :: write_correlation = .true.

    !> Write two point parallel correlation function calculated from the

    !> electric potential as a function of \(k_y\) and parallel separation,

    !> time averaged and calculated along the extended domain every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps once istep > nstep/4.

    !>

    !> @warning This diagnostic can have large persistent memory cost.

    logical :: write_correlation_extend = .false.

    !> Write the cross phase between electron density and perpendicular

    !> electron temperature every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps. Calculated at both the outboard midplane, averaged across

    !> \(x\) and \(y\); and averaged across all space

    !>

    !> @warning In old diagnostics, only written to text files

    logical :: write_cross_phase = .false.

    !> Write the whole non-adiabatic part of the density moment every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Requires [[gs2_diagnostics_knobs:write_moments]] to also be

    !> `.true.`

    !>

    !> @warning Only in new diagnostics

    logical :: write_density_over_time = .false.

    !> Write \(\phi, A_\parallel, B_\parallel\) normalised to the value of

    !> \(\phi\) at the outboard midplane every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps.

    !>

    !> If [[gs2_diagnostics_knobs:write_ascii]] is enabled, the text file is

    !> `<runname>.eigenfunc`.

    !>

    !> @note The normalising factor for a given \((\theta, k_y)\) point may not

    !> be exactly \(\phi\) at the outboard midplane if this value is zero

    !> there. If the adjacent point in \(\theta\) is also zero, then the fields

    !> will be unnormalised at that \((\theta, k_y)\).

    !>

    !> @warning If this option is turned on, the same normalising factor will

    !> also be used for the text output in

    !> [[gs2_diagnostics_knobs:write_final_moments]]

    !>

    !> @warning In old diagnostics, this is only done on exit, not every

    !> `nwrite` timesteps!

    !>

    !> @warning The text output is normalised (see note above), but the netCDF

    !> output is not

    logical :: write_eigenfunc = .false.

    !> Enable writing \(\phi, A_\parallel, B_\parallel\) every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning In old diagnostics, this only writes them on exit and

    !> [[gs2_diagnostics_knobs:write_phi_over_time]],

    !> [[gs2_diagnostics_knobs:write_apar_over_time]] and

    !> [[gs2_diagnostics_knobs:write_bpar_over_time]] instead control writing

    !> the fields over time, respectively. In new diagnostics, this will disable

    !> writing all three fields if set to `.false.`

    !>

    !> @warning Default value differs between old (`.false.`) and new

    !> (`.true.`) diagnostics

    logical :: write_fields = .true.

    !> Write the right-hand sides of the field equations at the final

    !> timestep. If [[gs2_diagnostics_knobs:write_ascii]] is enabled, the file

    !> suffix is `.antot`

    logical :: write_final_antot = .false.

    !> Write \(\delta B\) at the final timestep. If

    !> [[gs2_diagnostics_knobs:write_ascii]] is enabled, the file suffix is

    !> `.db`. This is not written to netCDF!

    logical :: write_final_db = .false.

    !> Write \(E_\parallel\) at the final timestep. If

    !> [[gs2_diagnostics_knobs:write_ascii]] is enabled, the file suffix is

    !> `.epar`

    logical :: write_final_epar = .false.

    !> Write \(\phi, A_\parallel, B_\parallel\) at the final timestep. If

    !> [[gs2_diagnostics_knobs:write_ascii]] is enabled, the file suffix is

    !> `.fields`

    logical :: write_final_fields = .false.

    !> Write various moments (densities, parallel and perpendicular

    !> velocities and temperatures, and heat and momentum fluxes) at

    !> the final timestep. If [[gs2_diagnostics_knobs: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.

    !>

    !> @warning If [[gs2_diagnostics_knobs:write_eigenfunc]] is

    !> enabled, then the same normalising factor is used for the

    !> final moments. Otherwise, the moments are unnormalised.

    !>

    !> @warning The text output is normalised (see note above), but

    !> the netCDF output is not

    logical :: write_final_moments = .false.

    !> Write instantaneous fluxes to output file every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Output formats and quantities differ between old and new

    !> diagnostics

    logical :: write_flux_line = .false.

    !> Write fluxes (heat, momentum and particle; total and per-species) every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps.

    !>

    !> If run is nonlinear, this defaults to true

    !>

    !> @warning In old diagnostics, this also turns on `write_fluxes_by_mode`

    logical :: write_fluxes = .false.

    !> Write fluxes (heat, momentum and particle; total and per-species) as a

    !> function of Fourier mode every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps.

    !>

    !> If run is nonlinear, this defaults to true

    !>

    !> @warning In old diagnostics, this is combined with `write_fluxes`

    logical :: write_fluxes_by_mode = .false.

    !> Write \(g(v_\parallel,v_\perp)\) at `ik=it=is=1, ig=0` to text file

    !> `<runname>.dist`

    !>

    !> @warning Only to text files

    logical :: write_g = .false.

    !> FIXME: Add documentation

    !>

    !> @warning Only outputs to text files

    logical :: write_gs = .false.

    !> Write \(g\) as a function of real space every

    !> [[gs2_diagnostics_knobs:nmovie]] timesteps to text file

    !> "<runname>.yxdist"

    !>

    !> @warning Only to text files

    logical :: write_gyx = .false.

    !> Write out various heating, free energy and energy injection

    !> diagnostics. Text file extension is `.heat`

    logical :: write_heating = .false.

    !> Write time averaged external current in the antenna,

    !> \(\operatorname{Re}(k_\perp^2 A_\mathrm{antenna})\), as a function of

    !> \(k_x, k_y\). File suffix is `.jext`

    !>

    !> @warning Only in new diagnostics

    logical :: write_jext = .false.

    !> Calculates and writes the electrostatic drive of zonal flows

    !> every [[gs2_diagnostics_knobs:nwrite]] timesteps.  The output

    !> `kinetic_energy_transfer_theta` resolves this over \(\theta\)

    !> 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.

    logical :: write_kinetic_energy_transfer = .false.

    !> Write the parallel spectrum of \(\phi, A_\parallel,

    !> B_\parallel\) at final timestep. File suffix is `.kpar`

    !>

    !> @warning Output only to text files

    logical :: write_kpar = .false.

    !> Print estimated frequencies and growth rates to text file every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    logical :: write_line = .true.

    !> Write `antenna_w` every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps

    !>

    !> FIXME: Define `antenna_w`

    !>

    !> @warning Old diagnostics only writes to text files

    !>

    !> @warning New diagnostics only writes to netCDF

    logical :: write_lorentzian = .false.

    !> Write the estimated maximum error from velocity space

    !> integrals for various quantities

    !>

    !> @warning Old diagnostics only outputs to text file

    logical :: write_max_verr = .false.

    !> 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

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Only outputs to netCDF files

    !>

    !> @warning New diagnostics writes various averages of the moments. To get

    !> the same output as old diagnostics, **also** set

    !> [[gs2_diagnostics_knobs:write_ntot_over_time]],

    !> [[gs2_diagnostics_knobs:write_density_over_time]],

    !> [[gs2_diagnostics_knobs:write_upar_over_time]],

    !> [[gs2_diagnostics_knobs:write_tperp_over_time]] to `.true.`

    !>

    !> @warning Default value differs between old (`.false.`) and new

    !> (`.true.`) diagnostics

    logical :: write_moments = .true.

    !> Write the poloidal distributions of the fluxes of particles,

    !> parallel momentum, perpendicular momentum, and energy every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps.

    !>

    !> See section 3.1 and appendix A of [Ball et al. PPCF 58 (2016)

    !> 045023](https://doi.org/10.1088/0741-3335/58/4/045023) as well as

    !> section 5 of "GS2 analytic geometry specification"

    logical :: write_nl_flux_dist = .false.

    !> Write the whole total density moment every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Requires [[gs2_diagnostics_knobs:write_moments]] to also be

    !> `.true.`

    !>

    !> @warning Only in new diagnostics

    logical :: write_ntot_over_time = .false.

    !> Write time-averaged growth rate and frequency to the output text file

    !> every [[gs2_diagnostics_knobs:nwrite]] timesteps. Time average is

    !> rolling window over the previous [[gs2_diagnostics_knobs:navg]]

    !> timesteps

    !>

    !> @warning Non-functional in new diagnostics, time-average is also written

    !> with [[gs2_diagnostics_knobs:write_omega]] instead

    logical :: write_omavg = .true.

    !> Write instantaneous growth rate and frequency every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Old diagnostics only writes to output text file

    !>

    !> @warning New diagnostics only writes to netCDF file

    !>

    !> @warning New diagnostics also writes time-average with this

    !> option. Output is the complex frequency, rather than separate growth

    !> rate and real frequency

    logical :: write_omega = .true.

    !> Write parities in distribution and particle fluxes to text file with the

    !> suffix `.parity`

    !>

    !> FIXME: Clarify what this means

    logical :: write_parity = .false.

    !> Write the entire \(\phi\) field every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps

    !>

    !> @warning New diagnostics requires

    !> [[gs2_diagnostics_knobs:write_fields]] to also be `.true.`

    !> (the default) to enable this

    logical :: write_phi_over_time = .false.

    !> Write a simple quasi-linear metric to netcdf.

    logical :: write_ql_metric = .true.

    !> Write the particle and momentum flux as a function of \(\theta\) and

    !> velocity space. See [[gs2_diagnostics_knobs:write_pflux_sym]] and

    !> [[gs2_diagnostics_knobs:write_pflux_tormom]]

    !>

    !> @warning Only outputs to netCDF

    !>

    !> @warning Old diagnostics does not write the particle flux, use

    !> [[gs2_diagnostics_knobs:write_pflux_sym]] instead

    logical :: write_symmetry = .false.

    !> Write the whole perturbed perpendicular temperature moment every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Requires [[gs2_diagnostics_knobs:write_moments]] to also be

    !> `.true.`

    !>

    !> @warning Only in new diagnostics

    logical :: write_tperp_over_time = .false.

    !> Write the whole perturbed parallel velocity moment every

    !> [[gs2_diagnostics_knobs:nwrite]] timesteps

    !>

    !> @warning Requires [[gs2_diagnostics_knobs:write_moments]] to also be

    !> `.true.`

    !>

    !> @warning Only in new diagnostics

    logical :: write_upar_over_time = .false.

    !> Write estimates of error resulting from velocity space integrals in the

    !> calculation of various quantities every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps.

    !>

    !> @warning Output only to text file

    !>

    !> @warning New diagnostics also writes to netCDF every

    !> [[collisions_knobs:ncheck]] timesteps, along with some other

    !> quantities such as collisionality

    !>

    !> @warning This is expensive

    logical :: write_verr = .false.

    !> Write the transfer of free energy, \(\tau\), as a function of \((k_x,

    !> k_y)\), averaged over \(\theta\), every [[gs2_diagnostics_knobs:nwrite]]

    !> timesteps

    !>

    !> @warning Only in new diagnostics

    logical :: write_zonal_transfer = .false.

#include "diagnostics_overrides_and_bound_auto_gen.inc"

    procedure :: set_smart_defaults => set_smart_defaults_local

  end type diagnostics_config_type

  type(diagnostics_config_type) :: diagnostics_config

contains

  !> Prints a warning about a non-functional diagnostic

    use run_parameters, only: use_old_diagnostics

    use mp, only: proc0

    !> Diagnostic switch

    logical, intent(in) :: diagnostic_switch

    !> Name of the switch

    character(len=*), intent(in) :: name

    character(len=3) :: diagnostics_module

    else

    end if

    end if

  !> Set the smart defaults for the new_gs2_diagnostics_config_type instance

    use nonlinear_terms, only: nonlin

    use run_parameters, only: use_old_diagnostics

    implicit none

    class(diagnostics_config_type), intent(in out) :: self

    end if

    else

    end if

  end subroutine set_smart_defaults_local

  !> Set values according to the old diagnostics defaults.

  !>

  !> Will overwrite existing values, unless the config object has

  !> already been initialised, in which case returns without changing

  !> any values

    type(diagnostics_config_type), intent(inout) :: self

  end subroutine apply_old_defaults

  !> Set values according to the new diagnostics defaults.

  !>

  !> Will overwrite existing values, unless the config object has

  !> already been initialised, in which case returns without changing

  !> any values

    type(diagnostics_config_type), intent(in out) :: self

  end subroutine apply_new_defaults

#include "diagnostics_auto_gen.inc"