Source code for pysparq.register_layout
"""Logical registers backed by multiple native words, without truncating high bits.
The C++ machine-word ABI stays intact. Every bit operation still executes on
the real sparse-state backend; logical values are reconstructed as Python ints.
"""
from __future__ import annotations
from typing import Any
from . import _core
WORD_BITS = 64
[docs]
def register_bits(name: str, width: int) -> list[tuple[str, int]]:
"""Resolve one logical register to little-endian native bit coordinates."""
if type(width) is not int or width < 0:
raise ValueError("logical register width must be a nonnegative integer")
if width <= WORD_BITS:
return [(name, bit) for bit in range(width)]
return [(f"{name}__word_{bit // WORD_BITS}", bit % WORD_BITS) for bit in range(width)]
def _active_native_names() -> set[str]:
# Native AddRegister silently permits duplicate names, which would make
# name-based gate addressing ambiguous; screen candidates against the
# live register table first. The 4th tuple element is the active flag.
return {entry[0] for entry in _core.System.name_register_map if entry[3]}
[docs]
class RegisterLayout:
"""Own logical register allocations in one native SparseState.
``add`` returns bit coordinates accepted by native gate operators. ``value``
reads a complete logical word from a basis state, including every high word.
Names must be distinct within the process-global native register namespace.
"""
def __init__(self, state: Any):
self.state = state
self.widths: dict[str, int] = {}
self.words: dict[str, tuple[tuple[str, int], ...]] = {}
def add(self, name: str, kind: Any, width: int) -> list[tuple[str, int]]:
bits = register_bits(name, width)
if name in self.words:
raise ValueError(f"logical register already exists: {name}")
words = ((name, width),) if 0 < width <= WORD_BITS else tuple(
(f"{name}__word_{offset // WORD_BITS}", min(WORD_BITS, width-offset))
for offset in range(0, width, WORD_BITS)
)
clash = {native for native, _ in words} & _active_native_names()
if clash:
raise ValueError(
f"native word register name already in use: {', '.join(sorted(clash))}"
)
allocated = []
try:
for native, size in words:
native_kind = kind if width <= WORD_BITS else _core.StateStorageType.General
_core.AddRegister(native, native_kind, size)(self.state)
allocated.append(native)
except Exception:
for native in reversed(allocated):
_core.RemoveRegister(native)(self.state)
raise
self.widths[name] = width
self.words[name] = words
return bits
def bits(self, name: str) -> list[tuple[str, int]]:
return register_bits(name, self.widths[name])
def value(self, name: str, basis: Any) -> int:
return sum((int(basis.get(_core.System.get_id(native)).value) & ((1 << width)-1))
<< (WORD_BITS*index)
for index, (native, width) in enumerate(self.words[name]))
def remove(self, name: str, *, require_zero: bool = True) -> None:
if require_zero and any(self.value(name, basis) for basis in self.state.basis_states):
raise ValueError(f"logical register not uncomputed: {name}")
for native, _ in reversed(self.words[name]):
_core.RemoveRegister(native)(self.state)
del self.words[name]
del self.widths[name]