pysparq 源代码

"""
PySparQ - Python bindings for QRAM-Simulator's sparse-state quantum circuit simulator.

PySparQ provides a high-performance Python interface to the sparse-state quantum
simulator with native QRAM support and Register Level Programming paradigm.

Basic Usage:
    >>> import pysparq as ps
    >>> ps.System.clear()
    >>> ps.System.add_register("q", ps.UnsignedInteger, 4)
    >>> state = ps.SparseState()
    >>> ps.Init_Unsafe("q", 5)(state)
    >>> ps.pprint(state)                         # print to stdout (Detail mode)
    >>> str(state)                               # __str__ → Detail mode string
    >>> repr(state)                              # __repr__ → Detail mode string
    >>> ps.StatePrint(state)                     # returns Detail mode string
    >>> ps.StatePrint(state, ps.StatePrintDisplay.Default)  # explicit mode

Key Features:
    - Register Level Programming: Operate on named registers instead of individual qubits
    - Sparse State Simulation: Efficiently simulate states with few non-zero amplitudes
    - Native QRAM Support: Quantum Random Access Memory for efficient data loading
    - High Performance: C++ core with Python bindings

Display Modes (StatePrintDisplay):
    - Default (0):  Brief format — amplitude and register values only
    - Detail  (1):  Register header + amplitude + named register values
    - Binary  (2):  Register values shown in binary
    - Prob    (4):  Amplitude + probability for each basis state
    Modes can be OR'd together: Detail | Prob

See Also:
    - Documentation: https://iai-ustc-quantum.github.io/QRAM-Simulator/
    - C++ API Docs: https://iai-ustc-quantum.github.io/QRAM-Simulator/api/
    - SparQ Paper: https://arxiv.org/abs/2503.15118
    - QRAM Paper: https://arxiv.org/abs/2503.13832
"""

from __future__ import annotations

# Version from installed dist-info metadata. setuptools-scm's write_to file
# is excluded from wheels by scikit-build-core's gitignore filtering (pysparq
# <= 0.1.1 shipped with __version__ == "0.0.0.dev0" because of this), so read
# the metadata instead, which always carries the setuptools-scm version.
try:
    from importlib.metadata import PackageNotFoundError, version as _dist_version

    __version__: str = _dist_version("pysparq")
except PackageNotFoundError:  # source tree without metadata
    __version__ = "0.0.0.dev0"

# Import everything from _core, then shadow StatePrint/print with Python functions.
# Using a targeted import + re-bind pattern (rather than "from ._core import *")
# so that we can override StatePrint without name collision.
import pysparq._core as _core
from pysparq._core import (
    SparseState,
    System,
    StateStorage,
    StateStorageType,
    # Expose StateStorageType values at module level for convenience
    UnsignedInteger,
    SignedInteger,
    Boolean,
    Rational,
    General as StateStorageType_General,
    SparseMatrix,
    DenseMatrix_complex,
    DenseMatrix_float64,
    BaseOperator,
    SelfAdjointOperator,
    # Operators
    AddRegister,
    AddRegisterWithHadamard,
    RemoveRegister,
    MoveBackRegister,
    SplitRegister,
    CombineRegister,
    Push,
    Pop,
    ClearZero,
    Normalize,
    Init_Unsafe,
    ModuleInheritance_Test,
    ModuleInheritance_Test_SelfAdjoint,
    CheckNormalization,
    CheckNan,
    ViewNormalization,
    TestRemovable,
    CheckDuplicateKey,
    Hadamard_Int,
    Hadamard_Int_Full,
    Hadamard_Bool,
    Hadamard_Partial,
    ZeroConditionalPhaseFlip,
    Reflection_Bool,
    GlobalPhase,
    PartialTrace,
    PartialTraceSelect,
    PartialTraceSelectRange,
    # Seedable measurement / reset / probability (dynamic executor support)
    MeasureZ,
    Reset,
    Probability,
    set_seed,
    get_seed,
    reseed,
    time_seed,
    QFT,
    InverseQFT,
    QRAMCircuit_qutrit,
    QRAMLoad,
    QRAMLoadFast,
    X_Bool,
    FlipBools,
    Swap_Bool_Bool,
    ShiftLeft_InPlace,
    ShiftRight_InPlace,
    Mult_UInt_ConstUInt,
    Add_Mult_UInt_ConstUInt_InPlace,
    Mod_Mult_UInt_ConstUInt_InPlace,
    Add_UInt_UInt,
    Add_UInt_UInt_InPlace,
    Add_UInt_ConstUInt,
    Add_ConstUInt_InPlace,
    Div_Sqrt_Arccos_UInt_UInt,
    Sqrt_Div_Arccos_Int_UInt,
    GetRotateAngle_Int_Int,
    # Arithmetic extension ops (width & truncation convention, docs/operators.md)
    Sub_UInt_UInt,
    Neg_UInt,
    Abs_SInt,
    Mul_UInt_UInt,
    Div_UInt_UInt,
    Sqrt_UInt,
    Select_Bool_UInt_UInt,
    And_UInt_UInt,
    Or_UInt_UInt,
    Xor_UInt_UInt,
    Less_SInt_SInt,
    Carry_UInt_UInt,
    Overflow_SInt_SInt,
    MulOverflow_UInt_UInt,
    IsZero_UInt,
    Negative_SInt,
    Add_AnyInt_AnyInt_InPlace,
    Assign,
    Compare_UInt_UInt,
    Less_UInt_UInt,
    Swap_General_General,
    GetMid_UInt_UInt,
    CustomArithmetic,
    StateHashExceptKey,
    StateHashExceptQubits,
    StateEqualExceptKey,
    StateEqualExceptQubits,
    StateLessExceptKey,
    StateLessExceptQubits,
    Rot_GeneralUnitary,
    Rot_GeneralStatePrep,
    stateprep_unitary_build_schmidt,
    SortExceptKey,
    SortByKey,
    SortExceptBit,
    SortExceptKeyHadamard,
    SortUnconditional,
    SortByAmplitude,
    SortByKey2,
    Phase_Bool,
    Rot_Bool,
    Y_Bool,
    Z_Bool,
    S_Bool,
    T_Bool,
    RX_Bool,
    RY_Bool,
    RZ_Bool,
    SX_Bool,
	    U2_Bool,
	    U3_Bool,
	    CondRot_Rational_Bool,
	    CondRot_Fixed_Bool,
	    GetQWRotateAngle_Int_Int_Int,
	    QuantumBinarySearch_Fast,
	    GetRowAddr,
    GetDataAddr,
    PlusOneAndOverflow,
    # Utilities
    split_systems,
    combine_systems,
    merge_system,
    remove_system,
    # Enums
    StatePrintDisplay,
    # Note: StatePrint (C++ class) is NOT imported here — we shadow it below
)
from .dynamic_operator import compile_operator, CompilationError, DynamicOperatorError


