#include <triqs/mc_tools/mc_generic.hpp>

Detailed Description

template<DoubleOrComplex MCSignType>
class triqs::mc_tools::mc_generic< MCSignType >

Generic Monte Carlo class.

This class provides a generic Monte Carlo simulation framework. It allows to register MC moves and measures that fulfill the triqs::mc_tools::MCMove and triqs::mc_tools::MCMeasure concepts, respectively. Additionally, one can register auxiliary measures that are callable objects (see triqs::mc_tools::measure_aux).

Most MC simulations consist of two phases:

warmup phase: No measurements are done during this phase. It is used to equilibrate the underlying Markov chain and to optionally calibrate the MC moves.
accumulation phase: This phase is used to accumulate measurements. The Markov chain is assumed to be already warmed up such that it generates MC configurations distrubuted according to the desired probability distribution.

Both phases follow the same overall procedure:

while not stop_flag do
  for i in 1..cycle_length do
    perform a Metropolis accept/reject step to update MC configuration;
  end
  perform after-cycle duties, e.g. measurements, calibration, etc.;
  update stop_flag;
end

As you can see, a cycle consists of cycle_length MC steps each of which does a single Metropolis accept/reject step. The after-cycle duties depend on the phase of the simulation and on input parameters. For example, in the accumulation phase, measurements are performed after each cycle, while in the warmup phase, moves might be calibrated to optimize the sampling procedure.

The simulation stops when one of the following conditions is met:

The number of requested cycles is done (if the number is \( < 1 \), the simulation runs indefinitely).
A user provided callback function returns true.
A signal is caught by the signal handler provided in triqs/utility/signal_handler.hpp.
An exception is caught.

Template Parameters

MCSignType Type of the sign/weight of a MC configuration (triqs::mc_tools::DoubleOrComplex).

Definition at line 96 of file mc_generic.hpp.

Classes
struct	run_param_t
	User-provided MC simulation parameters for the run() method. More...

Public Member Functions
	mc_generic (const std::string &rng_name, int rng_seed, int verbosity_lvl)
	Construct a generic Monte Carlo class.
int	accumulate (run_param_t const &params)
	Run the accumulations phase of the MC simulation.
int	accumulate (std::int64_t ncycles, std::int64_t cycle_length, std::function< bool()> stop_callback, mpi::communicator c=mpi::communicator{})
	Run the accumulation phase of the MC simulation.
template<typename T>
auto	add_measure (T &&m, std::string name, bool enable_timer=true, bool enable_report=false)
	Register a new MC measure.
template<typename T>
void	add_measure_aux (std::shared_ptr< T > const &m_ptr)
	Register a new auxiliary MC measure.
template<typename T>
void	add_move (T &&m, std::string name, double weight=1.0)
	Register a new MC move.
void	clear_measures ()
	Remove all registered measures.
void	collect_results (mpi::communicator const &c)
	Collect results from multiple MPI processes.
std::map< std::string, double >	get_acceptance_rates () const
	Get the acceptance rates of all MC moves (see move_set::get_acceptance_rates).
double	get_accumulation_time () const
	Get the time spent in the accumulation phase in seconds.
std::string	get_accumulation_time_HHMMSS () const
	Get the time spent in the accumulation phase in hours, minutes and seconds.
int	get_config_id () const
	Get the ID of the current MC configuration.
int	get_current_cycle_number () const
	Get the number of cycles done.
double	get_duration () const
	Get the total time, i.e. the sum of the warmup and accumulation times, in seconds.
int	get_nmeasures () const
	Get the number of measurements done.
double	get_percent () const
	Get the percentage of the requested number of cycles done.
random_generator &	get_rng ()
	Get a reference to the random number generator.
auto	get_run_params () const
	Get the default run parameters.
MCSignType	get_sign () const
	Get the current sign of the MC configuration.
double	get_total_time () const
	Get the total time, i.e. the sum of the warmup and accumulation times, in seconds.
double	get_warmup_time () const
	Get the time spent in the warmup phase in seconds.
auto	get_warmup_time_HHMMSS () const
	Get the time spent in the warmup phase in hours, minutes, and seconds.
void	rm_measure (typename measure_set< MCSignType >::measure_itr_t const &it)
	Remove a registered MC measure.
int	run (run_param_t const &params)
	Run a generic MC simulation.
int	run (std::int64_t ncycles, std::int64_t cycle_length, std::function< bool()> stop_callback, bool enable_measures, mpi::communicator c=mpi::communicator{}, bool enable_calibration=false)
	Run a generic MC simulation.
void	set_verbosity (int v)
	Set the verbosity level.
int	warmup (run_param_t const &params)
	Run the warumup phase of the MC simulation.
int	warmup (std::int64_t ncycles, std::int64_t cycle_length, std::function< bool()> stop_callback, MCSignType initial_sign, mpi::communicator c=mpi::communicator{})
	Run the warumup phase of the MC simulation.
