groundmeas 0.1.0__py3-none-any.whl

groundmeas/models.py

@@ -0,0 +1,214 @@
+"""
+groundmeas.models
+=================
+
+Pydantic/SQLModel data models for earthing measurements.
+
+Defines:
+- Location: a measurement site with geographic coordinates.
+- Measurement: a test event with metadata and related items.
+- MeasurementItem: a measured data point (e.g. impedance, resistivity) with
+  magnitude and optional complex components.
+
+Includes an SQLAlchemy event listener to ensure consistency between
+value, value_real/value_imag, and value_angle_deg fields.
+"""
+
+import logging
+import math
+import numpy as np
+from datetime import datetime, timezone
+from typing import Optional, List, Literal
+
+from sqlalchemy import Column, String, event
+from sqlmodel import SQLModel, Field, Relationship
+
+from pydantic import field_validator
+
+logger = logging.getLogger(__name__)
+
+
+MeasurementType = Literal[
+    "prospective_touch_voltage",
+    "touch_voltage",
+    "earth_potential_rise",
+    "step_voltage",
+    "transferred_potential",
+    "earth_fault_current",
+    "earthing_current",
+    "earthing_resistance",
+    "earthing_impedance",
+    "soil_resistivity",
+]
+
+MethodType = Literal[
+    "staged_fault_test",
+    "injection_remote_substation",
+    "injection_earth_electrode",
+]
+
+AssetType = Literal[
+    "substation",
+    "overhead_line_tower",
+    "cable",
+    "cable_cabinet",
+    "house",
+    "pole_mounted_transformer",
+    "mv_lv_earthing_system",
+]
+
+
+class Location(SQLModel, table=True):
+    """
+    A geographic location where measurements are taken.
+
+    Attributes:
+        id: Auto-generated primary key.
+        name: Human-readable site name.
+        latitude: Decimal degrees latitude.
+        longitude: Decimal degrees longitude.
+        altitude: Altitude in meters (optional).
+        measurements: Back-reference to Measurement records for this site.
+    """
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(..., description="Site name")
+    latitude: Optional[float] = Field(None, description="Latitude (°)")
+    longitude: Optional[float] = Field(None, description="Longitude (°)")
+    altitude: Optional[float] = Field(None, description="Altitude (m)")
+    measurements: List["Measurement"] = Relationship(back_populates="location")
+
+
+class Measurement(SQLModel, table=True):
+    """
+    A single earthing measurement event.
+
+    Attributes:
+        id: Auto-generated primary key.
+        timestamp: UTC datetime when the measurement occurred.
+        location_id: FK to Location.
+        location: Relationship to the Location object.
+        method: Measurement method used.
+        voltage_level_kv: System voltage in kilovolts (optional).
+        asset_type: Type of asset under test.
+        fault_resistance_ohm: Fault resistance in ohms (optional).
+        operator: Name or identifier of the operator (optional).
+        description: Free-text notes (optional).
+        items: List of MeasurementItem objects associated to this event.
+    """
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp of measurement",
+    )
+    location_id: Optional[int] = Field(default=None, foreign_key="location.id")
+    location: Optional[Location] = Relationship(back_populates="measurements")
+    method: MethodType = Field(
+        sa_column=Column(String, nullable=False), description="Measurement method"
+    )
+    voltage_level_kv: Optional[float] = Field(None, description="Voltage level in kV")
+    asset_type: AssetType = Field(
+        sa_column=Column(String, nullable=False), description="Type of asset"
+    )
+    fault_resistance_ohm: Optional[float] = Field(
+        None, description="Fault resistance (Ω)"
+    )
+    operator: Optional[str] = Field(None, description="Operator name")
+    description: Optional[str] = Field(None, description="Notes")
+    items: List["MeasurementItem"] = Relationship(back_populates="measurement")
+
+
+class MeasurementItem(SQLModel, table=True):
+    """
+    A single data point within a Measurement.
+
+    Supports both real/imaginary and magnitude/angle representations.
+
+    Attributes:
+        id: Auto-generated primary key.
+        measurement_type: Type of this data point.
+        value: Scalar magnitude (Ω or other unit).
+        value_real: Real component, if complex (Ω).
+        value_imag: Imaginary component, if complex (Ω).
+        value_angle_deg: Phase angle in degrees (optional).
+        unit: Unit string, e.g. "Ω", "m".
+        description: Free-text notes (optional).
+        frequency_hz: Frequency in Hz (optional).
+        additional_resistance_ohm: Extra series resistance (optional).
+        input_impedance_ohm: Instrument input impedance (optional).
+        measurement_distance_m: Depth or distance for resistivity (optional).
+        measurement_id: FK to parent Measurement.
+        measurement: Relationship to the Measurement object.
+    """
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    measurement_type: MeasurementType = Field(
+        sa_column=Column(String, nullable=False), description="Data point type"
+    )
+    value: Optional[float] = Field(None, description="Magnitude or scalar value")
+    value_real: Optional[float] = Field(None, description="Real part of complex value")
+    value_imag: Optional[float] = Field(
+        None, description="Imaginary part of complex value"
+    )
+    value_angle_deg: Optional[float] = Field(None, description="Phase angle in degrees")
+    unit: str = Field(..., description="Unit of the measurement")
+    description: Optional[str] = Field(None, description="Item notes")
+    frequency_hz: Optional[float] = Field(None, description="Frequency (Hz)")
+    additional_resistance_ohm: Optional[float] = Field(
+        None, description="Additional series resistance (Ω)"
+    )
+    input_impedance_ohm: Optional[float] = Field(
+        None, description="Instrument input impedance (Ω)"
+    )
+    measurement_distance_m: Optional[float] = Field(
+        None, description="Depth/distance for soil resistivity (m)"
+    )
+    measurement_id: Optional[int] = Field(default=None, foreign_key="measurement.id")
+    measurement: Optional[Measurement] = Relationship(back_populates="items")
+
+
+@event.listens_for(MeasurementItem, "before_insert", propagate=True)
+@event.listens_for(MeasurementItem, "before_update", propagate=True)
+def _compute_magnitude(mapper, connection, target: MeasurementItem):
+    """
+    SQLAlchemy event listener to enforce and propagate between
+    complex and polar representations:
+
+      - If `value` is None but real/imag are set, computes magnitude
+        and phase angle (degrees).
+      - If `value` is set and `value_angle_deg` is set, computes
+        `value_real` and `value_imag`.
+      - If neither representation is present, raises ValueError.
+
+    Raises:
+        ValueError: if no valid value is provided.
+    """
+    try:
+        # Case A: only rectangular given → compute scalar and angle
+        if target.value is None:
+            if target.value_real is not None or target.value_imag is not None:
+                r = target.value_real or 0.0
+                i = target.value_imag or 0.0
+                target.value = math.hypot(r, i)
+                target.value_angle_deg = float(np.degrees(np.arctan2(i, r)))
+            else:
+                logger.error(
+                    "MeasurementItem %s lacks both magnitude and real/imag components",
+                    getattr(target, "id", "<new>"),
+                )
+                raise ValueError(
+                    "Either `value` or at least one of (`value_real`, `value_imag`) must be provided"
+                )
+        # Case B: polar given → compute rectangular components
+        elif target.value_angle_deg is not None:
+            angle_rad = math.radians(target.value_angle_deg)
+            target.value_real = float(target.value * math.cos(angle_rad))
+            target.value_imag = float(target.value * math.sin(angle_rad))
+    except Exception:
+        # Ensure that any unexpected error in conversion is logged
+        logger.exception(
+            "Failed to compute magnitude/angle for MeasurementItem %s",
+            getattr(target, "id", "<new>"),
+        )
+        raise

