This is a ‘type interface.’ See Type Interfaces for more info on what that is.

A MHWalker compliant type describes a particular Metropolis-Hastings walk on some state space. It takes care for example of providing candidate new points (jump function), and calculating the probability ratio for the jump.

In the following documentation, \( P(x) \) designates the positive function which drives the Metropolis-Hastings random walk. The collected samples will (asymptotically) be distributed according to \( P(x) / \int P(x)\,dx \).

For instance, the Tomographer::MHRandomWalk class needs to be provided a MHWalker compliant type in order to carry out the random walk.

A type implementing the MHWalker interface must provide the following types:

typedef ... PointType: The type needed to represent a point in state space in which we are performing a random walk. An object of such type is never default-constructed, but always copy-constructed from another PointType. One should also be able to assign a PointType to another PointType (e.g. curpt = other_point).

typedef ... StepRealType: The type needed to represent a step size. This will most likely be a double or some floating-point type.

typedef ... FnValueType — required only if UseFnSyntaxType != MHUseFnRelativeValue: The return value type of the function evaluated at each point during the Metropolis-Hastings random walk. Usually this is double or some floating-point type. You do not need to provide this typedef if UseFnSyntaxType is set to MHUseFnRelativeValue.

A MHWalker must provide the following constant enumeration values:

static constexpr int UseFnSyntaxType = ...: Specifies how we calculate the function probability ratio of two points in the random walk. UseFnSyntaxType should be set to one of either Tomographer::MHUseFnValue (this class calculates the function value at each point), Tomographer::MHUseFnLogValue (this class calculates the natural logarithm of the function at each point), or Tomographer::MHUseFnRelativeValue (this class calculates the ratio of the values at two points). See below, "Role of UseFnSyntaxType".

And must provide the following members:

MHWalker(MHWalker&& other): A MHWalker type must have a move constructor.

PointType startPoint(): Should return the starting point for the random walk. This function will be called before init().

void init(): Will be called when beginning the random walk, i.e. just before the first thermalization iteration.

void thermalizingDone(): This method is called after all the thermalization sweeps have finished, and before starting with the live iterations. Typically this function shouldn't do anything, it's just provided for convenience.

void done(): Called after the random walk has been completed and all samples collected.

PointType jumpFn(const PointType & curpt, StepRealType step_size): Provide the next point where the random walk should consider jumping to. This function should return a new point depending on the current point curpt, according to some symmetric proposal distribution.

The jump function may consider using the step_size to tune the "width" of the proposal distribution. However jumpFn() is free to disregard the step_size argument. The class carrying out the random walk (such as Tomographer::MHRandomWalk) typically passes here a value which was provided to their constructor, simply for convenience.

FnValueType fnVal(const PointType & curpt): [Required only if UseFnSyntaxType == MHUseFnValue.] If UseFnSyntaxType==MHUseFnValue, this function should return the value of the function \( P(x) \) defining the random walk, evaluated at the point curpt. See below ("Role of UseFnSyntaxType").

FnValueType fnLogVal(const PointType & curpt): [Required only if UseFnSyntaxType == MHUseFnLogValue.] If UseFnSyntaxType==MHUseFnLogValue, this function should return the value of the function \( \ln P(x) \) defining the random walk, evaluated at the point curpt. See below ("Role of UseFnSyntaxType").

double fnRelVal(const PointType & newpt, const PointType & curpt): [Required only if UseFnSyntaxType == MHUseFnRelativeValue.] If UseFnSyntaxType==MHUseFnRelativeValue, this function should return the ratio \( P(\mathrm{newpt})/P(\mathrm{curpt}) \). See below ("Role of UseFnSyntaxType").

Role of UseFnSyntaxType:: In a Metropolis-Hastings random walk, the probability according to which one jumps to the next proposed point is given by the ratio of the values of the function \( P(x) \). There are three ways this class can provide this probability ratio.

You may provide the value \( P(x) \) itself. In this case, set UseFnSyntaxTYPE = Tomographer::MHUseFnValue. The class must define the member function fnVal() as described above. It doesn't have to provide the member functions fnLogVal() or fnRelVal().

You may provide the natural logarithm of the function, \( \ln P(x) \). Choose this option if it is more natural to calculate \( \ln P(x) \) instead of \( P(x) \) (for instance, if P(x) is a product of many terms). The random walk class (Tomographer::MHRandomWalk) will not calculate the exponential of the value you give, but rather the exponential of the difference of two values of \( \ln P(x) \) at two points in order to directly optain the probability ratio. In this case, set set UseFnSyntaxTYPE = Tomographer::MHUseFnLogValue. The class must define the member function fnLogVal() as described above. It doesn't have to provide the member functions fnVal() or fnRelVal().

You may directly provide the ratio of values for two points \( P(x')/P(x) \). in this case, set UseFnSyntaxTYPE = Tomographer::MHUseRelativeValue. The class must define the member function fnRelVal() as described above. It doesn't have to provide the member functions fnVal() or fnLogVal().