propaq.truncation

Composable truncation operators, applied together after every gate by both the numerical and the surrogate propagators.

See the truncation guide.

truncation

Composable truncation operators shared by the numerical and surrogate propagators.

Classes:

Name	Description
WeightTruncator	Drop whole Pauli/Majorana terms whose operator weight exceeds weight.
CoefficientTruncator	Drop contributions with coefficient magnitude below coefficient.
TermBudget	Live-term floor: below min_terms terms, all other lossy truncators
FrequencyTruncator	Drop monomials whose frequency (trig-factor count) exceeds frequency. Surrogate-only.
Simplify	Real (lossless) algebraic simplification, surrogate-only.
NativeTruncator	Truncation policy backed by a dynamically loaded C, Rust, or
Truncator	Abstract base class for composable truncation operators.
TruncationPolicy	Controls when and how terms are discarded during propagation.
FrequencyTruncationPolicy
ResolvedTruncation	A truncator pipeline collapsed to the values the emit gate compares against.

Functions:

Name	Description
resolve_truncation	Normalize the flexible truncation argument into a truncator list.

WeightTruncator

Bases: WeightTruncator

Drop whole Pauli/Majorana terms whose operator weight exceeds weight. Applies to both propagators.

A term with weight w is exponentially unlikely in w to contribute to the final state, which is why this is a useful truncation criterion for larger circuits.

Attributes:

Name	Type	Description
weight	int | None

weight property

weight: int | None

CoefficientTruncator

Bases: CoefficientTruncator

Drop contributions with coefficient magnitude below coefficient.

Attributes:

Name	Type	Description
coefficient	float | None

coefficient property

coefficient: float | None

TermBudget

Bases: TermBudget

Live-term floor: below min_terms terms, all other lossy truncators (WeightTruncator/CoefficientTruncator/NativeTruncator) are suppressed, keeping propagation exact until the operator has had room to grow. None disables the floor.

Attributes:

Name	Type	Description
min_terms	int | None

min_terms property

min_terms: int | None

FrequencyTruncator

Bases: FrequencyTruncator

Drop monomials whose frequency (trig-factor count) exceeds frequency. Surrogate-only.

Attributes:

Name	Type	Description
frequency	int | None

frequency property

frequency: int | None

Simplify

Bases: Simplify

Real (lossless) algebraic simplification, surrogate-only.

At every flush, collapses monomials sharing the same canonical trig-factor run into one, summing their scalars.

Attributes:

Name	Type	Description
enabled	bool

enabled property

enabled: bool

NativeTruncator

Bases: NativeTruncator

Truncation policy backed by a dynamically loaded C, Rust, or AOT-compiled Julia shared library

Methods:

Name	Description
keep_term	Delegate to the plugin's propaq_truncator_keep.

Attributes:

Name	Type	Description
abi_version	int	The ABI version the loaded plugin declared.
depends	int	The dependency bitmask the plugin declared: 1 = reads the term's key,

abi_version property

abi_version: int

The ABI version the loaded plugin declared.

depends property

depends: int

The dependency bitmask the plugin declared: 1 = reads the term's key, 2 = reads the layer index. 0 means weight and magnitude alone.

keep_term method descriptor

keep_term(basis_kind: int, words: Sequence[int], n_units: int, weight: int, coeff_magnitude: float, layer_index: int = 0, n_layers: int = 0) -> bool

Delegate to the plugin's propaq_truncator_keep.

Exposed so a plugin can be exercised from Python without running a circuit; propagation calls the same entry point directly from the pool.

Parameters:

Name	Type	Description	Default
basis_kind	int	0 for Pauli, 1 for Majorana.	required
words	Sequence[int]	The term's raw basis-string words, two bits per unit. Ignored (and passed as NULL) unless the plugin declared it reads keys.	required
n_units	int	Qubits (Pauli) or modes (Majorana) of the register.	required
weight	int	The term's weight.	required
coeff_magnitude	float	The term's coefficient magnitude.	required
layer_index	int	Zero-based circuit layer.	0
n_layers	int	Layers in the circuit.	0

