Setting the file. One moment.
Subchapter 101.1
references/devices.mdMarkdown13 KBView on GitHub
For pricing see pricing.md — rates differ per device, so a device choice is also a cost choice; for submitting work as a program set (many programs in one task) see program-sets.md; for cost guardrails see .
The ONLINE, OFFLINE, and RETIRED statuses have different semantics:
GetDevice and SearchDevices.Prefer the SDK — it applies filters client-side, performs region fan-out, and other niceties.
| Task | Braket Python SDK (preferred) | AWS CLI (portable) |
|---|---|---|
| Discover and filter devices | AwsDevice.get_devices(statuses=["ONLINE"], types=["QPU"]) — filters are ANDed; also arns, names, provider_names, order_by | aws braket search-devices --filters '[]' --region <region> then filter client-side; the API only supports deviceArn as filter |
| One device | AwsDevice(arn) | aws braket get-device --device-arn <arn> --region <region> |
| Read a field | device.name, device.status, device.type, device.is_available | aws braket get-device --device-arn <arn> --region <region> --query '{name:deviceName,status:deviceStatus,type:deviceType}' |
| Read capabilities | device.properties — already a parsed object | aws braket get-device --device-arn <arn> --region <region> --query 'deviceCapabilities' --output text | jq '.paradigm.qubitCount, (.action | keys)' — a JSON string, parse before reading |
Reference docs for correct usage:
AwsDevice (opens in a new tab) (AwsDevice.get_devices, AwsDevice.properties)braket search-devices (opens in a new tab), braket get-device (opens in a new tab)braket client — search_devices (opens in a new tab), get_device (opens in a new tab)Warning: GetDevice responses are large (10–30 KB per device, mostly deviceCapabilities). Do NOT dump the full response into your context — extract only the fields you need. Preferred approaches:
device = AwsDevice(arn); device.properties.<path> (already parsed, access fields directly)aws braket get-device --device-arn <arn> --region <region> --query 'deviceCapabilities' --output text | jq '<path to fields you need>'The deviceCapabilities field in GetDevice contains all information about a device, like whether it can run program sets, whether it can run OpenQASM gate model programs, etc.
deviceCapabilities is returned as a JSON-encoded string — parse it before reading (the SDK does this for you via AwsDevice.properties).
Inspect deviceCapabilities for all relevant fields — action types, paradigm.qubitCount, service.shotsRange, connectivity, etc. — no matter the device type.
Simulators and QPUs alike populate these fields (e.g. SV1 reports its qubit cap at paradigm.qubitCount).
Do not skip a field or substitute null based on assumptions about what a device type “has” — read the payload, and only report a field as missing after actually checking it.
For field meanings, types, and constraints, consult the amazon-braket-schemas-python repository rather than inferring them from memory.
You can do this by:
pip install --upgrade amazon-braket-schemas (always the latest), then read the module (e.g. inspect.getsource).Resolve the module from the live payload’s braketSchemaHeader: dots in name → folders under src/braket/, then append _v{version}.py. Example: braket.device_schema.iqm.iqm_device_capabilities v1 → src/braket/device_schema/iqm/iqm_device_capabilities_v1.py.
Braket supports two paradigms that are not mutually compatible:
GetDevice (deviceCapabilities.paradigm) rather than assuming a fixed device.A device accepts one paradigm. The most reliable discriminator is the action map, which names the program types the device will accept and covers every paradigm with one pattern:
actions = AwsDevice(arn).properties.action # keyed by DeviceActionType
"braket.ir.openqasm.program" in actions # gate-model OpenQASM
"braket.ir.openqasm.program_set" in actions # program sets
"braket.ir.ahs.program" in actions # analog Hamiltonian simulationdeviceCapabilities.paradigm carries the physical detail behind that choice — gate-model devices have nativeGateSet/connectivity, AHS devices have rydberg/lattice. Submitting a program type absent from the action map causes the program to be rejected.
All information regarding interpreting device availability can be found at https://docs.aws.amazon.com/braket/latest/developerguide/braket-task-when.html (opens in a new tab).
When a QPU is online but outside its executionWindows (availability window), it shows deviceStatus=ONLINE and queues tasks until the next window.
Unplanned maintenance or other device events shows deviceStatus=OFFLINE and attempts to create the quantum task will be rejected.
Braket device reservations (opens in a new tab) may also affect when tasks are able to run against QPUs.
When a target is OFFLINE or RETIRED, suggest an ONLINE alternative that is also within its availability window. When a target is outside its availability window, suggest an alternative that is.
| Field | Present on | SDK access → what it returns |
|---|---|---|
service.shotsRange | every device | AwsDevice(arn).properties.service.shotsRange → (shots_lower, shots_upper) |
service.reservationShotsRange | devices that support reservations and have different shot ranges | AwsDevice(arn).properties.service.reservationShotsRange → (shots_lower, shots_upper), or None when absent — a reservation can lower the floor, here from 100 shots to 1 |
Some providers apply a further shot minimum when error mitigation is enabled, carried under provider rather than service. See error mitigation on IonQ (opens in a new tab).
LocalSimulator(backend=...), documented at https://amazon-braket-sdk-python.readthedocs.io/en/latest/_apidoc/braket.devices.local_simulator.html (opens in a new tab) and https://docs.aws.amazon.com/braket/latest/developerguide/braket-send-to-local-simulator.html (opens in a new tab)LocalSimulator("braket_dm") locally, or the managed on-demand DM1. State-vector backends (braket_sv, default) cannot express noise models. See the example notebook (opens in a new tab) and SDK noise modules (opens in a new tab).shots=0 has special, simulator-specific behavior (analytical/exact mode): the circuit MUST include explicit result types — e.g. circuit.probability(), circuit.state_vector(), or circuit.expectation(observable) — or the simulator raises an error. QPUs always require shots > 0. See https://docs.aws.amazon.com/braket/latest/developerguide/braket-submit-tasks-simulators.html (opens in a new tab) and https://docs.aws.amazon.com/braket/latest/developerguide/braket-result-types.html (opens in a new tab)A local quantum device emulator is distinct from the local simulator: it applies a real device’s validation rules and noise model to a circuit locally, so you can catch a rejection before running on the QPU.
Learn how to use local device emulators at https://docs.aws.amazon.com/braket/latest/developerguide/braket-local-emulator.html (opens in a new tab).
In the SDK, the emulator obtained from a method on the AwsDevice class as AwsDevice.emulator() (opens in a new tab).
Some devices expose features behind an explicit opt-in, called “Experimental Capabilities” on Braket. Learn how to use experimental capabilities at https://docs.aws.amazon.com/braket/latest/developerguide/braket-experimental-capabilities.html (opens in a new tab). See example notebooks for experimental capabilities at https://github.com/amazon-braket/amazon-braket-examples/tree/main/examples/experimental_capabilities (opens in a new tab)
Some QPUs expose pulse-level access — you can inspect the native gate calibrations the QPU uses and attach custom pulse sequences at run time. Support can be determined from AwsDevice.properties.
Learn more about pulse control on Amazon Braket at https://docs.aws.amazon.com/braket/latest/developerguide/braket-pulse-control.html (opens in a new tab).
See example notebooks for pulse control at https://github.com/amazon-braket/amazon-braket-examples/tree/main/examples/pulse_control (opens in a new tab).
| Symptom | Cause | Fix |
|---|---|---|
| Context overflow / huge tool output | Dumped full GetDevice JSON into context | Use jq or --query to extract only needed fields; never dump raw deviceCapabilities |
| Treats “GetDevice succeeded” as “device is available” | Didn’t check deviceStatus in response | GetDevice returns successfully for RETIRED devices — you MUST check deviceStatus in the response is not RETIRED (and not OFFLINE if you need currently-runnable devices) |
| Emits an ARN for a device that has since retired | Recall from training data | Verify via SearchDevices live |
| Misses a device | Queried SearchDevices in only one region | Query all Braket regions |
queueSize/capabilities parse error | Treated string as int / JSON as object | queueSize is a string; deviceCapabilities is a json string - json.loads(deviceCapabilities) |
| Wrong availability answer | Looked for a maintenance field | Parse service.executionWindows |
Recommends a LocalSimulator backend name from memory | Backend names and their support status change between SDK releases | Enumerate what the installed SDK actually offers before choosing: python -c "from braket.devices import LocalSimulator; print(LocalSimulator.registered_backends())" or read https://docs.aws.amazon.com/braket/latest/developerguide/braket-submit-tasks-simulators.html (opens in a new tab) |
| Misses a conditional shot minimum (e.g. IonQ error mitigation) | Only read service.shotsRange | Check the device’s provider properties too — a mitigation scheme can raise the minimum above service.shotsRange |