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!

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

   pip install metriq-gym
   

2. 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
   

3. 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 generic examples in the ready-made JSON schemas under metriq_gym/schemas/examples/. These editable examples are not the canonical configurations used for Metriq Score 1.0; the score definition is in metriq_gym/suites/metriq_score_1_0.json.

Jobs dashboard

A local web view of your dispatched jobs — lifecycle status, per-device suite coverage, and poll/upload/delete actions:

mgym dashboard

Then open http://localhost:8787. The dashboard reads your local job database; provider APIs are only contacted when you click Poll.

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.