How kbknudsen/pyeis works
Project type and purpose
• PyEIS is an open-source Python library/tool for Electrochemical Impedance Spectroscopy (EIS) simulation, data extraction, validation (Kramers-Kronig), fitting, and plotting.
• It does not provide a standalone GUI or web service; instead it exposes a Python API and a small CLI wrapper for batch scripts. Tutorials in Jupyter notebooks demonstrate usage.
File structure
• Top-level artifacts:
• setup.py / LICENSE / Changes.txt – packaging, licensing, changelog
• PyEIS/ – core package containing:
– PyEIS.py (main entry point and high-level orchestration)
– PyEIS_Data_extraction.py (file parsers for .mpt/.DTA/.z)
– PyEIS_Lin_KK.py (Kramers-Kronig validation)
– PyEIS_Advanced_tools.py (simulation & numeric tools)
– __init__.py
• bin/PyEIS_script.py – thin CLI wrapper invoking PyEIS API
• Tutorials/ – demonstration notebooks and sample data (not part of runtime)
• pyEIS_images/ – documentation assets
README for additional insights
• Nine core features: built-in equivalent circuits, plotting, file import, validation, fitting with lmfit, batch fitting, parameter extraction, extensibility.
• Dependencies: numpy, scipy, pandas, mpmath, lmfit, matplotlib, seaborn.
• Usage context: Python REPL or Jupyter, with outputs as in-memory variables and plots.
Diagramming the system
a. Main components
• User Interface Layer
– Jupyter Notebooks (Tutorials)
– CLI Script (bin/PyEIS_script.py)
• Core Library Layer (PyEIS package)
– Data Extraction Module
– Linear KK Validation Module
– Simulation & Circuit Module
– Fitting Module
– Parameter Extraction Module
• External Dependencies
– numpy, scipy, pandas, mpmath, lmfit (numeric & fitting engines)
– matplotlib, seaborn (visualization)
• External Data Sources
– Experimental files (.mpt, .DTA, .z)
• Outputs
– Nyquist/Bode plots
– Fitted parameter sets (in-memory variables)
b. Relationships & interactions
– The User (notebook or CLI) invokes high-level API calls in PyEIS.py
– API dispatches to Data Extraction when importing files
– Extracted data flows to KK Validation module
– Validated data or simulated data flows into Fitting module, which calls lmfit
– Simulation module can generate synthetic data based on built-in circuits
– All data back to Visualization layer for plotting
– Parameter Extraction collects fit results for downstream analysis
c. Architectural patterns / design principles
– Layered architecture: Presentation → Core logic → External libraries
– Separation of concerns: file parsing, validation, simulation, fitting, plotting are distinct modules
– Extensibility: new circuits or file formats can be added via well-defined module interfaces
d. Key technologies and frameworks
– Python 3 package structure (setup.py for pip install)
– lmfit for non-linear least squares
– numpy/scipy for numeric computing
– pandas for data handling
– mpmath for arbitrary precision
– matplotlib / seaborn for plotting
– Jupyter notebooks as interactive usage demos
Detail
– Label every component and interface explicitly.
– Include notes on extensibility points (e.g., “Add new circuit in PyEIS_Advanced_tools.py”).