Sample Code

The Quantum Origin SDK includes a set of sample source code. This code is designed to demonstrate how to interface programmatically with the Quantum Origin library using the SDK’s C API.

This page details the steps needed to build and run the sample code.

There are six sample programs, each of which interfaces to the Quantum Origin SDK C API. The sample code and build scripts for the sample code can be found at:

WindowsUbuntuRedHat

# User sample code location:
C:\Users\%username%\source\repos\quantum_origin_sdk\sample_code

# Master sample code location:
C:\Program Files\Quantinuum\quantum_origin_sdk\sample_code

Sample Applications

This section outlines each of the sample programs and their differences.

1. qosdk_sample_code_A_using_config_file.c

Demo that requests a block of randomness from the library, while also making use of the logging features. Parameters and configuration are supplied to the library via a config file: quantum_origin_config.yml.

2. qosdk_sample_code_B_using_setopt_api.c

Demo similar to the above, but supplies the configuration parameters directly to the library using the setopt functions.

3. qosdk_sample_code_C_minimal_get32bytes.c

Minimal application that retrieves a small amount of randomness

4. qosdk_sample_code_D_minimal_coinflip.c

Demo application that retrieves a small amount of randomness and then prints “HEADS” or “TAILS” based on the value of a single bit.

5. qosdk_sample_code_E_minimal_get32bytes_using_setopt_api.c

Similar to qosdk_sample_code_C_minimal_get32bytes.c above, but uses the API’s setopt functions to configure the system, rather than using a config file.

6. qosdk_sample_code_F_minimal_coinflip_using_setopt_api.c

Similar to qosdk_sample_code_D_minimal_coinflip.c above, but uses the API’s setopt functions to configure the system, rather than using a config file.

Prerequisites

To build the sample code for the Quantum Origin SDK, the following dependencies are must be present.

Build Library Dependencies

Each environment will require build and library dependencies to be installed. These are used by the Quantum Origin SDK and your local compiler to configure your system and enable the software to be built.

Windows:

For Windows we provide steps for building the sample code using Visual Studio. Follow instructions from Microsoft to install and configure this, located here: https://learn.microsoft.com/en-us/visualstudio/install/install-visual-studio

Ensure the C++ Desktop Development workload is installed, which contains the necessary cmake for Windows component.

Once installed, ensure you have a working python3 (>= 3.10) environment, which can be downloaded from here: https://www.python.org/downloads/windows/. Python is used, via pip, to download and install conan2 and additional build dependencies necessary for Windows.

The commands below can be run to configure the build environment for Windows.

Linux:

For Linux environments, a build environment must be available and include the GNU Compiler Collection (GCC). Version 9.4.0 (or later) is recommended when building the sample code for the Quantum Origin SDK. These dependencies can be installed using the apt or dnf package managers on your platform.

WindowsUbuntuRedHat

# This installs the conan package manager that manages the C++ dependencies for the SDK:
pip install conan

# This creates a default profile that the SDK will use to run conan:
conan profile detect

Install Quantum Origin SDK

The Quantum Origin SDK must be installed and loaded onto the system before continuing. Detailed instructions on how to install the Quantum Origin SDK into your environment can be found on the Installing the SDK page.

WindowsUbuntuRedHat

# Interactive Installer
C:\> quantum_origin_sdk_installer.exe

# Silent Installer
C:\> quantum_origin_sdk_installer.exe /S

License Files

The Quantum Origin SDK requires a customer-specific license code in order to operate. This license code is provided by Quantinuum and is an encrypted string of characters. This license code contains the proven quantum seed, generated by the Quantinuum Systems quantum computer along with metadata authorizing the use of the software.

Quantinuum will provide the license code for use with the SDK in two file formats.

quantum_origin_license.h

This C “header” file contains the license represented in hexadecimal format. This is used by some of the samples mentioned above that programmatically define the license code.

quantum_origin_config.yml

This configuration file contains various configuration items, including the license code represented in base64 format. This file is also used by some of the samples applications that rely on a configuration file to define the SDK’s capabilities.

Building and Running the Sample Code

Build the Sample Code

Follow the steps below to build the sample application for your platform.

With the required dependencies installed, the steps to required to build the sample code are as follows:

WindowsUbuntuRedHat

.. note::

    On Windows these instructions must be run in a Visual Studio Developer Command Prompt, not the default Windows cmd.exe prompt.

.. code-block:: powershell

    cd %USERPROFILE%\source\repos\quantum_origin_sdk\sample_code
    .\build_and_run_samplecode.bat build

