0
# Amazon Braket SDK
1

2
An open source library for interacting with quantum computing devices on Amazon Braket.
3

4
The Amazon Braket SDK provides a comprehensive Python interface for quantum computing, offering support for quantum circuits, AWS quantum devices, local simulation, analog Hamiltonian simulation, quantum annealing, and advanced features like pulse control and error mitigation.
5

6
## Package Information
7

8
- **Package Name**: amazon-braket-sdk
9
- **Package Type**: pypi
10
- **Language**: Python
11
- **Installation**: `pip install amazon-braket-sdk`
12
- **Version**: 1.101.0
13
- **License**: Apache License 2.0
14
- **Python Support**: 3.10, 3.11, 3.12, 3.13
15
- **Architecture**: Namespace package structure
16

17
## Core Imports
18

19
```python { .api }
20
# Core SDK components
21
from braket._sdk import __version__
22

23
# Circuit construction and gates
24
from braket.circuits import Circuit, Gate, AngledGate, DoubleAngledGate
25
from braket.circuits.gates import H, CNot, Rx, Ry, Rz, X, Y, Z
26
from braket.circuits.observables import X as ObsX, Y as ObsY, Z as ObsZ, TensorProduct
27
from braket.circuits.result_types import StateVector, Expectation, Sample, Probability
28

29
# AWS integration
30
from braket.aws import AwsDevice, AwsQuantumTask, AwsSession, AwsDeviceType
31

32
# Local simulation
33
from braket.devices import LocalSimulator
34

35
# Quantum information utilities
36
from braket.quantum_information import PauliString
37

38
# Job management
39
from braket.jobs import hybrid_job
40

41
# Cost tracking
42
from braket.tracking import Tracker
43

44
# Parametric circuits and free parameters
45
from braket.circuits import FreeParameter, FreeParameterExpression, Parameterizable
46

47
# Program sets and parameter binding
48
from braket.program_sets import ProgramSet, ParameterSets, CircuitBinding
49

50
# Registers and qubit management
51
from braket.circuits import Qubit, QubitInput, QubitSet, QubitSetInput
52

53
# Circuit emulation and compilation
54
from braket.emulation import PassManager
55

56
# Timing data structures
57
from braket.timings import TimeSeries, TimeSeriesItem
58
```
59

60
## Basic Usage Example
61

62
```python { .api }
63
from braket.circuits import Circuit
64
from braket.circuits.gates import H, CNot
65
from braket.devices import LocalSimulator
66
from braket.aws import AwsDevice
67

68
# Create a Bell state circuit
69
def create_bell_circuit() -> Circuit:
70
    """
71
    Creates a Bell state quantum circuit.
72
    
73
    Returns:
74
        Circuit: A quantum circuit that creates a Bell state
75
    """
76
    circuit = Circuit()
77
    circuit.h(0)
78
    circuit.cnot(0, 1)
79
    return circuit
80

81
# Run on local simulator
82
def run_local_simulation(circuit: Circuit, shots: int = 1000) -> dict:
83
    """
84
    Run circuit on local simulator.
85
    
86
    Args:
87
        circuit: The quantum circuit to execute
88
        shots: Number of measurement shots
89
        
90
    Returns:
91
        dict: Measurement results
92
    """
93
    device = LocalSimulator()
94
    task = device.run(circuit, shots=shots)
95
    return task.result().measurement_counts
96

97
# Run on AWS device
98
def run_aws_device(circuit: Circuit, device_arn: str, shots: int = 1000) -> dict:
99
    """
100
    Run circuit on AWS quantum device.
101
    
102
    Args:
103
        circuit: The quantum circuit to execute
104
        device_arn: AWS device ARN
105
        shots: Number of measurement shots
106
        
107
    Returns:
108
        dict: Measurement results from AWS task
109
    """
110
    device = AwsDevice(device_arn)
111
    task = device.run(circuit, shots=shots)
112
    return task.result().measurement_counts
113
```
114

115
## Architecture Overview
116

117
The Amazon Braket SDK is organized into 20 major modules:
118

119
### Core Components
120

121
1. **[Circuit Construction](circuits.md)** - Quantum circuits, gates, and measurements
122
2. **[AWS Integration](aws-integration.md)** - Cloud quantum devices and task management  
123
3. **[Local Simulation](devices-simulation.md)** - Local quantum simulators and device management
124
4. **[Quantum Information](quantum-information.md)** - Pauli strings, parametric circuits, registers, and quantum utilities
125

126
### Advanced Features
127

128
5. **[Advanced Capabilities](advanced-features.md)** - AHS, annealing, pulse control, error mitigation, emulation, and experimental features
129

130
## Core Capabilities
131

132
### Quantum Circuit Construction
133

134
Build quantum circuits with a comprehensive gate library:
135

136
```python { .api }
137
from braket.circuits import Circuit
138
from braket.circuits.gates import H, CNot, Rx, Ry, Rz, U
139
from braket.circuits.observables import Z, X
140
from braket.circuits.result_types import Expectation
141
import numpy as np
142

143
# Parameterized quantum circuit
144
def variational_circuit(params: list[float]) -> Circuit:
145
    """
146
    Creates a parameterized variational quantum circuit.
147
    
148
    Args:
149
        params: List of rotation parameters
150
        
151
    Returns:
152
        Circuit: Variational quantum circuit
153
    """
154
    circuit = Circuit()
155
    
156
    # Layer of Hadamard gates
157
    for qubit in range(2):
158
        circuit.h(qubit)
159
    
160
    # Parameterized rotation layers
161
    for i, param in enumerate(params):
162
        qubit = i % 2
163
        circuit.ry(qubit, param)
164
        
165
    # Entangling layer
166
    circuit.cnot(0, 1)
167
    
168
    # Observable measurement
169
    circuit.expectation(observable=Z(0) @ Z(1))
170
    
171
    return circuit
172
```
173

