Base Module

The squint.ops.base module contains the core abstractions for building quantum circuits in Squint.

Key Concepts

Wires and Degrees of Freedom

A Wire represents a quantum subsystem with a specific Hilbert space dimension. Each wire can optionally specify a degree of freedom (DoF) type to distinguish between different physical encodings:

• DV - Discrete variable systems (qubits, qudits)
• CV - Continuous variable systems (optical modes in Fock space)
• TimeBin, FreqBin, Spatial - Photonic encoding schemes

Operation Hierarchy

All quantum operations inherit from AbstractOp:

• States: AbstractPureState, AbstractMixedState - Initial quantum states
• Gates: AbstractGate - Unitary transformations
• Channels: AbstractKrausChannel, AbstractErasureChannel - Non-unitary operations
• SharedGate - Parameter sharing across multiple wires (e.g., for phase estimation)
• Block - Grouping multiple operations

Typical Usage

from squint.ops.base import Wire, DV, SharedGate

# Create qubit wires
q0 = Wire(dim=2, dof=DV, idx=0)
q1 = Wire(dim=2, dof=DV, idx=1)

# Use in operations
from squint.ops.dv import DiscreteVariableState, RZGate
state = DiscreteVariableState(wires=(q0,), n=(0,))
phase = RZGate(wires=(q0,), phi=0.0)

---

AbstractDoF

Bases: Module

Abstract base class for degrees of freedom (DoF) in quantum systems.

Degrees of freedom classify the physical encoding of quantum information. Each DoF subclass represents a different physical implementation for encoding quantum states, which can be useful for enforcing circuit validity and distinguishing between different physical platforms.

Subclasses

DV: Discrete variable systems (qubits, qudits) CV: Continuous variable systems (optical modes) TimeBin: Time-bin encoded photonic systems FreqBin: Frequency-bin encoded photonic systems Spatial: Spatial mode encoding

Source code in src/squint/ops/base.py

class AbstractDoF(eqx.Module):
    """
    Abstract base class for degrees of freedom (DoF) in quantum systems.

    Degrees of freedom classify the physical encoding of quantum information.
    Each DoF subclass represents a different physical implementation for
    encoding quantum states, which can be useful for enforcing circuit
    validity and distinguishing between different physical platforms.

    Subclasses:
        DV: Discrete variable systems (qubits, qudits)
        CV: Continuous variable systems (optical modes)
        TimeBin: Time-bin encoded photonic systems
        FreqBin: Frequency-bin encoded photonic systems
        Spatial: Spatial mode encoding
    """

    pass

DV

Bases: AbstractDoF

Discrete variable degree of freedom.

Represents finite-dimensional quantum systems such as qubits (dim=2) or qudits (dim>2). These systems have a finite number of basis states and are commonly implemented in platforms like superconducting circuits, trapped ions, and spin systems.

Example

wire = Wire(dim=2, dof=DV, idx=0)  # A qubit wire

Source code in src/squint/ops/base.py

class DV(AbstractDoF):
    """
    Discrete variable degree of freedom.

    Represents finite-dimensional quantum systems such as qubits (dim=2)
    or qudits (dim>2). These systems have a finite number of basis states
    and are commonly implemented in platforms like superconducting circuits,
    trapped ions, and spin systems.

    Example:
        ```python
        wire = Wire(dim=2, dof=DV, idx=0)  # A qubit wire
        ```
    """

    pass

CV

Bases: AbstractDoF

Continuous variable degree of freedom.

Represents infinite-dimensional Fock space systems, typically optical modes with photon number states. In practice, the Hilbert space is truncated at a finite photon number cutoff specified by the wire dimension.

Example

wire = Wire(dim=10, dof=CV, idx=0)  # Optical mode with 10 photon cutoff

Source code in src/squint/ops/base.py

class CV(AbstractDoF):
    """
    Continuous variable degree of freedom.

    Represents infinite-dimensional Fock space systems, typically optical
    modes with photon number states. In practice, the Hilbert space is
    truncated at a finite photon number cutoff specified by the wire dimension.

    Example:
        ```python
        wire = Wire(dim=10, dof=CV, idx=0)  # Optical mode with 10 photon cutoff
        ```
    """

    pass

TimeBin

Bases: AbstractDoF

Time-bin encoded degree of freedom.

