nibcq.ACIR

class nibcq.ACIR(device: nibcq._device.Device, test_parameters: ACIRTestParameters, test_frequency: float = 1000)

Bases: nibcq.measurement.Measurement

Alternating Current Internal Resistance (ACIR) measurement handler class.

This class implements single-frequency AC impedance spectroscopy measurements using a Source Measure Unit (SMU). ACIR measurements characterize the complex impedance of electrochemical systems, batteries, and other devices by applying a sinusoidal current excitation and measuring the resulting voltage response.

The class handles the complete measurement workflow including signal generation, data acquisition, DFT analysis for impedance calculation, and error compensation. It provides a foundation for more complex measurements like EIS (Electrochemical Impedance Spectroscopy) which extends ACIR for frequency sweeps.

ACIR measurements are fundamental in battery testing, electrochemical analysis, and material characterization where understanding the frequency-dependent impedance behavior is crucial for system performance evaluation.

Example

>>> # Configure measurement parameters
>>> params = ACIRTestParameters(
...     current_amplitude=0.1,
...     number_of_periods=20,
...     compensation_method=CompensationMethod.SHORT
... )
>>>
>>> device = Device.connect("PXIe-4139")
>>> acir = ACIR(device, test_frequency=1000.0, test_parameters=params)
>>>
>>> # Run measurement at 1000 Hz
>>> compensation = Compensation()
>>> result = acir.run(compensation=compensation)
>>> print(f"Impedance: {abs(result.impedance):.2f} Ohms")

Parameters:

device (nibcq._device.Device)
test_parameters (ACIRTestParameters)
test_frequency (float)

DEVICE_FAMILY: Final[nibcq.enums.DeviceFamily]

Device family for ACIR and similar measurement types.

Type:: DeviceFamily

FREQUENCY_LIMIT: Final[float] = 10000.0

Frequency limit for ACIR and similar measurement types.

Type:: float

CURRENT_LIMIT: Final[float] = 2.0

Current limit for ACIR and similar measurement types.

Type:: float

property current_frequency: float

Get the current frequency of the ACIR Measurement.

Returns:: The current configured frequency in Hz
Return type:: float
Raises:: FrequencyError – If frequency has not been set

property test_parameters: ACIRTestParameters

Get the test parameters for ACIR measurement.

Returns:: The current test parameters configuration
Return type:: ACIRTestParameters
Raises:: ValueError – If test parameters have not been set

property result: nibcq.measurement.SMUResult | list[tuple[nibcq.switch.SMUCellData, nibcq.measurement.SMUResult]]

Get the result of the last ACIR measurement.

Returns the measurement result from the most recent measurement operation. The result type depends on whether switching was used or not.

Returns:

The measurement result(s).: For switching measurements, returns a list of tuples where each tuple contains the cell data and its corresponding results.

Return type:

SMUResult | list[tuple[SMUCellData, SMUResult]]

Raises:

SMUParameterError – If no measurement has been performed yet or if the result is not available.

generate_compensation_file_path() → str

Generate compensation file path using current compensation method setting.

Returns:

The generated file path for compensation data, or None if no compensation: is needed

Return type:

str

Raises:

CompensationMethodError – If compensation_method is not supported by nibcq Python API

property measurement_data: nibcq.measurement.SMUMeasurement

Get the processed measurement data used for impedance calculations.

Only allows measurement to be read, not access it directly. For frequencies > 60 Hz, sanitizes data by removing edge effects. Applies DC offset removal to ensure measurements start and end near zero.

Returns:

Sanitized measurement data containing tone frequency, voltage: values, and current values

Return type:

SMUMeasurement

Raises:

SMUParameterError – If no measurement data is available or measurement is incomplete

property raw_data: nibcq.measurement.SMUMeasurement

Get the raw measurement data read from the device.

Only allows measurement to be read, not access it directly. Returns unprocessed data as captured from the device.

Returns:

Raw measurement data containing tone frequency, voltage values,: and current values

Return type:

SMUMeasurement

Raises:

SMUParameterError – If no measurement data is available or measurement is incomplete

static validate_current_amplitude(current_amplitude: float) → bool

Validate that the current amplitude is within acceptable limits.

Parameters:: current_amplitude (float) – The current amplitude to validate (in Amps).
Returns:: Always returns True when validation passes.
Return type:: bool
Raises:: CurrentAmplitudeError – If the current amplitude is not positive or exceeds the defined maximum limit (defined in ACIR.CURRENT_LIMIT constant).

load_compensation_file(file_path: str | None = None) → nibcq.compensation.Compensation

Load compensation file based on compensation method and device serial number.

Creates and returns a compensation object with the appropriate compensation data. For NO_COMPENSATION, creates a default compensation object. For other methods, loads compensation data from file.

Parameters:

file_path (Optional[str]) – Optional specific file path to read from. If None, generates path automatically

Returns:

The loaded compensation object

Return type:

Compensation

Raises:

FileNotFoundError – If compensation file is not found and compensation is required
ValueError – If compensation file is invalid and compensation is required
CompensationMethodError – If compensation method is not supported by the nibcq Python API

run(compensation: nibcq.compensation.Compensation) → nibcq.measurement.SMUResult

Run the complete ACIR measurement process with the specified parameters.

Validates temperature if the compensation specifies a target temperature, and the device supports temperature measurement. Then configures the device, performs the measurement, applies compensation if specified, and returns the final impedance results.

Parameters:

compensation (Compensation) – The compensation object to use for impedance correction

Returns:

A complete measurement result containing compensated impedance data: including frequency, impedance, resistance, reactance, magnitude, and phase

Return type:

SMUResult

Raises:

FrequencyError – If test frequency is out of range or parameters are invalid.
SMUParameterError – If device configuration or measurement fails
CompensationMethodError – If unsupported compensation method is specified

