propaq.extrapolators

Extrapolation to the zero-noise and zero-cutoff limits, by sweeping the controlling parameter and fitting a curve.

See the extrapolation guide.

Zero-noise extrapolation

ZeroNoiseExtrapolator

ZeroNoiseExtrapolator(fitting_fn: Callable, noise_values: list[float])

Zero-noise extrapolation via curve fitting.

Construct a ZeroNoiseExtrapolator with a fitting function and noise values.

Methods:

Name	Description
build_noise	Build a fresh noise model carrying the given sweep value.
run	Sweep noise levels, fit, and extrapolate to zero noise.

Attributes:

Name	Type	Description
fitting_fn	Callable	Function to fit to the noise vs. expectation value data, passed to scipy.optimize.curve_fit.
noise_values	list[float]	Noise values to sweep over for the extrapolation.

fitting_fn instance-attribute

fitting_fn: Callable = fitting_fn

Function to fit to the noise vs. expectation value data, passed to scipy.optimize.curve_fit.

noise_values instance-attribute

noise_values: list[float] = list(noise_values)

Noise values to sweep over for the extrapolation.

build_noise

build_noise(value: float) -> UniformNoiseModel | GateNoiseModel | NativeNoiseModel

Build a fresh noise model carrying the given sweep value.

Defaults to UniformNoiseModel(value). Override to sweep a different single-parameter noise model, e.g. one parameter of a custom GateNoiseModel subclass with the rest held fixed.

run

run(propagator: AbstractPropagator[TermT, RotationT], observable: AbstractTermSum[TermT], circuit: CircuitLike[RotationT], initial_state: DiagState = 0, **curve_fit_kwargs) -> ZNEResult

Sweep noise levels, fit, and extrapolate to zero noise.

Works with any AbstractPropagator

Parameters:

Name	Type	Description	Default
propagator	AbstractPropagator[TermT, RotationT]	The propagator to sweep noise on.	required
observable	AbstractTermSum[TermT]	The observable to measure.	required
circuit	CircuitLike[RotationT]	The circuit to propagate.	required
initial_state	DiagState	Initial state index (default 0).	0
**curve_fit_kwargs		Forwarded to scipy.optimize.curve_fit (e.g. p0=).	{}

Returns:

Type	Description
ZNEResult	A ZNEResult containing the extrapolated zero-noise value and fit details.

ZNEResult dataclass

ZNEResult(zero_noise_value: float, noise_values: list[float], expectation_values: list[float], fit_params: ndarray, fit_covariance: ndarray)

Result of a zero-noise extrapolation run, including the fitted parameters and covariance.

Attributes:

Name	Type	Description
zero_noise_value	float	Extrapolated expectation value at zero noise.
noise_values	list[float]	Noise values used in the extrapolation.
expectation_values	list[float]	Expected values at each noise level.
fit_params	ndarray	Fitted parameters.
fit_covariance	ndarray	Covariance matrix of the fitted parameters.

zero_noise_value instance-attribute

zero_noise_value: float

Extrapolated expectation value at zero noise.

noise_values instance-attribute

noise_values: list[float]

Noise values used in the extrapolation.

expectation_values instance-attribute

expectation_values: list[float]

Expected values at each noise level.

fit_params instance-attribute

fit_params: ndarray

Fitted parameters.

fit_covariance instance-attribute

fit_covariance: ndarray

Covariance matrix of the fitted parameters.

Zero-cutoff extrapolation

ZeroCutoffExtrapolator

ZeroCutoffExtrapolator(fitting_fn: Callable, cutoff_values: list[float])

Bases: ABC

Zero cutoff extrapolation via curve fitting.

Construct a ZeroCutoffExtrapolator with a fitting function and cutoff values.

Methods:

Name	Description
run	Sweep cutoff values, fit, and extrapolate to zero cutoff.
truncator_cls	The truncator class this extrapolator sweeps, used to find its slot
build_truncator	Build a fresh truncator carrying the given cutoff (None = no cutoff).

Attributes:

Name	Type	Description
fitting_fn	Callable	Function to fit to the cutoff vs. expectation value data, passed to scipy.optimize.curve_fit.
cutoff_values	list[float]	Cutoff values to sweep over for the extrapolation.

fitting_fn instance-attribute

fitting_fn: Callable = fitting_fn

Function to fit to the cutoff vs. expectation value data, passed to scipy.optimize.curve_fit.

cutoff_values instance-attribute

cutoff_values: list[float] = list(cutoff_values)

Cutoff values to sweep over for the extrapolation.

run

run(propagator: AbstractPropagator[TermT, RotationT], observable: AbstractTermSum[TermT], circuit: CircuitLike[RotationT], initial_state: DiagState = 0, **curve_fit_kwargs) -> ZCEResult

Sweep cutoff values, fit, and extrapolate to zero cutoff.

Works with any AbstractPropagator

Parameters:

Name	Type	Description	Default
propagator	AbstractPropagator[TermT, RotationT]	The propagator to sweep a cutoff on.	required
observable	AbstractTermSum[TermT]	The observable to measure.	required
circuit	CircuitLike[RotationT]	The circuit to propagate.	required
initial_state	DiagState	Initial state index (default 0).	0
**curve_fit_kwargs		Forwarded to scipy.optimize.curve_fit (e.g. p0=).	{}

Returns:

Type	Description
ZCEResult	A ZCEResult containing the extrapolated zero-cutoff value and fit details.

truncator_cls abstractmethod

truncator_cls() -> type[object]

The truncator class this extrapolator sweeps, used to find its slot in the propagator's truncation pipeline.

build_truncator abstractmethod

build_truncator(cutoff: float | int | None) -> object

Build a fresh truncator carrying the given cutoff (None = no cutoff).

WeightCutoffExtrapolator

WeightCutoffExtrapolator(fitting_fn: Callable, cutoff_values: list[float])

Bases: ZeroCutoffExtrapolator

Zero weight-cutoff extrapolation via curve fitting.

Construct a ZeroCutoffExtrapolator with a fitting function and cutoff values.

Methods:

Name	Description
run	Sweep cutoff values, fit, and extrapolate to zero cutoff.
truncator_cls	The truncator class this extrapolator sweeps: WeightTruncator.
build_truncator	Build a fresh WeightTruncator carrying the given weight cutoff.

Attributes:

Name	Type	Description
fitting_fn	Callable	Function to fit to the cutoff vs. expectation value data, passed to scipy.optimize.curve_fit.
cutoff_values	list[float]	Cutoff values to sweep over for the extrapolation.

fitting_fn instance-attribute

fitting_fn: Callable = fitting_fn

Function to fit to the cutoff vs. expectation value data, passed to scipy.optimize.curve_fit.

cutoff_values instance-attribute

cutoff_values: list[float] = list(cutoff_values)

Cutoff values to sweep over for the extrapolation.

run

run(propagator: AbstractPropagator[TermT, RotationT], observable: AbstractTermSum[TermT], circuit: CircuitLike[RotationT], initial_state: DiagState = 0, **curve_fit_kwargs) -> ZCEResult

Sweep cutoff values, fit, and extrapolate to zero cutoff.

Works with any AbstractPropagator

Parameters:

Name	Type	Description	Default
propagator	AbstractPropagator[TermT, RotationT]	The propagator to sweep a cutoff on.	required
observable	AbstractTermSum[TermT]	The observable to measure.	required
circuit	CircuitLike[RotationT]	The circuit to propagate.	required
initial_state	DiagState	Initial state index (default 0).	0
**curve_fit_kwargs		Forwarded to scipy.optimize.curve_fit (e.g. p0=).	{}

Returns:

Type	Description
ZCEResult	A ZCEResult containing the extrapolated zero-cutoff value and fit details.

truncator_cls

truncator_cls() -> type[object]

The truncator class this extrapolator sweeps: WeightTruncator.

build_truncator

build_truncator(cutoff: float | int | None) -> WeightTruncator

Build a fresh WeightTruncator carrying the given weight cutoff.

CoefficientCutoffExtrapolator

CoefficientCutoffExtrapolator(fitting_fn: Callable, cutoff_values: list[float])

Bases: ZeroCutoffExtrapolator

Zero coefficient-cutoff extrapolation via curve fitting.

Construct a ZeroCutoffExtrapolator with a fitting function and cutoff values.

Methods:

Name	Description
run	Sweep cutoff values, fit, and extrapolate to zero cutoff.
truncator_cls	The truncator class this extrapolator sweeps: CoefficientTruncator.
build_truncator	Build a fresh CoefficientTruncator carrying the given coefficient cutoff.

Attributes:

Name	Type	Description
fitting_fn	Callable	Function to fit to the cutoff vs. expectation value data, passed to scipy.optimize.curve_fit.
cutoff_values	list[float]	Cutoff values to sweep over for the extrapolation.

fitting_fn instance-attribute

fitting_fn: Callable = fitting_fn

Function to fit to the cutoff vs. expectation value data, passed to scipy.optimize.curve_fit.

cutoff_values instance-attribute

cutoff_values: list[float] = list(cutoff_values)

Cutoff values to sweep over for the extrapolation.

run

run(propagator: AbstractPropagator[TermT, RotationT], observable: AbstractTermSum[TermT], circuit: CircuitLike[RotationT], initial_state: DiagState = 0, **curve_fit_kwargs) -> ZCEResult

Sweep cutoff values, fit, and extrapolate to zero cutoff.

Works with any AbstractPropagator

Parameters:

Name	Type	Description	Default
propagator	AbstractPropagator[TermT, RotationT]	The propagator to sweep a cutoff on.	required
observable	AbstractTermSum[TermT]	The observable to measure.	required
circuit	CircuitLike[RotationT]	The circuit to propagate.	required
initial_state	DiagState	Initial state index (default 0).	0
**curve_fit_kwargs		Forwarded to scipy.optimize.curve_fit (e.g. p0=).	{}

Returns:

Type	Description
ZCEResult	A ZCEResult containing the extrapolated zero-cutoff value and fit details.

truncator_cls

truncator_cls() -> type[object]

The truncator class this extrapolator sweeps: CoefficientTruncator.

build_truncator

build_truncator(cutoff: float | int | None) -> CoefficientTruncator

Build a fresh CoefficientTruncator carrying the given coefficient cutoff.

ZCEResult dataclass

ZCEResult(zero_cutoff_value: float, cutoff_values: list[float], expectation_values: list[float], fit_params: ndarray, fit_covariance: ndarray)

Result of a zero-cutoff extrapolation run, including the fitted parameters and covariance.

Attributes:

Name	Type	Description
zero_cutoff_value	float	Extrapolated expectation value at zero cutoff.
cutoff_values	list[float]	Cutoff values used in the extrapolation.
expectation_values	list[float]	Expected values at each cutoff value.
fit_params	ndarray	Fitted parameters.
fit_covariance	ndarray	Covariance matrix of the fitted parameters.

zero_cutoff_value instance-attribute

zero_cutoff_value: float

Extrapolated expectation value at zero cutoff.

cutoff_values instance-attribute

cutoff_values: list[float]

Cutoff values used in the extrapolation.

expectation_values instance-attribute

expectation_values: list[float]

Expected values at each cutoff value.

fit_params instance-attribute

fit_params: ndarray

Fitted parameters.

fit_covariance instance-attribute

fit_covariance: ndarray

Covariance matrix of the fitted parameters.