Represents photonic qubits/qudits encoded in discrete time bins. Information is encoded in the arrival time of single photons, commonly used in fiber-based quantum communication.

Example

wire = Wire(dim=2, dof=TimeBin, idx=0)  # Time-bin qubit

Source code in src/squint/ops/base.py

class TimeBin(AbstractDoF):
    """
    Time-bin encoded degree of freedom.

    Represents photonic qubits/qudits encoded in discrete time bins.
    Information is encoded in the arrival time of single photons,
    commonly used in fiber-based quantum communication.

    Example:
        ```python
        wire = Wire(dim=2, dof=TimeBin, idx=0)  # Time-bin qubit
        ```
    """

    pass

FreqBin

Bases: AbstractDoF

Frequency-bin encoded degree of freedom.

Represents photonic qubits/qudits encoded in discrete frequency modes. Information is encoded in the spectral properties of photons, useful for wavelength-division multiplexing in quantum networks.

Example

wire = Wire(dim=4, dof=FreqBin, idx=0)  # 4-level frequency-bin qudit

Source code in src/squint/ops/base.py

class FreqBin(AbstractDoF):
    """
    Frequency-bin encoded degree of freedom.

    Represents photonic qubits/qudits encoded in discrete frequency modes.
    Information is encoded in the spectral properties of photons,
    useful for wavelength-division multiplexing in quantum networks.

    Example:
        ```python
        wire = Wire(dim=4, dof=FreqBin, idx=0)  # 4-level frequency-bin qudit
        ```
    """

    pass

Spatial

Bases: AbstractDoF

Spatial mode encoded degree of freedom.

Represents quantum information encoded in spatial modes of light, such as different paths in an interferometer or transverse spatial modes (e.g., orbital angular momentum modes).

Example

wire = Wire(dim=2, dof=Spatial, idx=0)  # Dual-rail spatial encoding

Source code in src/squint/ops/base.py

class Spatial(AbstractDoF):
    """
    Spatial mode encoded degree of freedom.

    Represents quantum information encoded in spatial modes of light,
    such as different paths in an interferometer or transverse spatial
    modes (e.g., orbital angular momentum modes).

    Example:
        ```python
        wire = Wire(dim=2, dof=Spatial, idx=0)  # Dual-rail spatial encoding
        ```
    """

    pass

Wire

Bases: Module

Represents a quantum subsystem (wire) in a circuit.

A Wire defines a single quantum subsystem with a specific Hilbert space dimension and degree of freedom type. Wires are the fundamental building blocks that connect quantum operations in a circuit, determining how operators act on different parts of the composite quantum system.

Attributes:

Name	Type	Description
dim	int	The dimension of the local Hilbert space. For qubits, dim=2; for qudits, dim>2; for Fock spaces, dim is the photon number cutoff.
dof	type[AbstractDoF]	The type of degree of freedom this wire represents (e.g., DV for discrete variable, CV for continuous variable).
idx	str | int	Unique identifier for the wire, used to track which operations act on which subsystems.

Example

from squint.ops.base import Wire, DV, CV

# Create a qubit wire
qubit = Wire(dim=2, dof=DV, idx=0)

# Create an optical mode wire with photon cutoff of 5
mode = Wire(dim=5, dof=CV, idx="signal")

# Use wires in operations
from squint.ops.dv import DiscreteVariableState, HGate
state = DiscreteVariableState(wires=(qubit,), n=(0,))
gate = HGate(wires=(qubit,))

Source code in src/squint/ops/base.py

