.. _Circuit Builder:

Using Circuit Builder 
================================


.. figure:: images/circuit_builder.png
   :figwidth: 100%
   :alt: Circuit Builder

   QuICScript Circuit Builder (Default Configration)

Folder structure
-----------------
The QuICScript Circuit Builder is built using HTML, Javascript, and CSS. 

The core files are as follows:

::

   ├──index.html - Modify this file to change the default configuration
   └──assets/
      ├──index.js
      ├──index.css
      ├──QuICScript.js
      └──QuICScript.wasm

#. ``index.html`` - Web server to point to ``index.html``. For customization, see following sections for more information.
#. ``index.js`` - Logic for Circuit Builder
#. ``index.css`` - Styling for Circuit Builder
#. ``QuICScript.js`` - QuICScript Engine WASM library
#. ``QuICScript.wasm`` - QuICScript Engine WebAssembly file

.. warning::
    
	**Do not** modify the ``js`` and ``css`` files directly as it may break the application. They are bundled assets through the build process.

.. _change-default-configuration:

Circuit Builder Configuration
------------------------------

QuICScript Circuit Builder comes with fully customizable features suited for your needs. From changing styling to setting default configurations, the builder is designed to be flexible enabling personalized experience.

#. :ref:`Theme configuration`

   * :ref:`Change Gate Style`
   * :ref:`Modify Gate Palette`

#. :ref:`Feature configuration`

   #. :ref:`URL Params`
   #. :ref:`defaultConfig`

.. _Theme configuration:

Theme configuration
^^^^^^^^^^^^^^^^^^^^^^^

   Theme configuration allows you to change the look and feel of the Circuit Builder.

.. _Change Gate Style:

Modify Gate Style
"""""""""""""""""""

.. figure:: images/gate_style.png
   :figwidth: 30%
   :width: 100%
   :align: center
   :alt: Gate Style

Update in ``index.html`` under ``<style>`` tag. 

.. code-block:: html

   <style>
      div.gate {
         /* Change Gate background color here: Default (#f3f4f6) */
         background-color: #98CFEC;
      }
   </style>

.. note::

    Any CSS styling works, including removing border ``border: none;``

.. figure:: images/gate_palette.png
   :figwidth: 19%
   :align: Right
   :alt: Gate Palette

   Gate Palette

.. _Modify Gate Palette:

Modify Gate Palette
"""""""""""""""""""""

Update in index.html under ``<script>`` tag.

.. code-block:: html

   <script>
      /** Update Gates present in the palette: Default ["H", "X", "Y", "Z", "C", "N", "P", "T", "I", "s", "U", "d", "m"]  */
      /** Do check the documentation for allowed gates */
      const gates = ["H", "X", "Y", "Z", "C", "P", "T", "I", "s", "U", "m"];
   </script>

.. note::

	Check out :ref:`using_QuICScript` for available gates.

.. _Feature configuration:

Feature configuration
^^^^^^^^^^^^^^^^^^^^^^^

| The Circuit Builder comes with a set of features that can be customized to suit your needs.
| Feature configuration enable you to set default parameters for the builder.

Check :ref:`Parameters` for feature list.

There are 2 methods to customize the circuit builder.

#. :ref:`URL Params`
#. :ref:`defaultConfig`

.. note::

   The circuit builder piorities ``URL Params`` over ``defaultConfig``, if ``URL Params`` is set, ``defaultConfig`` will be disregarded.

.. _URL Params:

URL Params
"""""""""""

URL Params follows `Query String <https://en.wikipedia.org/wiki/Query_string>`_.

Using URL Params allows user to insert default parameters into the system for configurations.

Usage 
********

Single Parameter ``<url>?<param>=<data>``

Multiple Parameter (Separated with &) ``<url>?<param>=<data>&<param>=<data>``

.. warning::
   
   Make sure ``<param>`` follow exactly to Available Params. Any invalid param/data will not reflect in the builder.

.. _Parameters:

Parameters
***********

- ``quicscript`` - `QuICScript String <https://pqcee.github.io/QuICScript-manual/using_QuICScript.html#circuit-syntax>`_ 
- ``qubits`` - Number of qubits
- ``columns`` - Number of columns
- ``qibo`` - Enable/Disable of `Qibo <https://qibo.science/>`_ Feature
- ``type`` - Type of output
- ``input`` - Enable/Disable of Input Feature

