Update README.md
This commit is contained in:
336
README.md
336
README.md
@@ -1,2 +1,334 @@
|
||||
# cyberbee
|
||||
Software per la realizzazione della Blockchain e AI
|
||||
# ☀️ cyberbee PV Simulator
|
||||
|
||||
A modular, realistic photovoltaic plant simulator written in Python.
|
||||
|
||||
cyberbee PV Simulator generates synthetic time-series data for an entire PV plant hierarchy — from individual panels up to the plant level — with physically grounded models, configurable fault injection, and multi-format export.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
**Physical modelling**
|
||||
- Solar position computed via `pvlib` (elevation, azimuth, zenith, angle of incidence)
|
||||
- Clear-sky irradiance with seasonal and daily variation (GHI, DNI, DHI, POA)
|
||||
- Module temperature model (simplified NOCT approach)
|
||||
- Temperature coefficient applied to power output
|
||||
- Annual degradation of panels
|
||||
- Sensor noise (Gaussian)
|
||||
|
||||
**Fault simulation**
|
||||
- Panel failure, soiling, and partial shading
|
||||
- Combiner box offline
|
||||
- Inverter shutdown
|
||||
- Configurable daily failure probabilities per component level
|
||||
- Fault severity and reduction factors
|
||||
|
||||
**Weather**
|
||||
- Configurable cloud factor with random variability
|
||||
- Rain events with daily probability
|
||||
- Ambient temperature (annual mean + daily swing)
|
||||
|
||||
**Hierarchical aggregation**
|
||||
|
||||
```
|
||||
PV Plant
|
||||
├── Inverter 1
|
||||
│ ├── Combiner Box 1
|
||||
│ │ ├── String 1 → Panel 1 … Panel 20
|
||||
│ │ └── String 2 → Panel 1 … Panel 20
|
||||
│ └── Combiner Box 2
|
||||
│ └── ...
|
||||
└── Inverter 2
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Output & export**
|
||||
- CSV, Parquet, JSON, SQLite
|
||||
- Per-component time series (panel, combiner, inverter, plant, weather, faults)
|
||||
- KPI and statistics: energy yield, performance ratio, availability, specific yield, clipping losses, daily/monthly aggregations, fault summaries
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
pv_simulator/
|
||||
│
|
||||
├── config/
|
||||
│ └── plant.json # Plant configuration
|
||||
│
|
||||
├── pvsim/
|
||||
│ ├── __init__.py
|
||||
│ ├── panel.py # PVPanel model
|
||||
│ ├── combiner.py # CombinerBox model
|
||||
│ ├── inverter.py # Inverter model
|
||||
│ ├── plant.py # PVPlant (top-level object)
|
||||
│ ├── sun.py # Solar position model (pvlib)
|
||||
│ ├── weather.py # Meteorological model
|
||||
│ ├── faults.py # Fault manager and fault types
|
||||
│ ├── simulator.py # Simulation engine (PVSimulator)
|
||||
│ ├── exporter.py # CSV / Parquet / JSON export
|
||||
│ ├── statistics.py # KPI and statistics
|
||||
│ └── utils.py # Shared utilities
|
||||
│
|
||||
├── output/ # Generated data (auto-created)
|
||||
│
|
||||
├── run.py # Entry point
|
||||
├── requirements.txt
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-username/pv-simulator.git
|
||||
cd pv-simulator
|
||||
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Linux / macOS
|
||||
# .venv\Scripts\activate # Windows
|
||||
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**Requirements**
|
||||
|
||||
| Library | Purpose |
|
||||
|---|---|
|
||||
| `numpy` | Numerical computations |
|
||||
| `pandas` | Time-series management, CSV/Parquet export |
|
||||
| `matplotlib` | Production charts |
|
||||
| `scipy` | Statistical distributions and realistic noise |
|
||||
| `pvlib` | Solar position, irradiance models, PV physics |
|
||||
| `networkx` | Plant hierarchy representation |
|
||||
| `pyyaml` | YAML configuration support |
|
||||
| `tqdm` | Progress bar for long simulations |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
The entire plant is described in `config/plant.json`. No code changes are needed to resize or reconfigure the plant.
|
||||
|
||||
```json
|
||||
{
|
||||
"plant": {
|
||||
"name": "ZAK_PV_Simulator",
|
||||
"location": {
|
||||
"latitude": 45.4642,
|
||||
"longitude": 9.1900,
|
||||
"timezone": "Europe/Rome",
|
||||
"altitude": 120
|
||||
},
|
||||
"simulation": {
|
||||
"time_resolution_minutes": 5,
|
||||
"start_date": "2026-01-01 00:00:00",
|
||||
"end_date": "2026-12-31 23:55:00"
|
||||
}
|
||||
},
|
||||
"layout": {
|
||||
"inverters": [
|
||||
{
|
||||
"id": "INV_001",
|
||||
"nominal_power_kW": 100,
|
||||
"combiners": [
|
||||
{
|
||||
"id": "CB_001",
|
||||
"strings": 4,
|
||||
"panels_per_string": 20,
|
||||
"orientation": { "tilt_deg": 30, "azimuth_deg": 180 }
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The default configuration generates:
|
||||
|
||||
| Component | Count |
|
||||
|---|---|
|
||||
| Inverters | 2 |
|
||||
| Combiner boxes | 3 |
|
||||
| Panels | 240 |
|
||||
| Nominal DC power | 108 kWp |
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Run a full simulation
|
||||
|
||||
```python
|
||||
from datetime import datetime
|
||||
from pvsim.simulator import PVSimulator, SimulationConfig
|
||||
from pvsim.exporter import SimulationExporter
|
||||
from pvsim.statistics import SimulationStatistics
|
||||
|
||||
config = SimulationConfig(
|
||||
start=datetime(2026, 6, 21),
|
||||
end=datetime(2026, 6, 22),
|
||||
timestep_minutes=5,
|
||||
generate_random_faults=True,
|
||||
)
|
||||
|
||||
result = simulator.run(config)
|
||||
```
|
||||
|
||||
### Compute KPIs
|
||||
|
||||
```python
|
||||
stats = SimulationStatistics(result)
|
||||
kpi = stats.plant_kpi()
|
||||
|
||||
print(f"Energy produced : {kpi.energy_kWh:.1f} kWh")
|
||||
print(f"Peak power : {kpi.peak_power_W:.0f} W")
|
||||
print(f"Performance ratio: {kpi.performance_ratio:.2%}")
|
||||
print(f"Availability : {kpi.availability:.2%}")
|
||||
```
|
||||
|
||||
### Export data
|
||||
|
||||
```python
|
||||
exporter = SimulationExporter(output_dir="output")
|
||||
exporter.export_all(result, csv=True, parquet=True, json=True, statistics=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
output/
|
||||
│
|
||||
├── simulation.json # Simulation summary
|
||||
├── plant_kpi.json # Plant-level KPIs
|
||||
│
|
||||
├── panel_kpi.csv
|
||||
├── combiner_kpi.csv
|
||||
├── inverter_kpi.csv
|
||||
├── daily_statistics.csv
|
||||
├── monthly_statistics.csv
|
||||
├── fault_summary.csv
|
||||
│
|
||||
├── csv/
|
||||
│ ├── weather.csv
|
||||
│ ├── panel.csv
|
||||
│ ├── combiner.csv
|
||||
│ ├── inverter.csv
|
||||
│ ├── plant.csv
|
||||
│ └── faults.csv
|
||||
│
|
||||
└── parquet/
|
||||
├── weather.parquet
|
||||
├── panel.parquet
|
||||
├── combiner.parquet
|
||||
├── inverter.parquet
|
||||
├── plant.parquet
|
||||
└── faults.parquet
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
Each simulation timestep produces records at every level of the hierarchy.
|
||||
|
||||
**Panel**
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `timestamp` | Measurement instant |
|
||||
| `irradiance_Wm2` | Incident irradiance |
|
||||
| `module_temperature_C` | Module temperature |
|
||||
| `voltage_V` | Panel voltage |
|
||||
| `current_A` | Panel current |
|
||||
| `power_W` | Instantaneous power |
|
||||
| `energy_Wh` | Energy in timestep |
|
||||
| `soiling_factor` | Soiling loss factor |
|
||||
| `degradation_factor` | Cumulative degradation |
|
||||
| `enabled` | Panel operational status |
|
||||
|
||||
**Combiner Box**
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `dc_power_W` | Aggregated DC power |
|
||||
| `dc_voltage_V` | Bus voltage |
|
||||
| `dc_current_A` | Total current |
|
||||
| `active_panel_count` | Active panels |
|
||||
| `availability` | Fraction of active panels |
|
||||
| `status` | `normal` / `idle` / `fault` |
|
||||
|
||||
**Inverter**
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `dc_power_W` | DC input power |
|
||||
| `ac_power_W` | AC output power |
|
||||
| `efficiency` | Conversion efficiency |
|
||||
| `clipping_loss_W` | Clipping losses |
|
||||
| `temperature_C` | Internal temperature |
|
||||
| `status` | `normal` / `idle` / `fault` |
|
||||
|
||||
**Plant**
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `ac_power_W` | Total AC power |
|
||||
| `energy_Wh` | Energy in timestep |
|
||||
| `performance_ratio` | PR (AC / nominal) |
|
||||
| `availability` | Active panel fraction |
|
||||
| `fault_active` | Any active fault |
|
||||
|
||||
---
|
||||
|
||||
## Simulation Pipeline
|
||||
|
||||
```
|
||||
config/plant.json
|
||||
│
|
||||
▼
|
||||
PVPlant (built from config)
|
||||
│
|
||||
▼
|
||||
PVSimulator.run()
|
||||
│
|
||||
▼
|
||||
SimulationResult
|
||||
│
|
||||
├──────────────────┐
|
||||
▼ ▼
|
||||
statistics.py exporter.py
|
||||
│ │
|
||||
▼ ├── CSV
|
||||
KPI ├── Parquet
|
||||
├── JSON
|
||||
└── SQLite (optional)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Planned Improvements
|
||||
|
||||
- Single-diode model via `pvlib` for accurate I-V curves
|
||||
- Partial shading with bypass diode simulation
|
||||
- String-level mismatch modelling
|
||||
- Hot-spot simulation
|
||||
- Sensor drift and intermittent faults
|
||||
- Streaming / chunked export for multi-year simulations at 5-minute resolution
|
||||
- Diagnostic alarms per component
|
||||
- Interactive dashboard (Plotly / Streamlit)
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License — see `LICENSE` for details.
|
||||
|
||||
---
|
||||
|
||||
> Built as part of the ZAK project — a Linux-based measurement and monitoring platform for industrial and renewable energy systems.
|
||||
|
||||
Reference in New Issue
Block a user