ici-analysis 2.1.0__tar.gz

ici_analysis-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José J. Arroyo Gómez 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ici_analysis-2.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: ici-analysis
+Version: 2.1.0
+Summary: GUI tool for Intermittent Current Interruption (ICI) analysis of battery cycling data
+Author: José J. Arroyo-Gómez
+License: MIT
+Project-URL: Homepage, https://github.com/Joe-Arroyo/pyICI
+Project-URL: Repository, https://github.com/Joe-Arroyo/pyICI
+Keywords: electrochemistry,batteries,intermittent current interruption,internal resistance,diffusion
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: customtkinter>=5.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Dynamic: license-file
+
+# pyICI
+
+**Python-based Interactive Interface for Intermittent Current Interruption (ICI) data analysis for Battery Research**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+![tests](https://github.com/Joe-Arroyo/pyICI/actions/workflows/tests.yml/badge.svg)
+
+## Overview
+
+Intermittent current interruption (ICI) is an electrochemical technique used for the diagnostic analysis of battery systems. It involves introducing brief interruptions or pauses (1–10 seconds) into a constant current charge–discharge cycle and analyzing the voltage response during each interruption. The technique characterizes cell resistance using two parameters: the internal resistance (*R*, Ω), which captures Ohmic contributions, and the diffusion resistance coefficient (*k*, Ω s<sup>−1/2</sup>), which captures solid-state mass transport effects. Because ICI assumes a diffusion-controlled system, cycling must be performed at a comparatively slow rate of C/5 or lower. 
+
+pyICI is a GUI-based analysis tool designed for researchers working with electrochemical ICI data. The tool facilitates the calculation of *R* and *k* from datasets with one or more cycles. 
+
+Technical details of the ICI technique and associated literature can be found on the website of Dr. Matthew J. Lacey ([link here](https://lacey.se/projects/ici)), who developed the technique for routine battery analysis.
+
+## Features
+
+The GUI is organized into four sections:
+
+- **Data loading & visualization**: Import and view cycling data — several files at once, with an optional overlay to compare them.
+  - Automatic ICI cycle detection for three-column files; a column-mapping dialog for files with more columns
+  - Charge / discharge classification, coloured by cycle
+  - Plots: voltage vs time (all cycles, a subset, or a single cycle, with an optional current subplot) and voltage vs capacity / specific capacity
+  - CSV export of the capacity data
+
+- **Pulse verification**: Step through a cycle's current-interruption pulses to check they are segmented correctly.
+  - Whole-cycle overview with the selected pulse highlighted
+  - Per-pulse detail (voltage + current) and a zoom on the rest-period relaxation with *V₀* marked
+
+- **Regression**: Interactively perform linear regression of the voltage vs $\sqrt{time}$ data during each ICI step.
+  - User-defined fit window (time or index), applied to a single pulse, a whole cycle, or all cycles, and saved per file
+  - Fit parameters (slope, intercept) evaluated with R<sup>2</sup>, using the covariance matrix for error propagation
+  - The regression fit and an R<sup>2</sup>-across-pulses plot shown together, with axis-limit controls; an "Overall check" of R<sup>2</sup> across every cycle
+  - *R* and *k* shown on the fit plot, and a secondary time axis on the ΔV-vs-√time plot
+
+- **Kinetic analysis**: *R* and *k* calculation from the regression parameters.
+  - $R = - \frac{intercept}{I}$ and $k = - \frac{slope}{I}$, with *I* the current before the interruption
+  - *R* and *k* vs voltage, capacity, or specific capacity — coloured by cycle, with axis-limit controls and multi-file overlay
+  - Covariance-based error bars
+  - CSV export (per phase, and per file when overlaid) of *V*, *R*, *R_errors*, *k*, *k_errors* and *R*<sup>2</sup>, plus figure export (*R*, *k*, or both)
+
+## Installation
+
+- Compatible with Python 3.9 - 3.13
+
+### Quick install (from PyPI)
+
+The easiest way to get pyICI. This installs pyICI and all of its dependencies and
+adds a `pyici` command that launches the GUI:
+
+```bash
+pip install ici-analysis
+pyici
+```
+
+> On **Linux** you may first need the system `tkinter` package (see the note in
+> Step 1 below). Installing into a virtual environment is recommended (see Step 3).
+
+---
+
+### Install from source
+
+Use the steps below to run the latest (unreleased) code or to develop pyICI —
+they install from a clone of the repository.
+
+### Step 1: **Install Python:**
+**Windows:**
+Download the installer from [python.org](https://www.python.org/downloads/) and run it. Make sure to check "Add Python to PATH" during installation.
+
+**macOS:**
+Download the installer from [python.org](https://www.python.org/downloads/), or install via Homebrew:
+```bash
+brew install python
+```
+
+**Linux:**
+Python is usually pre-installed. Verify with:
+```bash
+python3 --version
+```
+If not installed, use your package manager:
+```bash
+# Ubuntu/Debian
+sudo apt install python3 python3-pip
+```
+
+> **Note on tkinter**: pyICI uses `tkinter` for its GUI. Installation varies by platform:
+> - **Windows**: included with the standard Python installer, no action needed
+> - **macOS**: included with Python from python.org. If using Homebrew: `brew install python-tk`
+> - **Ubuntu/Debian**: `sudo apt install python3-tk`
+> - **Fedora**: `sudo dnf install python3-tkinter`
+> - **CentOS/RHEL**: `sudo yum install python3-tkinter`
+
+---
+
+ ### Step 2: **Download the project:**
+ Open a terminal (Command prompt on Windows, Terminal on macOS/Linux) and run:
+```bash
+# Clone the repository
+git clone https://github.com/Joe-Arroyo/pyICI.git
+cd pyICI
+```
+Or download the ZIP file and extract it.
+
+---
+
+### Step 3: Create a virtual environment (recommended)
+
+Using a virtual environment keeps pyICI's dependencies isolated from other Python projects on your system.
+
+**Windows (Command Prompt):**
+```cmd
+python -m venv venv
+venv\Scripts\activate
+```
+
+**macOS / Linux:**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+You should see `(venv)` in your terminal prompt. To deactivate later, run `deactivate`.
+
+--- 
+
+### Step4:. **Install Python dependencies:**
+```bash
+pip install -e .     # installs pyICI; the `pyici` command then launches the GUI
+pyici                # GUI launches
+python main_gui.py   # also works
+```
+
+### Step 5: Run pyICI
+
+**Windows:**
+```bash
+python main_gui.py
+```
+
+**macOS / Linux:**
+```bash
+python3 main_gui.py
+```
+
+---
+
+### Step 6: Get started
+
+See the [Tutorial](Tutorial.md) for a quick guide through pyICI's features.
+
+---
+
+## Use as a library
+
+Beyond the GUI, pyICI can be scripted — useful for batch-processing many files or
+feeding *R* / *k* into your own analysis. Import everything from the top-level
+`pyici` package (no GUI / tkinter needed):
+
+```python
+import pyici
+
+# 1. Load a data file  ->  df_raw, cycle_list, data_format, ...
+data = pyici.run_data_analysis("path/to/folder", "cell01.txt")   # or pyici.load_data(...)
+
+# 2. Inspect a cycle's current-interruption pulses
+pulses = pyici.analyze_cycle_pulses(data.df_raw, cycle_num=1)     # or pyici.segment_pulses(...)
+
+# 3. Compute R (Ω) and k (Ω·s^-1/2) for some cycles, charge phase,
+#    using the default 0.1-1.0 s fit window
+rk = pyici.compute_R_k_for_cycles(                                # or pyici.compute_rk(...)
+    data.df_raw, data.cycle_list, "charge",
+    "time", pyici.DEFAULT_TIME_START, pyici.DEFAULT_TIME_END, {}, mass_mg=0.0,
+)
+for cyc in rk:
+    print(cyc["cycle"], cyc["R"], cyc["k"])
+
+# 4. Or write the R/k results to CSV (charge and discharge in separate files)
+pyici.export_R_k_results(data.df_raw, data.cycle_list, output_folder="exports")
+```
+
+`pyici.load_data`, `pyici.segment_pulses` and `pyici.compute_rk` are friendly
+aliases for the three most common calls. `print(pyici.__version__)` reports the
+installed version.
+
+---
+
+## AI Assistance
+This project was developed with the assistance of Claude (Anthropic). All code has been reviewed and tested by the authors.

ici_analysis-2.1.0/README.md

@@ -0,0 +1,191 @@
+# pyICI
+
+**Python-based Interactive Interface for Intermittent Current Interruption (ICI) data analysis for Battery Research**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+![tests](https://github.com/Joe-Arroyo/pyICI/actions/workflows/tests.yml/badge.svg)
+
+## Overview
+
+Intermittent current interruption (ICI) is an electrochemical technique used for the diagnostic analysis of battery systems. It involves introducing brief interruptions or pauses (1–10 seconds) into a constant current charge–discharge cycle and analyzing the voltage response during each interruption. The technique characterizes cell resistance using two parameters: the internal resistance (*R*, Ω), which captures Ohmic contributions, and the diffusion resistance coefficient (*k*, Ω s<sup>−1/2</sup>), which captures solid-state mass transport effects. Because ICI assumes a diffusion-controlled system, cycling must be performed at a comparatively slow rate of C/5 or lower. 
+
+pyICI is a GUI-based analysis tool designed for researchers working with electrochemical ICI data. The tool facilitates the calculation of *R* and *k* from datasets with one or more cycles. 
+
+Technical details of the ICI technique and associated literature can be found on the website of Dr. Matthew J. Lacey ([link here](https://lacey.se/projects/ici)), who developed the technique for routine battery analysis.
+
+## Features
+
+The GUI is organized into four sections:
+
+- **Data loading & visualization**: Import and view cycling data — several files at once, with an optional overlay to compare them.
+  - Automatic ICI cycle detection for three-column files; a column-mapping dialog for files with more columns
+  - Charge / discharge classification, coloured by cycle
+  - Plots: voltage vs time (all cycles, a subset, or a single cycle, with an optional current subplot) and voltage vs capacity / specific capacity
+  - CSV export of the capacity data
+
+- **Pulse verification**: Step through a cycle's current-interruption pulses to check they are segmented correctly.
+  - Whole-cycle overview with the selected pulse highlighted
+  - Per-pulse detail (voltage + current) and a zoom on the rest-period relaxation with *V₀* marked
+
+- **Regression**: Interactively perform linear regression of the voltage vs $\sqrt{time}$ data during each ICI step.
+  - User-defined fit window (time or index), applied to a single pulse, a whole cycle, or all cycles, and saved per file
+  - Fit parameters (slope, intercept) evaluated with R<sup>2</sup>, using the covariance matrix for error propagation
+  - The regression fit and an R<sup>2</sup>-across-pulses plot shown together, with axis-limit controls; an "Overall check" of R<sup>2</sup> across every cycle
+  - *R* and *k* shown on the fit plot, and a secondary time axis on the ΔV-vs-√time plot
+
+- **Kinetic analysis**: *R* and *k* calculation from the regression parameters.
+  - $R = - \frac{intercept}{I}$ and $k = - \frac{slope}{I}$, with *I* the current before the interruption
+  - *R* and *k* vs voltage, capacity, or specific capacity — coloured by cycle, with axis-limit controls and multi-file overlay
+  - Covariance-based error bars
+  - CSV export (per phase, and per file when overlaid) of *V*, *R*, *R_errors*, *k*, *k_errors* and *R*<sup>2</sup>, plus figure export (*R*, *k*, or both)
+
+## Installation
+
+- Compatible with Python 3.9 - 3.13
+
+### Quick install (from PyPI)
+
+The easiest way to get pyICI. This installs pyICI and all of its dependencies and
+adds a `pyici` command that launches the GUI:
+
+```bash
+pip install ici-analysis
+pyici
+```
+
+> On **Linux** you may first need the system `tkinter` package (see the note in
+> Step 1 below). Installing into a virtual environment is recommended (see Step 3).
+
+---
+
+### Install from source
+
+Use the steps below to run the latest (unreleased) code or to develop pyICI —
+they install from a clone of the repository.
+
+### Step 1: **Install Python:**
+**Windows:**
+Download the installer from [python.org](https://www.python.org/downloads/) and run it. Make sure to check "Add Python to PATH" during installation.
+
+**macOS:**
+Download the installer from [python.org](https://www.python.org/downloads/), or install via Homebrew:
+```bash
+brew install python
+```
+
+**Linux:**
+Python is usually pre-installed. Verify with:
+```bash
+python3 --version
+```
+If not installed, use your package manager:
+```bash
+# Ubuntu/Debian
+sudo apt install python3 python3-pip
+```
+
+> **Note on tkinter**: pyICI uses `tkinter` for its GUI. Installation varies by platform:
+> - **Windows**: included with the standard Python installer, no action needed
+> - **macOS**: included with Python from python.org. If using Homebrew: `brew install python-tk`
+> - **Ubuntu/Debian**: `sudo apt install python3-tk`
+> - **Fedora**: `sudo dnf install python3-tkinter`
+> - **CentOS/RHEL**: `sudo yum install python3-tkinter`
+
+---
+
+ ### Step 2: **Download the project:**
+ Open a terminal (Command prompt on Windows, Terminal on macOS/Linux) and run:
+```bash
+# Clone the repository
+git clone https://github.com/Joe-Arroyo/pyICI.git
+cd pyICI
+```
+Or download the ZIP file and extract it.
+
+---
+
+### Step 3: Create a virtual environment (recommended)
+
+Using a virtual environment keeps pyICI's dependencies isolated from other Python projects on your system.
+
+**Windows (Command Prompt):**
+```cmd
+python -m venv venv
+venv\Scripts\activate
+```
+
+**macOS / Linux:**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+You should see `(venv)` in your terminal prompt. To deactivate later, run `deactivate`.
+
+--- 
+
+### Step4:. **Install Python dependencies:**
+```bash
+pip install -e .     # installs pyICI; the `pyici` command then launches the GUI
+pyici                # GUI launches
+python main_gui.py   # also works
+```
+
+### Step 5: Run pyICI
+
+**Windows:**
+```bash
+python main_gui.py
+```
+
+**macOS / Linux:**
+```bash
+python3 main_gui.py
+```
+
+---
+
+### Step 6: Get started
+
+See the [Tutorial](Tutorial.md) for a quick guide through pyICI's features.
+
+---
+
+## Use as a library
+
+Beyond the GUI, pyICI can be scripted — useful for batch-processing many files or
+feeding *R* / *k* into your own analysis. Import everything from the top-level
+`pyici` package (no GUI / tkinter needed):
+
+```python
+import pyici
+
+# 1. Load a data file  ->  df_raw, cycle_list, data_format, ...
+data = pyici.run_data_analysis("path/to/folder", "cell01.txt")   # or pyici.load_data(...)
+
+# 2. Inspect a cycle's current-interruption pulses
+pulses = pyici.analyze_cycle_pulses(data.df_raw, cycle_num=1)     # or pyici.segment_pulses(...)
+
+# 3. Compute R (Ω) and k (Ω·s^-1/2) for some cycles, charge phase,
+#    using the default 0.1-1.0 s fit window
+rk = pyici.compute_R_k_for_cycles(                                # or pyici.compute_rk(...)
+    data.df_raw, data.cycle_list, "charge",
+    "time", pyici.DEFAULT_TIME_START, pyici.DEFAULT_TIME_END, {}, mass_mg=0.0,
+)
+for cyc in rk:
+    print(cyc["cycle"], cyc["R"], cyc["k"])
+
+# 4. Or write the R/k results to CSV (charge and discharge in separate files)
+pyici.export_R_k_results(data.df_raw, data.cycle_list, output_folder="exports")
+```
+
+`pyici.load_data`, `pyici.segment_pulses` and `pyici.compute_rk` are friendly
+aliases for the three most common calls. `print(pyici.__version__)` reports the
+installed version.
+
+---
+
+## AI Assistance
+This project was developed with the assistance of Claude (Anthropic). All code has been reviewed and tested by the authors.