LogicalQ.Logical

Classes

LogicalCircuit	Core LogicalQ representation of a logical quantum circuit.
LogicalQubit	A single LogicalQubit.
LogicalRegister	A register containing LogicalQubits.
LogicalStatevector	A LogicalStatevector is an object representing a Logical state.
LogicalDensityMatrix	A LogicalDensityMatrix

Functions

logical_state_fidelity(state1, state2)

Calculate the logical fidelity between two logical states.

Module Contents

class LogicalQ.Logical.LogicalCircuit(n_logical_qubits, label, stabilizer_tableau, name=None)

Bases: qiskit.QuantumCircuit

Core LogicalQ representation of a logical quantum circuit.

Parameters:

• n_logical_qubits (int)

• label (Iterable[int])

• stabilizer_tableau (Iterable[str])

• name (str)

n_logical_qubits

stabilizer_tableau

n_stabilizers

label

n_physical_qubits

n_ancilla_qubits

n_measure_qubits

flagged_stabilizers_1 = []

flagged_stabilizers_2 = []

x_stabilizers = []

z_stabilizers = []

qec_cycle_indices_initial

qec_cycle_indices_final

logical_qregs = []

ancilla_qregs = []

logical_op_qregs = []

enc_verif_cregs = []

curr_syndrome_cregs = []

prev_syndrome_cregs = []

flagged_syndrome_diff_cregs = []

unflagged_syndrome_diff_cregs = []

pauli_frame_cregs = []

logical_op_meas_cregs = []

final_measurement_cregs = []

qreg_lists

creg_lists

output_creg

cbit_setter_qreg

data_without_qec

classmethod from_physical_circuit(physical_circuit, label, stabilizer_tableau, name=None, max_iterations=1)

Construct a LogicalCircuit from a physical qiskit circuit.

Parameters:

• physical_circuit (qiskit.QuantumCircuit) – The QuantumCircuit to construct from.

• label (Iterable[int]) – The QECC label.

• stabilizer_tableau (Iterable[str]) – The set of stabilizers for the QECC.

• name (str) – An optional name for the circuit.

• max_iterations (int) – Number of times, to attempt to encod qubits.

Returns:

The LogicalCircuit constructed from the physical.

Return type:

LogicalCircuit

add_logical_qubits(logical_qubit_count)

Add logical qubit(s) to the LogicalCircuit.

Parameters:

logical_qubit_count (int) – The number of logical qubits to add.

group_stabilizers()

Generate the stabilizers for the code.

generate_code()

Generate the encoding circuit and logical operators for the selected tableau.

encode(*qubits, max_iterations=1, initial_states=None)

Prepare logical qubit(s) in the specified initial state.

Parameters:

• qubits (Iterable[int]) – Qubits to encode.

• max_iterations (int) – Maximum number of times, to try to encode data.

• initial_states (Iterable[list[int]]) – Initial states to encode in each qubit.

Returns:

True, always

Return type:

bool

reset_ancillas(logical_qubit_indices=None)

Reset all ancillas associated with specified logical qubits.

Parameters:

logical_qubit_indices (Iterable[int]) – Indices of logical qubits to reset. If None, then reset all.

steane_flagged_circuit1(logical_qubit_indices)

Measure first set of flagged syndromes for the Steane code.

Parameters:

logical_qubit_indices (Iterable[int])

steane_flagged_circuit2(logical_qubit_indices)

Measure second set of flagged syndromes for the Steane code.

Parameters:

logical_qubit_indices (Iterable[int])

measure_stabilizers(logical_qubit_indices=None, stabilizer_indices=None)

Measure specified stabilizers to the circuit as controlled Pauli operators.

Parameters:

• logical_qubit_indices (Iterable[int]) – Indices of logical qubits for which to measure stabilizers.

• stabilizer_indices (Iterable[int]) – Indices of stabilizers to measure.

measure_syndrome_diff(logical_qubit_indices=None, stabilizer_indices=None, flagged=False, steane_flag_1=False, steane_flag_2=False)

Measure flagged or unflagged syndrome differences for specified logical qubits and stabilizers.

