gs2_main Module

This module provides the external interface to gs2. It contains functions to initialize gs2, functions to run gs2, functions to finalize gs2 and functions to override/tweak gs2 parameters.

The main entry point is run_gs2, which takes care of initialising all the subsystems, solving the equations (either the time advance or eigensolver), and then finalising all the subsystems. This looks something like:

! An object holding the state of the simulationg
type(gs2_program_state_type) :: state
! Initialisation of subsystems
call initialize_gs2(state)
call initialize_equations(state)
call initialize_diagnostics(state)
! Solve the equations
if (state%do_eigsolve) then
  call run_eigensolver(state)
else
  call evolve_equations(state, state%nstep)
end if
! Clean up
call finalize_diagnostics(state)
call finalize_equations(state)
call finalize_gs2(state)

You can manipulate the gs2_program_state before running gs2.

You can also override parameters: typically this is done either before calling initialize_equations, or between two calls to evolve equations; here we manipulate the temperature gradient of the first species:

call prepare_profiles_overrides(state)
state%init%prof_ov%override_tprim(1) = .true.
state%init%prof_ov%tprim(1) = 5.5
call initialize_equations(state)
call initialize_diagnostics(state)
call evolve_equations(state, state%nstep/2)
call prepare_profiles_overrides(state)
state%init%prof_ov%tprim(1) = 6.0
call initialize_equations(state)
call evolve_equations(state, state%nstep/2)
...

It is very important to note that just because this interface is presented in an object-oriented way, it does not, unfortunately, mean that the entire program state, i.e. data arrays etc, is encapsulated in the gs2_program_state object. In fact most data is stored globally as module public variables. The gs2_program_state object is provided for convenience, as a way of monitoring the execution state of gs2, and because it is hoped that in the future gs2 will, in fact, be thread safe and have proper data encapsulation. A particular consequence of this is that only one instance of the gs2_program_state object should exist on each process, i.e. in a given memory space.



Contents


Derived Types

type, public ::  gs2_timers_type

Holds data pertaining to some of the main algorithm timers.

Components

Type Visibility Attributes Name Initial
real, public :: init(2) = 0.
real, public :: advance(2) = 0.
real, public :: timestep(2) = 0.
real, public :: finish(2) = 0.
real, public :: total(2) = 0.
real, public :: diagnostics(2) = 0.
real, public :: eigval(2) = 0.
real, public :: main_loop(2) = 0.

type, public ::  gs2_outputs_type

A type for storing outputs of gs2 for access externally

Components

Type Visibility Attributes Name Initial
real, public :: dvdrho = 0.0

The gradient of the flux tube volume wrt the flux label: related to the surface area of the flux tube

real, public :: grho = 0.0

The average gradient of the flux tube label <|grad rho|>

real, public, dimension (:), allocatable :: pflux

Particle flux by species

real, public, dimension (:), allocatable :: qflux

Heat flux by species

real, public, dimension (:), allocatable :: heat

Turbulent heating by species

real, public :: vflux

Momentum flux

type, public ::  gs2_program_state_type

The object which specifies and records the gs2 program state. Some attributes of the object, like mp_comm_external, are designed to be directly manipulated by the user, and some are designed to store program state information and be manipulated internally, like init%level.

Components

Type Visibility Attributes Name Initial
type(init_type), public :: init

A type for keeping track of the current initialization level of gs2, as well as storing all the overrides. See gs2_init::init_type for more information.

logical, public :: included = .true.

Do not set manually. If fewer than the available number of processors are being used, this is true for the processors that are active and false for those that lie idle.

type(gs2_timers_type), public :: timers

Derived type gs2_timers_type holding some of the timer data for this run.

logical, public :: exit = .false.

The exit flag is set to true by any part of the main timestep loop that wants to cause the loop to exit

logical, public :: converged = .false.

Whether the run has converged to a stationary state

logical, public :: do_eigsolve = .false.

Whether to run the eigenvalue solver or not. Set equal to the input value in intialize_equations. Typically only important for the standalone gs2 program

