MHRWController Interface

An instance of this type can be given additional control over a Metropolis-Hastings random walk (Tomographer::MHRandomWalk), by dynamically adjusting the parameters of the random walk, and by dynamically controlling how many thermalization and live run sweeps are to be carried out.

You can use Tomographer::MHRWNoController if you don't need to dynamically adjust the parameters of the random walk.

Multiple compatible controllers can be combined using Tomographer::MHRWMultipleControllers. For instance, you can have a step size dynamically adjusted during thermalization with Tomographer::MHRWStepSizeController, and then have the random walk stop after enough samples thanks to a Tomographer::MHRWValueErrorBinsConvergedController.

Since

The MHRWController type interface was introduced in Tomographer 5.0.

A MHRWController compliant type should provide the following constant public member value (e.g., as an enum):

enum { AdjustmentStrategy = ... }

Specify how often the parameters of the random walk should be adjusted. The value should be a value in the Tomographer::MHRWControllerAdjustmentStrategy enum.

One should also provide the following member functions:

void init(MHRWParamsType & params, const MHWalker & mhwalker, const MHRandomWalkType & mhrw)

Called before starting the random walk. References to the MHWalker Interface (mhwalker) and to the Tomographer::MHRandomWalk instance (mhrw) are provided.

The params may be modified if desired (e.g. to check for inconsistencies). However bear in mind that the controller may be paired with other controllers using a Tomographer::MHRWMultipleControllers, in which case all controllers' init() function will be called, so don't rely on the parameters not being modified between this init() callback and future other callbacks (such as adjustParams()).

void thermalizingDone(MHRWParamsType & params, const MHWalker & mhwalker, const MHRandomWalkType & mhrw)

Called after the thermalization has finished. The params may be modified if desired. References to the MHWalker Interface (mhwalker) and to the Tomographer::MHRandomWalk instance (mhrw) are provided.

The params may be modified if desired (e.g. to check for inconsistencies). However bear in mind that the controller may be paired with other controllers using a Tomographer::MHRWMultipleControllers, in which case all controllers' thermalizingDone() function will be called, so don't rely on the parameters not being modified between this callback and future other callbacks (such as adjustParams()).

template<bool IsThermalizing, bool IsAfterSample> inline void adjustParams(MHRWParamsType & params, const MHWalker & mhwalker, CountIntType iter_k, const MHRandomWalkType & mhrw)

This function is responsible for adjusting the random walk paramters (see MHWalker Interface) stored in params (it should update the params in place). As convenience a reference to the MHWalker Interface (mhwalker) and to the Tomographer::MHRandomWalk instance (mhrw), as well as the iteration number iter_k, are provided. The iteration number iter_k is reset to zero after thermalization runs.

The template parameter IsThermalizing is set to true during the thermalization sweeps. The parameter IsAfterSample is set to true if this function is called upon processing a live sample. If IsAfterSample==true, then necessarily IsThermalizing==false.

If the AdjustmentStrategy includes both the MHWalkerParamsAdjustEveryIteration and MHWalkerParamsAdjustEverySample bits, then while running, the callback adjustParams(...) will be called twice for the points that correspond to live samples: once after the iteration move, and once after processing the sample.

More involved informaton (accept events, current point, etc.) are not provided here. If the parameters are to be adjusted based on some statistics taken on the random walk (which is usually the case), you should use a MHRWStatsCollector and point your controller to that stats collector to get its information. For example, look at Tomographer::MHRWMovingAverageAcceptanceRatioStatsCollector and Tomographer::MHRWStepSizeController.

Only those template instantiations of adjustParams<...>() corresponding to the flags set in the AdjustmentStrategy need to be defined. For instance, if the AdjustmentStrategy is set to MHWalkerParamsDoNotAdjust (because, for instance, you only need to use the allowDoneThermalization() or allowDoneRuns() callback), then you do not need to define adjutsParams() at all.

bool allowDoneThermalization(const MHRWParamsType & params, const MHWalker & mhwalker, CountIntType iter_k, const MHRandomWalkType & mhrw)

This function is called after the prescribed number of thermalization sweeps has finished. If the return value is true, then the random walk proceeds to the live run sweeps. If the return value is false, then the random walk remains in thermalization mode, while calling allowDoneThermalization() again after each sweep, until it returns true, before proceeding to the live runs.

This function is not allowed to modify the params. [Rationale: see Tomographer::MHRWMultipleControllers]

bool allowDoneRuns(const MHRWParamsType & params, const MHWalker & mhwalker, CountIntType iter_k, const MHRandomWalkType & mhrw)

This function is called after the prescribed number of live run sweeps (the runs where we process samples, after all thermalization is done) has finished. If the return value is true, then the random walk ends. If the return value is false, then the random walk continues to run and process samples, while calling allowDoneRuns() again after each sweep, until it returns true, before finishing. The iteration number iter_k counts the run iterations only, not the thermalization ones.

This function is not allowed to modify the params. [Rationale: see Tomographer::MHRWMultipleControllers]