File boltzmann_hmc_walk.hpp

struct BoltzmannHMCWalk
#include <boltzmann_hmc_walk.hpp>

The Hamiltonian Monte Carlo random walk, to sample from the Boltzmann distribution, i.e. e^(-c*x/T). This implementation includes adaptive step sizing, velocity persistence, and temperature scaling for improved sampling efficiency, particularly useful for simulated annealing.

Public Members

parameters param
struct parameters
template<typename ConvexBody, typename RandomNumberGenerator>
struct Walk
#include <boltzmann_hmc_walk.hpp>

The implementation of the walk

Template Parameters:

  • ConvexBody – A convex body

  • RandomNumberGenerator – A random number generator

Public Types

typedef ConvexBody::PointType Point

The matrix/vector types we use.

typedef ConvexBody::MT MT
typedef ConvexBody::VT VT
typedef Point::FT NT

Public Functions

inline Walk()

Default constructor.

inline Walk(Settings &settings)

Constructor with settings

Parameters:

settings – [in] The settings of the random walk

inline void setSettings(Settings &settings)

Change the settings

Parameters:

settings – [in] The new settings of the random walk

template<typename Point>
inline void apply(ConvexBody &convexbody, Point const &interiorPoint, const unsigned int pointsNum, std::list<Point> &points)

Samples random points from the convex body using the Boltzmann distribution

Parameters:

  • convexbody – [in] A convex body

  • interiorPoint – [in] A point in the interior of the convex body

  • pointsNum – [in] The number of points to sample

  • points – [out] The list of the sampled points

Template Parameters:

Point – class Point with NT and VT as declared above in this class

template<typename Point>
inline void getNextPoint(ConvexBody &convexbody, VT &p)

A single step of the HMC random walk with Metropolis-Hastings acceptance. The trajectory follows the Hamiltonian dynamics H = U(x) + K(v), where U(x) = c*x/T (potential energy) and K(v) = 0.5*||v||^2 (kinetic energy).

Parameters:

  • convexbody – [in] A convex body

  • p – [inout] An interior point, updated to the next point in the random walk

Template Parameters:

Point –

inline void setTemperature(NT temperature)

Sets the temperature in the distribution

Parameters:

temperature – [in] New value of temperature (must be positive)

inline NT getStepSize() const

Gets the current effective step size (including temperature scaling)

Returns:

The current step size

inline NT getAcceptanceRate() const

Gets the current acceptance rate of the Metropolis-Hastings test

Returns:

The acceptance rate (between 0 and 1)

inline void setAdaptationEnabled(bool enabled)

Enable or disable adaptive step sizing

Parameters:

enabled – [in] True to enable, false to disable

inline void setStepScale(NT scale)

Manually set the step scale factor

Parameters:

scale – [in] The new step scale factor

inline void setMaxReflections(unsigned int maxReflections)

Set the maximum number of reflections allowed per trajectory

Parameters:

maxReflections – [in] The maximum number of reflections

Public Members

Settings settings

The parameters of the random walk.

NT current_step_scale

Adaptive step size control: current step scale factor.

NT reference_temperature

Reference temperature for relative scaling (used in simulated annealing)

NT last_temperature

Last temperature value to detect temperature changes.

unsigned int total_steps

Statistics for adaptive step sizing.

unsigned int accepted_steps
bool adapt_enabled

Flag to enable/disable adaptive step sizing.

mutable VT position_buffer

Working buffers to avoid repeated allocations.

mutable VT velocity_buffer
mutable VT acceleration_buffer
mutable VT previous_velocity

Previous velocity for velocity persistence (improves mixing)

mutable bool has_previous_velocity

Private Functions

inline VT computeTrajectoryPoint(const VT &pos, const VT &vel, const VT &acc, NT time) const

Helper function: compute position along parabolic trajectory Trajectory is x(t) = x0 + v*t + 0.5*a*t^2

Parameters:

  • pos – [in] Initial position x0

  • vel – [in] Initial velocity v

  • acc – [in] Acceleration a

  • time – [in] Time parameter t

Returns:

Position at time t

inline NT executeTrajectory(ConvexBody &body, VT &position, NT max_length, unsigned int &reflections)

Execute a Hamiltonian trajectory with boundary reflections and epsilon-inward handling. The trajectory follows x(t) = x0 + v*t + 0.5*a*t^2 until hitting the boundary, at which point the velocity is reflected.

Parameters:

  • body – [in] The convex body

  • position – [inout] Starting position, updated to final position

  • max_length – [in] Maximum trajectory length to execute

  • reflections – [out] Number of reflections that occurred

Returns:

Actual distance traveled along trajectory

Private Static Functions

template<typename Body>
static inline auto resetBodyFlags(Body &b) -> decltype(b.resetFlags(), void())

Reset body computation cache on temperature change (SFINAE pattern) This is important when the body caches computations that depend on temperature

template<typename Body>
static inline void resetBodyFlags(...)

Fallback for bodies that don’t have resetFlags method.

struct Settings
#include <boltzmann_hmc_walk.hpp>

A struct containing the parameters for the random walk.

Public Functions

template<typename Point>
inline Settings(const int walkLength, const RandomNumberGenerator &randomNumberGenerator, const Point &c, const NT temperature, const NT diameter, unsigned int reflectionsBound = 2000, NT stepScale = NT(1.0))

Constructs an object of Settings

Parameters:

  • walkLength – [in] The number of points to “burn” before keeping the following as a sample

  • randomNumberGenerator – [in] For generating random numbers

  • c – [in] The c in the distribution e^(-c*x/T)

  • temperature – [in] The T in the distribution

  • diameter – [in] The diameter of the convex body

  • reflectionsBound – [in] Maximum number of reflections allowed per step

  • stepScale – [in] Initial step size scaling factor (default 1.0)

Returns:

An instance of this struct

inline Settings()

Public Members

int walk_length

The number of points to “burn” before keeping the following as a sample.

RandomNumberGenerator randomNumberGenerator

For generating random numbers.

VT c

The c in the Boltzmann distribution e^(-c*x/T)

NT temperature

The temperature T in the distribution.

NT diameter

The diameter of the convex body.

unsigned int reflectionsBound

Set the maximum number of allowed reflections at each step.

NT initial_step_scale

Initial step size scale factor (will be adapted during sampling)