integer, public :: nstep

This parameter is set equal to run_parameters::nstep in initialize_equations and is the maximum number of timesteps that can be run without reinitalising the diagnostics. Do not modify. We should make this private but it is used in testing currently so we don't.

integer, public :: istep_end = 0

Gets set to the final value of istep in evolve equations. Any future calls to evolve_equations will increment this further. A call to finalize_diagnostics will set it back to 0. Note that setting this manually is NOT advised.

integer, public :: verb = 3

Verbosity at which we print out debug messages

integer, public :: external_job_id = -1

Parameters pertaining to cases when gs2 is being used as a library. external_job_id is not to be confused with the parameter job in mp, which identifies the subjob if running in list mode or with nensembles > 1

logical, public :: is_external_job = .false.

is_external_job should be set to true when GS2 is being used as a library. Perhaps this could just check external_job_id instead?

logical, public :: is_trinity_job = .false.

Set true if using trinity. This does several things: * it forces the calculation of the fluxes * it causes the species and theta_grid name lists to use parameters provided by trinity Setting this flag true automatically sets is_external_job to true

logical, public :: trinity_linear_fluxes = .false.

If true and running linearly, return linear diffusive flux estimates to Trinity.

logical, public :: trinity_ql_fluxes = .false.

If true and running linearly, return a QL flux estimate to Trinity.

logical, public :: print_full_timers = .true.

If true, print full timing breakdown.

logical, public :: print_times = .true.

If true, print run time or full timing breakdown, depending on the value of print_full_timers

integer, public :: mp_comm = mp_comm_null

1 communicator. This MUST be set.

integer, public :: nproc_actual = -1

This is set in initialize_gs2 to the number of procs actually used

logical, public :: run_name_external = .false.

If true then we end up passing run_name as the base file name.

character(len=run_name_size), public :: run_name = 'gs'

The run name to pass to init_file_utils if run_name_external is set to true. GS2 then uses this in place of any input file name passed at the command line.

logical, public :: skip_diagnostics = .false.

If true then skip the call to diagnostics calculations in evolve_equations (main loop and after main loop)

logical, public :: dont_change_timestep = .false.

If true then ignore any requests to change the time step in evolve_equations as a part of the time advance algorithm

logical, public :: list = .false.

Whether this is a list mode run

integer, public :: nensembles = 1

The number of identical runs happening simultaneously (used for ensemble averaging). Cannot be used in conjunction with list mode.

type(gs2_outputs_type), public :: outputs

Holds some outputs of interest (e.g. for Trinity)

logical, public :: set_outputs = .false.

If true, calculate and set outputs

type(optimisation_type), public :: optim

Optimisation configuration

type(exit_code), public :: exit_reason = EXIT_NOT_REQUESTED

Reason for end of simulation


Subroutines

public subroutine parse_command_line()

Parse some basic command line arguments. Currently just 'version' and 'help'.

Read more…

Arguments

None

public subroutine initialize_wall_clock_timer()

Starts the global wall clock timer used by check time. This is useful if you have multiple copies of gs2 running but you don't want to start them all at the same time, but you want them all to respect avail_cpu_time

Arguments

None

public subroutine initialize_gs2(state, header_in, header_out, quiet)

Initialise message passing, open the input file, split the communicator if running in list mode or if nensembles > 1, initialize the timers. After calling this function, gs2 reaches init\%level = basic. If it is desired to provide an external commuicator or set the input file name externally, these should be set before calling this function.

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state
type(standard_header_type), intent(in), optional :: header_in

Header for files with build and run information

type(standard_header_type), intent(out), optional :: header_out

Get the header set by this function. Useful if header_in is not used

logical, intent(in), optional :: quiet

If true, don't print start-up messages/header

public subroutine initialize_equations(state)

Initialize all the modules which are used to evolve the equations. After calling this function, gs2 reaches init%level = full.

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine initialize_diagnostics(state, header)