class Wire(eqx.Module):
    """
    Represents a quantum subsystem (wire) in a circuit.

    A Wire defines a single quantum subsystem with a specific Hilbert space dimension
    and degree of freedom type. Wires are the fundamental building blocks that connect
    quantum operations in a circuit, determining how operators act on different parts
    of the composite quantum system.

    Attributes:
        dim (int): The dimension of the local Hilbert space. For qubits, dim=2;
            for qudits, dim>2; for Fock spaces, dim is the photon number cutoff.
        dof (type[AbstractDoF]): The type of degree of freedom this wire represents
            (e.g., DV for discrete variable, CV for continuous variable).
        idx (str | int): Unique identifier for the wire, used to track which
            operations act on which subsystems.

    Example:
        ```python
        from squint.ops.base import Wire, DV, CV

        # Create a qubit wire
        qubit = Wire(dim=2, dof=DV, idx=0)

        # Create an optical mode wire with photon cutoff of 5
        mode = Wire(dim=5, dof=CV, idx="signal")

        # Use wires in operations
        from squint.ops.dv import DiscreteVariableState, HGate
        state = DiscreteVariableState(wires=(qubit,), n=(0,))
        gate = HGate(wires=(qubit,))
        ```
    """

    idx: int | str = 0
    dim: int
    dof: type[AbstractDoF]

    @beartype
    def __init__(
        self,
        dim: int,
        dof: Optional[type[AbstractDoF]] = AbstractDoF,
        idx: Optional[int | str] = None,
    ):
        """
        Initialize a Wire.

        Args:
            dim (int): The dimension of the local Hilbert space. Must be >= 2.
                For qubits use dim=2, for qudits use dim>2, for Fock spaces
                this is the photon number cutoff.
            dof (type[AbstractDoF], optional): Type of degree of freedom that
                this wire represents. Can be used to enforce circuit validity
                and distinguish between different physical encodings.
                Defaults to AbstractDoF.
            idx (str | int, optional): Unique identifier for the wire. If not
                provided, a random id is generated.

        Raises:
            ValueError: If dim < 2.
        """
        if dim < 2:
            raise ValueError("Dimension should be 2 or greater.")
        if isinstance(idx, int):
            if idx < 0:
                raise ValueError("Wire.idx integers must be positive. Negative integers are reserved for autogenerated identities.")
        self.dim = dim
        self.dof = dof
        # self.idx = idx if idx is not None else str(uuid4())
        # self.idx = idx if idx is not None else next(_wire_id)
        self.idx = idx if idx is not None else -next(_wire_id) - 1
        # self.idx = idx if idx is not None else f"__w{next(_wire_id)}"

    def __eq__(self, other: object) -> bool:
        return isinstance(other, Wire) and self.idx == other.idx

    def __hash__(self) -> int:
        return hash(self.idx)

__init__(dim: int, dof: Optional[type[AbstractDoF]] = AbstractDoF, idx: Optional[int | str] = None)

Initialize a Wire.

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the local Hilbert space. Must be >= 2. For qubits use dim=2, for qudits use dim>2, for Fock spaces this is the photon number cutoff.	required
dof	type[AbstractDoF]	Type of degree of freedom that this wire represents. Can be used to enforce circuit validity and distinguish between different physical encodings. Defaults to AbstractDoF.	AbstractDoF
idx	str | int	Unique identifier for the wire. If not provided, a random id is generated.	None

Raises:

Type	Description
ValueError	If dim < 2.

Source code in src/squint/ops/base.py

@beartype
def __init__(
    self,
    dim: int,
    dof: Optional[type[AbstractDoF]] = AbstractDoF,
    idx: Optional[int | str] = None,
):
    """
    Initialize a Wire.

    Args:
        dim (int): The dimension of the local Hilbert space. Must be >= 2.
            For qubits use dim=2, for qudits use dim>2, for Fock spaces
            this is the photon number cutoff.
        dof (type[AbstractDoF], optional): Type of degree of freedom that
            this wire represents. Can be used to enforce circuit validity
            and distinguish between different physical encodings.
            Defaults to AbstractDoF.
        idx (str | int, optional): Unique identifier for the wire. If not
            provided, a random id is generated.

    Raises:
        ValueError: If dim < 2.
    """
    if dim < 2:
        raise ValueError("Dimension should be 2 or greater.")
    if isinstance(idx, int):
        if idx < 0:
            raise ValueError("Wire.idx integers must be positive. Negative integers are reserved for autogenerated identities.")
    self.dim = dim
    self.dof = dof
    # self.idx = idx if idx is not None else str(uuid4())
    # self.idx = idx if idx is not None else next(_wire_id)
    self.idx = idx if idx is not None else -next(_wire_id) - 1

AbstractOp

Bases: Module

An abstract base class for all quantum objects, including states, gates, channels, and measurements. It provides a common interface for various quantum objects, ensuring consistency and reusability across different types of quantum operations.

Attributes:

Name	Type	Description
wires	tuple[int, ...]	A tuple of nonnegative integers representing the quantum wires on which the operation acts. Each wire corresponds to a specific subsystem in the composite quantum system.

Source code in src/squint/ops/base.py

