Merge f52457b into a8d3c45

doc/source/index.rst

@@ -23,6 +23,7 @@ qutip-qip |version|: QuTiP quantum information processing
     qip-simulator.rst
     qip-processor.rst
     qip-vqa.rst
+    qip-qiskit.rst
 
 .. toctree::
     :maxdepth: 2

doc/source/qip-qiskit.rst

@@ -0,0 +1,116 @@
+******************************
+Qiskit
+******************************
+
+Overview
+===============
+
+This submodule provides an interface to simulate circuits made in qiskit.
+
+Gate-level simulation on qiskit circuits is possible with :class:`.QiskitCircuitSimulator`. Pulse-level simulation is possible with :class:`.QiskitPulseSimulator` which supports simulation using the :class:`.LinearSpinChain`, :class:`.CircularSpinChain` and :class:`.DispersiveCavityQED` pulse processors.
+
+Running a qiskit circuit with qutip_qip
+==========================================
+
+After constructing a circuit in qiskit, either of the qutip_qip based backends (:class:`.QiskitCircuitSimulator` and :class:`.QiskitPulseSimulator`) can be used to run that circuit.
+
+Example
+--------
+
+Let's try constructing and simulating a qiskit circuit.
+
+We define a simple circuit as follows:
+
+.. code-block::
+
+    from qiskit import QuantumCircuit
+    
+    circ = QuantumCircuit(2,2)
+    circ.h(0)
+    circ.h(1)
+    
+    circ.measure(0,0)
+    circ.measure(1,1)
+
+Let's run this on the :class:`.QiskitCircuitSimulator` backend:
+
+.. code-block::
+
+    from qutip_qip.qiskit.provider import QiskitCircuitSimulator
+
+    backend = QiskitCircuitSimulator()
+    job = backend.run(circ)
+    result = job.result()
+    
+>>> from qiskit.visualization import plot_histogram
+>>> plot_histogram(result.get_counts())
+
+.. image:: /figures/qiskit-gate-level-plot.png
+    :alt: probabilities plot 
+
+Now, let's run the same circuit on :class:`.QiskitPulseSimulator`.
+
+While using a pulse processor, we define the circuit without measurements:
+
+.. code-block:: 
+
+    pulse_circ = QuantumCircuit(2,2)
+    pulse_circ.h(0)
+    pulse_circ.h(1)
+
+To use the :class:`.QiskitPulseSimulator` backend, we need to define the processor on which we want to run the circuit:
+
+.. code-block::
+
+    from qutip_qip.device import LinearSpinChain
+    processor = LinearSpinChain(num_qubits=2)
+
+Now that we defined our processor (:class:`.LinearSpinChain` in this case), we can use it to perform the simulation: 
+
+.. code-block::
+
+    from qutip_qip.qiskit.provider import QiskitPulseSimulator
+
+    pulse_backend = QiskitPulseSimulator(processor)
+    pulse_job = pulse_backend.run(pulse_circ)
+    pulse_result = pulse_job.result()
+
+>>> plot_histogram(pulse_result.get_counts())
+
+.. image:: /figures/qiskit-pulse-level-plot.png
+    :alt: probabilities plot
+
+Configurable Options
+========================
+
+Qiskit's interface allows us to provide some options like ``shots`` while running a circuit on a backend. We also have provided some options for the qutip_qip backends.
+
+``shots``
+-------------
+(Available for both: :class:`.QiskitCircuitSimulator` and :class:`.QiskitPulseSimulator`)
+``shots`` is the number of times measurements are sampled from the simulation result. By default it is set to ``1024``.
+
+``allow_custom_gate``
+-----------------------
+(Only available for :class:`.QiskitCircuitSimulator`)
+``allow_custom_gate``, when set to ``False``, does not allowing simulating circuits that have user-defined gates; it will throw an error in that case. By default, it is set to ``True``, in which case, the backend will simulate a user-defined gate by computing its unitary matrix.
+
+    The pulse backend does not allow simulation with user-defined gates.
+
+An example demonstrating configuring options:
+
+.. code-block::
+
+    backend = QiskitCircuitSimulator()
+    job = backend.run(circ, shots=3000)
+    result = job.result()
+
+We provided the value of shots explicitly, hence our options for the simulation are set as: ``shots=3000`` and ``allow_custom_gate=True``.
+
+Another example:
+
+.. code-block::
+    
+    backend = QiskitCircuitSimulator()
+    job = backend.run(circ, shots=3000, allow_custom_gate=False)
+    result = job.result()

src/qutip_qip/device/cavityqed.py

