nibcq.compensation.CompensationParameter

class nibcq.compensation.CompensationParameter

Represents compensation parameters for a specific frequency point.

This class encapsulates the frequency-specific compensation data used in ACIR/EIS measurements for error correction. Each instance represents a single frequency point with its associated complex impedance compensation value.

The compensation value is typically obtained through calibration measurements using known standards (short circuits, golden reference devices, etc.) and is applied to raw measurements to improve accuracy by correcting for systematic errors in the measurement system.

frequency: The frequency in Hertz for which this compensation applies. Must be a positive value.

compensation_value: The complex impedance compensation value in Ohms. Applied to raw measurements through mathematical operations (typically subtraction for SHORT compensation).

Example

>>> param = CompensationParameter(frequency=1000.0, compensation_value=10+5j)
>>> param.frequency
1000.0
>>> param.compensation_value
(10+5j)

classmethod from_item_dict(item: Dict[str, Any])

Build from a row dict.

Supports:

{“Frequency (Hz)”: <float>, “Compensation Value (Ohm)”: “<a+b i>”}

Parameters:: item (Dict[str, Any])

to_item_dict() → Dict[str, Any]

Single item representation used for JSON rows (frequency + value).

Return type:: Dict[str, Any]

static dict_to_list(param_dict: Dict[float, complex]) → list[CompensationParameter]

Convert a frequency-to-impedance dictionary into a list of CompensationParameter objects.

Transforms a dictionary mapping frequencies to complex impedance values into a structured list of CompensationParameter objects. The resulting list is sorted in descending frequency order for consistency with file formats.

Parameters:

param_dict (Dict[float, complex]) – Dictionary mapping frequency values (Hz) to complex impedance values (Ohms). Frequencies should be positive numbers.

Returns:

List of CompensationParameter objects sorted: by descending frequency.

Return type:

list[CompensationParameter]

Example

>>> freq_dict = {1000.0: 10+5j, 2000.0: 15+3j, 500.0: 8+7j}
>>> param_list = CompensationParameter.dict_to_list(freq_dict)
>>> len(param_list)
3
>>> param_list[0].frequency  # Highest frequency first
2000.0
>>> param_list[0].compensation_value
(15+3j)

static list_to_dict(param_list: list[CompensationParameter]) → Dict[float, complex]

Convert a list of CompensationParameter objects into a frequency-to-impedance dictionary.

Transforms a list of CompensationParameter objects into a dictionary mapping frequencies to complex impedance values. The resulting dictionary maintains descending frequency order for consistency.

Parameters:

param_list (list[CompensationParameter]) – List of CompensationParameter objects to convert.

Returns:

Dictionary mapping frequency values (Hz) to complex: impedance values (Ohms), ordered by descending frequency.

Return type:

Dict[float, complex]

Example

>>> params = [
...     CompensationParameter(1000.0, 10+5j),
...     CompensationParameter(2000.0, 15+3j)
... ]
>>> freq_dict = CompensationParameter.list_to_dict(params)
>>> freq_dict[1000.0]
(10+5j)
>>> list(freq_dict.keys())  # Descending order
[2000.0, 1000.0]

static validate_frequency_uniqueness(param_list: list[CompensationParameter]) → None

Validate that all frequencies in a CompensationParameter list are unique.

Ensures that there are no duplicate frequency values in the parameter list, which is essential for proper interpolation and compensation calculations. Duplicate frequencies would create ambiguous compensation values.

Parameters:: param_list (list[CompensationParameter]) – List of CompensationParameter objects to validate.
Raises:: ValueError – If duplicate frequencies are found, with details about which frequency is duplicated.
Return type:: None

Example

>>> params = [
...     CompensationParameter(1000.0, 10+5j),
...     CompensationParameter(2000.0, 15+3j)
... ]
>>> CompensationParameter.validate_frequency_uniqueness(params)  # No error
>>>
>>> duplicate_params = [
...     CompensationParameter(1000.0, 10+5j),
...     CompensationParameter(1000.0, 15+3j)  # Same frequency!
... ]
>>> CompensationParameter.validate_frequency_uniqueness(duplicate_params)
ValueError: Duplicate frequency found: 1000.0 Hz