Merge pull request #121 from BoxiLi/Rework-on-doc

Rework on the doc of the pulse-level simulation

.github/workflows/test.yml

@@ -72,7 +72,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install numpy scipy cython qutip sphinx matplotlib numpydoc sphinx_rtd_theme
+        python -mpip install -r doc/requirements.txt
         pip install .
     - name: Test code snippets in the documentation
       run: |

doc/requirements.txt

@@ -8,3 +8,4 @@ readthedocs-sphinx-search==0.1.0rc3
 numpydoc==1.1.0
 matplotlib==3.3.4
 docutils==0.16
+sphinxcontrib-bibtex==2.4

doc/source/apidoc.rst

@@ -6,7 +6,7 @@ qutip\_qip package
    :maxdepth: 1
 
 
-Operator-level simulation
+Gate-level simulation
 -------------------------
 Simulation based on operator-state multiplication.
 

doc/source/bibliography.rst

@@ -0,0 +1,7 @@
+************
+Bibliography
+************
+
+.. bibliography::
+    :cited:
+    :style: unsrt

doc/source/conf.py

@@ -57,6 +57,8 @@ def qutip_qip_version():
               'sphinx.ext.viewcode',
               'sphinx.ext.ifconfig',
               'sphinx.ext.napoleon',
+              'sphinxcontrib.bibtex',
+              'sphinx.ext.intersphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -171,4 +173,15 @@ def qutip_qip_version():
 # attention that some api docs files are adjusted manually for better illustration
 # and should not be overwritten.
 # autosummary_generate = True
-autosummary_imported_members = True
+autosummary_imported_members = True
+
+# -- Options for biblatex ---------------------------------------
+
+bibtex_bibfiles = ['references.bib']
+bibtex_default_style = 'unsrt'
+
+# -- Options for intersphinx ---------------------------------------
+
+intersphinx_mapping = {
+    'qutip': ('https://qutip.org/docs/latest/', None),
+}

doc/source/index.rst

@@ -49,6 +49,11 @@ qutip-qip |version|: QuTiP quantum information processing
 
     apidoc.rst
 
+.. toctree::
+    :caption: Bibliography
+
+    bibliography.rst
+
 Indices and tables
 ==================
 

doc/source/introduction.rst

@@ -19,13 +19,12 @@ It offers two different approaches for simulating quantum circuits, one with :cl
 Citing
 ===========
 
-If you use ``qutip.qip`` in your research, please cite the `article <https://quantum-journal.org/papers/q-2022-01-24-630>`_
+If you use ``qutip-qip`` in your research, please cite the `article <https://quantum-journal.org/papers/q-2022-01-24-630>`_
 as
 
 .. code-block:: text
 
-  Boxi Li, Shahnawaz Ahmed, Sidhant Saraogi, Neill Lambert, Franco Nori, Alexander Pitchford, & Nathan Shammah. (2021). Pulse-level noisy quantum circuits with QuTiP.
-
+    Boxi Li, Shahnawaz Ahmed, Sidhant Saraogi, Neill Lambert, Franco Nori, Alexander Pitchford, & Nathan Shammah. (2022). Pulse-level noisy quantum circuits with QuTiP. Quantum, 6, 630.
 
 The bibtex can be downloaded directly :download:`here<qutip_qip.bib>` or
 copy-pasted using :

doc/source/qip-simulator.rst

@@ -1,8 +1,8 @@
 .. _qip_simulator:
 
-*********************************
-Operator-level circuit simulation
-*********************************
+*****************************
+Gate-level circuit simulation
+*****************************
 
 Run a quantum circuit
 =====================

doc/source/references.bib

