qutip_qip.circuit

Circuit representation and simulation at the gate level.

Classes

QubitCircuit(N[, 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[, state, cbits, U_list, ...])

Operator based circuit simulator.

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.

class qutip_qip.circuit.CircuitSimulator(qc, state=None, cbits=None, U_list=None, measure_results=None, mode='state_vector_simulator', precompute_unitary=False)[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

U_list: list of Qobj, optional

list of predefined unitaries corresponding to circuit.

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.

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.QubitCircuit(N, input_states=None, output_states=None, reverse_states=True, user_gates=None, dims=None, num_cbits=0)[source]

Bases: object

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

Parameters
Nint

Number of qubits in the system.

user_gatesdict

Define a dictionary of the custom gates. See examples for detail.

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.

Examples

>>> def user_gate():
...     mat = np.array([[1.,   0],
...                     [0., 1.j]])
...     return Qobj(mat, dims=[[2], [2]])
>>> qubit_circuit = QubitCircuit(2, user_gates={"T":user_gate})
>>> qubit_circuit.add_gate("T", targets=[0])
add_1q_gate(name, start=0, end=None, qubits=None, arg_value=None, arg_label=None, classical_controls=None, control_value=None, classical_control_value=None)[source]

Adds a single qubit gate with specified parameters on a variable number of qubits in the circuit. By default, it applies the given gate to all the qubits in the register.

Parameters
namestring

Gate name.

startint

Starting location of qubits.

endint

Last qubit for the gate.

qubitslist

Specific qubits for applying gates.

arg_valuefloat

Argument value(phi).

arg_labelstring

Label for gate representation.

add_circuit(qc, start=0, overwrite_user_gates=False)[source]

Adds a block of a qubit circuit to the main circuit. Globalphase gates are not added.

Parameters
qcQubitCircuit

The circuit block to be added to the main circuit.

startint

The qubit on which the first gate is applied.

add_gate(gate, targets=None, controls=None, arg_value=None, arg_label=None, index=None, classical_controls=None, control_value=None, classical_control_value=None)[source]

Adds a gate with specified parameters to the circuit.

Parameters
gate: string orclass:~.operations.Gate

Gate name. If gate is an instance of Gate, parameters are unpacked and added.

targets: list

Gate targets.

controls: list

Gate controls.

arg_value: float

Argument value(phi).

arg_label: string

Label for gate representation.

indexlist

Positions to add the gate. Each index in the supplied list refers to a position in the original list of gates.

classical_controlsint or list of int, optional

indices of classical bits to control gate on.

control_valueint, optional

value of classical bits to control on, the classical controls are interpreted as an integer with 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).

add_gates(gates)[source]

Adds a sequence of gates to the circuit in a positive order, i.e. the first gate in the sequence will be applied first to the state.

Parameters
gates: Iterable (e.g., list)

The sequence of gates to be added.

add_measurement(measurement, targets=None, index=None, classical_store=None)[source]

Adds a measurement with specified parameters to the circuit.

Parameters
measurement: string

Measurement name. If name is an instance of Measuremnent, parameters are unpacked and added.

targets: list

Gate targets

indexlist

Positions to add the gate.

classical_storeint

Classical register where result of measurement is stored.

add_state(state, targets=None, state_type='input')[source]

Add an input or ouput 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”

adjacent_gates()[source]

Method to resolve two qubit gates with non-adjacent control/s or target/s in terms of gates with adjacent interactions.

Returns
qubit_circuit:class:.QubitCircuit

Return QubitCircuit of the gates for the qubit circuit with the resolved non-adjacent gates.

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(file_type='png', dpi=None, file_name='exported_pic', file_path='')[source]

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

Parameters
file_typeProvide a supported image file_type eg: “svg”/”png”.

Default : “png”.

dpiImage density in Dots per inch(dpi)

Applicable for PNG, NA for SVG. Default : None, though it’s set to 100 internally for PNG

file_nameFilename of the exported image.

Default : “exported_pic”

file_pathPath to which the file has to be exported.

Default : “” Note : User should have write access to the location.

property png

Return the png file

propagators(expand=True, ignore_measurement=False)[source]

Propagator matrix calculator returning the individual steps as unitary matrices operating from left to right.

Parameters
expandbool, optional

Whether to expand the unitary matrices for the individual steps to the full Hilbert space for N qubits. Defaults to True. If False, the unitary matrices will not be expanded and the list of unitaries will need to be combined with the list of gates in order to determine which qubits the unitaries should act on.

ignore_measurement: bool, optional

Whether Measurement operators should be ignored. If set False, it will raise an error when the circuit has measurement.

Returns
U_listlist

Return list of unitary matrices for the qubit circuit.

Notes

If expand=False, the global phase gate only returns a number. Also, classical controls are be ignored.

remove_gate_or_measurement(index=None, end=None, name=None, remove='first')[source]

Remove a gate from a specific index or between two indexes or the first, last or all instances of a particular gate.

Parameters
indexint

Location of gate or measurement to be removed.

namestring

Gate or Measurement name to be removed.

removestring

If first or all gates/measurements are to be removed.

resolve_gates(basis=['CNOT', 'RX', 'RY', 'RZ'])[source]

Unitary matrix calculator for N qubits returning the individual steps as unitary matrices operating from left to right in the specified basis. Calls ‘_resolve_to_universal’ for each gate, this function maps each ‘GATENAME’ with its corresponding ‘_gate_basis_2q’ Subsequently calls _resolve_2q_basis for each basis, this function maps each ‘2QGATENAME’ with its corresponding ‘_basis_’

Parameters
basislist.

Basis of the resolved circuit.

Returns
qcQubitCircuit

Return QubitCircuit of resolved gates for the qubit circuit in the desired basis.

reverse_circuit()[source]

Reverse an entire circuit of unitary gates.

Returns
qubit_circuitQubitCircuit

Return QubitCircuit of resolved gates for the qubit circuit in the reverse order.

run(state, cbits=None, U_list=None, measure_results=None, precompute_unitary=False)[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.

U_list: list of Qobj, optional

list of predefined unitaries corresponding to circuit.

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.

precompute_unitary: Boolean, optional

Specify if computation is done by pre-computing and aggregating gate unitaries. Possibly a faster method in the case of large number of repeat runs with different state inputs.

Returns
final_stateQobj

output state of the circuit run.

run_statistics(state, U_list=None, cbits=None, precompute_unitary=False)[source]

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

Parameters
stateket or oper

state vector or density matrix input.

cbitsList of ints, optional

initialization of the classical bits.

U_list: list of Qobj, optional

list of predefined unitaries corresponding to circuit.

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.

precompute_unitary: Boolean, optional

Specify if computation is done by pre-computing and aggregating gate unitaries. Possibly a faster method in the case of large number of repeat runs with different state inputs.

Returns
result: CircuitResult

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

property svg

Return the svg file

qutip_qip.circuit.image_from_latex(code, file_type='png', dpi=100)[source]

Convert the LaTeX code into an image format, defined by the file_type. Returns a string or bytes object, depending on whether the requested type is textual (e.g. svg) or binary (e.g. png). The known file types are in keys in this module’s CONVERTERS dictionary.

Parameters
code: str

LaTeX code representing the circuit to be converted.

file_type: str (“png”)

The file type that the image should be returned in.

Returns
image: str or bytes

An encoded version of the image. Whether the output type is str or bytes depends on whether the requested image format is textual or binary.