# TransientMultiApp

MultiApp for performing coupled simulations with the master and sub-application both progressing in time.

## Overview

The TransientMultiApp is designed to perform simulations with sub-applications that progress in time with the master application. A TransientMultiApp requires that your "sub-apps" use an Executioner derived from Transient.

A TransientMultiApp MultiApp objects will be taken into account during time step selection inside the "master" Transient executioner. By default, the minimum time step over the master and all sub-apps is utilized. The ability to do perform sub-cycling, which allows the sub-applications to perform multiple time steps per execution may be enabled using the "sub_cycling" parameter.

## Time state of TransientMultiApps

TransientMultiApps are "auto-advanced" by default whenever we are not doing Picard iterations between the master and sub-application. This means that the Transient::endStep and Transient::postStep methods of the sub-applications executioner are called, regardless of whether the sub-application solve fails or not. The endStep method increments the time and also performs EXEC_TIMESTEP_END output. When sub-applications are auto-advanced, their endStep call happens before the master application's endStep call. This has the important benefit that when master application output occurs, the sub-application's and master application's time states are the same, which enables MOOSE restart/recovery capability.

## Handing sub-application solve failures

As noted above, the default behavior when running TransientMultiApps is that their time state is incremented, e.g. they are "auto-advanced", regardless of whether their solve is actually successful. This is undesirable behavior, but we believe that the syncing of master and sub-application states, under normal operation, to enable correct checkpoint output is a good trade. Given the constraints of the elected design, there are still multiple ways to turn a failed sub-application solve from a warning into an exception that will force corrective behavior in either the sub- or master-application:

1. The user can set auto_advance = false in the Executioner block of the master application . This will cause the master application to immediately cut its time-step when the sub-application fails. However**, setting this parameter to false also eliminates the possibility of doing restart/recover because the master and sub will be out of sync if/when checkpoint output occurs.

2. The user can set catch_up = true in the TransientMultiApp block. This will cause the sub-application to try and catch up to the master application after a sub-app failed solve. If catch-up is unsuccessful, then MOOSE registers this as a true failure of the solve, and the master dt will then get cut. This option has the advantage of keeping the master and sub transient states in sync, enabling accurate restart/recover data.

In general, if the user wants sub-application failed solves to be treated as exceptions, we recommend that option 2 over option 1.

## Example Input File Syntax

The following input file shows the creation of a TransientMultiApp object with the time step size being governed by the master application.

[MultiApps]
[sub_app]
type = TransientMultiApp
app_type = MooseTestApp
input_files = 'dt_from_master_sub.i'
positions = '0   0   0
0.5 0.5 0
0.6 0.6 0
0.7 0.7 0'
[]
[]

(test/tests/multiapps/transient_multiapp/dt_from_master.i)

## Input Parameters

• input_filesThe input file for each App. If this parameter only contains one input file it will be used for all of the Apps. When using 'positions_from_file' it is also admissable to provide one input_file per file.

C++ Type:std::vector

Options:

Description:The input file for each App. If this parameter only contains one input file it will be used for all of the Apps. When using 'positions_from_file' it is also admissable to provide one input_file per file.

### Required Parameters

