AWS braket documentation change
Summary
Updated documentation for result types, observables, parameters, and adjoint gradients with code examples and clarifications
Security assessment
Changes focus on clarifying usage of quantum computing features (observables, parameters, adjoint gradients) and code examples. No mention of security vulnerabilities, access controls, encryption, or other security-related concepts. The updates are functional/educational improvements rather than security fixes or security feature documentation.
Diff
diff --git a/braket/latest/developerguide/braket-result-types.md b/braket/latest/developerguide/braket-result-types.md index a5a9540bb..3ed692d15 100644 --- a//braket/latest/developerguide/braket-result-types.md +++ b//braket/latest/developerguide/braket-result-types.md @@ -4,0 +5,2 @@ +ObservablesParametersAdjoint gradient + @@ -43,0 +46,2 @@ You can check the supported result types by examining the device properties, as + from braket.aws import AwsDevice + @@ -46 +50 @@ You can check the supported result types by examining the device properties, as - # print the result types supported by this device + # Print the result types supported by this device @@ -59 +63 @@ To call a `ResultType`, append it to a circuit, as shown in the following exampl - from braket.circuits import Observable + from braket.circuits import Circuit, Observable @@ -69 +73 @@ To call a `ResultType`, append it to a circuit, as shown in the following exampl - # print one of the result types assigned to the circuit + # Print one of the result types assigned to the circuit @@ -74 +78 @@ To call a `ResultType`, append it to a circuit, as shown in the following exampl -Some devices provide measurements (for instance Rigetti) as results and others provide probabilities as results (for instance IonQ). The SDK provides a measurements property on results, but for the devices that return probabilities, it is post-computed. Thus, devices like those provided by IonQ have measurement results determined by probability since per shot measurements are not returned. You can check if a result is post-computed by viewing the `measurements_copied_from_device` on the result object as shown in this [file](https://github.com/aws/amazon-braket-sdk-python/blob/ca5b08dada4839ca31c012ff50aa20b656fd1879/src/braket/tasks/gate_model_quantum_task_result.py#L70-L72). +Different quantum devices provide results in various formats. For example, Rigetti devices return measurements, while IonQ devices provide probabilities. The Amazon Braket SDK offers a measurements property for all results. However, for devices that return probabilities, these measurements are post-computed and based on the probabilities, as per-shot measurements are not available. To determine if a result has been post-computed, check the `measurements_copied_from_device` on the result object. This operation is detailed in the [gate_model_quantum_task_result.py](https://github.com/aws/amazon-braket-sdk-python/blob/ca5b08dada4839ca31c012ff50aa20b656fd1879/src/braket/tasks/gate_model_quantum_task_result.py#L70-L72) file in the Amazon Braket SDK GitHub repository. @@ -76 +80 @@ Some devices provide measurements (for instance Rigetti) as results and others p -**Observables** +## Observables @@ -78 +82 @@ Some devices provide measurements (for instance Rigetti) as results and others p -Amazon Braket includes an `Observable` class, which can be used to specify an observable to be measured. +Amazon Braket's `Observable` class allows you to measure a specific observable. @@ -80 +84 @@ Amazon Braket includes an `Observable` class, which can be used to specify an ob -You can apply at most one unique non-identity observable to each qubit. If you specify two or more different non-identity observables to the same qubit, you see an error. For this purpose, each factor of a tensor product counts as an individual observable, so it is permissible to have multiple tensor products acting on the same qubit, provided that the factor acting on that qubit is the same. +You can apply only one unique non-identity observable to each qubit. An error occurs If you specify two or more different non-identity observables to the same qubit. For this purpose, each factor of a tensor product counts as an individual observable. This means you can have multiple tensor products on the same qubit, as long as the factors acting on that qubit remain the same. @@ -82 +86 @@ You can apply at most one unique non-identity observable to each qubit. If you s -You can also scale an observable and add observables (scaled or not). This creates a `Sum` which can be used in the `AdjointGradient` result type. +An observable can be scaled and add other observables (scaled or not). This creates a `Sum` which can be used in the `AdjointGradient` result type. @@ -86,0 +91,2 @@ The `Observable` class includes the following observables. + import numpy as np + @@ -93 +99 @@ The `Observable` class includes the following observables. - # get the eigenvalues of the observable + # Get the eigenvalues of the observable @@ -95 +101 @@ The `Observable` class includes the following observables. - # or whether to rotate the basis to be computational basis + # Or rotate the basis to be computational basis @@ -98 +104 @@ The `Observable` class includes the following observables. - # get the tensor product of observable for the multi-qubit case + # Get the tensor product of the observable for the multi-qubit case @@ -100 +106 @@ The `Observable` class includes the following observables. - # view the matrix form of an observable by using + # View the matrix form of an observable by using @@ -104 +110 @@ The `Observable` class includes the following observables. - # also factorize an observable in the tensor form + # Factorize an observable in the tensor form @@ -107 +113 @@ The `Observable` class includes the following observables. - # self-define observables given it is a Hermitian + # Self-define observables, given it is a Hermitian @@ -113 +119 @@ The `Observable` class includes the following observables. - Eigenvalue: [ 1 -1] + Eigenvalue: [ 1. -1.] @@ -119,2 +125,2 @@ The `Observable` class includes the following observables. - [[ 0.+0.j 0.+0.j 0.-1.j 0.-0.j] - [ 0.+0.j -0.+0.j 0.-0.j 0.+1.j] + [[ 0.+0.j 0.+0.j 0.-1.j 0.+0.j] + [ 0.+0.j -0.+0.j 0.+0.j 0.+1.j] @@ -122 +128 @@ The `Observable` class includes the following observables. - [ 0.+0.j -0.-1.j 0.+0.j -0.+0.j]] + [ 0.+0.j 0.-1.j 0.+0.j -0.+0.j]] @@ -127 +133,10 @@ The `Observable` class includes the following observables. -**Parameters** +## Parameters + +Circuits can incorporate free parameters. These free parameters only need to be constructed once to run multiple times, and can be used to compute gradients. + +Each free parameter uses a string-encoded name that is used to: + + * Set parameter values + + * Identify which parameters to use + @@ -129 +143,0 @@ The `Observable` class includes the following observables. -Circuits may include free parameters, which you can be use in a “construct once - run many times” manner and to compute gradients. Free parameters have a string-encoded name that you can use to specify their values or to determine whether to differentiate with respect to them. @@ -132 +146,4 @@ Circuits may include free parameters, which you can be use in a “construct onc - from braket.circuits import Circuit, FreeParameter, Observable + + from braket.circuits import Circuit, FreeParameter, observables + from braket.parametric import FreeParameter + @@ -136 +152,0 @@ Circuits may include free parameters, which you can be use in a “construct onc - circ.adjoint_gradient(observable=Observable.Z() @ Observable.Z(), target=[0, 1], parameters = ["phi", theta] @@ -138 +154,13 @@ Circuits may include free parameters, which you can be use in a “construct onc -For the parameters you want to differentiate, specify them either by using their name (as a string) or by direct reference. Note that computing the gradient using the `AdjointGradient` result type is done with respect to the **expectation value** of the observable. +## Adjoint gradient + +The SV1 device calculates the adjoint gradient of an observable expectation value, including multi-term Hamiltonian. To differentiate parameters, specify their name (in string format) or by direct reference. + + + from braket.aws import AwsDevice + from braket.devices import Devices + + device = AwsDevice(Devices.Amazon.SV1) + + circ.adjoint_gradient(observable=3 * Observable.Z(0) @ Observable.Z(1) - 0.5 * observables.X(0), parameters = ["phi", theta]) + +Passing fixed parameter values as arguments to a parameterized circuit will remove the free parameters. Running this circuit with `AdjointGradient` produces an error, because the free parameters no longer exist. The follow code example demonstrates the correct and incorrect usage: @@ -140 +167,0 @@ For the parameters you want to differentiate, specify them either by using their -**Note:** If you have fixed the values of free parameters by passing them as arguments to the parameterized circuit, running a circuit with `AdjointGradient` as a result type and parameters specified will produce an error. This is because the parameters we are using to differentiate with are no longer present. See the following example. @@ -141,0 +169,2 @@ For the parameters you want to differentiate, specify them either by using their + # Will error, as no free parameters will be present + #device.run(circ(0.2), shots=0) @@ -143,2 +172,2 @@ For the parameters you want to differentiate, specify them either by using their - device.run(circ(0.2), shots=0) # will error, as no free parameters will be present - device.run(circ, shots=0, inputs={'phi'=0.2, 'theta'=0.2) # will succeed + # Will succeed + device.run(circ, shots=0, inputs={'phi': 0.2, 'theta': 0.2})