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[, U_list, mode, ...])	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, U_list=None, mode='state_vector_simulator', precompute_unitary=False, state=None, cbits=None, measure_results=None)[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: 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.
indexlist, optional: 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 the gate.
control_valueint, optional: 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).

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.
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.