Running the Sample Code

Note

The sample code directory also includes a script that will run all sample code executables.

• Windows: build_and_run_samplecode.bat run

• Linux: qosdk_samples_run.sh

Sample Code A:

WindowsUbuntuRedHat

call envvars.bat
.\build\bin\Release\qosdk_sample_code_A_using_config_file.exe .\quantum_origin_config.yml 32 --hex

[2025-07-29 10:58:32.992] [quantinuum_qo_logger] [warning] Logger already configured, dropping previous logger
[QuantumOrigin] WARNING: Logger already configured, dropping previous logger
RESULT [32 bytes]: 48 18 AE 97 1C 62 29 BA 87 1C 85 01 8D 43 47 DC 2E 8E 27 41 C8 09 2F CE 47 A2 63 57 74 28 02 54
INFO: WSR Callback Stats
INFO:     numberOfWsrRequests  : 0
INFO:     numberOfBytesSupplied: 0
INFO:     lastError            : 0
INFO: Logging Callback Stats
INFO:     numberOfLoggingRequests  : 1

Sample Code B:

WindowsUbuntuRedHat

call envvars.bat
.\build\bin\Release\qosdk_sample_code_B_using_setopt_api.exe 32 --hex

RESULT [32 bytes]: F0 17 E1 84 13 44 AC 09 7A 34 BB 9F CF CB 02 DA B9 8B 73 7C EB 2E B9 B4 55 79 FC 65 C8 B5 96 B9
INFO: WSR Callback Stats
INFO:     numberOfWsrRequests  : 5
INFO:     numberOfBytesSupplied: 26022
INFO:     lastError            : 0
INFO: Logging Callback Stats
INFO:     numberOfLoggingRequests  : 0

Sample Code C:

WindowsUbuntuRedHat

call envvars.bat
.\build\bin\Release\qosdk_sample_code_C_minimal_get32bytes.exe .\quantum_origin_config.yml

INFO: Number of bytes of randomness returned = 32
RESULT [32 bytes]: 81 D1 0B 69 C8 97 72 78 43 67 8B C7 C0 8E 46 1C B8 F5 02 75 5E C8 21 47 17 88 A9 5A C0 02 3D D8

Sample Code D:

WindowsUbuntuRedHat

call envvars.bat
.\build\bin\Release\qosdk_sample_code_D_minimal_coinflip.exe .\quantum_origin_config.yml

HEADS

Sample Code E:

WindowsUbuntuRedHat

call envvars.bat
.\build\bin\Release\qosdk_sample_code_E_minimal_get32bytes_using_setopt_api.exe --hex

INFO: Size of License Content = 8767
INFO: Number of bytes of randomness returned = 32
RESULT [32 bytes]: 92 B1 8F 22 7F B9 1F 60 60 1C D3 E6 17 51 47 23 28 85 7E 27 B5 E5 C3 9F 16 C7 9A 45 2B 3A 47 6C

Sample Code F:

WindowsUbuntuRedHat

call envvars.bat
.\build\bin\Release\qosdk_sample_code_F_minimal_coinflip_using_setopt_api.exe

INFO: Size of License Content = 8767
TAILS

Running the Sample Code on Docker

This section will covers the process of installing the Quantum Origin SDK into a Docker image so that an application can be run in a container. We will be using the sample code Linux binaries that were built in the Building the Sample Code section above.

The following three files are required:

• The Quantum Origin sample code binaries: We will use the Linux binaries that were built in the earlier Building the Sample Code section.

• A Quantum Origin configuration file, complete with license: This is needed for the samples that use the “ConfigFile” approach. Those that use the SetOptions approach have the license and other configuration options set directly in the code.

• The Quantum Origin Debian package: We will install the entire SDK into the docker container, even though for this section, we need only the runtime/redistributable - specifically the shared library.

There are three subdirectories referred to in the steps below:

• ~/quantum_origin_sdk_test/ - This is the temporary folder on the host system that was used to build the sample code Linux binaries in Building the Sample Code section above.

• ~/quantum_origin_sdk_docker/ - This is a new temporary folder on the host system used to gather the files needed to create the docker container.

• /qo_sdk/ - This is the working directory inside the Docker container.

Some lines will need to be modified to match your own system and product version. In particular, please substitute any occurrences of <version> with the actual version of the Quantum Origin SDK that you are using, e.g. 5.1.2.

In the following steps we will:

• Install Docker

• Create the Docker container