Parameters:

• logical_qubit_indices (Iterable[int]) – Logical qubits for which to measure indices.

• stabilizer_indices (Iterable[int]) – Stabilizers for which to measure indices.

• flagged (bool) – Whether to measure flagged or unflagged differences.

• steane_flag_1 (bool) – Whether to measure the first Steane code syndrome. Takes priority over steane_flag_2.

• steane_flag_2 (bool) – Whether to measure the second Steane code syndrome. Ignored if steane_flag_1 is True.

optimize_qec_cycle_indices(logical_qubit_indices=None, constraint_model=None, ignore_existing_qec=False, clear_existing_qec=False)

Compute optimal QEC cycle indices.

Parameters:

• logical_qubit_indices (Iterable[int]) – Logical qubits for which to compute optimal QEC cycle indices.

• constraint_model (dict[str, float]) – Constraint model, i.e., dictionary of gadget costs for the circuit.

• ignore_existing_qec (bool) – Whether to ignore QEC-related parameters in the constraint model.

• clear_existing_qec (bool) – Whether to remove existing QEC cycles.

Returns:

Dictionary with optimal QEC cycle indices for each requested qubit.

Return type:

dict[int, int]

insert_qec_cycles(logical_qubit_indices=None, qec_cycle_indices=None, clear_existing_qec=False)

Insert QEC cycles at specified indices in the circuit data.

Parameters:

• logical_qubit_indices (Iterable[int]) – Logical qubits for which to insert QEC cycles.

• qec_cycle_indices (dict[int, list] | list[list]) – Indices at which to insert QEC cycles for each logical qubit.

• clear_existing_qec (bool) – Whether to clear the existing QEC cycles.

Returns:

Original circuit data and data after appending QEC cycles.

Return type:

tuple[qiskit.circuit.quantumcircuitdata.QuantumCircuitData, qiskit.circuit.quantumcircuitdata.QuantumCircuitData]

append_qec_cycle(logical_qubit_indices=None, perform_flagged_syndrome_measurements=True)

Append a QEC cycle to the end of the circuit.

Parameters:

• logical_qubit_indices (Iterable[int] | None) – Logical qubits for which to add QEC cycles.

• perform_flagged_syndrome_measurements (bool)

Returns:

Qubits and indices with QEC cycles, before and after appending.

Return type:

tuple[dict[int, int], dict[int, int]]

clear_qec_cycles(logical_qubit_indices=None, qec_cycle_indices=None)

Clear QEC cycles (either specified or all) on specified logical qubits. Not yet implemented.

Parameters:

• logical_qubit_indices (Iterable[int]) – Logical qubits from which to clear QEC cycles. Clears all if None.

• qec_cycle_indices (Iterable[int]) – QEC cycles to clear. Clears all if None

Returns:

This method is not yet implemented.

Return type:

NotImplementedError

apply_decoding(logical_qubit_indices, stabilizer_indices, with_flagged)

Decode the syndrome measurements to determine the correction to apply.

Parameters:

• logical_qubit_indices (Iterable[int]) – Logical qubits to apply decoding to.

• stabilizer_indices (Iterable[int]) – Stabilizers for which to decode syndromes.

• with_flagged (bool) – Whether to decode with flagged or unflagged syndrome differences.

measure(logical_qubit_indices, cbit_indices, with_error_correction=True)

Measure specified qubits (in the Z basis) into classical bits.

Parameters:

• logical_qubit_indices (Iterable[int]) – Logical qubits to measure.

• cbit_indices (Iterable[int]) – Classical bits in which to record measurements.

• with_error_correction (bool) – Whether to apply QEC.

Raises:

ValueError – if logical_qubit_indices or cbit_indices is not an iterable or if number of qubits and cbits does not match.

measure_all(inplace=True, with_error_correction=True)

Add measurements to all qubits.

Parameters:

• inplace (bool) – Whether to perform measurements on this circuit or a copy. If False, a new circuit is returned.

• with_error_correction (bool) – Whether to perform measurements with QEC.

Returns:

Circuit with measurements, if inplace = False.