class AbstractOp(eqx.Module):
    """
    An abstract base class for all quantum objects, including states, gates, channels, and measurements.
    It provides a common interface for various quantum objects, ensuring consistency and reusability across different types
    of quantum operations.

    Attributes:
        wires (tuple[int, ...]): A tuple of nonnegative integers representing the quantum wires
                                 on which the operation acts. Each wire corresponds to a specific subsystem
                                 in the composite quantum system.
    """

    wires: tuple[Wire, ...]

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        """
        Initializes the AbstractOp instance.

        Args:
            wires (tuple[int, ...], optional): A tuple of nonnegative integers representing the quantum wires
                                               on which the operation acts. Defaults to (0, 1).

        Raises:
            TypeError: If any wire in the provided tuple is not a nonnegative integer.
        """
        # if not all([wire >= 0 for wire in wires]):
        # raise TypeError("All wires must be nonnegative ints.")
        self.wires = wires
        return

    def unwrap(self):
        """
        A base method for unwrapping an operator into constituent parts, important in, e.g., shared weights across operators.

        This method can be overridden by subclasses to provide additional unwrapping functionality, such as
        decomposing composite operations into their components.

        Returns:
            ops (tuple[AbstractOp]): A tuple of AbstractOp which represent the constituent ops.
        """
        return (self,)

__init__(wires: Sequence[Wire])

Initializes the AbstractOp instance.

Parameters:

Name	Type	Description	Default
wires	tuple[int, ...]	A tuple of nonnegative integers representing the quantum wires on which the operation acts. Defaults to (0, 1).	required

Raises:

Type	Description
TypeError	If any wire in the provided tuple is not a nonnegative integer.

Source code in src/squint/ops/base.py

def __init__(
    self,
    wires: Sequence[Wire],
):
    """
    Initializes the AbstractOp instance.

    Args:
        wires (tuple[int, ...], optional): A tuple of nonnegative integers representing the quantum wires
                                           on which the operation acts. Defaults to (0, 1).

    Raises:
        TypeError: If any wire in the provided tuple is not a nonnegative integer.
    """
    # if not all([wire >= 0 for wire in wires]):
    # raise TypeError("All wires must be nonnegative ints.")
    self.wires = wires
    return

unwrap()

A base method for unwrapping an operator into constituent parts, important in, e.g., shared weights across operators.

This method can be overridden by subclasses to provide additional unwrapping functionality, such as decomposing composite operations into their components.

Returns:

Name	Type	Description
ops	tuple[AbstractOp]	A tuple of AbstractOp which represent the constituent ops.

Source code in src/squint/ops/base.py

def unwrap(self):
    """
    A base method for unwrapping an operator into constituent parts, important in, e.g., shared weights across operators.

    This method can be overridden by subclasses to provide additional unwrapping functionality, such as
    decomposing composite operations into their components.

    Returns:
        ops (tuple[AbstractOp]): A tuple of AbstractOp which represent the constituent ops.
    """
    return (self,)

AbstractState

Bases: AbstractOp

An abstract base class for all quantum states.

Source code in src/squint/ops/base.py

class AbstractState(AbstractOp):
    r"""
    An abstract base class for all quantum states.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def __call__(self, dim: int):
        raise NotImplementedError

AbstractPureState

Bases: AbstractState

An abstract base class for all pure quantum states, equivalent to the state vector formalism. Pure states are associated with a Hilbert space of size \(|\psi\rangle \in \mathcal{H}^{d_1 \times \dots \times d_w}\) where \(w\) = len(wires) and \(d\) is assigned at compile time.

Source code in src/squint/ops/base.py

class AbstractPureState(AbstractState):
    r"""
    An abstract base class for all pure quantum states, equivalent to the state vector formalism.
    Pure states are associated with a Hilbert space of size
    $|\psi\rangle \in \mathcal{H}^{d_1 \times \dots \times d_w}$
    where $w$ = `len(wires)` and $d$ is assigned at compile time.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def __call__(self, dim: int):
        raise NotImplementedError

AbstractMixedState

Bases: AbstractState

An abstract base class for all mixed quantum states, equivalent to the density matrix formalism. Mixed states are associated with a Hilbert space of size \(\rho \in \mathcal{H}^{d_1 \times \dots \times d_w \times d_1 \times \dots \times d_w}\) where \(w\) = len(wires) and \(d\) is assigned at compile time.

