scuq.constants
==============

``scuq.constants`` provides a deliberately small set of physical constants as
native SCUQ quantities. It does not import SciPy and does not mirror the full
``scipy.constants`` database.

Data provenance
---------------

The measured value in the initial set is pinned to the
`2022 CODATA recommended values <https://physics.nist.gov/constants>`_
published in version 9.0 of the NIST Reference on Constants, Units, and
Uncertainty (May 2024). The exact values follow the
`SI defining constants <https://www.bipm.org/en/measurement-units/si-defining-constants>`_
published by the BIPM.

The SI fixes the numerical values of ``c``, ``h``, ``e``, ``k_B``, and
``N_A`` exactly. Their SCUQ standard uncertainty is therefore zero. In
contrast, the fine-structure constant ``alpha`` is measured and carries the
CODATA 2022 standard uncertainty.

Shared electromagnetic uncertainty
------------------------------------

Vacuum permeability, vacuum permittivity, and vacuum impedance are derived
from the same uncertain fine-structure input:

.. math::

   \mu_0 &= \frac{2\alpha h}{e^2 c},\\
   \epsilon_0 &= \frac{1}{\mu_0 c^2},\\
   Z_0 &= \mu_0 c.

They are consequently physically dependent SCUQ expressions, not three
independent measurements. Calculations containing more than one of these
constants retain this shared dependency during uncertainty propagation.

Example
-------

.. code-block:: python

   from scuq.constants import alpha, epsilon_0, mu_0, Z_0
   from scuq.ucomponents import Context

   context = Context()
   print(context.value_uncertainty_unit(alpha))
   print(context.value_uncertainty_unit(mu_0))
   print(context.value_uncertainty_unit(epsilon_0))
   print(context.value_uncertainty_unit(Z_0))

The module-level constants are protected against augmented assignment and
direct changes to their stored value or unit. Ordinary arithmetic remains
available and returns regular :class:`scuq.quantities.Quantity` expressions.

API
---

.. automodule:: scuq.constants
   :members:
   :undoc-members:
   :show-inheritance: