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 circuit resource requirements before dispatching jobs.

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`

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.