Source code in src/squint/ops/base.py

class AbstractMixedState(AbstractState):
    r"""
    An abstract base class for all mixed quantum states, equivalent to the density matrix formalism.
    Mixed states are associated with a Hilbert space of size
    $\rho \in \mathcal{H}^{d_1 \times \dots \times d_w \times d_1 \times \dots \times d_w}$
    where $w$ = `len(wires)` and $d$ is assigned at compile time.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def __call__(self, dim: int):
        raise NotImplementedError

AbstractGate

Bases: AbstractOp

An abstract base class for all unitary quantum gates, which transform an input state in a reversible way. \(U \in \mathcal{H}^{d_1 \times \dots \times d_w \times d_1 \times \dots \times d_w}\) where \(w\) = len(wires) and \(d\) is assigned at compile time.

Source code in src/squint/ops/base.py

class AbstractGate(AbstractOp):
    r"""
    An abstract base class for all unitary quantum gates, which transform an input state in a reversible way.
    $U \in \mathcal{H}^{d_1 \times \dots \times d_w \times d_1 \times \dots \times d_w}$
    where $w$ = `len(wires)` and $d$ is assigned at compile time.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def __call__(self, dim: int):
        raise NotImplementedError

AbstractChannel

Bases: AbstractOp

An abstract base class for quantum channels, including channels expressed as Kraus operators, erasure (partial trace), and others.

Source code in src/squint/ops/base.py

class AbstractChannel(AbstractOp):
    r"""
    An abstract base class for quantum channels, including channels expressed as Kraus operators, erasure (partial trace), and others.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def unwrap(self):
        return (self,)

    def __call__(self, dim: int):
        raise NotImplementedError

AbstractMeasurement

Bases: AbstractOp

An abstract base class for quantum measurements. Currently, this is not supported, and measurements are projective measurements in the computational basis.

Source code in src/squint/ops/base.py

class AbstractMeasurement(AbstractOp):
    r"""
    An abstract base class for quantum measurements. Currently, this is not supported, and measurements are projective measurements in the computational basis.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def __call__(self, dim: int):
        raise NotImplementedError

SharedGate

Bases: AbstractGate

A class representing a shared quantum gate, which allows for the sharing of parameters or attributes across multiple copies of a quantum operation. This is useful for scenarios where multiple gates share the same underlying structure or parameters, such as in variational quantum circuits. This is most commonly used when applying the same parameterized gate across different wires, e.g., phase gates, for studying phase estimation protocols.

Attributes:

Name	Type	Description
op	AbstractOp	The base quantum operation that is shared across multiple copies.
copies	Sequence[AbstractOp]	A sequence of copies of the base operation, each acting on different wires.
where	Callable	A function that determines which attributes of the operation are shared across copies.
get	Callable	A function that retrieves the shared attributes from the base operation.

Source code in src/squint/ops/base.py

class SharedGate(AbstractGate):
    r"""
    A class representing a shared quantum gate, which allows for the sharing of parameters or attributes
    across multiple copies of a quantum operation. This is useful for scenarios where multiple gates
    share the same underlying structure or parameters, such as in variational quantum circuits.
    This is most commonly used when applying the same parameterized gate across different wires,
    e.g., phase gates, for studying phase estimation protocols.

    Attributes:
        op (AbstractOp): The base quantum operation that is shared across multiple copies.
        copies (Sequence[AbstractOp]): A sequence of copies of the base operation, each acting on different wires.
        where (Callable): A function that determines which attributes of the operation are shared across copies.
        get (Callable): A function that retrieves the shared attributes from the base operation.
    """

    op: AbstractOp
    copies: Sequence[AbstractOp]
    where: Callable
    get: Callable

    @beartype
    def __init__(
        self,
        op: AbstractOp,
        wires: Union[Sequence[Wire], Sequence[Sequence[Wire]]],
        where: Optional[Callable] = None,
        get: Optional[Callable] = None,
    ):
        # todo: handle the wires coming from both main and the shared wires
        copies = [eqx.tree_at(lambda op: op.wires, op, (wire,)) for wire in wires]
        self.copies = copies
        self.op = op

        if is_bearable(wires, Sequence[Wire]):
            wires = op.wires + wires

        elif is_bearable(wires, Sequence[Sequence[Wire]]):
            wires = op.wires + tuple(itertools.chain.from_iterable(wires))

        # wires = op.wires + wires
        super().__init__(wires=wires)

        # use a default where/get sharing mechanism, such that all ArrayLike attributes are shared exactly
        attrs = [key for key, val in op.__dict__.items() if eqx.is_array_like(val)]

        if where is None:  # todo: check  get/where functions if it is user-defined
            where = lambda pytree: sum(
                [[copy.__dict__[key] for copy in pytree.copies] for key in attrs], []
            )
        if get is None:
            get = lambda pytree: sum(
                [[pytree.op.__dict__[key] for _ in pytree.copies] for key in attrs], []
            )
        self.where = where
        self.get = get

        return

    def __check_init__(self):
        return object.__setattr__(
            self,
            "__dict__",
            eqx.tree_at(self.where, self, replace_fn=lambda _: None).__dict__,
        )

    def unwrap(self):
        """Unwraps the shared ops for compilation and contractions."""
        _self = eqx.tree_at(
            self.where, self, self.get(self), is_leaf=lambda leaf: leaf is None
        )
        return [_self.op] + [op for op in _self.copies]

