pfqn_mc_common.h File Reference

Randomness scaffolding shared by the Monte Carlo normalizing-constant estimators (pfqn_mci, pfqn_is, pfqn_ld_is, pfqn_oi_is, pfqn_pas_is, pfqn_ls, pfqn_mmsample2) and by the perfect sampler pfqn_cftp. More...

#include <cmath>
#include <cstdint>
#include <limits>
#include <random>
#include <vector>
#include "line/num/number.h"
#include "line/util/error.h"

Include dependency graph for pfqn_mc_common.h:

Go to the source code of this file.

Namespaces
namespace	line
namespace	line::pfqn

Typedefs
using	line::pfqn::McRng = std::mt19937_64
	The generator type every Monte Carlo entry point in this tree accepts.

Functions
double	line::pfqn::mc_uniform01 (McRng &g)
	Uniform deviate on [0,1) with 53 significant bits, as a double.
template<class T>
T	line::pfqn::mc_uniform (McRng &g)
	The same deviate materialized in the working arithmetic.
std::uint64_t	line::pfqn::mc_uniform_int (McRng &g, std::uint64_t n)
	Uniform integer on [0, n), unbiased by rejection.
double	line::pfqn::mc_normal01 (McRng &g)
	Standard normal deviate by the Box-Muller transform.
double	line::pfqn::mc_logmeanexp (const std::vector< double > &v)
	log(mean(exp(v))), computed by factoring out the maximum so that the exponentials stay in range.
template<class T>
T	line::pfqn::mc_exp (double lv)
	exp of a log-domain value, materialized in the working arithmetic.
template<class T>
double	line::pfqn::mc_log_factorial (long n)
	log(n!) for a non-negative integer n, the factln / gammaln(1+n) of the references, accumulated in the working arithmetic so the high-precision backends do not lose the digits a double lgamma would drop.

Detailed Description

Randomness scaffolding shared by the Monte Carlo normalizing-constant estimators (pfqn_mci, pfqn_is, pfqn_ld_is, pfqn_oi_is, pfqn_pas_is, pfqn_ls, pfqn_mmsample2) and by the perfect sampler pfqn_cftp.

This header is NOT a port of a MATLAB function. It exists because the MATLAB references draw from the global MATLAB stream (rand / randi / mvnrnd, seeded out of band by rng(options.seed)), and a library must not carry a hidden global stream. Every estimator in this tree therefore takes a std::mt19937_64& as an explicit argument and consumes it through the helpers below.

REPRODUCIBILITY CONTRACT, which every estimator's own header repeats:

• The estimate is comparable to MATLAB only IN DISTRIBUTION, never stream for stream. MATLAB's Mersenne Twister, its uniform-to-integer mapping and its normal transform all differ from the ones here, so the same seed does NOT produce the same sample path and the two estimates agree only up to Monte Carlo error. What IS comparable is the estimand: both target the exact constant of pfqn_ca, and both converge to it at the 1/sqrt(n) rate.
• Within this port, reproducibility requires passing a generator in the same state. Two calls with generators seeded identically, on identical inputs, in the same build, produce bit-identical output; the generator is advanced by the call, so a second call on the same generator object does not repeat the first. No estimator seeds, re-seeds or copies the generator internally.
• The uniform-to-integer map here is rejection based, not modulo based, so it is unbiased and identical on every platform and standard-library version. std::uniform_int_distribution and std::normal_distribution are deliberately avoided: their output is implementation defined, which would make a fixed-seed regression test non-portable.

Arithmetic: everything here is inherently inexact (uniform deviates are dyadic approximations of a continuous law, the normal transform needs log/cos), so each consumer gates on num_traits<T>::has_transcendental.

Definition in file pfqn_mc_common.h.