groundmeas/plots.py

@@ -0,0 +1,137 @@
+# src/groundmeas/plots.py
+
+import matplotlib.pyplot as plt
+from typing import Tuple, Union, List, Dict, Any, Optional
+import warnings
+from .analytics import impedance_over_frequency, real_imag_over_frequency
+
+
+def plot_imp_over_f(
+    measurement_ids: Union[int, List[int]], normalize_freq_hz: Optional[float] = None
+) -> plt.Figure:
+    """
+    Plot earthing impedance versus frequency for one or multiple measurements on a single figure.
+
+    Args:
+        measurement_ids: single ID or list of Measurement IDs.
+        normalize_freq_hz: if provided, normalize each impedance curve by its impedance at this frequency.
+
+    Returns:
+        A matplotlib Figure containing all curves.
+
+    Raises:
+        ValueError: if normalize_freq_hz is specified but a measurement lacks that frequency,
+                    or if no data is available for a single measurement.
+    """
+    # Normalize input to list
+    single = isinstance(measurement_ids, int)
+    ids: List[int] = [measurement_ids] if single else list(measurement_ids)
+
+    # Create a single figure and axis
+    fig, ax = plt.subplots()
+
+    plotted = False
+    for mid in ids:
+        # Retrieve impedance-frequency map
+        freq_imp = impedance_over_frequency(mid)
+        if not freq_imp:
+            warnings.warn(
+                f"No earthing_impedance data for measurement_id={mid}; skipping curve",
+                UserWarning,
+            )
+            continue
+
+        # Sort frequencies
+        freqs = sorted(freq_imp.keys())
+        imps = [freq_imp[f] for f in freqs]
+
+        # Normalize if requested
+        if normalize_freq_hz is not None:
+            baseline = freq_imp.get(normalize_freq_hz)
+            if baseline is None:
+                raise ValueError(
+                    f"Measurement {mid} has no impedance at {normalize_freq_hz} Hz for normalization"
+                )
+            imps = [val / baseline for val in imps]
+
+        # Plot the curve
+        ax.plot(freqs, imps, marker="o", linestyle="-", label=f"ID {mid}")
+        plotted = True
+
+    if not plotted:
+        if single:
+            raise ValueError(
+                f"No earthing_impedance data available for measurement_id={measurement_ids}"
+            )
+        else:
+            raise ValueError(
+                "No earthing_impedance data available for the provided measurement IDs."
+            )
+
+    # Labels and title
+    ax.set_xlabel("Frequency (Hz)")
+    ylabel = (
+        "Normalized Impedance" if normalize_freq_hz is not None else "Impedance (Ω)"
+    )
+    ax.set_ylabel(ylabel)
+    title = "Impedance vs Frequency"
+    if normalize_freq_hz is not None:
+        title += f" (Normalized @ {normalize_freq_hz} Hz)"
+    ax.set_title(title)
+
+    # Grid and scientific tick formatting
+    ax.grid(True, which="both", linestyle="--", linewidth=0.5)
+    ax.ticklabel_format(axis="y", style="sci", scilimits=(0, 0))
+
+    # Legend
+    ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def plot_rho_f_model(
+    measurement_ids: List[int],
+    rho_f: Tuple[float, float, float, float, float],
+    rho: Union[float, List[float]] = 100,
+) -> plt.Figure:
+    """
+    Plot measured impedance and rho-f model on the same axes.
+
+    Args:
+        measurement_ids: list of Measurement IDs.
+        rho_f: tuple (k1, k2, k3, k4, k5).
+        rho: single float or list of rho values. For list, multiple model curves are plotted.
+
+    Returns:
+        A matplotlib Figure with measured and modeled impedance magnitude vs frequency.
+    """
+    # Plot measured curves
+    fig = plot_imp_over_f(measurement_ids)
+    ax = fig.axes[0]
+
+    # Gather real/imag data
+    rimap = real_imag_over_frequency(measurement_ids)
+    # Union of frequencies
+    all_freqs = set()
+    for freq_map in rimap.values():
+        all_freqs.update(freq_map.keys())
+    freqs = sorted(all_freqs)
+
+    # Unpack model coefficients
+    k1, k2, k3, k4, k5 = rho_f
+
+    # Normalize rho parameter to list
+    rhos: List[float] = [rho] if isinstance(rho, (int, float)) else list(rho)
+
+    # Plot model curves for each rho
+    for rho_val in rhos:
+        model_mag = [
+            abs((k1) * rho_val + (k2 + 1j * k3) * f + (k4 + 1j * k5) * rho_val * f)
+            for f in freqs
+        ]
+        ax.plot(
+            freqs, model_mag, linestyle="--", linewidth=2, label=f"Model (ρ={rho_val})"
+        )
+
+    ax.legend()
+    return fig