• Build the Docker container

• Run the Docker container

1. Install the Docker Engine: It is recommended that the Docker repositories and their corresponding instructions are used, both of which can be found on the Docker website: https://docs.docker.com/engine/install/

2. Copy the required files to ~/quantum_origin_sdk_docker/, substituting “<version>” with the actual version being used:

mkdir -p ~/quantum_origin_sdk_docker
cp -R /usr/share/doc/qosdk_sample_code ~/quantum_origin_sdk_docker/
cp ~/Downloads/libquantum_origin_sdk_<version>_amd64.deb ~/quantum_origin_sdk_docker/
cp ~/Downloads/quantum_origin_config.yml ~/quantum_origin_sdk_docker/
cp ~/Downloads/quantum_origin_license.h ~/quantum_origin_sdk_docker/
cd ~/quantum_origin_sdk_docker

3. Prepare the Docker container: Using a text editor, create the ~/quantum_origin_sdk_docker/Dockerfile as shown below.

 # Example Dockerfile...
 FROM ubuntu:22.04

 WORKDIR /qo_sdk

 # Copy the required files into Docker container...
 COPY qosdk_sample_code_C_minimal_get32bytes_shared .
 COPY quantum_origin_config.yml .
 COPY libquantum_origin_sdk_<version>_amd64.deb .
 COPY run_sample_code.sh .

 # Install the qosdk .deb into the Docker image...
 RUN dpkg -i libquantum_origin_sdk_<version>_amd64.deb

 # Run the run_sample_code.sh script which will request some randomness and prints it to the console (stdout)...
 CMD ["sh", "-c", "/qo_sdk/run_sample_code.sh"]

This example Dockerfile uses Ubuntu 22.04 LTS as its base operating system and will ultimately run the bash script that is created in the next step.
The script also copies the config file, and Debian package, into the container.

Make sure to change the version of the SDK to the actual filename from 'libquantum_origin_sdk_<version>_amd64.deb'.

4. Create the run_sample_code.sh file which is called when the container starts. The following example is specific to the sample code, which runs the sample code multiple (NN) times, before exiting.

#!/bin/bash

# This script runs the sample code multiple times, then exits.

NN=100  # Number of times to run the sample code
count=1
while [ $count -le $NN ]; do
    printf "[%4d] qo_onboard_sample_code_C_minimal_get32bytes TEST #$count:\n" $count
    /qo_sdk/qosdk_sample_code_C_minimal_get32bytes_shared /qo_sdk/quantum_origin_config.yml
    printf "\n"

    count=$((count+1))
    sleep 2
done

5. Check that the run_sample_code.sh script is executable by the container:

chmod +x ./run_sample_code.sh

6. Build the container:

sudo docker build ./ -t qosdk_sample_code

The output should be similar to the following:

[+] Building 5.2s (11/11) FINISHED                                        docker:default
=> [internal] load build definition from Dockerfile                                 0.1s
=> => transferring dockerfile: 654B                                                 0.0s
=> [internal] load metadata for docker.io/library/ubuntu:22.04                      1.2s
=> [internal] load .dockerignore                                                    0.0s
=> => transferring context: 2B                                                      0.0s
=> [1/6] FROM docker.io/library/ubuntu:22.04@sha256:<sha hash>                      3.0s
=> => resolve docker.io/library/ubuntu:22.04@sha256:<sha hash>                      0.0s
=> => sha256:<sha hash> 1.34kB / 1.34kB                                             0.0s
=> => sha256:<sha hash> 424B / 424B                                                 0.0s
=> => sha256:<sha hash> 2.30kB / 2.30kB                                             0.0s
=> => sha256:<sha hash> 29.54MB / 29.54MB                                           0.7s
=> => extracting sha256:<sha hash>                                                  1.9s
=> [internal] load build context                                                    0.0s
=> => transferring context: 1.52MB                                                  0.0s
=> [2/6] COPY run_sample_code.sh /qo_sdk                                            0.2s
=> [3/6] COPY qosdk_sample_code_C_minimal_get32bytes_shared    /qo_sdk              0.0s
=> [4/6] COPY quantum_origin_config.yml                        /qo_sdk              0.0s
=> [5/6] COPY libquantum_origin_sdk_3.2.2_amd64.deb            /qo_sdk              0.0s
=> [6/6] RUN dpkg -i /qo_sdk/libquantum_origin_sdk_3.2.2_amd64.deb                  0.4s
=> exporting to image                                                               0.1s
=> => exporting layers                                                              0.1s
=> => writing image sha256:<sha hash>                                               0.0s
=> => naming to docker.io/library/qosdk_sample_code                                 0.0s

