Sampler#

The Sampler is the main class users will interact with for MC sampling and is the holder of all important classes needed to perform MC sampling. In general, it is recommended to use the from_ensemble() function to automatically instantiate the relevant classes (MCKernel, MCUsher, SamplerContainer) to perform Metropolis sampling and either single site flipping or two-site swapping depending on the ensemble.

class Sampler(kernels, container)[source]#

Bases: object

A sampler is used to run MCMC sampling simulations.

The specific MCMC algorithm is defined by the given MCKernel. The default will use a simple Metropolis random walk kernel.

Initialize BaseSampler.

It is recommended to initialize a sampler with the from_ensemble method, unless you need more control over the sampling kernel, mcusher, etc.

Parameters:

  • kernels ([MCKernel]) –

    a list of MCKernel instances for each walker. .. note:

    we only support the same type of kernel and the same ensemble for
all walkers.

  • container (SampleContainer) – a sampler container to store samples.

anneal(temperatures, mcmc_steps, initial_occupancies=None, thin_by=1, progress=False, stream_chunk=0, stream_file=None, swmr_mode=True)[source]#

Carry out a simulated annealing procedure.

Will MC sampling for each temperature for the specified number of steps, taking the last sampled configuration at each temperature as the starting configuration for the next temperature.

Everything is saved to the same SampleContainer, or if streaming, saved to the same file. To save each temperature in a different container, simply run a similar “for loop” creating a new sampler at each temperature.

Note

This method is only available for Samplers with a ThermalKernel.

Parameters:

  • temperatures (Sequence) – sequence of temperatures to anneal, should be strictly decreasing.

  • mcmc_steps (int) – number of Monte Carlo steps to run at each temperature.

  • initial_occupancies (ndarray) – array of occupancies. If None, the last sample will be taken. You should only provide this the first time you call run.

  • thin_by (int) – optional amount to thin by for saving samples.

  • progress (bool) – if true will show a progress bar.

  • stream_chunk (int) – optional chunk of samples to stream into a file. If > 0 samples will be flushed to backend file in stream_chucks

  • stream_file (str) – optional file name to use as backend. If file already exists will try to append to datasets. If not given will create a new file.

  • swmr_mode (bool) – optional if true allows to read file from other processes. Single Writer Multiple Readers.

clear_samples()[source]#

Clear samples from sampler container.

efficiency(discard=0, flat=True)[source]#

Get the efficiency of MCMC sampling (accepted/total).

classmethod from_ensemble(ensemble, *args, step_type=None, kernel_type=None, seeds=None, nwalkers=1, **kwargs)[source]#

Create a sampler based on an Ensemble instance.

This is the easier way to set up a Sampler. This will automatically populate and create an appropriate SampleContainer.

Parameters:

  • ensemble (Ensemble) – an Ensemble class to obtain sample probabilities from.

  • step_type (str) – optional type of step to run MCMC with. If not given the default depends on whether chemical potentials are defined.

  • *args – positional arguments to pass to the MCKernel constructor. More often than not you want to specify the temperature!

  • kernel_type (str) – optional string specifying the specific MCMC transition kernel. This represents the underlying MC algorithm. Currently only Metropolis is supported.

  • seeds ([int]) – optional seed for the PRNG in each kernel.

  • nwalkers (int) – optional number of walkers/chains to sampler. Default is 1. More than 1 is still experimental…

  • **kwargs – keyword arguments to pass to the MCKernel constructor. More often than not you want to specify the temperature!

Returns:

Sampler

property mckernels#

Get the underlying ensemble.

run(nsteps, initial_occupancies=None, thin_by=1, progress=False, stream_chunk=0, stream_file=None, keep_last_chunk=False, swmr_mode=False)[source]#

Run an MCMC sampling simulation.

This will run and save the samples every thin_by into a SampleContainer.

Parameters:

  • nsteps (int) – number of total MC steps.

  • initial_occupancies (ndarray) – array of occupancies. If None, the last sampler will be taken. You should only provide this the first time you call run. If you want to reset then you should call reset before to start a fresh run.

  • thin_by (int) – optional the amount to thin by for saving samples.

  • progress (bool) – optional if true will show a progress bar.

  • stream_chunk (int) – optional chunk of samples to stream into a file. If > 0 samples will be flushed to backend file in stream_chucks

  • stream_file (str) – optional file name to use as backend. If file already exists will try to append to datasets. If not given will create a new file.

  • keep_last_chunk (bool) – optional if True will keep the last chunk of samples in memory, but will reset the sampler otherwise. This is useful if the last occupancies are needed to start another run (ie for simulated annealing with streaming)

  • swmr_mode (bool) – optional if true allows to read file from other processes. Single Writer Multiple Readers.

sample(nsteps, initial_occupancies, thin_by=1, progress=False)[source]#

Generate MCMC samples.

Yield a sampler state every thin_by iterations. A state is give by a tuple of (occupancies, features, enthalpy)

Parameters:

  • nsteps (int) – number of iterations to run.

  • initial_occupancies (ndarray) – array of occupancies

  • thin_by (int) – optional number to thin iterations by and provide samples.

  • progress (bool) – If true will show a progress bar.

Yields:

tuple – accepted, occupancies, features change, enthalpies change

property samples#

Get the SampleContainer.

property seeds#

Seed for the random number generator.

setup_sample(initial_occupancies)[source]#

Copy and reshape occupancies and compute initial trace for sampling.

Parameters:

initial_occupancies (ndarray) – initial occupancies for sampling.

Returns: (occupancies, trace)
occupancies (ndarray):

initial occupancies for sampling.

trace (Trace):

initial trace for sampling.