qrunch.quantum.circuits

Module implementing quantum circuits.

Classes

Circuit

CircuitBase class for representing quantum circuits.

class Circuit

Bases: HasCustomEncoding

CircuitBase class for representing quantum circuits.

Quantum circuit consisting of a number of gates acting on a number of qubits.

print can be used to print a diagram of the circuit which preserves the appending order and indices of the gates.

__init__(num_qubits: int, /) → None

__init__(gates: Iterable[Gate], /) → None

__init__(num_qubits: int | None = None, gates: Iterable[Gate] | None = None) → None

Initialize a Circuit object with the given number of qubits.

Parameters:

num_qubits (int | Iterable[Gate] | None) – Number of qubits for the circuit to operate on. If not provided, gates must be
gates. (provided and the number of qubits is obtained from the)
gates (Iterable[Gate] | None) – Initial gates to be added to the circuit. If not provided, the circuit is initialized empty.

Raises:

ValueError – If num_qubits is negative or zero.

Return type:

None

append(gate: Gate, *, skip_validation: bool = False) → None

Append gate to the end of the circuit.

Parameters:

gate (Gate) – The gate to be appended to the end of the circuit.
skip_validation (bool) – Skip checking that the gate fits into the circuit. Validation costs a noticeable fraction of the time it takes to build a circuit with a very large number of gates, such as a Trotterized time evolution, and it is redundant when the caller constructs the gates itself and already knows which qubits they act on. Only pass True in that situation: an invalid gate that is not rejected here surfaces much later as a far more confusing failure.

Raises:

IndexError – When the gate acts on qubits which are not included in the circuit.
ValueError – When the name of a gate parameter is already taken by a different parameter in the circuit.

Return type:

None

as_gate(name: str) → GateFactory

Return the circuit as a single gate.

Creates a gate function that will apply the circuit as a single gate. The function takes qubit indices as arguments, maps this circuit’s qubits to the new indices, and creates a gate with the new indices.

Parameters:: name (str) – Name of the gate.
Return type:: GateFactory

copy() → Self

Create a shallow copy of the circuit.

This is faster than using copy.deepcopy() as it directly copies the internal state without the overhead of Python’s generic deep copy mechanism.

Note: Gates are not deep copied as they are immutable.

Returns:: A new Circuit instance with the same gates.
Return type:: Self

count_gates() → dict[str, int]

Count the number of all gate types in circuit.

Returns:: Dictionary between string representing gate, e.g., X or CX and the gate count.
Return type:: dict[str, int]

classmethod decode(data: dict[str, Any]) → Self

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: Self

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

extend(other: Self | Iterable[Gate], *, skip_validation: bool = False) → None

Extend self with other by concatenating other to the right of self.

other can be either a circuit or list containing the gates to be appended on self.

Parameters:

other (Self | Iterable[Gate]) – CircuitBase or list of gates to extend with.
skip_validation (bool) – Skip checking that each gate fits into the circuit, see append(). Beyond saving the checks themselves this appends the gates in one go instead of one at a time, which matters when the same block of gates is concatenated many times.

Raises:

ValueError – If other is a circuit, and the two circuits do not have the same number of qubits.

Return type:

None

get_parameters() → list[Parameter]

Return all unspecified gate parameters present in the circuit.

Returns:: List of unspecified parameters.
Return type:: list[Parameter]

inactive_qubits() → set[int]

Return a set of inactive qubits, that is qubits without any gates.

Return type:: set[int]

is_fully_specified() → bool

Check if the circuit is fully specified, i.e., whether all parameters have been set.

Returns:: True if circuit is fully specified.
Return type:: bool

property num_gates: int: Number of gates in the circuit.

property num_parameters: int: Number of unspecified gate parameters.

property num_qubits: int: Number of qubits for the circuit to operate on.

to_string(*, compact: bool = False, max_character_width: int = 120, max_number_of_decimals: int | None = None, qubit_label_prefix: str = 'q') → str

Convert the circuit to a nicely formatted string representation which can be printed.

Parameters:

compact (bool) – If True, gates are allowed change order compared to the original order. Defaults to False.
max_character_width (int) – Maximum number of characters for each line in the circuit print. Must be at least 50.
max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the circuit. Defaults to None.
qubit_label_prefix (str) – Prefix for the qubit labels. Defaults to “q”.

Return type:

str

with_specified_parameters(parameter_value_pairs: dict[Parameter, float] | dict[str, float]) → Self

Update the given parameters with the given values in the dictionary.

The parameters can be parsed through the parameter object or the name.

Parameters:: parameter_value_pairs (dict[Parameter, float] | dict[str, float]) – Dictionary containing the parameters or name of parameters and values to be set.
Returns:: New circuit equivalent to the original circuit but with the parameters specified.
Raises:: ValueError – If a parameter or parameter name is not present in the circuit.
Return type:: Self

Modules

`circuit`	Module implementing the abstract base class of the circuit class.
`compilers`	Module containing compilers that can convert a circuit to a universal gate circuit.
`hamiltonian_time_evolution`	Module providing randomized compilers for Hamiltonian time evolution, such as qDRIFT.
`synthesis`	Module containing all circuit synthesis algorithms such as layout synthesis.
`translators`	Contains translators that can translate Kvantify Qrunch circuits to third party circuit formats.
`transpilation`	Module containing transpilation tools that convert circuits into a form suitable for specific quantum hardware.
`trotter`	Module providing Trotterization of standard Hermitian Pauli Hamiltonians.
`universal_gate_circuits`	Module implementing a circuit that only accepts universal gates.