Reject unsupported work before creating a job¶
Read the Backend's declared capabilities, then request a GPU device that the local simulator does not provide. Complete job recovery and resource planning. Use the installed environment.
Predict an error before a Job is returned. Silently switching to CPU would change the requested execution conditions; an application should make that choice explicit if it offers an alternative.
Read the declaration and test the request¶
"""Inspect declared Backend capability and a structured fail-fast boundary.
Capability is explicit data, not an optimistic fallback. The local Backend
declares executable methods and rejects a requested GPU device before creating
a doomed Job or allocating a large state array.
"""
from __future__ import annotations
import json
from cascaqit import CapabilityError, Circuit, LocalBackend
from cascaqit.simulators import SimulationOptions
def main() -> None:
"""Read capability and capture one unsupported-device diagnostic."""
backend = LocalBackend(seed=405)
capability = backend.capability
error_code = None
error_stage = None
error_path = None
gpu_job = None
try:
gpu_job = backend.run(
Circuit(1, program_id="lesson.platform.capability").h(0),
shots=8,
options=SimulationOptions(device="gpu"),
)
except CapabilityError as error:
error_code = error.code
error_stage = error.stage
error_path = error.object_path
payload = {
"track": "sdk_platform_engineer",
"level": "expert",
"lesson": "capability_boundaries",
"facts": {
"backend_id": capability.backend_id,
"methods": list(capability.executable_simulation_methods),
"scan_supported": capability.unified_scan_supported,
"noise_supported": capability.noise_supported,
"gpu_error_code": error_code,
"gpu_error_stage": error_stage,
"gpu_error_path": error_path,
"job_created_for_gpu": gpu_job is not None,
},
"boundaries": {
"hardware_execution": False,
"cloud_execution": False,
"network_accessed": False,
"credentials_loaded": False,
},
}
print(json.dumps(payload, sort_keys=True))
if __name__ == "__main__":
main()
python3 examples/user/tracks/sdk_platform_engineer/05_expert_capability_boundaries_en.py
The capability lists supported simulation methods and flags for scans and noise. Those declarations describe available features, not a guarantee that every combination of program, method, noise model and device is valid. For example, subspace execution needs an applicable basis; a general Hybrid circuit is not automatically projected into a smaller space.
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"backend_id": "local.simulator",
"gpu_error_code": "SIMULATION_DEVICE_UNAVAILABLE",
"gpu_error_path": "simulation_options.device",
"gpu_error_stage": "simulation",
"job_created_for_gpu": false,
"methods": [
"state_vector",
"subspace",
"density_matrix",
"trajectory"
],
"noise_supported": true,
"scan_supported": true
},
"lesson": "capability_boundaries",
"level": "expert",
"track": "sdk_platform_engineer"
}
The GPU request should raise CapabilityError with code SIMULATION_DEVICE_UNAVAILABLE, stage simulation and object path simulation_options.device. job_created_for_gpu is calculated from whether the call returned a handle. It should be false. The script catches this expected error so that it can print the diagnostic; this does not mean a GPU job succeeded.
Use a stable error code to choose an application action, and display the message and suggestion when available. Do not catch all exceptions and return an empty result: invalid input, unsupported capability and runtime failure need different handling. A rejected request has no measurement data to export.
Explain capability at the right level¶
| Fact | What it supports |
|---|---|
| A method appears in the capability list | The Backend implements that method for eligible workloads. |
| A plan accepts the current request | The program, options and estimated resources passed preflight. |
| A Job returns a completed result | This submitted workload actually executed. |
| Results match an independent prediction | The tested calculation agrees with that prediction under its assumptions. |
These statements build on one another; none replaces the later checks. Likewise, a source hash or a dry-run package does not demonstrate hardware execution. This SDK's public Backend path runs local simulation; Cloud and Hanyuan material is limited to the documented offline interfaces, replay or dry runs.
Try a supported device and an ineligible method¶
- In a copy, request
device='cpu'. Inspect the returned Job and then callresult(). Which stage now performs the numerical work? - Request
method='density_matrix'for the same program without a noise model. Why does appearing in the method list not guarantee acceptance? - After a capability rejection, should retrying the identical request three times help?
The CPU request returns a queued Job, and result() executes it. The explicit density-matrix request is ineligible without a noise model and is rejected during planning. Repeating the same unsupported request does not add the missing capability. Change the requested conditions or choose a compatible Backend explicitly.
See local simulator algorithms for method eligibility and current limitations for hardware boundaries. You can now follow a request from validation through execution, retained results and recovery without interpreting an offline artifact as a live run.