Getting started

Quickstart

The fastest way to get a working Qristal installation is to run it directly from the provided Docker image.

To learn how to use Qristal, let’s run a simple Python example to create a Bell state.

The Bell state is the simplest example of a maximally entangled state, and comprises just 2 qubits. These 2 qubits contribute a Hilbert space of dimension 4. In the qubit basis \(\ket{0}\) and \(\ket{1}\), these four components are written as

\[ \ket{\Phi^+} = \frac{\ket{00} + \ket{11}}{\sqrt{2}} , \]
\[ \ket{\Phi^-} = \frac{\ket{00} - \ket{11}}{\sqrt{2}} , \]
\[ \ket{\Psi^+} = \frac{\ket{01} + \ket{10}}{\sqrt{2}} , \]
\[ \ket{\Psi^-} = \frac{\ket{01} - \ket{10}}{\sqrt{2}} . \]

A Bell state can be constructed through the application of simple gates such as the Hadamard, X, Z and CNOT gates. Each of the above components are created through their respective circuit:

Circuit to create \(\ket{\Phi^+}\):

Circuit to create \(\ket{\Phi^-}\):

Circuit to create \(\ket{\Psi^+}\):

Circuit to create \(\ket{\Psi^-}\):

Now let’s code up the circuit to generate \(\ket{\Phi^+}\).

Import the Qristal core:

import qb.core

Create a quantum computing session using Qristal:

my_sim = qb.core.session()

Choose some default session parameters:

my_sim.qb12()

Set the number of shots to run through the circuit:

my_sim.sn = 1024

Set the number of qubits:

my_sim.qn = 2

Choose the simulator backend:

my_sim.acc = "qpp"

Create the \(\ket{\Phi^+}\) component of the Bell state using Hadamard and CNOT gates:

my_sim.instring = '''
__qpu__ void MY_QUANTUM_CIRCUIT(qreg q)
{
  OPENQASM 2.0;
  include "qelib1.inc";
  creg c[2];
  h q[0];
  cx q[0], q[1];
  measure q[0] -> c[0];
  measure q[1] -> c[1];
}
'''

Run the circuit:

my_sim.run()

Print the cumulative results in each of the classical registers:

print(my_sim.out_raw[0][0])

Installation

Qristal can either be run directly from the provided Docker image, or installed from source. This section provides instructions for working with the source. If using Windows Subsystem for Linux 2, ensure you have Docker Desktop installed on Windows and not under your Linux distribution, as it allows Docker to use WSL2 as a backend.

Dependencies

Installing Qristal from source requires the following libraries/packages to be installed:

Also, note that Qristal will be built with support for CUDA Quantum if and only if cmake detects that your system has a compatible CUDA Quantum installation. A shortcut is to run Qristal directly from the Docker image that we provide with a compatible version of CUDA Quantum already installed.

Additional dependencies that can be installed automatically at build time:

Note

Automatic dependency installation

It is highly recommended that users let the Qristal build system install the additional dependencies mentioned above, by setting the -DINSTALL_MISSING=ON CMake option.

Installing from source

  1. For development purposes, it is recommended to install Qristal using automatic dependency installation mode.

git clone https://github.com/qbrilliance/qristal.git qristal
cd qristal
mkdir build && cd build
cmake .. -DINSTALL_MISSING=ON
make install

-The -DINSTALL_MISSING=ON flag ensures that all missing dependencies (if any) will be downloaded and installed automatically. To automatically download and install only C++ dependencies, instead set -DINSTALL_MISSING=CXX. To download and install only Python module dependencies, use -DINSTALL_MISSING=PYTHON.

The required dependencies must be installed on your system. -DINSTALL_MISSING=ON will not handle those mandatory dependencies.

  1. Other useful cmake options

The directory into which Qristal is to be installed can be specified by setting -DCMAKE_INSTALL_PREFIX=<YOUR QRISTAL INSTALLATION DIR>.

If you wish to build Qristal’s C++ noise-aware circuit placement routines, you must also enable the use of the additional dependency TKET. This is done by passing -DWITH_TKET=ON to cmake. TKET will be installed automatically by cmake if both -DWITH_TKET=ON and -DINSTALL_MISSING=ON (or -DINSTALL_MISSING=CXX) are passed to cmake.

