"""Guppy structs and definitions for state factories."""
from typing import Generic, no_type_check
from guppylang import guppy
from guppylang.std.builtins import array, exit, panic
from guppylang.std.collections import Queue
from guppylang.std.lang import Function, owned
from guppylang.std.option import Option, nothing, some
from guppylang.std.quantum import Measurement, collect_measurements, qubit
from ._logical_block import LogicalBlock
__all__ = [
"PreBlock",
"StateFactory",
]
BLOCK_SIZE = guppy.nat_var("BLOCK_SIZE")
N_FLAGS = guppy.nat_var("N_FLAGS")
MAX_BATCH_SIZE = guppy.nat_var("MAX_BATCH_SIZE")
@guppy
@no_type_check
def _array_any(arr: array[bool, BLOCK_SIZE]) -> bool:
for i in range(BLOCK_SIZE): # noqa: SIM110 # `all` is not yet supported by Guppy
if arr[i]:
return True
return False
[docs]
@guppy.struct
@no_type_check
class PreBlock(Generic[BLOCK_SIZE, N_FLAGS]): # type: ignore[misc]
"""Logical block that went through state preparation, but may not have succeeded.
The measurement outcomes specifying if it succeeded have not been read. Hence,
the runtime is not blocked by measurements, allowing multiple state preparation to
occur in parallel.
Args:
BLOCK_SIZE: Number of physical qubits in the logical block.
N_FLAGS: Size of the results array
Attributes:
logical_block (LogicalBlock[N]): The candidate logical block
flag_outcomes (array[Measurement, N_FLAGS]): Array of measurement outcomes.
"""
logical_block: LogicalBlock[BLOCK_SIZE] # type: ignore[type-arg, valid-type]
flag_outcomes: array[Measurement, N_FLAGS] # type: ignore[valid-type]
[docs]
@guppy
@no_type_check
def force_check(
self: "PreBlock[BLOCK_SIZE, N_FLAGS]" @ owned,
) -> Option[LogicalBlock[BLOCK_SIZE]]:
"""If preparation was successful, return the block, otherwise return `nothing`.
Calling this forces the measurement of the flags to take place (if they had
not already).
"""
failed = _array_any(collect_measurements(self.flag_outcomes))
if failed:
self.logical_block.discard()
return nothing()
else:
return some(self.logical_block)
@guppy
@no_type_check
def _qalloc_dirty() -> LogicalBlock[BLOCK_SIZE]:
"""Allocate resources for a codeblock, but the qubits are not in a valid logical
state."""
return LogicalBlock(array(qubit() for _ in range(BLOCK_SIZE)))
[docs]
@guppy.struct
class StateFactory(Generic[BLOCK_SIZE, N_FLAGS, MAX_BATCH_SIZE]): # type: ignore[misc]
"""State factory, making preparation attempts in parallel.
Args:
BLOCK_SIZE: Number of physical qubits in the logical block.
N_FLAGS: Number of flag outcomes each `PreBlock` tracks.
MAX_BATCH_SIZE: Maximum number of states produced in the same batch.
Attributes:
prep_routine: Function to prepare a state.
max_attempts: Maximum number of repeat-until-success attempts.
batch: The Queue of elements in the batch. Provide an empty
queue with `guppylang.std.collections.queue.empty_queue`.
"""
prep_routine: Function[[], PreBlock[BLOCK_SIZE, N_FLAGS]] # type: ignore[type-arg,valid-type]
max_attempts: int
batch: Queue[PreBlock[BLOCK_SIZE, N_FLAGS], MAX_BATCH_SIZE] # type: ignore[type-arg,valid-type]
[docs]
@guppy
@no_type_check
def get_state(
self: "StateFactory[BLOCK_SIZE, N_FLAGS, MAX_BATCH_SIZE]",
) -> LogicalBlock[BLOCK_SIZE]:
"""Supply a state using the configured maximum batch size."""
return self.get_state_with_batch_size_limit(int(MAX_BATCH_SIZE))
[docs]
@guppy
@no_type_check
def get_state_with_batch_size_limit(
self: "StateFactory[BLOCK_SIZE, N_FLAGS, MAX_BATCH_SIZE]", batch_size_limit: int
) -> LogicalBlock[BLOCK_SIZE]:
"""Supply a state with at most `batch_size_limit` candidates prepared per batch.
Batch size is bounded by `MAX_BATCH_SIZE` and remaining attempts. Cached
candidates are checked first, even when `batch_size_limit` is zero.
"""
if MAX_BATCH_SIZE <= 0:
panic("StateFactory: MAX_BATCH_SIZE must be greater than zero")
if batch_size_limit < 0:
exit("StateFactory: batch_size_limit must be non-negative")
if batch_size_limit > MAX_BATCH_SIZE:
batch_size_limit = int(MAX_BATCH_SIZE)
for attempt in range(self.max_attempts):
# If empty, request a new batch
if len(self.batch) == 0:
# If `batch_size_limit == 0`, any cached blocks in the
# queue will be checked first. If none were successful,
# no further attempts will be made and the program will
# exit.
if batch_size_limit == 0:
exit("StateFactory: batch_size_limit set to zero")
# Prevent preparing more blocks than remaining attempts
remaining_attempts = self.max_attempts - attempt
count = (
remaining_attempts
if remaining_attempts < batch_size_limit
else batch_size_limit
)
for _ in range(count):
self.batch.push(self.prep_routine())
# Pop an element from batch and check if it successfully prepared a state
pre_block_prep = self.batch.pop()
state = pre_block_prep.force_check()
# If successful, early exit
if state.is_some():
return state.unwrap()
else:
state.unwrap_nothing()
return exit("StateFactory ran out of attempts!")
[docs]
@guppy
@no_type_check
def discard(
self: "StateFactory[BLOCK_SIZE, N_FLAGS, MAX_BATCH_SIZE]" @ owned,
) -> None:
"""Discard all state-preparation candidates in the batch."""
for blk in self.batch:
blk.logical_block.discard()