QStone

A utility to benchmark the quality of HPC and Quantum Computer integration.

Overview

QStone allows you to define a set of users for which configurable quantum applications will be randomly selected and executed. The benchmark generates different portable files (.tar.gz), each supporting different users and schedulers.

Currently supported quantum applications:

• VQE (Variational Quantum Eigensolver)
• PyMatching
• RB (Randomized Benchmarking)
• QBC (Quantum Binary Classifier)

Key features:

• Support for custom applications alongside core applications
• Multi-scheduler support (SLURM, LSF, bare metal)
• Detailed performance metrics collection
• Bottleneck and resource constraint analysis at the quantum-HPC interface

The benchmark operates under specific assumptions.

Why QStone?

Building appropriate hardware/software infrastructure for HPCQC requires significant effort. QStone enables a data-driven approach where you can measure performance, implement fixes, and measure again with every new version of quantum computers, software, and HPC hardware.

Supported Platforms

Platform	Architecture	OS
Apple Silicon	M1-M4	macOS
Intel	x86_64	Ubuntu
IBM Power	Power9	RedHat

Python versions: 3.10 - 3.12

Installation

Basic Installation

pip install QStone

Full Installation with MPI Support

First, install OpenMPI:

# Ubuntu/Debian
sudo apt install openmpi-bin openmpi-common libopenmpi-dev

# RedHat/CentOS/Fedora  
sudo yum install openmpi openmpi-devel

# macOS
brew install openmpi

Then install QStone with MPI support:

pip install QStone[mpi]

Usage

1. Generate Benchmark Suite

qstone generate -i config.json [--atomic/-a] [--scheduler/-s "slurm"/"jsrun"/"bare_metal"]

Options:

• --atomic / -a: Generate single-step jobs instead of three-phase jobs (pre/run/post)
• --scheduler / -s: Select output scheduler (default: bare_metal)

Supported schedulers: bare metal, Altair/FNC, SLURM/SchedMD

2. Execute Benchmark

qstone run -i scheduler.qstone.tar.gz [-o output_folder]

Alternative: Extract the tar.gz file and run manually:

tar -xzf scheduler.qstone.tar.gz
cd qstone_suite
sh qstone.sh

3. Profile Results

Single user:

qstone profile --cfg config.json --folder qstone_profile

Multiple users:

qstone profile --cfg config.json --folder qstone_profile --folder qstone_profile2

Configuration

Sample Configuration File

Create a config.json file with the following structure:

{
  "environment": { 
    "project_name": "my_quantum_project",
    "scheduling_mode": "LOCK",
    "job_count": 5,
    "qpu": {
      "mode": "RANDOM"
    },
    "connectivity": {
      "mode": "NO_LINK",
      "qpu": {
        "ip_address": "0.0.0.0",
        "port": 55
      }
    },
    "timeouts": {
      "http": 5,
      "lock": 4
    } 
  },
  "jobs": [
    {
      "type": "VQE",
      "qubits": [4, 6],
      "num_shots": [100, 200],
      "walltime": 10,
      "nthreads": 4,
      "app_logging_level": 2 
    },
    {
      "type": "RB",
      "qubits": [2],
      "num_shots": [100],
      "walltime": 10,
      "nthreads": 2
    },
    {
      "type": "QBC",
      "qubits": [4],
      "num_shots": [32],
      "walltime": 20,
      "nthreads": 2
    }
  ],
  "users": [
    {
      "user": "user0",
      "computations": {
        "VQE": 0.05,
        "RB": 0.94,
        "PyMatching": 0.01
      }
    }
  ]
}

Additional arguments

Additional arguments can be passed to quantum applications in the "jobs" array though `app_args' objects:

{ "type": "RB",
  "app_args": {
    "benchmarks": list of lists, each containing the qubit numbers on which one- or two-qubit RBs will be run, # [[0],[1,2]]
    "depths":     list of integers representing the different number of Clifford gates employed in the RB, # [2,4,8,16]
    "reps":       integer representing the number of times circuits of a particular depth are generated, # 10
  }
}

{ "type": "QBC",
  "app_args": {
    "pqc_number" :    integer in [2,5,15] representing the parametrized quantum circuit with the same number
                      in figure 2 of Adv. Quantum Technol. 2, 1900070 (2019)
    "training_size" : integer representing the number of feature vectors in the training dataset # 20
    "max_iters" :     integer representing the maximum number of iterations in the model's training
  }
}

For detailed configuration options, refer to the JSON schema.

Note: Only SLURM currently supports the high-performance "SCHEDULER" mode with lowest latency. See SLURM documentation for more details.

Programmatic Usage

from qstone.generators import generator

def main():
    generator.generate_suite(
        config="config.json",
        job_count=100, 
        output_folder=".", 
        atomic=False, 
        scheduler="bare_metal"
    )

if __name__ == "__main__":
    main()

Supported Backend Connectivities

• Local no-link runner - For testing without quantum hardware
• gRPC - High-performance remote procedure calls
• HTTP/REST - Standard web-based communication
• Rigetti - Native Rigetti quantum computer integration

Examples and Resources

• 📓 Getting Started Notebook
• 🔧 Adding New Computation Types
• 🌐 Creating a Simple Gateway

Contributing

• Contributing Guidelines
• Change Log

License

License

---

For questions, issues, or feature requests, please visit our GitHub repository or open an issue.