Initialize the diagostics modules. This function can only be called when the init level is 'full', i.e., after calling initialize_equations. However, gs2 can be partially uninitialized without finalizing the diagnostics, for example to change parameters such as the timestep.

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state
type(standard_header_type), intent(in), optional :: header

Header for files with build and run information

public subroutine evolve_equations(state, nstep_run, header)

Run the initial value solver. nstep_run must be less than or equal to state%nstep, which is set from the input file. The cumulative number of steps that can be run cannot exceed state%nstep, without a call to reset_equations. Examples:

Read more…

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state
integer, intent(in) :: nstep_run
type(standard_header_type), intent(in), optional :: header

public subroutine run_eigensolver(state)

Employ the eigenvalue solver to seek eigenmodes using SLEPc

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine reset_equations(state)

Effectively resets the state of the diagnostics and time index back to the start of the simulation. Primarily useful to allow one to reuse existing files etc. without having to start a new process. Mostly used in trinity workflows.

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine finalize_diagnostics(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine finalize_equations(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine finalize_gs2(state, quiet)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state
logical, intent(in), optional :: quiet

If true, don't print start-up messages/header

public subroutine prepare_optimisations_overrides(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine prepare_miller_geometry_overrides(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine prepare_profiles_overrides(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine prepare_kt_grids_overrides(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine prepare_initial_values_overrides(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine set_initval_overrides_to_current_vals(initval_ov)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(initial_values_overrides_type), intent(inout) :: initval_ov

public subroutine finalize_overrides(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine calculate_outputs(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

private subroutine reset_timers(timers)

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Private subroutines !!!!!!!!!!!!!!!!!!!!!!!!!!! Reset timers data to 0

Arguments

Type IntentOptional Attributes Name
type(gs2_timers_type), intent(inout) :: timers

private subroutine get_parallel_statistics(value_in, min_value, max_value, mean_value, proc0_value, iproc_min, iproc_max, values_out)

Gets statistics of passed real value across all processes. Intended for use with our timers.

Arguments

Type IntentOptional Attributes Name
real, intent(in) :: value_in
real, intent(out) :: min_value
real, intent(out) :: max_value
real, intent(out) :: mean_value
real, intent(out) :: proc0_value
integer, intent(out) :: iproc_min
integer, intent(out) :: iproc_max
real, intent(out), optional, dimension(:), allocatable :: values_out

private subroutine write_time_parallel_statistics(timers, report_unit)

Writes the timing information statistics to optional passed unit

Arguments

Type IntentOptional Attributes Name
type(gs2_timers_type), intent(in) :: timers

Timing information

integer, intent(in), optional :: report_unit

private subroutine print_times(state, timers)

Print timing information to standard output.

Read more…

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(in) :: state

Program state information, needed to print

type(gs2_timers_type), intent(in) :: timers

Timing information

private subroutine allocate_outputs(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

private subroutine deallocate_outputs(state)

FIXME : Add documentation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

public subroutine run_gs2(state, finalize, quiet)

The main entry point into GS2, runs a single GS2 simulation

Read more…

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

State of the GS2 simulation. Used to modify the behaviour of GS2 and/or to programmatically get information about the simulation on completion.

logical, intent(in), optional :: finalize

If .true. (default), then GS2 is finalised, end-of-simulation diagnostics are computed, files are closed, arrays are deallocated, and so on.

Read more…
logical, intent(in), optional :: quiet

Optional passed through to intialize/finalize gs2 methods to suppress printing

public subroutine finish_gs2(state, quiet)

Finish and cleanup a complete simulation

Arguments

Type IntentOptional Attributes Name
type(gs2_program_state_type), intent(inout) :: state

An existing, initialisation simulation state

logical, intent(in), optional :: quiet

private subroutine reset_linear_magnitude()

FIXME : Add documentation

Arguments

None

public subroutine write_used_inputs_file(header)

Write an input file containing the current state of all input parameters

Arguments

Type IntentOptional Attributes Name
type(standard_header_type), intent(in), optional :: header

Header for files with build and run information