circuit

Quantum circuit

Classes

DistributedQubitCircuit(nqubit[, name, ...])	Quantum circuit for a distributed state vector.
QubitCircuit(nqubit[, init_state, name, ...])	Quantum circuit for qubits.

class DistributedQubitCircuit(nqubit: int, name: str | None = None, reupload: bool = False, shots: int = 1024)

Bases: QubitCircuit

Quantum circuit for a distributed state vector.

Parameters:

• nqubit (int) – The number of qubits in the circuit.

• name (str | None) – The name of the circuit. Default: None

• reupload (bool) – Whether to use data re-uploading. Default: False

• shots (int) – The number of shots for the measurement. Default: 1024

cnot(control: int, target: int) → None

Add a CNOT gate.

expectation(shots: int | None = None) → Tensor

Get the expectation value according to the final state and observables.

Parameters:

shots (int | None) – The number of shots for the expectation value. Default: None (which means the exact and differentiable expectation value)

forward(data: Tensor | None = None, state: DistributedQubitState | None = None) → DistributedQubitState

Perform a forward pass of the quantum circuit and return the final state.

This method applies the operators of the quantum circuit to the initial state or the given state and returns the resulting state. If data is given, it is used as the input for the encoders. The data must be a 1D tensor.

Parameters:

• data (Tensor | None) – The input data for the encoders. Default: None

• state (DistributedQubitState | None) – The initial state for the quantum circuit. Default: None

measure(shots: int | None = None, with_prob: bool = False, wires: int | list[int] | None = None, block_size: int = 16777216) → dict | None

Measure the final state.

Parameters:

• shots (int | None) – The number of shots for the measurement. Default: None (which means self.shots)

• with_prob (bool) – Whether to show the true probability of the measurement. Default: False

• wires (int | list[int] | None) – The wires to measure. Default: None (which means all wires)

• block_size (int) – The block size for sampling. Default: 2**24

set_init_state(init_state: str | DistributedQubitState = 'zeros') → None

Set the initial state of the circuit.

toffoli(control1: int, control2: int, target: int) → None

Add a Toffoli gate.

class QubitCircuit(nqubit: int, init_state: Any = 'zeros', name: str | None = None, den_mat: bool = False, reupload: bool = False, mps: bool = False, chi: int | None = None, shots: int = 1024)

Bases: Operation

Quantum circuit for qubits.

This class inherits from the Operation class and implements methods for creating, manipulating, and measuring quantum states.

Parameters:

• nqubit (int) – The number of qubits in the circuit.

• init_state (Any) – The initial state of the circuit. Default: 'zeros'

• name (str | None) – The name of the circuit. Default: None

• den_mat (bool) – Whether to use density matrix representation. Default: False

• reupload (bool) – Whether to use data re-uploading. Default: False

• mps (bool) – Whether to use matrix product state representation. Default: False

• chi (int | None) – The bond dimension for matrix product state representation. Default: None

• shots (int) – The number of shots for the measurement. Default: 1024

Raises:

AssertionError – If the type or dimension of init_state does not match nqubit or den_mat.

add(op: Operation, encode: bool = False, wires: int | list[int] | None = None, controls: int | list[int] | None = None) → None

A method that adds an operation to the quantum circuit.

The operation can be a gate, a layer, or another quantum circuit. The method also updates the attributes of the quantum circuit. If wires is specified, the parameters of gates are shared.

Parameters:

• op (Operation) – The operation to add. It is an instance of Operation class or its subclasses, such as Gate, Layer, Channel, or QubitCircuit.

• encode (bool) – Whether the gate or layer is to encode data. Default: False

• wires (int | list[int] | None) – The wires to apply the gate on. It can be an integer or a list of integers specifying the indices of the wires. Default: None (which means the gate has its own wires)

• controls (int | list[int] | None) – The control wires for the gate. It can be an integer or a list of integers specifying the indices of the control wires. Only valid when wires is not None. Default: None (which means the gate has its own control wires)

Raises:

AssertionError – If the input arguments are invalid or incompatible with the quantum circuit.

amp_damp(wires: int, inputs: Any = None, encode: bool = False) → None

Add an amplitude-damping channel.

amplitude_encoding(data: Any) → Tensor

Encode data into quantum states using amplitude encoding.

any(unitary: Any, wires: int | list[int] | None = None, minmax: list[int] | None = None, controls: int | list[int] | None = None, name: str = 'uany') → None

Add an arbitrary unitary gate.

barrier(wires: int | list[int] | None = None) → None

Add a barrier.

bit_flip(wires: int, inputs: Any = None, encode: bool = False) → None

Add a bit-flip channel.

ccx(control1: int, control2: int, target: int) → None