MPI is enabled by adding the option -DENABLE_MPI=ON.

If you also wish to build this html documentation, pass -DBUILD_DOCS=ON.

  1. Manual Installation of additional dependencies (Advanced alternative to step 1)

cmake .. -DXACC_DIR=<YOUR XACC INSTALLATION DIR> -DEXATN_DIR=<YOUR EXATN INSTALLATION DIR> -DTNQVM_DIR=<YOUR TNQVM INSTALLATION DIR>

In this manual mode, the build system will check for a specific version of XACC, EXATN and TNQVM as provided. If not satisfied, it will terminate the build and ask for a reinstallation of the dependency. Please follow the error message to install the correct version (specified as a git commit hash key).

Similarly, if building with noise-aware placement routines enabled using -DWITH_TKET=ON, you can pass -DWITH_TKET=ON -DTKET_DIR=<YOUR TKET INSTALLATION DIR> to cmake to tell it to use your own installation of TKET rather than building TKET from source.

Contributing

There are many ways in which you can contribute to Qristal, whether by contributing some code or by engaging in discussions; we value contributions in all shapes and sizes!

Here are some ideas for how you can get involved.

Asking Questions

Have a question? Some concepts are hard-to-understand?

Please feel free to file an issue to ask your questions here.

Your question will serve as resource to others searching for help.

Reporting and Discussing Issues

If you have feedback about Qristal, please let us know by filing a new issue!

When filing a bug report, please follow the below template:

# [Title]
A concise but specific description of the bug.

### Steps to reproduce
Describe what needs to be done to reproduce the faulty behavior.

### Resulting and expected behavior
A brief description of what you expected and what you actually got.

### Self help
If you found a workaround or tried to fix the bug yourself, please provide your attempt here.

### Technical output
If available, provide a traceback, logs or similar. Console output is helpful here.

### Screenshot
If applicable and helpful, provide a screenshot.

### System information and environment
- Software version:
- Operating system:

We also encourage you to look at the list of currently open issues to share your ideas and expertise.

Contributing Code

Before submitting a new pull request, please make sure to do the following:

  • Include a unit test for any new routines or features. If you’ve fixed a bug or added code that should be tested, add a test to the tests directory.

  • Ensure that the test suite passes, e.g., by running the CITests executable. This will also be checked by our CI when the MR is submitted.

  • Fix (not suppress) any warnings generated by your changes. You can turn warnings on in the code by passing -DWARNINGS=ON to cmake.

When ready, submit your fork as a pull request to the QB GitHub repository, filling out the pull request form.

  • When describing the pull request, please include as much detail as possible regarding the changes made/new features added/performance improvements. If including any bug fixes, mention the issue numbers associated with the bugs.

  • Once you have submitted the pull request, the CI pipeline will automatically run to ensure that all tests continue to pass.

We may ask for changes to a pull request if it requires more documentation or unit tests to better make use of it.

Last but not least, thank you for taking the time to contribute.

Emulator

Qristal Emulator Getting Started Guide

1. Check that your system meets minimum requirements

  • 16 GB RAM

  • x86 processor

  • A working Linux system. Windows Subsystem for Linux 2 (WSL) is fine.

2. Install Docker

Instructions for installing Docker can be found here. You only need the Engine, not the Desktop.

If you have NVIDIA GPUs on your system and want to use them, you will also need to install the NVIDIA Container Toolkit.

3. Log in to the Gitlab Docker registry

Open a terminal and run:

sudo docker login -u XXXX registry.gitlab.com

where XXXX is replaced with your Gitlab username. Depending on your Gitlab authentication settings, you may need to work through getting a token and/or setting up two-factor authentication. If you have trouble, please refer to this guide.

4. Get the Qristal Emulator Image

In a terminal, run:

sudo docker run --rm -it --name emulator registry.gitlab.com/qbau/software-and-apps/public-restricted/emulator/qristal-emulator

If you have NVIDIA GPUs on your system and want to use them, insert --gpus all after run in the command above.

5. Activate the image using your license key

At the command prompt inside the image, run the following commands, replacing XXXXX-XXXXX-XXXXX-XXXXX with the license key that you have received from Quantum Brilliance:

mkdir /qb
echo -e '{\n  "isFloatingLicense": true,\n  "LicenseKey": "XXXXX-XXXXX-XXXXX-XXXXX"\n}' > /qb/QB-Emulator-License.json

6. Test that your image is successfully activated

Navigate to the Python examples folder in the image

cd /mnt/qb/qristal/examples/python

Run a simple example that uses a noise model. First, using a noise model that is built into the open-source version of Qristal and does not require an emulator license:

python3 noise_model.py

Next, retry the example using a noise model imported from the emulator:

python3 noise_model.py --qdk

You should see something similar to the following:

Running in virtual machine: enforcing floating license!

Retrieving license-key and floating-setting from json file: /qb/QB-Emulator-License.json
{
    "LicenseKey": "XXXXX-XXXXX-XXXXX-XXXXX",
    "isFloatingLicense": true
}
Provided floating license, key: XXXXX-XXXXX-XXXXX-XXXXX, productID: 20053 and machine code: floating-7943610145998300972
Provided floating license, key: XXXXX-XXXXX-XXXXX-XXXXX, productID: 20053 and machine code: floating-7943610145998300972
{
    "00": 274,
    "01": 247,
    "10": 234,
    "11": 269
}

7. Run some other examples

  1. Go to the Python examples folder in the image: cd /mnt/qb/qristal/examples/python

  2. Run example qsim_noisy.py using python3 qsim_noisy.py. You should get the output:

{'110': 1024}

  1. Install the text editor nano to edit the noise properties using apt install nano.

  2. Open qsim_noisy.py with the text editor nano using nano qsim_noisy.py

  3. Within the text editor, turn on noise properties by uncommenting lines

    • s.noise = True

    • s.noise_model = qb.core.NoiseModel("qb-nm1", n_qbits)

  4. Exit the text editor by hitting Ctrl + x, then enter y to save changes, then hit Enter.

  5. Rerun the example using the same command python3 qsim_noisy.py. You should see something similar to this output:

Running in virtual machine: enforcing floating license!

Retrieving license-key and floating-setting from json file: /qb/QB-Emulator-License.json
{
    "LicenseKey": "XXXXX-XXXXX-XXXXX-XXXXX",
    "isFloatingLicense": true
}
Provided floating license, key: XXXXX-XXXXX-XXXXX-XXXXX, productID: 20053 and machine code: floating-5076244496556924759
Provided floating license, key: XXXXX-XXXXX-XXXXX-XXXXX, productID: 20053 and machine code: floating-5076244496556924759
{'000': 1, '010': 18, '100': 7, '110': 982, '111': 16}

  1. Try out a C++ example with CUDA Quantum. Navigate to the example folder:

cd /mnt/qb/qristal/examples/cpp/benchmark1_cudaq/

  1. Build and run the example:

mkdir build
cd build
cmake ..
make
./benchmark1_cudaq

You should get results that look similar to this:

Executing C++ demo...
About to run quantum program...
Results:
{
    "00000000000000000000": 10038,
    "11111111111111111111": 9962
}

  1. Try out some of the other examples in /mnt/qb/qristal/examples. Note that a few of these (e.g. cudaq_qft) use simulators that only work with GPUs, so if you’re not running with GPUs these particular examples won’t execute.

8. Test out the Jupyter Lab interface, and try the exercise

  1. Launch Jupyter Lab by opening up your browser and typing in the navigator localhost:8889.

  2. Make a new notebook, and try executing one of the python examples in it.

  3. Open /mnt/qb/qristal/exercises/QB_Qristal_Challenge/QB_Qristal_Challenge.ipynb inside Jupyter Lab, and see if you can solve the problems there! If you struggle, you can find solutions in the same directory.

9. Write your own quantum programs!

We’d love to hear how you get on – let your sales contact know!

10. Known issues

The following are known issues under active development:

  • Tensor network backends qb-mps, qb-purification and qb-mpdo should only be used with placement turned on (session.noplacement=False) and with TKET support for Qristal installed (WITH_TKET=ON at cmake time; customer images are shipped with Qristal already compiled this way).

  • Even with placement turned on, qb-mps, qb-purification and qb-mpdo will fail for some circuits if noise modelling is turned on and used with QPU topologies that include connections between qubits with non-sequential indices. The noise model nm-3 is designed to be safe from this problem.