A helper class for updating the triangulation, using Metropolis–Hastings algorithm. This is a high-level interface intended to implement a basic Monte-Carlo updating scheme, which should be sufficient for a lot of simple situations. More...

#include <MonteCarloUpdater.hpp>

Public Member Functions
	MonteCarloUpdater (fp::Triangulation &triangulation_inp, EnergyFunctionParameters const &prms_inp, EnergyFunctionType energy_function_inp, RandomNumberEngine &rng_inp, Real min_bond_length, Real max_bond_length)

bool	move_needs_undoing (Real e_diff)
	Implementation of the Metropolis algorithm.

bool	new_neighbour_distances_are_between_min_and_max_length (fp::Node const &node, fp::vec3< Real > const &displacement)
	Pre-update check to test that the update step will not result in an unphysical configuration.

bool	new_next_neighbour_distances_are_between_min_and_max_length (fp::Node const &node, fp::vec3< Real > const &displacement)
	Pre-update check to test that the update step will not result in an unphysical configuration.

bool	new_verlet_neighbour_distances_are_between_min_and_max_length (fp::Node const &node, fp::vec3< Real > const &displacement)
	Pre-update check to test that the update step will not result in an unphysical configuration.

std::optional< Real >	move_MC_updater (fp::Node const &node, fp::vec3< Real > const &displacement)
	Attempt a move Monte Carlo Step.

void	flip_MC_updater (fp::Node const &node)
	Attempt a flip Monte Carlo Step.

void	flip_MC_updater (fp::Node const &node, Index id_in_nn_ids)
	Attempt a flip Monte Carlo Step.

void	reset_kBT (Real kBT)
	Reset the temperature of the Monte Carlo updater, at which the Boltzmann weights are evaluated.

Real	kBT ()
	A getter function that returns a value of a state variable.

unsigned long	move_attempt_count () const
	A getter function that returns a value of a state variable.

unsigned long	bond_length_move_rejection_count () const
	A getter function that returns a value of a state variable.

unsigned long	move_back_count () const
	A getter function that returns a value of a state variable.

unsigned long	flip_attempt_count () const
	A getter function that returns a value of a state variable.

unsigned long	bond_length_flip_rejection_count () const
	A getter function that returns a value of a state variable.

unsigned long	flip_back_count () const
	A getter function that returns a value of a state variable.

Detailed Description

template<typename EnergyFunctionParameters, typename RandomNumberEngine>
class fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >

A helper class for updating the triangulation, using Metropolis–Hastings algorithm. This is a high-level interface intended to implement a basic Monte-Carlo updating scheme, which should be sufficient for a lot of simple situations.

Template Parameters

Real	type that will be used for all floating point numbers inside this class/struct. Any data type that satisfies the floating_point_number concept is allowed, for example, `float`.
Index	type that will be used for all integer numbers inside this class/struct. Any data type that satisfies the indexing_number concept is allowed, for example, `unsigned int`.
EnergyFunctionParameters	A user-defined struct type. An instance of this struct will be part of the input of the energy function. Energy function provided during instantiation must have a third argument of type EnergyFunctionParameters const&.
RandomNumberEngine	type of the random number engine that will be provided during the instantiation of the class. For example std::mt19937_64.
triangulation_type	One of the types specified by the TriangulationType enum. This must match the type of triangulation provided during the class instantiation.

Constructor & Destructor Documentation

◆ MonteCarloUpdater()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::MonteCarloUpdater	(	fp::Triangulation &	triangulation_inp,
		EnergyFunctionParameters const &	prms_inp,
		EnergyFunctionType	energy_function_inp,
		RandomNumberEngine &	rng_inp,
		Real	min_bond_length,
		Real	max_bond_length )

inline

Parameters

triangulation_inp	Reference to the triangulation that will be updated.
prms_inp	The instance of the struct that contains the parameters of the system energy.
energy_function_inp	A c++ function that represents the system energy. It can be evaluated for a given node for a Monte Carlo step.
rng_inp	Random number engine
min_bond_length	Minimal bond length between two triangulation nodes. More generally, a minimal distance two nodes of the triangulation are allowed to have. If set to zero, the stability of the updater will suffer, and nonphysical shapes with self-intersecting triangulation will be common.
max_bond_length	Maximal allowed length of a bond between two nodes of a triangulation. If set too high, the stability of the updater will suffer, and nonphysical shapes with self-intersecting triangulation will be common. Conversely, setting this variable too low will significantly reduce the chance of a successful bond flip.

Member Function Documentation

◆ move_needs_undoing()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

bool fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::move_needs_undoing ( Real e_diff )

inline

Implementation of the Metropolis algorithm.

This function implements the Metropolis algorithm to evaluate whether the performed move should be rejected and undone.

Returns: true if the energy difference between the old and the new states is negative (i.e., the move costs energy) and the random number is smaller than the Boltzmann Probability of accepting the move. false otherwise.

Here is the caller graph for this function:

◆ new_neighbour_distances_are_between_min_and_max_length()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

bool fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::new_neighbour_distances_are_between_min_and_max_length	(	fp::Node const &	node,
		fp::vec3< Real > const &	displacement )

inline

Pre-update check to test that the update step will not result in an unphysical configuration.

Check if both the node does not overlap with any of its Verlet list neighbors or next neighbors and that none of its connections to the next neighbors exceeds the maximal distance.

Parameters

node	The reference to the node being updated.
displacement	Displacement vector, by which the node will be moved (if the move is accepted).

Returns: true if new_next_neighbour_distances_are_between_min_and_max_length(fp::Node const&, fp::vec3<Real> const&) and new_verlet_neighbour_distances_are_between_min_and_max_length(fp::Node const&, fp::vec3<Real> const&) conditions are both satisfied, false otherwise.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ new_next_neighbour_distances_are_between_min_and_max_length()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

bool fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::new_next_neighbour_distances_are_between_min_and_max_length	(	fp::Node const &	node,
		fp::vec3< Real > const &	displacement )

inline

Pre-update check to test that the update step will not result in an unphysical configuration.

Iterate through the next neighbor distances of a node which is a collection of 3d vectors, i.e. nn_dist is of type fp::vec3. Then check if the displacement would make any of the nn_distance vectors longer than the allowed max length.

Parameters

node	The reference to the node being updated.
displacement	Displacement vector, by which the node will be moved (if the move is accepted).

Returns: true if all next neighbor distances are between minimal and maximal allowed values, provided during the instantiation of the MonteCarloUpdater class, false otherwise.

Here is the caller graph for this function:

◆ new_verlet_neighbour_distances_are_between_min_and_max_length()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

bool fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::new_verlet_neighbour_distances_are_between_min_and_max_length	(	fp::Node const &	node,
		fp::vec3< Real > const &	displacement )

inline

Pre-update check to test that the update step will not result in an unphysical configuration.

Iterate through the Verlet list neighbor distances of a node which is a collection of 3d vectors. Then check if the displacement would make any of the Verlet list neighbors move closer than the minimal allowed distance between two nodes. I.e., we check if the node would overlap with any of its Verlet list neighbors after the move. The overlap distance or the minimal allowed distance is provided during the instantiation of the class.

Parameters

node	The reference to the node being updated.
displacement	Displacement vector, by which the node will be moved (if the move is accepted).

Returns: true if the nodes did not overlap before but overlap now. false otherwise.

Here is the caller graph for this function:

◆ move_MC_updater()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

std::optional< Real > fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::move_MC_updater	(	fp::Node const &	node,
		fp::vec3< Real > const &	displacement )

inline

Attempt a move Monte Carlo Step.

A move step is attempted on the specified node. Metropolis algorithm is used to evaluate whether the move should be accepted.

Parameters

node	The reference to the node being updated.
displacement	Displacement vector, by which the node will be moved (if the move is accepted).

Returns: This function returns the calculated energy difference. If not energy difference was calculated due to bond_length constraint rejection, then an empty optional is returned.

Here is the call graph for this function:

◆ flip_MC_updater() [1/2]

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

void fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::flip_MC_updater ( fp::Node const & node )

inline

Attempt a flip Monte Carlo Step.

A flip step is attempted between a specified node and one of its randomly chosen next neighbors. Metropolis algorithm is used to evaluate whether the flip should be accepted.

Parameters

node	The reference to the node being updated. otherwise, the flippy will fail silently.

Note: This function randomly chooses the next neighbor of the node and flips the edge between them. If more precise control is required, i.e., if it is necessary to control exactly which edge needs to be flipped, then the flip_MC_updater(fp::Node const& node, Index id_in_nn_ids) method can be used.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ flip_MC_updater() [2/2]

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

void fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::flip_MC_updater	(	fp::Node const &	node,
		Index	id_in_nn_ids )

inline

Attempt a flip Monte Carlo Step.

A flip step is attempted between a specified node and its specified next neighbor. Metropolis algorithm is used to evaluate whether the flip should be accepted.

Parameters

node	The reference to the node being updated.
id_in_nn_ids	This id must be part of the Node::nn_ids vector of the node provided in the first argument , otherwise, the flippy will fail silently.

Warning: For performance reasons, this function does not check if id_in_nn_ids is really a nn_id of the node provided in the first argument. The user is required to guarantee this fact. Otherwise, flippy will fail unpredictably. flip_MC_updater(fp::Node const&) is the safer method if the user does not care exactly which bond is flipped.

Here is the call graph for this function:

◆ reset_kBT()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

void fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::reset_kBT ( Real kBT )

inline

Reset the temperature of the Monte Carlo updater, at which the Boltzmann weights are evaluated.

Parameters

kBT	input value of new temperature. The internal private data member `kBT_` that contains the current value of temperature will be overwritten with this input.

Here is the call graph for this function:

◆ kBT()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

Real fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::kBT ( )