Return type:

LogicalCircuit

remove_final_measurements(inplace=False)

Remove final measurements from circuit.

Parameters:

inplace (bool) – Whether to remove measurements in place, i.e., for this circuit (not supported).

Raises:

NotImplementedError – if in-place measurement is attempted.

Returns:

The circuit without measurements.

Return type:

LogicalCircuit

get_logical_counts(physical_counts, logical_qubit_indices=None)

Get logical counts from physical counts.

Parameters:

• physical_counts (Iterable[int]) – Physical counts to convert to logical counts.

• logical_qubit_indices (Iterable[int]) – Logical qubits to get counts for. If None, then get counts for all.

Returns:

Logical qubit counts.

Return type:

dict[str, int]

h(*targets, method='Coherent_Feedback')

Logical Hadamard gate.

Parameters:

• targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “LCU”, “LCU_Corrected”, “Coherent_Feedback”, or “Transversal_Uniform”.

x(*targets)

Logical PauliX gate.

Parameters:

targets (Iterable[Int]) – Logical qubits to apply gate to.

y(*targets)

Logical PauliY gate.

Parameters:

targets (Iterable[int]) – Logical qubits to apply gate to.

z(*targets)

Logical PauliZ gate.

Parameters:

• targest – Logical qubits to apply gate to.

• targets (Iterable[int])

s(*targets, method='Coherent_Feedback')

Logical S gate

Definition: .. math:

\begin{pmatrix}
1 & 0 \\
0 & i
\end{pmatrix}

Parameters:

• targest – Logical qubits to apply gate to.

• method (str) – Method, which can be “LCU_Corrected”, “Coherent_Feedback”, or “Transversal_Uniform”.

• targets (Iterable[int])

sdg(*targets, method='Coherent_Feedback')

Logical S^dagger gate, adjoint of the logical S gate.

Definition: .. math:

\begin{pmatrix}
1 & 0 \\
0 & -i
\end{pmatrix}

Parameters:

• targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “LCU_Corrected”, “Coherent_Feedback”, or “Transversal_Uniform”.

t(*targets, method='Coherent_Feedback')

Logical T gate

Definition: .. math:

begin{pmatrix} 1 & 0 \ 0 & e^{ipi/4} end{pmatrix}

Parameters:

• targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “LCU_Corrected”, or “Coherent_Feedback”.

tdg(*targets, method='Coherent_Feedback')

Logical T^dagger gate

Definition: .. math:

\begin{pmatrix}
1 & 0 \\
0 & e^{-i\pi/4}
\end{pmatrix}

Parameters:

• targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “LCU_Corrected”, or “Coherent_Feedback”.

cx(control, *_targets, method='Ancilla_Assisted')

Logical Controlled-Pauli X gate.

Parameters:

• control (int) – Control qubit.

• _targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “Ancilla_Assisted” or “Transversal_Uniform”.

cz(control, *_targets, method='Ancilla_Assisted')

Logical Controlled-Pauli Z gate.

Parameters:

• control (int) – Control qubit.

• _targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “Ancilla_Assisted” or “Transversal_Uniform”.

cy(control, *_targets, method='Ancilla_Assisted')

Logical Controlled-Pauli Y gate.

Parameters:

• control (int) – Control qubit.

• _targets (Iterable[int]) – Logical qubits to apply gate to.

• method (str) – Method, which can be “Ancilla_Assisted” or “Transversal_Uniform”.

mcmt(gate, controls, targets)

Logical Multi-Control Multi-Target gate

rx(theta, targets, method='S-K', depth=10, recursion_degree=1, box=True)

Logical Single-Target Rotation Gate

method = “LCU” -> linear combination of unitaries or “S-K” -> solovay-kitaev algorithm or “OAA” -> oblivious amplitude amplification

theta in radians

Parameters:

theta (float)

ry(theta, targets, method='S-K', depth=10, recursion_degree=1, box=True)

Logical Single-Target Rotation Gate

method = “LCU” or “S-K”

theta in radians

Parameters:

theta (float)

