Metadata-Version: 2.1
Name: quingo
Version: 0.1.5
Summary: Quingo Runtime System
Home-page: https://gitee.com/quingo/quingo-runtime
Author: Xiang Fu
Author-email: gtaifu@gmail.com
License: UNKNOWN
Project-URL: Bug Tracker, https://gitee.com/quingo/quingo-runtime/issues
Description: # Quingo Runtime System
        
        Along with quingo compilers, the Quingo runtime system which provides users the capability to program and simulate Quingo programs.
        
        ## Installation
        
        The Quingo installation comprises of two main steps:
        
        ### Install the Runtime system and simulator
        Install Quingo runtime system with required simulators using the following command:
        ```sh
        pip install quingo
        ```
        
        Upon success, it will automatically install the Quingo runtime system (this package), the PyQCAS simulator and the PyQCISim simulator.
        
        ### Install the Quingo compiler
        
        Two versions of Quingo compiler has been developed:
        1. the mlir-based compiler, it can generate QCIS instructions which can be simulated by PyQCISim.
        2. the xtext-based compiler, it can generate eQASM instructions which can be simulated by PyQCAS
        
        
        #### Install the Mlir-based Compiler
        
        We can install mlir-based quingo compiler in two ways:
        
        + Install the mlir-based Quingo compiler using the following command:
          ```sh
          python -m quingo.install_quingoc
          ```
        
        + Download [mlir-based Quingo compiler](https://gitee.com/quingo/quingoc-release/releases)
          + Windows: unzip .zip file, add directory which contains the quingoc executable file to system environment PATH.  
          + Linux: as the following sample usage, Quingoc will be installed to user defined directory, then add directory which contains the quingoc executable file to system environment PATH.
          ```sh
           quingo-compiler-0.1.4.sh -prefix=/home/user/.local
          ```
          + Macos: uncompress .dmg file, copy quingoc executable file to user defined directory, then add directory which contains the quingoc executable file to system environment PATH.
        
        #### Install the Xtext-based Compiler
        
        At present, the java executable file of xtext-based compiler has not yet been automatically downloaded, so users need to download [java executable](https://github.com/Quingo/compiler_xtext/releases) separately to get the xtext-based compiler.
        
        After downloading the binary, you need to call specify the compiler path for once in python using the following commands:
        ```python
        import quingo
        # for xtext compiler
        quingo.set_xtext_compiler_path(<path-to-quingo.jar>)
        ```
        
        ## Usage
        A simple example can be found in the directory `src/examples`. You can simply run the bell_state example by running:
        ```sh
        cd src/examples/bell_state
        python host.py
        ```
        If everything runs correctly, you should see the following output:
        ```sh
        connecting pyqcisim_quantumsim...
        num_qubits:  2
        The result of bell_state is:
        (['q0', 'q1'], {'00': 504, '01': 0, '10': 0, '11': 496})
        ```
        
        ## APIs of the Quingo runtime system
        The `Quingo_interface` class expose the following methods:
         - `set_log_level(<log_level>)`: `<log_level>` can be one of `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`.
         - `connect_backend(<backend>)`: `<backend>` currently can be `'pyqcas_quantumsim'` or `'pyqcisim_quantumsim'`.
        - `get_backend_name()`: return the name of the backend that is being used. An empty string will be returned if no backend has been set.
        - `set_compiler(<compiler_name>)`: `<compiler_name>` can be `'mlir'` or `'xtext'`.
        - `get_last_qasm()`: get the qasm code generated by the last execution.
        - `config_execution(<mode>, <num_shots>)`:
          -  Configure the execution mode to `'one_shot'` or `'state_vector'`.
          -  When the execution mode is `'one_shot'`, the number of times to run the uploaded quantum circuit can be configured using the parameter `num_shots` at the same time.
        -  `call_quingo(<qg_filename>, <qg_func_name>, *args)`:
           - the main entry to call Quingo operation.
           - `<qg_filename (str)>` :  the name of the Qingo file which contains the quantum function called by the host program.
           - `<qg_func_name (str)>` : the name of the quantum function
           - `<args (dict)>`: a variable length of parameters used to call the Quingo operation in the form `qg_func_name(<args>)`.
         - `read_result()`: read the computation result from the quantum kernel.
           - For eQASM-based backend, the result is a binary block which encodes the quantum computation result.
           - For QCIS-based backend, the result format is defined by PyQCISim. Please refer to the docstring of `quingo.if_backend.non_arch_backend.pyqcisim_quantumsim.PyQCISim_quantumsim::execute()`
        
        ## Quingo programming tutorial
        At present, Qingguo runtime system has included sample programs such as `Bell_state`, `GHZ`, `VQE`, etc. Details can be found [here](https://gitee.com/quingo/quingo-runtime/tree/master/src/examples).
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
