Submitting Hardware Jobs
compile() only creates a compilation result. submit() sends a job to a quantum hardware provider and may consume job quota. Confirm the provider, machine, shot count, and credentials before submitting.
Pre-submission checks
- Validate the circuit and measurement mappings in the simulator.
- Use
compile()to inspect the target basis, layout, and generated executable. - Confirm the provider account, target machine, number of shots, cost, and job quota.
- Provide the token securely, then call
submit().
from unitarylab import Circuit
qc = Circuit(2)
qc.h(0)
qc.cx(0, 1)
job = qc.submit(
provider="guodun", machine="gd_qc1",
token="your-provider-token", shots=1024,
)submit() compiles and submits the job, then immediately returns HardwareJob without waiting for completion. Guodun and Tianyan adapters query the machine list and select an available entry when machine is omitted. Other adapters require an explicit machine. If credentials are omitted, Guodun and Tianyan can read GUODUN_LOGIN_KEY and TIANYAN_LOGIN_KEY, respectively.
submit(provider, machine=None, shots=1024, token=None)provider must identify a real hardware adapter; local is not valid. shots must be a positive integer and satisfy the provider’s minimum and multiple requirements. When machine is omitted, the target depends on the machine list returned at submission time. Specify a machine to pin the target.
from unitarylab import QCompiler
job = QCompiler().submit(
circuit_or_qasm,
provider="guodun", machine="gd_qc1",
token="your-provider-token", shots=1024,
)After pipeline compilation, submission creates a job; call job.result() to obtain HardwareResult. LQCloud requires the lqcloud SDK, QPanda3 requires pyqpanda3, and Quafu requires quarkstudio; missing dependencies raise an error during submission.
HardwareJob and single queries
print(job.provider, job.machine, job.job_ids, job.status)
hardware_result = job.result()
print(hardware_result.status, hardware_result.message)
print(hardware_result.counts)Each call to job.result() queries once and updates job.status; it does not block and poll until completion. Pending results contain a status explanation in message and empty distributions. Query the same job again later according to its status, rather than submitting again. HardwareJob also stores metadata and the provider’s job object.
HardwareResult.job usually refers to the original submitting job. An identity-only reference constructed from job identifiers lacks query context and is not guaranteed to support result().
HardwareResult
HardwareResult contains the following information:
| Field or property | Description |
|---|---|
provider / vendor | Provider name |
machine, status, submitted | Machine, job status, and submission state |
query_ids / job_ids | Provider job identifiers |
message, job | Status explanation and associated job |
counts, probabilities | Compatibility aliases for the recommended result view |
layout, final_layout | Logical-to-physical qubit mapping |
raw_counts, raw_probabilities | Raw measurement results |
corrected_counts, corrected_probabilities | Readout-mitigated results |
observed_counts, observed_probabilities | Recommended result view based on mitigation state |
executable, executable_format | Submitted program and format |
stage_metadata, provider_result | Pipeline metadata and provider result |
Call to_dict() to create a serializable summary. Job statuses and additional result fields vary by provider. Check status before reading counts or provider_result.
Successful submission means the provider accepted the job; it does not mean execution has completed. After a network timeout, check the provider job identifier before retrying to avoid duplicate quota use.
Security and limitations
- Do not print tokens in notebook output, logs, screenshots, or exception messages.
- Hardware results are affected by queueing, calibration, noise, and shots and will not exactly match ideal simulation results.
- Save compilation artifacts, machine name, and submission parameters before submission to support reproducibility.
- Authentication and network errors from third-party SDKs use provider-specific formats.