qcs 0.26.1

High level interface for running Quil on a QPU
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import typing
from qcs_sdk import QcsSdkError

@typing.final
class ChooseRandomRealSubRegions:
    r"""
    An [`ExternedCall`] that may be used to select one or more random
    sub-regions from a source array of real values to a destination array.
    """
    NAME: builtins.str = 'choose_random_real_sub_regions'
    r"""
    The name of the function referenced by the `PRAGMA EXTERN` and `CALL` instructions.
    """
    @staticmethod
    def build_signature() -> builtins.str:
        r"""
        Build the signature for the `PRAGMA EXTERN choose_random_real_sub_regions` instruction.
        
        The signature expressed in Quil is as follows:
        
        ```text
        "(destination : mut REAL[], source : REAL[], sub_region_size : INTEGER, seed : mut INTEGER)"
        ```
        """

@typing.final
class PrngSeedValue:
    r"""
    A valid seed value that may be used to initialize the PRNG. Such
    values are in the range `[1, MAX_SEQUENCER_VALUE]` and are losslessly
    convertible to `f64`.
    """
    def __new__(cls, value: builtins.int) -> PrngSeedValue:
        r"""
        Attempt to create a new instance of `PrngSeedValue` from a `u64`.
        
        # Errors
        
        Returns [`Error::InvalidSeed`] if the value is not in range `[1, MAX_SEQUENCER_VALUE]`
        or if it is not losslessly convertible to `f64`.
        """
    def as_f64(self) -> builtins.float: ...

class RandomError(QcsSdkError):
    r"""
    Errors that may occur using the randomization primitives defined in this module.
    """
    ...

def choose_random_real_sub_region_indices(seed: PrngSeedValue, start_index: builtins.int, series_length: builtins.int, sub_region_count: builtins.int) -> builtins.list[builtins.int]:
    r"""
    Given a seed, start index, series length, and sub-region count, this function
    will generate and return the sequence of pseudo-randomly chosen indices on
    the Rigetti control systems.
    
    For instance, if the following Quil program is run for 100 shots:
    
    ```quil
    # presumed sub-region size is 3.
    DECLARE destination REAL[6] # prng invocations per shot = (6 / sub_region_size)  = 2
    DECLARE source REAL[12]     # implicit sub-region count = (12 / sub_region_size) = 4
    DECLARE seed INTEGER[1]
    DECLARE ro BIT[1]
    
    DELAY 0 1e-6
    
    PRAGMA EXTERN choose_random_real_sub_regions "(destination : mut REAL[], source : REAL[], sub_region_size : INTEGER, seed : mut INTEGER)"
    CALL choose_random_real_sub_regions destination source 3 seed
    ```
    
    with a seed of 639,523, the following will provide the random sequence of sub-region indices:
    
    ```rust
    use qcs::qpu::experimental::random::{choose_random_real_sub_region_indices, PrngSeedValue};
    
    let seed = PrngSeedValue::try_new(639_523).unwrap();
    let start_index = 0;
    let prng_invocations_per_shot = 2;
    let shot_count = 100;
    let series_length = prng_invocations_per_shot * shot_count;
    let sub_region_count = 4;
    let _random_indices = choose_random_real_sub_region_indices(seed, start_index, series_length, sub_region_count);
    ```
    """

def lfsr_v1_next(seed: PrngSeedValue) -> builtins.int:
    r"""
    This represents the [linear feedback shift
    register](https://en.wikipedia.org/wiki/Linear-feedback_shift_register)
    currently implemented on Rigetti control systems. Specifically,
    it implements a 48-bit LFSR with taps at 0-based indices 47, 46, 20, and 19.
    The taps have been shown to produce maximal sequence lengths for 48-bit strings.
    """