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:

Since: Changed in Tomographer 5.0: Added the WalkerParams member type and obsoleted StepRealType.

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 ... WalkerParams: A user type describing parameters of the random walk jump process, such as the step size. This is likely to be a double or some floating-point type to store just the step size. This type should be streamable using C++ streams, this is used for logging & debugging.

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:

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, const WalkerParams& walker_params): 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.

: This jump function should honor the specified walker_params, which is the value passed to the constructor of the Tomographer::MHRWParams class. The parameters may be dynamically adjusted with a MHRWController Interface, so MHWalker implementations should not assume that the parameters won't change from one call of jumpFn() to another.

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 does not have to provide the member functions fnVal() or fnLogVal(), nor does it have to provide the type FnValueType.