# helios

**Repository Path**: Mr_Chippy/helios

## Basic Information

- **Project Name**: helios
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Helios

> 舟山海岛光伏海雾—盐雾衰减模型

## 1. 项目简介

**Helios** 用于构建一个面向**舟山海岛光伏场景**的环境衰减仿真模型。

模型的目标不是一开始就做一个“大而全”的完整物理模型，而是先建立一条可运行、可解释、可逐步增强的计算链路：

```text
气象时间序列输入
    ↓
基准光伏出力
    ↓
海雾衰减修正
    ↓
盐雾污损修正
    ↓
修正后光伏出力
    ↓
指标计算与图表输出
```

当前版本重点服务于：

- 海岛光伏出力趋势分析
- 海雾/盐雾影响的情景模拟
- 修正前后净负荷差异分析
- 后续更精细模型的工程骨架搭建

## 2. 当前模型状态

当前仓库已经具备完整的 Python 工程骨架，并且主流程可以端到端运行。

目前各模块状态如下：

- `src/fog_loss.py`：**已实现真实海雾衰减算法**
  - 基于能见度 `visibility` 和相对湿度 `relative_humidity`
  - 当前采用单一标量 `K_fog` 修正总辐照度
- `src/salt_soiling.py`：**已实现盐雾沉积+结晶模块**
  - 向量化纯整段计算 `M_salt`、`salt_state`、`K_soiling`
  - 包含风速/湿度驱动沉积、按日降雨清洗、湿/干滞后析出
- `src/pvlib_engine.py`：**已接入 pvlib PVWatts DC**
  - 包含太阳位置、GHI 分解、POA、组件温度、DC 出力

因此，当前版本已经不再是“完全恒等于基准”的模型：

- 当 demo 数据中出现低能见度、高湿海雾窗口时，`K_fog < 1`
- 修正后出力 `P_corrected` 会低于基准出力 `P_base`

## 3. 模型核心思路

当前版本采用如下总公式：

```text
P_corrected = P_base × K_fog × K_soiling
```

其中：

- `P_base`：基准光伏出力
- `K_fog`：海雾衰减系数
- `K_soiling`：盐雾污损系数

### 海雾模块

当前海雾修正采用经验型公式：

```text
K_fog = exp(-alpha_fog × F_fog)
F_fog = max(0, vis_ref / vis_eff - 1) × H
H     = max(0, (RH - rh_threshold) / (100 - rh_threshold))
```

说明：

- 能见度越低，海雾衰减越强
- 相对湿度越高，海雾判据越容易触发
- 当输入 `GHI` 已经是实测值时，模型会旁路 fog 修正，避免重复衰减

### 盐雾模块

当前已实现一阶盐雾污损：

```text
M_salt    ← deposition + daily carry + day-end rain wash-off
K_soiling = exp(-β_state × M_salt)
```

说明：

- 沉积通量由 `wind_speed` 与 `relative_humidity` 驱动
- 降雨按日累计后在日末触发分档清洗
- 结晶状态用 deliquescence / efflorescence 阈值滞后建模
- 实现保持与 fog / pvlib 一致的向量化纯模块 `(df, config) -> df`
- **参数校准状态**：`k0` 等盐雾参数**未基于实测出力校准**。`k0` 已据舟山 2025-06 真实气象数据从演示值 0.005 下调至 0.001（原值在该月产生 ~96% 峰值透光损失、~34% 月度能量损失的物理荒谬结果），下调后该月落 ~10% 月度污损损失，处于文献合理带但仍属量级抢救、非真校准。待接入实测 PV 出力后再做正式校准。

## 4. 如何运行模型

### 4.1 安装依赖

建议使用 Python 3.10 及以上版本。

在项目根目录执行：

```bash
pip install -e ".[dev]"
```

### 4.2 运行主程序

```bash
python main.py
```

运行 `Helios` 后程序会：

1. 生成 demo 气象数据
2. 计算基准光伏出力
3. 计算海雾衰减系数
4. 计算盐雾污损系数（沉积+结晶）
5. 输出修正后光伏出力
6. 计算指标并生成图表

### 4.3 输出位置

运行结果会写入：

`data/output/`

当前输出包括：

- `corrected_output.csv`：逐时结果表
- `indicators.json`：指标结果
- `pv_power_comparison.png`：基准/修正出力对比图
- `k_fog_curve.png`：海雾衰减曲线
- `k_soiling_curve.png`：盐雾污损曲线
- `net_load_comparison.png`：净负荷对比图（若输入含负荷）

## 5. 输入数据说明

当前统一使用 `pandas.DataFrame` 作为数据契约。

强制输入要求：

