impedance_agent.core package

Submodules

impedance_agent.core.config module

class Variable(*, name: str, initialValue: float, lowerBound: float, upperBound: float)[source]

Bases: BaseModel

name: str

initialValue: float

lowerBound: float

upperBound: float

classmethod validate_name(v)[source]

classmethod validate_bounds(v, values)[source]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class WeightingConfig(*, type: str = 'modulus', data: ~typing.Dict[str, ~typing.Any] = <factory>)[source]

Bases: BaseModel

type: str

data: Dict[str, Any]

classmethod validate_type(v)[source]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class FitterConfig(*, model_code: str, variables: ~typing.List[~impedance_agent.core.config.Variable], weighting: ~impedance_agent.core.config.WeightingConfig = <factory>)[source]

Bases: BaseModel

model_code: str

variables: List[Variable]

weighting: WeightingConfig

classmethod validate_model_code(v)[source]

classmethod validate_variables_unique(values)[source]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class Config(config_path: str | None = None, config_dict: Dict | None = None)[source]

Bases: object

__init__(config_path: str | None = None, config_dict: Dict | None = None)[source]

classmethod load_model(config_path: str | Path) → Dict[source]: Load model configuration from YAML file

impedance_agent.core.env module

class APIConfig(api_key: str, base_url: str, model: str)[source]

Bases: object

api_key: str

base_url: str

model: str

__init__(api_key: str, base_url: str, model: str) → None

class Environment(config_dict: dict | None = None, validate: bool = True)[source]

Bases: object

__init__(config_dict: dict | None = None, validate: bool = True)[source]

Initialize environment with optional config override for testing

Parameters:

config_dict – Optional configuration dictionary for testing
validate – Whether to validate the configuration (disable for testing)

get_provider_config(provider: str) → APIConfig | None[source]

Get the configuration for a specific provider.

Parameters:: provider – The name of the provider (‘deepseek’ or ‘openai’)
Returns:: The APIConfig for the specified provider or None if not found
Raises:: ValueError – If the provider is not supported

is_provider_configured(provider: str) → bool[source]

Check if a provider is properly configured.

Parameters:: provider – The name of the provider to check
Returns:: True if the provider has valid credentials, False otherwise

get_available_providers() → list[str][source]

Get a list of configured providers.

Returns:: List of provider names that have valid credentials

impedance_agent.core.exceptions module

exception BaseError[source]

Bases: Exception

Base exception for all custom exceptions

exception DataLoadError[source]

Bases: BaseError

Exception raised for errors during data loading

exception ConfigError[source]

Bases: BaseError

Exception raised for configuration errors

exception ValidationError[source]

Bases: BaseError

Exception raised for validation errors

exception FittingError[source]

Bases: BaseError

Exception raised for errors during fitting

exception ExportError[source]

Bases: BaseError

Exception raised for errors during result export

impedance_agent.core.exporters module

class ResultExporter[source]

Bases: object

Handles exporting analysis results to various formats with async I/O

logger = <Logger impedance_agent.core.exporters (WARNING)>

async static export_async(result: AnalysisResult, file_path: str | Path, format: str = 'json') → None[source]: Async export of analysis results to file

static export(result: AnalysisResult, file_path: str | Path, format: str = 'json') → None[source]: Synchronous wrapper for async export

impedance_agent.core.loaders module

class ImpedanceLoader[source]

Bases: object

Handles loading impedance data from various file formats

static load(file_path: str | Path) → ImpedanceData[source]: Load impedance data from file based on extension

impedance_agent.core.logging module

setup_logging(level: str = 'INFO', config_path: Path | None = None) → None[source]: Configure logging with optional configuration file

impedance_agent.core.models module

class ImpedanceData(*, frequency: ndarray, real: ndarray, imaginary: ndarray, measurement_id: str | None = None, timestamp: datetime | None = None)[source]

Bases: BaseModel

Container for electrochemical impedance spectroscopy data.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

frequency: ndarray

real: ndarray

imaginary: ndarray

measurement_id: str | None

timestamp: datetime | None

class FitQualityMetrics(*, vector_difference: float, vector_quality: str, path_deviation: float, path_quality: str, overall_quality: str)[source]

Bases: BaseModel

Quality metrics for assessing impedance fits.

References

[1] Boukamp, B.A. “A Linear Kronig-Kramers Transform Test for Immittance Data Validation.”

Electrochem. Soc. 142 (1995)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vector_difference: float

vector_quality: str

path_deviation: float

path_quality: str

overall_quality: str

