braket.circuits.result_type module

class braket.circuits.result_type.ResultType(ascii_symbols: list[str])

Bases: object

Class ResultType represents a requested result type for the circuit. This class is considered the result type definition containing the metadata that defines what a requested result type is and what it does.

Initializes a ResultType.

Parameters:

ascii_symbols (list[str]) – ASCII string symbols for the result type. This is used when printing a diagram of circuits.

Raises:

ValueError – ascii_symbols is None

property ascii_symbols: list[str]

Returns the ascii symbols for the requested result type.

Type:

list[str]

property name: str

Returns the name of the result type

Returns:

str – The name of the result type as a string

to_ir(ir_type: IRType = IRType.JAQCD, serialization_properties: SerializationProperties | None = None, **kwargs) → Any

Returns IR object of the result type

Parameters:

• ir_type (IRType) – The IRType to use for converting the result type object to its IR representation. Defaults to IRType.JAQCD.

• serialization_properties (SerializationProperties | None) – The serialization properties to use while serializing the object to the IR representation. The serialization properties supplied must correspond to the supplied ir_type. Defaults to None.

Returns:

Any – IR object of the result type

Raises:

ValueError – If the supplied ir_type is not supported, or if the supplied serialization properties don’t correspond to the ir_type.

copy(target_mapping: dict[QubitInput, QubitInput] | None = None, target: QubitSetInput | None = None) → ResultType

Return a shallow copy of the result type.

Note

If target_mapping is specified, then self.target is mapped to the specified qubits. This is useful apply an instruction to a circuit and change the target qubits.

Parameters:

• target_mapping (dict[QubitInput, QubitInput] | None) – A dictionary of qubit mappings to apply to the target. Key is the qubit in this target and the value is what the key is changed to. Default = None.

• target (QubitSetInput | None) – Target qubits for the new instruction.

Returns:

ResultType – A shallow copy of the result type.

Raises:

TypeError – If both target_mapping and target are supplied.

Examples

>>> result_type = ResultType.Probabilities(targets=[0])
>>> new_result_type = result_type.copy()
>>> new_result_type.targets
QubitSet(Qubit(0))
>>> new_result = result_type.copy(target_mapping={0: 5})
>>> new_result_type.target
QubitSet(Qubit(5))
>>> new_result = result_type.copy(target=[5])
>>> new_result_type.target
QubitSet(Qubit(5))

classmethod register_result_type(result_type: type[ResultType]) → None

Register a result type implementation by adding it into the ResultType class.

Parameters:

result_type (type[ResultType]) – ResultType class to register.

class AdjointGradient(observable: Observable, target: list[QubitSetInput] | None = None, parameters: list[str | FreeParameter] | None = None)

Bases: ObservableParameterResultType

The gradient of the expectation value of the provided observable, applied to target, with respect to the given parameter.

Inits an AdjointGradient.

Parameters:

• observable (Observable) – The expectation value of this observable is the function against which parameters in the gradient are differentiated.

• target (list[QubitSetInput] | None) – Target qubits that the result type is requested for. Each term in the target list should have the same number of qubits as the corresponding term in the observable. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

• parameters (list[Union[str, FreeParameter]] | None) – The free parameters in the circuit to differentiate with respect to. Default: all.

Raises:

ValueError – If the observable’s qubit count does not equal the number of target qubits, or if target=None and the observable’s qubit count is not 1.

Examples

>>> ResultType.AdjointGradient(observable=Observable.Z(),
                            target=0, parameters=["alpha", "beta"])

>>> tensor_product = Observable.Y() @ Observable.Z()
>>> hamiltonian = Observable.Y() @ Observable.Z() + Observable.H()
>>> ResultType.AdjointGradient(
>>>     observable=tensor_product,
>>>     target=[[0, 1], [2]],
>>>     parameters=["alpha", "beta"],
>>> )

static adjoint_gradient(observable: Observable, target: list[QubitSetInput] | None = None, parameters: list[str | FreeParameter] | None = None) → ResultType

Registers this function into the circuit class.

Parameters:

• observable (Observable) – The expectation value of this observable is the function against which parameters in the gradient are differentiated.

• target (list[QubitSetInput] | None) – Target qubits that the result type is requested for. Each term in the target list should have the same number of qubits as the corresponding term in the observable. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

