metriq-gym 0.7.0

Framework for implementing and running standard quantum benchmarks on different quantum devices by different providers.

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