Measurement quantities, units, and uncertainty
==============================================

mpylab uses SCUQ throughout for physical measurement quantities. A
``Quantity`` combines a value, unit, and optional uncertainty or correlation.
Preserve this information up to the instrument or presentation boundary.

Creating quantities
-------------------

.. code-block:: python

   from scuq.quantities import Quantity
   from scuq.si import HERTZ, WATT

   frequency = Quantity(HERTZ, 1e9)
   power = Quantity(WATT, 0.1)

Configurations use quantities particularly for levels, field strengths, and
powers. Some historical APIs still use plain Hz floats for frequency lists;
attach the unit explicitly inside physical calculations.

Value, uncertainty, and unit
----------------------------

Evaluate real and complex uncertainty models through one shared helper:

.. code-block:: python

   from mpylab.tools.quantity_uncertainty import value_uncertainty_unit

   value, uncertainty, unit = value_uncertainty_unit(power)

For real quantities, ``uncertainty`` is the standard uncertainty. For complex
quantities, it is a Cartesian 2x2 covariance matrix for real and imaginary
parts.

Calculating with path corrections
---------------------------------

Path corrections may be complex. ``multiply_quantities`` and
``divide_quantities`` harmonize real and complex uncertainty models.
``magnitude_quantity`` then forms a real magnitude with uncertainty.
Converting to ``float`` before applying a correction would discard phase and
uncertainty.

Converting units
----------------

``mpylab.tools.uconv`` is the canonical conversion layer:

* ``to_quantity(unit, value)`` creates a quantity from protocol data;
* ``from_quantity(unit, quantity)`` returns a value in a target unit;
* ``quantity_to_db`` and ``quantity_to_dBm`` retain uncertainty information;
* S-parameter converters explicitly distinguish phase in degrees and radians.

A symmetric linear uncertainty is generally asymmetric on the dB scale. When
the lower linear bound is not positive, the dB representation explicitly
marks its clipped lower bound.

Power and amplitude ratios
--------------------------

``POWERRATIO`` and ``AMPLITUDERATIO`` select dB factors 10 and 20,
respectively. This does not determine whether a transfer factor is real or
complex. A complex ``S21`` may therefore use ``POWERRATIO`` when its dB
definition uses factor 10.