@@ -88,9 +88,7 @@ def __init__(
         self, num_qubits, num_levels=10, correct_global_phase=True, **params
     ):
         model = CavityQEDModel(
-            num_qubits=num_qubits,
-            num_levels=num_levels,
-            **params,
+            num_qubits=num_qubits, num_levels=num_levels, **params
         )
         super(DispersiveCavityQED, self).__init__(
             model=model, correct_global_phase=correct_global_phase
@@ -105,21 +103,21 @@ def sx_ops(self):
         """
         list: A list of sigmax Hamiltonians for each qubit.
         """
-        return self.ctrls[0 : self.num_qubits]
+        return self.ctrls[0: self.num_qubits]
 
     @property
     def sz_ops(self):
         """
         list: A list of sigmaz Hamiltonians for each qubit.
         """
-        return self.ctrls[self.num_qubits : 2 * self.num_qubits]
+        return self.ctrls[self.num_qubits: 2 * self.num_qubits]
 
     @property
     def cavityqubit_ops(self):
         """
         list: A list of interacting Hamiltonians between cavity and each qubit.
         """
-        return self.ctrls[2 * self.num_qubits : 3 * self.num_qubits]
+        return self.ctrls[2 * self.num_qubits: 3 * self.num_qubits]
 
     @property
     def sx_u(self):
@@ -129,15 +127,15 @@ def sx_u(self):
     @property
     def sz_u(self):
         """array-like: Pulse matrix for sigmaz Hamiltonians."""
-        return self.coeffs[self.num_qubits : 2 * self.num_qubits]
+        return self.coeffs[self.num_qubits: 2 * self.num_qubits]
 
     @property
     def g_u(self):
         """
         array-like: Pulse matrix for interacting Hamiltonians
         between cavity and each qubit.
         """
-        return self.coeffs[2 * self.num_qubits : 3 * self.num_qubits]
+        return self.coeffs[2 * self.num_qubits: 3 * self.num_qubits]
 
     def eliminate_auxillary_modes(self, U):
         """
@@ -167,6 +165,48 @@ def load_circuit(self, qc, schedule_mode="ASAP", compiler=None):
         self.global_phase = compiler.global_phase
         return tlist, coeff
 
+    def generate_init_processor_state(
+        self, init_circuit_state: Qobj = None
+    ) -> Qobj:
+        """
+        Generate the initial state with the dimensions of the DispersiveCavityQED processor.
+
+        Parameters
+        ----------
+        init_circuit_state : :class:`qutip.Qobj`
+            Initial state provided with the dimensions of the circuit.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the initial state with the dimensions of the DispersiveCavityQED processor model.
+            If initial_circuit_state was not provided, return the zero state.
+        """
+        if init_circuit_state is None:
+            return basis(
+                [self.num_levels] + [2] * self.num_qubits,
+                [0] + [0] * self.num_qubits,
+            )
+        return tensor(basis(self.num_levels, 0), init_circuit_state)
+
+    def get_final_circuit_state(self, final_processor_state: Qobj) -> Qobj:
+        """
+        Truncate the final processor state to get rid of the cavity subsystem.
+
+        Parameters
+        ----------
+        final_processor_state : :class:`qutip.Qobj`
+            State provided with the dimensions of the DispersiveCavityQED processor model.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the truncated final state with the dimensions of the circuit.
+        """
+        return final_processor_state.ptrace(
+            range(1, len(final_processor_state.dims[0]))
+        )
+
 
 class CavityQEDModel(Model):
     """

src/qutip_qip/device/modelprocessor.py

@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from qutip import Qobj, QobjEvo, tensor, mesolve
+from qutip import Qobj, QobjEvo, tensor, mesolve, basis
 from ..operations import globalphase
 from ..circuit import QubitCircuit
 from .processor import Processor
@@ -164,7 +164,7 @@ def pulse_matrix(self, dt=0.01):
             t_idx_len = int(np.floor(dt_list[n] / dt))
             mm = 0
             for m in range(len(ctrls)):
-                u[mm, t_start : (t_start + t_idx_len)] = (
+                u[mm, t_start: (t_start + t_idx_len)] = (
                     np.ones(t_idx_len) * coeffs[n, m]
                 )
                 mm += 1
@@ -243,6 +243,45 @@ def load_circuit(self, qc, schedule_mode="ASAP", compiler=None):
         self.set_tlist(tlist)
         return tlist, coeffs
 
+    def generate_init_processor_state(
+        self, init_circuit_state: Qobj = None
+    ) -> Qobj:
+        """
+        Generate the initial state with the dimensions of the processor.
+
+        Parameters
+        ----------
+        init_circuit_state : :class:`qutip.Qobj`
+            Initial state provided with the dimensions of the circuit.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the initial state with the dimensions
+            of the processor model. If initial_circuit_state
+            was not provided, return the zero state.
+        """
+        if init_circuit_state is None:
+            return basis([2] * self.num_qubits, [0] * self.num_qubits)
+        return init_circuit_state
+
+    def get_final_circuit_state(self, final_processor_state: Qobj) -> Qobj:
+        """
+        Convert the state with the dimensions of the processor model to
+        a state with the dimensions of the circuit.
+
+        Parameters
+        ----------
+        final_processor_state : :class:`qutip.Qobj`
+            State provided with the dimensions of the processor model.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the final state with the dimensions of the circuit.
+        """
+        return final_processor_state
+
 
 def _to_array(params, num_qubits):
     """