• parameters (list[Union[str, FreeParameter]] | None) – The free parameters in the circuit to differentiate with respect to. Default: all.

Returns:

ResultType – gradient computed via adjoint differentiation as a requested result type

Examples

>>> alpha, beta = FreeParameter('alpha'), FreeParameter('beta')
>>> circ = Circuit().h(0).h(1).rx(0, alpha).yy(0, 1, beta).adjoint_gradient(
>>>     observable=Observable.Z(), target=[0], parameters=[alpha, beta]
>>> )

class Amplitude(state: list[str])

Bases: ResultType

The amplitude of the specified quantum states as a requested result type. This is available on simulators only when shots=0.

Initializes an Amplitude.

Parameters:

state (list[str]) – list of quantum states as strings with “0” and “1”

Raises:

ValueError – If state is None or an empty list, or state is not a list of strings of ‘0’ and ‘1’

Examples

>>> ResultType.Amplitude(state=['01', '10'])

static amplitude(state: list[str]) → ResultType

Registers this function into the circuit class.

Parameters:

state (list[str]) – list of quantum states as strings with “0” and “1”

Returns:

ResultType – state vector as a requested result type

Examples

>>> circ = Circuit().amplitude(state=["01", "10"])

property state: list[str]

class DensityMatrix(target: QubitSetInput | None = None)

Bases: ResultType

The full density matrix as a requested result type. This is available on simulators only when shots=0.

Inits a DensityMatrix.

Parameters:

target (QubitSetInput | None) – The target qubits of the reduced density matrix. Default is None, and the full density matrix is returned.

Examples

>>> ResultType.DensityMatrix(target=[0, 1])

static density_matrix(target: QubitSetInput | None = None) → ResultType

Registers this function into the circuit class.

Parameters:

target (QubitSetInput | None) – The target qubits of the reduced density matrix. Default is None, and the full density matrix is returned.

Returns:

ResultType – density matrix as a requested result type

Examples

>>> circ = Circuit().density_matrix(target=[0, 1])

property target: QubitSet

class Expectation(observable: Observable, target: QubitSetInput | None = None)

Bases: ObservableResultType

Expectation of the specified target qubit set and observable as the requested result type.

If no targets are specified, the observable must operate only on 1 qubit and it is applied to all qubits in parallel. Otherwise, the number of specified targets must be equivalent to the number of qubits the observable can be applied to.

For shots>0, this is calculated by measurements. For shots=0, this is supported only by simulators and represents the exact result.

See braket.circuits.observables module for all of the supported observables.

Inits an Expectation.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Examples

>>> ResultType.Expectation(observable=Observable.Z(), target=0)

>>> tensor_product = Observable.Y() @ Observable.Z()
>>> ResultType.Expectation(observable=tensor_product, target=[0, 1])

static expectation(observable: Observable, target: QubitSetInput | None = None) → ResultType

Registers this function into the circuit class.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Returns:

ResultType – expectation as a requested result type

Examples

>>> circ = Circuit().expectation(observable=Observable.Z(), target=0)

class Probability(target: QubitSetInput | None = None)

Bases: ResultType

Probability in the computational basis as the requested result type.

It can be the probability of all states if no targets are specified, or the marginal probability of a restricted set of states if only a subset of all qubits are specified as targets.

For shots>0, this is calculated by measurements. For shots=0, this is supported only on simulators and represents the exact result.

Inits a Probability.

Parameters:

target (QubitSetInput | None) – The target qubits that the result type is requested for. Default is None, which means all qubits for the circuit.

Examples

>>> ResultType.Probability(target=[0, 1])

static probability(target: QubitSetInput | None = None) → ResultType

Registers this function into the circuit class.

Parameters:

target (QubitSetInput | None) – The target qubits that the result type is requested for. Default is None, which means all qubits for the circuit.

Returns:

ResultType – probability as a requested result type

Examples

>>> circ = Circuit().probability(target=[0, 1])

property target: QubitSet

class Sample(observable: Observable, target: QubitSetInput | None = None)

Bases: ObservableResultType

Sample of specified target qubit set and observable as the requested result type.

If no targets are specified, the observable must operate only on 1 qubit and it is applied to all qubits in parallel. Otherwise, the number of specified targets must equal the number of qubits the observable can be applied to.

