nibcq.LCRACIR
=============

.. py:class:: nibcq.LCRACIR(device: nibcq._device.Device, test_parameters: LCRTestParameters)

   LCR-based ACIR (AC Internal Resistance) measurement handler class.

   This class implements single-frequency AC impedance measurements using
   the NI PXIe-4190 LCR Meter. Unlike SMU-based ACIR which uses waveform
   generation and FFT analysis, the LCR meter performs hardware-based
   impedance measurements directly at 1000 Hz.

   The LCR meter handles all signal generation and analysis internally,
   making measurements simpler and faster than SMU-based methods.

   .. attribute:: DEVICE_FAMILY

      DeviceFamily.LCR_METER - required device type.

      :type: DeviceFamily

   .. attribute:: measurement_frequency

      Default frequency for ACIR (1000.0 Hz).

      :type: float

   .. attribute:: MEASUREMENT_TIMEOUT

      21.0 seconds - timeout for measurement completion.

      :type: float

   .. rubric:: Examples

   >>> device = Device.create(DeviceFamily.LCR_METER, "PXI1Slot2")
   >>> params = LCRTestParameters(current_amplitude=0.07)
   >>> lcr_acir = LCRACIR(device, params)
   >>> result = lcr_acir.run()
   >>> print(f"Impedance: {result.z_magnitude:.4f} Ohm")


   .. py:property:: device
      :type: nibcq._device.Device


      Get the device instance.

      :returns: The connected LCR Meter device instance.
      :rtype: Device


   .. py:property:: test_parameters
      :type: LCRTestParameters


      Get the test parameters.

      :returns: The current LCR test parameters configuration.
      :rtype: LCRTestParameters


   .. py:property:: result
      :type: Optional[nibcq.measurement.LCRMeasurementResult]


      Get the last measurement result.


   .. py:method:: validate_current_amplitude(current_amplitude: float) -> bool
      :staticmethod:


      Validate that the current amplitude is within acceptable limits.

      :param current_amplitude: The current amplitude to validate in Amperes RMS.
      :type current_amplitude: float

      :returns: Always returns True when validation passes.
      :rtype: bool

      :raises LCRParameterError: If the current amplitude is outside the valid range
          (7.08 nA to 707 mA).



   .. py:method:: run() -> nibcq.measurement.LCRMeasurementResult

      Run the complete LCR ACIR measurement.

      Configures the device, performs the measurement, and returns the results.
      The measurement is performed at 1000 Hz (ACIR standard frequency).

      :returns:

                The measurement results containing impedance,
                    resistance, reactance, phase, and frequency data.
      :rtype: LCRMeasurementResult

      :raises LCRParameterError: If parameters are invalid.
      :raises nidcpower.Error: If hardware operation fails.

      .. rubric:: Examples

      >>> device = Device.create(DeviceFamily.LCR_METER, "PXI1Slot2")
      >>> params = LCRTestParameters()
      >>> lcr_acir = LCRACIR(device, params)
      >>> result = lcr_acir.run()
      >>> print(f"Z = {result.z_magnitude:.4f} Ohm")
      >>> print(f"Rs = {result.resistance:.4f} Ohm")
      >>> print(f"Theta = {result.theta:.2f} degrees")



   .. py:method:: create_compensation(params: nibcq.lcr_compensation.LCRCompensationParameters, skip_prompts: bool = False) -> nibcq.measurement.LCRMeasurementResult

      Generate LCR compensation data and verify with a measurement.

      This method performs the complete 7-step compensation generation flow
      as defined in the LabVIEW "Create Compensation" example:

      1. Session init (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)

      The compensation data is stored on the device's onboard memory and
      remains available for subsequent measurements until the device is
      reset or powered off.

      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 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.
                           Follows the Calibrator.self_calibrate(force=...) pattern.
      :type skip_prompts: bool

      :returns:

                Verification measurement result after
                    compensation is applied. Can be used to verify compensation
                    quality (should show near-zero impedance for a short).
      :rtype: LCRMeasurementResult

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

      .. rubric:: Examples

      >>> # Interactive compensation with user prompts
      >>> lcr = LCRACIR(device, test_params)
      >>> result = lcr.create_compensation(
      ...     LCRCompensationParameters(
      ...         generate_open=True,
      ...         generate_short=True,
      ...         enable_open=True,
      ...         enable_short=True,
      ...     )
      ... )
      >>> print(f"Verification Z: {result.z_magnitude:.6f} Ohm")
      >>>
      >>> # Automated compensation (for testing)
      >>> result = lcr.create_compensation(params, skip_prompts=True)