class FitResult(*, parameters: List[float], errors: List[float], param_info: List[Dict], correlation_matrix: ndarray | None = None, chi_square: float, aic: float, wrms: float, dof: int, measurement_id: str | None = None, timestamp: datetime | None = None, Z_fit: ndarray | None = None, fit_quality: FitQualityMetrics | None = None)[source]

Bases: BaseModel

Results from equivalent circuit model fitting.

Notes

The fitting process uses weighted complex nonlinear least squares with:

Parameter estimation minimizing: χ² = Σᵢ wᵢ|Z_{exp,i} - Z_{fit,i}|²
Akaike Information Criterion: AIC = -2ln(L) + 2k where L is likelihood and k is number of parameters
Parameter uncertainties via QR decomposition of weighted Jacobian
Correlation matrix from Hessian of objective function

References

[1] Sadkowski, A. “CNLS fits and Kramers-Kronig validation of resonant EIS data.”: Journal of Electroanalytical Chemistry (2004)
[2] Ingdal, M., Johnsen, R., & Harrington, D. A. “The Akaike information criterion: in weighted regression of immittance data.” Electrochimica Acta (2019)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: List[float]

errors: List[float]

param_info: List[Dict]

correlation_matrix: ndarray | None

chi_square: float

aic: float

wrms: float

dof: int

measurement_id: str | None

timestamp: datetime | None

Z_fit: ndarray | None

fit_quality: FitQualityMetrics | None

class DRTResult(*, tau: ndarray, gamma: ndarray, peak_frequencies: List[float], peak_polarizations: List[float], regularization_param: float, residual: float, Z_fit: ndarray | None = None, residuals_real: ndarray | None = None, residuals_imag: ndarray | None = None, fit_quality: FitQualityMetrics | None = None)[source]

Bases: BaseModel

Results from Distribution of Relaxation Times (DRT) analysis.

Notes

The DRT analysis solves the integral equation: Z(ω) - R_∞ = R_pol ∫₀^∞ γ(τ)/(1 + iωτ)dτ

Uses Tikhonov Regularization + Projected Gradient (TRPG) method.

References

[1] Kulikovsky, A. “PEM fuel cell distribution of relaxation times: a method for the: calculation and behavior of an oxygen transport peak.” (2021)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tau: ndarray

gamma: ndarray

peak_frequencies: List[float]

peak_polarizations: List[float]

regularization_param: float

residual: float

Z_fit: ndarray | None

residuals_real: ndarray | None

residuals_imag: ndarray | None

fit_quality: FitQualityMetrics | None

class LinKKResult(*, M: int, mu: float, Z_fit: ndarray, residuals_real: ndarray, residuals_imag: ndarray, max_residual: float, mean_residual: float, fit_quality: FitQualityMetrics | None = None)[source]

Bases: BaseModel

Results from Lin-KK (Linear Kramers-Kronig) validation analysis.

References

[1] Boukamp, B.A. “A Linear Kronig‐Kramers Transform Test for Immittance Data Validation.”

Electrochem. Soc. 142 (1995)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

M: int

mu: float

Z_fit: ndarray

residuals_real: ndarray

residuals_imag: ndarray

max_residual: float

mean_residual: float

fit_quality: FitQualityMetrics | None

class AnalysisResult(*, ecm_fit: ~impedance_agent.core.models.FitResult | None = None, drt_fit: ~impedance_agent.core.models.DRTResult | None = None, linkk_fit: ~impedance_agent.core.models.LinKKResult | None = None, summary: str = '', recommendations: ~typing.List[str] = <factory>, overall_assessment: ~typing.Dict[str, ~typing.Any] = <factory>)[source]

Bases: BaseModel

Comprehensive impedance analysis results combining multiple methods.

References

[1] Barsoukov, E., Macdonald, J.R. “Impedance Spectroscopy: Theory, Experiment, and Applications.”: Wiley (2018)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ecm_fit: FitResult | None

drt_fit: DRTResult | None

linkk_fit: LinKKResult | None

summary: str

recommendations: List[str]

overall_assessment: Dict[str, Any]

impedance_agent.core.plotting module

class PlotManager[source]

Bases: object

Manages creation and export of publication-quality electrochemical analysis plots

logger = <Logger impedance_agent.core.plotting (WARNING)>

static create_plots(result: AnalysisResult, output_dir: str | Path, file_format: str = 'png', dpi: int = 600, show: bool = False) → None[source]

Generate and save publication-quality electrochemical analysis plots

Parameters:

result (AnalysisResult) – Analysis results containing impedance, DRT, and fitting data
output_dir (Union[str, Path]) – Directory where plots will be saved
file_format (str, optional) – Output file format (default: ‘png’)
dpi (int, optional) – Resolution of saved plots (default: 600)
show (bool, optional) – Whether to display plots (default: False)