This is only available for shots>0.

See braket.circuits.observables module for all of the supported observables.

Inits a Sample.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Examples

>>> ResultType.Sample(observable=Observable.Z(), target=0)

>>> tensor_product = Observable.Y() @ Observable.Z()
>>> ResultType.Sample(observable=tensor_product, target=[0, 1])

static sample(observable: Observable, target: QubitSetInput | None = None) → ResultType

Registers this function into the circuit class.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Returns:

ResultType – sample as a requested result type

Examples

>>> circ = Circuit().sample(observable=Observable.Z(), target=0)

class StateVector

Bases: ResultType

The full state vector as a requested result type. This is available on simulators only when shots=0.

Initializes a ResultType.

Parameters:

ascii_symbols (list[str]) – ASCII string symbols for the result type. This is used when printing a diagram of circuits.

Raises:

ValueError – ascii_symbols is None

static state_vector() → ResultType

Registers this function into the circuit class.

Returns:

ResultType – state vector as a requested result type

Examples

>>> circ = Circuit().state_vector()

class Variance(observable: Observable, target: QubitSetInput | None = None)

Bases: ObservableResultType

Variance of specified target qubit set and observable as the requested result type.

If no targets are specified, the observable must operate only on 1 qubit and it is applied to all qubits in parallel. Otherwise, the number of targets specified must equal the number of qubits that the observable can be applied to.

For shots>0, this is calculated by measurements. For shots=0, this is supported only by simulators and represents the exact result.

See braket.circuits.observables module for all of the supported observables.

Inits a Variance.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Raises:

ValueError – If the observable’s qubit count does not equal the number of target qubits, or if target=None and the observable’s qubit count is not 1.

Examples

>>> ResultType.Variance(observable=Observable.Z(), target=0)

>>> tensor_product = Observable.Y() @ Observable.Z()
>>> ResultType.Variance(observable=tensor_product, target=[0, 1])

static variance(observable: Observable, target: QubitSetInput | None = None) → ResultType

Registers this function into the circuit class.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must only operate on 1 qubit and it will be applied to all qubits in parallel

Returns:

ResultType – variance as a requested result type

Examples

>>> circ = Circuit().variance(observable=Observable.Z(), target=0)

class braket.circuits.result_type.ObservableResultType(ascii_symbols: list[str], observable: Observable, target: QubitSetInput | None = None)

Bases: ResultType

Result types with observables and targets. If no targets are specified, the observable must only operate on 1 qubit and it will be applied to all qubits in parallel. Otherwise, the number of specified targets must be equivalent to the number of qubits the observable can be applied to.

See braket.circuits.observables module for all of the supported observables.

Initializes an ObservableResultType.

Parameters:

• ascii_symbols (list[str]) – ASCII string symbols for the result type. This is used when printing a diagram of circuits.

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must only operate on 1 qubit and it will be applied to all qubits in parallel

Raises:

ValueError – if target=None and the observable’s qubit count is not 1. Or, if target!=None and the observable’s qubit count and the number of target qubits are not equal. Or, if target!=None and the observable’s qubit count and the number of ascii_symbols are not equal.

property observable: Observable

property target: QubitSet

class braket.circuits.result_type.ObservableParameterResultType(ascii_symbols: list[str], observable: Observable, target: QubitSetInput | None = None, parameters: list[str | FreeParameter] | None = None)

Bases: ObservableResultType

Result types with observables, targets and parameters. If no targets are specified, the observable must only operate on 1 qubit and it will be applied to all qubits in parallel. Otherwise, the number of specified targets must be equivalent to the number of qubits the observable can be applied to. If no parameters are specified, observable will be applied to all the free parameters.

See braket.circuits.observables module for all of the supported observables.

Initializes an ObservableResultType.

Parameters:

• ascii_symbols (list[str]) – ASCII string symbols for the result type. This is used when printing a diagram of circuits.

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must only operate on 1 qubit and it will be applied to all qubits in parallel

Raises:

ValueError – if target=None and the observable’s qubit count is not 1. Or, if target!=None and the observable’s qubit count and the number of target qubits are not equal. Or, if target!=None and the observable’s qubit count and the number of ascii_symbols are not equal.

property parameters: list[str]