unwrap()

Unwraps the shared ops for compilation and contractions.

Source code in src/squint/ops/base.py

def unwrap(self):
    """Unwraps the shared ops for compilation and contractions."""
    _self = eqx.tree_at(
        self.where, self, self.get(self), is_leaf=lambda leaf: leaf is None
    )
    return [_self.op] + [op for op in _self.copies]

AbstractKrausChannel

Bases: AbstractChannel

An abstract base class for quantum channels expressed as Kraus operators. The channel \(K\) is of shape \((d_1 \times \dots \times d_w \times d_1 \times \dots \times d_w)\) where \(w\) = len(wires) and \(d\) is assigned at compile time.

Source code in src/squint/ops/base.py

class AbstractKrausChannel(AbstractChannel):
    r"""
    An abstract base class for quantum channels expressed as Kraus operators.
    The channel $K$ is of shape $(d_1 \times \dots \times d_w \times d_1 \times \dots \times d_w)$
    where $w$ = `len(wires)` and $d$ is assigned at compile time.
    """

    def __init__(
        self,
        wires: Sequence[Wire],
    ):
        super().__init__(wires=wires)
        return

    def unwrap(self):
        return (self,)

    def __call__(self, dim: int):
        raise NotImplementedError

AbstractErasureChannel

Bases: AbstractChannel

This channel traces out the local Hilbert space associated with the wires

Source code in src/squint/ops/base.py

class AbstractErasureChannel(AbstractChannel):
    """
    This channel traces out the local Hilbert space associated with the `wires`
    """

    @beartype
    def __init__(self, wires: Sequence[Wire]):
        super().__init__(wires=wires)
        return

    def __call__(self, dim: int):
        return None

Block

Bases: Module

A block operation that groups a sequence of quantum operations.

Blocks allow organizing multiple operations into a single logical unit. They can be nested within circuits or other blocks, and support the same add and unwrap interface as Circuit. Unlike Circuit, Block does not specify a backend and is purely for organizational purposes.

Attributes:

Name	Type	Description
ops	OrderedDict	Ordered dictionary mapping keys to operations or nested blocks.

Example

from squint.ops.base import Block, Wire
from squint.ops.dv import RXGate, RYGate

wire = Wire(dim=2, idx=0)
block = Block()
block.add(RXGate(wires=(wire,), phi=0.1), "rx")
block.add(RYGate(wires=(wire,), phi=0.2), "ry")

# Use in a circuit
circuit.add(block, "rotation_block")

Source code in src/squint/ops/base.py