int	warmup (std::int64_t ncycles, std::int64_t cycle_length, std::function< bool()> stop_callback, mpi::communicator c=mpi::communicator{})
int	warmup_and_accumulate (std::int64_t ncycles_warmup, std::int64_t ncycles_acc, std::int64_t cycle_length, std::function< bool()> stop_callback, MCSignType initial_sign, mpi::communicator c=mpi::communicator{})
	Run the warumup and accumulation phases of the MC simulation.
int	warmup_and_accumulate (std::int64_t ncycles_warmup, std::int64_t ncycles_acc, std::int64_t cycle_length, std::function< bool()> stop_callback, mpi::communicator c=mpi::communicator{})

Friends
void	h5_read (h5::group g, std::string const &name, mc_generic &mc)
	Read the MC simulation object from HDF5.
void	h5_write (h5::group g, std::string const &name, mc_generic const &mc)
	Write the MC simulation object to HDF5.

Constructor & Destructor Documentation

◆ mc_generic()

template<DoubleOrComplex MCSignType>

triqs::mc_tools::mc_generic< MCSignType >::mc_generic	(	const std::string &	rng_name,
		int	rng_seed,
		int	verbosity_lvl )

inline

Construct a generic Monte Carlo class.

Parameters

rng_name	Name of the RNG to be used (see triqs::mc_tools::random_generator).
rng_seed	Seed for the RNG.
verbosity_lvl	Verbosity level (see triqs::utility::report_stream).

Definition at line 174 of file mc_generic.hpp.

Member Function Documentation

◆ accumulate() [1/2]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::accumulate ( run_param_t const & params )

Run the accumulations phase of the MC simulation.

Measurements are always enabled and calibration is always disabled, even if the corresponding parameters are set to true.

Parameters

params User-provided MC simulation parameters (see run_param_t).

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 193 of file mc_generic.cpp.

◆ accumulate() [2/2]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::accumulate	(	std::int64_t	ncycles,
		std::int64_t	cycle_length,
		std::function< bool()>	stop_callback,
		mpi::communicator	c = mpi::communicator{} )

Run the accumulation phase of the MC simulation.

Parameters

ncycles	Number of accumulation cycles to run ( \( < 1 \) to run indefinitely).
cycle_length	Number of MC steps per cycle ( \( > 0 \)).
stop_callback	Callback function to check if the simulation should be stopped (returns true to stop).
c	MPI communicator.

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 226 of file mc_generic.cpp.

◆ add_measure()

template<DoubleOrComplex MCSignType>

template<typename T>

auto triqs::mc_tools::mc_generic< MCSignType >::add_measure	(	T &&	m,
		std::string	name,
		bool	enable_timer = true,
		bool	enable_report = false )

inline

Register a new MC measure.

Template Parameters

T	triqs::mc_tools::MCMeasure type.

Parameters

m	MC measure to register.
name	Name of the measure.
enable_timer	Enable the timer in the measure::accumulate and measure::collect_results methods.
enable_report	Enable the measure::report method.

Returns: Iterator to the registered measure.

Definition at line 206 of file mc_generic.hpp.

◆ add_measure_aux()

template<DoubleOrComplex MCSignType>

template<typename T>

void triqs::mc_tools::mc_generic< MCSignType >::add_measure_aux ( std::shared_ptr< T > const & m_ptr )

inline

Register a new auxiliary MC measure.

Template Parameters

T	Type of the auxiliary measure.

Parameters

m_ptr Shared pointer to the auxiliary MC measure to register.

Definition at line 216 of file mc_generic.hpp.

◆ add_move()

template<DoubleOrComplex MCSignType>

template<typename T>

void triqs::mc_tools::mc_generic< MCSignType >::add_move	(	T &&	m,
		std::string	name,
		double	weight = 1.0 )

inline

Register a new MC move.

Template Parameters

T	triqs::mc_tools::MCMove type.

Parameters

m	MC move to register.
name	Name of the move.
weight	Weight of the move which is proportional to its proposal probability ( \( \geq 0 \)).

Definition at line 194 of file mc_generic.hpp.

◆ collect_results()

template<DoubleOrComplex MCSignType>

void triqs::mc_tools::mc_generic< MCSignType >::collect_results ( mpi::communicator const & c )

Collect results from multiple MPI processes.

Parameters

c	MPI communicator.

Definition at line 245 of file mc_generic.cpp.

◆ rm_measure()

template<DoubleOrComplex MCSignType>

void triqs::mc_tools::mc_generic< MCSignType >::rm_measure ( typename measure_set< MCSignType >::measure_itr_t const & it )

inline

Remove a registered MC measure.

Parameters

it	Iterator to the measure to remove.

Definition at line 222 of file mc_generic.hpp.

◆ run() [1/2]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::run ( run_param_t const & params )

Run a generic MC simulation.

Parameters

params User-provided MC simulation parameters (see run_param_t).

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 48 of file mc_generic.cpp.

◆ run() [2/2]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::run	(	std::int64_t	ncycles,
		std::int64_t	cycle_length,
		std::function< bool()>	stop_callback,
		bool	enable_measures,
		mpi::communicator	c = mpi::communicator{},
		bool	enable_calibration = false )

Run a generic MC simulation.

Parameters

ncycles	Number of MC cycles to run ( \( < 1 \) to run indefinitely).
cycle_length	Number of MC steps per cycle ( \( > 0 \)).
stop_callback	Callback function to check if the simulation should be stopped (returns true to stop).
enable_measures	Enable measurements at the end of each cycle (false during warmup phase).
c	MPI communicator.
enable_calibration	Enable calibration of the moves after each cycle (false during accumulation phase).

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 203 of file mc_generic.cpp.

◆ warmup() [1/3]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::warmup ( run_param_t const & params )

Run the warumup phase of the MC simulation.

Measurements are always disabled, even if the enable_measures parameter is set to true.

Parameters

params User-provided MC simulation parameters (see run_param_t).

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 185 of file mc_generic.cpp.

◆ warmup() [2/3]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::warmup	(	std::int64_t	ncycles,
		std::int64_t	cycle_length,
		std::function< bool()>	stop_callback,
		MCSignType	initial_sign,
		mpi::communicator	c = mpi::communicator{} )

Run the warumup phase of the MC simulation.

Parameters

ncycles	Number of warumup cycles to run ( \( < 1 \) to run indefinitely).
cycle_length	Number of MC steps per cycle ( \( > 0 \)).
stop_callback	Callback function to check if the simulation should be stopped (returns true to stop).
initial_sign	Sign of the initial MC configuration.
c	MPI communicator.

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 215 of file mc_generic.cpp.

◆ warmup() [3/3]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::warmup	(	std::int64_t	ncycles,
		std::int64_t	cycle_length,
		std::function< bool()>	stop_callback,
		mpi::communicator	c = mpi::communicator{} )

The same as warmup(std::int64_t, std::int64_t, std::function<bool()>, MCSignType, mpi::communicator) but without specifying the initial sign.

Definition at line 221 of file mc_generic.cpp.

◆ warmup_and_accumulate() [1/2]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::warmup_and_accumulate	(	std::int64_t	ncycles_warmup,
		std::int64_t	ncycles_acc,
		std::int64_t	cycle_length,
		std::function< bool()>	stop_callback,
		MCSignType	initial_sign,
		mpi::communicator	c = mpi::communicator{} )

Run the warumup and accumulation phases of the MC simulation.

Parameters

ncycles_warmup	Number of warumup cycles to run ( \( < 1 \) to run indefinitely).
ncycles_acc	Number of accumulation cycles to run ( \( < 1 \) to run indefinitely).
cycle_length	Number of MC steps per cycle ( \( > 0 \)).
stop_callback	Callback function to check if the simulation should be stopped (returns true to stop).
initial_sign	Sign of the initial MC configuration.
c	MPI communicator.

Returns: 0 if the simulation has done all requested cycles, 1 if it has been stopped due to stop_callback() returned true, 2 if it has been stopped due to a signal.

Definition at line 231 of file mc_generic.cpp.

◆ warmup_and_accumulate() [2/2]

template<DoubleOrComplex MCSignType>

int triqs::mc_tools::mc_generic< MCSignType >::warmup_and_accumulate	(	std::int64_t	ncycles_warmup,
		std::int64_t	ncycles_acc,
		std::int64_t	cycle_length,
		std::function< bool()>	stop_callback,
		mpi::communicator	c = mpi::communicator{} )

The same as warmup_and_accumulate(std::int64_t, std::int64_t, std::int64_t, std::function<bool()>, MCSignType, mpi::communicator) but without specifying the initial sign.

Definition at line 240 of file mc_generic.cpp.

◆ h5_read

template<DoubleOrComplex MCSignType>

void h5_read	(	h5::group	g,
		std::string const &	name,
		mc_generic< MCSignType > &	mc )

friend

Read the MC simulation object from HDF5.

It reads the registered moves and measures as well as the number of cycles and measures that have been done and the sign of the last configuration.

Parameters

g	h5::group to be read from.
name	Name of the subgroup.
mc	MC simulation object to be read into.

Definition at line 398 of file mc_generic.hpp.

◆ h5_write

template<DoubleOrComplex MCSignType>

void h5_write	(	h5::group	g,
		std::string const &	name,
		mc_generic< MCSignType > const &	mc )

friend

Write the MC simulation object to HDF5.

It writes the registered moves and measures as well as the number of cycles and measures that have been done and the sign of the current configuration.

Parameters

g	h5::group to be written to.
name	Name of the subgroup.
mc	MC simulation object to be written.

Definition at line 379 of file mc_generic.hpp.

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

triqs/mc_tools/mc_generic.hpp
triqs/mc_tools/mc_generic.cpp

Detailed Description

Classes

Public Member Functions

Friends

Constructor & Destructor Documentation

◆ mc_generic()

Member Function Documentation

◆ accumulate() [1/2]

◆ accumulate() [2/2]

◆ add_measure()

◆ add_measure_aux()

◆ add_move()

◆ collect_results()

◆ rm_measure()

◆ run() [1/2]

◆ run() [2/2]

◆ warmup() [1/3]

◆ warmup() [2/3]

◆ warmup() [3/3]

◆ warmup_and_accumulate() [1/2]

◆ warmup_and_accumulate() [2/2]

Friends And Related Symbol Documentation

◆ h5_read

◆ h5_write