# kbknudsen/pyeis architecture

> Architecture diagram of the GitHub repository kbknudsen/pyeis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kbknudsen/pyeis
- Repository: https://github.com/kbknudsen/pyeis

## Overview

##### 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”).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Notebook["Jupyter Notebook"]:::presentation
        CLI["CLI Script"]:::presentation
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        direction TB
        HighLevel["PyEIS.py\n(Orchestration)"]:::core
        DataExt["PyEIS_Data_extraction"]:::core
        KK["PyEIS_Lin_KK"]:::core
        Sim["PyEIS_Advanced_tools"]:::core
        Fit["Fitting Module"]:::core
        Param["Parameter Extraction"]:::core
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        ExtNumeric["Scientific Stack:\nnumpy, scipy, pandas,\nmpmath, lmfit"]:::external
        ExtViz["Visualization Stack:\nmatplotlib, seaborn"]:::external
    end

    %% Data Sources
    subgraph "External Data Sources"
        direction TB
        Files["Experimental Files\n(.mpt, .DTA, .z)"]:::data
    end

    %% Outputs
    subgraph "Outputs"
        direction TB
        Plots["Nyquist / Bode Plots"]:::data
        Results["Fit Parameters\n(in-memory)"]:::data
    end

    %% Packaging & Docs
    subgraph "Project Artifacts"
        direction TB
        Setup["setup.py"]:::packaging
        License["LICENSE"]:::packaging
        Changes["Changes.txt"]:::packaging
        Docs["pyEIS_images/"]:::docs
    end

    %% Data Flow
    Notebook -->|"invoke API"| HighLevel
    CLI -->|"invoke API"| HighLevel
    Files -->|"parse → DataFrame"| DataExt
    HighLevel --> DataExt
    DataExt -->|"validate → KK residuals"| KK
    HighLevel --> Sim
    KK --> Fit
    Sim --> Fit
    Fit -->|"fit → parameters"| Param
    Param --> Results
    Fit --> ExtNumeric
    HighLevel -->|"plot → Nyquist/Bode"| ExtViz
    ExtViz --> Plots

    %% Packaging & Docs Links
    Setup
    License
    Changes
    Docs

    %% Click Events
    click Notebook "https://github.com/kbknudsen/pyeis/blob/master/Tutorials/PyEIS_experimental-data_tutorial.ipynb"
    click CLI "https://github.com/kbknudsen/pyeis/blob/master/bin/PyEIS_script.py"
    click HighLevel "https://github.com/kbknudsen/pyeis/blob/master/PyEIS/PyEIS.py"
    click DataExt "https://github.com/kbknudsen/pyeis/blob/master/PyEIS/PyEIS_Data_extraction.py"
    click KK "https://github.com/kbknudsen/pyeis/blob/master/PyEIS/PyEIS_Lin_KK.py"
    click Sim "https://github.com/kbknudsen/pyeis/blob/master/PyEIS/PyEIS_Advanced_tools.py"
    click Setup "https://github.com/kbknudsen/pyeis/blob/master/setup.py"
    click License "https://github.com/kbknudsen/pyeis/tree/master/LICENSE"
    click Changes "https://github.com/kbknudsen/pyeis/blob/master/Changes.txt"
    click Docs "https://github.com/kbknudsen/pyeis/tree/master/pyEIS_images/"

    %% Styles
    classDef presentation fill:#E0F7FA,stroke:#333,stroke-width:1px;
    classDef core fill:#E8F5E9,stroke:#333,stroke-width:1px;
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px;
    classDef data fill:#FFF9C4,stroke:#333,stroke-width:1px;
    classDef packaging fill:#F3E5F5,stroke:#333,stroke-width:1px;
    classDef docs fill:#FFEBEE,stroke:#333,stroke-width:1px;
```
