sda.analysis.calibration
========================

.. py:module:: sda.analysis.calibration

.. autoapi-nested-parse::

   E = k·V² calibration helpers shared across SDA analysis scripts.

   Provides a single ``K_DEFAULT`` constant (the median k derived from the CH5
   campaign) and two functions:

   * :func:`calibrate_k` — fit k per generator from tests that have both
     energy and voltage columns.
   * :func:`infer_energy` — compute E = k·V² using the best available k for a
     given generator, falling back to ``K_DEFAULT``.



Attributes
----------

.. autoapisummary::

   sda.analysis.calibration.K_DEFAULT


Functions
---------

.. autoapisummary::

   sda.analysis.calibration.calibrate_k
   sda.analysis.calibration.infer_energy


Module Contents
---------------

.. py:data:: K_DEFAULT
   :type:  float
   :value: 0.07


.. py:function:: calibrate_k(tests, voltage_cols = None, energy_cols = None, exclude = frozenset())

   Fit k = E / V² per generator from tests that have both columns.

   :param tests:
   :type tests: :py:class:`List` of :py:class:`SDA test names` to :py:class:`scan.`
   :param voltage_cols: :data:`~sda.analysis.columns.VOLTAGE_COLS`.
   :type voltage_cols: :py:class:`Column name candidates for voltage.  Defaults to`
   :param energy_cols: :data:`~sda.analysis.columns.ENERGY_COLS`.
   :type energy_cols: :py:class:`Column name candidates for energy.  Defaults to`
   :param exclude: not meaningful).
   :type exclude: :py:class:`Test names` to :py:class:`skip (e.g. mixed NRP+DC tests whose k is`

   :returns: * :py:class:`dict mapping generator name (and `````"default"``:py:class:```)` to :py:class:`median k (mJ / kV²).`
             * :py:class:`Falls back` to :py:class:``````{"default": K_DEFAULT}``:py:class:``` when no calibration data is found.`


.. py:function:: infer_energy(voltage_kv, k_map = None, generator = 'default')

   Compute E = k · V² using the best available k for the given generator.

   :param voltage_kv:
   :type voltage_kv: :py:class:`Voltage in kV.`
   :param k_map: :func:`calibrate_k`).  When ``None``, uses ``K_DEFAULT``.
   :type k_map: :py:class:`Dict mapping generator names` to :py:class:`k values (from`
   :param generator: in *k_map*.
   :type generator: :py:class:`Generator name.  Falls back` to :py:class:``````"default"``:py:class:``` when not found`

   :rtype: :py:class:`Energy per pulse in mJ`, or ``np.nan`` if *voltage_kv* is not finite.