EPANETH程序员工具箱

EPANETH程序员工具箱原著：LewisA.Rossman（俄亥俄州辛辛那提市美国环境保护局研究和开发办公室国家风险管理研究实验室供水和水资源分部，45268）翻译：李树平（上海市同济大学环境科学与工程学院，200092）2011年9月21日Toolkith.rtfEPANETH程序员工具箱第1页，共73页EPANETH程序员工具箱EPANETH是一个分析配水系统水力和水质特性的程序。EPANETH程序员工具箱是一个函数动态链接库(DLL)，允许开发人员为了特定需求，定制EPANETH计算引擎。函数可以包含在C/C++,DelphiPascal,VisualBasic，或者任何其它语言编写的32位Windows应用程序中，可以在WindowsDLL中调用函数。工具箱DLL文件命名为EPANET2H.DLL，与EPANETH一起发布。工具箱包含了头文件，函数定义文件和.lib文件，以简化将它与C/C++,Delphi和VisualBasic代码衔接的任务。EPANET及其程序员工具箱由美国环境保护署国家风险管理研究实验室供水和水资源分部开发；汉化后命名为EPANETH及其程序员工具箱，该汉化工作由同济大学环境科学与工程学院完成。1．工具箱概览程序员工具箱是EPANETH模拟软件包的扩展。EPANETH执行有压管网水力和水质特性的延时模拟。管网可以包含管道、节点（管道连接节点）、水泵、阀门、贮水池或者水箱。EPANETH跟踪每一管道的流量、每一节点的压力、每一水池的水位，以及多时段模拟过程中整个管网的化学成分浓度。除了化学成分，也可以模拟水龄和源头跟踪。工具箱提供了一系列函数，允许程序员定制应用EPANETH的水力和水质计算引擎。利用工具箱之前，应熟悉EPANETH表示管网的方式，以及执行模拟需要的设计和运行信息。该信息可以从EPANETH的在线帮助文件或者EPANETH用户手册获得。为了分析配水系统的工具箱函数，其典型应用如下：1.使用ENopen函数打开工具箱系统，同时打开EPANETH输入文件。2.使用ENsetxxx系列函数，改变和选择系统特性。3.利用ENsolveH函数执行完整的水力模拟(它自动将结果保存到水力文件)；或者利用ENopen-ENinitH-ENrunH-ENnextH-ENcloseH系列函数，逐步进行水力模拟；利用ENgetxxx系列函数访问计算结果。4.利用ENsolveQ执行完整的水质分析(它自动将水力和水质结果保存到输出文件)；或者使用ENopenQ-ENinitQ-ENrunQ-ENnextQ(或者ENstepQ)-ENcloseQ系列函数，逐步进行水质模拟；利用ENgetxxx系列函数访问结果。5.为了执行额外的分析，返回步骤2，或者利用ENreport函数，将格式化报告写入到报告文件。6.调用ENclose函数，关闭所有文件，并释放系统内存。利用这些函数的特定例子见示例应用主题。Toolkith.rtfEPANETH程序员工具箱第2页，共73页2．数据流程图EPANETH工具箱利用ANSI标准C语言书写，对于输入过程、水力分析、水质分析、稀疏矩阵/线性方程分析和报告生成，具有单独的代码模块。分析管网的数据流程图见左图。本流程图描述的处理步骤总结如下：z输入处理器模块接受被模拟管网的描述，来自外部输入文件(.INP)。文件的内容被分析、解释和保存在共享内存区域。z水力求解器模块执行延时水力模拟。每一时间步长获得的结果可以写入外部非格式化（二进制）水力文件(.HYD)。这些时间步长可以表示系统改变中间点的时间，因为水池充满或者放空，或者水泵启闭，由于水位控制或者时间调度运行。z如果需要水质模拟，水质求解器模块访问来自水力文件的流量数据，计算整个管网在每一水力时间步长中物质的迁移和反应。该过程可以书写前面计算的水力结果，以及每一预先设定报告间隔的水质结果，写入到非格式化（二进制）输出文件(.OUT)。如果没有调用水质分析，那么保存在.HYD文件中的水力结果可以均匀报告间隔，简单写入到二进制输出文件。z如果需要，报告书写器模块从二进制输出文件(.OUT)读回计算的模拟结果，对于每一报告时段，可将选择的数值写入格式化报告文件(.RPT)。运行过程产生的任何错误或者警告信息也将写入该文件。工具箱函数将在程序员控制下执行所有这些步骤，包括阅读或者更改多数系统全局性数据。3．怎样使用工具箱以下主题简要描述怎样利用工具箱完成一些基本任务。工具箱完整应用的代码列表见示例应用主题。3.1打开和关闭工具箱调用其他任何函数之前，工具箱必须打开EPANETH的输入文件o，获取分析管网的描述。(例外是ENepanet函数，它执行了完整的水力/水质模拟，类似于EPANETH命令行执行情况)。一旦完成所有分析，必须关闭它，释放所有分配内存。完成该任务的函数有ENopen和ENclose。使用这些函数的例子如下。char*f1,*f2,*f3;interrcode;errcode=ENopen(f1,f2,f3);if(errcode0){ENclose();return;}/*调用执行期望分析的函数*/ENclose();Toolkith.rtfEPANETH程序员工具箱第3页，共73页3.2检索和设置管网参数工具箱具有各种用于检索和设置参数的函数，定义了被分析管网的设计和运行状况。所有检索函数名称均以ENget开始(例如ENgetnodevalue,ENgetoption等)，而用于设置参数值的函数以ENset开始(例如ENsetnodevalue,ENsetoption等)。其中多数函数使用索引号参考特定管网组件（例如节点、管段或者时间模式）。该数字是所有类似类型组件列表中的位置(例如节点10在管网中是从1开始的第10个节点)，在被处理的输入文件中没有相同的ID标签赋给组件。具有一系列参数确定给定ID标签的组件索引(见ENgetlinkindex,ENgetnodeindex和ENgetpatternindex)。类似的，具有函数检索给定索引号的组件ID标签(参见ENgetlinkid,ENgetnodeid和ENgetpatternid)。函数ENgetcount可用于确定管网中不同组件的数量。以下编码是使用参数索引和设置函数的例子。它将所有直径为250mm的管道改为300mm。inti,Nlinks;floatD;ENgetcount(EN_LINKCOUNT,&Nlinks);for(i=1;i=Nlinks;i++){ENgetlinkvalue(i,EN_DIAMETER,&D);if(D==250)ENsetlinkvalue(i,EN_DIAMETER,300);}3.3执行水力分析利用工具箱执行水力分析具有两种方式：1.使用ENsolveH函数，运行完整的延时分析，不需要访问中间结果；2.使用ENopenH-ENinitH-ENrunH-ENnextH-ENcloseH系列函数，步进形式模拟水力时间步长。方法1对于仅仅希望执行单一的水力分析是有用的，可能将输入提供给水质分析。利用该方法，每一时间步长的水力分析结果总是保存到水力文件。如果需要访问时间步长之间的结果；或者希望有效地执行多次分析，必须使用方法2。为了完成后者，可以仅调用一次ENopenH，开始该过程，然后连续调用ENinitH-ENrunH–EnnextH，执行每一次分析，昀后调用ENcloseH，关闭水力系统。这样的例子见下（调用ENnextH不是需要的，因为在该例中仅仅执行单一时段分析)。inti,Nruns;longt;ENopenH()for(i=1;i=Nruns;i++){/*设置当前执行的参数*/setparams(i);Toolkith.rtfEPANETH程序员工具箱第4页，共73页/*初始化水力特性*/ENinitH(0);/*单一时段运行*/ENrunH(&t);/*检索结果*/getresults(i);}ENcloseH();3.4执行水质分析水质分析之前，必须产生水力结果，来自执行水力分析或者来自以前执行而导入保存的水力文件。与水力分析类似，水质分析也具有两种方式：1.利用ENsolveQ函数，执行完整的延时分析，不需要访问中间结果；2.利用ENopenQENopenHinfo-ENinitQ-ENrunQ-ENnextQENnextHinfo-ENcloseQ函数序列，步进通过每一水力时间步长模拟。(ENnextQ替换为ENstepQ，将步进通过每一水质时间步长。)使用方法2的例子如下。interr;longt,tstep;err=ENsolveH();if(err100)return(err);ENopenQ();ENinitQ(1);do{ENrunQ(&t);ENnextQ(&tstep);}while(tstep0);ENcloseQ();ENreport();3.5检索计算结果ENgetnodevalue和ENgetlinkvalue函数，用于检索水力和水质模拟结果。计算的参数（及其工具箱代码）可以按照以下检索：对于节点:对于管段:EN_DEMAND(需水量)EN_FLOW(流量)EN_HEAD(水力水头)EN_VELOCITY(流速)EN_PRESSURE(压强)EN_HEADLOSS(水头损失)EN_QUALITY(水质)EN_STATUS(管段状态)EN_SOURCEMASS(水质源头质量进流)EN_SETTING(水泵转速或者阀门设置)Toolkith.rtfEPANETH程序员工具箱第5页，共73页以下代码说明怎样在每一时间步长水力分析之后，检索管网每一节点的压力(writetofile是由用户定义的将记录写入文件的函数)：inti,NumNodes;longt,tstep;floatp;charid[16];ENgetcount(EN_NODECOUNT,&NumNodes);ENopenH();ENinitH(0);do{ENrunH(&t);for(i=1;i=NumNodes;i++){ENgetnodevalue(i,EN_PRESSURE,&p);ENgetnodeid(i,id);writetofile(t,id,p);}ENnextH(&tstep);}while(tstep0);ENcloseH();3.6书写报告工具箱具有一些内置功能，用于产生报告到文件的格式化输出结果。更特殊的报告需要通过书写特定编码处理。ENsetreport函数用于定义报告的格式，同时ENreport函数实际上书写报告。或者仅仅在水力或者水质分析之后调用。创建列出所有节点的报告例子，其中压力超过20psi随模拟时段变化，见下：/*计算范围(max-min)*/ENsettimeparam(EN_STATISTIC,EN_RANGE);/*求解水力特性*/ENsolveH();/*从水力文件向输出文件转换结果*/ENsaveH();/*定义报告的内容*/ENresetreport();ENsetreport(FILEmyfile.rpt);ENsetreport(NODESALL);ENsetreport(PRESSUREPRECISION1);ENsetreport(PRESSUREABOVE20);/*将报告写入文件*/ENreport();Toolkith.rtfEPANETH程序员工具箱第6页，共73页4．示例应用例1–为其他应用程序提供内嵌引擎本例说明工具箱为其他应用程序提供管网分析的简单性。应用程序将需要三个步骤：1.将配水系统数据写入到EPANETH格式的输入文件(参见输入文件格式)。2.调用ENepanet函数，提供EPANETH输入文件名，状态和错误信息需要写入的报告文件名，以及将包含分析结果的二进制输出文件名。3.通过访问输出文件，以在应用程序中显示期望的分析结果(参见输出文件格式)。例2–为消防流量研究建立消火栓性能曲线本例说明了工具箱怎样用于