# tem_convergence_module Module

This module contains type definition and routines for convergence to decide steady state status.

convergence may be a single table with the definition of the convergence parameters or it might be a table of tables with each holding the definition of a convergence criterion.

The general convergence definition looks like this:

  convergence = {
variable = {'density', 'pressure'},
time_control = {
min = 0,
max = {sim = 10.0},
interval = {iter = 1}
},
shape = {kind='all'},
reduction = {'average', 'average'},
norm = 'average',
nvals = 10,
absolute = true,
condition = {
{threshold = 1.e-15, operator = '<=' },
{threshold = 1.e-12, operator = '<=' }
}
}


variable needs to be a list of variables from the variable system, providing the quantities that are to checked for convergence.

time_control needs to be a time control definition, see tem_timeControl_module it defines the timespan within which the convergence check should be active. Its interval setting describes when to perform the necessary operations to decide whether a steady state is reached.

shape needs to be shape definition to describe a subsection of the overall domain in which the check for convergence is to be done (might be {kind='all'} to take the complete simulation domain into account. See tem_shape_module for more details.

reduction needs to be a table of spatial reduction definitions for each variable. Typical reduction operations could be average, sum and l2norm. This reduction is applied to obtain a single value for the convergence decision across all elements within the domain section defined by shape. See tem_reduction_spatial_module for more details.

norm describes how to treat the spatially reduced values over time. There are two options: 'simple' will just compare the current value with the one from the last check. 'average' will build the average over the nvals last values that have been obtained via the spatial reduction. Default of this setting is to use the simple comparison.

nvals is a setting used if norm = 'average' and sets the size of the sliding window in the historical data across which an average will be made to obtain the value to compare against in the current check.

absolute denotes whether to use an absolute or relative measure to make the comparisons provided in the condition setting. The default is false that which results in a relative measure. Relative means here, that the difference of the current value and the comparison value is checked against the threshold multiplied with the current value instead of using the threshold itself directly.

use_get_point indicates whether to use individual points to obtain the values or whole elements. Default is false, so the complete state of elements in the shape will be used to find the reduced values.

ndofs describes how many degrees of freedom to use from elements if use_get_point is false. The default is to use all degrees of freedom, which can be indicated by setting ndofs = -1.

condition needs to be table providing the condition under which convergence is assumed for each variable. The condition is defined by a threshold and an operator. See tem_condition_module for details.

Convergence is assumed if all variables defined in the convergence table meet their defined definition. To check for convergence a reduction and condition has to be defined for each variable that is to be considered for the steady state check.

## Variables

TypeVisibilityAttributesNameInitial
integer, private, parameter:: norm_simple =1

Convergence norm kinds

integer, private, parameter:: norm_average =2

## Interfaces

• ### private subroutine tem_convergence_dump_vector(me, outUnit)

Dumps array of convergence to given unit

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me(:)

convergence to write into the lua file

integer, intent(in) :: outUnit

unit to write to

• ### private subroutine tem_convergence_dump_single(me, outUnit)

Dump single convergence to given unit

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me

convergence to write into the lua file

integer, intent(in) :: outUnit

unit to write to

• ### private subroutine tem_convergence_out_vector(me, conf)

Allows the output of array of convergence to lua out

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me(:)

convergence to write into the lua file

type(aot_out_type), intent(inout) :: conf

aotus type handling the output to the file in lua format

• ### private subroutine tem_convergence_out_single(me, conf, level)

Allows the output of the single convergence to lua out.

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me

convergence to write into the lua file

type(aot_out_type), intent(inout) :: conf

aotus type handling the output to the file in lua format

integer, intent(in), optional :: level

to dump variable with key or without key

• ### private subroutine Copy_convergence(left, right)

This function provides the assignment operator of two convergence. Temporary Solution as CRAY compiler dont have = Operator Copying a convegence object (right) into other convergence (left)

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(out) :: left

convegence to copy to

type(tem_convergence_type), intent(in) :: right

convegence to copy from

## Derived Types

### type, public :: tem_convergence_type

The convergence type which contains convergence flag and an instance of the condition type

#### Components

TypeVisibilityAttributesNameInitial

integer, private :: norm_kind

norm kind

real(kind=rk), private, allocatable:: lastState(:,:)

state field holding the reference values for the nScalars size: nLastVals, nScalars

integer, private :: nChecks

number of performed convergence checks corresponds to the entry in the lastState array

type(tem_comm_env_type), private :: proc

Process description to use for the output. Might be only a subset of the global communicator

type(tem_varMap_type), private :: varMap

Contains name and position of variables in global varSys

type(tem_subTree_type), private :: subTree

sub-tree resulting from the elements within the convergence shape The sub-tree also holds the sub-communicator

integer, private :: chunkSize

number of elements that fit in the buffer

integer, private :: nChunks

number of chunks per output

integer, private :: nDofs

The number of dofs for each scalar variable of the equation system

type(tem_reduction_spatial_type), private, allocatable:: redSpatial(:)

spatial reduction for each variable

Convergence description loaded from config file

#### Components

TypeVisibilityAttributesNameInitial
character(len=labelLen), private :: norm

convergence kind

integer, private :: nConditions

number of defined conditions

type(tem_condition_type), private, allocatable:: cond(:)

An instance of the condition type for each variable

integer, private :: nLastVals

Number of last values to check for convergence

logical, private :: absoluteError

absolute Error (.true.) or relative Error( .false.)

character(len=labelLen), private, allocatable:: varName(:)

array of variable labels to check for convergence

integer, private :: nRequestedVars

number of variables to check for convergence i.e size(varName)

type(tem_timeControl_type), private :: timeControl

stores time control parameters

type(tem_shape_type), private, allocatable:: geometry(:)

convergence shapes

type(tem_reduction_spatial_config_type), private :: redSpatial_config

reduction config

logical, private :: useGetPoint

Logic to decide to use get_point or get_element to dump data

integer, private :: nDofs

Number of dofs to check for convergence if useGetPoint = .false.

## Functions

### private function evaluate_residual(me, state, iScalar) result(res)

evaluate the residual For relative errors (defined in convergence%absoluteError ), the result is divided by the current status value

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout) :: me