- 时间必须是**规整逐时（1h）**序列
- 推荐使用 `DatetimeIndex`，索引名为 `time`
- 若不是 `DatetimeIndex`，CSV 必须提供可解析的 `time` 列
- 时间建议使用 **tz-naive 的舟山当地时间**，避免带时区时间在逐时校验时引入歧义
- 脏数据会被 `src/data_loader.py::validate_input` **硬拒**，不会自动排序、去重、补点、插值或裁剪

六个必需字段包括：

- `ghi`（单位：`W/m²`）
- `temp_air`（单位：`°C`）
- `visibility`（单位：`m`）
- `rainfall`（单位：`mm`）
- `wind_speed`（单位：`m/s`）
- `relative_humidity`（单位：`%`）

必需字段的物理范围如下，超出即拒绝：

- `ghi >= 0`
- `temp_air ∈ [-40, 60]`
- `visibility > 0`
- `rainfall >= 0`
- `wind_speed >= 0`
- `relative_humidity ∈ [0, 100]`

输出字段中，`P_base` 单位为 `kW`。

可选字段：

- `load_raw`
- `sea_salt_concentration`
- `wash_record`

若可选列存在，也必须为有限值；其中 `load_raw` 还必须满足 `>= 0`。

CSV 输入会通过 `src/data_loader.py` 自动解析 `time` 列并转换为时间索引，但在进入模型前会执行完整输入审校。

### 5.1 宇培电站 baseline 报告

宇培专属 baseline 入口不会修改 `main.py` demo 主线，需单独运行：

```bash
python -m src.yupei_baseline
```

默认输入文件（由 `src/site_presets.py` 中的 `YUPEI_2025_06_PRESET` 集中维护）：

- 气象：`data/input/zhoushan_2025-06.csv`
- 实测出力：`data/input/宇培光伏电站2025年6月.csv`

默认输出目录：

- `data/output/yupei_2025-06_baseline/`

输出至少包含：

- `baseline_comparison.csv`
- `baseline_metrics.json`
- `measured_vs_baseline.png`

其中 `baseline_comparison.csv` 至少包含：`time`、`measured_pv_kw`、`modeled_base_kw`、`scaled_modeled_base_kw`、`residual_kw`、`residual_ratio`。

宇培 baseline preset 固定为：`capacity_kw=12000`、`ghi_source='measured'`、`tilt_deg=20`、`azimuth_deg=90`、`k0=0`。其中 `tilt=20 / azimuth=90` 是**基于数据反推得到的 baseline 假设**，用于构造更贴近实测的比较基线，不代表 surveyed truth；当前这条 baseline **不解释盐污损**，而是通过 preset 级别 `k0=0` 显式关闭盐解释。

## 6. 主要目录结构

```text
.
├── config.py
├── data/
│   ├── input/
│   └── output/
├── docs/
│   └── model_upgrade_roadmap.md
├── main.py
├── pyproject.toml
├── README.md
├── requirements.txt
├── tests/
│   ├── test_fog_loss.py
│   └── test_smoke.py
└── src/
    ├── __init__.py
    ├── correction.py
    ├── data_loader.py
    ├── environment_adapter.py
    ├── fields.py
    ├── fog_loss.py
    ├── indicators.py
    ├── output_writer.py
    ├── pipeline.py
    ├── plotting.py
    ├── pvlib_engine.py
    └── salt_soiling.py
```

## 7. 当前边界与限制

当前版本是一个**第一阶段可运行模型**，不是最终的高精度实证模型。

目前明确不包含：

- 完整 `pvlib.ModelChain`
- DNI / DHI / POA 分层海雾修正
- 盐雾 refractive 二阶增强
- 参数校准
- Mie 散射
- 含盐雾滴折射率增强

因此当前模型更适合：

- 架构验证
- 模块替换开发
- 规律分析
- 敏感性分析

而不是直接作为最终工程预测模型。

## 8. 后续升级路线

所有“当前先简化、后续再增强”的内容，统一维护在：

`docs/model_upgrade_roadmap.md`

后续推荐升级顺序：

1. salt refractive 二阶增强（待定义 `C_salt` 真浓度语义）
2. `pvlib_engine.py`：接入真实 `pvlib` 主链路
3. fog 模块升级到 `K_fog_dni` / `K_fog_dhi`
4. 引入更细的 POA 层修正与参数校准

## 9. 质量保障

项目当前启用了较严格的 Python 工程约束：

- `mypy --strict`
- `ruff check`
- `ruff format --check`
- `pytest`

你可以手动运行：

```bash
mypy --strict src config.py main.py tests
ruff check src config.py main.py tests
ruff format --check src config.py main.py tests
pytest -q
```

如果你后续继续扩展模块，建议始终保持这些检查通过。