Metadata-Version: 2.1
Name: pvclipping
Version: 0.1.1
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
)
```
