dimod.ess.compute_ess_sampleset#

compute_ess_sampleset(sample_set: SampleSet, test_function: Callable[[SampleSet], Iterable[float]] | None = None, batch_size: int | None = None)[source]#

Estimates the effective sample size of sample_set.

NOTE: The estimate can be nan or negative for extreme cases (e.g., constants). This can occur by definition of the estimator and is not a bug.

This function differs from compute_ess in that it assumes its input, sample_set, consists of states from a single Markov chain. By default, when no test function is supplied, the effective sample size is estimated based on the sample set’s energies.

Examples

This example demonstrates a typical use case of the estimator, measuring a QPU sample’s ESS based on the magnetization of the system.

Example (1): QPU

import numpy as np
from dwave.system import DWaveCliqueSampler
from dimod.ess import estimate_effective_sample_size
from dimod.generators import power_r

markov_chain_length = 100
num_vars = 33
bqm = power_r(512, num_vars)
bqm.normalize()
qpu = DWaveCliqueSampler()

def test_fn(ss):
    return ss.record.sample.mean(1)

sample_set = qpu.sample(bqm, num_reads=markov_chain_length, answer_mode="raw")
print("Effective sample size (QPU):",
      estimate_effective_sample_size_sampleset(sample_set, test_fn))
# Effective sample size per chain (QPU): 69.69037448554732
Parameters:

  • sample_set – A sample set with m ordered reads and n variables. In a typical use case with QPU samples, the sample set should have been attained with the sampling parameter answer_mode set to “raw”.

  • test_function – A function mapping sample_set to an iterable of floats of length m (the sample size of the sample set). If None, then the default test function is the energy of the model as reported by the sample set. Defaults to None.

  • batch_size – Batch size of the estimator. If None, then batch_size is set to the floor of the square root of n. Defaults to None.

Returns:

An estimate of the effective sample size of sample_set. The estimate can be NaN or even negative when the input chain is nearly constant. This can occur by definition of the estimator and is not a bug.

Return type:

float