class Block(eqx.Module):
    """
    A block operation that groups a sequence of quantum operations.

    Blocks allow organizing multiple operations into a single logical unit.
    They can be nested within circuits or other blocks, and support the same
    `add` and `unwrap` interface as Circuit. Unlike Circuit, Block does not
    specify a backend and is purely for organizational purposes.

    Attributes:
        ops (OrderedDict): Ordered dictionary mapping keys to operations or nested blocks.

    Example:
        ```python
        from squint.ops.base import Block, Wire
        from squint.ops.dv import RXGate, RYGate

        wire = Wire(dim=2, idx=0)
        block = Block()
        block.add(RXGate(wires=(wire,), phi=0.1), "rx")
        block.add(RYGate(wires=(wire,), phi=0.2), "ry")

        # Use in a circuit
        circuit.add(block, "rotation_block")
        ```
    """

    ops: OrderedDict[Union[str, int], Union[AbstractOp, "Block"]]

    @beartype
    def __init__(self):
        """
        Initialize an empty Block.

        Creates a new Block with no operations. Operations can be added
        using the `add` method.
        """
        self.ops = OrderedDict()

    @property
    def wires(self) -> Sequence[Wire]:
        """
        Get all wires used by operations in this block.

        Returns:
            set[Wire]: Set of all Wire objects that operations in this block act on.
        """
        # BUG: this line caused a bug with undefined wire order
        # return set(sum((op.wires for op in self.unwrap()), ()))
        return OrderedSet(
            sorted(
                dict.fromkeys(
                    itertools.chain.from_iterable(op.wires for op in self.unwrap())
                ),
                key=wire_sort_key,
            )
        )

    @beartype
    def add(self, op: Union[AbstractOp, "Block"], key: str = None) -> None:
        """
        Add an operator to the block.

        Operators are added sequentially. When this block is used in a circuit,
        the operations will be applied in the order they were added.

        Args:
            op (AbstractOp | Block): The operator or nested block to add.
            key (str, optional): A string key for indexing into the block's ops
                dictionary. If None, an integer counter is used as the key.
        """

        if key is None:
            key = len(self.ops)
        self.ops[key] = op

    def unwrap(self) -> tuple[AbstractOp]:
        """
        Unwrap all operators in the block into a flat tuple.

        Recursively calls `unwrap()` on all contained operations and nested
        blocks to produce a flat sequence of atomic operations.

        Returns:
            tuple[AbstractOp]: Flattened tuple of all operations in order.
        """
        return tuple(
            op for op_wrapped in self.ops.values() for op in op_wrapped.unwrap()
        )

wires: Sequence[Wire] property

Get all wires used by operations in this block.

Returns:

Type	Description
Sequence[Wire]	set[Wire]: Set of all Wire objects that operations in this block act on.

__init__()

Initialize an empty Block.

Creates a new Block with no operations. Operations can be added using the add method.

Source code in src/squint/ops/base.py

@beartype
def __init__(self):
    """
    Initialize an empty Block.

    Creates a new Block with no operations. Operations can be added
    using the `add` method.
    """
    self.ops = OrderedDict()

add(op: Union[AbstractOp, Block], key: str = None) -> None

Add an operator to the block.

Operators are added sequentially. When this block is used in a circuit, the operations will be applied in the order they were added.

Parameters:

Name	Type	Description	Default
op	AbstractOp | Block	The operator or nested block to add.	required
key	str	A string key for indexing into the block's ops dictionary. If None, an integer counter is used as the key.	None

Source code in src/squint/ops/base.py

@beartype
def add(self, op: Union[AbstractOp, "Block"], key: str = None) -> None:
    """
    Add an operator to the block.

    Operators are added sequentially. When this block is used in a circuit,
    the operations will be applied in the order they were added.

    Args:
        op (AbstractOp | Block): The operator or nested block to add.
        key (str, optional): A string key for indexing into the block's ops
            dictionary. If None, an integer counter is used as the key.
    """

    if key is None:
        key = len(self.ops)
    self.ops[key] = op

unwrap() -> tuple[AbstractOp]

Unwrap all operators in the block into a flat tuple.

Recursively calls unwrap() on all contained operations and nested blocks to produce a flat sequence of atomic operations.

Returns:

Type	Description
tuple[AbstractOp]	tuple[AbstractOp]: Flattened tuple of all operations in order.

Source code in src/squint/ops/base.py

def unwrap(self) -> tuple[AbstractOp]:
    """
    Unwrap all operators in the block into a flat tuple.

    Recursively calls `unwrap()` on all contained operations and nested
    blocks to produce a flat sequence of atomic operations.

    Returns:
        tuple[AbstractOp]: Flattened tuple of all operations in order.
    """
    return tuple(
        op for op_wrapped in self.ops.values() for op in op_wrapped.unwrap()
    )

create(dim) cached

Returns the create operator for a Hilbert space of dimension dim. The create operator is a matrix that adds one excitation to a quantum system, effectively increasing the energy level by one. Args: dim (int): The dimension of the Hilbert space. Returns: jnp.ndarray: A 2D array of shape (dim, dim) representing the create operator.