174
### AWS Device Integration
175

176
Connect to quantum processors and simulators on AWS:
177

178
```python { .api }
179
from braket.aws import AwsDevice, AwsDeviceType, AwsSession
180
from braket.circuits import Circuit
181

182
# Device discovery and selection
183
def get_available_devices() -> dict[str, AwsDevice]:
184
    """
185
    Get all available AWS Braket devices.
186
    
187
    Returns:
188
        dict: Mapping of device names to AwsDevice instances
189
    """
190
    # Get QPU devices
191
    qpu_devices = AwsDevice.get_devices(device_types=[AwsDeviceType.QPU])
192
    
193
    # Get simulator devices  
194
    sim_devices = AwsDevice.get_devices(device_types=[AwsDeviceType.SIMULATOR])
195
    
196
    devices = {}
197
    for device in qpu_devices + sim_devices:
198
        devices[device.name] = device
199
        
200
    return devices
201

202
# Session management
203
def create_aws_session(region: str = "us-east-1") -> AwsSession:
204
    """
205
    Create authenticated AWS session for Braket.
206
    
207
    Args:
208
        region: AWS region for quantum computing resources
209
        
210
    Returns:
211
        AwsSession: Authenticated session
212
    """
213
    return AwsSession(boto_session=None, braket_user_agents=None)
214
```
215

216
### Hybrid Quantum Jobs
217

218
Execute hybrid quantum-classical algorithms:
219

220
```python { .api }
221
from braket.jobs import hybrid_job, save_job_result, get_job_device_arn
222
from braket.aws import AwsDevice
223
from braket.circuits import Circuit
224

225
@hybrid_job(device="ml.m5.large")
226
def quantum_optimization_job():
227
    """
228
    Hybrid job for quantum optimization algorithm.
229
    
230
    This job runs a variational quantum algorithm combining
231
    quantum circuit execution with classical optimization.
232
    """
233
    # Get the quantum device for this job
234
    device_arn = get_job_device_arn()
235
    device = AwsDevice(device_arn)
236
    
237
    # Define cost function using quantum circuits
238
    def cost_function(params: list[float]) -> float:
239
        circuit = variational_circuit(params)
240
        task = device.run(circuit, shots=1000)
241
        result = task.result()
242
        return result.values[0]  # Expectation value
243
    
244
    # Classical optimization loop
245
    import scipy.optimize
246
    initial_params = [0.1, 0.2]
247
    result = scipy.optimize.minimize(cost_function, initial_params)
248
    
249
    # Save results
250
    save_job_result({
251
        "optimal_params": result.x.tolist(),
252
        "optimal_value": float(result.fun)
253
    })
254
```
255

256
### Cost and Resource Tracking
257

258
Monitor quantum computing usage and costs:
259

260
```python { .api }
261
from braket.tracking import Tracker
262
from braket.aws import AwsDevice
263
from braket.circuits import Circuit
264

265
def tracked_quantum_execution(circuit: Circuit, device_arn: str) -> dict:
266
    """
267
    Execute quantum circuit with cost tracking.
268
    
269
    Args:
270
        circuit: Quantum circuit to execute
271
        device_arn: AWS device ARN
272
        
273
    Returns:
274
        dict: Results including cost information
275
    """
276
    with Tracker() as tracker:
277
        # Execute quantum task
278
        device = AwsDevice(device_arn)
279
        task = device.run(circuit, shots=1000)
280
        result = task.result()
281
        
282
        # Get cost information
283
        cost_info = {
284
            "quantum_tasks_cost": tracker.quantum_tasks_cost(),
285
            "simulator_tasks_cost": tracker.simulator_tasks_cost(),
286
            "total_cost": tracker.quantum_tasks_cost() + tracker.simulator_tasks_cost()
287
        }
288
        
289
    return {
290
        "measurement_counts": result.measurement_counts,
291
        "cost_tracking": cost_info
292
    }
293
```
294

295
## Key Features
296

297
- **Complete Gate Library**: 50+ quantum gates including parameterized gates, multi-qubit gates, and custom unitary operations
298
- **Multiple Quantum Computing Paradigms**: Gate model circuits, analog Hamiltonian simulation, quantum annealing, and photonic quantum computing
299
- **AWS Cloud Integration**: Access to real quantum processors from IonQ, Rigetti, IBM, and AWS simulators
300
- **Local Development**: High-performance local quantum simulators for circuit development and testing
301
- **Hybrid Algorithms**: Seamless integration of quantum and classical computing for optimization and machine learning
302
- **Production Features**: Cost tracking, job management, error mitigation, and experimental capabilities
303
- **Pulse-Level Control**: Direct pulse sequence programming for supported quantum devices
304
- **Noise Modeling**: Comprehensive noise models for realistic quantum circuit simulation
305

306
## Documentation Structure
307

308
This documentation is organized into focused capability areas:
309

310
- **[circuits.md](circuits.md)** - Circuit construction, quantum gates, observables, noise models, and result types
311
- **[aws-integration.md](aws-integration.md)** - AWS devices, quantum tasks, sessions, jobs, and cost tracking  
312
- **[devices-simulation.md](devices-simulation.md)** - Device management, local simulators, and emulation capabilities
313
- **[quantum-information.md](quantum-information.md)** - Pauli strings, quantum information utilities, and mathematical tools
314
- **[advanced-features.md](advanced-features.md)** - Analog Hamiltonian simulation, quantum annealing, pulse control, and error mitigation
315

316
Each documentation section provides complete API coverage with type definitions, usage patterns, and practical examples for AI agent consumption.