7. Confirm that the built image works correctly.

The following command can be used to check that the qosdk_sample_code image is successfully installed:

sudo docker images

The output should be similar to the following:

REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
qosdk_sample_code   latest    c948eaf4c7df   23 seconds ago   83.3M

Then, run this qosdk_sample_code image using:

sudo docker run qosdk_sample_code

Depending on the value of NN (the default is 5), the sample code should produce output similar to that shown below:

[   1] qo_onboard_sample_code_C_minimal_get32bytes TEST #1:
INFO: Number of bytes of randomness returned = 32
RESULT [32 bytes]: 38 01 05 0B CF 2A 62 82 4E 5B E9 21 38 02 50 C5 8F 56 80 07 F6 21 74 43 6C 74 75 1E 34 DE B7 0D

...

[  NN] qo_onboard_sample_code_C_minimal_get32bytes TEST #NN:
INFO: Number of bytes of randomness returned = 32
RESULT [32 bytes]: 71 EF 6B 09 B8 26 86 28 1A 35 30 83 CD 2C F6 D4 77 EE 71 2D AB 83 6D B4 52 2F 1C 3B 19 9C E8 DD

The Docker container should then stop.

8. Remove old images

Remove old images from docker with:

sudo docker  rmi -f qosdk_sample_code

Running the Sample Code within a Nitro Enclave

This Docker container can also be made to run on an AWS Nitro Enclave. Ensure you are using a valid instance that supports Nitro Enclaves. Documentation for AWS Nitro Enclaves can be found online here: https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html

To run the Docker images and the Nitro Enclaves, ensure that all the necessary prerequisites as listed in the AWS documentation are installed.

The following steps will guide you through the process of running the above image inside a Nitro Enclave.

1. Prepare the Docker image to run on the Nitro Enclave by saving it to a file.

sudo docker image save -o ./qosdk_sample_code.img qosdk_sample_code:latest

2. Transfer this .img file to a valid EC2 instance that can run Nitro Enclaves:

scp ./qosdk_sample_code.img ec2-user@nitro-instance:

SSH into the EC2 instance and load the Docker image file. Then convert the Docker image into an Enclave Image File .eif:

sudo docker image load -i ./qosdk_sample_code.img
nitro-cli build-enclave --docker-uri qosdk_sample_code:latest --output-file qosdk_sample_code.eif

You should see an output similar to the following:

Start building the Enclave Image...
Using the locally available Docker image...
Enclave Image successfully created.
{
"Measurements": {
    "HashAlgorithm": "Sha384 { ... }",
    "PCR0": "7a8...06ea01103f12f7dd6",
    "PCR1": "034...f605946b3d8b0c6aa",
    "PCR2": "d8c...52ca720c6125ef185"
    }
}

3. We will now test that the Enclave Image File can run correctly. To do this we will start the Enclave in debug mode. In debug mode, certain arguments such as --cpu-count and --memory must be passed into the command as documented by AWS.

nitro-cli run-enclave --cpu-count 2 --memory 512 --enclave-cid 16 --eif-path ./qosdk_sample_code.eif --debug-mode

The output will be similar to the following. Ensure you note the Enclave ID as this is needed to connect to the debug console and check output.

Started enclave with enclave-cid: 16, memory: 512 MiB, cpu-ids: [1, 3]
{
"EnclaveName": "qosdk_sample_code",
"EnclaveID": "i-02caa57a57f38ca80-enc192435c9960bc4a",
"ProcessID": 2496,
"EnclaveCID": 16,
"NumberOfCPUs": 2,
"CPUIDs": [
    1,
    3
],
"MemoryMiB": 512
}

4. Now connect to the debug console:

nitro-cli console --enclave-id i-02caa57a57f38ca80-enc192435c9960bc4a

The output should be similar to the following:

Connecting to the console for enclave 16...
Successfully connected to the console.
0
[    0.180004] RSP: 0000:ffffc900000cbdb8 EFLAGS: 00010287
...
[   1] qo_onboard_sample_code_C_minimal_get32bytes TEST #1:
INFO: Number of bytes of randomness returned = 32
RESULT [32 bytes]: 6D 78 6E 7D 5C 66 C8 F6 53 97 88 83 F2 93 7E 41 61 06 71 DF D7 1A 8F 28 8D DA 70 0B 2B 9B 87 10
...