Create a Sampler

Goal

Construct a sampler for use in Adaptive/Iterative VQEs (e.g., FAST-VQE), choosing among backend, excitation gate, or memory restricted simulators, and configuring key options.

Quick Start (default sampler)

If all that is required is a default working sampler:

import qrunch as qc

sampler = (
      qc.sampler_creator()
      .create()
)

The sampler builder follows the pattern explained in Understanding and Using Kvantify Qrunch’s Fluent Builder Pattern.

In practice, one usually narrows down to a specific sampler type first:

  • .backend(): third-party simulators, noisy simulators, and real hardware (see Choose a Backend)

  • .excitation_gate(): Kvantify’s proprietary chemistry-tailored excitation gate simulator

  • .memory_restricted(): Kvantify’s proprietary chemistry-tailored, memory restricted simulator

  • .tensor_network(): tensor-network sampling with exact contraction-based strategies

Excitation Gate Sampler

The excitation gate sampler is the recommended high-performance simulator for many chemistry workflows and pairs naturally with FAST-VQE.

import qrunch as qc

sampler = (
      qc.sampler_creator()
      .excitation_gate()
      .create()
)

This sampler can be customized with the following options:

import qrunch as qc

sampler = (
      qc.sampler_creator()
      .excitation_gate()
      .with_float_type("f64")             # Precision of internal floats: "f64" (default) or "f32"
      .with_parallel_setting("parallel")  # Parallelization behavior: "serial" or "parallel"
      .with_spin_particle_conservation()  # Spin policy (see note below)
      .with_seed(1234)                    # Reproducibility: set a seed (or None to disable)
      .with_eps(1e-12)                    # Sampling epsilon lower bound (absolute amplitude threshold), or None
      .create()
)

Note on spin conservation policies

  • with_spin_particle_conservation() keeps the spin_difference fixed during sampling. This is required for fermionic encodings such as FAST-VQE, where there is a clear spin-up/spin-down qubit separation.

  • with_total_particle_conservation() allows the spin_difference to change. This is required for bosonic encodings such as BEAST-VQE where there is no spin-up/spin-down qubit separation.

Memory Restricted Sampler

The memory restricted sampler is the recommended simulator for large scale calculations. It is designed to handle very large Hilbert spaces by capping memory usage. Thus it is not an exact simulator, but rather a high-performance approximate simulator.

One can use the memory restricted sampler with default precise settings:

import qrunch as qc

sampler_precise = (
      qc.sampler_creator()
      .memory_restricted()
      .with_precise_defaults()
      .create()
)

Or with fast but less precise default settings:

import qrunch as qc

sampler_fast = (
      qc.sampler_creator()
      .memory_restricted()
      .with_quick_defaults()
      .create()
)

The memory restricted sampler can also be manually configured with the options shown in the following example:

import qrunch as qc

options = qc.options.MemoryRestrictedSimulatorOptions(
      suppress_warnings=False,
      max_number_of_amplitudes=1_000_000,
      max_memory_usage_in_kb=None,
)

sampler_custom = (
      qc.sampler_creator()
      .memory_restricted()
      .with_options(options)
      .create()
)

An alternative to setting the maximum number of amplitudes is to specify the maximum memory usage:

import qrunch as qc

sampler_custom = (
      qc.sampler_creator()
      .memory_restricted()
      .with_max_memory(max_memory_usage_in_kb=512_000)
      .create()
)

In this example, the sampler will use at most 512 MB of RAM (512.000 kilobyte).

Backend Sampler

This option is designed for use with third-party simulators, noisy simulators, or real quantum computers.

import qrunch as qc

sampler = (
      qc.sampler_creator()
      .backend()
      .create()
)

See Choose a Backend for how to choose and configure a non-default backend.

Optionally, one can also attach a post-selection-based error mitigator:

import qrunch as qc

sampler = (
      qc.sampler_creator()
      .backend()
      .choose_sampler_error_mitigator()
      .hamming_weight_post_selection()
      .create()
)

The currently supported option is "hamming_weight_post_selection", which enforces correct Hamming weight / particle number conservation.

Tensor Network Sampler

The tensor-network sampler samples from a quantum circuit by contracting it as a tensor network rather than forming the full state vector directly. It is configured through .tensor_network(), which selects a sampler algorithm and an optional contraction path finder.

import qrunch as qc

sampler = (
      qc.sampler_creator()
      .tensor_network()
      .create()
)

Choosing the Sampler Algorithm

Use choose_sampler_algorithm() to override the default configuration:

  • .exact_cpu(): CPU-based exact algorithm, powered by opt_einsum (default).

  • .exact_gpu(): GPU-accelerated exact algorithm, powered by NVIDIA cuTensorNet (requires CUDA).

Here the “exact” indicates that the estimator computes exact expectation values, as opposed to approximate methods that may be used in other samplers (e.g., memory restricted sampler).

Only recommended for BEAST or Paired Electron Approximation Circuits

For BEAST circuits (iterative VQE calculator with beast or paired_electron_approximation) It is possible to scale the tensor network sampler to larger circuits than the ExcitationGateEstimator, without sacrificing accuracy. However, it is not recommended for FAST circuits (iterative VQE calculator with standard).

import qrunch as qc

# CPU (default)
sampler = (
      qc.sampler_creator()
      .tensor_network()
      .choose_sampler_algorithm()
      .exact_cpu()
      .create()
)

# cuTensorNet GPU (requires CUDA)
sampler_gpu = (
      qc.sampler_creator()
      .tensor_network()
      .choose_sampler_algorithm()
      .exact_gpu()
      .create()
)

Choosing the Contraction Path Finder

See Choose a Contraction Path Finder for a detailed description of all available contraction path finders and their options.

Verify the Result

  • You now have a configured sampler instance ready for use in an Adaptive VQE, e.g., as the sampler in the FAST gate selector.

Next Step

See Also