eisyfit 0.1.2__tar.gz

eisyfit-0.1.2/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: eisyfit
+Version: 0.1.2
+Summary: Interactive desktop application for exploring, cleaning, and fitting BioLogic electrochemical impedance spectra.
+Author: Jaroslav Herman
+Project-URL: Homepage, https://github.com/jaroslav-herman/EIS_fitting
+Project-URL: Repository, https://github.com/jaroslav-herman/EIS_fitting
+Project-URL: Issues, https://github.com/jaroslav-herman/EIS_fitting/issues
+Keywords: electrochemistry,impedance spectroscopy,EIS,BioLogic,equivalent circuit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: eisyfit-bayes-drt2>=0.2
+Requires-Dist: eisyfit-hybrid-drt>=0.1
+Requires-Dist: impedance>=1.7.1
+Requires-Dist: matplotlib>=3.11.1
+Requires-Dist: natsort>=8.4.0
+Requires-Dist: numpy>=2.5.1
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: scipy>=1.18.0
+Requires-Dist: pyarrow>=25.0.1
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: pygad>=3.6.0
+Requires-Dist: pyswarms>=1.3
+Requires-Dist: eisyfit-wepy>=0.1.2
+
+## EIS Fitting
+
+EIS Fitting is a desktop application for exploring, cleaning, and fitting
+electrochemical impedance spectroscopy (EIS) data exported by BioLogic as
+`.mpt` (PEIS) files. It combines an interactive Nyquist plot with circuit
+parameter editing, cycle-aware analysis, DRT-assisted outlier detection, and
+batch fitting, so spectra can be reviewed and fitted without leaving the GUI.
+
+The application:
+
+- Supports multiple files and multiple measurement cycles
+- Displays spectra beside an editable equivalent-circuit parameter table
+- Lets you include or exclude individual points while preserving cycle state
+- Runs fitting and outlier detection in the background so the GUI stays responsive
+- Uses `bayes-drt2` ridge analysis to identify outliers and initialize circuit fits
+- Compares measured and fitted points at identical frequencies with residual connectors
+- Provides a sortable spectra explorer for cycle and acquisition metadata
+- Exports fitted parameters and spectrum metadata to CSV and a ready-to-run Python script
+
+## Installation
+
+### Requirements
+
+- Windows, macOS, or Linux with a desktop environment
+- Python 3.14 or newer
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/), the environment and dependency manager used by this project
+
+### Install from GitHub
+
+In PowerShell, Terminal, or a shell:
+
+```text
+git clone https://github.com/jaroslav-herman/EIS_fitting.git
+cd EIS_fitting
+uv sync
+```
+
+`uv sync` creates the project environment and installs the versions recorded
+in `uv.lock`, including the required EIS and DRT libraries. Re-run it after
+pulling changes to update the environment.
+
+### Start the application
+
+From the repository directory, run:
+
+```text
+uv run python main.py
+```
+
+To open a BioLogic file immediately and select a cycle:
+
+```text
+uv run python main.py PEIS_at_N2_flow_80_sccm_automated_01_PEIS.mpt --cycle 1
+```
+
+On Windows, `run_gui.cmd` can also be double-clicked. It checks that `uv` is
+available and starts the application from the repository directory.
+
+If `uv` is not available, install it using the official instructions linked
+above, then open a new terminal and repeat `uv sync`.
+
+## Run
+
+The command-line entry point also accepts options for the initial control
+channel, outlier threshold, and equivalent-circuit model:
+
+```text
+uv run python main.py PEIS_at_N2_flow_80_sccm_automated_01_PEIS.mpt --cycle 1 --threshold 1.0 --circuit "R0-L0-p(R1,CPE1)"
+```
+
+### GUI controls
+
+- Click a point: toggle include/exclude
+- Cycle arrows or selector: move between cycles
+- Spectra explorer: select a spectrum or sort rows by source file, cycle, voltage, current, point count, or frequency limits
+- Fitting model: select a preset or enter an `impedance.py` circuit string, then set it
+- Apply to current cycle: use the frequency range only for the displayed spectrum
+- Apply to all cycles: use the frequency range for every spectrum in the file
+- Outliers: current: run the bayes-drt2 ridge analysis on active points only, apply its outlier mask without reactivating excluded points, and initialize the EEC fit from its ohmic resistance, inductance, and strongest DRT peaks
+- Outliers: all cycles: perform the same active-point analysis and EEC initialization for every spectrum in the background
+- Fit spectrum: fit included points with the parameter table values
+- Batch fit from current: fit toward higher cycles, using each result to initialize the next
+- Export to Python: save fitted parameters and spectrum metadata from all loaded files to CSV, create a ready-to-run pandas script, and open it in VS Code or another available editor
+- Reset points: include all points and clear detected outliers
+
+The **File** menu contains additive multi-file data import, project load/save, mask saving, fit-parameter and Python-workspace exports, and exit commands. Import accepts several `.mpt` files at once and keeps previously loaded spectra.
+
+The **Fit** menu fits the selected spectrum or batch-fits upward/downward through the explorer's visible order. Metadata-limited batches use the last clicked numeric explorer column and stop at its nearest available target value.
+
+Outlier detection never runs automatically. Cycle state is retained while the GUI is open.
+
+Keyboard shortcuts:
+
+- `Alt+A`: copy fitted values from the previous cycle into the current initial values
+- `Alt+D`: copy fitted values from the next cycle into the current initial values
+- `Alt+S`: fit the selected spectrum
+- `Ctrl+O`: import another `.mpt` data file
+- `Ctrl+Shift+O`: load an EIS fitting project
+- `Ctrl+S`: save the EIS fitting project
+
+### Code structure
+
+- `eis_model.py`: GUI-independent project and per-cycle state
+- `eis_services.py`: file loading, outlier detection, and fitting operations
+- `eis_project.py`: versioned project persistence and fit CSV export
+- `eis_gui.py`: Tk interface, plot rendering, and event coordination
+- `main.py`: command-line entry point

eisyfit-0.1.2/README.md

@@ -0,0 +1,107 @@
+## EIS Fitting
+
+EIS Fitting is a desktop application for exploring, cleaning, and fitting
+electrochemical impedance spectroscopy (EIS) data exported by BioLogic as
+`.mpt` (PEIS) files. It combines an interactive Nyquist plot with circuit
+parameter editing, cycle-aware analysis, DRT-assisted outlier detection, and
+batch fitting, so spectra can be reviewed and fitted without leaving the GUI.
+
+The application:
+
+- Supports multiple files and multiple measurement cycles
+- Displays spectra beside an editable equivalent-circuit parameter table
+- Lets you include or exclude individual points while preserving cycle state
+- Runs fitting and outlier detection in the background so the GUI stays responsive
+- Uses `bayes-drt2` ridge analysis to identify outliers and initialize circuit fits
+- Compares measured and fitted points at identical frequencies with residual connectors
+- Provides a sortable spectra explorer for cycle and acquisition metadata
+- Exports fitted parameters and spectrum metadata to CSV and a ready-to-run Python script
+
+## Installation
+
+### Requirements
+
+- Windows, macOS, or Linux with a desktop environment
+- Python 3.14 or newer
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/), the environment and dependency manager used by this project
+
+### Install from GitHub
+
+In PowerShell, Terminal, or a shell:
+
+```text
+git clone https://github.com/jaroslav-herman/EIS_fitting.git
+cd EIS_fitting
+uv sync
+```
+
+`uv sync` creates the project environment and installs the versions recorded
+in `uv.lock`, including the required EIS and DRT libraries. Re-run it after
+pulling changes to update the environment.
+
+### Start the application
+
+From the repository directory, run:
+
+```text
+uv run python main.py
+```
+
+To open a BioLogic file immediately and select a cycle:
+
+```text
+uv run python main.py PEIS_at_N2_flow_80_sccm_automated_01_PEIS.mpt --cycle 1
+```
+
+On Windows, `run_gui.cmd` can also be double-clicked. It checks that `uv` is
+available and starts the application from the repository directory.
+
+If `uv` is not available, install it using the official instructions linked
+above, then open a new terminal and repeat `uv sync`.
+
+## Run
+
+The command-line entry point also accepts options for the initial control
+channel, outlier threshold, and equivalent-circuit model:
+
+```text
+uv run python main.py PEIS_at_N2_flow_80_sccm_automated_01_PEIS.mpt --cycle 1 --threshold 1.0 --circuit "R0-L0-p(R1,CPE1)"
+```
+
+### GUI controls
+
+- Click a point: toggle include/exclude
+- Cycle arrows or selector: move between cycles
+- Spectra explorer: select a spectrum or sort rows by source file, cycle, voltage, current, point count, or frequency limits
+- Fitting model: select a preset or enter an `impedance.py` circuit string, then set it
+- Apply to current cycle: use the frequency range only for the displayed spectrum
+- Apply to all cycles: use the frequency range for every spectrum in the file
+- Outliers: current: run the bayes-drt2 ridge analysis on active points only, apply its outlier mask without reactivating excluded points, and initialize the EEC fit from its ohmic resistance, inductance, and strongest DRT peaks
+- Outliers: all cycles: perform the same active-point analysis and EEC initialization for every spectrum in the background
+- Fit spectrum: fit included points with the parameter table values
+- Batch fit from current: fit toward higher cycles, using each result to initialize the next
+- Export to Python: save fitted parameters and spectrum metadata from all loaded files to CSV, create a ready-to-run pandas script, and open it in VS Code or another available editor
+- Reset points: include all points and clear detected outliers
+
+The **File** menu contains additive multi-file data import, project load/save, mask saving, fit-parameter and Python-workspace exports, and exit commands. Import accepts several `.mpt` files at once and keeps previously loaded spectra.
+
+The **Fit** menu fits the selected spectrum or batch-fits upward/downward through the explorer's visible order. Metadata-limited batches use the last clicked numeric explorer column and stop at its nearest available target value.
+
+Outlier detection never runs automatically. Cycle state is retained while the GUI is open.
+
+Keyboard shortcuts:
+
+- `Alt+A`: copy fitted values from the previous cycle into the current initial values
+- `Alt+D`: copy fitted values from the next cycle into the current initial values
+- `Alt+S`: fit the selected spectrum
+- `Ctrl+O`: import another `.mpt` data file
+- `Ctrl+Shift+O`: load an EIS fitting project
+- `Ctrl+S`: save the EIS fitting project
+
+### Code structure
+
+- `eis_model.py`: GUI-independent project and per-cycle state
+- `eis_services.py`: file loading, outlier detection, and fitting operations
+- `eis_project.py`: versioned project persistence and fit CSV export
+- `eis_gui.py`: Tk interface, plot rendering, and event coordination
+- `main.py`: command-line entry point

eisyfit-0.1.2/circuit_structure.py

@@ -0,0 +1,157 @@
+"""Physical circuit structure helpers.
+
+Circuit element suffixes are identifiers, not part of the physical topology.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+
+@dataclass(frozen=True)
+class CircuitNode:
+    kind: str
+    value: str | None = None
+    children: tuple["CircuitNode", ...] = ()
+
+
+def _group(kind: str, children: list[CircuitNode]) -> CircuitNode:
+    flattened: list[CircuitNode] = []
+    for child in children:
+        if child.kind == kind:
+            flattened.extend(child.children)
+        else:
+            flattened.append(child)
+    if len(flattened) == 1:
+        return flattened[0]
+    return CircuitNode(kind, children=tuple(flattened))
+
+
+class _Parser:
+    def __init__(self, text: str):
+        self.text = re.sub(r"\s+", "", text)
+        self.index = 0
+
+    def parse(self) -> CircuitNode:
+        if not self.text:
+            raise ValueError("circuit is empty")
+        node = self._parse_series()
+        if self.index != len(self.text):
+            raise ValueError(f"unexpected circuit text at position {self.index}")
+        return node
+
+    def _parse_series(self) -> CircuitNode:
+        children = [self._parse_term()]
+        while self.index < len(self.text) and self.text[self.index] == "-":
+            self.index += 1
+            children.append(self._parse_term())
+        return _group("series", children)
+
+    def _parse_term(self) -> CircuitNode:
+        if self.text.startswith("p(", self.index):
+            self.index += 2
+            children = [self._parse_series_until(",", ")")]
+            while self.index < len(self.text) and self.text[self.index] == ",":
+                self.index += 1
+                children.append(self._parse_series_until(",", ")"))
+            if self.index >= len(self.text) or self.text[self.index] != ")":
+                raise ValueError("unclosed parallel circuit block")
+            self.index += 1
+            return _group("parallel", children)
+        start = self.index
+        while self.index < len(self.text) and self.text[self.index] not in "-,)":
+            self.index += 1
+        if start == self.index:
+            raise ValueError(f"expected circuit element at position {self.index}")
+        token = self.text[start:self.index]
+        element_type = re.match(r"[A-Za-z]+", token)
+        if element_type is None:
+            raise ValueError(f"invalid circuit element {token!r}")
+        return CircuitNode("element", token)
+
+    def _parse_series_until(self, *terminators: str) -> CircuitNode:
+        start = self.index
+        children = [self._parse_term()]
+        while self.index < len(self.text) and self.text[self.index] == "-":
+            if self.index + 1 < len(self.text) and self.text[self.index + 1] in terminators:
+                break
+            self.index += 1
+            children.append(self._parse_term())
+        if self.index == start:
+            raise ValueError("empty circuit block")
+        return _group("series", children)
+
+
+def parse_circuit(circuit: str) -> CircuitNode:
+    return _Parser(circuit).parse()
+
+
+def _element_type(token: str) -> str:
+    match = re.match(r"[A-Za-z]+", token)
+    return match.group(0).casefold() if match else token.casefold()
+
+
+def canonical_circuit(circuit: str) -> tuple:
+    def canonical(node: CircuitNode) -> tuple:
+        if node.kind == "element":
+            return ("element", _element_type(node.value or ""))
+        children = tuple(sorted((canonical(child) for child in node.children), key=repr))
+        return (node.kind, children)
+
+    return canonical(parse_circuit(circuit))
+
+
+def circuits_equivalent(first: str | None, second: str | None) -> bool:
+    try:
+        return canonical_circuit(first or "") == canonical_circuit(second or "")
+    except ValueError:
+        return re.sub(r"\s+", "", str(first or "")).casefold() == re.sub(
+            r"\s+", "", str(second or "")
+        ).casefold()
+
+
+def parameter_name_mapping(source: str, target: str) -> dict[str, str] | None:
+    """Return source-element-name -> target-element-name correspondence."""
+    source_root = parse_circuit(source)
+    target_root = parse_circuit(target)
+    if canonical_circuit(source) != canonical_circuit(target):
+        return None
+
+    mapping: dict[str, str] = {}
+
+    def walk(source_node: CircuitNode, target_node: CircuitNode) -> None:
+        if source_node.kind == "element" and target_node.kind == "element":
+            mapping[source_node.value or ""] = target_node.value or ""
+            return
+        source_children = sorted(
+            source_node.children,
+            key=lambda child: (repr(canonical_circuit_from_node(child)), child.value or ""),
+        )
+        target_children = sorted(
+            target_node.children,
+            key=lambda child: (repr(canonical_circuit_from_node(child)), child.value or ""),
+        )
+        for source_child, target_child in zip(source_children, target_children):
+            walk(source_child, target_child)
+
+    def canonical_circuit_from_node(node: CircuitNode) -> tuple:
+        if node.kind == "element":
+            return ("element", _element_type(node.value or ""))
+        return (
+            node.kind,
+            tuple(sorted((canonical_circuit_from_node(child) for child in node.children), key=repr)),
+        )
+
+    walk(source_root, target_root)
+    return mapping
+
+
+def map_parameter_name(name: str, element_mapping: dict[str, str]) -> str | None:
+    for source_element, target_element in sorted(element_mapping.items(), key=lambda item: -len(item[0])):
+        if name == source_element:
+            return target_element
+        prefix = source_element + "_"
+        if name.startswith(prefix):
+            return target_element + name[len(source_element):]
+    return None