qutip_qip.circuit

Circuit representation and simulation at the gate level.

Classes

`QubitCircuit`([num_qubits, input_states, ...])	Representation of a quantum program/algorithm, maintaining a sequence of gates.
`CircuitResult`(final_states, probabilities[, ...])	Result of a quantum circuit simulation.
`CircuitSimulator`(qc[, mode])	Operator based circuit simulator.
`CircuitInstruction`(operation, ...)
`GateInstruction`(operation, ...)
`MeasurementInstruction`(operation, qubits, ...)

class qutip_qip.circuit.CircuitInstruction(operation: Union[qutip_qip.operations.gateclass.Gate, Type[qutip_qip.operations.gateclass.Gate], qutip_qip.operations.measurement.Measurement], qubits: tuple[int, ...] = (), cbits: tuple[int, ...] = (), style: dict = <factory>)[source]: Bases: ABC

class qutip_qip.circuit.CircuitResult(final_states, probabilities, cbits=None)[source]

Bases: object

Result of a quantum circuit simulation.

get_cbits(index=None)[source]

Return list of classical bit outputs corresponding to the results.

Parameters:

index: int: Indicates i-th output, probability pair to be returned.

Returns:

cbits: list of int or list of list of int: list of classical bit outputs

get_final_states(index=None)[source]

Return list of output states.

Parameters:

index: int: Indicates i-th state to be returned.

Returns:

final_states: Qobj or list of Qobj.: List of output kets or density matrices.

get_probabilities(index=None)[source]

Return list of probabilities corresponding to the output states.

Parameters:

index: int: Indicates i-th probability to be returned.

Returns:

probabilities: float or list of float: Probabilities associated with each output state.

plot_histogram(fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, color: str = '#1f77b4', top_m: int | None = None, threshold: float = 1e-10) → tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]

Plot a histogram of the measurement outcomes and their probabilities.

Parameters:

figmatplotlib.figure.Figure, optional: The figure object for the histogram plot. If not provided, a new figure will be created.
axmatplotlib.axes.Axes, optional: The axes object for the histogram plot. If not provided, a new axes will be created.
colorstr, optional: Bar color for the histogram. Default is ‘#1f77b4’.
top_mint, optional: The number of top m highest probability measurements to be plotted in the histogram. If not specified, defaults to all the measurements above the mentioned tolerance.
thresholdfloat, optional: The probability e.g. 1e-7 above which the measurements are plotted in the histogram. If not specified, defaults to 1e-10.

Returns:

figmatplotlib.figure.Figure: The figure object for the histogram plot.
axmatplotlib.axes.Axes: The axes object for the histogram plot.

class qutip_qip.circuit.CircuitSimulator(qc, mode: str = 'state_vector_simulator')[source]

Bases: object

Operator based circuit simulator.

initialize(state=None, cbits=None, measure_results=None)[source]

Reset Simulator state variables to start a new run.

Parameters:

state: ket or oper: ket or density matrix
cbits: list of int, optional: initial value of classical bits
measure_resultstuple of ints, optional: optional specification of each measurement result to enable post-selection. If specified, the measurement results are set to the tuple of bits (sequentially) instead of being chosen at random.

run(state, cbits=None, measure_results=None)[source]

Calculate the result of one instance of circuit run.

Parameters:

stateket or oper: state vector or density matrix input.
cbitsList of ints, optional: initialization of the classical bits.
measure_resultstuple of ints, optional: optional specification of each measurement result to enable post-selection. If specified, the measurement results are set to the tuple of bits (sequentially) instead of being chosen at random.

Returns:

result: CircuitResult: Return a CircuitResult object containing output state and probability.

run_statistics(state, cbits=None)[source]

Calculate all the possible outputs of a circuit (varied by measurement gates).

Parameters:

stateket: state to be observed on specified by density matrix.
cbitsList of ints, optional: initialization of the classical bits.

Returns:

result: CircuitResult: Return a CircuitResult object containing output states and and their probabilities.

property state

The current state of the simulator as a qutip.Qobj

Returns:: The current state of the simulator.
Return type:: qutip.Qobj

step()[source]

Return state after one step of circuit evolution (gate or measurement).

Returns:

stateket or oper: state after one evolution step.

