groundmeas 0.1.0__tar.gz

groundmeas-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.3
+Name: groundmeas
+Version: 0.1.0
+Summary: 
+Author: Christian Ehlert
+Author-email: christian.ehlert@mailbox.org
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: matplotlib (>=3.10.1,<4.0.0)
+Requires-Dist: numpy (>=2.2.5,<3.0.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: sqlite-utils (>=3.38,<4.0)
+Requires-Dist: sqlmodel (>=0.0.24,<0.0.25)
+Description-Content-Type: text/markdown
+
+# groundmeas: Grounding System Measurements & Analysis
+
+**groundmeas** is a Python package for collecting, storing, analyzing, and visualizing earthing (grounding) measurement data.
+
+---
+
+## Project Description
+
+groundmeas provides:
+
+* **Database models & CRUD** via SQLModel/SQLAlchemy (`Location`, `Measurement`, `MeasurementItem`).
+* **Export utilities** to JSON, CSV, and XML.
+* **Analytics routines** for impedance-over-frequency, real–imaginary processing, and rho–f model fitting.
+* **Plotting helpers** for impedance vs frequency and model overlays using Matplotlib.
+
+It’s designed to help engineers and researchers work with earthing measurement campaigns, automate data pipelines, and quickly gain insights on soil resistivity and grounding impedance behavior.
+
+---
+
+## Technical Background
+
+In grounding studies, measurements of earth electrode impedance are taken over a range of frequencies, and soil resistivity measurements at various depths are collected.
+
+* **Earthing Impedance** $Z$ vs. **Frequency** (f): typically expressed in Ω.
+* **Soil Resistivity** (ρ) vs. **Depth** (d): used to model frequency‑dependent behavior.
+* **rho–f Model**: fits the relationship
+
+  $$
+  Z(ρ, f) = k_1·ρ + (k_2 + j·k_3)·f + (k_4 + j·k_5)·ρ·f
+  $$
+
+where $k_1…k_5$ are real coefficients determined by least‑squares across multiple measurements.
+
+---
+
+## Installation
+
+Requires Python 3.12+:
+
+```bash
+git clone https://github.com/Ce1ectric/groundmeas.git
+cd groundmeas
+poetry install
+poetry shell
+```
+
+or using pip locally:
+```bash
+git clone https://github.com/Ce1ectric/groundmeas.git
+cd groundmeas
+pip install .
+```
+
+Or install via pip: `pip install groundmeas`.
+
+---
+
+## Usage
+
+### 1. Database Setup
+
+Initialize or connect to a SQLite database (tables will be created automatically):
+
+```python
+from groundmeas.db import connect_db
+connect_db("mydata.db", echo=True)
+```
+
+### 2. Creating Measurements
+
+Insert a measurement (optionally with nested location) and its items:
+
+```python
+from groundmeas.db import create_measurement, create_item
+
+# Create measurement with nested Location
+meas_id = create_measurement({
+    "timestamp": "2025-01-01T12:00:00",
+    "method": "staged_fault_test",
+    "voltage_level_kv": 10.0,
+    "asset_type": "substation",
+    "location": {"name": "Site A", "latitude": 52.0, "longitude": 13.0},
+})
+
+# Add earthing impedance item
+item_id = create_item({
+    "measurement_type": "earthing_impedance",
+    "frequency_hz": 50.0,
+    "value": 12.3
+}, measurement_id=meas_id)
+```
+
+### 3. Exporting Data
+
+Export measurements (and nested items) to various formats:
+
+```python
+from groundmeas.export import (
+    export_measurements_to_json,
+    export_measurements_to_csv,
+    export_measurements_to_xml,
+)
+
+export_measurements_to_json("data.json")
+export_measurements_to_csv("data.csv")
+export_measurements_to_xml("data.xml")
+```
+
+### 4. Analytics
+
+Compute impedance and resistivity mappings, and fit the rho–f model:
+
+```python
+from groundmeas.analytics import (
+    impedance_over_frequency,
+    real_imag_over_frequency,
+    rho_f_model,
+)
+
+# Impedance vs frequency for a single measurement
+imp_map = impedance_over_frequency(1)
+
+# Real & Imag components for multiple measurements
+ri_map = real_imag_over_frequency([1, 2, 3])
+
+# Fit rho–f model across measurements [1,2,3]
+k1, k2, k3, k4, k5 = rho_f_model([1, 2, 3])
+```
+
+### 5. Plotting
+
+Visualize raw and modeled curves:
+
+```python
+from groundmeas.plots import plot_imp_over_f, plot_rho_f_model
+
+# Raw impedance curves
+fig1 = plot_imp_over_f([1, 2, 3])
+fig1.show()
+
+# Normalized at 50 Hz
+fig2 = plot_imp_over_f(1, normalize_freq_hz=50)
+fig2.show()
+
+# Overlay rho–f model
+fig3 = plot_rho_f_model([1,2,3], (k1,k2,k3,k4,k5), rho=[100, 200])
+fig3.show()
+```
+
+## Contributing
+
+Pull requests are welcome!
+For major changes, please open an issue first to discuss.
+Ensure tests pass and add new tests for your changes.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+

groundmeas-0.1.0/README.md

@@ -0,0 +1,160 @@
+# groundmeas: Grounding System Measurements & Analysis
+
+**groundmeas** is a Python package for collecting, storing, analyzing, and visualizing earthing (grounding) measurement data.
+
+---
+
+## Project Description
+
+groundmeas provides:
+
+* **Database models & CRUD** via SQLModel/SQLAlchemy (`Location`, `Measurement`, `MeasurementItem`).
+* **Export utilities** to JSON, CSV, and XML.
+* **Analytics routines** for impedance-over-frequency, real–imaginary processing, and rho–f model fitting.
+* **Plotting helpers** for impedance vs frequency and model overlays using Matplotlib.
+
+It’s designed to help engineers and researchers work with earthing measurement campaigns, automate data pipelines, and quickly gain insights on soil resistivity and grounding impedance behavior.
+
+---
+
+## Technical Background
+
+In grounding studies, measurements of earth electrode impedance are taken over a range of frequencies, and soil resistivity measurements at various depths are collected.
+
+* **Earthing Impedance** $Z$ vs. **Frequency** (f): typically expressed in Ω.
+* **Soil Resistivity** (ρ) vs. **Depth** (d): used to model frequency‑dependent behavior.
+* **rho–f Model**: fits the relationship
+
+  $$
+  Z(ρ, f) = k_1·ρ + (k_2 + j·k_3)·f + (k_4 + j·k_5)·ρ·f
+  $$
+
+where $k_1…k_5$ are real coefficients determined by least‑squares across multiple measurements.
+
+---
+
+## Installation
+
+Requires Python 3.12+:
+
+```bash
+git clone https://github.com/Ce1ectric/groundmeas.git
+cd groundmeas
+poetry install
+poetry shell
+```
+
+or using pip locally:
+```bash
+git clone https://github.com/Ce1ectric/groundmeas.git
+cd groundmeas
+pip install .
+```
+
+Or install via pip: `pip install groundmeas`.
+
+---
+
+## Usage
+
+### 1. Database Setup
+
+Initialize or connect to a SQLite database (tables will be created automatically):
+
+```python
+from groundmeas.db import connect_db
+connect_db("mydata.db", echo=True)
+```
+
+### 2. Creating Measurements
+
+Insert a measurement (optionally with nested location) and its items:
+
+```python
+from groundmeas.db import create_measurement, create_item
+
+# Create measurement with nested Location
+meas_id = create_measurement({
+    "timestamp": "2025-01-01T12:00:00",
+    "method": "staged_fault_test",
+    "voltage_level_kv": 10.0,
+    "asset_type": "substation",
+    "location": {"name": "Site A", "latitude": 52.0, "longitude": 13.0},
+})
+
+# Add earthing impedance item
+item_id = create_item({
+    "measurement_type": "earthing_impedance",
+    "frequency_hz": 50.0,
+    "value": 12.3
+}, measurement_id=meas_id)
+```
+
+### 3. Exporting Data
+
+Export measurements (and nested items) to various formats:
+
+```python
+from groundmeas.export import (
+    export_measurements_to_json,
+    export_measurements_to_csv,
+    export_measurements_to_xml,
+)
+
+export_measurements_to_json("data.json")
+export_measurements_to_csv("data.csv")
+export_measurements_to_xml("data.xml")
+```
+
+### 4. Analytics
+
+Compute impedance and resistivity mappings, and fit the rho–f model:
+
+```python
+from groundmeas.analytics import (
+    impedance_over_frequency,
+    real_imag_over_frequency,
+    rho_f_model,
+)
+
+# Impedance vs frequency for a single measurement
+imp_map = impedance_over_frequency(1)
+
+# Real & Imag components for multiple measurements
+ri_map = real_imag_over_frequency([1, 2, 3])
+
+# Fit rho–f model across measurements [1,2,3]
+k1, k2, k3, k4, k5 = rho_f_model([1, 2, 3])
+```
+
+### 5. Plotting
+
+Visualize raw and modeled curves:
+
+```python
+from groundmeas.plots import plot_imp_over_f, plot_rho_f_model
+
+# Raw impedance curves
+fig1 = plot_imp_over_f([1, 2, 3])
+fig1.show()
+
+# Normalized at 50 Hz
+fig2 = plot_imp_over_f(1, normalize_freq_hz=50)
+fig2.show()
+
+# Overlay rho–f model
+fig3 = plot_rho_f_model([1,2,3], (k1,k2,k3,k4,k5), rho=[100, 200])
+fig3.show()
+```
+
+## Contributing
+
+Pull requests are welcome!
+For major changes, please open an issue first to discuss.
+Ensure tests pass and add new tests for your changes.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

groundmeas-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "groundmeas"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Christian Ehlert",email = "christian.ehlert@mailbox.org"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "sqlmodel (>=0.0.24,<0.0.25)",
+    "sqlite-utils (>=3.38,<4.0)",
+    "pandas (>=2.2.3,<3.0.0)",
+    "numpy (>=2.2.5,<3.0.0)",
+    "matplotlib (>=3.10.1,<4.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "groundmeas", from = "src"}]
+
+
+[tool.poetry.group.dev.dependencies]
+typer = "^0.15.3"
+pytest = "^8.3.5"
+black = "^25.1.0"
+ipykernel = "^6.29.5"
+pytest-cov = "^6.1.1"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

groundmeas-0.1.0/src/groundmeas/__init__.py

@@ -0,0 +1,84 @@
+"""
+groundmeas
+==========
+
+A Python package for managing, storing, analyzing, and plotting earthing measurements.
+
+Features:
+- SQLite + SQLModel (Pydantic) data models for Measurement, MeasurementItem, and Location.
+- CRUD operations with simple `connect_db`, `create_*`, `read_*`, `update_*`, and `delete_*` APIs.
+- Analytics: impedance vs frequency, real/imag mappings, and rho–f modeling.
+- Plotting helpers wrapping matplotlib for quick visualizations.
+
+Example:
+    import groundmeas as gm
+
+    gm.connect_db("ground.db")
+    mid = gm.create_measurement({...})
+    items, ids = gm.read_items_by(measurement_id=mid)
+    fig = gm.plot_imp_over_f(mid)
+    fig.show()
+"""
+
+import logging
+
+# Configure a library logger with a NullHandler by default
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+__version__ = "0.1.0"
+__author__ = "Ce1ectric"
+__license__ = "MIT"
+
+try:
+    from .db import (
+        connect_db,
+        create_measurement,
+        create_item,
+        read_measurements,
+        read_measurements_by,
+        read_items_by,
+        update_measurement,
+        update_item,
+        delete_measurement,
+        delete_item,
+    )
+    from .models import Location, Measurement, MeasurementItem
+    from .analytics import (
+        impedance_over_frequency,
+        real_imag_over_frequency,
+        rho_f_model,
+    )
+    from .plots import plot_imp_over_f, plot_rho_f_model
+except ImportError as e:
+    logger.error("Failed to import groundmeas submodule: %s", e)
+    raise
+
+__all__ = [
+    # database
+    "connect_db",
+    "create_measurement",
+    "create_item",
+    "read_measurements",
+    "read_measurements_by",
+    "read_items_by",
+    "update_measurement",
+    "update_item",
+    "delete_measurement",
+    "delete_item",
+    # data models
+    "Location",
+    "Measurement",
+    "MeasurementItem",
+    # analytics
+    "impedance_over_frequency",
+    "real_imag_over_frequency",
+    "rho_f_model",
+    # plotting
+    "plot_imp_over_f",
+    "plot_rho_f_model",
+    # metadata
+    "__version__",
+    "__author__",
+    "__license__",
+]

groundmeas-0.1.0/src/groundmeas/analytics.py

@@ -0,0 +1,248 @@
+"""
+groundmeas.analytics
+====================
+
+Analytics functions for the groundmeas package. Provides routines to fetch and
+process impedance and resistivity data for earthing measurements, and to fit
+and evaluate rho–f models.
+"""
+
+import itertools
+import logging
+import warnings
+from typing import Dict, Union, List, Tuple
+
+import numpy as np
+
+from .db import read_items_by
+
+# configure module‐level logger
+logger = logging.getLogger(__name__)
+
+
+def impedance_over_frequency(
+    measurement_ids: Union[int, List[int]],
+) -> Union[Dict[float, float], Dict[int, Dict[float, float]]]:
+    """
+    Build a mapping from frequency (Hz) to impedance magnitude (Ω).
+
+    Args:
+        measurement_ids: A single measurement ID or a list of IDs for which
+            to retrieve earthing_impedance data.
+
+    Returns:
+        If a single ID is provided, returns:
+            { frequency_hz: impedance_value, ... }
+        If multiple IDs, returns:
+            { measurement_id: { frequency_hz: impedance_value, ... }, ... }
+
+    Raises:
+        RuntimeError: if retrieving items from the database fails.
+    """
+    single = isinstance(measurement_ids, int)
+    ids: List[int] = [measurement_ids] if single else list(measurement_ids)
+    all_results: Dict[int, Dict[float, float]] = {}
+
+    for mid in ids:
+        try:
+            items, _ = read_items_by(
+                measurement_id=mid, measurement_type="earthing_impedance"
+            )
+        except Exception as e:
+            logger.error("Error reading impedance items for measurement %s: %s", mid, e)
+            raise RuntimeError(
+                f"Failed to load impedance data for measurement {mid}"
+            ) from e
+
+        if not items:
+            warnings.warn(
+                f"No earthing_impedance measurements found for measurement_id={mid}",
+                UserWarning,
+            )
+            all_results[mid] = {}
+            continue
+
+        freq_imp_map: Dict[float, float] = {}
+        for item in items:
+            freq = item.get("frequency_hz")
+            value = item.get("value")
+            if freq is None:
+                warnings.warn(
+                    f"MeasurementItem id={item.get('id')} missing frequency_hz; skipping",
+                    UserWarning,
+                )
+                continue
+            try:
+                freq_imp_map[float(freq)] = float(value)
+            except Exception:
+                warnings.warn(
+                    f"Could not convert item {item.get('id')} to floats; skipping",
+                    UserWarning,
+                )
+
+        all_results[mid] = freq_imp_map
+
+    return all_results[ids[0]] if single else all_results
+
+
+def real_imag_over_frequency(
+    measurement_ids: Union[int, List[int]],
+) -> Union[Dict[float, Dict[str, float]], Dict[int, Dict[float, Dict[str, float]]]]:
+    """
+    Build a mapping from frequency to real & imaginary components.
+
+    Args:
+        measurement_ids: A single measurement ID or list of IDs.
+
+    Returns:
+        If single ID:
+            { frequency_hz: {"real": real_part, "imag": imag_part}, ... }
+        If multiple IDs:
+            { measurement_id: { frequency_hz: {...}, ... }, ... }
+
+    Raises:
+        RuntimeError: if retrieving items from the database fails.
+    """
+    single = isinstance(measurement_ids, int)
+    ids: List[int] = [measurement_ids] if single else list(measurement_ids)
+    all_results: Dict[int, Dict[float, Dict[str, float]]] = {}
+
+    for mid in ids:
+        try:
+            items, _ = read_items_by(
+                measurement_id=mid, measurement_type="earthing_impedance"
+            )
+        except Exception as e:
+            logger.error("Error reading impedance items for measurement %s: %s", mid, e)
+            raise RuntimeError(
+                f"Failed to load impedance data for measurement {mid}"
+            ) from e
+
+        if not items:
+            warnings.warn(
+                f"No earthing_impedance measurements found for measurement_id={mid}",
+                UserWarning,
+            )
+            all_results[mid] = {}
+            continue
+
+        freq_map: Dict[float, Dict[str, float]] = {}
+        for item in items:
+            freq = item.get("frequency_hz")
+            r = item.get("value_real")
+            i = item.get("value_imag")
+            if freq is None:
+                warnings.warn(
+                    f"MeasurementItem id={item.get('id')} missing frequency_hz; skipping",
+                    UserWarning,
+                )
+                continue
+            try:
+                freq_map[float(freq)] = {
+                    "real": float(r) if r is not None else None,
+                    "imag": float(i) if i is not None else None,
+                }
+            except Exception:
+                warnings.warn(
+                    f"Could not convert real/imag for item {item.get('id')}; skipping",
+                    UserWarning,
+                )
+
+        all_results[mid] = freq_map
+
+    return all_results[ids[0]] if single else all_results
+
+
+def rho_f_model(
+    measurement_ids: List[int],
+) -> Tuple[float, float, float, float, float]:
+    """
+    Fit the rho–f model:
+        Z(ρ,f) = k1*ρ + (k2 + j*k3)*f + (k4 + j*k5)*ρ*f
+
+    Enforces that at f=0 the impedance is purely real (→ k1*ρ).
+
+    Args:
+        measurement_ids: List of measurement IDs to include in the fit.
+
+    Returns:
+        A tuple (k1, k2, k3, k4, k5) of real coefficients.
+
+    Raises:
+        ValueError: if no soil_resistivity or no impedance overlap.
+        RuntimeError: if the least-squares solve fails.
+    """
+    # 1) Gather real/imag data
+    rimap = real_imag_over_frequency(measurement_ids)
+
+    # 2) Gather available depths → ρ
+    rho_map: Dict[int, Dict[float, float]] = {}
+    depth_choices: List[List[float]] = []
+
+    for mid in measurement_ids:
+        try:
+            items, _ = read_items_by(
+                measurement_id=mid, measurement_type="soil_resistivity"
+            )
+        except Exception as e:
+            logger.error("Error reading soil_resistivity for %s: %s", mid, e)
+            raise RuntimeError(
+                f"Failed to load soil_resistivity for measurement {mid}"
+            ) from e
+
+        dt = {
+            float(it["measurement_distance_m"]): float(it["value"])
+            for it in items
+            if it.get("measurement_distance_m") is not None
+            and it.get("value") is not None
+        }
+        if not dt:
+            raise ValueError(f"No soil_resistivity data for measurement {mid}")
+        rho_map[mid] = dt
+        depth_choices.append(list(dt.keys()))
+
+    # 3) Select depths minimizing spread
+    best_combo, best_spread = None, float("inf")
+    for combo in itertools.product(*depth_choices):
+        spread = max(combo) - min(combo)
+        if spread < best_spread:
+            best_spread, best_combo = spread, combo
+
+    selected_rhos = {
+        mid: rho_map[mid][depth] for mid, depth in zip(measurement_ids, best_combo)
+    }
+
+    # 4) Assemble design matrices & response vectors
+    A_R, yR, A_X, yX = [], [], [], []
+
+    for mid in measurement_ids:
+        rho = selected_rhos[mid]
+        for f, comp in rimap.get(mid, {}).items():
+            R = comp.get("real")
+            X = comp.get("imag")
+            if R is None or X is None:
+                continue
+            A_R.append([rho, f, rho * f])
+            yR.append(R)
+            A_X.append([f, rho * f])
+            yX.append(X)
+
+    if not A_R:
+        raise ValueError("No overlapping impedance data available for fitting")
+
+    try:
+        A_R = np.vstack(A_R)
+        A_X = np.vstack(A_X)
+        R_vec = np.asarray(yR)
+        X_vec = np.asarray(yX)
+
+        kR, *_ = np.linalg.lstsq(A_R, R_vec, rcond=None)  # [k1, k2, k4]
+        kX, *_ = np.linalg.lstsq(A_X, X_vec, rcond=None)  # [k3, k5]
+    except Exception as e:
+        logger.error("Least-squares solve failed: %s", e)
+        raise RuntimeError("Failed to solve rho-f least-squares problem") from e
+
+    k1, k2, k4 = kR
+    k3, k5 = kX
+
+    return float(k1), float(k2), float(k3), float(k4), float(k5)