# --------------------------------------------------------------------
# State string formatting (shadows _core.StatePrint)
# --------------------------------------------------------------------

[文档] def StatePrint( state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0, ) -> str: """Return a formatted string representation of a SparseState. This is the primary way to convert a SparseState to a string. ``ps.StatePrint(state)`` is equivalent to ``str(state)`` but allows explicit control over display mode and precision. Args: state: The SparseState to format. mode: Display mode (int or StatePrintDisplay enum). Defaults to Detail (1) — shows register names and types. See ``StatePrintDisplay`` for available modes. precision: Number of decimal places for floating-point numbers. Defaults to 0 (uses the state's default). Returns: A formatted string describing the quantum state. Example: >>> ps.System.clear() >>> ps.AddRegister("q", ps.UnsignedInteger, 2)(ps.SparseState()) >>> ps.Init_Unsafe("q", 1)(ps.SparseState()) >>> state = ps.SparseState() >>> ps.Hadamard_Int("q", 2)(state) >>> ps.StatePrint(state) # Detail mode (default) >>> ps.StatePrint(state, mode=ps.StatePrintDisplay.Default) >>> ps.StatePrint(state, mode=ps.StatePrintDisplay.Binary) >>> ps.StatePrint(state, mode=ps.StatePrintDisplay.Prob) """ return state.to_string(int(mode), precision)
[文档] def to_string( state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0, ) -> str: """Return a formatted string representation of a SparseState. Alias for ``StatePrint(state, mode, precision)`` with Detail mode default. Args: state: The SparseState to format. mode: Display mode. Defaults to Detail (1). precision: Decimal places for floating-point numbers. Returns: A formatted string describing the quantum state. """ return state.to_string(int(mode), precision)
[文档] def pprint(state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0) -> None: """Print a SparseState to stdout in the specified display mode. This function prints directly to standard output, which is captured correctly by Jupyter and IPython notebooks. Args: state: The SparseState to print. mode: Display mode. Defaults to Detail (1). precision: Decimal places for floating-point numbers. Example: >>> ps.System.clear() >>> ps.AddRegister("q", ps.UnsignedInteger, 2)(ps.SparseState()) >>> state = ps.SparseState() >>> ps.Hadamard_Int("q", 2)(state) >>> ps.pprint(state) # prints to stdout in Detail mode >>> ps.pprint(state, mode=ps.StatePrintDisplay.Prob) # Prob mode """ result = state.to_string(int(mode), precision) import sys sys.stdout.write(result + '\n')
[文档] class StatePrinter: """Reusable state formatter with configurable default mode. Provides a stateful formatter that holds a persistent mode and precision setting. Useful when printing many states in the same format. Args: mode: Default display mode. Defaults to Detail (1). precision: Default decimal precision. Defaults to 0. Example: >>> printer = StatePrinter(ps.StatePrintDisplay.Prob) >>> printer(state1) # uses Prob mode >>> printer(state2) # uses Prob mode >>> printer(state3, mode=ps.StatePrintDisplay.Binary) # override """ def __init__( self, mode: int | StatePrintDisplay = 1, precision: int = 0, ): self.mode = int(mode) self.precision = precision
[文档] def __call__( self, state: SparseState, mode: int | StatePrintDisplay | None = None, ) -> str: """Format a state using this printer's mode (or override it). Args: state: The SparseState to format. mode: Optional mode override for this call. Returns: Formatted string representation. """ effective_mode = int(mode) if mode is not None else self.mode return state.to_string(effective_mode, self.precision)
def __str__(self) -> str: return f"StatePrinter(mode={self.mode}, precision={self.precision})" def __repr__(self) -> str: return self.__str__()
# -------------------------------------------------------------------- # Test utilities # -------------------------------------------------------------------- def test_import() -> None: """Test that PySparQ imports are working correctly. This function tests basic functionality including: - Module creation - SparseState creation - BaseOperator and SelfAdjointOperator behavior Raises: RuntimeError: If any test fails ImportError: If imports are not working correctly Example: >>> import pysparq as ps >>> ps.test_import() Test import passed. """ # Test imports module1 = ModuleInheritance_Test() print("module1 created.") sparse_state = SparseState() print("sparse_state created.") try: # this should be OK module1(sparse_state) print("Test module1 passed.") except Exception as e: print("Test import failed. Details: ") raise e try: # this should raise RuntimeError module1.dag(sparse_state) raise ImportError("Test import failed. dag() should raise an error.") except RuntimeError as e: # Test import passed. dag() raised a RuntimeError as expected. print(f"Test module1.dag passed. {e}") except ImportError as e: print("Test import failed (dag should raise an exception). Details: ") raise e except Exception as e: print("Test import failed. Details: ") raise e module2 = ModuleInheritance_Test_SelfAdjoint() print("module2 created.") try: # this should be OK module2.dag(sparse_state) print("Test module2.dag passed.") module2(sparse_state) print("Test module2 passed.") except Exception as e: print("Test import failed. Details: ") raise e print("Test import passed.") # -------------------------------------------------------------------- # Algorithm utilities # -------------------------------------------------------------------- from pysparq.algorithms.state_preparation import make_tree_and_qram from pysparq.algorithms.qda_solver import ( qda_solve, qda_solve_tridiagonal, qda_solve_via_qram, ) # -------------------------------------------------------------------- # RIR (QECC.Lang intermediate representation) execution # -------------------------------------------------------------------- from pysparq.rir import RIRError, RIRResult, load_rir, run_rir, run_rir_file from pysparq.register_layout import RegisterLayout # -------------------------------------------------------------------- # Deprecated operator aliases (naming refactor; see docs/naming_conventions.md) # -------------------------------------------------------------------- # Old names resolve to their renamed classes and emit a DeprecationWarning. # Remove these aliases (and the matching C++ ``using`` aliases) in the next # major version. import warnings _DEPRECATED_ALIASES = { "Xgate_Bool": "X_Bool", "Ygate_Bool": "Y_Bool", "Zgate_Bool": "Z_Bool", "Sgate_Bool": "S_Bool", "Tgate_Bool": "T_Bool", "RXgate_Bool": "RX_Bool", "RYgate_Bool": "RY_Bool", "RZgate_Bool": "RZ_Bool", "SXgate_Bool": "SX_Bool", "U2gate_Bool": "U2_Bool", "U3gate_Bool": "U3_Bool", "inverseQFT": "InverseQFT", "GlobalPhase_Int": "GlobalPhase", "AddAssign_AnyInt_AnyInt_InPlace": "Add_AnyInt_AnyInt_InPlace", "Div_Sqrt_Arccos_Int_Int": "Div_Sqrt_Arccos_UInt_UInt", "Sqrt_Div_Arccos_Int_Int": "Sqrt_Div_Arccos_Int_UInt", "Hadamard_PartialQubit": "Hadamard_Partial", "QuantumBinarySearchFast": "QuantumBinarySearch_Fast", } def __getattr__(name: str): new_name = _DEPRECATED_ALIASES.get(name) if new_name is None: raise AttributeError(f"module {__name__!r} has no attribute {name!r}") warnings.warn( f"pysparq.{name} is deprecated; use pysparq.{new_name} instead " "(docs/naming_conventions.md)", DeprecationWarning, stacklevel=2, ) return globals()[new_name]