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.

Steps

  1. 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 follow 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.

  2. Excitation gate sampler with customization

    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): "fixed" or "varied"
    .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("fixed") 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_spin("varied") 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.

  3. Memory restricted sampler with customization

    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_fast_defaults()
    .create()
)

    The memory-restricted sampler can also be manually configured with the following options:

    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).

  4. Backend sampler (third-party / noisy / hardware)

    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.

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