Tomographer  v5.4
Tomographer C++ Framework Documentation
Tomographer Namespace Reference

Base namespace for the Tomographer project. More...

Namespaces

 DenseDM
 Main implementation for densely represented density matrices.
 
 Logger
 Tomographer's Logging Framework
 
 MAT
 Utilities and helpers for reading MATLAB .mat files.
 
 MathTools
 General math routines.
 
 MHRWAcceptRatioWalkerParamsControllerDefaults
 Default parameters for MHRWAcceptRatioWalkerParamsController.
 
 MHRWTasks
 Definitions for running multiple Metropolis-Hastings random walks, and collecting statistics over the visited samples.
 
 MultiProc
 Definitions for multi-processing classes and helpers.
 
 Tools
 Various useful tools.
 

Classes

class  AggregatedHistogramSimple
 Histogram aggregator, if each histogram doesn't have error bars. More...
 
class  AggregatedHistogramWithErrorBars
 Histogram aggregator, if each individual histogram already has error bars. More...
 
class  AveragedHistogram
 Combines several histograms (with same parameters) into an averaged histogram. More...
 
class  BinningAnalysis
 Simple binning analysis for determining error bars. More...
 
struct  BinningAnalysisParams
 Group template parameters for BinningAnalysis. More...
 
struct  BinningErrorBarConvergenceSummary
 Brief summary of convergence of error bars from a binning analysis. More...
 
class  Histogram
 Stores a histogram. More...
 
struct  HistogramParams
 The parameters of a Histogram. More...
 
class  HistogramWithErrorBars
 Stores a histogram along with error bars. More...
 
class  MHRandomWalk
 A Metropolis-Hastings Random Walk. More...
 
class  MHRWAcceptRatioWalkerParamsController
 Basic functionality for a MHRWController Interface to adjust MHWalkerParams based on keeping the acceptance ratio within a required range. More...
 
struct  MHRWControllerInvoker
 Helper class to invoke a MHRWController Interface 's callbacks. More...
 
class  MHRWMovingAverageAcceptanceRatioStatsCollector
 
class  MHRWMultipleControllers
 A MHRWController Interface which combines several independent random walk controllers. More...
 
struct  MHRWParams
 Specify the parameters of a Metropolis-Hastings random walk. More...
 
struct  MHRWStatsCollectorNoResult
 An empty struct used as a ResultType in MultipleMHRWStatsCollector for stats collectors which don't really produce results. More...
 
struct  MHRWStatusReport
 Status Report structure representing the status of a MHRandomWalk. More...
 
class  MHRWStepSizeController
 A MHRWController Interface dynamically adjusting the step size to keep a good acceptance ratio. More...
 
class  MHRWValueErrorBinsConvergedController
 A MHRWController Interface which stops the random walk after enough samples have been taken to make all bins of a histogram have converged error bars. More...
 
struct  MHWalkerParamsStepSize
 An MHWalkerParams type which just stores a step size. More...
 
class  MultipleMHRWStatsCollectors
 A simple MHRWStatsCollector interface which combines several stats collectors. More...
 
class  MultiplexorValueCalculator
 A ValueCalculator implementation which the choice of which ValueCalculator to use at run-time. More...
 
class  PeriodicStatusReportMHRWStatsCollector
 A "stats collector" which produces status reports periodically. More...
 
class  PredStatusReportMHRWStatsCollector
 A "stats collector" which produces status reports whenever a predicate evaluates to true. More...
 
class  ValueHistogramMHRWStatsCollector
 A StatsCollector which builds a histogram of values calculated with a ValueCalculator for each data sample point. More...
 
class  ValueHistogramWithBinningMHRWStatsCollector
 Collect a histogram of values from a MH random walk, with binning analysis. More...
 
struct  ValueHistogramWithBinningMHRWStatsCollectorParams
 Traits-like class for ValueHistogramWithBinningMHRWStatsCollector. More...
 
struct  ValueHistogramWithBinningMHRWStatsCollectorResult
 Result type of a ValueHistogramWithBinningMHRWStatsCollector. More...
 

Typedefs

template<typename Scalar_ = double>
using UniformBinsHistogramParams = HistogramParams< Scalar_ >
 
template<typename Scalar_ , typename CountType_ = int>
using UniformBinsHistogram = Histogram< Scalar_, CountType_ >
 
template<typename Scalar_ , typename CountType_ = double>
using UniformBinsHistogramWithErrorBars = HistogramWithErrorBars< Scalar_, CountType_ >
 
typedef MHRWMultipleControllers MHRWNoController
 A MHRWController Interface which does not adjust anything. More...
 
