Merge pull request #33 from DiCarloLab-Delft/develop

Merging for release 0.2

.gitignore

@@ -2,6 +2,7 @@ build
 cbuild
 dist
 openql.egg-info
+lab
 
 *.dot
 *.qc
@@ -14,3 +15,4 @@ openql.egg-info
 *.pyc
 *.cache
 openql/openql.py
+*/test_output/*

CMakeLists.txt

@@ -38,17 +38,17 @@ INCLUDE_DIRECTORIES(
 )
 
 IF(CMAKE_COMPILER_IS_GNUCXX)
-  SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3 -Wall -Wfatal-errors ")
-  SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -std=c++11 -Wall -Wfatal-errors")
+  SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3 -Wall -Wfatal-errors -ggdb")
+  SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -std=c++11 -Wall -Wfatal-errors -ggdb")
 ENDIF(CMAKE_COMPILER_IS_GNUCXX)
 
 IF(MSVC)
 SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /std:c++11")
 ENDIF(MSVC)
 
 IF("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
-  SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3 -Wall -Wfatal-errors ")
-  SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -std=c++11 -Wall -Wfatal-errors -Wno-unused-local-typedef")
+  SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3 -Wall -Wfatal-errors -ggdb")
+  SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -std=c++11 -Wall -Wfatal-errors -Wno-unused-local-typedef -ggdb")
 ENDIF("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
 
 ADD_SUBDIRECTORY(programs)

README.md

@@ -7,7 +7,6 @@ for various target platforms. While the microcode is platform-specific, the
 quantum assembly code (qasm) is hardware-agnostic and can be simulated on the
 QX simulator.
 
-
 ## Supported Patforms
 
 * Linux
@@ -26,59 +25,76 @@ QX simulator.
 * [Optional] XDot to visualize generated graphs in dot format
 
 
-# Installing OpenQL as Python Package
+# Getting started 
 
-## Linux & OSX
+After installing OpenQL (see install instructions below) a good place to get started is by looking at the files in the "tests" directory, e.g., test_basics.py. Here you can find commented examples on how to use OpenQL. 
 
-Running the following command in terminal should install the openql package:
+N.B. gates in OpenQL are *case insensitive*. 
 
-        python setup.py install --user
 
-Run `py.test -v` to test the installation  
 
-## Windows
+# Compiling C++ OpenQL tests and programs
 
-Python.exe and swig.exe should be in the path of power shell.
+Existing tests and programs can be compiled by the following instructions. You can use an existing example as a starting point and write your own programs. Make sure to include them in CMakeLists.txt file to inform cmake to compile it as well.
 
-Make sure the following variables are defined:
 
-* PYTHON\_INCLUDE (should point to the directory containing Python.h)
-* PYTHON\_LIB (should point to the python library python35.lib)
+## Linux/OSX
+    mkdir cbuild 
+    cd OpenQL/cbuild 
+    cmake ..   # generates the make file based on CMakeLists.txt in the OpenQL directory
+    make       # compiles the source code into the current directory. 
 
-Then running the following command in power shell should install the openql package:
+To execute an example program go to e.g., `OpenQL/cbuild/programs` and execute one of the files e.g.,  `./simple`. The output will be saved to the output directory next to the file.
 
-        python setup.py install
+If one wants to compile and run a single file, e.g., `example.cc`, to compile it one can run : 
+```
+    mkdir output           # create an output directory if it does not exist
+    g++ -std=c++11 example.cc -o example.exe -I OpenQL/   # compile the file
+    ./example.exe                                         # execute the file
+```
 
-Run `py.test -v` to test the installation  
+## Windows
+    cd OpenQL/cbuild
+    cmake -G "NMake Makefiles" ..
+    nmake
 
 
-# Compiling C++ OpenQL tests and programs
+## Usage
+
+Example C++ tests and programs can be found in 'tests' and 'programs'
+directories. Executables for these will be generated in 'build/tests' and 'build/programs'
+directory.
 
-Existing tests and programs can be compiled by the following instructions. You can
-use an existing example as a starting point and write your own programs. Make sure
-to include them in CMakeLists.txt file to inform cmake to compile it as well.
+Example python tests and programs can be found in the 'tests' and 'programs' directories.
+These can be executed as 'python tests/simplePyTest.py'.
+
+# Installing OpenQL as Python Package
+
+N.B. the instructions below will compile the C++ files the first time they are run. 
+If you are updating an existing installation you should first clean and recompile the C++ files using the following command. 
+```
+    rm -rf cbuild       # delete the old build folder 
+```
+
+## Linux & OSX
 
-## Linux
+Running the following command in terminal should install the openql package:
 
-        mkdir cbuild
-        cd cbuild
-        cmake ..
-        make
+        pip install  -e .
+
+Run `py.test -v` to test the installation  
 
 ## Windows
 
-        mkdir cbuild
-        cd cbuild
-        cmake -G "NMake Makefiles" ..
-        nmake
+Python.exe and swig.exe should be in the path of power shell.
 
+Make sure the following variables are defined:
 
-## Usage
+* PYTHON\_INCLUDE (should point to the directory containing Python.h)
+* PYTHON\_LIB (should point to the python library python35.lib)
 
-Example C++ tests and programs can be found in 'tests' and 'programs'
-directories. Executables for these will be generated in 'build/tests' and 'build/programs'
-directory.
+Then running the following command in power shell should install the openql package:
 
-Example python tests and programs can be found in 'tests' and 'programs' directories.
-These can be executed as 'python tests/simplePyTest.py'.
+        pip install  -e .
 
+Run `py.test -v` to test the installation  

coding_style.md

@@ -0,0 +1,26 @@
+OpenQL C++ Coding Conventions
+=============================
+
+In order to maintain the code homogeneous and consistent, all contibutors are invited to follow this coding convetion.
+
+## Files Naming ##
+
+C++ source files should be named `.cc` 
+C++ header files should be named `.h`
+
+Files should be named all lower case and separated by `_` when composed of multiple words: 
+quantum_kernel, quantum_program, configuration_loader ...
+
+## Variable/Function Naming ##
+
+Use descriptive names, and be consistent in the style. Variable and class names should be all lower case and separated by `_` when composed of multiple words. 
+
+## Custom Types Definition ##
+
+When defining custom types using `typedef` , the type name should end with `_t` to distinguish it from instance and variable names.
+
+## Getter/Setter ##
+
+In the early developement phases of QpenQL, many attributes has been made public to speed up the developement and avoid writing getters/setters for the class attributes, obviously this not the proper way to code safely. From now on, add systematically getters/setters when defining private attributes and control setting with checks when needed.
+
+

configuration_specification.md

@@ -1,6 +1,6 @@
 ## Specifying experimental configuration
 
-The goal of the config is to specify the information required to convert operations to qumis instructions.  It should be emphasized that flexibility and extensibility of this format is a driving requirement.  The config is specified in JSON and contains a nested dictionary with the required information for **every** allowed operation including it's arguments.  If there is no entry in the configuration for a specific operation with it's arguments then it is not allowed.  There is a different entry in the configuration for different arguments of the same function: e.g., `X180(q0)` and `X180(q1)` would be two distinct entries in the config. In addition to the configuration entries there are several globally defined parameters. 
+The goal of the config is to specify the information required by the compiler which compile user-defined C++ or Python program into 1) QISA instructions with corresponding microcode for CC-Light, or 2) qumis instructions for CBox_v3. It should be emphasized that flexibility and extensibility of this format is a driving requirement.  The config is specified in JSON and contains a nested dictionary with the required information for **every** allowed operation including it's arguments.  If there is no entry in the configuration for a specific operation with it's arguments then it is not allowed.  There is a different entry in the configuration for different arguments of the same function: e.g., `X180(q0)` and `X180(q1)` would be two distinct entries in the config. In addition to the configuration entries there are several globally defined parameters.
 
 ## Globally defined parameters
 
@@ -18,29 +18,30 @@ The goal of the config is to specify the information required to convert operati
 - `RO_RO_buffer` (int) : buffer between pulses of type RO and RO in ns
 
 ## Configuration entries
-Entries are either an `alias` or a full entry. 
+Entries are either an `alias` or a full entry.
 
 `entry` (str) : unique id for the operation with arguments formatted as `op_name(arg1, ..., argN)`
 
 - `alias` entries only contain one item:
     + `alias` (str) : name of operation +args it is an alias of
-- full entries contain the following pieces of information 
+- full entries contain the following pieces of information
     + `duration` (int) : duration of the operation in ns
     + `latency` (int): latency of operation in ns
     + `qubits` (list) : what qubits this operation affects (can be empty list)
+    + `type`: one of either `MW`, `Flux`, `RO`, `None`.
     + `matrix` (matrix): the process matrix, can be an empty matrix.
     + 'disable_optimization' (bool): if this is True this operation cannot be compiled away. 
     + type (str): one of either `MW`, `Flux`, `RO`, `None`
     + `qumis_instr` (str): one of `wait`, `pulse`, `trigger`, `CW_trigger`, `dummy`, `measure`.
     + `qumis_instr_kw` (dict): dictionary containing keyword arguments for the qumis instruction. 
 
-## Qumis instruction 
+## CBox_v3 instuction configuration
 OpenQL supports the following instructions
 
-- `wait` 
+- `wait`
     + time (int): time to wait in ns, must be multiple of `cycle_time`
 - `pulse` plays a waveform from one of the internal AWG's
-    + awg_nr (int): index specifying the awg to play the pulse on 
+    + awg_nr (int): index specifying the awg to play the pulse on
     + lut_idx (int) : index of the lookuptable that stores the waveform
 - `trigger` : raises a trigger for a specified time
     + `trigger_bit` (int) : trigger_bit
@@ -54,22 +55,83 @@ OpenQL supports the following instructions
 - `dummy` blocks the qubit for the duration specified but executes no instruction
     + no arguments
 - `measure`
-    + N.B. the measure instruction does not have a duration
+    + no arguments
+
+## CC-Light instuction configuration
+Every quantum operation (QISA instruction) is translated into one or multiple microinstructions. For the first release of CC-Light, only one microinstruction is supported. It should contain the following information:
+
+- `name` (str):  the name of the operation in the program.
+- `physical qubits` (int): the address of targeted physical qubits. A list containing up to two integers ranging from 0 to 6. Can be empty. See appendix for more details.
+- `type`: (int): 0 for single-qubit gates, 1 for two-qubit gates.
+- `op_left type`: one of either `MW`, `Flux`, `RO`, `None`.
+- `op_left` (int): 0\~255 for MW, 0\~7 for flux. Otherwise omiited.
+- `lut_idx` (int) : index of the lookuptable that stores the waveform.
+- `op_right type`: one of either `MW`, `Flux`, `RO`, `None`.
+- `op_right` (int): 0\~255 for MW, 0\~7 for flux. Otherwise omiited.
+- `lut_idx` (int) : index of the lookuptable that stores the waveform.
+
 
 ## Potential extensibility and current flaws
 
 - **New qumis instructions** will be needed as hardware changes (e.g., vector switch matrix) or to support different platforms (spin-qubits, NV-centers, etc). This should not affect the structure of this config but will change the content in the future.
 - **Classical logic** is not specified in this document but does relate to the underlying qumis instructions, e.g, operations conditional on measurement outcomes.
-- **Composite qumis instructions**. In the current proposal it is not possible to specify composite qumis instructions even though there is a clear potential for this. An example would be quickly putting a copy of a pulse on a different channel or triggering a scope. 
+- **Composite qumis instructions**. In the current proposal it is not possible to specify composite qumis instructions even though there is a clear potential for this. An example would be quickly putting a copy of a pulse on a different channel or triggering a scope.
 - The format is flattened out completely, not taking use of any structure in the configuration. This is on purpose.
 
 ## Example use of aliases
 
 - CZ(q0, q1) -> CZ(q1, q0)
 - CZ_11(q0, q1) -> CZ_11(q1, q0)
-- CZ_01(q0, q1) -> CZ_10(q1, q0) 
+- CZ_01(q0, q1) -> CZ_10(q1, q0)
 
 - X180(q0) -> X(q0)
 - X180(q0) -> rX180(q0)
 
 
+
+## Appendix: Device channel to qubit mapping
+A mapping is required to map the user-defined qubit name into a physical qubit address. The physical qubit address and the directed edge address are defined in the following figure and table:
+
+![Qubit and edge number definition](qubit_number.png)
+
+| edge address| left qubit address | right qubit address|
+|----|:------:|:------------:|
+|0   |   2    | 0 |
+|1   |   0    | 3 |
+|2   |   3    | 1 |
+|3   |   1    | 4 |
+|4   |   2    | 5 |
+|5   |   5    | 3 |
+|6   |   3    | 6 |
+|7   |   6    | 4 |
+|8   |   0    | 2 |
+|9   |   3    | 0 |
+|10  |   1    | 3 |
+|11  |   4    | 1 |
+|12  |   5    | 2 |
+|13  |   3    | 5 |
+|14  |   6    | 3 |
+|15  |   4    | 6 |
+
+
+In the CC-Light architecture, the following connection is suppoed:
+
+| Device Name | DIO connector | Target qubits | Operation Type|
+|-------------------|:----:|:--------------:|-------------|
+|UHFQC-0            | DIO1 | 0, 2, 3, 5, 6  | measurement |
+|UHFQC-1            | DIO2 |   1, 4         | measurement |
+|AWG-8 0, channel 0~6 | DIO3 |   0~6          | flux |
+|AWG-8 1, channel 0 | DIO4 |   0,1          | microwave |
+|AWG-8 1, channel 1 | DIO4 |   5,6          | microwave |
+|AWG-8 2, channel 0 | DIO5 |   2,3,4        | microwave |
+|VSM                |  -   |   0~6          | microwave masking |
+
+### Potential change requirements & Solutions
+- The user would like to use AWG-8 2, instead of AWG-8 1 to drive qubit 5,6.
+  + Solution: Switch the DIO connection of AWG-8 1 and 2.
+- How address a single qubit?
+  + Solution: For MW, use VSM to shield other qubits. For flux, only activiate the channel for that qubit. For measurement, only generate the trigger bit for that qubit. If the program is written for a single qubit, then it can be automatically done.
+- How to use the same program to address two different qubits in two experiments?
+  + Solution: Change the qubit mapping in the config file. For example, the first experiment, the qubit name "target_qubit" is mapped to physical qubit address 0, and in the second experiment, change this mapping to physical qubit 1.
+- Is it possible to only change the flux channel 1 and 4 for qubit 1 and 4, respectively, while not affecting the MW channel?
+  + This is not allowed by CC-Light.

contributors

@@ -1,7 +1,23 @@
 
-Main author: OpenQL has been created initially by Nader Khammassi.
+OpenQL framework has been created initially by Nader Khammassi.
+...
+
+
+Contributors:
+
+- Imran Ashraf 
+    Implemented ASAP/ALAP Gate Scheduling Algorithms
+    Created a Python Package for OpenQL
+    Setup CMake-based Compilation
+    ...
+
+- Adriaan Rol and Xiang Fu
+    Contributed to the Hardware Configuration Specification
+    Testing OpenQL on the Hardware
+    ...
+
+Note: please fill your contributions in this file...
 
-Other Contributors:
 -
 -
 -

openql/makefile

@@ -1,13 +1,14 @@
 SWIG=swig
 
-INCS= -I. -I/data/repositories/quantRepos/openql -I/opt/lemon/include -I/usr/include/python3.5
+INCS= -I..  -I. -I/usr/include/python3.5
 PYTHON=python3
 
 wrapper: openql.i
+	export MACOSX_DEPLOYMENT_TARGET="10.10"
 	$(SWIG) -c++ -python openql.i
 
 lib: wrapper
-	g++ -fpic $(INCS) -std=c++11 -c openql_wrap.cxx
+	g++ -fpic $(INCS) -std=c++11 -c openql_wrap.cxx -ggdb
 	g++ -shared openql_wrap.o -o _openql.so
 
 ptest: lib