Merge 0a308e8 into 7bad281

doc/source/installation.rst

@@ -47,7 +47,68 @@ In addition
 
 are used to build and test the documentation.
 
-A few other packages such as LaTeX is used for circuit plotting, please refer to the main documentation section for detailed instruction.
+.. _circuit_plot_packages:
+
+Additional software for Plotting Circuits
+=========================================
+In order to plot circuits, the following non-Python packages are needed:
+
+LaTeX
+-----
+The circuit plotting function in QuTiP uses LaTeX and a few LaTeX packages including ``qcircuit``, ``pdfcrop`` and ``braket``.
+
+**For Linux and Mac** :
+You need to install a TeX distribution such as `TeX Live <https://www.tug.org/texlive/>`_. You can either install it through ``apt-get``/``brew`` or using their installer on the website.
+If you would prefer to avoid installing the full ``texlive`` distribution (which is a few Gigabyte large), `this link <https://tex.stackexchange.com/a/504566/203959>`_
+has some useful discussion on selectively installing part of the packages. In particular:
+
+* ``braket`` will be installed as a part of ``texlive-latex-extra``
+* ``qcircuit`` will be installed as a part of ``texlive-pictures``
+* ``pdfcrop`` and ``pdflatex`` are installed when a minimal ``texlive`` is installed.
+
+.. note::
+  Do not install ``pdfcrop`` via pip because the package's old dependencies will clash
+  with newer dependencies of other programs installed in the ``qutip-qip`` virtual
+  environment.
+
+**For Windows** :
+We recommend installing `MiKTeX <https://miktex.org/>`_, which will automatically install necessary packages like ``qcircuit`` for you when it is used. It will only take a few more minutes in your first attempt at plotting a circuit.
+In addition, you also need to install perl for ``pdfcrop``.
+
+ImageMagick and Ghostscript
+---------------------------
+In order to display the circuit in Jupyter notebook, we need to convert it to png
+format. To do that, you will need to install `Ghostscript <https://www.ghostscript.com/doc/current/Make.htm>`_
+and `ImageMagick <https://imagemagick.org/script/install-source.php>`_.
+The first is responsible for reading the pdf file while the second will convert it to png.
+
+
+.. note::
+    You `might need to make changes <https://stackoverflow.com/a/52863413/10241324>`_ to ``policy.xml`` if the following error occurs :
+
+    .. code-block:: text
+
+        RuntimeError: convert-im6.q16: not authorized `qcirc.pdf' @ error/constitute.c/ReadImage/412.
+        convert-im6.q16: no images defined `qcirc.png' @ error/convert.c/ConvertImageCommand/3258.
+
+
+The output of a circuit plot will be output in a `Jupyter notebook <https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html>`_.
+In your virtual environment, start [a Jupyter notebook server](https://jupyter.readthedocs.io/en/latest/running.html#starting-the-notebook-server) and run your examples
+in a notebook. If you try to access a circuit plot in a terminal or IPython console,
+you will only be able to access the location of this image in your device's memory.
+
+
+
+pdf2svg
+-------
+To convert the circuit into svg format, you will need to install ``pdf2svg``.
+Please visit `their website <https://github.com/dawbarton/pdf2sv>`_ for installation guide.
+
+.. note::
+    If you want to check whether all dependencies are installed,
+    see if the following three commands work correctly:
+    ``pdflatex``, ``pdfcrop`` and ``magick anypdf.pdf anypdf.png``,
+    where ``anypdf.pdf`` is any pdf file you have.
 
 .. _installation:
 
@@ -69,6 +130,7 @@ If you want to edit the code, use instead
     pip install -e .
 
 To test the installation from a download of the source code, run from the `qutip-qip` directory
+
 ```
 pytest tests
 ```

doc/source/qip-basics.rst

@@ -284,20 +284,8 @@ Plotting a Quantum Circuit
 A quantum circuit (described above) can directly be plotted using the QCircuit library (https://github.com/CQuIC/qcircuit).
 QCiruit is a quantum circuit drawing application and is implemented directly into QuTiP.
 
-The circuit image visualization requires LaTeX and ImageMagick for display.
-The module automatically generates the LaTeX code for plotting the circuit,
-produces the pdf and converts it to the png format. On Mac and Linux,
-ImageMagick can be easily installed with the command conda install imagemagick if you have conda installed.
-Otherwise, please follow the installation instructions on the ImageMagick documentation.
-
-On windows, you need to download and install ImageMagick installer.
-In addition, you also need perl (for ``pdfcrop``) and
-Ghostscript (additional dependency of ImageMagick for png conversion).
-
-If you want to check whether all dependencies are installed,
-see if the following three commands work correctly:
-``pdflatex``, ``pdfcrop`` and ``magick anypdf.pdf anypdf.png``,
-where ``anypdf.pdf`` is any pdf file you have.
+More information related to installing these packages is also available in the
+installation guide (:ref:`circuit_plot_packages`).
 
 An example code for plotting the example quantum circuit from above is given: