qrunch.quantum.operators.pauli.mixed_precision

Utilities for splitting a HermitianPauliSum into precision tiers for mixed-precision evaluation.

The core idea is to partition Pauli terms by their coefficient magnitude so that terms with tiny coefficients (which contribute less to the final energy) can be evaluated with cheaper, lower-precision arithmetic (e.g. single precision float32), while terms with large coefficients preserve accuracy through double precision `float64`.

Two splitting strategies are provided:

  1. Absolute-threshold splitting (split_by_absolute_thresholds) — each term is assigned to the tier whose lower bound its |coefficient| exceeds.

  2. 1-norm budget splitting (split_operator_by_norm_budget) — terms are sorted by |coefficient| and accumulated from smallest to largest. The cumulative 1-norm is compared against user-specified fractions of the total 1-norm to decide tier boundaries. This gives direct control over the worst-case error budget per tier:

    \[\begin{split}\\varepsilon_{\\text{tier}} \\le \\sum_{i \\in \\text{tier}} |c_i| \\cdot \\varepsilon_{\\text{dtype}}\end{split}\]

Functions

split_operator_by_norm_budget(pauli_sum, *)

Split a HermitianPauliSum into precision tiers based on cumulative 1-norm budgets.

Classes

MixedPrecisionSplit

Result of splitting a HermitianPauliSum into precision tiers.

PrecisionTier

A single precision tier holding a sub-Hamiltonian.

PrecisionTierName

Enum for precision tier names.
class MixedPrecisionSplit

Bases: object

Result of splitting a HermitianPauliSum into precision tiers.

Parameters:

  • tiers – Non-empty tuple of PrecisionTier objects ordered from highest to lowest precision. Tiers with zero terms are omitted.

  • original_one_norm – The 1-norm (sum of |c_i|) of the original operator.

__init__(tiers: tuple[PrecisionTier, ...], original_one_norm: float) → None
Parameters:
Return type:

None

original_one_norm: float
tiers: tuple[PrecisionTier, ...]
class PrecisionTier

Bases: object

A single precision tier holding a sub-Hamiltonian.

Parameters:

  • name – Human-readable tier name ("high", "medium", or "low").

  • pauli_sum – The HermitianPauliSum containing only the terms assigned to this tier.

__init__(name: PrecisionTierName, pauli_sum: HermitianPauliSum) → None
Parameters:
Return type:

None

name: PrecisionTierName
pauli_sum: HermitianPauliSum
class PrecisionTierName

Bases: Enum

Enum for precision tier names.

HIGH = 'high'
LOW = 'low'
MEDIUM = 'medium'
split_operator_by_norm_budget(pauli_sum: HermitianPauliSum, *, low_norm_fraction: float = 0.01, medium_norm_fraction: float = 0.1) → MixedPrecisionSplit

Split a HermitianPauliSum into precision tiers based on cumulative 1-norm budgets.

Terms are sorted by ascending |coefficient|. Walking from the smallest term upwards, the cumulative 1-norm is tracked:

  • While the cumulative 1-norm is at most low_norm_fraction of the total 1-norm, terms are assigned to the low tier.

  • While it is at most low_norm_fraction + medium_norm_fraction of the total, terms are assigned to the medium tier.

  • All remaining terms go to the high tier.

This gives a rough principled error guarantee. For each tier the worst-case absolute error contributed by rounding is bounded by:

\[\begin{split}\\varepsilon_{\\text{tier}} \\le \\sum_{i \\in \\text{tier}} |c_i| \\cdot \\varepsilon_{\\text{rel}}(c_i)\end{split}\]

where \(\\varepsilon_{\\text{rel}}(c_i)\) is the relative rounding error for the value \(c_i\) in the tier’s floating-point format. Because floating-point numbers distribute their bits between exponent and significand, the relative precision depends on the magnitude of each coefficient — not just on a single machine-epsilon constant. For example, bfloat16 has a 7-bit significand giving \(\\varepsilon_{\\text{rel}} = 2^{-7} \\approx 7.8 \\times 10^{-3}\) for values near a power of two, while float32 uses 23 significand bits (\(\\varepsilon_{\\text{rel}} = 2^{-23} \\approx 1.2 \\times 10^{-7}\)).

Parameters:

  • pauli_sum (HermitianPauliSum) – The operator to split.

  • low_norm_fraction (float) – Fraction of the total 1-norm allocated to the bfloat16 tier.

  • medium_norm_fraction (float) – Fraction of the total 1-norm allocated to the float32 tier.

Return type:

MixedPrecisionSplit