mpylab.tools.quantity_uncertainty module

Helpers for evaluating real and complex SCUQ quantities.

class mpylab.tools.quantity_uncertainty.PreparedRatioCorrection(correction: Quantity, operation: str, magnitude: bool, output_unit: object, fast_scale: float | None)

Bases: object

A ratio correction whose invariant SCUQ properties are analyzed once.

Instances are normally created with prepare_ratio_correction().

Parameters:

• correction (scuq.quantities.Quantity) – Original SCUQ ratio correction.

• operation (str) – Stored operation, either "divide" or "multiply".

• magnitude (bool) – Whether apply() forms the magnitude.

• output_unit (scuq.units.Unit or None) – Optional unit for the corrected result.

• fast_scale (float or None) – Precomputed constant scale, or None when the full SCUQ expression must be evaluated.

apply(value)

Apply the prepared correction to one measurement quantity.

Constant scaling is used only for a finite real uncertain value already expressed in the stored output unit. Other values automatically use the full SCUQ calculation.

Parameters:

value (scuq.quantities.Quantity) – Measurement value to correct.

Returns:

Corrected value using the stored operation, magnitude setting, and output unit.

Return type:

scuq.quantities.Quantity

Raises:

TypeError – If value is not a SCUQ quantity.

correction: Quantity

fast_scale: float | None

magnitude: bool

operation: str

output_unit: object

property uses_fast_path

Return whether applying this correction uses constant scaling.

mpylab.tools.quantity_uncertainty.apply_ratio_correction(value, correction, *, operation='divide', magnitude=True, output_unit=None)

Apply a ratio correction with a conservative SCUQ-preserving fast path.

This convenience function prepares correction and applies it once. Use prepare_ratio_correction() directly when applying the same correction repeatedly.

Parameters:

• value (scuq.quantities.Quantity) – Measurement value to correct.

• correction (scuq.quantities.Quantity) – Amplitude- or power-ratio correction.

• operation (str) – Apply the correction by "divide" (default) or "multiply".

• magnitude (bool) – If true (default), form the corrected magnitude. If false, preserve phase.

• output_unit (scuq.units.Unit or None) – Optional unit to which the result is reduced.

Returns:

Corrected measurement value.

Return type:

scuq.quantities.Quantity

Raises:

• TypeError – If value or correction is not a SCUQ quantity.

• ValueError – If operation is invalid or the requested correction or unit conversion cannot be performed.

mpylab.tools.quantity_uncertainty.complex_component_from_covariance(value, covariance)

Build a persistent complex component from a Cartesian covariance.

The covariance is represented through independent real-valued complex inputs. Consequently no external SCUQ context is needed after pickling.

mpylab.tools.quantity_uncertainty.divide_quantities(numerator, denominator)

Divide quantities after harmonizing their uncertainty models.

mpylab.tools.quantity_uncertainty.harmonize_uncertainty_models(first, second)

Promote both quantities when either uses complex uncertainty.

mpylab.tools.quantity_uncertainty.is_complex_uncertain(quantity)

Return whether quantity contains a complex SCUQ component.

mpylab.tools.quantity_uncertainty.magnitude_quantity(quantity)

Return abs(quantity) with a real scalar uncertainty component.

mpylab.tools.quantity_uncertainty.multiply_quantities(first, second)

Multiply quantities after harmonizing their uncertainty models.

mpylab.tools.quantity_uncertainty.polar_component(value, magnitude_uncertainty, phase_uncertainty_rad)

Build a complex component from independent polar uncertainties.

mpylab.tools.quantity_uncertainty.prepare_ratio_correction(correction, *, operation, magnitude, output_unit=None)

Analyze one invariant ratio correction for repeated application.

Parameters:

• correction (scuq.quantities.Quantity) – Amplitude- or power-ratio correction to prepare.

• operation (str) – Apply the correction by "divide" or "multiply". This keyword argument is required.

• magnitude (bool) – If true, form the corrected magnitude. If false, preserve phase. This keyword argument is required.

• output_unit (scuq.units.Unit or None) – Optional unit to which corrected values are reduced.

Returns:

Reusable correction with pre-analyzed fast-path properties.

Return type:

PreparedRatioCorrection

Raises:

• TypeError – If correction is not a SCUQ quantity.

• ValueError – If operation is neither "divide" nor "multiply".

The constant-scaling fast path is prepared only for an exact correction, magnitude output, an explicit output unit, and a finite non-zero divisor. Unsupported cases automatically retain the reference SCUQ calculation.

mpylab.tools.quantity_uncertainty.promote_to_complex_uncertainty(quantity)

Promote a real uncertain quantity to the complex SCUQ model.

mpylab.tools.quantity_uncertainty.value_uncertainty_unit(quantity, context=None)

Return value, uncertainty representation, and unit for quantity.

Real uncertain quantities return the scalar standard uncertainty used by scuq.ucomponents. Complex uncertain quantities return their 2x2 Cartesian covariance matrix with rows and columns ordered as real and imaginary part.