qcs-sdk-python 0.21.12rc4__tar.gz → 0.21.13__tar.gz

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/Cargo.lock

@@ -1806,9 +1806,9 @@ dependencies = [
 
 [[package]]
 name = "libloading"
-version = "0.8.3"
+version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c2a198fb6b0eada2a8df47933734e6d35d350665a33a3593d7164fa52c75c19"
+checksum = "4979f22fdb869068da03c9f7528f8297c6fd2606bc3a4affe42e6a823fdb8da4"
 dependencies = [
  "cfg-if 1.0.0",
  "windows-targets 0.52.6",
@@ -1829,7 +1829,7 @@ dependencies = [
  "bindgen",
  "cc",
  "libc",
- "libloading 0.8.3",
+ "libloading 0.8.5",
  "num-complex",
  "paste",
  "pkg-config",
@@ -2628,7 +2628,7 @@ checksum = "0c1318b19085f08681016926435853bbf7858f9c082d0999b80550ff5d9abe15"
 dependencies = [
  "bytes",
  "heck 0.5.0",
- "itertools 0.13.0",
+ "itertools 0.11.0",
  "log",
  "multimap",
  "once_cell",
@@ -2648,7 +2648,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e9552f850d5f0964a4e4d0bf306459ac29323ddfbae05e35a7c0d35cb0803cc5"
 dependencies = [
  "anyhow",
- "itertools 0.13.0",
+ "itertools 0.11.0",
  "proc-macro2",
  "quote",
  "syn 2.0.66",
@@ -2811,7 +2811,7 @@ dependencies = [
 
 [[package]]
 name = "qcs"
-version = "0.25.11-rc.4"
+version = "0.25.12"
 dependencies = [
  "assert2",
  "async-trait",
@@ -2860,9 +2860,9 @@ dependencies = [
 
 [[package]]
 name = "qcs-api-client-common"
-version = "0.11.8"
+version = "0.11.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed485c8c48ec362a35bc5106b67520c63495cf04166c9d2733fc971bcf3ca2ca"
+checksum = "cfd6d5b09d8e6b8576ebf34a26e864c513e402ff49e10222eb04b029909b5253"
 dependencies = [
  "async-tempfile",
  "async-trait",
@@ -2893,9 +2893,9 @@ dependencies = [
 
 [[package]]
 name = "qcs-api-client-grpc"
-version = "0.11.8"
+version = "0.11.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a022867a1995c0509014d2786c3d6e85e0ff2869f5cb42488a92956655548ac2"
+checksum = "56d06564cd30895f83ac41c7995f0106860308a8b71638b3fd3b9fa532fa1d52"
 dependencies = [
  "backoff",
  "futures-util",
@@ -2932,9 +2932,9 @@ dependencies = [
 
 [[package]]
 name = "qcs-api-client-openapi"
-version = "0.12.8"
+version = "0.12.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42225f82f62536c99a99d50e7b1ab0222afc0053064a0fb8c3f8388e9ade2983"
+checksum = "9b82adef224d6e01d929dcceb139a33c2c6e0fa9bd6c6263b73e616c802b1790"
 dependencies = [
  "anyhow",
  "http 1.1.0",
@@ -2953,7 +2953,7 @@ dependencies = [
 
 [[package]]
 name = "qcs-sdk-python"
-version = "0.21.12-rc.4"
+version = "0.21.13"
 dependencies = [
  "async-trait",
  "numpy",
@@ -2988,8 +2988,8 @@ checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
 [[package]]
 name = "quil-rs"
-version = "0.29.2"
-source = "git+https://github.com/rigetti/quil-rs?tag=quil-py%2Fv0.13.2#f725e9f67ae3a3137cd9033d0f98143e8644b610"
+version = "0.30.0"
+source = "git+https://github.com/rigetti/quil-rs?tag=quil-py%2Fv0.15.2#ead13b6c1db0e8089b5c22a1e6125b69632558d4"
 dependencies = [
  "approx",
  "indexmap 2.7.1",
@@ -4496,9 +4496,9 @@ checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b"
 
 [[package]]
 name = "unicode-width"
-version = "0.1.13"
+version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0336d538f7abc86d282a4189614dfaa90810dfc2c6f6427eaf88e16311dd225d"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
 
 [[package]]
 name = "unindent"

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/Cargo.toml

@@ -3,9 +3,9 @@ members = ["crates/*"]
 resolver = "2"
 
 [workspace.dependencies]
-qcs-api-client-common = "0.11.8"
-qcs-api-client-grpc = "0.11.8"
-qcs-api-client-openapi = "0.12.8"
+qcs-api-client-common = "0.11.9"
+qcs-api-client-grpc = "0.11.9"
+qcs-api-client-openapi = "0.12.9"
 serde_json = "1.0.86"
 thiserror = "1.0.57"
 tokio = "1.36.0"
@@ -15,7 +15,7 @@ tokio = "1.36.0"
 # `crates/python/pyproject.toml`.
 # The version must also be specified in order to publish to crates.io. Cargo enforces
 # that the specified version is the same as the version in the git repository.
-quil-rs = { version = "0.29.2", git = "https://github.com/rigetti/quil-rs", tag = "quil-py/v0.13.2" }
+quil-rs = { git = "https://github.com/rigetti/quil-rs", tag = "quil-py/v0.15.2" }
 
 # ndarray is used by the `qcs` crate, but it is also used in the `python` crate via a
 # re-export through the numpy crate. They should be updated as a pair to keep both

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcs-sdk-python
-Version: 0.21.12rc4
+Version: 0.21.13
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.8
@@ -8,22 +8,22 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Operating System :: OS Independent
-Requires-Dist: quil>=0.15.2
-Requires-Dist: qcs-api-client-common>=0.11.8
-Requires-Dist: pyquil==4.14.2 ; extra == 'pyquil'
-Requires-Dist: black>=24.8.0 ; extra == 'dev'
-Requires-Dist: opentelemetry-sdk==1.25.0 ; extra == 'dev'
-Requires-Dist: pytest>=8.1.1 ; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23.6 ; extra == 'dev'
-Requires-Dist: pytest-mock>=3.14.0 ; extra == 'dev'
-Requires-Dist: pytest-sugar>=1.0.0 ; extra == 'dev'
-Requires-Dist: pytest-clarity>=1.0.1 ; extra == 'dev'
-Requires-Dist: syrupy>=4.0.0 ; extra == 'dev'
-Requires-Dist: maturin==1.5.1 ; extra == 'dev'
-Requires-Dist: numpy>=1.24.1 ; extra == 'dev'
-Requires-Dist: pdoc>=14.6.1 ; extra == 'dev'
-Requires-Dist: ruff>=0.3.5 ; extra == 'dev'
-Requires-Dist: mypy>=1.14.1 ; extra == 'dev'
+Requires-Dist: quil >=0.15.2
+Requires-Dist: qcs-api-client-common >=0.11.8
+Requires-Dist: pyquil ==4.14.2 ; extra == 'pyquil'
+Requires-Dist: black >=24.8.0 ; extra == 'dev'
+Requires-Dist: opentelemetry-sdk ==1.25.0 ; extra == 'dev'
+Requires-Dist: pytest >=8.1.1 ; extra == 'dev'
+Requires-Dist: pytest-asyncio >=0.23.6 ; extra == 'dev'
+Requires-Dist: pytest-mock >=3.14.0 ; extra == 'dev'
+Requires-Dist: pytest-sugar >=1.0.0 ; extra == 'dev'
+Requires-Dist: pytest-clarity >=1.0.1 ; extra == 'dev'
+Requires-Dist: syrupy >=4.0.0 ; extra == 'dev'
+Requires-Dist: maturin ==1.7.0 ; extra == 'dev'
+Requires-Dist: numpy >=1.24.1 ; extra == 'dev'
+Requires-Dist: pdoc >=14.6.1 ; extra == 'dev'
+Requires-Dist: ruff >=0.3.5 ; extra == 'dev'
+Requires-Dist: mypy >=1.14.1 ; extra == 'dev'
 Provides-Extra: pyquil
 Provides-Extra: dev
 Summary: Python interface for the QCS Rust SDK

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/crates/lib/CHANGELOG.md

@@ -1,3 +1,47 @@
+## 0.25.12
+
+### Features
+
+- add support for hardware randomization (#515)
+
+### Fixes
+
+- update grpc clients (#537)
+
+## 0.25.12-rc.2
+
+### Features
+
+- add support for hardware randomization (#515)
+
+### Fixes
+
+- update grpc clients (#537)
+
+## 0.25.12-rc.1
+
+### Features
+
+- add support for hardware randomization (#515)
+
+## 0.25.12-rc.0
+
+### Features
+
+- add support for hardware randomization (#515)
+
+## 0.25.11
+
+### Fixes
+
+- wheel building for linux, macos (#535)
+
+## 0.25.11-rc.5
+
+### Fixes
+
+- wheel building for linux, macos (#535)
+
 ## 0.25.11-rc.4
 
 ### Fixes

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/crates/lib/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "qcs"
 description = "High level interface for running Quil on a QPU"
-version = "0.25.11-rc.4"
+version = "0.25.12"
 edition = "2018"
 license = "Apache-2.0"
 repository = "https://github.com/rigetti/qcs-sdk-rust"
@@ -17,6 +17,7 @@ otel-tracing = ["tracing-config", "qcs-api-client-grpc/otel-tracing", "qcs-api-c
 libquil = ["dep:libquil-sys"]
 grpc-web = ["qcs-api-client-grpc/grpc-web"]
 tracing-opentelemetry = ["tracing-config", "qcs-api-client-grpc/tracing-opentelemetry", "qcs-api-client-openapi/tracing-opentelemetry"]
+experimental = []
 
 [dependencies]
 cached = "0.44.0"
@@ -73,3 +74,4 @@ built = "0.6.1"
 name = "compilation-and-simulation-with-libquil"
 path = "examples/libquil.rs"
 required-features = ["libquil"]
+

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/crates/lib/Makefile.toml

@@ -22,9 +22,16 @@ run_task = [{name = "test-flow"}]
 dependencies = ["clippy-flow"]
 
 [tasks.examples]
+dependencies = ["examples-libquil", "examples-experimental"]
+
+[tasks.examples-libquil]
 command = "cargo"
 args = ["build", "--examples", "--features", "libquil"]
 
+[tasks.examples-experimental]
+command = "cargo"
+args = ["build", "--examples", "--features", "experimental"]
+
 [tasks.deny]
 install_crate = "cargo-deny"
 command = "cargo"

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/crates/lib/src/lib.rs

@@ -1,5 +1,4 @@
 #![deny(clippy::all)]
-#![deny(clippy::pedantic)]
 #![deny(clippy::cargo)]
 #![allow(clippy::multiple_crate_versions)] // This should be enforced by cargo-deny
 #![allow(clippy::missing_errors_doc)]
@@ -8,6 +7,7 @@
 #![forbid(unsafe_code)]
 #![warn(future_incompatible)]
 #![warn(rust_2018_compatibility, rust_2018_idioms)]
+#![warn(clippy::pedantic)]
 #![warn(
     absolute_paths_not_starting_with_crate,
     anonymous_parameters,

qcs_sdk_python-0.21.13/crates/lib/src/qpu/experimental/mod.rs

@@ -0,0 +1,10 @@
+//! This module supports experimental features that meet the following criteria:
+//!
+//! * They support recent and compelling research in quantum computing.
+//! * Implementation is specific to Rigetti's QPUs; implementation may
+//!   not othewrise be expressed through a generalized quantum computing
+//!   language, such as Quil or QASM.
+//!
+//! As such, the features contained herein should be considered unstable, possibly
+//! ephemeral, and subject to specific authorization checks.
+pub mod random;

qcs_sdk_python-0.21.13/crates/lib/src/qpu/experimental/random.rs

@@ -0,0 +1,372 @@
+//! This module supports low-level primitives for randomization on Rigetti's QPUs.
+use std::{convert::TryFrom, ops::BitXor};
+
+use num::{complex::Complex64, ToPrimitive};
+use quil_rs::instruction::{ExternParameter, ExternParameterType, ExternSignature};
+use quil_rs::{
+    instruction::{Call, CallError, ExternError, UnresolvedCallArgument},
+    quil::ToQuilError,
+};
+
+/// Hardware values are 48 bits long.
+const MAX_SEQUENCER_VALUE: u64 = 0x0000_FFFF_FFFF_FFFF;
+
+/// Hardware multiplication currently uses the lower 16 bits of
+/// the PRNG value.
+const MAX_UNSIGNED_MULTIPLIER: u64 = 0x0000_0000_0000_FFFF;
+
+/// The taps for the LFSR used on Rigetti control systems. These taps
+/// have been shown to produce maximal sequence lengths for 48-bit
+/// strings.
+const V1_TAPS: [u32; 4] = [47, 46, 20, 19];
+
+/// An error that may occur using the randomization primitives defined
+/// in this module.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    /// An invalid seed value was provided.
+    #[error(
+        "seed values must be in range [1, {MAX_SEQUENCER_VALUE}] and losslessly convertible to f64, found {0}"
+    )]
+    InvalidSeed(u64),
+    /// An error occurred while converting to Quil.
+    #[error("error converting to Quil: {0}")]
+    ToQuilError(#[from] ToQuilError),
+    /// An error occurred while constructing an extern signature.
+    #[error("error constructing extern signature: {0}")]
+    ExternSignatureError(#[from] ExternError),
+    /// The destination must be a `REAL[]`.
+    #[error("destination must be a REAL[], found {destination_type:?}")]
+    InvalidDestinationType {
+        /// The type on the destination declaration.
+        destination_type: quil_rs::instruction::ScalarType,
+    },
+    /// The source must be a `REAL[]`.
+    #[error("source must be a REAL[], found {source_type:?}")]
+    InvalidSourceType {
+        /// The type on the source declaration.
+        source_type: quil_rs::instruction::ScalarType,
+    },
+    /// The destination length must be divisible by the sub-region size.
+    #[error(
+        "destination length must be in range [0, {}] and divisible by the sub-region size, found {destination_length} % {sub_region_size}", 2u64.pow(f64::MANTISSA_DIGITS) - 1
+    )]
+    InvalidDestinationLength {
+        /// The length of the destination declaration.
+        destination_length: u64,
+        /// The size of each sub-region in source and destination memory arrays.
+        sub_region_size: f64,
+    },
+    /// The source length must be divisible by the sub-region size.
+    #[error(
+        "source length must be in range [0, {}] and divisible by the sub-region size, found {source_length} % {sub_region_size}", 2u64.pow(f64::MANTISSA_DIGITS) - 1
+    )]
+    InvalidSourceLength {
+        /// The length of the source declaration.
+        source_length: u64,
+        /// The size of each sub-region in source and destination memory arrays.
+        sub_region_size: f64,
+    },
+}
+
+/// A specialized `Result` type for hardware extern function calls.
+#[allow(clippy::module_name_repetitions)]
+pub type RandomResult<T> = Result<T, Error>;
+
+/// 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.
+#[derive(Debug, Clone)]
+pub struct ChooseRandomRealSubRegions {
+    destination_memory_region_name: String,
+    source_memory_region_name: String,
+    sub_region_size: f64,
+    seed_memory_region_name: String,
+}
+
+impl ChooseRandomRealSubRegions {
+    /// Create a new instance of [`ChooseRandomRealSubRegions`].
+    ///
+    /// # Parameters
+    ///
+    /// * `destination` - The name of the destination array.
+    /// * `source` - The identifier of the source array.
+    /// * `sub_region_size` - The size of the sub-regions to select from
+    ///   the source array. Note, `len(source) % sub_region_size` and
+    ///   `len(destination) % sub_region_size` must be zero.
+    /// * `seed` - The name of the seed value.
+    ///
+    /// The values provided for `destination`, `source`, and `seed` must
+    /// be declared within the Quil program where the call is made.
+    pub fn try_new<T: Into<f64> + Copy>(
+        destination: &quil_rs::instruction::Declaration,
+        source: &quil_rs::instruction::Declaration,
+        sub_region_size: T,
+        seed: &quil_rs::instruction::MemoryReference,
+    ) -> RandomResult<Self> {
+        if !matches!(
+            destination.size.data_type,
+            quil_rs::instruction::ScalarType::Real
+        ) {
+            return Err(Error::InvalidDestinationType {
+                destination_type: destination.size.data_type,
+            });
+        }
+        if !matches!(
+            source.size.data_type,
+            quil_rs::instruction::ScalarType::Real
+        ) {
+            return Err(Error::InvalidSourceType {
+                source_type: source.size.data_type,
+            });
+        }
+        if destination
+            .size
+            .length
+            .to_f64()
+            .is_none_or(|destination_length| destination_length % sub_region_size.into() != 0f64)
+        {
+            return Err(Error::InvalidDestinationLength {
+                destination_length: destination.size.length,
+                sub_region_size: sub_region_size.into(),
+            });
+        }
+
+        if source
+            .size
+            .length
+            .to_f64()
+            .is_none_or(|source_length| source_length % sub_region_size.into() != 0f64)
+        {
+            return Err(Error::InvalidSourceLength {
+                source_length: source.size.length,
+                sub_region_size: sub_region_size.into(),
+            });
+        }
+
+        Ok(Self {
+            destination_memory_region_name: destination.name.clone(),
+            source_memory_region_name: source.name.clone(),
+            sub_region_size: sub_region_size.into(),
+            seed_memory_region_name: seed.name.clone(),
+        })
+    }
+
+    /// The name of the function referenced by the `PRAGMA EXTERN` and `CALL` instructions.
+    pub const EXTERN_NAME: &str = "choose_random_real_sub_regions";
+
+    #[allow(clippy::doc_markdown)]
+    /// 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)"
+    /// ```
+    pub fn build_signature() -> RandomResult<ExternSignature> {
+        vec![
+            ExternParameter::try_new(
+                "destination".to_string(),
+                true,
+                ExternParameterType::VariableLengthVector(quil_rs::instruction::ScalarType::Real),
+            ),
+            ExternParameter::try_new(
+                "source".to_string(),
+                false,
+                ExternParameterType::VariableLengthVector(quil_rs::instruction::ScalarType::Real),
+            ),
+            ExternParameter::try_new(
+                "sub_region_size".to_string(),
+                false,
+                ExternParameterType::Scalar(quil_rs::instruction::ScalarType::Integer),
+            ),
+            ExternParameter::try_new(
+                "seed".to_string(),
+                true,
+                ExternParameterType::Scalar(quil_rs::instruction::ScalarType::Integer),
+            ),
+        ]
+        .into_iter()
+        .map(|r| r.map_err(Error::from))
+        .collect::<RandomResult<Vec<ExternParameter>>>()
+        .map(|parameters| ExternSignature::new(None, parameters))
+    }
+
+    /// Build a `PRAGMA EXTERN` instruction for the externed function.
+    pub(super) fn pragma_extern() -> Result<quil_rs::instruction::Pragma, Error> {
+        use quil_rs::quil::Quil;
+
+        Ok(quil_rs::instruction::Pragma::new(
+            quil_rs::instruction::RESERVED_PRAGMA_EXTERN.to_string(),
+            vec![quil_rs::instruction::PragmaArgument::Identifier(
+                Self::EXTERN_NAME.to_string(),
+            )],
+            Some(Self::build_signature()?.to_quil().map_err(Error::from)?),
+        ))
+    }
+}
+
+impl TryFrom<ChooseRandomRealSubRegions> for Call {
+    type Error = CallError;
+
+    fn try_from(value: ChooseRandomRealSubRegions) -> Result<Self, Self::Error> {
+        Self::try_new(
+            ChooseRandomRealSubRegions::EXTERN_NAME.to_string(),
+            vec![
+                UnresolvedCallArgument::Identifier(value.destination_memory_region_name),
+                UnresolvedCallArgument::Identifier(value.source_memory_region_name),
+                UnresolvedCallArgument::Immediate(Complex64 {
+                    re: value.sub_region_size,
+                    im: 0.0,
+                }),
+                UnresolvedCallArgument::Identifier(value.seed_memory_region_name),
+            ],
+        )
+    }
+}
+
+/// 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`.
+#[derive(Debug, Clone, Copy)]
+pub struct PrngSeedValue {
+    u64_value: u64,
+    f64_value: f64,
+}
+
+impl PrngSeedValue {
+    /// Attempt to create a new instance of `PrngSeedValue` from a `u64`.
+    /// The value must be in the range `[1, MAX_SEQUENCER_VALUE]` and
+    /// losslessly convertible to `f64`.
+    pub fn try_new(value: u64) -> RandomResult<Self> {
+        if !(1..=MAX_SEQUENCER_VALUE).contains(&value) {
+            return Err(Error::InvalidSeed(value));
+        }
+        if let Some(f64_value) = value.to_f64() {
+            Ok(Self {
+                u64_value: value,
+                f64_value,
+            })
+        } else {
+            Err(Error::InvalidSeed(value))
+        }
+    }
+
+    pub(super) fn as_f64(&self) -> f64 {
+        self.f64_value
+    }
+}
+
+fn lfsr_next(seed: u64, taps: &[u32]) -> u64 {
+    let feedback_value = taps.iter().fold(0, |acc, tap| {
+        let base = 2u64.pow(*tap);
+        let bit = u64::from((seed & base) != 0);
+        acc.bitxor(bit)
+    });
+    ((seed << 1) & MAX_SEQUENCER_VALUE) | feedback_value
+}
+
+/// 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.
+#[must_use]
+pub fn lfsr_v1_next(seed: PrngSeedValue) -> u64 {
+    lfsr_next(seed.u64_value, &V1_TAPS)
+}
+
+fn generate_lfsr_v1_sequence(seed: u64, start_index: u32, series_length: u32) -> Vec<u64> {
+    let mut lfsr = seed & MAX_SEQUENCER_VALUE;
+
+    let range = start_index..(start_index + series_length);
+    let mut collection = vec![];
+    for i in 0..(start_index + series_length) {
+        lfsr = lfsr_next(lfsr, &V1_TAPS);
+        if range.contains(&i) {
+            collection.push(lfsr);
+        }
+    }
+    collection
+}
+
+fn prng_value_to_sub_region_index(value: u64, sub_region_count: u8) -> u8 {
+    ((value & MAX_UNSIGNED_MULTIPLIER) % u64::from(sub_region_count))
+        .to_u8()
+        .expect("modulo u8 should always produce a valid value")
+}
+
+/// 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);
+/// ```
+#[must_use]
+pub fn choose_random_real_sub_region_indices(
+    seed: PrngSeedValue,
+    start_index: u32,
+    series_length: u32,
+    sub_region_count: u8,
+) -> Vec<u8> {
+    generate_lfsr_v1_sequence(seed.u64_value, start_index, series_length)
+        .iter()
+        .map(|&value| prng_value_to_sub_region_index(value, sub_region_count))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{collections::HashMap, fs::File};
+
+    /// These are values that have been validated as final memory read off Rigetti QPUs.
+    fn prng_sequences() -> HashMap<u32, Vec<(u64, u64)>> {
+        serde_json::de::from_reader(
+            File::open(concat!(
+                env!("CARGO_MANIFEST_DIR"),
+                "/tests/prng_test_cases.json"
+            ))
+            .unwrap(),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn test_lfsr_v1_next() {
+        for (num_shots, sequences) in prng_sequences() {
+            for (seed, expected) in sequences {
+                let sequence = super::generate_lfsr_v1_sequence(seed, num_shots - 1, 1);
+                assert_eq!(sequence.len(), 1);
+                let end_of_sequence = sequence[0];
+                assert_eq!(
+                    end_of_sequence, expected,
+                    "seed={seed}, num_shots={num_shots}",
+                );
+            }
+        }
+    }
+}

{qcs_sdk_python-0.21.12rc4 → qcs_sdk_python-0.21.13}/crates/lib/src/qpu/mod.rs

@@ -16,6 +16,8 @@ use tokio::time::error::Elapsed;
 
 pub mod api;
 mod execution;
+#[cfg(feature = "experimental")]
+pub mod experimental;
 pub mod result_data;
 pub mod translation;