qasm2image 0.8.0
An OpenQASM visualisation tool
Keywords: qasm svg png visualisation


qasm2image
==========

The qasm2image repository provides functions to represent quantum circuits written following the `OpenQASM <https://github.com/QISKit/qiskit-openqasm>`_ specification.

Installation
------------

Dependencies
^^^^^^^^^^^^

The tool and all the dependencies are available via the PIP tool. See the installation instructions below.

Installation procedure
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: shell

   pip3 install cffi
   pip3 install qasm2image

Usage
-----

In a Python environnement
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

   # Import the functions
   from qasm2image import qasm2svg
   from qasm2image import qasm2png
   # Generate your QASM string (either read from a file or generate a circuit and ask for its QASM).
   qasm_str = "..."
   # Define the basis used to represent the circuit
   basis = 'u1,u2,u3,U,cx'
   # Compute the SVG representation
   svg_str = qasm2svg(qasm_str, basis=basis, show_clbits=True)
   # Compute the PNG representation
   png_bytes = qasm2png(qasm_str, basis=basis, show_clbits=True)
   # Types of the outputs
   assert type(svg_str) is str
   assert type(png_bytes) is bytes
   # Write the result into files
   with open('circuit.svg', 'w') as svg_file:
       svg_file.write(svg_str)
   # Don't forget to write in *binary* mode for PNG
   with open('circuit.png', 'wb') as png_file:
       png_file.write(png_bytes)

In a shell environnement
^^^^^^^^^^^^^^^^^^^^^^^^

A script is provided to change QASM code directly from the command line.

.. code-block:: shell

   $ qasm2image -h
   usage: qasm2image [-h] [-b BASIS] [--hide-clbits] [-s SCALE]
                     input_file output_file

   Transform a quantum circuit in QASM format to an image format.

   positional arguments:
     input_file            the QASM file implementing the circuit to transform
     output_file           the image file that will be generated by the tool

   optional arguments:
     -h, --help            show this help message and exit
     -b BASIS, --basis BASIS
                           a comma-separated list of gate names which represent
                           the gate basis in which the circuit will be decomposed
     --hide-clbits         if present, classical bits will not be represented
     -s SCALE, --scale SCALE
                           scale of the PNG image. SVG output is not affected by
                           this parameter

License
-------

This project is distributed under the `CeCILL-B <http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html>`_ license. A copy of the whole license is included
in the repository.

In order to use the work in this repository you have a strong obligation to cite (as stated in the license):


#. 
   The author of the work: Adrien Suau (see on my GitHub page or `mail me <mailto:adrien.suau@grenoble-inp.org>`_ if any doubt).

#. 
   The CERFACS (Centre Européen de Recherche et de Formation Avancée en Calcul Scientifique).

Output
------

`adder.qasm <https://github.com/nelimeee/qasm2image/blob/master/tests/examples/generic/adder.qasm>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/adder_simple.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/adder_simple.png
   :alt: adder.png


`qft.qasm <https://github.com/nelimeee/qasm2image/blob/master/tests/examples/generic/qft.qasm>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/qft_simple.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/qft_simple.png
   :alt: qft.png


`inverseqft1.qasm <https://github.com/nelimeee/qasm2image/blob/master/tests/examples/generic/inverseqft1.qasm>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/inverseqft1_simple.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/inverseqft1_simple.png
   :alt: inverseqft1.png


`inverseqft2.qasm <https://github.com/nelimeee/qasm2image/blob/master/tests/examples/generic/inverseqft2.qasm>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/inverseqft2_simple.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/inverseqft2_simple.png
   :alt: inverseqft2.png


`qec.qasm <https://github.com/nelimeee/qasm2image/blob/master/tests/examples/generic/qec.qasm>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/qec_simple.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/qec_simple.png
   :alt: qec.png

The same QASM code, but with the ``hide-clbits`` option set: ``qasm2image --hide-clbits qec.{qasm,png}``.

.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/qec_no_clbits.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/qec_no_clbits.png
   :alt: qec\_no\_clbits.png


`teleportv2.qasm <https://github.com/nelimeee/qasm2image/blob/master/tests/examples/generic/teleportv2.qasm>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. image:: https://github.com/nelimeee/qasm2image/blob/master/images/teleportv2_simple.png
   :target: https://github.com/nelimeee/qasm2image/blob/master/images/teleportv2_simple.png
   :alt: teleportv2.png