Job Commands¶

Commands for dispatching, monitoring, and managing individual benchmark jobs.

dispatch¶

Dispatch a benchmark job to a quantum device or simulator.

mgym job dispatch <config> [OPTIONS]

Arguments¶

Argument	Type	Description	Required
`CONFIG`	STR	Path to job configuration JSON file	Yes

Options¶

Option	Type	Description	Default
`--provider, -p`	STR	Provider name (e.g., ibm, braket, azure, ionq, local)	`None`
`--device, -d`	STR	Device identifier	`None`

estimate¶

Estimate provider usage as a proxy for job costs before dispatching. Circuits are constructed and compiled locally; no jobs are submitted or executed on hardware.

mgym job estimate <config> [OPTIONS]

Arguments¶

Argument	Type	Description	Required
`CONFIG`	STR	Path to job configuration JSON file	Yes

Options¶

Option	Type	Description	Default
`--provider, -p`	STR	Provider name (e.g., ibm, braket, azure, ionq, local)	`None`
`--device, -d`	STR	Device identifier	`None`
`--verbose, -v`	BOOL	Show per-job resources, circuit statistics, and estimation assumptions	`False`

The output starts with a short header identifying the benchmark, provider, and device. Add -v or --verbose to show circuit resources, statistics, and estimation assumptions. The default summary depends on the provider:

--provider ibm --device <device> shows estimated QPU time in seconds based on the device's timing metadata. Reading that metadata requires provider access, but the estimate does not run anything on the device.
--provider quantinuum shows total H-series Quantum Credits (HQCs).
--provider aws (or its alias braket) shows total shots and total tasks, counting one task per circuit. Use --verbose for the full resource breakdown.
Other providers report that no cost estimate is available. Use --verbose to show circuit resources.

IBM estimates assume the default repetition delay, initial reset, and about two seconds of overhead per circuit batch. Additional server-side splitting, runtime mitigation, and idle time billed within sessions are excluded. This estimates QPU usage, not queue time, wall-clock completion time, or a monetary price. See IBM's usage estimation guide.

If IBM timing metadata is unavailable or --device is omitted, the QPU estimate is marked unavailable. Use --verbose for the explanation and any available circuit resource counts.

poll¶

Poll job status and retrieve results when complete.

mgym job poll [job_id] [OPTIONS]

Arguments¶

Argument	Type	Description	Required
`JOB_ID`	STR	Job ID to poll (use 'latest' for most recent)	No

Options¶

Option	Type	Description	Default
`--json`	STR	Export results to JSON file	`None`
`--no-cache`	BOOL	Ignore locally cached results and refetch	`False`
`--include-raw`	BOOL	Export raw measurement counts to a separate debug file	`False`

Debug Output¶

When --include-raw is used with --json, a separate debug file is created alongside the results file. For example:

mgym job poll latest --json result.json --include-raw

This creates:

result.json - Standard benchmark results
result_debug.json - Debug data for replay/debugging:

{
    "job_id": "...",
    "job_type": "...",
    "params": {...},
    "job_data": {...},
    "raw_results": [{"measurement_counts": {"00": 512, "11": 488},...}, ...]
}

This is useful for debugging benchmark results locally without access to the original quantum provider.

Note

If results are cached, raw counts are not available. Use --no-cache to refetch from the provider.

view¶

View job details and metadata.

mgym job view [job_id]

Arguments¶

Argument	Type	Description	Required
`JOB_ID`	STR	Job ID to view (lists all if omitted)	No

delete¶

Delete a job from the local database.

mgym job delete [job_id]

Arguments¶

Argument	Type	Description	Required
`JOB_ID`	STR	Job ID to delete	No

upload¶

Upload job results to GitHub via pull request.

mgym job upload [job_id] [OPTIONS]

Arguments¶

Argument	Type	Description	Required
`JOB_ID`	STR	Job ID to upload	No

Options¶

Option	Type	Description	Default
`--repo`	STR	Target GitHub repo (owner/repo) (env: `MGYM_UPLOAD_REPO`)	`unitaryfoundation/metriq-data`
`--base`	STR	Base branch for the PR (env: `MGYM_UPLOAD_BASE_BRANCH`)	`main`
`--dir`	STR	Directory in repo for the JSON file (env: `MGYM_UPLOAD_DIR`)	`None`
`--branch`	STR	Branch name for the PR	`None`
`--title`	STR	Pull request title	`None`
`--body`	STR	Pull request body	`None`
`--commit-message`	STR	Commit message	`None`
`--clone-dir`	STR	Working directory to clone into (env: `MGYM_UPLOAD_CLONE_DIR`)	`None`
`--dry-run`	BOOL	Do not push or open a PR; print actions only	`False`
`--outcome`	STR	Upload a non-completed outcome record instead of results: `error`, `unsupported` or `not_applicable`	`None`
`--reason`	STR	Human-readable reason for the `--outcome` classification (required for `unsupported` / `not_applicable`)	`None`

Failed jobs¶

A job whose dispatch raised, or whose provider tasks ended in a failed/cancelled state, keeps the captured error on the job record (visible in mgym job view). Uploading such a job produces an outcome: "error" record with the verbatim error message instead of results. To assert that the device structurally cannot run the benchmark instance, reclassify it by hand:

mgym job upload <JOB_ID> --outcome unsupported --reason "Compiler rejects 100-qubit LR-QAOA circuits"

Completed jobs cannot be uploaded with --outcome; a completed record always supersedes outcome records for the same benchmark instance. --outcome error is reserved for captured failures and cannot be asserted by hand.

Once a failure is recorded, poll and upload trust it without reconnecting to the provider (failed/cancelled statuses are terminal); pass --no-cache to poll to force a re-check. An upload with an explicit --outcome goes ahead even if the provider cannot be reached, attaching whatever error was recorded locally.

replay¶

Replay benchmark computation from a debug file to recompute results locally.

This command allows you to recompute benchmark results without access to the original quantum provider, using the raw measurement data captured with --include-raw.

mgym job replay <debug_file> [OPTIONS]

Arguments¶

Argument	Type	Description	Required
`DEBUG_FILE`	STR	Path to debug JSON file (created with `--include-raw`)	Yes

Options¶

Option	Type	Description	Default
`--json`	STR	Export replayed results to JSON file	`None`

Example Workflow¶

Capture raw data during poll:
```
mgym job poll latest --json result.json --include-raw
```
This creates result.json (results) and result_debug.json (debug data).
Share debug file for debugging:

Send result_debug.json to another user who can replay the computation locally.

Replay to recompute results:

mgym job replay result_debug.json

Or export to JSON:

mgym job replay result_debug.json --json replayed.json

Note

The replay command does use provider credentials or network access. All computation happens locally using the captured raw measurement data. Any benchmark metric calculations that rely on job specific data will fail to replay.