[EPANET][翻译]使用EPANET开发包（1）：开发库使用流程与导入文件格式介绍

EPANET 开发包使用概述

这份《程序员开发参考手册》是EPANET延期水力模拟包(这里指EPANET的DLL)的一个附加产品，旨在为使用EPANET的开发人员提供帮助。EPANET能够为加压的管网提供延期水力和水质模拟，这些管网由管段，节点，泵站，阀门储水池或水库组成，EPANET能在多周期的延期模拟中，计算管段的流量，节点的压力，每个水池的高度，流经各个管段的化学物质的浓度等，同时，对于指定的化学物质，EPANET还能模拟水管内的水龄。

这份开发包提供了一系列的函数，这些函数允许程序根据实际的应用需要去自定义使用EPANET的水力和水质计算引擎。在使用EPANET的开发包之前，我们建议您先熟悉EPANET软件的一些常见操作方法，比如如何利用EPANET软件进行供配水管网的设计，如何进行水力和水质模拟，具体的操作方法可以参见EPANET的一些在线帮助文档或者EPANET的用户指南(注：用户指南可以参见前面译文)

对于如何开始使用EPANET的开发包，下面提供一种比较常见的使用方法：

1. 使用ENopen()函数去打开一个符合EPANET格式的导入文件；

2. 使用ENsetxxx 系列函数去改变选择的系统特性；

3. 使用ENsolveH 函数去运行一个完整的水力模拟（计算结果会自动保存到一个水力文件中）或使用ENopenH - ENinitH - ENrunH - ENnextH - ENcloseH系列函数去计算水力模拟，模拟后的结果可以通过ENgetxxx系列函数进行获取；

4. 略

5. 返回步骤2进行其他的附加分析或者利用ENreport 函数导出分析结果

6. 调用Enclose函数去关闭所有文件流，释放内存。

附录：

1. 导入文件(Input File)

导入文件是一个标准的供EPANET计算引擎分析的导入数据文件，这个文件既能用基于开发库进行创建的具体应用程序创建，也可以用应用程序本身去创建，创建之后可以将该文件供ENopen函数使用，但是要注意在如果要使用开发库中其他函数，必须要先正确执行了ENopen函数，同时，在程序执行Enclose函数前，导入文件内的数据信息在程序范围内都是可以访问的。

导入文件是一个可用记事本打开的文件文件，其中文本文件中包含的项有：

