15 Star 40 Fork 15

arclightquantum / isq

Create your Gitee Account
Explore and code with more than 12 million developers,Free private repositories !:)
Sign up
Clone or Download
Sync branch
Notice: Creating folder will generate an empty file .keep, because not support in Git

isQ is a quantum programming software. The compiler of isQ accepts isQ programs as input, and procedure low-level codes written several kinds of intermediate representations or instruction sets (depending on the conceret compiler options).


Via docker containers.

We provide a container which contains the isQ running environment, you can quickly get it through the following command

docker pull arclightquantum/isq:latest

From source code

You can also get isQ compiling from source code. Since isQ contains many modules, there are some environments need to be installed first.


software version ref
mlir =14.0.0 https://mlir.llvm.org/getting_started/
stack >=2.7 https://docs.haskellstack.org/en/stable/README/
cargo >=1.61 https://github.com/rust-lang/cargo
python >=3.8 https://docs.conda.io/en/latest/miniconda.html#linux-installers

get source code

Get source from gitee and set an environment variable ISQ_ROOT

git clone xxxxxx
cd xxx
mkdir bin
export ISQ_ROOT=`pwd`/xxx

install plugin


This plugin is used to do qubit mapping. We need use pyinstaller to convert .py to .exe

We suggest using conda to create a pure python env, otherwise the .exe may become very big

cd ${ISQ_ROOT}/simulator/plugins/python-routing-plugin/src
conda create -n route python=3.8
conda activate route
pip install numpy
pip install networkx
pip install pyinstaller

The one thing you must do is modify the test_sahs_qct.spec file, changing the file path to path on your computer

a = Analysis(['test_sahs_qct.py',

Use pyinstaller to get .exe

pyinstaller test_sahs_qct.spec
cp ./dist/route ${ISQ_ROOT}/bin/
cuda-plugin (optional)

This plugin is used to simulate with gpu and it is optinal. When you need use this plugin, you may install cuda env first, and then use makefile to install plugin

cd ${ISQ_ROOT}/simulator/plugins/cuda-plugin
cp ./libqsim_kernel.so /usr/lib/

Another thing you need to do is add cuda to profile ${ISQ_ROOT}/simulator/Cargo.toml

default = ["qcis"]
none = []

default = ["cuda", "qcis"]
none = []

install isQ

Now, you can use makefile to install isQ

cd ${ISQ_ROOT}
export PATH=${ISQ_ROOT}/bin:$PATH


You can use isQ’s run command to compile and run quantum programs

isqc run <Input>


The isQ compiler receives the isQ source file as input, and the instruction format is as follows:

isqc compile [options] <Input>


  • --emit <FORMAT> : output content format, format value can be mlir, mlirqir, llvm, mlir-optimized, binary, out [default: out]
  • -o, --output <OUTFILE> : output file
  • -O, --opt-level <OPT_LEVEL> : llvm opt-level such as -O1, -O2, -O3 etc.
  • --target <TARGET_IR> : target ir, now support qir, open-qasm3, qcis [default: qir]
  • --qcis-config <MAPPING_CONFIG_FILE> : qcis mapping config file

You can compile isQ source file to qir or qcis use follow command:

# compile to qir, default output file is source.so
isqc compile source.isq
# compile to qcis, default output file is source.qcis
isqc compile --target qcis --qcis-config MAPPING_CONFIG_FILE source.isq

Qcis instructions can run on real superconducting hardware, so isQ compiler provides qubit-mapping function. You should feed mapping_config_file like above. The file content needs to include the following fields:

// required
    "qbit_num": 12, // qubit number on hardware
    "topo": [[1,2],[2,3],[3,4],[4,5],[5,6],[6,7],[7,8],[8,9],[9,10],[10,11],[11,12]], // topology of hardware
// option 
    "init_map": "simulated_annealing" // the way to get init mapping

Of course, you can get the intermediate results of compilation by using --emit like that:

# compile to mlir, default output file is source.mlir
isqc compile --emit mlir source.isq
# compile to llvm(qir), default output file is source.ll
isqc compile --emit llvm source.isq


The simulator of isQ provides the simulation of qir. The input must be a .so file generated by compiler. There is only one option --cuda <CUDA> which use gpu for simulation. For example:

# simulate in cpu
isqc simulate ./source.so
# simulate in gpu
isqc simulate --cuda 10 ./source.so

The output is the print value in source.isq. Note that isQ simulator only simulate the circuit one time, so you may write a simple script to get multiple simulation results.

<script type="text/javascript" id="MathJax-script" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.0.0/es5/tex-mml-chtml.js"> </script> <script> MathJax = { tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] } }; </script> <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"> </script>
MIT License Copyright (c) 2023 arclightquantum Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


a part of quantum software toolkit of Institute of Software, Chinese Academy of Science expand collapse
C++ and 6 more languages


No release




Load More
can not load any more
马建仓 AI 助手


344bd9b3 5694891 D2dac590 5694891