Examples

>>> params = ACIRTestParameters()
>>> acir = ACIR(device, params)
>>> compensation = acir.load_compensation_file()
>>> results = acir.run(1000, compensation)

run_with_switching(compensation: nibcq.compensation.Compensation) → list[tuple[nibcq.switch.SMUCellData, nibcq.measurement.SMUResult]]

Run ACIR measurements across multiple DUTs using switch matrix configuration.

This method performs AC impedance measurements on multiple devices under test (DUTs) by automatically switching between different channels. It leverages the device’s switching capability to sequentially connect to each configured DUT, perform the ACIR measurement, and collect results for all channels.

Returns partial, already processed measurements, even if an error occurs during switching or measurement.

The switching process includes proper debounce timing to ensure stable connections before measurements, and automatic disconnection after each measurement to prevent interference. This enables efficient multi-DUT testing for battery characterization, production testing, or comparative analysis scenarios.

Parameters:

compensation (Compensation) – The compensation object containing error correction data for impedance accuracy improvement across the measurement frequency.

Returns:

A list of tuples mapping each cell to its: measurement result. Each SMUCellData represents a DUT connection point, and SMUResult contains the impedance, resistance, reactance, magnitude, and phase measurements for that specific DUT.

Return type:

list[tuple[SMUCellData, SMUResult]]

Raises:

SwitchConfigurationError – If switching capability is not enabled (call device.with_switching() first) or if no switch channels are configured in the switch matrix.
FrequencyError – If test frequency is out of range or test parameters are invalid.
ValueError – If compensation list length doesn’t match the number of DUTs, or if temperature validation fails for any cell.
CompensationMethodError – If unsupported compensation method is specified.
FileNotFoundError – If compensation file is required but not found.
RuntimeError – If device configuration or measurement fails.

Note

This method automatically handles switch timing with debounce delays to ensure measurement stability. The end guarantees proper disconnection even if exceptions occur during measurement, preventing DUT damage or interference.

Examples

>>> params = ACIRTestParameters()
>>> acir = ACIR(device, params)
>>> compensation = acir.load_compensation_file()
>>> results = acir.run_with_switching(1000, compensation)

write_compensation_file(compensation_file_path: str | None = None, kit_file_path: str | None = None, comment: str | None = None) → str

Create a compensation file based on the current compensation data.

Parameters:

compensation_file_path (Optional[str]) – Optional specific file path to write to. If None, generates path automatically.
kit_file_path (Optional[str]) – Optional specific file path to the known impedance table. If None, no known impedance table is used.
comment (Optional[str]) – Optional comment to include in the compensation file. If None, no comment is included.

Returns:

The path of the created compensation file.

Return type:

string

Raises:

FrequencyError – If the test frequency is out of range or otherwise invalid.
CompensationMethodError – If the compensation method parameters are invalid, the selected method does not support compensation files, or an unsupported compensation method is specified.
FileNotFoundError – If compensation file is required but not found.
SMUParameterError – If device configuration or measurement fails.

property has_switch_capability: bool

Check if the device has switch capability.

Returns:: True if switch capability is available, False otherwise
Return type:: bool

connect_channel(channel: SMUCellData) → None

Connect to a specific DUT channel using the device’s switch capability.

Parameters:: channel (SMUCellData) – SwitchChannel containing connection information
Raises:: RuntimeError – If no switch capability is available
Return type:: None

disconnect_all() → None

Disconnect all channels using the device’s switch capability.

Raises:: RuntimeError – If no switch capability is available
Return type:: None

wait_for_debounce() → None

Wait for switch relays to settle using the device’s switch capability.

Raises:: RuntimeError – If no switch capability is available
Return type:: None

property switch_cells: List[str] | List[SMUCellData]

Get the configured switch cells from the device.

Returns:: A list of DUT channel names or SMUCellData objects, which contain the DUT and switch channel information.
Return type:: List[str] | List[SMUCellData]

property acceptable_temperature_delta: float

Get the acceptable temperature delta for compensation validation.

Returns the maximum allowed temperature difference from the device’s temperature capability. This is a pass-through property that delegates to the underlying TemperatureCapability.

Returns:: The acceptable temperature delta in degrees, or NaN if no temperature capability
Return type:: float

Examples

>>> measurement = EIS(device)
>>> measurement.acceptable_temperature_delta = 2.5
>>> delta = measurement.acceptable_temperature_delta

property temperature: float

Get the latest temperature reading from the device.

Returns:: The most recent temperature measurement, or NaN if no temperature capability
Return type:: float

property temperature_range: CenteredRange

Get the latest temperature reading from the device, coupled with the user-set delta.

Returns:: A CenteredRange representing the most recent temperature measurement (NaN if not available), along with the acceptable temperature delta (NaN if not set).
Return type:: CenteredRange

measure_temperature() → CenteredRange

Get a new temperature reading from the device.

Returns:: Current temperature reading, or NaN if no temperature capability
Return type:: CenteredRange

validate_temperature(target_temperature: CenteredRange) → bool

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

Delegates to the device’s temperature capability for validation. The capability handles all validation logic including checking if thermocouple is configured, using overridden delta values if set, and printing appropriate warnings.

Parameters:

target_temperature (CenteredRange) – The target temperature parameters for validation

Returns:

True if thermocouple is configured and temperature is within range.: False if thermocouple is not configured (capability missing or not set up), or if target temperature/delta is NaN.

Return type:

bool

Raises:

TemperatureError – If the current temperature exceeds the target ± delta range (only raised when capability is configured)

Examples

>>> measurement = EIS(device)
>>> measurement.measure_temperature()
>>> target = compensation.temperature_parameter
>>> is_valid = measurement.validate_temperature(target)