Source code in src/squint/ops/base.py

@functools.cache
def create(dim):
    """
    Returns the create operator for a Hilbert space of dimension `dim`.
    The create operator is a matrix that adds one excitation to a quantum system,
    effectively increasing the energy level by one.
    Args:
        dim (int): The dimension of the Hilbert space.
    Returns:
        jnp.ndarray: A 2D array of shape (dim, dim) representing the create operator.
    """
    return jnp.diag(jnp.sqrt(jnp.arange(1, dim)), k=-1)

destroy(dim) cached

Returns the destroy operator for a Hilbert space of dimension dim. The destroy operator is a matrix that annihilates one excitation of a quantum system, effectively reducing the energy level by one. Args: dim (int): The dimension of the Hilbert space. Returns: jnp.ndarray: A 2D array of shape (dim, dim) representing the destroy operator.

Source code in src/squint/ops/base.py

@functools.cache
def destroy(dim):
    """
    Returns the destroy operator for a Hilbert space of dimension `dim`.
    The destroy operator is a matrix that annihilates one excitation of a quantum system,
    effectively reducing the energy level by one.
    Args:
        dim (int): The dimension of the Hilbert space.
    Returns:
        jnp.ndarray: A 2D array of shape (dim, dim) representing the destroy operator.
    """
    return jnp.diag(jnp.sqrt(jnp.arange(1, dim)), k=1)

eye(dim) cached

Returns the identity operator for a Hilbert space of dimension dim.

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the Hilbert space.	required

Returns: jnp.ndarray: A 2D array of shape (dim, dim) representing the identity operator.

Source code in src/squint/ops/base.py

@functools.cache
def eye(dim):
    """
    Returns the identity operator for a Hilbert space of dimension `dim`.

    Args:
        dim (int): The dimension of the Hilbert space.
    Returns:
        jnp.ndarray: A 2D array of shape (dim, dim) representing the identity operator.
    """
    return jnp.eye(dim)

bases(dim) cached

Returns the computational basis indices for a Hilbert space of dimension dim.

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the Hilbert space.	required

Returns:

Type	Description
	jnp.ndarray: A 1D array of shape (dim,) containing the indices of the computational bases.

Source code in src/squint/ops/base.py

@functools.cache
def bases(dim):
    """

    Returns the computational basis indices for a Hilbert space of dimension `dim`.

    Args:
        dim (int): The dimension of the Hilbert space.

    Returns:
        jnp.ndarray: A 1D array of shape (dim,) containing the indices of the computational bases.
    """
    return jnp.arange(dim)

dft(dim) cached

Returns the discrete Fourier transform matrix of dimension dim.

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the DFT matrix.	required

Returns:

Type	Description
	jnp.ndarray: A 2D array of shape (dim, dim) representing the DFT matrix.

Source code in src/squint/ops/base.py

@functools.cache
def dft(dim):
    """
    Returns the discrete Fourier transform matrix of dimension `dim`.

    Args:
        dim (int): The dimension of the DFT matrix.

    Returns:
        jnp.ndarray: A 2D array of shape (dim, dim) representing the DFT matrix.
    """
    return jnp.array(sp.linalg.dft(dim, scale="sqrtn"))

basis_operators(dim) cached

Return a basis of orthogonal Hermitian operators on a Hilbert space of dimension \(d\), with the identity element in the last place. i.e., the Gell-Mann operators (for dim=2, these are the four Pauli operators).

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the Hilbert space.	required

Returns:

Type	Description
	jnp.ndarray: A 3D array of shape (n_operators, dim, dim) containing the basis operators.

Source code in src/squint/ops/base.py

@functools.cache
def basis_operators(dim):
    """
    Return a basis of orthogonal Hermitian operators on a Hilbert space of
    dimension $d$, with the identity element in the last place.
    i.e., the Gell-Mann operators (for dim=2, these are the four Pauli operators).

    Args:
        dim (int): The dimension of the Hilbert space.

    Returns:
        jnp.ndarray: A 3D array of shape (n_operators, dim, dim) containing the basis operators.
    """
    return jnp.array(
        [
            gellmann(j, k, dim)
            for j, k in itertools.product(range(1, dim + 1), repeat=2)
        ],
        jnp.complex128,
    )