Analysis -- Distance Metrics & Fidelity

Functions for comparing probability distributions, quantum measurement outcomes, and quantum-state fidelities.

hellinger_distance

Compute the Hellinger distance between two probability distributions. The Hellinger distance measures the similarity between two discrete distributions and is bounded in $[0,1]$.

For discrete distributions $p$ and $q$:

$$H(p,q)=\frac{1}{\sqrt{2}}\sqrt{\sum _x{(\sqrt{p(x)}-\sqrt{q(x)})}^2}$$

Signature (dict with integer keys)

hellinger_distance(
    p: dict[int, float],
    q: dict[int, float],
) -> float

Signature (dict with string keys)

hellinger_distance(
    p: dict[str, float],
    q: dict[str, float],
) -> float

Parameters

Parameter	Type	Description
p	dict[int, float] or dict[str, float]	The first probability distribution, represented as a dictionary mapping outcomes to probabilities.
q	dict[int, float] or dict[str, float]	The second probability distribution, represented as a dictionary mapping outcomes to probabilities.

Returns

float -- The Hellinger distance between the two distributions. A value of 0 means the distributions are identical; a value of 1 means they have no overlap.

Examples

from pyqpanda3.quantum_info import hellinger_distance

p = {0: 0.5, 1: 0.5}
q = {0: 0.3, 1: 0.7}

d = hellinger_distance(p, q)
print(d)

Output:

0.1452366588341136

---

hellinger_fidelity

Compute the Hellinger fidelity between two probability distributions. The Hellinger fidelity is related to the Hellinger distance by $F_H(p,q)={(1-H(p,q{)}^2)}^2$, or equivalently:

$$F_H(p,q)={\left(\sum _x\sqrt{p(x)q(x)}\right)}^2$$

Signature (dict with integer keys)

hellinger_fidelity(
    p: dict[int, float],
    q: dict[int, float],
) -> float

Signature (dict with string keys)

hellinger_fidelity(
    p: dict[str, float],
    q: dict[str, float],
) -> float

Parameters

Parameter	Type	Description
p	dict[int, float] or dict[str, float]	The first probability distribution.
q	dict[int, float] or dict[str, float]	The second probability distribution.

Returns

float -- The Hellinger fidelity between the two distributions. A value of 1 means the distributions are identical; a value of 0 means they have no overlap.

Examples

from pyqpanda3.quantum_info import hellinger_fidelity

p = {0: 0.5, 1: 0.5}
q = {0: 0.3, 1: 0.7}

f = hellinger_fidelity(p, q)
print(f)  # 0.96

Output:

0.958257569495584

---

KL_divergence

Compute the Kullback-Leibler (KL) divergence between two probability distributions.

For discrete distributions:

$$D_{\mathrm{KL}}(p|q)=\sum _{x}p(x)\log \frac{p(x)}{q(x)}$$

For continuous distributions:

$$D_{\mathrm{KL}}(p|q)=\int p(x)\log \frac{p(x)}{q(x)}dx$$

Note: The KL divergence is not symmetric: $D_{\mathrm{KL}}(p|q)\ne D_{\mathrm{KL}}(q|p)$.

Signature (discrete)

KL_divergence(
    p: list[float],
    q: list[float],
) -> float

Signature (continuous)

KL_divergence(
    p_pdf: Callable[[float], float],
    q_pdf: Callable[[float], float],
    x_start: float,
    x_end: float,
    dx: float = 1e-4,
) -> float

Parameters (discrete)

Parameter	Type	Description
p	list[float]	The first discrete probability distribution.
q	list[float]	The second discrete probability distribution.

Parameters (continuous)

Parameter	Type	Description
p_pdf	Callable[[float], float]	The probability density function of the first distribution $p(x)$.
q_pdf	Callable[[float], float]	The probability density function of the second distribution $q(x)$.
x_start	float	The lower bound of the integration interval.
x_end	float	The upper bound of the integration interval.
dx	float	The step size for numerical integration. Defaults to 1e-4.

Returns

float -- The KL divergence of distribution p relative to distribution q. The value is non-negative; it is zero if and only if the distributions are identical.

Examples

Discrete distributions:

from pyqpanda3.quantum_info import KL_divergence

p = [0.5, 0.5]
q = [0.3, 0.7]

d = KL_divergence(p, q)
print(d)

Output:

0.08717669357238891

Continuous distributions:

import math
from pyqpanda3.quantum_info import KL_divergence

def p_pdf(x):
    return math.exp(-x) if x >= 0 else 0.0

def q_pdf(x):
    return 0.5 * math.exp(-0.5 * x) if x >= 0 else 0.0

d = KL_divergence(p_pdf, q_pdf, 0.0, 20.0, 1e-4)
print(d)

Output:

0.19318185912583796

state_fidelity

Compute the fidelity between two quantum states. Four overloads cover every combination of density matrices and state vectors. The state-vector fidelity is $|⟨{\psi }_2|{\psi }_1⟩{|}^2$; the density-matrix fidelity uses the standard Uhlmann definition.

Note: a flat (1-D) input is interpreted as a state vector; a 2-D square matrix is interpreted as a density matrix. The matrix overloads are registered before the state-vector overloads to avoid mis-dispatching nested Python sequences to the state-vector branch.

Signature (density matrix x density matrix)

state_fidelity(matrix1, matrix2, validate: bool = True) -> float

Signature (density matrix x state vector)

state_fidelity(matrix, state, validate: bool = True) -> float

Signature (state vector x density matrix)

state_fidelity(state, matrix, validate: bool = True) -> float

Signature (state vector x state vector)

state_fidelity(state1, state2, validate: bool = True) -> float

Parameters

Parameter	Type	Description
matrix / matrix1 / matrix2	2-D square matrix	A density matrix.
state / state1 / state2	1-D complex array	A state-vector amplitude array.
validate	bool	Whether to validate normalization / positivity (default True). A failed check raises RuntimeError; set to False to skip validation, in which case the result may exceed [0, 1].

Returns

float -- the fidelity between the two states, normally in [0, 1] (it can exceed this range only when validate=False and the input is non-physical).

Example

from pyqpanda3.quantum_info import state_fidelity

plus = [[0.5, 0.5], [0.5, 0.5]]   # |+><+|
zero = [[1.0, 0.0], [0.0, 0.0]]   # |0><0|

# density matrix x density matrix
print(round(state_fidelity(plus, zero), 6))

# density matrix x state vector
print(round(state_fidelity(zero, [1.0, 0.0]), 6))

# state vector x state vector (orthogonal, fidelity is 0)
print(round(state_fidelity([0.5, 0.5, 0.5, 0.5], [0.5, -0.5, 0.5, -0.5]), 6))

Output:

0.5
1.0
0.0

See Also

• StateVector
• DensityMatrix