graph_tool.inference.mcmc_equilibrate(state, wait=1000, nbreaks=2, max_niter=inf, force_niter=None, epsilon=0, gibbs=False, multiflip=True, mcmc_args={}, entropy_args={}, history=False, callback=None, verbose=False)[source]#

Equilibrate a MCMC with a given starting state.

stateAny state class (e.g. BlockState)

Initial state. This state will be modified during the algorithm.

waitint (optional, default: 1000)

Number of iterations to wait for a record-breaking event.

nbreaksint (optional, default: 2)

Number of iteration intervals (of size wait) without record-breaking events necessary to stop the algorithm.

max_niterint (optional, default: numpy.inf)

Maximum number of iterations.

force_niterint (optional, default: None)

If given, will force the algorithm to run this exact number of iterations.

epsilonfloat (optional, default: 0)

Relative changes in entropy smaller than epsilon will not be considered as record-breaking.

gibbsbool (optional, default: False)

If True, each step will call state.gibbs_sweep instead of state.mcmc_sweep.

multiflipbool (optional, default: True)

If True, each step will call state.multiflip_mcmc_sweep instead of state.mcmc_sweep.

mcmc_argsdict (optional, default: {})

Arguments to be passed to state.mcmc_sweep (or state.gibbs_sweep).

historybool (optional, default: False)

If True, a list of tuples of the form (nattempts, nmoves, entropy) will be kept and returned, where entropy is the current entropy and nmoves is the number of vertices moved.

callbackfunction (optional, default: None)

If given, this function will be called after each iteration. The function must accept the current state as an argument, and its return value must be either None or a (possibly empty) list of values that will be append to the history, if history == True.

verbosebool or tuple (optional, default: False)

If True, progress information will be shown. Optionally, this accepts arguments of the type tuple of the form (level, prefix) where level is a positive integer that specifies the level of detail, and prefix is a string that is prepended to the all output messages.

historylist of tuples of the form (nattempts, nmoves, entropy)

Summary of the MCMC run. This is returned only if history == True.


Current entropy value after run. This is returned only if history == False.


Number of node move attempts.


Number of node moves.


The MCMC equilibration is attempted by keeping track of the maximum and minimum values, and waiting sufficiently long without a record-breaking event.

This function calls state.mcmc_sweep (or state.gibbs_sweep) at each iteration (e.g. graph_tool.inference.BlockState.mcmc_sweep() and graph_tool.inference.BlockState.gibbs_sweep()), and keeps track of the value of state.entropy(**args) with args corresponding to mcmc_args["entropy_args"].



Tiago P. Peixoto, “Efficient Monte Carlo and greedy heuristic for the inference of stochastic block models”, Phys. Rev. E 89, 012804 (2014), DOI: 10.1103/PhysRevE.89.012804 [sci-hub, @tor], arXiv: 1310.4378