主要项	子项	说明
管网主要构件	标题(Title)	用于简要描述要进行分析的管网，用标志[TITLE]进行标识
节点(Junctions)	通过[JUNCTIONS]标识要进行说明的节点集合，主要描述的属性有 ;ID, 高程(Elev), 需求(Demand), 模式( Pattern) 四个属性，其中每行开头通过“;”来进行标志。
水库(Reservoirs)	标识：[JUNCTIONS] 格式： ;ID, 水头(Head), 模式( Head Pattern ID) 说明： 1. 此处的水头为高程和压力水头之和； 2. 使用模式可以使得水库在不同的时间模拟不同的水头 3. 在一个给定管网中至少要存在一个水库或者水池
水库(Tanks)	格式： ID 底部高程（Bottom elevation） 初始水位（Initial water level） 最小水位（Minimum water level） 最大水位（Maximum water level,） 直径（Nominal diameter） 最小体积（Minimum volume） 体积曲线ID（Volume curve ID） 说明： 1. 水表高程等于水底高程与水深之和； 2. 非圆柱形水池的体积可以通过[Curves]节点中的体积曲线进行说明； 3. 如果体积曲线不为空，则直径不能为任意的非零数据； 4. 如果提供了体积曲线或者为圆柱形水池，则最小体积可以为空
管段(Pipes)	标识：[PIPES] 格式： ID 起点节点 终点节点 长度 直径 粗糙系数（Roughness coefficient） 局部损失系数(Minor loss coefficient) 状态(Status): 有OPEN,CLOSED,CV三种状态； 说明： 1. 粗糙系数：如果采用Hazen-Williams 和Chezy-Manning公式，则该值无单位，如果为Darcy-Weisbach公式，则单位为毫米，具体用什么计算公式可以用[OPTIONS] 配置节进行配置 2. 如果设置状态为CV，则说明管段中包含一个检查阀将水流只限定为一个方向流动 3. 如果局部水头损失为0且管段状态为打开状态，则这两项在导入文件中可以忽略不计。
水泵(Pumps)	标识：[PUMPS] 格式： ID, 起点节点 终点节点 关键字/值 说明： 1. 关键字包含：能量(Power),水头(Head),速度(Speed),模式(Pattern) 2. 每个水泵的能量或水头必须要被指定，其他的关键字为可选
阀门(Valves)	标识：[VALVES] 格式： ID 起点节点 终点节点 口径 阀门类型 阀门设置 局部水头损失 说明： 1. 阀门类型包括如下： PRV(减压阀) PSV(稳压阀) PBV(pressure breaker valve) FCV(流量控制阀) TCV(节流阀) GPV (general purpose valve) 2. 关闭阀门，则被认为是阀门为一个CV，并构成了管段一部分
发射体？？(Emitters)	标识：[EMITTERS] 格式： ID 流量系数 说明： 1. 发射体用来描述管段泄露或者洒水时的流量； 2. 流过发射物体的流量等于流量系数值与节点水压之和 3. 能量可以通过[OPTIONS]去设置，默认为0.5 4. 通常在程序报表中的需求项中的值为正常需求与节点需求与通过发射体的节点需求之和； 5. 该项为可选项
系统操作	曲线(Curves)	目的：定义曲线点的X,Y坐标 格式： ID,X,Y 说明： 1. 曲线能被使用在如下几种情况 水泵的流量与水头曲线 水泵的功率与流量曲线 水池的体积与深度曲线 GPV的水头损失与流量曲线 2. 构成曲线点的X坐标必须有低到高自增排列 3. 如果使用的windows版本的EPANET导入文件，那么会包含关于一个曲线类型和描述性的注释，曲线类型包括泵站，功率，体积与水头损失
模式(Patterns)	目的：定义时间曲线 格式： ID,一个或多个乘子 说明： 1. 乘子定义了每个时间段某个基本量的一些变化情况； 2. 所有的时间模式共享由[Time]配置节配置的时间间隔； 3. 每个模式在不同的时间段能拥有不同的值 4. 如果模拟计算的时间超过了时间模式设置的峰值，则自动会返回第一个时间段进行计算 5. 每个模式通过多行来表示多个乘子
能量(Energy)	目的：定义用于计算水泵能量于费用的一些参数值 格式： 全局(GLOBAL),包括PRICE/PATTERN/EFFIC 水泵（Pump）,包括PRICE/PATTERN/EFFIC 需求(Demand) 费用(Charge) 说明： 1. 第一个格式是用来设置一些全局性的关于能量价格，价格模式，和所有泵站功率的默认值； 2. 第二个是用来设置某些指定泵站的值(这些值会取代全局默认值) 3. 参数的单位： PRICE = kw-hour PATTERN = 不同时间段随时间改变的能量价格的曲线ID值 EFFIC = DEMAND CHARGE = 4. 默认的全局参数中，泵站的效率为57%,能量价格为0； 5. 此项中所有选项为可选
状态(Status)	目的：定义指定管段在模拟时的初始状态； 格式： ID,状态值 说明： 1. 如果所有管段不在本项中出现，则该管段默认为OPEN状态或这ACTIVE状态； 2. 状态值可以设置为OPEN也可以设置为CLOSE 3. 管段的初始状态也可以设置在[PIPES]配置节中； 4. CV的状态不能进行事先设置； 5. 使用[CONTROLS]或[RULES]去改变在将来要出现的状态值 6. 在一个CLOSED或者OPEN状态的控制阀CV转换为ACTIVE状态，则必须要CONTROLS或者RULES配置节中要对其压力或者流量进行预设。
控制(Controls)	目的：通过一些条件来实现管段的控制 格式： LINK linkID status IF NODE nodeID ABOVE/BELOW value LINK linkID status AT TIME time LINK linkID status AT CLOCKTIME clocktime AM/PM 说明： 略
规则(Rules)	略
需求(Demands)	目的：定义节点上的多重供水需求量 格式： ID,BASE DEMAND,PatternID,CATEGORY 说明： 1. 只有当在[Junctions]中节点的需求需要改变时才会使用此配置节； 2. 此处的数据会取代在[Junctions]中设置的值 3. 节点的需求归类(Category)的数目是不受限制的 4. 如果没有需求模式，则节点的需求模式会自动加载默认值，或者如果没有默认需求模式的话则为模式1，如果默认值或者模式1都不存在，则需求量会被定义为一常量。
水质	水质(Quality)	略
反应(Reactions)	略
源(Sources)	略
混合(Mixing)	略
选项和报表	选项(Options)	目的：定义模拟分析中的各种选项 格式： 单位(UNITS) 水头损失(Head LOSS) 水质（QUALITY） 粘度（VISCOSITY） 扩散系数（diffusivity） 地球重力（GRAVITY） 迭代次数（TRIALS） 精度（ACCURACY） 不平衡(UNBALANCED) 模式（PATTERN） 需求乘子（DEMAND MULTIPLIER） 发射物（EMITTER EXPONENT） 容限（TOLERANCE） 地图（MAP） 说明：略
时间(Times)	目的：定义在模拟计算过程用到的时间参数 格式： 持续时间（DURATION） 水力计算时间周期（HYDRAULIC TIMESTEP） 规则周期（RULE TIMESTEP） PATTERN TIMESTEP PATTERN START REPORT TIMESTEP REPORT START START CLOCKTIME STATISTIC
报表(Report)	目的：描述计算后的输出格式 格式： 页面大小（PAGESIZE） 文件名（FILE） 状态（STATUS） 概要（SUMMARY） 消息 (MESSAGES) 能量（ENERGY） 节点（NODES） 管段（LINKS） 变量（VARIABLE）

