Samplers

The samplers subpackage provides configuration sampling strategies.

Base Classes

class qvartools.samplers.sampler.SamplerResult(configs, counts=<factory>, metadata=<factory>, log_probs=None, wall_time=0.0)[source]

Bases: object

Immutable container for sampler output.

Parameters:

configs (torch.Tensor) – Sampled configurations, shape (n_samples, n_sites). Each row is a computational-basis state with entries in {0, 1}.
counts (dict) – Mapping from bitstring representation to occurrence count. Keys are strings of '0' and '1' characters.
metadata (dict) – Additional sampler-specific information (e.g. unique count, sampling time, flow parameters).
log_probs (torch.Tensor or None, optional) – Log-probabilities of the sampled configurations, shape (n_samples,). None when the sampler does not provide probabilities.
wall_time (float, optional) – Wall-clock time in seconds spent generating the samples (default 0.0).

configs

Type:: torch.Tensor

counts

Type:: dict

metadata

Type:: dict

log_probs

Type:: torch.Tensor or None

wall_time

Type:: float

Examples

>>> result = SamplerResult(configs=torch.zeros(10, 4, dtype=torch.int64))
>>> result.configs.shape
torch.Size([10, 4])

configs: Tensor

counts: dict[str, int]

metadata: dict[str, Any]

log_probs: Tensor | None = None

wall_time: float = 0.0

class qvartools.samplers.sampler.Sampler[source]

Bases: ABC

Abstract base class for all configuration samplers.

Every subclass must implement sample(), which draws a set of computational-basis configurations and returns a SamplerResult.

abstractmethod sample(n_samples)[source]

Draw configuration samples.

Parameters:: n_samples (int) – Number of samples to draw.
Returns:: Sampled configurations, counts, and metadata.
Return type:: SamplerResult

Classical Samplers

class qvartools.samplers.classical.nf_sampler.NFSampler(flow, nqs=None, hamiltonian=None, device='cpu')[source]

Bases: Sampler

Normalizing-flow-based configuration sampler.

Wraps a trained normalizing flow to generate discrete binary configurations. Optionally uses an NQS for importance weighting or a Hamiltonian for local-energy estimation.

Parameters:

flow (nn.Module) – A trained normalizing-flow model. Must implement sample(batch_size) returning (all_configs, unique_configs).
nqs (nn.Module or None, optional) – A neural quantum state for importance weighting. If provided, configurations are weighted by |psi(x)|^2.
hamiltonian (Hamiltonian or None, optional) – The Hamiltonian for energy-based metadata. If provided, the sampler computes local energy statistics.
device (str, optional) – Torch device for sampling (default "cpu").

flow

The flow model.

Type:: nn.Module

nqs

The NQS model (optional).

Type:: nn.Module or None

hamiltonian

The Hamiltonian (optional).

Type:: Hamiltonian or None

device

Active device.

Type:: torch.device

Examples

>>> sampler = NFSampler(flow=trained_flow)
>>> result = sampler.sample(1000)
>>> result.configs.shape
torch.Size([1000, 10])

sample(n_samples)[source]

Draw configuration samples from the trained flow.

Parameters:: n_samples (int) – Number of samples to draw.
Returns:: Sampled configurations with bitstring counts and metadata.
Return type:: SamplerResult
Raises:: ValueError – If n_samples < 1.

Quantum Samplers

class qvartools.samplers.quantum.trotter_sampler.TrotterSampler(hamiltonian, n_trotter_steps=10, time_step=0.1, initial_state=None)[source]

Bases: Sampler

Trotterized time-evolution sampler.

Evolves an initial state under the Hamiltonian via \(|\psi(t)\rangle = e^{-iHt} |\psi_0\rangle\) and samples computational-basis configurations from the Born-rule distribution \(p(x) = |\langle x | \psi(t) \rangle|^2\).

Uses scipy.sparse.linalg.expm_multiply() for the matrix exponential, which is efficient for sparse Hamiltonians.

Parameters:

hamiltonian (Hamiltonian) – The system Hamiltonian.
n_trotter_steps (int, optional) – Number of Trotter steps in the time evolution (default 10).
time_step (float, optional) – Time step per Trotter step (default 0.1).
initial_state (np.ndarray or None, optional) – Initial state vector. If None, uses the first computational- basis state (index 0).

hamiltonian

The Hamiltonian.

Type:: Hamiltonian

n_trotter_steps

Number of Trotter steps.

Type:: int

time_step

Time step per step.

Type:: float

total_time

Total evolution time n_trotter_steps * time_step.

Type:: float

Examples

>>> sampler = TrotterSampler(hamiltonian, n_trotter_steps=5)
>>> result = sampler.sample(1000)
>>> result.configs.shape[0]
1000

sample(n_samples)[source]

Sample configurations from the evolved state.

Parameters:

n_samples (int) – Number of configuration samples to draw.

Returns:

Sampled configurations with bitstring counts and metadata.

Return type:

SamplerResult

Raises:

ValueError – If n_samples < 1.
RuntimeError – If the evolved state has near-zero norm.