typedef MultipleMHRWStatsCollectors TrivialMHRWStatsCollector
 Trivial, NO-OP stats collector. More...
 

Enumerations

enum  
 
enum  MHRWControllerAdjustmentStrategy
 Describe how frequently the parameters of the random walk should be dynamically adjusted. More...
 
enum  BinningConvergence
 Convergence status of binning error bar. More...
 

Functions

template<typename HistogramType >
void histogramPrettyPrint (std::ostream &str, const HistogramType &histogram, int max_width=0)
 pretty-print the given histogram. More...
 
template<typename HistogramType >
std::string histogramPrettyPrint (const HistogramType &histogram, int max_width=0)
 Utility to display histograms for humans. More...
 
template<typename HistogramType >
int histogramShortBar (std::ostream &str, const HistogramType &histogram, bool log_scale=true, int max_width=0)
 Format the histogram as a one-line bar. More...
 
template<typename HistogramType >
std::string histogramShortBar (const HistogramType &histogram, bool log_scale=true, int max_width=0)
 Format the histogram as a one-line bar. More...
 
template<typename HistogramType >
void histogramShortBarWithInfo (std::ostream &str, std::string head, const HistogramType &hist, std::string tail, bool log_scale=true, int full_max_width=0)
 Format the histogram as a one-line bar, with some surrounding info. More...
 
template<typename HistogramType >
std::string histogramShortBarWithInfo (std::string head, const HistogramType &hist, std::string tail, bool log_scale=true, int full_max_width=0)
 Format the histogram as a one-line bar, with some surrounding info. More...
 
template<typename StepRealType >
std::ostreamoperator<< (std::ostream &stream, MHWalkerParamsStepSize< StepRealType > p)
 
template<typename CountIntType , typename MHWalkerParams >
std::ostreamoperator<< (std::ostream &str, const MHRWParams< MHWalkerParams, CountIntType > &p)
 
template<typename... MHRWControllerTypes>
MHRWMultipleControllers< MHRWControllerTypes... > mkMHRWMultipleControllers (MHRWControllerTypes &... controllers)
 Convenience function to create a MHRWMultipleControllers (using template argument deduction) More...
 
std::ostreamoperator<< (std::ostream &stream, const BinningErrorBarConvergenceSummary &s)
 
template<typename IterCountIntType , typename LocalLoggerType >
int sanitizeBinningLevels (int binning_num_levels, IterCountIntType n_run, IterCountIntType samples_last_level, LocalLoggerType &logger)
 Utility for sanitizing/determining number of binning levels. More...
 
template<typename... MHRWStatsCollectors>
MultipleMHRWStatsCollectors< MHRWStatsCollectors... > mkMultipleMHRWStatsCollectors (MHRWStatsCollectors &... mhrwstatscollectors)
 Convenience function to create a MultipleMHRWStatsCollector (using template argument deduction) More...
 
template<typename ValueCalculator_ , typename LoggerType = Logger::VacuumLogger, typename HistogramType_ = Histogram<typename ValueCalculator_::ValueType>>
ValueHistogramMHRWStatsCollector< ValueCalculator_, LoggerType, HistogramType_ > mkValueHistogramMHRWStatsCollector (typename HistogramType_::Params hist_params, ValueCalculator_ valcalc, LoggerType &logger)
 Helper to easily instantiate a ValueHistogramMHRWStatsCollector. More...
 
template<typename ValueCalculator_ , typename CountIntType_ = int, typename CountRealAvgType_ = double, int NumTrackValues_ = Eigen::Dynamic, int NumLevels_ = Eigen::Dynamic, typename LoggerType = Tomographer::Logger::VacuumLogger>
ValueHistogramWithBinningMHRWStatsCollector< ValueHistogramWithBinningMHRWStatsCollectorParams< ValueCalculator_, CountIntType_, CountRealAvgType_, NumTrackValues_, NumLevels_ >, LoggerType > mkValueHistogramWithBinningMHRWStatsCollector (HistogramParams< typename ValueCalculator_::ValueType > hist_params, ValueCalculator_ valcalc, int num_binning_levels, LoggerType &logger)
 Helper to easily instantiate a ValueHistogramWithBinningMHRWStatsCollector. More...
 