groundmeas-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+groundmeas/__init__.py,sha256=g2lTdyjsvJaU1MtEYa_ELSmDCkwQbu5tRWlgenb9zIg,2087
+groundmeas/analytics.py,sha256=7mwL0f4M6VXnDI59UX7h-4dApjwvqIm9h9dUcZeRRHU,8102
+groundmeas/db.py,sha256=P5a7xtJDbnvSaBoqd1x6DpN1m1-L_GPTtiwVj0zff7g,12800
+groundmeas/export.py,sha256=cBY7zJaXXHCdRqJXwSCuhnX6ywMoo7Jbp0hhPxnEUjM,5687
+groundmeas/models.py,sha256=Zu8IKNOPp0Y_GOGD_IA8I4MJulveVMQjo29WlTyWCnU,8248
+groundmeas/plots.py,sha256=3Gq45jZh2XvHZ7Fpm9tyDJdiaJwNH_83rp6_kxPaIr4,4363
+groundmeas-0.1.0.dist-info/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundmeas-0.1.0.dist-info/METADATA,sha256=vB3Jdffn3fiwHkKkM3U8k7sLF_xXxOskAIu_DDBdoEc,4545
+groundmeas-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+groundmeas-0.1.0.dist-info/RECORD,,

groundmeas-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any