• app_typeThe type of application to build (applications not registered can be loaded with dynamic libraries. Master application type will be used if not provided.

C++ Type:MooseEnum

Options:CombinedApp CombinedTestApp

Description:The type of application to build (applications not registered can be loaded with dynamic libraries. Master application type will be used if not provided.

• bounding_box_inflation0.01Relative amount to 'inflate' the bounding box of this MultiApp.

Default:0.01

C++ Type:double

Options:

Description:Relative amount to 'inflate' the bounding box of this MultiApp.

Default:0 0 0

C++ Type:libMesh::Point

Options:

• catch_upFalseIf true this will allow failed solves to attempt to 'catch up' using smaller timesteps.

Default:False

C++ Type:bool

Options:

Description:If true this will allow failed solves to attempt to 'catch up' using smaller timesteps.

• cli_argsAdditional command line arguments to pass to the sub apps. If one set is provided the arguments are applied to all, otherwise there must be a set for each sub app.

C++ Type:std::vector

Options:

Description:Additional command line arguments to pass to the sub apps. If one set is provided the arguments are applied to all, otherwise there must be a set for each sub app.

• clone_master_meshFalseTrue to clone master mesh and use it for this MultiApp.

Default:False

C++ Type:bool

Options:

Description:True to clone master mesh and use it for this MultiApp.

• detect_steady_stateFalseIf true then while sub_cycling a steady state check will be done. In this mode output will only be done once the MultiApp reaches the target time or steady state is reached

Default:False

C++ Type:bool

Options:

Description:If true then while sub_cycling a steady state check will be done. In this mode output will only be done once the MultiApp reaches the target time or steady state is reached

• execute_onTIMESTEP_BEGINThe list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM.

Default:TIMESTEP_BEGIN

C++ Type:ExecFlagEnum

Options:NONE INITIAL LINEAR NONLINEAR TIMESTEP_END TIMESTEP_BEGIN FINAL CUSTOM

Description:The list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM.

• global_time_offset0The time offset relative to the master application for the purpose of starting a subapp at different time from the master application. The global time will be ahead by the offset specified here.

Default:0

C++ Type:double

Options:

Description:The time offset relative to the master application for the purpose of starting a subapp at different time from the master application. The global time will be ahead by the offset specified here.

• interpolate_transfersFalseOnly valid when sub_cycling. This allows transferred values to be interpolated over the time frame the MultiApp is executing over when sub_cycling

Default:False

C++ Type:bool

Options:

Description:Only valid when sub_cycling. This allows transferred values to be interpolated over the time frame the MultiApp is executing over when sub_cycling

• keep_solution_during_restoreFalseThis is useful when doing Picard. It takes the final solution from the previous Picard iterationand re-uses it as the initial guess for the next picard iteration

Default:False

C++ Type:bool

Options:

Description:This is useful when doing Picard. It takes the final solution from the previous Picard iterationand re-uses it as the initial guess for the next picard iteration

• library_nameThe file name of the library (*.la file) that will be dynamically loaded.

C++ Type:std::string

Options:

Description:The file name of the library (*.la file) that will be dynamically loaded.

• library_pathPath to search for dynamic libraries (please avoid committing absolute paths in addition to MOOSE_LIBRARY_PATH)

C++ Type:std::string

Options:

Description:Path to search for dynamic libraries (please avoid committing absolute paths in addition to MOOSE_LIBRARY_PATH)

• max_catch_up_steps2Maximum number of steps to allow an app to take when trying to catch back up after a failed solve.

Default:2

C++ Type:double

Options:

Description:Maximum number of steps to allow an app to take when trying to catch back up after a failed solve.

• max_failures0Maximum number of solve failures tolerated while sub_cycling.

Default:0

C++ Type:unsigned int

Options:

Description:Maximum number of solve failures tolerated while sub_cycling.

• max_procs_per_app4294967295Maximum number of processors to give to each App in this MultiApp. Useful for restricting small solves to just a few procs so they don't get spread out

Default:4294967295

C++ Type:unsigned int

Options:

Description:Maximum number of processors to give to each App in this MultiApp. Useful for restricting small solves to just a few procs so they don't get spread out

• move_appsApps, designated by their 'numbers' starting with 0 corresponding to the order of the App positions, to be moved at move_time to move_positions

C++ Type:std::vector

Options:

Description:Apps, designated by their 'numbers' starting with 0 corresponding to the order of the App positions, to be moved at move_time to move_positions

• move_positionsThe positions corresponding to each move_app.

C++ Type:std::vector

Options:

Description:The positions corresponding to each move_app.

• move_time1.79769e+308The time at which Apps designated by move_apps are moved to move_positions.

Default:1.79769e+308

C++ Type:double

Options:

Description:The time at which Apps designated by move_apps are moved to move_positions.

• output_in_positionFalseIf true this will cause the output from the MultiApp to be 'moved' by its position vector

Default:False

C++ Type:bool

Options:

Description:If true this will cause the output from the MultiApp to be 'moved' by its position vector

• output_sub_cyclesFalseIf true then every sub-cycle will be output.

Default:False

C++ Type:bool

Options:

Description:If true then every sub-cycle will be output.

• positionsThe positions of the App locations. Each set of 3 values will represent a Point. This and 'positions_file' cannot be both supplied. If this and 'positions_file' are not supplied, a single position (0,0,0) will be used

C++ Type:std::vector

Options:

Description:The positions of the App locations. Each set of 3 values will represent a Point. This and 'positions_file' cannot be both supplied. If this and 'positions_file' are not supplied, a single position (0,0,0) will be used

• positions_fileA filename that should be looked in for positions. Each set of 3 values in that file will represent a Point. This and 'positions' cannot be both supplied

C++ Type:std::vector

Options:

Description:A filename that should be looked in for positions. Each set of 3 values in that file will represent a Point. This and 'positions' cannot be both supplied

• print_sub_cyclesTrueToggle the display of sub-cycles on the screen.

Default:True

C++ Type:bool

Options:

Description:Toggle the display of sub-cycles on the screen.

• relaxation_factor1Fraction of newly computed value to keep.Set between 0 and 2.

Default:1

C++ Type:double

Options:

Description:Fraction of newly computed value to keep.Set between 0 and 2.

• relaxed_variablesList of variables to relax during Picard Iteration

C++ Type:std::vector

Options:

Description:List of variables to relax during Picard Iteration

• reset_appsThe Apps that will be reset when 'reset_time' is hit. These are the App 'numbers' starting with 0 corresponding to the order of the App positions. Resetting an App means that it is destroyed and recreated, possibly modeling the insertion of 'new' material for that app.

C++ Type:std::vector

Options:

Description:The Apps that will be reset when 'reset_time' is hit. These are the App 'numbers' starting with 0 corresponding to the order of the App positions. Resetting an App means that it is destroyed and recreated, possibly modeling the insertion of 'new' material for that app.

• reset_time1.79769e+308The time at which to reset Apps given by the 'reset_apps' parameter. Resetting an App means that it is destroyed and recreated, possibly modeling the insertion of 'new' material for that app.

Default:1.79769e+308

C++ Type:double

Options:

Description:The time at which to reset Apps given by the 'reset_apps' parameter. Resetting an App means that it is destroyed and recreated, possibly modeling the insertion of 'new' material for that app.

• steady_state_tol1e-08The relative difference between the new solution and the old solution that will be considered to be at steady state

Default:1e-08

C++ Type:double

Options:

Description:The relative difference between the new solution and the old solution that will be considered to be at steady state

• sub_cyclingFalseSet to true to allow this MultiApp to take smaller timesteps than the rest of the simulation. More than one timestep will be performed for each 'master' timestep

Default:False

C++ Type:bool

Options:

Description:Set to true to allow this MultiApp to take smaller timesteps than the rest of the simulation. More than one timestep will be performed for each 'master' timestep

• tolerate_failureFalseIf true this MultiApp won't participate in dt decisions and will always be fast-forwarded to the current time.

Default:False

C++ Type:bool

Options:

Description:If true this MultiApp won't participate in dt decisions and will always be fast-forwarded to the current time.

### Optional Parameters

• control_tagsAdds user-defined labels for accessing object parameters via control logic.

C++ Type:std::vector

Options:

Description:Adds user-defined labels for accessing object parameters via control logic.

• enableTrueSet the enabled status of the MooseObject.

Default:True

C++ Type:bool

Options:

Description:Set the enabled status of the MooseObject.

• implicitTrueDetermines whether this object is calculated using an implicit or explicit form

Default:True

C++ Type:bool

Options:

Description:Determines whether this object is calculated using an implicit or explicit form

• use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Default:False

C++ Type:bool

Options:

Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.