.. list-table:: Parameters
  :widths: 6 5 10 10 5 5
  :header-rows: 1

  * - Query string parameter
    - Type
    - Description
    - Constraint
    - Default
    - Example
  * - ``quicscript``
    - string
    - `QuICScript String <https://pqcee.github.io/QuICScript-manual/using_QuICScript.html#circuit-syntax>`_ (qubits are calculated)
    - 0 :math:`<` qubits :math:`\leq` 20
    - ---
    - `Link <https://pqcee.github.io/quicscript-dev-react/?quicscript=HI,CN>`__
  * - ``qubits``
    - integer
    - Number of qubits
    - 0 :math:`<` qubits :math:`\leq` 20
    - ``9``
    - `Link <https://pqcee.github.io/quicscript-dev-react/?qubits=3>`__
  * - ``columns``
    - integer
    - Gate depth
    - ---
    - ``20``
    - `Link <https://pqcee.github.io/quicscript-dev-react/?columns=5>`__
  * - ``qibo``
    - boolean
    - Toggle Qibo Feature
    - ``true`` | ``false``
    - ``false``
    - `Link <https://pqcee.github.io/quicscript-dev-react/?qibo=false>`__
  * - ``type``
    - string
    - Type of output
    - ``decimal`` | ``binary`` | ``invbinary``
    - ``binary``
    - `Link <https://pqcee.github.io/quicscript-dev-react/?type=decimal&quicscript=HI,CN>`__
  * - ``input``
    - boolean
    - Enable QuICScript input 
    - ``true`` | ``false``
    - ``true``
    - `Link <https://pqcee.github.io/quicscript-dev-react/?input=true>`__

.. list-table:: Examples use cases
  :widths: 10 10 10 25 10
  :header-rows: 1

  * - quicscript
    - qubits
    - columns
    - Remarks
    - Example
  * - not-in-use
    - not-in-use
    - not-in-use
    - Default configuration
    - `Link <https://pqcee.github.io/quicscript-dev-react/>`__
  * - use
    - not-in-use
    - not-in-use
    - Set Bell State
    - `Link <https://pqcee.github.io/quicscript-dev-react/?quicscript=HI,CN>`__
  * - use
    - use
    - use
    - 3-qubit QFT circuit with 6 columns
    - `Link <https://pqcee.github.io/quicscript-dev-react/?quicscript=IIH,ICP,CIT,IHI,CPI,HII&qubits=3&columns=6>`__
  * - not-in-use
    - use
    - use
    - Empty 5-qubit circuit with gate depth of 10
    - `Link <https://pqcee.github.io/quicscript-dev-react/?qubits=5&columns=10>`__

.. note::
   In this example we are using ``https://pqcee.github.io/quicscript-dev-react/`` as the base URL, do replace it with where you are hosting the website application

.. _defaultConfig:

defaultConfig
""""""""""""""""""""""

Similar to :ref:`URL Params`, ``defaultConfig`` has all the parameters as configurable as ``URL Params``. ``defaultConfig`` enables config to be set in the ``index.html`` for standardized usage when served.

Confguration is done via editing ``index.html``, uncommenting the comments to set default config:

.. code::

   /* Allow config of the QuICScript Builder
   *  Remove the comment to enable the config
   */
   const defaultConfig = {
      // defaultQubits: 9, // Default: null
      // defaultColumns: 20, // Default: null
      // defaultQuic: "HI,CN", // Default: null
      // qibo: true, // Default: false
      // defaultResultDelimiter: "binary", // Default: binary (decimal, invbinary, binary)
      // displayInput: false, // Default: true
   };


Circuit Builder Setup (iFrame)
--------------------------------------------

Follow these steps: 

#. Basic Embedding

   * To embed the link ``https://pqcee.github.io/quicscript-dev-react/`` in an HTML file using an iframe:

   .. code-block:: html
      
      <iframe src="https://pqcee.github.io/quicscript-dev-react/?qibo=true&input=false"    
              title="iFrame example" 
              width="50%" 
              height="600" 
              allow="fullscreen">
      </iframe>

   .. note::
        
      This code embeds the page, allows full-screen, enables qibo, disables input field, and adjusts the width and height.*

#. Adjusting ``<iframe ...>`` Parameters:
   
   * Width: The width of the frame in CSS pixels. Default is 300.
   * Height: The height of the frame in CSS pixels. Default is 150.

#. Allow fullscreen: 

   * To enable fullscreen mode for the iframe, add the ``allow="fullscreen"`` attribute. 

#. Optional Parameters: 

   * See :ref:`Feature configuration` for more information on the URL parameters you can modify to create custom configurations.

 

Preloading Circuits
-------------------------------------

The Circuit Builder comes with a ``callback_render`` fuction which enables developers to interact with the visualizer via ``index.html``.

This can be triggered after ``ReactOnLoad``. Uncommenting the following code in ``index.html`` will set the circuit to render ``H,CN`` onload.

.. code:: javascript

   ReactOnLoad = () => {
      // Example Preload Circuit with H,CN
      // Uncomment the line below to preload a circuit
      // callback_render("H,CN");
   };