Convergence description

real(kind=rk), intent(in) :: state

Spatially reduced variable value

integer, intent(in) :: iScalar

Current scalar

#### Return Value real(kind=rk)

residual to check for convergence

## Subroutines

Load the convergence definition table The convergence object must be part of a convergence object, for which the format has been set to format = 'convergence' In the convergence table, you then must define a norm:

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(out), allocatable:: me(:)

list of the convergence entities to create

type(flu_state) :: conf

general control parameters handle of the lua config file

integer, optional :: parent

if the convergence table is a child-table of some other table, use the parent as a reference

Steady flag in abort_criteria to check for convergence

### public subroutine tem_init_convergence(me, tree, varSys, bc_prop, globProc, stencil, nDofs)

Initialize the convergence subtreee

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout), allocatable:: me(:)

convergence descriptions

type(treelmesh_type), intent(in) :: tree

Global mesh from which the elements are identified and then stored to sub-meshes inside the convergences

type(tem_varSys_type), intent(in) :: varSys

solver-provided variable systems

type(tem_BC_prop_type), intent(in) :: bc_prop

bc property that used to identify elements of certain BCs

type(tem_comm_env_type), intent(in) :: globProc

Process description to use.

stencil used to create subTree of boundary type

integer, intent(in), optional :: nDofs

The number of dofs for each scalar variable of the equation system

### public subroutine tem_convergence_reset(me)

This routine resets convergence lastState and nChecks

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout) :: me(:)

convergence descriptions

### public subroutine tem_convergence_check(me, time, status, varSys, tree)

This routine runs over each convergence object and check for convergence of each requested quantities timeControl is active on current time

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout), target:: me(:)

convergence descriptions

type(tem_time_type), intent(in) :: time

current simulation time

type(tem_status_type), intent(inout) :: status

Status bits

type(tem_varSys_type), intent(in) :: varSys

global variable system

type(treelmesh_type), intent(in) :: tree

global tree

Read the convergence variables from convergence subtables defined in configuration from the main lua file

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(out) :: me

list of the convergence entities to create

type(flu_state) :: conf

handle of the lua config file

integer, intent(in) :: sub_handle

table sub-handle for the convergence table

### private subroutine tem_convergence_check_element(me, time, status, varSys, tree, res)

This routine runs over convergence check using get_element interface

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout), target:: me

convergence descriptions

type(tem_time_type), intent(in) :: time

current simulation time

type(tem_status_type), intent(inout) :: status

Status bits

type(tem_varSys_type), intent(in) :: varSys

global variable system

type(treelmesh_type), intent(in) :: tree

global tree

real(kind=rk), intent(out) :: res(:)

Output data size: io_buffer_size

### private subroutine tem_convergence_check_point(me, time, status, varSys, tree, res)

This routine runs over convergence check using get_point interface

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout), target:: me

convergence descriptions

type(tem_time_type), intent(in) :: time

current simulation time

type(tem_status_type), intent(inout) :: status

Status bits

type(tem_varSys_type), intent(in) :: varSys

global variable system

type(treelmesh_type), intent(in) :: tree

global tree

real(kind=rk), intent(out) :: res(:)

Output data size: io_buffer_size

### private subroutine tem_convergence_evaluate(me, achieved)

Evaluate if the convergence was achieved

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(inout) :: me

Convergence description contians

logical, intent(out) :: achieved

is all Scalars in current convergence_type are converged

### private subroutine tem_convergence_dump_vector(me, outUnit)

Dumps array of convergence to given unit

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me(:)

convergence to write into the lua file

integer, intent(in) :: outUnit

unit to write to

### private subroutine tem_convergence_dump_single(me, outUnit)

Dump single convergence to given unit

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me

convergence to write into the lua file

integer, intent(in) :: outUnit

unit to write to

### private subroutine tem_convergence_out_vector(me, conf)

Allows the output of array of convergence to lua out

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me(:)

convergence to write into the lua file

type(aot_out_type), intent(inout) :: conf

aotus type handling the output to the file in lua format

### private subroutine tem_convergence_out_single(me, conf, level)

Allows the output of the single convergence to lua out.

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(in) :: me

convergence to write into the lua file

type(aot_out_type), intent(inout) :: conf

aotus type handling the output to the file in lua format

integer, intent(in), optional :: level

to dump variable with key or without key

### private subroutine Copy_convergence(left, right)

This function provides the assignment operator of two convergence. Temporary Solution as CRAY compiler dont have = Operator Copying a convegence object (right) into other convergence (left)

#### Arguments

TypeIntentOptionalAttributesName
type(tem_convergence_type), intent(out) :: left

convegence to copy to

type(tem_convergence_type), intent(in) :: right

convegence to copy from