template<typename MHRWParamsType , typename MHRWMovingAverageAcceptanceRatioStatsCollectorType_ , typename BaseLoggerType_ >
MHRWStepSizeController< MHRWMovingAverageAcceptanceRatioStatsCollectorType_, BaseLoggerType_, typename MHRWParamsType::MHWalkerParams::StepRealType, typename MHRWParamsType::CountIntType > mkMHRWStepSizeController (const MHRWMovingAverageAcceptanceRatioStatsCollectorType_ &accept_ratio_stats_collector_, BaseLoggerType_ &baselogger_, double desired_accept_ratio_min_=MHRWAcceptRatioWalkerParamsControllerDefaults::DesiredAcceptanceRatioMin, double desired_accept_ratio_max_=MHRWAcceptRatioWalkerParamsControllerDefaults::DesiredAcceptanceRatioMax, double acceptable_accept_ratio_min_=MHRWAcceptRatioWalkerParamsControllerDefaults::AcceptableAcceptanceRatioMin, double acceptable_accept_ratio_max_=MHRWAcceptRatioWalkerParamsControllerDefaults::AcceptableAcceptanceRatioMax, double ensure_n_therm_fixed_params_fraction_=MHRWAcceptRatioWalkerParamsControllerDefaults::EnsureNThermFixedParamsFraction)
 
template<typename IterCountIntType_ = int, typename ValueHistogramWithBinningMHRWStatsCollectorType_ = void, typename BaseLoggerType_ = void>
MHRWValueErrorBinsConvergedController< ValueHistogramWithBinningMHRWStatsCollectorType_, IterCountIntType_, BaseLoggerType_ > mkMHRWValueErrorBinsConvergedController (const ValueHistogramWithBinningMHRWStatsCollectorType_ &value_stats_collector_, BaseLoggerType_ &baselogger_, IterCountIntType_ check_frequency_sweeps_=1024, Eigen::Index max_allowed_unknown_=0, Eigen::Index max_allowed_unknown_notisolated_=0, Eigen::Index max_allowed_not_converged_=0, double max_add_run_iters=1.5)
 Convenience function to create a MHRWValueErrorBinsConvergedController (using template argument deduction) More...
 

Variables

constexpr const double MHRWAcceptanceRatioRecommendedMin = 0.2
 Minimal recommended acceptance ratio.
 
constexpr const double MHRWAcceptanceRatioRecommendedMax = 0.4
 Maximal recommended acceptance ratio.
 

Detailed Description

Base namespace for the Tomographer project.

This namespace contains the public API for the Tomographer project template library.

Typedef Documentation

§ MHRWNoController

A MHRWController Interface which does not adjust anything.

No adjustments are performed whatsoever. The MHWalkerParams may be of any type.

Since
Added in Tomographer 5.0.

Definition at line 562 of file mhrw.h.

§ TrivialMHRWStatsCollector

Trivial, NO-OP stats collector.

The minimal interface to a MHRWStatsCollector Interface which does absolutely nothing.

Definition at line 309 of file mhrwstatscollectors.h.

Enumeration Type Documentation

§ anonymous enum

anonymous enum
Enumerator
MHUseFnValue 

Provides the MH function value at each point (see Role of UseFnSyntaxType)

MHUseFnLogValue 

Provides the logarithm MH function value at each point (see Role of UseFnSyntaxType)

MHUseFnRelativeValue 

Provides directly the ratio of the function values for two consecutive points of the MH random walk (see Role of UseFnSyntaxType)

Definition at line 64 of file mhrw.h.

§ BinningConvergence

Convergence status of binning error bar.

Since
Changed in Tomographer 5.0: these constants are now global to the namespace and no longer members of the BinningAnalysisParams class.
Enumerator
BINNING_UNKNOWN_CONVERGENCE 

It is unknown whether the error bar has converged or not.

BINNING_CONVERGED 

The error bar appears to have converged.

BINNING_NOT_CONVERGED 

The error bar appears NOT to have converged.

Definition at line 77 of file mhrw_bin_err.h.

§ MHRWControllerAdjustmentStrategy

Describe how frequently the parameters of the random walk should be dynamically adjusted.

The value of an AdjustmentStrategy may be a binary OR value of several bits. The strategy needs to specify:

  • Whether the adjustments are to be enabled only during thermalization sweeps, only during live run sweeps, or during both
  • Whether the adjustments are to be performed after an individual iteration (a single move in the random walk), or only after processing a live sample (only during live runs)
Since
Added in Tomographer 5.0.
Enumerator
MHRWControllerDoNotAdjust 

Never adjust the parameters of the random walk.

MHRWControllerAdjustWhileThermalizing 

Adjustments are enabled during thermalization sweeps.

MHRWControllerAdjustWhileRunning 

Adjustments are enabled during live (running) sweeps.

MHRWControllerAdjustWhileThermalizingAndRunning 

Adjustments are enabled during both thermalization and live (running) sweeps.

MHRWControllerAdjustRWStageMASK 

Mask out bits which decide at which random walk stage (thermalizing and/or running) adjustments are performed.

