`propaq.propagators`¶

The propagators. A numerical propagator back-propagates an observable through a concrete circuit; a surrogate propagator compiles a parameterized circuit into a reusable symbolic model.

See the quickstart and the surrogate guide.

propagators ¶

Core propagators for quantum simulation.

Classes:

Name	Description
`PauliPropagator`	Back-propagates Pauli observables through quantum circuits in the Heisenberg picture.
`MajoranaPropagator`	Back-propagates Majorana observables through quantum circuits in the Heisenberg picture.
`PauliSurrogatePropagator`	Back-propagates Pauli observables symbolically, producing a compiled model
`MajoranaSurrogatePropagator`	Back-propagates Majorana observables symbolically.
`AbstractPropagator`	Heisenberg-picture propagation over an arbitrary operator basis.

Attributes:

Name	Type	Description
`CircuitLike`	`TypeAlias`

CircuitLike `module-attribute` ¶

CircuitLike: TypeAlias = _HasLayers[RotationT] | _HasRotations[RotationT] | Sequence[RotationT] | Sequence[Sequence[RotationT]]

PauliPropagator ¶

Back-propagates Pauli observables through quantum circuits in the Heisenberg picture.

Parameters:

Name	Description	Default
`noise`	Optional noise model (UniformNoiseModel, GateNoiseModel, or custom).	required
`truncation`	A list of truncators (WeightTruncator, CoefficientTruncator, TermBudget), a single such truncator, a legacy TruncationPolicy (decomposed), or None. The symbolic-only FrequencyTruncator is rejected.	required
`n_threads`	Number of worker threads. Defaults to the system thread count.	required
`logger`	Optional Logger for verbose JSON Lines event logging.	required
`pin_threads`	Bind each worker to its own CPU.	required
`progress_bar`	Draw a tqdm bar over the gate loop.	required
`progress_every`	Gates between progress bar ticks. Defaults to 1.	required

Methods:

