nibcq.temperature.TemperatureCapability
=======================================

.. py:class:: nibcq.temperature.TemperatureCapability

   Temperature measurement capability that can be added to measurement devices.

   Provides thermocouple-based temperature monitoring functionality for devices
   that require temperature for validating compensation values. Manages DAQ tasks for
   temperature acquisition and tracks acceptable temperature variations for
   measurement validity.

   This capability can be added to Device instances to enable temperature
   monitoring during measurements, which is essential for proper compensation
   validation in precision measurement applications.

   .. rubric:: Examples

   >>> capability = TemperatureCapability()
   >>> settings = ThermocoupleSettings("Dev1/ai0")
   >>> capability.setup_thermocouple(settings)
   >>> temp = capability.read_temperature()


   .. py:property:: thermocouple_settings
      :type: Optional[ThermocoupleSettings]


      Get the current thermocouple configuration settings.

      Returns the ThermocoupleSettings object that defines how temperature
      measurements are performed, including the DAQ resource, thermocouple
      type, and measurement range. Returns None if temperature capability
      has not been configured yet.

      :returns:

                The current thermocouple settings,
                    or None if not configured yet
      :rtype: Optional[ThermocoupleSettings]

      .. rubric:: Examples

      >>> capability = TemperatureCapability()
      >>> print(capability.thermocouple_settings)  # None
      >>> settings = ThermocoupleSettings("Dev1/ai0")
      >>> capability.setup_thermocouple(settings)
      >>> print(capability.thermocouple_settings.resource_name)  # "Dev1/ai0"


   .. py:property:: acceptable_temperature_delta
      :type: float


      Get the acceptable temperature delta for compensation validation.

      Returns the maximum allowed temperature difference in the configured data type
      between the current measurement temperature and the reference temperature used
      for compensation. This value is used to validate whether compensation
      data is still valid for the current thermal conditions.

      :returns: The acceptable temperature delta in the defined degrees unit, or NaN if not set
      :rtype: float

      .. rubric:: Examples

      >>> capability = TemperatureCapability()
      >>> capability.acceptable_temperature_delta = 2.5
      >>> delta = capability.acceptable_temperature_delta
      >>> print(f"Max temperature delta: ±{delta}°C")


   .. py:property:: temperature_measurement
      :type: CenteredRange


      Get the latest temperature measurement data.

      Returns the most recent temperature reading along with the acceptable
      temperature delta for validation. This information is used for
      compensation validation and thermal monitoring during measurements.

      :returns:

                Object containing the latest temperature
                    reading in the defined degrees unit and the acceptable temperature delta
      :rtype: CenteredRange

      .. rubric:: Examples

      >>> capability = TemperatureCapability()
      >>> measurement = capability.temperature_measurement
      >>> if not math.isnan(measurement.center):
      ...     print(f"Current temperature: {measurement.center}°C")


   .. py:method:: setup_thermocouple(settings: ThermocoupleSettings, temperature_delta: float = math.nan)

      Configure the thermocouple settings for temperature measurements.

      :param settings: The thermocouple configuration settings
      :param temperature_delta: The acceptable temperature delta for validation.
                                The base suggested value is 1.5. Leave as NaN to use compensation
                                file defined target value.



   .. py:method:: run_task()

      Read the temperature from the thermocouple.

      Creates a new task for each measurement to ensure clean, isolated
      temperature readings. Task is automatically closed after reading.

      :raises RuntimeError: If thermocouple settings are not initialized



   .. py:method:: measure_temperature() -> CenteredRange

      Get a new, current temperature reading and update the measured temperature.

      :returns: The current temperature reading with set delta information



   .. py:method:: validate_latest_temperature(target_temperature: CenteredRange) -> bool

      Validate the current temperature against the compensation file's target.

      Checks if the measured temperature is within the acceptable delta. If the user
      has overridden the delta (via acceptable_temperature_delta), that value takes
      precedence over the target's delta. If target temperature or delta is NaN,
      validation is skipped and returns False.

      :param target_temperature: The target temperature parameters for validation

      :returns:

                True if temperature is within acceptable range.
                    False if target temperature or delta is NaN (no validation needed),
                    or if thermocouple is not configured.
      :rtype: bool

      :raises ValueError: If the current temperature exceeds the target ± delta range

      .. rubric:: Examples

      >>> capability = TemperatureCapability()
      >>> capability.setup_thermocouple(settings)
      >>> capability.measure_temperature()
      >>> target = CenteredRange(25.0, 2.0)
      >>> is_valid = capability.validate_latest_temperature(target)