MHRWControllerAdjustEveryIteration 

Adjustemnts should be performed after each individual iteration.

MHRWControllerAdjustEverySample 

Adjustemnts should be performed after a sample is taken (during live runs only)

MHRWControllerAdjustFrequencyMASK 

Mask out bits which decide at which frequency (after each iteration and/or after each sample) adjustments are performed.

MHRWControllerAdjustEveryIterationWhileThermalizing 

Adjustemnts should be performed only while thermalizing, after each individual iteration.

MHRWControllerAdjustEveryIterationAlways 

Adjustemnts should be performed all the time, after each individual iteration.

Definition at line 229 of file mhrw.h.

Function Documentation

§ histogramPrettyPrint() [1/2]

template<typename HistogramType >
void Tomographer::histogramPrettyPrint ( std::ostream str,
const HistogramType &  histogram,
int  max_width = 0 
)
inline

pretty-print the given histogram.

This overload dumps the pretty print into the ostream str.

If max_width <= 0, then the screen width (or default width) minus the given amount in absolute value is used. The negative amount is useful if your line is already occupied by some content.

Definition at line 1751 of file histogram.h.

§ histogramPrettyPrint() [2/2]

template<typename HistogramType >
std::string Tomographer::histogramPrettyPrint ( const HistogramType &  histogram,
int  max_width = 0 
)
inline

Utility to display histograms for humans.

This version of the function returns a formatted std::string.

If max_width <= 0, then the screen width (or default width) minus the given amount in absolute value is used. The negative amount is useful if your line is already occupied by some content.

Definition at line 1773 of file histogram.h.

§ histogramShortBar() [1/2]

template<typename HistogramType >
int Tomographer::histogramShortBar ( std::ostream str,
const HistogramType &  histogram,
bool  log_scale = true,
int  max_width = 0 
)
inline

Format the histogram as a one-line bar.

Produces a one-line visual representation of the histogram. The histogram is printed in the given std::ostream.

There's no final newline.

If max_width <= 0, then the screen width (or default width) minus the given amount in absolute value is used. The negative amount is useful if your line is already occupied by some content.

Returns
The number of characters which are still left to fill a line with maximal width. More precisely, the maximum width is first determined from max_width and/or from the COLUMNS environment variable. Then histogram is formatted into a bar which fits in this width. The difference between the maximum width and the histogram length is returned.

Definition at line 1798 of file histogram.h.

§ histogramShortBar() [2/2]

template<typename HistogramType >
std::string Tomographer::histogramShortBar ( const HistogramType &  histogram,
bool  log_scale = true,
int  max_width = 0 
)
inline

Format the histogram as a one-line bar.

Produces a one-line visual representation of the histogram. Returns a std::string.

There's no final newline.

If max_width <= 0, then the screen width (or default width) minus the given amount in absolute value is used. The negative amount is useful if your line is already occupied by some content.

Definition at line 1826 of file histogram.h.

§ histogramShortBarWithInfo() [1/2]

template<typename HistogramType >
void Tomographer::histogramShortBarWithInfo ( std::ostream str,
std::string  head,
const HistogramType &  hist,
std::string  tail,
bool  log_scale = true,
int  full_max_width = 0 
)
inline

Format the histogram as a one-line bar, with some surrounding info.

Produces a one-line visual representation of the histogram, streamed into an std::ostream. The bar is surrounded by some info, given as two strings head and tail. A final newline is inserted.

More precisely, this function outputs head, then the histogram bar, and then tail, while ensuring that the full width of everything reaches exactly full_max_width. If max_width <= 0, then the screen width (or default width) minus the given amount in absolute value is used instead. The negative amount is useful if your line is already occupied by some content.

See also histogramShortBarWithInfo(std::string, const HistogramType&, std::string, bool, int)

Definition at line 1854 of file histogram.h.

§ histogramShortBarWithInfo() [2/2]

template<typename HistogramType >
std::string Tomographer::histogramShortBarWithInfo ( std::string  head,
const HistogramType &  hist,
std::string  tail,
bool  log_scale = true,
int  full_max_width = 0 
)
inline

Format the histogram as a one-line bar, with some surrounding info.

Produces a one-line visual representation of the histogram, returned as a string. The bar is surrounded by some info, given as two strings head and tail. A final newline is inserted.

More precisely, this function outputs head, then the histogram bar, and then tail, while ensuring that the full width of everything reaches exactly full_max_width. If max_width <= 0, then the screen width (or default width) minus the given amount in absolute value is used instead. The negative amount is useful if your line is already occupied by some content.

See also histogramShortBarWithInfo(std::ostream&, std::string, const HistogramType&, std::string, bool, int)