Name	Description
`expectation_value`	Compute the expectation value of observable in the state prepared by circuit.
`propagate`	Back-propagate circuit through observable, returning the evolved term sum.
`set_noise`	Set the noise model for this propagator.
`set_truncation`	Replace the truncation pipeline (accepts the same forms as the

Attributes:

Name	Type	Description
`noise`	`Any \| None`	The noise model used during propagation, if any.
`truncators`	`list[Any]`	The active truncation pipeline as a list of truncator objects.

noise `property` ¶

noise: Any | None

The noise model used during propagation, if any.

truncators `property` ¶

truncators: list[Any]

The active truncation pipeline as a list of truncator objects.

expectation_value `method descriptor` ¶

expectation_value(observable: PauliTermSum, circuit: Any, initial_state: Any | None = None, filename: str | None = None) -> PropagationResult

Compute the expectation value of observable in the state prepared by circuit.

Parameters:

Name	Type	Description	Default
`observable`	`PauliTermSum`	The Pauli observable.	required
`circuit`	`Any`	A PauliCircuit applied to the reference state.	required
`initial_state`	`Any \| None`	Computational basis reference state as a bitstring integer.	`None`
`filename`	`str \| None`	If given, save the final terms to a gzip-compressed binary file at this path.	`None`

propagate `method descriptor` ¶

propagate(observable: PauliTermSum, circuit: Any, filename: str | None = None) -> PauliTermSum

Back-propagate circuit through observable, returning the evolved term sum.

Parameters:

Name	Type	Description	Default
`observable`	`PauliTermSum`	The Pauli observable to back-propagate.	required
`circuit`	`Any`	A PauliCircuit whose rotations are applied in reverse.	required
`filename`	`str \| None`	If given, save the final terms to a gzip-compressed binary file at this path.	`None`

set_noise `method descriptor` ¶

set_noise(noise: Any | None = None) -> None

Set the noise model for this propagator.

set_truncation `method descriptor` ¶

set_truncation(truncation: Any | None = None) -> None

Replace the truncation pipeline (accepts the same forms as the constructor's truncation).

MajoranaPropagator ¶

Back-propagates Majorana observables through quantum circuits in the Heisenberg picture.

Parameters:

Name	Description	Default
`noise`	Optional noise model (UniformNoiseModel, GateNoiseModel, or custom).	required
`truncation`	A list of truncators (WeightTruncator, CoefficientTruncator, TermBudget), a single such truncator, a legacy TruncationPolicy (decomposed), or None. The symbolic-only FrequencyTruncator is rejected.	required
`n_threads`	Number of worker threads. Defaults to the system thread count.	required
`logger`	Optional Logger for verbose JSON Lines event logging.	required
`pin_threads`	Bind each worker to its own CPU.	required
`progress_bar`	Draw a tqdm bar over the gate loop.	required
`progress_every`	Gates between progress bar ticks. Defaults to 1.	required

Methods:

Name	Description
`expectation_value`	Compute the expectation value of observable in the state prepared by circuit.
`propagate`	Back-propagate circuit through observable, returning the evolved term sum.
`set_truncation`	Replace the truncation pipeline (accepts the same forms as the

Attributes:

Name	Type	Description
`noise`	`Any \| None`
`truncators`	`list[Any]`	The active truncation pipeline as a list of truncator objects.

noise `property` ¶

noise: Any | None

truncators `property` ¶

truncators: list[Any]

The active truncation pipeline as a list of truncator objects.

expectation_value `method descriptor` ¶

expectation_value(observable: MajoranaTermSum, circuit: Any, initial_state: Any | None = None, filename: str | None = None) -> PropagationResult

Compute the expectation value of observable in the state prepared by circuit.

Parameters:

Name	Type	Description	Default
`observable`	`MajoranaTermSum`	The Majorana observable.	required
`circuit`	`Any`	A MajoranaCircuit applied to the reference state.	required
`initial_state`	`Any \| None`	Fock state as a bitstring integer.	`None`
`filename`	`str \| None`	If given, save the final terms to a gzip-compressed binary file at this path.	`None`

propagate `method descriptor` ¶

propagate(observable: MajoranaTermSum, circuit: Any, filename: str | None = None) -> MajoranaTermSum

Back-propagate circuit through observable, returning the evolved term sum.

Parameters:

Name	Type	Description	Default
`observable`	`MajoranaTermSum`	The Majorana observable to back-propagate.	required
`circuit`	`Any`	A MajoranaCircuit whose rotations are applied in reverse.	required
`filename`	`str \| None`	If given, save the final terms to a gzip-compressed binary file at this path.	`None`

set_truncation `method descriptor` ¶

set_truncation(truncation: Any | None = None) -> None

Replace the truncation pipeline (accepts the same forms as the constructor's truncation).

PauliSurrogatePropagator ¶

Back-propagates Pauli observables symbolically, producing a compiled model that can be re-evaluated for any parameter assignment.

Parameters:

Name	Description	Default
`truncation`	A list of truncator objects (FrequencyTruncator, CoefficientTruncator, WeightTruncator, TermBudget) applied at each flush, a single such truncator, a legacy FrequencyTruncationPolicy (decomposed automatically), or None.	required
`n_threads`	Number of worker threads. Defaults to the system thread count.	required
`logger`	Optional Logger for verbose JSON Lines event logging.	required
`progress_bar`	Draw a tqdm bar over the build's gate loop.	required
`progress_every`	Gates between progress bar ticks. Defaults to 1.	required

Methods:

Name	Description
`build`	Compile the observable back-propagated through the circuit into a SurrogateModel.
`set_truncation`	Replace the truncation pipeline (accepts the same forms as the

Attributes:

Name	Type	Description
`truncators`	`list[Any]`	The active truncation pipeline as a list of truncator objects.

truncators `property` ¶

truncators: list[Any]

The active truncation pipeline as a list of truncator objects.

build `method descriptor` ¶

build(observable: PauliTermSum, circuit: Any, initial_state: Any | None = None) -> PauliSurrogateModel

Compile the observable back-propagated through the circuit into a SurrogateModel.

Parameters:

Name	Type	Description	Default
`observable`	`PauliTermSum`	The Pauli observable to back-propagate.	required
`circuit`	`Any`	A SurrogatePauliCircuit.	required
`initial_state`	`Any \| None`	Fock state as a bitstring integer (default 0).	`None`

set_truncation `method descriptor` ¶

set_truncation(truncation: Any | None = None) -> None

Replace the truncation pipeline (accepts the same forms as the constructor's truncation).

MajoranaSurrogatePropagator ¶

Back-propagates Majorana observables symbolically.

Methods:

Name	Description
`set_truncation`	Replace the truncation pipeline (accepts the same forms as the

Attributes:

Name	Type	Description
`truncators`	`list[Any]`	The active truncation pipeline as a list of truncator objects.

truncators `property` ¶

truncators: list[Any]

The active truncation pipeline as a list of truncator objects.

set_truncation `method descriptor` ¶

set_truncation(truncation: Any | None = None) -> None

Replace the truncation pipeline (accepts the same forms as the constructor's truncation).

AbstractPropagator ¶

AbstractPropagator(noise: UniformNoiseModel | GateNoiseModel | NativeNoiseModel | None = None, truncation: object | Sequence[object] | TruncationPolicy | None = None)

Bases: ABC, Generic[TermT, RotationT]

Heisenberg-picture propagation over an arbitrary operator basis.

Parameters:

Name	Type	Description	Default
`noise`	`UniformNoiseModel \| GateNoiseModel \| NativeNoiseModel \| None`	Optional noise model (`UniformNoiseModel`, `GateNoiseModel`, `NativeNoiseModel`, or any object exposing `damping_factor` / `damping_factor_term`).	`None`
`truncation`	`object \| Sequence[object] \| TruncationPolicy \| None`	A truncator, a sequence of truncators, a `TruncationPolicy`, or None. Surrogate-only and engine-only truncators are rejected	`None`

Construct a propagator with an optional noise model and truncation pipeline.

Methods:

Name	Description
`set_noise`	Replace the noise model.
`set_truncation`	Replace the truncation pipeline.
`apply_gate`	Branch one basis term under one gate
`layers_of`	Normalize a circuit into its gate layers, in Heisenberg application order.
`apply_layer`	Apply one gate to every live term, folding branches back together.
`apply_noise`	Damp every live coefficient by this layer's noise, then reclaim.
`propagate`	Back-propagate circuit through observable in the Heisenberg picture.
`expectation_value`	Compute the expectation value of observable after evolving through circuit.
`save_terms`	Write terms to a gzip-compressed binary file at filename.

Attributes:

Name	Type	Description
`basis_kind`	`int`	The integer a key-aware native noise plugin sees as `basis_kind`.
`term_sum_type`	`type[AbstractTermSum] \| None`	Container type built for a propagated result.
`noise`	`UniformNoiseModel \| GateNoiseModel \| NativeNoiseModel \| None`	The current noise model, or None.
`truncators`	`list[object]`	The current truncation pipeline, in application order.

basis_kind `class-attribute` ¶

basis_kind: int = -1

The integer a key-aware native noise plugin sees as basis_kind.

0 is Pauli and 1 is Majorana, and a plugin is only guaranteed to interpret those two. The default, -1 denies plugin access to the basis kind. Subclass if your custom basis supports the representation the plugin expects.

term_sum_type `class-attribute` ¶

term_sum_type: type[AbstractTermSum] | None = None

Container type built for a propagated result.

noise `property` ¶

noise: UniformNoiseModel | GateNoiseModel | NativeNoiseModel | None

The current noise model, or None.

truncators `property` ¶

truncators: list[object]

The current truncation pipeline, in application order.

set_noise ¶

set_noise(noise: UniformNoiseModel | GateNoiseModel | NativeNoiseModel | None = None) -> None

Replace the noise model.

Parameters:

Name	Type	Description	Default
`noise`	`UniformNoiseModel \| GateNoiseModel \| NativeNoiseModel \| None`	The new model, or None to disable noise.	`None`

set_truncation ¶

set_truncation(truncation: object | Sequence[object] | TruncationPolicy | None = None) -> None

Replace the truncation pipeline.

Parameters:

Name	Type	Description	Default
`truncation`	`object \| Sequence[object] \| TruncationPolicy \| None`	A truncator, a sequence of truncators, a legacy `TruncationPolicy`, or None.	`None`

Raises:

Type	Description
`TypeError`	If `truncation` is not one of the accepted forms, or names a surrogate-only (`FrequencyTruncator`/`Simplify`) or engine-only (`NativeTruncator`) truncator. See `resolve_truncation`.

apply_gate `abstractmethod` ¶

apply_gate(term: TermT, coeff: complex, rotation: RotationT) -> Iterable[tuple[TermT, complex]]

Branch one basis term under one gate

Parameters:

Name	Type	Description	Default
`term`	`TermT`	The basis term being conjugated.	required
`coeff`	`complex`	The term's current coefficient.	required
`rotation`	`RotationT`	The gate, typically an `AbstractRotation` carrying a `generator` and an `angle`.	required

Returns:

Type	Description
`Iterable[tuple[TermT, complex]]`	The `(child_term, child_coeff)` pairs of the expansion.

layers_of `staticmethod` ¶

layers_of(circuit: CircuitLike) -> list[list[RotationT]]

Normalize a circuit into its gate layers, in Heisenberg application order.

Parameters:

Name	Type	Description	Default
`circuit`	`CircuitLike`	The circuit to normalize.	required

Returns:

Type	Description
`list[list[RotationT]]`	One (reversed) list of rotations per (reversed) layer.

Raises:

Type	Description
`TypeError`	If `circuit` is none of the accepted forms.

apply_layer ¶

apply_layer(terms: dict[TermT, complex], rotation: RotationT, layer_index: int) -> dict[TermT, complex]

Apply one gate to every live term, folding branches back together.

Override this to transform a whole term map at once.

Parameters:

Name	Type	Description	Default
`terms`	`dict[TermT, complex]`	The live terms, as a `{term: coefficient}` map.	required
`rotation`	`RotationT`	The gate to apply.	required
`layer_index`	`int`	Index of this gate's layer, in the reversed (Heisenberg) order `layers_of` produces.	required

Returns:

Type	Description
`dict[TermT, complex]`	The evolved term map.

apply_noise ¶

apply_noise(terms: dict[TermT, complex], layer_index: int, n_layers: int) -> dict[TermT, complex]

Damp every live coefficient by this layer's noise, then reclaim.

Parameters:

Name	Type	Description	Default
`terms`	`dict[TermT, complex]`	The live terms, as a `{term: coefficient}` map.	required
`layer_index`	`int`	Index of the layer about to be applied, in the reversed (Heisenberg) order `layers_of` produces.	required
`n_layers`	`int`	Total number of layers in the circuit.	required

Raises:

Type	Description
`NotImplementedError`	If the noise model exposes neither `damping_factor_term`, `factor_term`, nor `damping_factor`.

propagate ¶

propagate(observable: AbstractTermSum[TermT], circuit: CircuitLike, filename: str | None = None) -> AbstractTermSum[TermT]

Back-propagate circuit through observable in the Heisenberg picture.

Layers, and the gates within each layer, are applied in reverse, so the result is \(U^\dagger O U\).

If filename is given, the final term sum is saved to a gzip-compressed binary file at that path.

Parameters:

Name	Type	Description	Default
`observable`	`AbstractTermSum[TermT]`	The term sum to back-propagate (matching this propagator's basis).	required
`circuit`	`CircuitLike`	The circuit to propagate through: anything `layers_of` accepts.	required
`filename`	`str \| None`	Optional path to save the evolved term sum to, gzip-compressed.	`None`

Returns:

Type	Description
`AbstractTermSum[TermT]`	The evolved term sum, in the same container class as observable
`AbstractTermSum[TermT]`	unless `term_sum_type` says otherwise.

expectation_value ¶

expectation_value(observable: AbstractTermSum[TermT], circuit: CircuitLike, initial_state: DiagState = 0, filename: str | None = None) -> PropagationResult

Compute the expectation value of observable after evolving through circuit.

Evaluates \(\langle f | U^\dagger O U | f \rangle\) by summing each evolved term's AbstractTerm.trace_with_diag_state against initial_state.

Parameters:

Name	Type	Description	Default
`observable`	`AbstractTermSum[TermT]`	The term sum whose expectation value is computed.	required
`circuit`	`CircuitLike`	The circuit to propagate through.	required
`initial_state`	`DiagState`	The reference state, passed through unchanged to `AbstractTerm.trace_with_diag_state`. Both `PauliString` and `MajoranaMonomial` read it as an integer bitmask.	`0`
`filename`	`str \| None`	Optional path to save the evolved term sum to, gzip-compressed.	`None`

Returns:

Type	Description
`PropagationResult`	The expectation value, plus the diagnostics collected during the
`PropagationResult`	run

Raises:

Type	Description
`ValueError`	If the summed value has a non-negligible imaginary part. `PropagationResult` is real-valued, matching the two built-in propagators

save_terms ¶

save_terms(terms: AbstractTermSum[TermT], filename: str) -> None

Write terms to a gzip-compressed binary file at filename.

Delegates to the term sum's own save when it has one, otherwise uses the from_bytes and to_bytes methods to serialize terms.

Parameters:

Name	Type	Description	Default
`terms`	`AbstractTermSum[TermT]`	The term sum to write.	required
`filename`	`str`	Destination path.	required

propaq.propagators¶

propagators ¶

CircuitLike module-attribute ¶

PauliPropagator ¶

noise property ¶

truncators property ¶

expectation_value method descriptor ¶

propagate method descriptor ¶

set_noise method descriptor ¶

set_truncation method descriptor ¶

MajoranaPropagator ¶

noise property ¶

truncators property ¶

expectation_value method descriptor ¶

propagate method descriptor ¶

set_truncation method descriptor ¶

PauliSurrogatePropagator ¶

truncators property ¶

build method descriptor ¶

set_truncation method descriptor ¶

MajoranaSurrogatePropagator ¶

truncators property ¶

set_truncation method descriptor ¶

AbstractPropagator ¶

basis_kind class-attribute ¶

term_sum_type class-attribute ¶

noise property ¶

truncators property ¶

set_noise ¶

set_truncation ¶

apply_gate abstractmethod ¶

layers_of staticmethod ¶

apply_layer ¶

apply_noise ¶

propagate ¶

expectation_value ¶

save_terms ¶

`propaq.propagators`¶

CircuitLike `module-attribute` ¶

noise `property` ¶

truncators `property` ¶

expectation_value `method descriptor` ¶

propagate `method descriptor` ¶

set_noise `method descriptor` ¶

set_truncation `method descriptor` ¶

noise `property` ¶

truncators `property` ¶

expectation_value `method descriptor` ¶

propagate `method descriptor` ¶

set_truncation `method descriptor` ¶

truncators `property` ¶

build `method descriptor` ¶

set_truncation `method descriptor` ¶

truncators `property` ¶

set_truncation `method descriptor` ¶

basis_kind `class-attribute` ¶

term_sum_type `class-attribute` ¶

noise `property` ¶

truncators `property` ¶

apply_gate `abstractmethod` ¶

layers_of `staticmethod` ¶