qcs_sdk.qpu.experimental.random

This module supports low-level primitives for randomization on Rigetti's QPUs.

class PrngSeedValue:

A seed value for the Rigetti QPU PRNG.

class ChooseRandomRealSubRegions:

A class that represents a QPU extern call to pseudo-randomly choose sub-regions of a source memory declaration. The parameters of the call function are as follows:

  • destination - The destination memory region to copy the pseudo-randomly chosen sub-region to.
  • source - The source memory region to choose sub-regions from.
  • sub_region_size - The size of each sub-region.
  • seed - A memory reference to an integer value that will be used to seed the PRNG. This value will be mutated to the next element in the PRNG sequence, so you may use it to generate subsequent pseudo-random values.

Note, len(destination) % sub_region-size and len(source) % sub_region_size must be 0.

Example

The following example declares a source with 12 real values, representing 4 sub-regions each of size 3. The destination memory region is declared with 3 real values, representing a single sub-region. The seed memory region is declared with a single integer value.

The Call instruction will pseudo-randomly choose a sub-region of the source memory region and copy it to the destination memory region according to the seed value. The seed value is mutated to the next element in the PRNG sequence.

from quil.program import Program
from quil.instructions import (
    Declaration,
    Instruction,
    Pragma,
    Call,
    CallArgument,
    MemoryReference,
    Vector,
    ScalarType,
    PragmaArgument,
)
from qcs_sdk.qpu.experimental.random import ChooseRandomRealSubRegions


EXPECTED_QUIL = """
PRAGMA EXTERN choose_random_real_sub_regions "(destination : mut REAL[], source : REAL[], sub_region_size : INTEGER, seed : mut INTEGER)"
DECLARE destination REAL[3]
DECLARE source REAL[12]
DECLARE seed INTEGER[1]
CALL choose_random_real_sub_regions destination source 3 seed[0]
"""


def test_choose_random_real_subregions():
    """Test that `ChooseRandomRealSubRegions` is correctly added to a Quil progrram."""
    program = Program()
    destination = Declaration("destination", Vector(ScalarType.Real, 3), None)
    program.add_instruction(Instruction.from_declaration(destination))
    source = Declaration("source", Vector(ScalarType.Real, 12), None)
    program.add_instruction(Instruction.from_declaration(source))
    seed = Declaration("seed", Vector(ScalarType.Integer, 1), None)
    program.add_instruction(Instruction.from_declaration(seed))
    pragma_extern = Pragma(
        "EXTERN",
        [PragmaArgument.from_identifier(ChooseRandomRealSubRegions.NAME)],
        ChooseRandomRealSubRegions.build_signature(),
    )
    program.add_instruction(Instruction.from_pragma(pragma_extern))
    call = Call(
        ChooseRandomRealSubRegions.NAME,
        [
            CallArgument.from_identifier("destination"),
            CallArgument.from_identifier("source"),
            CallArgument.from_immediate(complex(3, 0)),
            CallArgument.from_memory_reference(MemoryReference("seed", 0)),
        ],
    )
    program.add_instruction(Instruction.from_call(call))
    assert program == Program.parse(EXPECTED_QUIL)

From there, you may reference the destination memory region in your pulse program.

def build_signature(cls) -> str:

Build the Quil signature of the PRAGMA EXTERN instruction.

NAME: str = 'choose_random_real_sub_regions'

The name of the extern call function, which may be used in PRAGMA EXTERN and CALL instructions.

class RandomError(builtins.ValueError):

An error that may occur while initializing a seed value or generating a QPU PRNG sequence.

def lfsr_v1_next( seed_value: PrngSeedValue) -> PrngSeedValue:

Given a seed value, return the next value in the LFSR v1 PRNG sequence.

def choose_random_real_sub_region_indices( seed: PrngSeedValue, start_index: int, series_length: int, sub_region_count: int) -> List[int]:

Given a seed value, the starting index and length of a pseudo-random series, and the number of sub-regions from which to choose, return a list of the sub-region indices that were chosen.

The LFSR v1 pseudo-random number generator underlies this sequence.