.. _sec_measurement: =================== Quantum Measurement =================== Built-in quantum gates have no side effects on classical execution; the only way to extract information from a quantum state is through measurement or simulation state extraction. Ket offers three primary methods for evaluating a quantum state: the :func:`~ket.operations.measure` function for single-shot measurements, the :func:`~ket.operations.sample` function for multi-shot measurements, and the :func:`~ket.operations.exp_value` function to compute the expectation value of a Hamiltonian. Additionally, Ket provides the :func:`~ket.operations.dump` function, which returns the exact state vector from a simulator. ----------------------- Single-Shot Measurement ----------------------- The :func:`~ket.operations.measure` function takes a :class:`~ket.base.Quant` as input and returns a :class:`~ket.base.Measurement` object. This object references the result, acting similarly to an asynchronous programming Future. In live execution mode, the measurement result is evaluated immediately and can be retrieved using the :meth:`~ket.base.Measurement.get` method, which returns an integer representing the measured state. In batch mode, calling :meth:`~ket.base.Measurement.get` triggers the quantum execution. Note that once execution starts in batch mode, all :class:`~ket.base.Measurement` objects associated with the process are resolved, but the quantum process is terminated, preventing further operations. After the result becomes available, the :meth:`~ket.base.Measurement.get` method can be called as often as needed. .. code-block:: python process = Process() a, b = process.alloc(2) CNOT(H(a), b) # Prepare a Bell state m = measure(a + b).get() # The result will be either 0 or 3 Whether a qubit can be manipulated after a measurement depends on the target execution backend. Typically, on physical quantum hardware, the qubit is invalidated after measurement. However, in the KBW simulator, the qubit collapses to the measured state and remains available for subsequent operations. Single-shot measurement is particularly useful for implementing fault-tolerant algorithms, quantum communication protocols, and quantum error correction routines. ------------------- Multi-Shot Sampling ------------------- Because many quantum algorithms output a probability distribution rather than a single deterministic state, the :func:`~ket.operations.sample` function is often more appropriate. The :func:`~ket.operations.sample` function returns a :class:`~ket.base.Samples` object, which operates similarly to the :class:`~ket.base.Measurement` class. Calling the :meth:`~ket.base.Samples.get` method triggers the quantum execution and returns a dictionary where the measurement result (as an ``int``) is mapped to its exact observation count. The :meth:`~ket.base.Samples.histogram` method generates a plot of the measurement distribution. .. code-block:: python process = Process() a, b = process.alloc(2) CNOT(H(a), b) # Prepare a Bell state sample(a + b, 100).histogram("bin") # Histogram of 100 shots On quantum hardware, sampling generally terminates the quantum process. The KBW simulator allows execution to continue after a sample; however, each sample represents an independent run. Consequently, entanglement correlations cannot be detected between two different samples, only within a single sample itself. .. _subsec_exp: -------------------------------- Expectation Values and Gradients -------------------------------- Calculating expectation values is crucial for near-term quantum algorithms, such as Variational Quantum Algorithms and Quantum Machine Learning :cite:`amaral2026`. To calculate an expectation value, an observable is required. The :func:`~ket.operations.exp_value` function takes a :class:`~ket.expv.Hamiltonian` object as input and returns an :class:`~ket.expv.ExpValue` object. Calling the :meth:`~ket.expv.ExpValue.get` method triggers execution and returns the calculated expectation value as a float. .. code-block:: python # chsh_obs is an instance of a Hamiltonian object exp_value(chsh_obs).get() # e.g., 2.828427125 Hamiltonian construction is detailed in Section :ref:`sec_hamiltonian`. Note that the :func:`~ket.operations.exp_value` function requires only the observable as input; the target qubit references are inherently encapsulated within the Hamiltonian object itself. A key feature of expectation values in Ket is the ability to calculate parameter gradients, which is essential for gradient-based optimization in Variational Quantum Algorithms. Gradient calculation is handled by the target backend via Native Simulation (*e.g.*, tensor networks) or automatically via the Parameter-Shift Rule :cite:`mitarai2018` applied by Libket. To enable gradient calculation with the KBW simulator, the keyword argument ``gradient=True`` must be provided when instantiating the process. .. code-block:: python process = Process(gradient=True) theta = process.param(0.5) # Define a variational parameter # ... perform expectation value calculation circuit ... grad = theta.grad # Retrieve the calculated gradient ----------------------- State Vector Inspection ----------------------- Ket provides the :func:`~ket.operations.dump` function to retrieve the full state vector from a simulator. Naturally, this is physically impossible on actual quantum hardware. The :func:`~ket.operations.dump` function is not intended to be a substitute for measurement. It does not collapse the quantum state, and extracting a subset of entangled qubits via a dump will not yield the expected partial trace of the system. Nevertheless, it is an invaluable tool for debugging. It returns a :class:`~ket.quantumstate.QuantumState` object equipped with useful methods such as :meth:`~ket.quantumstate.QuantumState.get` to view complex probability amplitudes, :meth:`~ket.quantumstate.QuantumState.sphere` to plot a Bloch sphere for single qubits, and :meth:`~ket.quantumstate.QuantumState.show` to output LaTeX representations of the state.