feat: resource estimation workflow for benchmark jobs.

docs/source/cli_workflows.rst

@@ -108,7 +108,30 @@ Defaults:
 * Directory: ``metriq-gym/v<major.minor>/<provider>`` (override with ``--dir`` or ``MGYM_UPLOAD_DIR``)
 * Uploads append records to ``results.json``
 
-Authentication:
+Estimate Job Resources
+======================
+
+Before dispatching, you can approximate the circuit footprint, gate counts, and (for
+Quantinuum) HQCs:
+
+.. code-block:: sh
+
+   mgym job estimate metriq_gym/schemas/examples/wit.example.json \
+       --provider quantinuum
+
+The command prints aggregated totals and per-circuit statistics. HQCs are calculated
+automatically for Quantinuum devices using the published H-series coefficients
+(``HQC = 5 + C × (N₁ + 10N₂ + 5Nₘ)/5000``); for other providers, only gate counts are shown.
+Benchmarks that depend on device topology (e.g. BSEQ, CLOPS, Mirror Circuits, LR-QAOA)
+require ``--device`` to be supplied so the estimator can inspect connectivity.
+
+.. code-block:: sh
+
+   mgym job estimate metriq_gym/schemas/examples/wit.example.json \
+       --provider ibm --device ibm_fez
+
+Authentication
+==============
 
 * Set ``GITHUB_TOKEN`` (or ``GH_TOKEN``). External contributors should fork the data repo first.
 * Token docs: https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

metriq_gym/cli.py

@@ -169,6 +169,22 @@ def parse_arguments() -> argparse.Namespace:
         help="Backend to use",
     )
 
+    job_estimate = job_subparsers.add_parser("estimate", help="Estimate resources for a job")
+    job_estimate.add_argument("config", type=str, help="Path to job configuration file.")
+    job_estimate.add_argument(
+        "-p",
+        "--provider",
+        type=str,
+        choices=get_providers() + ["local"],
+        help="String identifier for backend provider service",
+    )
+    job_estimate.add_argument(
+        "-d",
+        "--device",
+        type=str,
+        help="Backend to use (optional for resource estimation)",
+    )
+
     job_poll = job_subparsers.add_parser("poll", help="Poll job")
     job_view = job_subparsers.add_parser("view", help="View job")
     job_delete = job_subparsers.add_parser("delete", help="Delete job")