rz(theta, targets, method='S-K', depth=10, recursion_degree=1, box=True)

Logical Single-Target Rotation Gate

method = “LCU” or “S-K”

theta in radians

Parameters:

theta (float)

rxx(theta, targets, method='S-K', depth=10, recursion_degree=1, box=True)

Apply RXXGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters:

• theta (float) – The angle of the rotation.

• qubit1 – The qubit(s) to apply the gate to.

• qubit2 – The qubit(s) to apply the gate to.

Returns:

A handle to the instructions created.

ryy(theta, targets, method='S-K', depth=10, recursion_degree=1, box=True)

Apply RYYGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters:

• theta (float) – The rotation angle of the gate.

• qubit1 – The qubit(s) to apply the gate to.

• qubit2 – The qubit(s) to apply the gate to.

Returns:

A handle to the instructions created.

rzz(theta, targets, method='S-K', depth=10, recursion_degree=1, box=True)

Apply RZZGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters:

• theta (float) – The rotation angle of the gate.

• qubit1 – The qubit(s) to apply the gate to.

• qubit2 – The qubit(s) to apply the gate to.

Returns:

A handle to the instructions created.

append_sk_decomposition(circuit, targets, label='U', depth=10, recursion_degree=1, box=False, return_subcircuit=False)

r(axis, targets, theta=0, label='R', depth=10, recursion_degree=1, box=True, method='S-K')

Apply RGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters:

• theta – The angle of the rotation.

• phi – The angle of the axis of rotation in the x-y plane.

• qubit – The qubit(s) to apply the gate to.

Returns:

A handle to the instructions created.

append(instruction, qargs=None, cargs=None, copy=True)

Append a Logical gate to the circuit.

Parameters:

• instruction – The instruction to add. Accepts instances of Instruction, CircuitInstruction, or a string containing the gate name.

• qargs – Logical qubits to target.

• cargs – Classical bits to target.

• copy – Whether to copy the instruction before appending, to prevent modification of the argument.

Raises:

• ValueError – If the instruction cannot be parsed.

• ValueError – If an element of the qargs cannot be recognized.

• ValueError – If an element of the cargs cannot be recognized.

• NotImplementedError – Is MCMT is attempted.

add_error(l_ind, p_ind, error_type)

Induces an X or Z error on a physical qubit.

Parameters:

• l_ind (int) – Logical qubit index

• p_ind (int) – Physical qubit index within logical qubit

• error_type – The type of error to add. Accepts ‘X’ or ‘Z’.

set_cbit(cbit, value)

Set the value of a bit in classical register.

Parameters:

• cbit – Classical bit

• value – 0 or 1

cbit_not(cbit)

Control flow method that performs NOT statement on a classical bit.

Parameters:

cbit – Classical bit

cbit_and(cbits, values)

Control flow method used to perform AND statement on multiple classical bits against a set of values.

Parameters:

• cbits – The classical bits to compare

• values – A list of zeros and ones

Returns:

result

cbit_xor(cbits)

Control flow method used to perform XOR statement on multiple classical bits.

Parameters:

cbits – The classical bits to XOR

Returns:

result

draw(output=None, scale=None, filename=None, style=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=None, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30, fold_qec=True, fold_logicalop=True)

LogicalCircuit drawer based on Qiskit circuit drawer

class LogicalQ.Logical.LogicalQubit(regs=None, qregs=None, cregs=None)

Bases: list

A single LogicalQubit.

NOT YET FULLY IMPLEMENTED.

_data = []

qregs = []

cregs = []

class LogicalQ.Logical.LogicalRegister(qregs=None, cregs=None)

Bases: list

A register containing LogicalQubits.

qregs = None

cregs = None

class LogicalQ.Logical.LogicalStatevector(data, logical_circuit=None, n_logical_qubits=None, label=None, stabilizer_tableau=None, dims=None)

Bases: qiskit.quantum_info.Statevector

A LogicalStatevector is an object representing a Logical state.

Parameters:

• data (numpy.ndarray | qiskit.QuantumCircuit | LogicalCircuit | qiskit.quantum_info.Statevector)

