147 lines
5.8 KiB
Markdown
147 lines
5.8 KiB
Markdown
---
|
||
name: service-area-analysis
|
||
description: 基于实时水力模拟数据的水源追溯供水服务范围分区。通过管段流量确定水流方向，从水库BFS追溯服务节点，环网/零流量节点用无向拓扑补充分配，输出分区可视化。
|
||
---
|
||
|
||
# 供水服务范围分区工作流
|
||
|
||
## 概述
|
||
|
||
本工作流基于指定时刻的水力模拟结果，通过**流向追溯法**将全部管网节点分配到各水库的服务范围。核心思路：利用管段流量符号判定水流方向，构建有向图从水库逐级追溯，对环网和零流量节点用无向拓扑修正。
|
||
|
||
适用场景：供水服务范围评估、DMA分区规划、多水源供水格局分析、管网调度策略评估。
|
||
|
||
## 分区方法
|
||
|
||
### 第一步：水流方向判定
|
||
|
||
对于每条管段，根据实时流量 `flow` 判定水流方向：
|
||
|
||
| flow 值 | 水流方向 | 说明 |
|
||
|---------|----------|------|
|
||
| `flow > 1e-6` | node1 → node2 | 正向流量 |
|
||
| `flow < -1e-6` | node2 → node1 | 反向流量 |
|
||
| `|flow| ≤ 1e-6` | 无方向 | 零流量，不参与有向追溯 |
|
||
|
||
### 第二步：多源有向BFS
|
||
|
||
1. 以每个水库为根节点，沿水流方向执行 BFS
|
||
2. 遍历到的节点归属该水库的服务范围
|
||
3. **先到先得**：一个节点首次被访问到的水库即为归属
|
||
4. 预期覆盖 **85–90%** 节点
|
||
|
||
### 第三步：无向拓扑修正
|
||
|
||
有向BFS不可达节点（通常 10–15%）通过无向图邻近性补充分配：
|
||
|
||
| 不可达原因 | 说明 |
|
||
|------------|------|
|
||
| 环状管网 | 水流回路中下游节点反向连回上游，有向遍历被阻断 |
|
||
| 零流量管段 | `flow≈0` 的管段无方向，其下游节点断开 |
|
||
| 多水源交汇 | 交汇区流向往复，非树状拓扑 |
|
||
|
||
### 输出统计
|
||
|
||
每个分区输出：
|
||
- `node_count`：分区内节点总数
|
||
- `total_demand`：总需水量（负数=净供水区）
|
||
- `avg_pressure`/`min_pressure`/`max_pressure`：压力统计
|
||
|
||
## 数据依赖
|
||
|
||
| 步骤 | 命令 | 数据量 | 超时 | 关键字段 |
|
||
|------|------|--------|------|----------|
|
||
| ① 管道拓扑 | `network get-all-pipes-properties` | ~11.7MB / 91K条 | 120s | id, node1, node2 |
|
||
| ② 水库属性 | `network get-all-reservoirs-properties` | ~小 | 120s | id, links |
|
||
| ③ 管段流量 | `data timeseries realtime links --start-time T --end-time T+15min` | ~39MB / 182K条 | 300s | id, flow, time |
|
||
| ④ 节点数据 | `data timeseries realtime nodes --start-time T --end-time T+15min` | ~28MB / 176K条 | 300s | id, pressure, actual_demand, time |
|
||
|
||
> **时间窗口**：模拟步长 15 分钟，查询 T~T+15min 覆盖 1–2 个时间步。脚本按 `--target-time` 精确筛选。
|
||
|
||
> **文件输入**：四份调用都使用 `store_result=true`，包括结果较小的水库属性。脚本读取每次返回的 `data_file.file_path`；文件都属于当前对话，禁止使用 `/tmp` 或全局 `tool-output/`。
|
||
|
||
## 执行步骤
|
||
|
||
### 第 1 步：并行拉取数据
|
||
|
||
4 个 `tjwater_cli` 调用（互不依赖），可一次发起：
|
||
|
||
```bash
|
||
# ① 管道静态拓扑
|
||
tjwater_cli(command="network get-all-pipes-properties", timeout=120, store_result=true)
|
||
|
||
# ② 水库属性
|
||
tjwater_cli(command="network get-all-reservoirs-properties", timeout=120, store_result=true)
|
||
|
||
# ③ 目标时刻管段流量
|
||
tjwater_cli(command="data timeseries realtime links --start-time 2026-04-01T08:00:00+08:00 --end-time 2026-04-01T08:15:00+08:00", timeout=300, store_result=true)
|
||
|
||
# ④ 目标时刻节点数据
|
||
tjwater_cli(command="data timeseries realtime nodes --start-time 2026-04-01T08:00:00+08:00 --end-time 2026-04-01T08:15:00+08:00", timeout=300, store_result=true)
|
||
```
|
||
|
||
### 第 2 步：运行分区脚本
|
||
|
||
```bash
|
||
python3 <skill_dir>/scripts/service_area_partition.py \
|
||
--pipe-props <data_file.file_path-①> \
|
||
--reservoirs <data_file.file_path-②> \
|
||
--links <data_file.file_path-③> \
|
||
--nodes <data_file.file_path-④> \
|
||
--target-time '2026-04-01T08:00:00+08:00' \
|
||
--output ./service_area_partition_wrapper.json
|
||
```
|
||
|
||
**脚本参数**：
|
||
|
||
| 参数 | 说明 | 必填 |
|
||
|------|------|------|
|
||
| `--pipe-props` | 管道属性 JSON 文件路径 | 是 |
|
||
| `--reservoirs` | 水库属性 JSON 文件路径 | 是 |
|
||
| `--links` | 实时管段数据 JSON 文件路径 | 是 |
|
||
| `--nodes` | 实时节点数据 JSON 文件路径 | 是 |
|
||
| `--target-time` | 目标时刻 ISO8601 | 是 |
|
||
| `--output` | 分区结果输出路径 | 是 |
|
||
|
||
**输出**：
|
||
- **stderr**：处理日志 + 各分区统计表格
|
||
- **stdout**：紧凑 JSON 摘要（total_nodes, reservoirs, areas）
|
||
- **文件**：符合 `store_render_ref` 要求的 `{metadata, location, data}` 包装 JSON，其中 `data` 包含 `node_area_map`、`area_ids`、`area_colors` 和分析元数据
|
||
|
||
### 第 3 步：前端可视化
|
||
|
||
```bash
|
||
# 持久化分区结果
|
||
store_render_ref(file_path=<output-file>)
|
||
|
||
# 渲染节点分区
|
||
render_junctions(render_ref="res-xxxxxxxx-xxxx-xx")
|
||
|
||
# 定位水库
|
||
locate_features(ids=[...], feature_type="reservoir")
|
||
|
||
# 展示统计图表
|
||
show_chart(title="各水源分区节点数/压力对比", chart_type="bar", ...)
|
||
```
|
||
|
||
## 参考数据规模
|
||
|
||
基于 91,000 管段 / 88,000 节点规模的管网模型：
|
||
|
||
| 指标 | 实测值 |
|
||
|------|--------|
|
||
| 管道拓扑数据量 | 91,052 条 |
|
||
| 水库数量 | 13 个 |
|
||
| 总节点数 | 87,907 |
|
||
| 有向BFS分配节点 | ~76,900 (87.5%) |
|
||
| 无向修正节点 | ~11,000 (12.5%) |
|
||
| 分区覆盖率 | 100% |
|
||
| 脚本处理时间 | ~15-30 秒 |
|
||
| 峰值内存 | ~400-500MB |
|
||
|
||
## 已知限制
|
||
|
||
- **水库顺序敏感**：多源 BFS 中先遍历到的水库优先分配，不同水库启动顺序可能影响边界区域分配结果
|
||
- **单时刻快照**：分区仅反映目标时刻的水力工况，不同时段的泵站启停、阀门切换可能导致分区边界变化
|
||
- **零流量阈值**：`1e-6` 阈值过滤极低流量管段，若管网有长期小流量管段可能漏判方向
|