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.
Holds data pertaining to some of the main algorithm timers.
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. |
A type for storing outputs of gs2 for access externally
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 |
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
.
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 |
|
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 |
Parse some basic command line arguments. Currently just 'version' and 'help'.
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
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.
Type | Intent | Optional | 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 |
|
logical, | intent(in), | optional | :: | quiet |
If true, don't print start-up messages/header |
Initialize all the modules which are used to evolve the
equations. After calling this function, gs2 reaches init%level = full
.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
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.
Type | Intent | Optional | 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 |
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:
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state | |||
integer, | intent(in) | :: | nstep_run | |||
type(standard_header_type), | intent(in), | optional | :: | header |
Employ the eigenvalue solver to seek eigenmodes using SLEPc
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | 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.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state | |||
logical, | intent(in), | optional | :: | quiet |
If true, don't print start-up messages/header |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(initial_values_overrides_type), | intent(inout) | :: | initval_ov |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Private subroutines !!!!!!!!!!!!!!!!!!!!!!!!!!! Reset timers data to 0
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_timers_type), | intent(inout) | :: | timers |
Gets statistics of passed real value across all processes. Intended for use with our timers.
Type | Intent | Optional | 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 |
Writes the timing information statistics to optional passed unit
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_timers_type), | intent(in) | :: | timers |
Timing information |
||
integer, | intent(in), | optional | :: | report_unit |
Print timing information to standard output.
Type | Intent | Optional | 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 |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
FIXME : Add documentation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
The main entry point into GS2, runs a single GS2 simulation
Type | Intent | Optional | 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 |
|
logical, | intent(in), | optional | :: | quiet |
Optional passed through to intialize/finalize gs2 methods to suppress printing |
Finish and cleanup a complete simulation
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(gs2_program_state_type), | intent(inout) | :: | state |
An existing, initialisation simulation state |
||
logical, | intent(in), | optional | :: | quiet |
FIXME : Add documentation
Write an input file containing the current state of all input parameters
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(standard_header_type), | intent(in), | optional | :: | header |
Header for files with build and run information |