.. _using_Circuit_builder:
================================
3. Using Circuit Builder 
================================

3.1 Overview
-------------
The QuICScript Circuit Builder is built using HTML, Javascript, and CSS. 

The core files are as follows:

::

    ├──index.html
    └──assets/
        ├──index-xxxxxxxx.js
        └──index-xxxxxxxx.css

1. ``index.html`` - Point your web server to ``index.html`` to serve
    * | This file maybe edited to change the default circuit layout. 
      | See :ref:`change-default-configuration` for more information.

2. ``index-xxxxxxxx.js`` - Logic for Circuit Builder
3. ``index-xxxxxxxx.css`` - Styling for Circuit Builder

.. note::
    
    Do not modify the ``js`` and ``css`` files directly as it may break the application. They are bundled assets through the build process.
    
    **xxxxxxxx** - Are hashed values of the file, will be different if there's updates to the file.

.. _change-default-configuration:

3.2 Change Gate Style and Palette
---------------------------------

3.2.1 Change 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;``

3.2.2 Change 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.

.. _add-new-circuit:

3.3 Add New Circuit 
-------------------
Description
^^^^^^^^^^^^^^^^^
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
^^^^^^^^^^
- ``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: 13 10 25 15 5 3
  :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
    - Enable/Disable 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: 8 8 8 25 5
  :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

3.4 Embed Circuit Builder in Website
-------------------------------------

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:`add-new-circuit` for more information on the URL parameters you can modify to create custom configurations.