nibcq.lcr_compensation
======================

.. py:module:: nibcq.lcr_compensation

.. autoapi-nested-parse::

   LCR Meter compensation generation module for nibcq package.

   This module provides the compensation generation functionality for the NI PXIe-4190
   LCR Meter. The compensation data is stored on the device's onboard memory and can
   be used by LCRACIR measurements.

   The module contains:
   - LCRCompensationParameters: Configuration dataclass for compensation generation
   - perform_lcr_compensation(): Helper function implementing the 7-step compensation flow



Classes
-------

.. toctree::
   :hidden:

   /autoapi/nibcq/lcr_compensation/LCRCompensationParameters

.. autoapisummary::

   nibcq.lcr_compensation.LCRCompensationParameters


Functions
---------

.. autoapisummary::

   nibcq.lcr_compensation.parse_cable_length
   nibcq.lcr_compensation.validate_compensation_parameters
   nibcq.lcr_compensation.perform_lcr_compensation


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

.. py:function:: parse_cable_length(cable_length_str: str) -> nidcpower.CableLength

   Convert a cable length string into a nidcpower.CableLength enum value.

   :param cable_length_str: Human-readable cable length string from configuration,
                            for example "1m", "2m triaxial", or "custom onboard".
   :type cable_length_str: str

   :returns: The corresponding :class:`nidcpower.CableLength` enum value.
   :rtype: nidcpower.CableLength

   :raises LCRParameterError: If the provided cable length string is not supported.

   .. rubric:: Examples

   >>> parse_cable_length("1m")
   <CableLength.NI_STANDARD_1M: ...>


.. py:function:: validate_compensation_parameters(params: LCRCompensationParameters) -> None

   Validate LCR compensation parameters.

   Checks that the compensation parameters are valid before performing
   the compensation procedure.

   :param params: The LCRCompensationParameters to validate.
   :type params: LCRCompensationParameters

   :raises LCRParameterError: If parameters are invalid. Specifically:
       - If generate_load=True but generate_open or generate_short is False
       - If enable_load=True but enable_open or enable_short is False
       - If measurement_time=CUSTOM but custom_measurement_time is not positive


.. py:function:: perform_lcr_compensation(session: nidcpower.Session, params: LCRCompensationParameters, skip_prompts: bool = False, timeout: float = DEFAULT_COMPENSATION_TIMEOUT) -> dict

   Perform the 7-step LCR compensation flow.

   This function implements the complete compensation generation flow as defined
   in the LabVIEW "Create Compensation" example. The compensation data is stored
   on the device's onboard memory.

   The 7 steps are:
   1. Session init (assumed already done via Device.create)
   2. Custom cable compensation (if enabled)
   3. Set cable length
   4. Open/Short compensation (if enabled)
   5. Load compensation (if enabled)
   6. Configure session for verification measurement
   7. Verification measurement (initiate, wait, measure, reset)

   User prompts are displayed before each step requiring physical connection
   changes (open, short, load). These prompts ensure the user has made
   the correct physical setup before compensation data is captured.

   :param session: The nidcpower.Session connected to the LCR Meter.
   :type session: nidcpower.Session
   :param params: LCRCompensationParameters with all configuration
                  options.
   :type params: LCRCompensationParameters
   :param skip_prompts: If True, skips user prompts for physical connections.
                        User must ensure correct connections are made before each step.
                        Useful for automated testing or scripted calibration sequences.
   :type skip_prompts: bool
   :param timeout: Timeout in seconds for the verification measurement.
                   Default is 21.0 seconds.
   :type timeout: float

   :returns:

             Raw measurement data from verification measurement containing:
                 - 'z': Complex impedance
                 - 'z_magnitude': Impedance magnitude
                 - 'z_phase': Phase angle in degrees
                 - 'resistance': Series resistance Rs
                 - 'stimulus_frequency': Actual measurement frequency
   :rtype: dict

   :raises LCRParameterError: If parameters are invalid (e.g., load comp
       without open AND short).
   :raises nidcpower.Error: If hardware operation fails.

   .. rubric:: Examples

   >>> # Perform compensation with user prompts
   >>> result = perform_lcr_compensation(
   ...     session=device.session,
   ...     params=LCRCompensationParameters(
   ...         generate_open=True,
   ...         generate_short=True,
   ...     ),
   ... )
   >>>
   >>> # Automated compensation (for testing)
   >>> result = perform_lcr_compensation(session, params, skip_prompts=True)