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.

{'device': 'aer_simulator',
 'job_type': 'WIT',
 'provider': 'local',
 'results': {'expectation_value': 0.99658203125},
 'timestamp': '2025-07-29T20:31:17.978851',
 'version': '0.1.3.dev0'}

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

Documentation

• CLI workflows, credential setup, and upload instructions: Command-Line Workflows
• Contributor and release guidance: Developer Guide
• API reference and benchmark integration notes: metriq-gym Docs

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 GNU GPL v3.0 or later.