inlinenodiscard

A getter function that returns a value of a state variable.

Monte Carlo Updater requires a kBT value in the calculation of the rejection probability of a random move.

Returns: the state of the kBT value of the updater.

See also: move_needs_undoing()

Here is the caller graph for this function:

◆ move_attempt_count()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

unsigned long fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::move_attempt_count ( ) const

inlinenodiscard

A getter function that returns a value of a state variable.

Every time a move is attempted, a private internal state variable move_attempt is incremented by move_MC_updater(). This variable can be used for diagnostics or statistical tracking, but its state does not impact the function of the updater.

Returns: current state of move_attempt.

See also: move_needs_undoing()

◆ bond_length_move_rejection_count()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

unsigned long fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::bond_length_move_rejection_count ( ) const

inlinenodiscard

A getter function that returns a value of a state variable.

Moves that cause nodes to overlap with their Verlet list neighbors or move them too far away from any of their next neighbors are rejected. Every time such rejection happens, a private internal state variable bond_length_move_rejection is incremented by move_MC_updater(). The specifics of this rejection criteria are calculated in the function new_neighbour_distances_are_between_min_and_max_length(fp::Node const& node, fp::vec3<Real> const& displacement) Every time a node move would lead that node to have a bond with one of its next neighbors, which is longer than a specified maximal length (max_bond_length()), the move will be rejected. This variable can be used for diagnostics or statistical tracking, but its state does not impact the function of the updater.

Returns: current state of bond_length_move_rejection.

See also: move_needs_undoing()

◆ move_back_count()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

unsigned long fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::move_back_count ( ) const

inlinenodiscard

A getter function that returns a value of a state variable.

Every time a move is rejected because the energy requirement was not satisfied, a private internal state variable move_back is incremented by move_MC_updater(). This variable does not track the rejections resulting from bond length restriction violations. This variable can be used for diagnostics or statistical tracking, but its state does not impact the function of the updater.

Returns: current state of move_back.

See also: move_needs_undoing() bond_length_move_rejection_count()

◆ flip_attempt_count()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

unsigned long fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::flip_attempt_count ( ) const

inlinenodiscard

A getter function that returns a value of a state variable.

Every time a flip is attempted, a private internal state variable flip_attempt is incremented by flip_MC_updater() and flip_MC_updater(fp::Node const& node, Index index_in_nn_ids). This variable can be used for diagnostics or statistical tracking, but its state does not impact the function of the updater.

Returns: current state of flip_attempt.

◆ bond_length_flip_rejection_count()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

unsigned long fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::bond_length_flip_rejection_count ( ) const

inlinenodiscard

A getter function that returns a value of a state variable.

If a flip would turn a valid bond into a bond that is too long, the flip is rejected, a private internal state variable bond_length_flip_rejection is incremented by flip_MC_updater() and flip_MC_updater(fp::Node const& node, Index index_in_nn_ids). The rejection of flips is handled by the Triangulation class itself and reported through the BondFlipData to the flip functions of the updater. This variable can be used for diagnostics or statistical tracking, but its state does not impact the function of the updater.

Returns: current state of bond_length_flip_rejection.

See also: Triangulation::flip_bond(Index, Index, Real, Real) Triangulation::unflip_bond(Index, Index, BondFlipData const&)

◆ flip_back_count()

template<typename EnergyFunctionParameters , typename RandomNumberEngine >

unsigned long fp::MonteCarloUpdater< EnergyFunctionParameters, RandomNumberEngine >::flip_back_count ( ) const

inlinenodiscard

A getter function that returns a value of a state variable.

Every time a flip is rejected because the energy requirement was not satisfied, a private internal state variable flip_back is incremented by flip_MC_updater() and flip_MC_updater(fp::Node const& node, Index index_in_nn_ids). The rejection of flips is handled by the Triangulation class itself and reported through the BondFlipData to the flip functions of the updater. This variable does not track the rejections resulting from bond length restriction violations. This variable can be used for diagnostics or statistical tracking, but its state does not impact the function of the updater.

Returns: current state of flip_back.

See also: Triangulation:: unflip_bond(Index node_id, Index nn_id, BondFlipData const& common_nns) bond_length_flip_rejection_count()

The documentation for this class was generated from the following file:

flippy/MonteCarloUpdater.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ MonteCarloUpdater()

Member Function Documentation

◆ move_needs_undoing()

◆ new_neighbour_distances_are_between_min_and_max_length()

◆ new_next_neighbour_distances_are_between_min_and_max_length()

◆ new_verlet_neighbour_distances_are_between_min_and_max_length()

◆ move_MC_updater()

◆ flip_MC_updater() [1/2]

◆ flip_MC_updater() [2/2]

◆ reset_kBT()

◆ kBT()

◆ move_attempt_count()

◆ bond_length_move_rejection_count()

◆ move_back_count()

◆ flip_attempt_count()

◆ bond_length_flip_rejection_count()

◆ flip_back_count()