• logical_circuit (LogicalCircuit)

• n_logical_qubits (int)

• label (Iterable[int])

• stabilizer_tableau (Iterable[str])

• dims (int)

_logical_decomposition = None

classmethod from_counts(counts, n_logical_qubits, label, stabilizer_tableau, basis='physical')

Construct a LogicalStatevector from measurement counts.

Parameters:

• counts (dict) – The set of counts measured from a circuit execution.

• n_logical_qubits (int) – The number of logical qubits.

• label (tuple) – The quantum error correction code [[n,k,d]] (given as a tuple).

• stabilizer_tableau (Iterable[str]) – The set of stabilizers for the QECC.

• basis (str) – The basis in which each respective count’s vector is given, physical or logical.

Returns:

The normalized LogicalStatevector constructed from the counts.

Raises:

ValueError – if the counts format could not be parsed or if basis is invalid.

Return type:

LogicalStatevector

classmethod from_basis_str(basis_str, n_logical_qubits, label, stabilizer_tableau, basis='physical')

Construct a LogicalStatevector, an element of the logical computational basis, from

a basis string.

Parameters:

• basis_str (str) – Either a binary bitstring or its hex equivalent to identify the basis.

• n_logical_qubits (int) – Number of logical qubits.

• label (tuple) – The label of the quantum error correction code [[n,k,d]] (as a tuple).

• stabilizer_tableau (Iterable[str]) – The set of stabilizers for the QECC.

• basis (str) – The basis in which each respective count’s vector is given, physical or logical.

Returns:

The LogicalStatevector of

the given basis state.

Return type:

LogicalStatevector

Raises:

ValueError – if the basis_str could not be parsed due to improper format.

property logical_decomposition

Give a decomposition of a LogicalStatevector into the logical basis.

Parameters:

atol (float) – Tolerance within which to set probability amplitude to zero.

Returns:

The set of coefficients \(\alpha_i, \delta\), where

\(|\psi\rangle = \sum_{x=0}^{2^n - 1}\alpha_x|x\rangle + \delta|\psi^\perp\rangle\), where \(|\psi^\perp\rangle\) is the component of the state vector not in the codespace. Note that coefficients are returned in ascending order of value, e.g., 000, 001, 010, 011, 100, 101, etc.

Return type:

np.ndarray

__array__(basis='physical', dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED)

Return an array representation of the object.

Parameters:

• basis (str) – The basis, physical or logical, in which to represent the vector.

• dtype (data-type) – The desired data-type for the array.

• copy (bool) – If True, then the array data is copied

Returns:

The logical_decomposition()

if basis is logical and the statevector data otherwise.

Return type:

np.ndarray

Raises:

ValueError – if the basis is invalid.

__repr__(basis='logical')

Return a string representation of the statevector.

Parameters:

basis (str) – The basis, logical or physical, in which to return the array.

Returns:

String representation of the statevector in the requested basis.

Return type:

np.ndarray

Raises:

ValueError – if the basis is invalid.

draw(output=None)

Return a visual representation of the statevector in the logical basis.

Parameters:

output (str) – The method in which to draw. Valid choices are text, latex, and latex_source.

Returns:

String or LaTeX representation of the statevector.

Return type:

str or IPython.display.Latex

Raises:

ValueError – if the draw method is invalid.

class LogicalQ.Logical.LogicalDensityMatrix(data, n_logical_qubits=None, label=None, stabilizer_tableau=None, dims=None)

Bases: qiskit.quantum_info.DensityMatrix

A LogicalDensityMatrix

_logical_decomposition = None

abstract property logical_decomposition

__repr__(basis='logical')

LogicalQ.Logical.logical_state_fidelity(state1, state2)

Calculate the logical fidelity between two logical states.

Parameters:

• state1 – The first state.

• state2 – The second state.

Raises:

• NotImplementedError – If state fidelity computation for LogicalDensityMatrix instances is attempted.

• TypeError – If either state is not a LogicalStatevector, LogicalDensityMatrix, Statevector, or DensityMatrix.

Returns:

fidelity