paulicirc.circuits

Circuits of Pauli gadgets.

Circuit

final class Circuit(data, num_qubits=None)[source]

Bases: object

A quantum circuit, represented as a sequential composition of Pauli gadgets.

__bytes__()[source]

Serializes a circuit to bytes:

1B fixed to 0x01, to indicate a Circuit encoding
1B encoding the circuit phase dtype (currently, fixed to 0x04 for float64)
8B encoding the number of gadgets, encoded as unsigned big endian
8B encoding the number of qubits, encoded as unsigned big endian
the bytes of the underlying data array, using numpy.ndarray.tobytes

Return type:: bytes

__getitem__(idx)[source]

Accesses the gadget at a given index, or selects/slices a sub-circuit.

Parameters:: idx (SupportsIndex | slice | list[SupportsIndex])
Return type:: Gadget | Circuit

static __new__(cls, data, num_qubits=None)[source]

Constructs a gadget circuit from the given data.

Parameters:

data (CircuitData)
num_qubits (int | None)

Return type:

Self

__setitem__(idx, value)[source]

Writes a gadget at the given index of this circuit, or writes a sub-circuit onto the given selection/slice of this circuit.

Parameters:

idx (SupportsIndex | slice | list[SupportsIndex])
value (Gadget | Circuit)

Return type:

None

clone()[source]

Creates a copy of the gadget circuit.

Return type:: Self

commute(codes)[source]

Commutes adjacent gadget pairs in the circuit according to the given commutation codes.

See Gadget.commute_past for a description of the commutation procedure and associated commutation code conventions.

Parameters:: codes (Sequence[int] | CommutationCodeArray)
Return type:: Self

static from_bytes(bs)[source]

Deserializes a circuit from bytes. See Circuit.__bytes__ for discussion of the encoding.

Parameters:: bs (bytes)
Return type:: Circuit

classmethod from_gadgets(gadgets, num_qubits=None)[source]

Constructs a circuit from the given gadgets.

Parameters:

gadgets (Iterable[Gadget])
num_qubits (int | None)

Return type:

Self

inverse()[source]

Returns the inverse of this graph, with both phases and gadget order inverted.

Return type:: Self

invert_phases()[source]

Inverts phases inplace, keeping gadget order unchanged.

Return type:: None

property is_zero

Whether the circuit is all zero (legs set to _, phases set to 0).

Return type:: bool

iter_gadgets(*, start=0, stop=None, fast=False)[source]

Iterates over the gadgets in the circuit.

If fast is set to True, the gadgets yielded are ephemeral: they should not be stored, as the same object will be reused in each iteration.

Parameters:

start (int; default = 0)
stop (int | None)
fast (bool; default = False)

Return type:

Iterable[Gadget]

property legs

The 2D array of gadget legs for this circuit.

Return type:: PauliArray2D

property listing

Returns a listing of the circuit.

Return type:: CircuitListing

property num_gadgets

Number of gadgets in the circuit.

Return type:: int

property num_qubits

Number of qubits in the circuit.

Return type:: int

property phases

Array of phases for the gadgets in the circuit.

Return type:: PhaseArray

classmethod random(num_gadgets, num_qubits, *, rng=None)[source]

Constructs a circuit with the given number of gadgets and qubits, where all gadgets have random legs and random phase.

Parameters:

num_gadgets (int)
num_qubits (int)
rng (int | RNG | None)

Return type:

Self

statevec(input, canonical_phase=True, _use_cupy=False)[source]

Computes the statevector resulting from the application of this gadget circuit to the given input statevector.

Parameters:

input (ComplexArray1D | FloatArray1D)
canonical_phase (bool; default = True)
_use_cupy (bool; default = False)

Return type:

Complex128Array1D

unitary(*, canonical_phase=True, _use_cupy=False)[source]

Returns the unitary matrix associated to this Pauli gadget circuit.

Parameters:

canonical_phase (bool; default = True)
_use_cupy (bool; default = False)

Return type:

Complex128Array2D

classmethod zero(num_gadgets, num_qubits)[source]

Constructs a circuit with the given number of gadgets and qubits, where all gadgets have no legs and zero phase.

Parameters:

num_gadgets (int)
num_qubits (int)

Return type:

Self

CircuitData

CircuitData

Type alias for data encoding a circuit of Pauli gadgets.

alias of ndarray[tuple[int, …], dtype[uint8]]

CircuitListing

final class CircuitListing(circuit, selection=None)[source]

Bases: object

A listing for a quantum circuit.

static __new__(cls, circuit, selection=None)[source]

Instantiates a new listing for the given circuit, with optional starting and/or stopping gadget indices.

Parameters:

circuit (Circuit)
selection (tuple[int, int] | None)

Return type:

Self

__repr__()[source]

Creates a string listing of the circuit, with gadgets listed one per line, in the format idx phase paulistr.

Return type:: str

CommutationCodeArray

CommutationCodeArray

A 1D array of commutation codes, used by Circuit.commute.

See Gadget.commute_past for a description of the commutation procedure and associated commutation code conventions.

alias of ndarray[tuple[int, …], dtype[uint8]]

commute_circuit

commute_circuit(circ, codes)[source]

Low-level function. Commutes subsequent gadget pairs in the circuit according to the given codes. Expects the number of codes to be m//2, where m is the number of gadgets.

See Gadget.commute_past for a description of the commutation procedure and associated commutation code conventions.

Parameters:

circ (CircuitData)
codes (CommutationCodeArray)

Return type:

CircuitData

get_circuit_legs

get_circuit_legs = CPUDispatcher(<function get_circuit_legs>)[source]: Low-level function. Extract a 2D array of leg information from given circuit data. The returned array has values in range(4), where the encoding is explained in GadgetData.

rand_circ

rand_circ(m, n, *, rng)[source]

Low-level function. Returns a uniformly random circuit with m gadgets on n qubits.

Parameters:

m (int)
n (int)
rng (RNG)

Return type:

CircuitData

set_circuit_legs

set_circuit_legs(circ, legs)[source]

Low-level function. Sets leg information in the given circuit data. The input array should have values in range(4), where the encoding is explained in GadgetData.

Parameters:

circ (CircuitData)
legs (PauliArray2D)

Return type:

None

statevec_from_gadgets

statevec_from_gadgets(self, input, canonical_phase=True, _use_cupy=False)[source]

Low-level function. Computes the statevector resulting from the application of the given gadgets to the given input statevector.

Parameters:

self (Iterable[Gadget])
input (ComplexArray1D | FloatArray1D)
canonical_phase (bool; default = True)
_use_cupy (bool; default = False)

Return type:

Complex128Array1D

transversal_set_gadget_leg_at

transversal_set_gadget_leg_at = CPUDispatcher(<function transversal_set_gadget_leg_at>)[source]: Low-level function. Sets single leg data to the given circuit data, transversally over multiple gadget indices and qubits.

transversal_set_phase

transversal_set_phase = CPUDispatcher(<function transversal_set_phase>)[source]: Low-level function. Sets phase data, transversally over multiple gadget indices.