Definition at line 1883 of file histogram.h.

§ mkMHRWMultipleControllers()

template<typename... MHRWControllerTypes>
MHRWMultipleControllers<MHRWControllerTypes...> Tomographer::mkMHRWMultipleControllers ( MHRWControllerTypes &...  controllers)
inline

Convenience function to create a MHRWMultipleControllers (using template argument deduction)

Since
Added in Tomographer 5.0

Definition at line 549 of file mhrw.h.

§ mkMHRWValueErrorBinsConvergedController()

template<typename IterCountIntType_ = int, typename ValueHistogramWithBinningMHRWStatsCollectorType_ = void, typename BaseLoggerType_ = void>
MHRWValueErrorBinsConvergedController<ValueHistogramWithBinningMHRWStatsCollectorType_, IterCountIntType_, BaseLoggerType_> Tomographer::mkMHRWValueErrorBinsConvergedController ( const ValueHistogramWithBinningMHRWStatsCollectorType_ &  value_stats_collector_,
BaseLoggerType_ &  baselogger_,
IterCountIntType_  check_frequency_sweeps_ = 1024,
Eigen::Index  max_allowed_unknown_ = 0,
Eigen::Index  max_allowed_unknown_notisolated_ = 0,
Eigen::Index  max_allowed_not_converged_ = 0,
double  max_add_run_iters = 1.5 
)
inline

Convenience function to create a MHRWValueErrorBinsConvergedController (using template argument deduction)

Since
Added in Tomographer 5.0

Definition at line 263 of file mhrwvalueerrorbinsconvergedcontroller.h.

§ mkMultipleMHRWStatsCollectors()

template<typename... MHRWStatsCollectors>
MultipleMHRWStatsCollectors<MHRWStatsCollectors...> Tomographer::mkMultipleMHRWStatsCollectors ( MHRWStatsCollectors &...  mhrwstatscollectors)
inline

Convenience function to create a MultipleMHRWStatsCollector (using template argument deduction)

Since
Added in Tomographer 5.0

Definition at line 320 of file mhrwstatscollectors.h.

§ mkValueHistogramMHRWStatsCollector()

template<typename ValueCalculator_ , typename LoggerType = Logger::VacuumLogger, typename HistogramType_ = Histogram<typename ValueCalculator_::ValueType>>
ValueHistogramMHRWStatsCollector<ValueCalculator_, LoggerType, HistogramType_> Tomographer::mkValueHistogramMHRWStatsCollector ( typename HistogramType_::Params  hist_params,
ValueCalculator_  valcalc,
LoggerType &  logger 
)
inline

Helper to easily instantiate a ValueHistogramMHRWStatsCollector.

Definition at line 985 of file mhrwstatscollectors.h.

§ mkValueHistogramWithBinningMHRWStatsCollector()

template<typename ValueCalculator_ , typename CountIntType_ = int, typename CountRealAvgType_ = double, int NumTrackValues_ = Eigen::Dynamic, int NumLevels_ = Eigen::Dynamic, typename LoggerType = Tomographer::Logger::VacuumLogger>
ValueHistogramWithBinningMHRWStatsCollector< ValueHistogramWithBinningMHRWStatsCollectorParams<ValueCalculator_, CountIntType_, CountRealAvgType_, NumTrackValues_, NumLevels_>, LoggerType > Tomographer::mkValueHistogramWithBinningMHRWStatsCollector ( HistogramParams< typename ValueCalculator_::ValueType >  hist_params,
ValueCalculator_  valcalc,
int  num_binning_levels,
LoggerType &  logger 
)
inline

Helper to easily instantiate a ValueHistogramWithBinningMHRWStatsCollector.

Definition at line 1013 of file mhrwstatscollectors.h.

§ sanitizeBinningLevels()

template<typename IterCountIntType , typename LocalLoggerType >
int Tomographer::sanitizeBinningLevels ( int  binning_num_levels,
IterCountIntType  n_run,
IterCountIntType  samples_last_level,
LocalLoggerType &  logger 
)
inline

Utility for sanitizing/determining number of binning levels.

If binning_num_levels is <= 0, then we determine the number of binning levels so that there are at least samples_last_level at the last level of the binning analysis; this will be returned. If binning_num_levels is > 0, then that number will be return.

In addition, a warning message is produced if there are too few binning levels, which might cause the error bars not to be reliable.

In addition, a warning message is produced if the number of samples at the last level of the binning analysis is less than samples_last_level.

The argument logger must be a Tomographer::Logger::LocalLogger (with some meaningful origin set) where warnings will be emitted.

Definition at line 934 of file mhrw_bin_err.h.