class qutip_qip.circuit.GateInstruction(operation: Union[qutip_qip.operations.gateclass.Gate, Type[qutip_qip.operations.gateclass.Gate]], qubits: tuple[int, ...] = (), cbits: tuple[int, ...] = (), style: dict = <factory>, cbits_ctrl_value: int | None = None)[source]: Bases: CircuitInstruction

class qutip_qip.circuit.MeasurementInstruction(operation: qutip_qip.operations.measurement.Measurement, qubits: tuple[int, ...]=(), cbits: tuple[int, ...]=(), style: dict = <factory>)[source]: Bases: CircuitInstruction

class qutip_qip.circuit.QubitCircuit(num_qubits=None, input_states=None, output_states=None, reverse_states=True, dims=None, num_cbits=0, user_gates=None, N=None)[source]

Bases: object

Representation of a quantum program/algorithm, maintaining a sequence of gates.

Parameters:

num_qubitsint: Number of qubits in the system.
input_stateslist: A list of string such as 0,’+’, “A”, “Y”. Only used for latex.
dimslist: A list of integer for the dimension of each composite system. e.g [2,2,2,2,2] for 5 qubits system. If None, qubits system will be the default option.
num_cbitsint: Number of classical bits in the system.

property N: int: Number of qubits in the circuit.

add_circuit(qc, start=0)[source]

Adds a block of a qubit circuit to the main circuit.

Parameters:

qcQubitCircuit: The circuit block to be added to the main circuit.
startint: The qubit on which the first gate is applied.

Adds a gate with specified parameters to the circuit.

Parameters:

gate: :class:`~.operations.Gate` or :obj:`~.operations.Gate` or str: Gate name. If gate is an instance of Gate, parameters are unpacked and added.
targets: int or list, optional: Index for the target qubits.
controls: int or list, optional: Indices for the (quantum) control qubits.
arg_value: Any, optional: Arguments for the gate. It will be used when generating the unitary matrix. For predefined gates, they are used when calling the get_compact_qobj methods of a gate.
arg_label: string, optional: Label for gate representation.
classical_controlsint or list of int, optional: Indices of classical bits to control the gate.
control_valueoptional: Value of classical bits to control on, the classical controls are interpreted as an integer with the lowest bit being the first one. If not specified, then the value is interpreted to be 2 ** len(classical_controls) - 1 (i.e. all classical controls are 1).
style:: For circuit draw

Adds a measurement with specified parameters to the circuit.

Parameters:

measurementMeasurement: Measurement subclasses
targetsint or Sequence of int: Gate targets
classical_storeint or Sequence of int: Classical register where result of measurement is stored.
indexlist: Positions to add the gate.

add_state(state: str, targets: list[int | integer] | tuple[int | integer, ...] | ndarray[tuple[Any, ...], dtype[integer]], state_type: str = 'input')[source]

Add an input or output state to the circuit. By default all the input and output states will be initialized to None. A particular state can be added by specifying the state and the qubit where it has to be added along with the type as input or output.

Parameters:

state: str: The state that has to be added. It can be any string such as 0, ‘+’, “A”, “Y”
targets: list: A list of qubit positions where the given state has to be added.
state_type: str: One of either “input” or “output”. This specifies whether the state to be added is an input or output. default: “input”

compute_unitary()[source]

Evaluates the matrix of all the gates in a quantum circuit.

Returns:

circuit_unitaryqutip.Qobj: Product of all gate arrays in the quantum circuit.

draw(renderer='matplotlib', file_type='png', dpi=None, file_path='circuit', save=False, **kwargs)[source]

Export circuit object as an image file in a supported format.

Parameters:

rendererstr, optional: The renderer to use for the circuit. Options are ‘latex’, ‘matplotlib’, or ‘text’. Default is ‘matplotlib’.
file_typestr, optional: The type of the image file to export. Supported types are ‘svg’ and ‘png’. Default is ‘png’.
dpiint, optional: The image density in dots per inch (dpi). Applicable for PNG, not for SVG. Default is None (set to 100 internally for PNG).
file_pathstr, optional: The path to save the image file. Default is the current working directory.
savebool, optional: If True, the image will be saved to the specified path. Default is False.
kwargsdict: Additional keyword arguments passed to the renderer. Passed to StyleConfig Dataclass under base_renderer.py, pls refer to the file for more details.