Messgrößen, Einheiten und Unsicherheiten
========================================

mpylab verwendet SCUQ durchgängig für physikalische Messgrößen. Eine
``Quantity`` verbindet Wert, Einheit und gegebenenfalls Unsicherheit oder
Korrelation. Diese Information soll bis zur Geräte- oder
Darstellungsschnittstelle erhalten bleiben.

Quantities erzeugen
-------------------

.. code-block:: python

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

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

Konfigurationen verwenden Quantities insbesondere für Pegel, Feldstärken und
Leistungen. Frequenzlisten historischer APIs bestehen teilweise weiterhin aus
Hz-Floats; innerhalb physikalischer Berechnungen wird die Einheit
ausdrücklich ergänzt.

Wert, Unsicherheit und Einheit
------------------------------

Reelle und komplexe Unsicherheitsmodelle werden über eine gemeinsame
Hilfsfunktion ausgewertet:

.. code-block:: python

   from mpylab.tools.quantity_uncertainty import value_uncertainty_unit

   value, uncertainty, unit = value_uncertainty_unit(power)

Bei reellen Größen ist ``uncertainty`` die Standardunsicherheit. Bei
komplexen Größen wird eine kartesische 2x2-Kovarianzmatrix für Real- und
Imaginärteil zurückgegeben.

Rechnen mit Pfadkorrekturen
---------------------------

Pfadkorrekturen können komplex sein. ``multiply_quantities`` und
``divide_quantities`` harmonisieren reelle und komplexe Unsicherheitsmodelle.
``magnitude_quantity`` bildet anschließend einen reellen Betrag mit
Unsicherheit. Direkte Umwandlung in ``float`` vor der Korrektur würde Phase
und Unsicherheit verlieren.

Einheiten umrechnen
-------------------

``mpylab.tools.uconv`` ist die zentrale Umrechnungsebene:

* ``to_quantity(unit, value)`` erzeugt eine Quantity aus Protokolldaten;
* ``from_quantity(unit, quantity)`` liefert einen Wert für eine Ziel-Einheit;
* ``quantity_to_db`` und ``quantity_to_dBm`` erhalten Unsicherheitsinformation;
* S-Parameter-Konverter unterscheiden Phase in Grad und Bogenmaß ausdrücklich.

Eine symmetrische lineare Unsicherheit wird auf der dB-Skala im Allgemeinen
asymmetrisch. Wenn die untere lineare Grenze nicht positiv ist, kennzeichnet
die dB-Darstellung die gekappte Untergrenze ausdrücklich.

Leistungs- und Amplitudenverhältnisse
-------------------------------------

``POWERRATIO`` und ``AMPLITUDERATIO`` bestimmen den dB-Faktor 10
beziehungsweise 20. Das sagt nicht aus, ob ein Übertragungsfaktor reell oder
komplex ist. Ein komplexes ``S21`` kann deshalb als ``POWERRATIO`` geführt
werden, wenn seine dB-Definition den Faktor 10 verwendet.