2. 一个导入的样例（来源于EPANET示例）

[TITLE]

[JUNCTIONS]

;ID Elev Demand Pattern

2 0 0 ;

3 0 0 ;

4 0 0 ;

5 0 0 ;

6 0 0 ;

[RESERVOIRS]

;ID Head Pattern

1 0 ;

[TANKS]

;ID Elevation InitLevel MinLevel MaxLevel Diameter MinVol VolCurve

[PIPES]

;ID Node1 Node2 Length Diameter Roughness MinorLoss Status

1 1 2 1000 12 100 0 Open ;

2 2 3 1000 12 100 0 Open ;

3 3 4 1000 12 100 0 Open ;

4 2 5 1000 12 100 0.2 Open ;plr

[PUMPS]

;ID Node1 Node2 Parameters

5 5 6 POWER ;

[VALVES]

;ID Node1 Node2 Diameter Type Setting MinorLoss

[TAGS]

LINK 4 gg

[DEMANDS]

;Junction Demand Pattern Category

[STATUS]

;ID Status/Setting

[PATTERNS]

;ID Multipliers

[CURVES]

;ID X-Value Y-Value

[CONTROLS]

[RULES]

[ENERGY]

Global Efficiency 75

Global Price 0

Demand Charge 0

[EMITTERS]

;Junction Coefficient

[QUALITY]

;Node InitQual

[SOURCES]

;Node Type Quality Pattern

[REACTIONS]

;Type Pipe/Tank Coefficient

Bulk 4 22

Wall 4 33

[REACTIONS]

Order Bulk 1

Order Tank 1

Order Wall 1

Global Bulk 0

Global Wall 0

Limiting Potential 0

Roughness Correlation 0

[MIXING]

;Tank Model

[TIMES]

Duration 0

Hydraulic Timestep 1:00

Quality Timestep 0:05

Pattern Timestep 1:00

Pattern Start 0:00

Report Timestep 1:00

Report Start 0:00

Start ClockTime 12 am

Statistic None

[REPORT]

Status No

Summary No

Page 0

[OPTIONS]

Units GPM

Headloss H-W

Specific Gravity 1

Viscosity 1

Trials 40

Accuracy 0.001

Unbalanced Continue 10

Pattern 1

Demand Multiplier 1.0

Emitter Exponent 0.5

Quality None mg/L

Diffusivity 1

Tolerance 0.01

[COORDINATES]

;Node X-Coord Y-Coord

2 624.19 8647.59

3 2704.81 8725.62

4 3576.07 7698.31

5 1053.32 7165.15

6 2769.83 6514.95

1 -338.10 9076.72

[VERTICES]

;Link X-Coord Y-Coord

[LABELS]

;X-Coord Y-Coord Label & Anchor Node

[BACKDROP]

DIMENSIONS 0.00 0.00 10000.00 10000.00

UNITS None

FILE

OFFSET 0.00 0.00

[END]