pvclipping 0.1.0__tar.gz

pvclipping-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.1
+Name: pvclipping
+Version: 0.1.0
+Summary: Clipping detection helpers for the solar plant rule engine
+Requires-Python: >=3.7
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Description-Content-Type: text/markdown
+
+# pvclipping
+
+Inverter clipping detection helper for the solar plant rule engine.
+
+## Install
+
+```bash
+pip install pvclipping
+```
+
+## Usage with RuleParser
+
+```python
+from pvclipping import get_custom_funcs
+
+parser = RuleParser(
+    plant_id=...,
+    meter_dim=meter_dim,
+    postgres_engine=engine,
+    influx_engine=clickhouse,
+    reading_dim=reading_dim,
+    custom_func=get_custom_funcs(),
+)
+```
+
+## Rule JSON
+
+```json
+{
+  "steps": [
+    {
+      "name": "irr_filter#GLOBAL",
+      "type": "filter",
+      "value": "$$Tilt_Irr#GLOBAL$$ > 400"
+    },
+    {
+      "name": "Power_Active#INV",
+      "value": "$$Power_Active#INV$$.round(0)",
+      "filter": "irr_filter#GLOBAL",
+      "all_ticks": true
+    },
+    {
+      "name": "AC_Capacity#INV",
+      "value": "$$AC_Capacity#INV$$",
+      "all_ticks": true,
+      "fill_missing": true
+    },
+    {
+      "name": "Clipping_status#INV",
+      "value": "detect_clipping(df['Power_Active#INV'], df['AC_Capacity#INV'])",
+      "eval_meter": true
+    },
+    {
+      "name": "Clipping_status_F#INV",
+      "type": "filter",
+      "value": "$$Clipping_status#INV$$ > 0"
+    }
+  ],
+  "output": ["Clipping_status_F#INV"]
+}
+```
+
+## Function signature
+
+```python
+detect_clipping(
+    power,               # pd.Series — active power, pre-filtered to evaluation window
+    capacity,            # pd.Series — AC capacity, forward-filled
+    window=5,            # rolling window size in ticks
+    std_threshold=1.0,   # max rolling std (kW) to qualify as a flat plateau
+    min_power_fraction=0.2,  # min power fraction of capacity to exclude standby
+)
+```

pvclipping-0.1.0/README.md

@@ -0,0 +1,73 @@
+# pvclipping
+
+Inverter clipping detection helper for the solar plant rule engine.
+
+## Install
+
+```bash
+pip install pvclipping
+```
+
+## Usage with RuleParser
+
+```python
+from pvclipping import get_custom_funcs
+
+parser = RuleParser(
+    plant_id=...,
+    meter_dim=meter_dim,
+    postgres_engine=engine,
+    influx_engine=clickhouse,
+    reading_dim=reading_dim,
+    custom_func=get_custom_funcs(),
+)
+```
+
+## Rule JSON
+
+```json
+{
+  "steps": [
+    {
+      "name": "irr_filter#GLOBAL",
+      "type": "filter",
+      "value": "$$Tilt_Irr#GLOBAL$$ > 400"
+    },
+    {
+      "name": "Power_Active#INV",
+      "value": "$$Power_Active#INV$$.round(0)",
+      "filter": "irr_filter#GLOBAL",
+      "all_ticks": true
+    },
+    {
+      "name": "AC_Capacity#INV",
+      "value": "$$AC_Capacity#INV$$",
+      "all_ticks": true,
+      "fill_missing": true
+    },
+    {
+      "name": "Clipping_status#INV",
+      "value": "detect_clipping(df['Power_Active#INV'], df['AC_Capacity#INV'])",
+      "eval_meter": true
+    },
+    {
+      "name": "Clipping_status_F#INV",
+      "type": "filter",
+      "value": "$$Clipping_status#INV$$ > 0"
+    }
+  ],
+  "output": ["Clipping_status_F#INV"]
+}
+```
+
+## Function signature
+
+```python
+detect_clipping(
+    power,               # pd.Series — active power, pre-filtered to evaluation window
+    capacity,            # pd.Series — AC capacity, forward-filled
+    window=5,            # rolling window size in ticks
+    std_threshold=1.0,   # max rolling std (kW) to qualify as a flat plateau
+    min_power_fraction=0.2,  # min power fraction of capacity to exclude standby
+)
+```

pvclipping-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pvclipping"
+version = "0.1.0"
+description = "Clipping detection helpers for the solar plant rule engine"
+readme = "README.md"
+requires-python = ">=3.7"
+dependencies = [
+    "numpy>=1.20",
+    "pandas>=1.3",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pvclipping"]

pvclipping-0.1.0/src/pvclipping/__init__.py

@@ -0,0 +1,16 @@
+from .clipping import detect_clipping
+
+__all__ = ["detect_clipping", "get_custom_funcs"]
+
+
+def get_custom_funcs() -> dict:
+    """Return all pvclipping helpers ready for RuleParser's custom_func param.
+
+    Usage::
+
+        from pvclipping import get_custom_funcs
+        parser = RuleParser(..., custom_func=get_custom_funcs())
+    """
+    return {
+        "detect_clipping": detect_clipping,
+    }

pvclipping-0.1.0/src/pvclipping/clipping.py

@@ -0,0 +1,35 @@
+import numpy as np
+import pandas as pd
+
+
+def detect_clipping(
+    power: pd.Series,
+    capacity: pd.Series,
+    window: int = 5,
+    std_threshold: float = 1.0,
+    min_power_fraction: float = 0.2,
+) -> pd.Series:
+    """Detect inverter power clipping ticks via rolling-std plateau detection.
+
+    Intended for use inside a rule JSON step with eval_meter=true so that
+    the function is applied independently per inverter.
+
+    Args:
+        power: Active power series, pre-filtered to the evaluation window
+               (e.g. irradiance > 400 W/m²). NaN on excluded ticks.
+        capacity: AC capacity series, forward-filled so every tick has a value.
+        window: Rolling window size in ticks used to compute std (default 5).
+        std_threshold: Max rolling std (kW) to qualify as a flat plateau (default 1.0).
+        min_power_fraction: Min power as a fraction of capacity to exclude
+                            standby/low-output ticks (default 0.2 → 20%).
+
+    Returns:
+        Series with the active power value on clipping ticks, NaN otherwise.
+        Index is preserved from ``power``.
+    """
+    min_threshold = capacity * min_power_fraction
+    rolling_std = (
+        power.rolling(window=window, min_periods=window).std().fillna(99)
+    )
+    is_plateau = (rolling_std < std_threshold) & (power > min_threshold)
+    return pd.Series(np.where(is_plateau, power, np.nan), index=power.index)