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).

Install

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.

requirements

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

python-routing-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',
            'front_circuit.py',
            'YOUR_PATH/cir_gen/interface.py',
            'YOUR_PATH/multi_objectives/init_mapping/get_init_map.py',
            'YOUR_PATH/multi_objectives/init_mapping/sa_mapping.py',
            'YOUR_PATH/multi_objectives/sahs/sahs_search.py',
            ],
             pathex=["YOUR_PATH/multi_objectives"],

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
make
cp ./libqsim_kernel.so /usr/lib/

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

#before
[features]
default = ["qcis"]
none = []

#after
[features]
default = ["cuda", "qcis"]
none = []

install isQ

Now, you can use makefile to install isQ

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

Run

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

isqc run <Input>

Compile

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

isqc compile [options] <Input>

options:

• --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

Simulate

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.