@@ -0,0 +1,65 @@
+@article{Li2022pulselevelnoisy,
+  doi = {10.22331/q-2022-01-24-630},
+  url = {https://doi.org/10.22331/q-2022-01-24-630},
+  title = {Pulse-level noisy quantum circuits with {Q}u{T}i{P}},
+  author = {Li, Boxi and Ahmed, Shahnawaz and Saraogi, Sidhant and Lambert, Neill and Nori, Franco and Pitchford, Alexander and Shammah, Nathan},
+  journal = {{Quantum}},
+  issn = {2521-327X},
+  publisher = {{Verein zur F{\"{o}}rderung des Open Access Publizierens in den Quantenwissenschaften}},
+  volume = {6},
+  pages = {630},
+  month = jan,
+  year = {2022}
+}
+@article{magesan2020effective,
+  title={Effective Hamiltonian models of the cross-resonance gate},
+  author={Magesan, Easwar and Gambetta, Jay M},
+  journal={Physical Review A},
+  volume={101},
+  number={5},
+  pages={052308},
+  year={2020},
+  publisher={APS}
+}
+@article{blais2021circuit,
+  title={Circuit quantum electrodynamics},
+  author={Blais, Alexandre and Grimsmo, Arne L and Girvin, SM and Wallraff, Andreas},
+  journal={Reviews of Modern Physics},
+  volume={93},
+  number={2},
+  pages={025005},
+  year={2021},
+  publisher={APS}
+}
+@article{mundada2019suppression,
+  title={Suppression of qubit crosstalk in a tunable coupling superconducting circuit},
+  author={Mundada, Pranav and Zhang, Gengyan and Hazard, Thomas and Houck, Andrew},
+  journal={Physical Review Applied},
+  volume={12},
+  number={5},
+  pages={054023},
+  year={2019},
+  publisher={APS}
+}
+@book{breuer2002theory,
+  title={The theory of open quantum systems},
+  author={Breuer, Heinz-Peter and Petruccione, Francesco and others},
+  year={2002},
+  publisher={Oxford University Press on Demand}
+}
+@article{lidar2019lecture,
+  title={Lecture notes on the theory of open quantum systems},
+  author={Lidar, Daniel A},
+  journal={arXiv preprint arXiv:1902.00967},
+  year={2019}
+}
+@article{koch2007charge,
+  title={Charge-insensitive qubit design derived from the Cooper pair box},
+  author={Koch, Jens and Terri, M Yu and Gambetta, Jay and Houck, Andrew A and Schuster, David Isaac and Majer, Johannes and Blais, Alexandre and Devoret, Michel H and Girvin, Steven M and Schoelkopf, Robert J},
+  journal={Physical Review A},
+  volume={76},
+  number={4},
+  pages={042319},
+  year={2007},
+  publisher={APS}
+}

src/qutip_qip/device/cavityqed.py

@@ -28,7 +28,7 @@
 class DispersiveCavityQED(ModelProcessor):
     """
     The processor based on the physical implementation of
-    a dispersive cavity QED system.
+    a dispersive cavity QED system (:obj:`.CavityQEDModel`).
     The available Hamiltonian of the system is predefined.
     For a given pulse amplitude matrix, the processor can
     calculate the state evolution under the given control pulse,
@@ -134,22 +134,59 @@ class CavityQEDModel(Model):
     """
     The physical model for a dispersive cavity-QED processor
     (:obj:`.DispersiveCavityQED`).
+    It is a qubit-resonator model that describes a system composed of
+    a single resonator and a few qubits connected to it.
+    The coupling is kept small so that the resonator is rarely
+    excited but acts only as a mediator for entanglement generation.
+    The single-qubit control Hamiltonians used are
+    :math:`\sigma_x` and :math:`\sigma_z`.
+    The dynamics between the resonator and the qubits is captured by
+    the Tavis-Cummings Hamiltonian,
+    :math:`\propto\sum_j a^\dagger \sigma_j^{-} + a \sigma_j^{+}`,
+    where :math:`a`, :math:`a^\dagger` are
+    the destruction and creation operators of the resonator,
+    while :math:`\sigma_j^{-}`, :math:`\sigma_j^{+}` are those of each qubit.
+    The control of the qubit-resonator coupling depends on
+    the physical implementation, but in the most general case
+    we have single and multi-qubit control in the form
+
+    .. math::
+
+        H=
+        \\sum_{j=0}^{N-1}
+        \\epsilon^{\\rm{max}}_{j}(t) \\sigma^x_{j} +
+        \\Delta^{\\rm{max}}_{j}(t) \\sigma^z_{j} +
+        J_{j}(t)
+        (a^\\dagger \\sigma^{-}_{j} + a \\sigma^{+}_{j}).
+
+    The effective qubit-qubit coupling is computed by the
+
+    .. math::
+
+        J_j = \\frac{g_j g_{j+1}}{2}(\\frac{1}{\\Delta_j} +
+        \\frac{1}{\\Delta_{j+1}}),
+
+    with :math:`\\Delta=w_q-w_0`
+    and the dressed qubit frequency :math:`w_q` defined as
+    :math:`w_q=\sqrt{\epsilon^2+\delta^2}`.
 
     Parameters
     ----------
     num_qubits : int
-        The number of qubits.
+        The number of qubits :math:`N`.
     num_levels : int, optional
         The truncation level of the Hilbert space for the resonator.
     **params :
         Keyword arguments for hardware parameters, in the unit of GHz.
         Qubit parameters can either be a float or a list of the length
-        ``num_qubits``.
+        :math:`N`.
 
         - deltamax: float or list, optional
-            The pulse strength of sigma-x control, default ``1.0``.
+            The pulse strength of sigma-x control,
+            :math:`\\Delta^{\\rm{max}}`, default ``1.0``.
         - epsmax: float or list, optional
-            The pulse strength of sigma-z control, default ``9.5``.
+            The pulse strength of sigma-z control,
+            :math:`\\epsilon^{\\rm{max}}`, default ``9.5``.
         - eps: float or list, optional
             The bare transition frequency for each of the qubits,
             default ``9.5``.
@@ -159,15 +196,13 @@ class CavityQEDModel(Model):
             The coupling strength between the resonator and the qubit,
             default ``1.0``.
         - w0 : float, optional
-            The bare frequency of the resonator. Should only be a float,
-            default ``0.01``.
+            The bare frequency of the resonator :math:`w_0`.
+            Should only be a float, default ``0.01``.
         - t1 : float or list, optional
             Characterize the amplitude damping for each qubit.
         - t2 : list of list, optional
             Characterize the total dephasing for each qubit.
 
-        The dressed qubit frequency is `wq` is computed by
-        :math:`w_q=\sqrt{\epsilon^2+\delta^2}`
     """
 
     def __init__(self, num_qubits, num_levels=10, **params):

src/qutip_qip/device/circuitqed.py

@@ -16,7 +16,8 @@
 
 class SCQubits(ModelProcessor):
     """
-    A chain of superconducting qubits with fixed frequency.
+    A chain of superconducting qubits with fixed frequency
+    (:obj:`SCQubitsModel`).
     Single-qubit control is realized by rotation around the X and Y axis
     while two-qubit gates are implemented with Cross Resonance gates.
     A 3-level system is used to simulate the superconducting qubit system,
@@ -25,8 +26,6 @@ class SCQubits(ModelProcessor):
     system, as a demonstration and
     for simplicity, we only use a ZX Hamiltonian for
     the two-qubit interaction.
-    For details see https://arxiv.org/abs/2005.12667 and
-    https://journals.aps.org/pra/abstract/10.1103/PhysRevA.101.052308.
 
     Parameters
     ----------
@@ -63,6 +62,43 @@ class SCQubitsModel(Model):
     """
     The physical model for superconducting-qubit model processor
     (:obj:`.SCQubits`) with fixed frequency.
+    Each qubit is simulated by a multi-level Duffing model
+    :cite:`koch2007charge`,
+    in which the qubit subspace is provided by the ground state
+    and the first excited state.
+    By default, the creation and annihilation operators are
+    truncated at the third level, which can be adjusted.
+    The multi-level representation can capture the leakage of the population
+    out of the qubit subspace during single-qubit gates.
+    The single-qubit control is generated by two orthogonal quadratures
+    :math:`a_j^{\\dagger}+a_j` and :math:`i(a_j^{\\dagger}-a_j)`.
+    The interaction is possible only between adjacent qubits.
+    Although this interaction is mediated by a resonator, for simplicity,
+    we replace the complicated dynamics among two superconducting qubits
+    and the resonator with a two-qubit effective Hamiltonian
+    derived in Ref. :cite:`magesan2020effective`.
+
+    As an example, we choose the cross resonance interaction
+    in the form of :math:`\\sigma^z_{j} \\sigma^x_{j+1}`,
+    acting only on the two-qubit levels,
+    which is widely used, e.g., in fixed-frequency superconducting qubits.
+    We can write the Hamiltonian as
+
+    .. math::
+
+        H &= H_{\\rm{d}}
+         + \\sum_{j=0}^{N-1} \\Omega^x_{j} (a_j^{\\dagger} + a_j)
+        + \\Omega^y_{j} i(a_j^{\\dagger} - a_j) \\\\
+        &
+        + \\sum_{j=0}^{N-2} \\Omega^{\\rm{cr}1}_{j} \\sigma^z_j \\sigma^x_{j+1}
+        + \\Omega^{\\rm{cr}2}_{j} \\sigma^x_j \\sigma^z_{j+1}
+
+    where the drift Hamiltonian is defined as
+
+    .. math::
+
+        H_{\\rm{d}} = \\sum_{j=0}^{N-1}
+        \\frac{\\alpha_j}{2} a_j^{\\dagger}a_j^{\\dagger}a_j a_j
 
     Parameters
     ----------
@@ -90,7 +126,8 @@ class SCQubitsModel(Model):
             Anharmonicity for each superconducting qubit,
             default ``[-0.3]*num_qubits``.
         - omega_single : list, optional
-            Control strength for single-qubit gate,
+            The maximal control strength for single-qubit gate,
+            :math:`\\Omega^x` and :math:`\\Omega^y`,
             default ``[0.01]*num_qubits``.
         - omega_cr : list, optional
             Control strength for cross resonance gate,

src/qutip_qip/device/processor.py

@@ -27,7 +27,7 @@
 class Processor(object):
     """
     The noisy quantum device simulator using QuTiP dynamic solvers.
-    It compiles quantums circuit into a Hamiltonian model and then
+    It compiles quantum circuit into a Hamiltonian model and then
     simulate the time-evolution described by the master equation.
 
     Parameters

src/qutip_qip/device/spinchain.py

@@ -222,12 +222,28 @@ def topology_map(self, qc):
 class SpinChainModel(Model):
     """
     The physical model for the spin chian processor
-    (:obj:`CircularSpinChain` and :obj`LinearSpinChain`).
+    (:obj:`CircularSpinChain` and :obj:`LinearSpinChain`).
+    The interaction is only possible between adjacent qubits.
+    The single-qubit control Hamiltonians are :math:`\\sigma_j^x`$`,
+    :math:`\\sigma_j^z`, while the interaction is realized by
+    the exchange Hamiltonian
+    :math:`\\sigma^x_{j}\\sigma^x_{j+1}+\\sigma^y_{j}\\sigma^y_{j+1}`.
+    The overall Hamiltonian model is written as:
+
+    .. math::
+
+        H=
+        \\sum_{j=0}^{N-1}
+        \\Omega^x_{j}(t) \\sigma^x_{j} +
+        \\Omega^z_{j}(t) \\sigma^z_{j} + \\sum_{j=0}^{N-2}
+        g_{j}(t)
+        (\\sigma^x_{j}\\sigma^x_{j+1}+
+        \\sigma^y_{j}\\sigma^y_{j+1}).
 
     Parameters
     ----------
     num_qubits: int
-        The number of qubits.
+        The number of qubits, :math:`N`.
     setup : str
         "linear" for an open end and "circular" for a closed end chain.
     **params :
@@ -237,14 +253,16 @@ class SpinChainModel(Model):
         for each qubits.
 
         - sx : float or list, optional
-            The pulse strength of sigma-x control, default ``0.25``.
+            The pulse strength of sigma-x control, :math:`\\Omega^x`,
+            default ``0.25``.
         - sz : float or list, optional
-            The pulse strength of sigma-z control, default ``1.0``.
+            The pulse strength of sigma-z control, :math:`\\Omega^z`,
+            default ``1.0``.
         - sxsy : float or list, optional
-            The pulse strength for the exchange interaction,
+            The pulse strength for the exchange interaction, :math:`g`,
             default ``0.1``.
             It should be either a float or an array of the length
-            ``num_qubits-1`` for the linear setup or ``num_qubits`` for
+            :math:`N-1` for the linear setup or :math:`N` for
             the circular setup.
         - t1 : float or list, optional
             Characterize the amplitude damping for each qubit.