metriq-gym¶

metriq-gym is a Python framework for implementing and running standard quantum benchmarks on different quantum devices by different providers.

Open – Open-source since its inception and fully developed in public.
Transparent – All benchmark parameters are defined in a schema file and the benchmark code is reviewable by the community.
Cross-platform – Supports running benchmarks on multiple quantum hardware providers (integration powered by qBraid-SDK)
User-friendly – Provides a simple command-line interface for dispatching, monitoring, and polling benchmark jobs (you can go on with your life while your job waits in the queue).

Quick Start¶

Four easy steps to get started with metriq-gym!

Install metriq-gym directly in your Python environment using pip:

pip install metriq-gym

Download a benchmark configuration file from the schemas/examples/ directory (this example uses the WIT — Wormhole-inspired teleportation — benchmark)
```
curl -O https://raw.githubusercontent.com/unitaryfoundation/metriq-gym/refs/heads/main/metriq_gym/schemas/examples/wit.example.json
```

Dispatch it to a quantum device or simulator.

mgym job dispatch wit.example.json -p local -d aer_simulator

4. Poll the job to get the results.

mgym job poll latest

You will see the results of the benchmark printed in your terminal. E.g.

{'app_version': '0.6.0',
 'job_type': 'WIT',
 'platform': {'device': 'aer_simulator',
              'device_metadata': {'num_qubits': 31,
                                  'simulator': True,
                                  'version': '0.17.2'},
              'provider': 'local'},
 'results': {'expectation_value': {'uncertainty': 0.0006673812593654682,
                                   'value': 0.996337890625},
             'score': {'uncertainty': 0.0006673812593654682,
                       'value': 0.996337890625}},
 'runtime_seconds': 0.009346791077405214,
 'suite_id': None,
 'timestamp': '2026-01-16T15:42:18.173736'}

Results:
  expectation_value: 0.996337890625 ± 0.0006673812593654682
  score: 0.996337890625 ± 0.0006673812593654682

Explore more examples in the ready-made JSON schemas under metriq_gym/schemas/examples/.

Documentation¶

Quickstart Guide - Get up and running quickly
CLI Reference - Command-line workflows and credential setup
Provider Configuration - Setup guides for IBM, IonQ, AWS, Azure, Quantinuum, OriginQ
Benchmarks - Available benchmarks and configuration
Developer Guide - Contributing to metriq-gym

Community¶

Join the discussion on Discord (#metriq channel)
Ask questions or share ideas via GitHub Discussions

Contributing¶

Start with CONTRIBUTING.md for the workflow checklist, and review the Developer Guide. Issues and pull requests are welcome!

License¶

metriq-gym is available under the Apache License 2.0.