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

Go to the Python examples folder in the image: cd /mnt/qb/qristal/examples/python
Run example qsim_noisy.py using python3 qsim_noisy.py. You should get the output:

{'110': 1024}

Install the text editor nano to edit the noise properties using apt install nano.
Open qsim_noisy.py with the text editor nano using nano qsim_noisy.py

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

```
s.noise = True
```

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

Exit the text editor by hitting Ctrl + x, then enter y to save changes, then hit Enter.
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}

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

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

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
}

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

Launch Jupyter Lab by opening up your browser and typing in the navigator localhost:8889.
Make a new notebook, and try executing one of the python examples in it.
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.