Add a Toffoli gate.

ch(control: int, target: int) → None

Add a controlled Hadamard gate.

cnot(control: int, target: int) → None

Add a CNOT gate.

cnot_ring(minmax: list[int] | None = None, step: int = 1, reverse: bool = False) → None

Add a layer of CNOT gates in a cyclic way.

cp(control: int, target: int, inputs: Any = None, encode: bool = False) → None

Add a controlled phase shift gate.

crx(control: int, target: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Rx gate.

crxx(control: int, target1: int, target2: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Rxx gate.

crxy(control: int, target1: int, target2: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Rxy gate.

cry(control: int, target: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Ry gate.

cryy(control: int, target1: int, target2: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Ryy gate.

crz(control: int, target: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Rz gate.

crzz(control: int, target1: int, target2: int, inputs: Any = None, encode: bool = False) → None

Add a controlled Rzz gate.

cs(control: int, target: int) → None

Add a controlled S gate.

csdg(control: int, target: int) → None

Add a controlled S dagger gate.

cswap(control: int, target1: int, target2: int) → None

Add a Fredkin gate.

ct(control: int, target: int) → None

Add a controlled T gate.

ctdg(control: int, target: int) → None

Add a controlled T dagger gate.

cu(control: int, target: int, inputs: Any = None, encode: bool = False) → None

Add a controlled U3 gate.

cut(wires: int | list[int]) → None

Add a wire-cut operation.

cx(control: int, target: int) → None

Add a CNOT gate.

cxlayer(wires: list[list[int]] | None = None) → None

Add a layer of CNOT gates.

cy(control: int, target: int) → None

Add a controlled Y gate.

cz(control: int, target: int) → None

Add a controlled Z gate.

defer_measure(with_prob: bool = False) → Tensor | tuple[Tensor, list, list]

Get the state vectors and the measurement results after deferred measurement.

depolarizing(wires: int, inputs: Any = None, encode: bool = False) → None

Add a depolarizing channel.

draw(output: str = 'mpl', **kwargs)

Visualize the quantum circuit.

encode(data: Tensor | None) → None

Encode the input data into the quantum circuit parameters.

This method iterates over the encoders of the quantum circuit and initializes their parameters with the input data. If reupload is False, the input data must be at least as long as the number of parameters in the encoders. If reupload is True, the input data can be repeated to fill up the parameters.

Parameters:

data (Tensor | None) – The input data for the encoders, must be a 1D tensor.

Raises:

AssertionError – If reupload is False and the input data is shorter than the number of parameters in the encoders.

expectation(shots: int | None = None) → Tensor

Get the expectation value according to the final state and observables.

Parameters:

shots (int | None) – The number of shots for the expectation value. Default: None (which means the exact and differentiable expectation value)

forward(data: Tensor | None = None, state: Tensor | QubitState | list[Tensor] | MatrixProductState | None = None) → Tensor | list[Tensor]

Perform a forward pass of the quantum circuit and return the final state.

This method applies the operators of the quantum circuit to the initial state or the given state and returns the resulting state. If data is given, it is used as the input for the encoders. The state can be either a MatrixProductState or a QubitState object, or a tensor representation of them. The data must be a 1D or 2D tensor.

Parameters:

• data (Tensor | None) – The input data for the encoders. Default: None

• state (Tensor | QubitState | list[Tensor] | MatrixProductState | None) – The initial state for the quantum circuit. Default: None

Returns:

The final state of the quantum circuit after applying the operators.

Return type:

Tensor | list[Tensor]

fredkin(control: int, target1: int, target2: int) → None

Add a Fredkin gate.

gen_amp_damp(wires: int, inputs: Any = None, encode: bool = False) → None

Add a generalized amplitude-damping channel.

get_amplitude(bits: str) → Tensor

Get the amplitude for the given bit string.

Parameters:

bits (str) – A bit string.

get_prob(bits: str, wires: int | list[int] | None = None) → Tensor

Get the probability for the given bit string.

Parameters:

• bits (str) – A bit string.

• wires (int | list[int] | None) – The wires to measure. It can be an integer or a list of integers specifying the indices of the wires.

get_subexperiments(qubit_labels: Sequence[Hashable] | None = None) → tuple[dict, list[float]]

Generate cutting subexperiments and their associated coefficients.

get_unitary() → Tensor

Get the unitary matrix of the quantum circuit.

h(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add a Hadamard gate.

hamiltonian(hamiltonian: Any, t: Any = None, wires: int | list[int] | None = None, minmax: list[int] | None = None, controls: int | list[int] | None = None, encode: bool = False, name: str = 'hamiltonian') → None

Add a Hamiltonian gate.

hlayer(wires: int | list[int] | None = None) → None

Add a layer of Hadamard gates.

init_encoder() → None

Initialize the parameters of the encoders.

init_para() → None

Initialize the parameters of the operators.

inverse(encode: bool = False) → QubitCircuit

Get the inversed circuit.

Note

The inversed circuit shares the parameters with the original circuit. You should ONLY encode data onto the original circuit. If you want to encode data onto the inversed circuit, set encode to be True.

iswap(wires: list[int], controls: int | list[int] | None = None, condition: bool = False) → None

Add an imaginary SWAP gate.

j(wires: int, inputs: Any = None, plane: str = 'xy', controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add a projection matrix J.

latent(wires: int | list[int] | None = None, minmax: list[int] | None = None, inputs: Any = None, controls: int | list[int] | None = None, encode: bool = False, name: str = 'latent') → None

Add a latent gate.

property max_depth: int

Get the max number of gates on the wires.

measure(shots: int | None = None, with_prob: bool = False, wires: int | list[int] | None = None, block_size: int = 16777216) → dict | list[dict] | None

Measure the final state.

Parameters:

• shots (int | None) – The number of shots for the measurement. Default: None (which means self.shots)

• with_prob (bool) – Whether to show the true probability of the measurement. Default: False

• wires (int | list[int] | None) – The wires to measure. Default: None (which means all wires)

• block_size (int) – The block size for sampling. Default: 2**24

move(wire1: int, wire2: int, postselect: int | None = 0) → None

Add a move operation.

observable(wires: int | list[int] | None = None, basis: str = 'z') → None

Add an Observable.

Parameters:

• wires (int | list[int] | None) – The wires to measure. Default: None (which means all wires are measured)

• basis (str) – The measurement basis for each wire. It can be 'x', 'y', or 'z'. If only one character is given, it is repeated for all wires. Default: 'z'

p(wires: int, inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add a phase shift gate.

pattern() → Pattern

Get the MBQC pattern.

pauli(wires: int, inputs: Any = None, encode: bool = False) → None

Add a Pauli channel.

phase_damp(wires: int, inputs: Any = None, encode: bool = False) → None

Add a phase-damping channel.

phase_flip(wires: int, inputs: Any = None, encode: bool = False) → None

Add a phase-flip channel.

post_select(bits: str) → Tensor

Get the state vectors after post selection.

qasm() → str

Get QASM of the quantum circuit.

rbs(wires: list[int], inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add a Reconfigurable Beam Splitter gate.

reset(wires: int | list[int] | None = None, postselect: int | None = 0) → None

Add a reset operation.

reset_circuit(init_state: Any = 'zeros') → None

Reset the QubitCircuit according to init_state.

reset_observable() → None

Reset the observables.

rx(wires: int, inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Rx gate.

rxlayer(wires: int | list[int] | None = None, inputs: Any = None, encode: bool = False) → None

Add a layer of Rx gates.

rxx(wires: list[int], inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Rxx gate.

rxy(wires: list[int], inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Rxy gate.

ry(wires: int, inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Ry gate.

rylayer(wires: int | list[int] | None = None, inputs: Any = None, encode: bool = False) → None

Add a layer of Ry gates.

ryy(wires: list[int], inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Ryy gate.

rz(wires: int, inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Rz gate.

rzlayer(wires: int | list[int] | None = None, inputs: Any = None, encode: bool = False) → None

Add a layer of Rz gates.

rzz(wires: list[int], inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add an Rzz gate.

s(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add an S gate.

sdg(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add an S dagger gate.

set_init_state(init_state: Any) → None

Set the initial state of the circuit.

swap(wires: list[int], controls: int | list[int] | None = None, condition: bool = False) → None

Add a SWAP gate.

t(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add a T gate.

tdg(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add a T dagger gate.

toffoli(control1: int, control2: int, target: int) → None

Add a Toffoli gate.

transform_cut2move() → QubitCircuit

Transform WireCut to Move and expand the observables accordingly.

u3(wires: int, inputs: Any = None, controls: int | list[int] | None = None, condition: bool = False, encode: bool = False) → None

Add a U3 gate.

u3layer(wires: int | list[int] | None = None, inputs: Any = None, encode: bool = False) → None

Add a layer of U3 gates.

x(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add a Pauli-X gate.

xlayer(wires: int | list[int] | None = None) → None

Add a layer of Pauli-X gates.

y(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add a Pauli-Y gate.

ylayer(wires: int | list[int] | None = None) → None

Add a layer of Pauli-Y gates.

z(wires: int, controls: int | list[int] | None = None, condition: bool = False) → None

Add a Pauli-Z gate.

zlayer(wires: int | list[int] | None = None) → None

Add a layer of Pauli-Z gates.