SpECTRE  v2024.06.05
PhaseControl Namespace Reference

Contains utilities for determining control-flow among phases. More...

Classes

struct  CheckpointAndExitAfterWallclock
 Phase control object that runs the WriteCheckpoint and Exit phases after a specified amount of wallclock time has elapsed. More...
 
struct  TagAndCombine
 A type for denoting a piece of data for deciding a phase change. More...
 
struct  TaggedTupleCombine
 A flexible combine invokable that combines into a tuples::TaggedTuple a new tuples::TaggedTuple, and combines according to type aliases combination_methods that are required to be defined in each tag. More...
 
struct  TaggedTupleMainCombine
 A flexible combine invokable that combines into a tuples::TaggedTuple a new tuples::TaggedTuple with a subset of the original tags, and combines according to type aliases main_combine_methods that are required to be defined in each tag. More...
 
struct  TriggerAndPhaseChanges
 Option-creatable pair of a trigger and associated phase change objects. More...
 
struct  VisitAndReturn
 Phase control object for temporarily visiting TargetPhase, until the algorithm halts again, then returning to the original phase. More...
 

Typedefs

using factory_creatable_classes = tmpl::list< VisitAndReturn< Parallel::Phase::EvaluateAmrCriteria >, VisitAndReturn< Parallel::Phase::AdjustDomain >, VisitAndReturn< Parallel::Phase::CheckDomain >, VisitAndReturn< Parallel::Phase::LoadBalancing >, VisitAndReturn< Parallel::Phase::WriteCheckpoint >, CheckpointAndExitAfterWallclock >
 
template<typename Metavariables >
using get_phase_change_tags = tmpl::push_back< tmpl::flatten< tmpl::transform< typename detail::phase_change_derived_classes< Metavariables >::type, detail::get_phase_change_tags_and_combines< tmpl::_1 > > >, TagsAndCombines::UsePhaseChangeArbitration, Parallel::Tags::ExitCode >
 Metafunction for determining the merged collection of tags in phase_change_tags_and_combiness from all PhaseChange derived classes in Metavariables::factory_creation
 
template<typename TagsAndCombinesPresent , typename TagsAndCombines >
using reduction_data = Parallel::ReductionData< Parallel::ReductionDatum< tuples::tagged_tuple_from_typelist< TagsAndCombinesPresent >, TaggedTupleCombine > >
 A Parallel::ReductionData with a single Parallel::ReductionDatum for a given tagged tuple type determined by TagsPresent, and performs the combine according to TagsAndCombines, which must be a tmpl::list of PhaseControl::TagAndCombines. More...
 

Enumerations

enum  ArbitrationStrategy { RunPhaseImmediately , PermitAdditionalJumps }
 The possible options for instructing the Main chare in deciding the next phase to jump to. More...
 

Functions

template<typename... DecisionTags, typename Metavariables >
std::optional< Parallel::Phasearbitrate_phase_change (const gsl::not_null< tuples::TaggedTuple< DecisionTags... > * > phase_change_decision_data, Parallel::Phase current_phase, const Parallel::GlobalCache< Metavariables > &cache)
 Use the runtime data aggregated in phase_change_decision_data to decide which phase to execute next. More...
 
template<typename... DecisionTags, typename Metavariables >
void initialize_phase_change_decision_data (const gsl::not_null< tuples::TaggedTuple< DecisionTags... > * > phase_change_decision_data, const Parallel::GlobalCache< Metavariables > &cache)
 Initialize the Main chare's phase_change_decision_data for the option-selected PhaseChanges.
 

Detailed Description

Contains utilities for determining control-flow among phases.

Typedef Documentation

◆ reduction_data

template<typename TagsAndCombinesPresent , typename TagsAndCombines >
using PhaseControl::reduction_data = typedef Parallel::ReductionData<Parallel::ReductionDatum< tuples::tagged_tuple_from_typelist<TagsAndCombinesPresent>, TaggedTupleCombine> >

A Parallel::ReductionData with a single Parallel::ReductionDatum for a given tagged tuple type determined by TagsPresent, and performs the combine according to TagsAndCombines, which must be a tmpl::list of PhaseControl::TagAndCombines.

Each tag in the TagsAndCombinesPresent may either be a TagsAndCombines or otherise define all three type traits type, combine_method, and main_combine_method.

Enumeration Type Documentation

◆ ArbitrationStrategy

The possible options for instructing the Main chare in deciding the next phase to jump to.

An object of this enum type is packaged with a requested phase in the PhaseChange::arbitrate_phase_change function.

Enumerator
RunPhaseImmediately 

Jump to the requested phase immediately, before considering other requested phases.

This will ensure that the requested phase is always run, where alternative methods could have 'double-jumps' where the Main chare replaces a requested phase immediately without actually entering the phase.

PermitAdditionalJumps 

After the requested phase is considered, continue considering other requests, potentially replacing this request.

This will permit reprocessing the phase-jumps to help with cases where multiple phases are simultaneously requested. The PermitAdditionalJumps permits 'double-jumps' where a requested phase is immediately replaced by another phase to jump to.

Function Documentation

◆ arbitrate_phase_change()

template<typename... DecisionTags, typename Metavariables >
std::optional< Parallel::Phase > PhaseControl::arbitrate_phase_change ( const gsl::not_null< tuples::TaggedTuple< DecisionTags... > * >  phase_change_decision_data,
Parallel::Phase  current_phase,
const Parallel::GlobalCache< Metavariables > &  cache 
)

Use the runtime data aggregated in phase_change_decision_data to decide which phase to execute next.

Details

This function will iterate through each of the option-created pairs of PhaseChanges, and obtain from each a std::optional<std::pair<Parallel::Phase, PhaseControl::ArbitrationStrategy>. Any std::nullopt is skipped. If all PhaseChanges provide std::nullopt, the phase will either keep its current value (if the halt was caused by one of the triggers associated with an option-created PhaseChange), or this function will return a std::nullopt as well (otherwise), indicating that the phase should proceed according to other information, such as global ordering.

In the case of a PhaseControl::ArbitrationStrategy::RunPhaseImmediately, the first such return value is immediately run, and no further PhaseChanges are queried for their input.

Note
There can be cases where multiple triggers activate, and/or multiple PhaseChange objects have data in a state for which they would request a specific phase. When multiple phases are requested, arbitration will proceed in order of appearance in the PhaseChangeAndTriggers, determined from the input file options. Therefore, if that order of execution is important for the logic of the executable, the input file ordering and ArbitrationStrategy must be chosen carefully.