qrmi-sampler

This is a standalone quantum workload container that submits a Qiskit Runtime SamplerV2 job to an IBM backend via qrmi-go and prints the result. I made it to prototype with fluence), which will decide which quantum backend to run on. This application has a dependency on qrmi-go.

How it works

The container reads its configuration from the environment, submits the sampler input to the backend in job mode (a single job, no session — which is what the IBM open plan allows, and that is what I have), polls to completion, and prints the serialized result.

Variable	Meaning	Required
IBM_CLOUD_TOKEN	IBM Cloud IAM API key	yes
IBM_CLOUD_CRN	Qiskit Runtime service instance CRN	yes
QRMI_BACKEND	backend to submit to, e.g. ibm_fez	yes
QRMI_SAMPLER_INPUT	path to a params-only SamplerV2 JSON	no (default /etc/sampler/sampler_input.json)
QRMI_EXECUTION_MODE	job (default) or session (paid plans)	no
QRMI_JOB_TIMEOUT	overall timeout, e.g. 15m	no

The image bundles a tiny default job (testdata/sampler_input.json, a single-qubit sx + measure circuit that is ISA-valid on any IBM backend). To run a larger circuit, generate its params-only SamplerV2 input (e.g. with QRMI's gen_sampler_inputs.py), mount it, and point QRMI_SAMPLER_INPUT at it.

Build and run

I am doing this in the VSCode environment. It has Go, Rust, and the QRMI native library prebuilt, so make build and make test work out of the box.

go mod tidy
make build      # needs the QRMI native library at /usr/local
make image      # container image
make test       # pure-Go unit tests (no native library needed)

Locally:

curl -fsSL https://clis.cloud.ibm.com/install/linux | sudo sh
export IBM_CLOUD_TOKEN=<key>
ibmcloud login --apikey $IBM_CLOUD_TOKEN
# 12 for us-east

export QRMI_BACKEND=ibm_fez 
export QRMI_TEST_BACKEND=ibm_fez 
export QRMI_TEST_TYPE=qiskit-runtime-service
export IBM_CLOUD_CRN=$(ibmcloud resource service-instances --service-name quantum-computing --output json | jq -r '.[] | {name: .name, crn: .crn}' | jq -r .crn)
make run

CGO_ENABLED=1 CGO_CFLAGS="-I/usr/local/include" CGO_LDFLAGS="-L/usr/local/lib" \
  go build -tags cgo_qrmi -o bin/qrmi-sampler .
QRMI_SAMPLER_INPUT=testdata/sampler_input.json ./bin/qrmi-sampler
2026/06/06 02:58:14 submitting sampler job to ibm_fez
{"results": [{"data": {"c": {"samples": ["0x1", "0x0", "0x0", "0x0", "0x0", "0x1", "0x1", "0x1", "0x0", "0x0", "0x1", "0x0", "0x1", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x0", "0x1", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x0", "0x0", "0x0", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x1", "0x1", "0x0", "0x0", "0x1", "0x1", "0x1", "0x1", "0x0", "0x1", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x0", "0x1", "0x0", "0x1", "0x1", "0x0", "0x0", "0x1", "0x1", "0x1", "0x1", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x1", "0x0", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x1", "0x0", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x1", "0x1", "0x0", "0x1", "0x1", "0x1", "0x1", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x1", "0x1", "0x1", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x0", "0x0", "0x0", "0x1", "0x0", "0x0", "0x1", "0x0", "0x0", "0x1", "0x1", "0x0", "0x1", "0x1", "0x1", "0x0", "0x1", "0x0", "0x1", "0x1", "0x0", "0x0", "0x0", "0x0", "0x0", "0x0", "0x1", "0x1", "0x1", "0x0", "0x1", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x0", "0x1", "0x0", "0x0", "0x1", "0x0", "0x0", "0x0", "0x1", "0x0", "0x0", "0x1", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x0", "0x1", "0x1", "0x0", "0x0", "0x1", "0x1", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x1", "0x0", "0x0", "0x1", "0x1", "0x1", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x0", "0x1", "0x1", "0x0", "0x0", "0x0", "0x0", "0x1", "0x1", "0x1", "0x0", "0x0", "0x0", "0x1", "0x0", "0x0", "0x1", "0x0", "0x0", "0x1", "0x1", "0x1", "0x0", "0x1", "0x0", "0x1", "0x1", "0x0", "0x0", "0x1", "0x1", "0x1", "0x1", "0x1", "0x0", "0x1", "0x1", "0x1", "0x0", "0x1", "0x0", "0x0", "0x0", "0x1", "0x1", "0x0", "0x0", "0x1", "0x0", "0x0"], "num_bits": 1}}, "metadata": {"circuit_metadata": {}}}], "metadata": {"execution": {"execution_spans": [[{"date": "2026-06-06T02:58:19.133117"}, {"date": "2026-06-06T02:58:22.937346"}, {"0": [[256], [0, 1], [0, 256]]}]]}, "version": 2}}
2026/06/06 02:58:25 done: 2070 bytes from ibm_fez

Boum!

The above image is built via Github actions and published to ghcr.io/converged-computing/qrmi-sampler.

On Kubernetes

Deploy as an ordinary pod and let your scheduler place it. Provide the IBM credentials via a Secret:

kubectl create secret generic ibm-quantum -n default \
  --from-literal=token='YOUR_IAM_API_KEY' \
  --from-literal=crn='crn:v1:bluemix:...'

apiVersion: v1
kind: Pod
metadata:
  name: sampler
spec:
  schedulerName: fluence          # whichever scheduler decides the backend
  restartPolicy: Never
  containers:
    - name: sampler
      image: ghcr.io/converged-computing/qrmi-sampler:latest
      env:
        - name: IBM_CLOUD_TOKEN
          valueFrom: {secretKeyRef: {name: ibm-quantum, key: token}}
        - name: IBM_CLOUD_CRN
          valueFrom: {secretKeyRef: {name: ibm-quantum, key: crn}}
        - name: QRMI_BACKEND
          value: "ibm_fez"

License

HPCIC DevTools is distributed under the terms of the MIT license. All new contributions must be made under this license.

See LICENSE, COPYRIGHT, and NOTICE for details.

SPDX-License-Identifier: MIT

LLNL-CODE-842614