Truncator

Bases: ABC

Abstract base class for composable truncation operators.

TruncationPolicy

Controls when and how terms are discarded during propagation.

Parameters:

Name	Type	Description	Default
weight_cutoff		Discard terms with Pauli weight strictly greater than this value. None disables weight-based truncation.	required
coeff_cutoff		Discard terms with |coefficient| strictly less than this value.	required
min_terms		Live-term floor below which truncation is suppressed.	required

Methods:

Name	Description
should_truncate	Return True if a term with weight and |coefficient| abs_coeff should be discarded.

Attributes:

Name	Type	Description
coeff_cutoff	float
min_terms	int | None
weight_cutoff	int | None

coeff_cutoff property

coeff_cutoff: float

min_terms property

min_terms: int | None

weight_cutoff property

weight_cutoff: int | None

should_truncate method descriptor

should_truncate(weight: int, abs_coeff: float) -> bool

Return True if a term with weight and |coefficient| abs_coeff should be discarded.

FrequencyTruncationPolicy

Attributes:

Name	Type	Description
max_frequency	int | None	Drop monomials with more than this many trig factors (None = no limit).
min_terms	int | None	Live-term floor below which truncation is suppressed entirely.
weight_cutoff	int | None	Drop Pauli/Majorana terms with weight exceeding this value (None = no limit).

max_frequency property

max_frequency: int | None

Drop monomials with more than this many trig factors (None = no limit).

min_terms property

min_terms: int | None

Live-term floor below which truncation is suppressed entirely.

weight_cutoff property

weight_cutoff: int | None

Drop Pauli/Majorana terms with weight exceeding this value (None = no limit).

ResolvedTruncation dataclass

ResolvedTruncation(weight_cutoff: int | None = None, coeff_cutoff: float | None = None, min_terms: int | None = None)

A truncator pipeline collapsed to the values the emit gate compares against.

Methods:

Name	Description
from_truncators	Collapse a truncator list into one ResolvedTruncation, last-wins per type.
at_size	The cutoff to use when emitting children of a term sum with n_live live terms.
admits	True if a term of this weight and coefficient belongs in the store.

from_truncators classmethod

from_truncators(truncators: Sequence[_Truncator]) -> ResolvedTruncation

Collapse a truncator list into one ResolvedTruncation, last-wins per type.

Parameters:

Name	Type	Description	Default
truncators	Sequence[_Truncator]	The truncators, as returned by resolve_truncation.	required

at_size

at_size(n_live: int) -> ResolvedTruncation

The cutoff to use when emitting children of a term sum with n_live live terms.

Parameters:

Name	Type	Description	Default
n_live	int	The number of terms live before this emission.	required

Returns:

Type	Description
ResolvedTruncation	self unchanged, unless min_terms is set and n_live is
ResolvedTruncation	below it, in which case weight_cutoff and coeff_cutoff are
ResolvedTruncation	suppressed (returned as None) and min_terms is kept.

admits

admits(weight: int, coeff: complex) -> bool

True if a term of this weight and coefficient belongs in the store.

Parameters:

Name	Type	Description	Default
weight	int	The term's weight.	required
coeff	complex	The term's coefficient.	required

resolve_truncation

resolve_truncation(truncation: object | Sequence[object] | TruncationPolicy | None = None) -> list[_Truncator]

Normalize the flexible truncation argument into a truncator list.

Parameters:

Name	Type	Description	Default
truncation	object | Sequence[object] | TruncationPolicy | None	The pipeline, in any of the accepted forms.	None

Returns:

Type	Description
list[_Truncator]	The truncators, in application order.

Raises:

Type	Description
TypeError	If truncation (or one of its elements) is not one of the accepted forms, or is a surrogate-only (FrequencyTruncator/ Simplify) or engine-only (NativeTruncator) truncator