Home

MSE Supervisor User`s Manual

1. Get input state variables double hi GetVarIn func segmentiHead lpISMap double h2 GetVarIn func segment4Head lpISMap Provide supervsory function based on input state variable Set the output variables if not SetVarOut func wmi ctrl spvr0ut1 lpOCMap gt return 1 if not SetVarOut func ctrl 102 spvr0ut2 lpOCMap gt gt return 1 return 0 In the above XML section and supervisory function the output of varOut with name ctr1_102 is used to dynamically assign a controller to the wa termover with ID wmID 1 The value of the variable spvrOut1 in the function MySupervise will be converted to an integer the controller which has an ID matching the integer value of spvrOut1 will be set as the ac tive controller for the watermover with ID wmID 1 The second output spvrOut2 will be used to set the triglow parameter of the controller with the controller ID ctrl1ID 102 8 10 User Defined Supervisor Example In this example the shared object named UserSprv so module UserSprv is loaded from the current directory to call the supervisor functions func SetWM1Controller and func SetWM1CtrlTriggers The function SetWMiController is used to select one of two controllers 35 so cid 101 or cid 101 for the watermover with wmID 1 The function SetWM1CtrlTriggers will set the lower trigger threshold value triglow for the controllers These functions
2. controller R controller id gt 0 Table 2 2 1 Multiple Controller Selection XML 2 3 Controller Override It may be desirable for a supervisor to directly control the flow modulation of a watermover To accommodate this the supervisors are able to directly override the control computations of a watermover controller This is done with the use of the func attribute of a supervisor a lt varOut gt environ ment set to either func control0ut or func override If the lt varOut gt specifies func control0ut then the controller output will be replaced by the value of the supervisor lt var0ut gt As an example lt varOut ctrlID 103 func control0ut name Override gt lt varOut gt The above lt var0ut gt will force the controller to apply the output value of the supervisor variable named Override to the watermover flow modula tion Setting func control0ut implicitly sets the override on for future timesteps The supervisor will continue to override the controller output value until this feature is turned off In order to turn off or turn on the controller override the supervisor implements a lt var0ut gt which sets the attribute func override and assigns it 0 for off 1 for on An example of this usage is shown below lt varOut ctrlID 103 func override name 0verride0n0ff gt lt varOut gt The above lt var0ut gt will activate the controller override for controller ctrlID 103 if the
3. 7 2 Supervisor Time Interval Execution of supervisory control may not be required at each timestep of the simulation in which case the user may specify a simulation time interval which must elapse in order for the supervisor to be activated This interval is set within the supervisors XML tag specification via the attributes shown in Table 7 2 attribute type meaning days int number of days in interval hours int number of days in interval minutes int number of minutes in interval Table 7 2 MSE Supervisor XML For example to set the GLPK supervisor to run at simulation intervals of 3 days 2 hours and 1 minute the following XML tag attributes can be used lt management id 1 label RSM Supervisor gt lt glpk supervise id 801 label glpk supervise 1 modelFile glpk msei mod days 3 hours 2 minutes 1 gt lt glpk supervise gt lt management gt The default values are days 0 hours 0 minutes 0 which means that the Supervisor algorithm will run at every timestep 25 8 User Defined Supervisor 8 1 Implementation The user supervisor provides a facility for the user to independently develop a control algorithm applied to a controller watermover The user develops a supervisory algorithm in C C then compiles the control routine s into a shared object library The lt user supervise gt implements a shared library loader and function pointer interface which calls the
4. Constraints Objectives State Vector x N Controlled N WaterMovers gt Function HSE e HSE MSE LTS Interface Figure 2 MSE Schematic The MSE design approach is to allow multiple independent supervi sory control or objective optimization algorithms to run in parallel The supervisors are mapped to individual or multiple controllers providing a high level of flexibility in the configuration of control policies It is notable that this design allows for the investigation of regional water policy man agement decisions with implicit consideration of fully coupled hydrological flows and managed structure behaviors A schematic representation of the MSE information flow structure is shown in figure 2 MSE will receive state information from the HSE as well as constraint and objective information A from the user defined inputs MSE super visors compute a control vector X which is applied to the appropriate controllers A supervisor is capable of controlling a single or multiple con trollers and multiple controllers can be attached to a watermover though only one controller at a time can modulate the watermover It is relevant to note that this information processing scheme does not specify or rely upon a particular form of the control decision generator The implementation of a uniform interface between the supervisors and controllers and between the controllers and watermovers means that con trollers and su
5. www gnu org directory libs glpk html download from ftp ftp gnu org gnu glpk Ford L R Fulkerson D R Flows in Networks Princeton Uni versity Press 1962 Ahuja R K Magnanti T I Orlin J B Network Flows Theory Algorithms and Applications Prentice Hall 1993 Diba A Louie P W F Mahjoub M Yeh W Planned Oper ation of Large Scale Water Distribution System J Water Resour Plng and Mgmt 121 3 p 260 9 1995 Ostfeld A Water Distribution Systems Connectivity Analysis J Water Resour Plng and Mgmt 131 1 p 58 66 2005 64
6. MSE uses the lt spvrmonitor gt environment to monitor input state values fed to the supervisors or to monitor output values generated by supervisors To monitor controller I O and watermover variables the user may resort to the lt ctrlmonitor gt and lt wmmonitor gt environments respectively These moni tors are detailed in the MSE Controllers Manual 4 within the Watermover Control Maxflow Monitors and the Controller Monitors sections The lt spvrmonitor gt attributes are shown in Table 6 environment attribute meaning lt ctrlmonitor gt spvrID ID of supervisor to be monitored attr attribute to be monitored montype type of variable scalar vector var variable name for type vector Table 6 Supervisor Monitor XML Each supervisor monitor must define a spvrID attribute of the lt spvrmonitor gt The spvrID attribute specifies supervisor id number of the supervisor to be monitored The spvrID must be a positive integer The other required attribute is the attr The attr may take one of two values output or state which are used for supervisor output and input monitoring respectively Generally supervisors are multi input multi output MIMO though they can be single input single output The montype attribute speci fies whether the data stream is single or multi I O by assignment of the values scalar default or vector respectively In the case of multi inputs or outputs the va
7. Management Section gt lt management id 1 label glpk_supervise gt lt glpk_supervise id 301 label glpk_supervise modelFile glpk_mse mod modelName nine_cell probFile _glpk_mse prb solnFile _glpk_mse sol outputFile _glpk_mse out method simplex optimize minimize presolve off msglevel 3 timelimit 60 outfreq 1000 days 7 hours 0 minutes 0 gt lt Controllers to be controlled gt lt ctrlID gt 101 102 lt ctrlID gt lt GLPK output variables to controllers gt lt varOut ctrlID 101 func Control0ut name Gain_R1 gt lt varOut gt lt varOut ctrlID 102 func Control0ut name Gain_D1 gt lt var0ut gt lt Input variables to GLPK from HSE gt lt varIn param PCRi name PCRi monitor ctrlmonitor monID 1 monType maxflow gt lt varIn gt lt varIn param PCD1 name PCD1 monitor ctrlmonitor monID 2 monType maxflow gt lt varIn gt lt varIn param IH 1 name IH 1 monitor cellmonitor monID 1 monType head gt lt varIn gt lt varIn param IH 2 name IH 2 monitor cellmonitor monID 2 monType head gt lt varIn gt lt HSE State Monitors to Varln variables gt lt ctrlmonitor wmID 1 attr maxflow gt lt ctrlmonitor gt lt ctrlmonitor wmID 2 attr maxflow gt lt ctrlmonitor gt lt cellmonitor id 1 attr head gt lt cellmonitor gt lt cellmonitor id 2 attr head gt lt cellmonitor gt lt glpk supervise gt
8. The name arguments must correspond to a param defined in the GLPK model file Each lt varIn gt entry will have an associated lt monitor gt i e lt segmentmonitor gt entry The monitor monID and monType attributes must match the attributes of the associated state lt monitor gt For example the following are valid XML entries lt varIn param InitHead name IH 1 monitor cellmonitor monID 1 monType head gt lt varIn gt lt varIn param InitHead name IH 2 monitor cellmonitor monID 1 monType head gt lt varIn gt lt cellmonitor id 1 attr head gt lt cellmonitor gt lt cellmonitor id 2 attr head gt lt cellmonitor gt The corresponding data section of the GLPK model file could look like this param InitHead IH_1 12 5 IH 2 11 3 where the parameter InitHead is a vector with multiple input parame ters values IH 1 and IH 2 If the input parameter is not a vector but is a single variable then the param and name attributes have the same argument for example if the GLPK data section has parameter entries as follows 15 17 os param IH 1 param 1H_2 then the corresponding VarIn XML section would appear as lt varIn param 1H_1 name 1H_1 monitor cellmonitor monID 1 monType head gt lt varIn gt lt varIn param IH 2 name IH 2 monitor cellmonitor monID 2 monType head gt lt varIn gt lt cellmonitor id 1 attr head gt lt cellmonitor gt lt cell
9. 7 1 7 2 Global Supervisor On On ss a SE ate ey ee as Supervisor Time Interval User Defined Supervisor 8 1 8 2 Implementation ssa sugeri piora ES E ee a DEMI Interface sy eg nk AE Oe ETR ARO gta E R Ae 8 2 1 user supervise attributes 8 2 2 ctrllD environment 2 10 10 11 12 12 12 13 13 13 14 14 15 15 16 17 18 18 19 20 21 22 24 24 25 8 2 3 varIn attributes 28 8 2 4 varOut attributes 28 8 3 User Supervisor Criteria oaoa 29 8 4 User Supervisor Library Compilation 29 8 5 User Supervisor Initialization and Cleanup 30 8 6 User Supervisor and Statically Linked HSE 30 8 7 C User Supervisor Interface 31 8 8 C User Supervisor Interface 32 8 9 C User Supervisor API functions 33 8 9 1 E RE o N 33 8 10 User Defined Supervisor Example 35 9 Expert System Rule Based Fuzzy Supervisor 40 9 1 Fuzzy Supervisor Usage 2 2 0 0 eee ee 41 9 1 1 fuz supervise attributes e 42 9 1 2 ctrllD environment e 42 9 1 3 varln attributes e 42 9 1 4 varOut attributes o 43 9 2 Expert System Supervisor Example 44 10 GNU Linear Programming Kit GLPK Supervisor 49 10 1 GLPK MathProg Language 49 10 2 GLPK Supervisor Usage 50 HUE id attribute a a E
10. A 51 10 2 2 probFile solnFile outputFile attributes 52 10 2 3 method attribute o 52 10 2 4 optimize attribute o a 52 10 2 5 presolve attribute 52 10 2 6 msglevel attribute 52 10 2 7 timelimit attribute 53 10 28 outireq x usaria a Se ek do A 53 10 2 9 days hours minutes attribute 53 10 2 10ctrIID environment 53 10 2 11varln attributes 0 20 0 0 0000048 54 10 2 12 varOut attributes 2 20 0 0 00 2000 55 10 3 GLPK Supervisor Example o 56 10 3 1 GLPK XML File 57 11 Graph Flow Algorithm Supervisor 11 1 Graph Flow Supervisor XML o 11 1 1 graph supervise attributes 11 2 Graph Supervise Example 12 Object Routing Model Assessor Supervisor 1 Introduction The Regional Simulation Model RSM is a comprehensive hydrological model intended to serve the numerical modeling needs of the South Florida Water Management District RSM incorporates an object oriented design approach leveraging the inherent advantages of logical abstraction inheri tance and hierarchical data object organization throughout the model The RSM consists of two interactive primary components 1 Hydrologic Simulation Engine HSE 2 Management Simulation Engine MSE The HSE is a finite volume coupled surface groundwater canal numer ical
11. GLPK data file probFile optional problem output file solnFile optional solution output file outputFile optional info output file method simplex or interior optimize maximize or minimize presolve on or off msglevel 0 1 2 3 timelimit solution time limit in seconds outfreq output info frequency in iterations days supervise interval in days hours supervise interval in hours minutes supervise interval in minutes lt ctrlID gt list of controller IDs lt varIn gt input variable s param MathProg parameter for input name input variable name monitor monitor specification monID monitor ID monType monitor type lt var0ut gt output variable s ctrlID controller ID wmID watermover ID func controller function name output variable name lt monitor gt State variable specification Table 10 2 GLPK System XML 10 2 1 id attribute The id is a unique supervisor identifier label is an optional string which will label the outputs of the supervisor modelName is an optional label 51 to name the GLPK problem internally this name will then appear in the GLPK output files The modelFile attribute must specify a valid GLPK MathProg model file The dataFile is an optional file specification if the GLPK model file contains a data section this file is not required If the model file does not have a data section this attribute specifies the name of the data file 10 2 2 probFile solnFile outputFile attributes The probFile solnFile
12. Network lt mse node gt PJ lt mse_unit gt WCU10 HSE Network MSE Network Figure 3 HSE amp MSE Network 17 4 Input Variables The lt varIn gt XML environment provides a generic interface for the multi input variables accessed by MSE supervisors The XML attributes and environments supported by lt varIn gt are shown in Table 4 environment attribute meaning lt varIn gt input variable s name input variable name source input source monitor monitor specification monID monitor ID monType monitor type param parameter name for GLPK mse unit MSE Network unit WCU name unit attr MSE Network mse unit attribute mse arc MSE Network arc name arc_attr MSE Network mse_arc attribute mse_node MSE Network node name node_attr MSE Network mse_node attribute lt scalar gt single value XML input lt vector gt multi value XML input lt matrix gt 2D value XML input Table 4 varIn Tags The lt varIn gt environments define the state input s and provide a link between the inputs defined in the XML file and the RSM state variables The name argument defines a key which is used to access an input state variable Each lt varIn gt entry can have one of three source attributes which defines the source of the data input monitor xml or mse_network The default is source monitor 4 1 RSM Monitor Inputs To input state information from a RSM monitor inter
13. describes the available func attributes for each controller When a supervisor is used to activate a particular controller from among multiple controllers attached to a watermover the wmID attribute is used to specify the affected watermover the func controller must be set and the name defines the output variable function name in the shared library module which will return a controller id number positive integer of the controller to be activated 28 8 3 User Supervisor Criteria The following criteria apply to the lt user supervisor gt shared library 1 Ensure that the location of your library is included in the environment variable LD LIBRARY PATH 2 The function must include the mseIO h header file 3 The function must include the state mapIO cc file to access MSE API functions 4 The function must return an integer value 0 success nonzero failure 5 C shared library functions must accept two input arguments a pointer to a C STL containter map lt string InputState gt and a pointer to an map lt string OutputControl gt 6 C shared library functions must accept six input arguments First is an integer the number of variables Second is an array of character pointers each array element listing an input variable name Third is an array of floating point double pointers each reference is to the current state of the corresponding input variable with the same array index listed in the array of input va
14. environmen tal conditions constitutes an expert system which optimizes the regional hydrological responses under the constraints imposed by flood control wa ter supply and environmental concerns It is therefore important that a natural and efficient mechanism is employed by the MSE to allow for in corporation of expert system control The MSE achieves this by use of a multi input multi output characteristic field controller which is imple mented according to the International Electrotechnical Commission TEC Technical Committee on Industrial Process Measurement and Control Pro grammable Controllers 9 It relies upon a user defined set of input output variables and rules which map the variables to the control functions It is important that the format of the rules do not rely upon an obscure or difficult to understand syntax which decouples the natural expression of the existing knowledge base from that of the MSE implementation For example if the published guideline for a structure is If the upstream head at structure Al is high then open the gate then the corresponding rule in the expert system management should read roughly the same The obvious way to achieve this is to apply the principles of linguistic processing which have led to the development of the Fuzzy Control Language FCL The FCL provides a natural common language interface to the implementation of a nonlinear characteristic field controller and is ideal for th
15. gt are shown in Table 5 environment attribute meaning lt var0ut gt output variable s ctrlID controller ID wmID watermover ID func controller function name output variable name lt monitor gt State variable specification Table 5 User Defined Supervisor System XML Each varOut must have either the ctr1ID or wmID defined but not both The ctr1ID is used when a supervisor is setting a controller attribute as de scribed in section 2 1 The wmID is used only when a supervisor is selecting a controller for activation on a watermover For example in the following excerpt the first varOut is selecting a controller while the second and third are setting a controller functional attribute lt var0ut wmID 2 func controller name s4_Controller gt lt varOut gt lt var0ut ctrlID 103 func triglow name 103_TrigLow gt lt varQut gt lt var0ut ctrlID 104 func triglow name 104_TrigLow gt lt varQut gt The func attribute is used to specify which controller functional at tribute is being modified The allowed values of this attribute are described in section 2 1 The name attribute must correspond to the name of the su pervisor function in user defined modules or to the output variable name in the FCL file of fuzzy supervisors or the output variable name of a GLPK supervisor Refer to the section of a particular supervisor for usage and examples of varOut 21 6 Supervisor Monitors
16. lt management gt environment Within the lt management gt section the super visors are defined with appropriate XML specifications The XML environ ments available for the MSE supervisors are shown in Table 7 environment meaning lt user_supervise gt User defined finite state machine lt fuz_supervise gt FCL rule based expert system lt glpk_supervise gt GNU Linear Programming Kit lt orm_supervise gt Object Routing Model lt graph_supervise gt Graph theory flow algorithms Table 7 MSE Supervisor XML General supervisory control XML for activation deactivation of supervi sors or conditional supervisor execution are described below in sections 7 1 and 7 2 7 1 Global Supervisor On Off It may be advantageous to deactivate all supervisors with a single variable This is the function of the supervisors variable in the lt control gt section of the XML input file The default value is supervisors on If the value is set to any value other than on all supervisors will be deactivated The supervisors will not influence the behavior of the controllers the controllers will operate according to their internal algorithms or rules An example of this usage is shown below 24 lt control tslen 15 tstype minute startdate 01jani994 starttime 1200 enddate 05jan1994 endtime 0600 alpha 0 500 solver PETSC method gmres precond ilu controllers on supervisors o0ff gt lt control gt
17. user defined control function s at each timestep Each lt user supervise gt will maintain it s own shared object and function pointer information allowing the user to define multiple supervisory functions inside a single shared object so that individual supervisors may be enacted by selected functions which reside inside a single shared object It is also possible to define separate shared objects for each supervisor The user defined functions can take advantage of several RSM application programming interface API functions to assist in accessing input state variables and setting output values The library function interface is different for C and C libraries as described in the following sections User defined supervisor shared object codes must include the file mseIO h 8 2 XML Interface Four information items have to be supplied to the supervisor for correct coupling to the RSM state and control information controller id s input state variables output control variables ON shared library information this is done with use of the XML attributes available for the user defined supervisor shown in Table 8 2 26 environment attribute meaning lt user supervise gt id supervisor id label optional supervisor label libType type of shared object module shared library path name func supervisor function name in module xml MSE Network XML file graph MSE Network graph file flow graph t
18. watermover the wmID attribute is used to specify the affected watermover the func controller must be set and the name defines the output variable name from the GLPK model file which will return a controller id number positive integer of the controller to be activated An example of a valid VarOut XML section to change the attribute of a controller is shown below lt varOut ctrlID 101 func Control0ut name Gain_R1 gt lt var0ut gt where the output value of the GLPK supervisor into the GLPK model variable named Gain BI is passed to the controller with id 101 and set as the new Control0ut value of the controller An example of a valid VarOut XML section to change the active con troller of a watermover is shown below lt varOut wmID 1 func controller name wmi_ControllerID gt lt varOut gt where the output of the GLPK supervisor into the GLPK model vari able named wm1_ControllerID is a controller id which is used to select a controller from the list of controllers attached to the watermover with wmID 1 55 10 3 GLPK Supervisor Example See the RSM Benchmark BM47 for a complete example of the GLPK su pervisor applied to control of watermover controllers An excerpt from the RSM XML file of BM47 is shown below 56 10 3 1 GLPK XML File lt hse version 0 1 gt lt control tslen 1 tstype day startdate 01jan2000 starttime 0000 enddate 30jan2000 endtime 0000 alpha 0 500 solver PET
19. will receive two input state values named segment 1Head and segment4Head The state variables will reside in an InputStateMap with keys segmentiHead and segment4Head which are used to access the input values through the GetVarIn API function The two controllers attached to watermover 1 are simple linear transfer function setpoint con trollers Refer to the Setpoint Controllers section of the MSE Controller Manual 4 for complete descriptions of the controller parameters The XML controller definitions for this example are lt controller id 1 gt lt Multiple controllers per watermover are defined gt lt The first controller parsed will be set as the active controller gt lt Any subsequent controller with control on will become the gt lt active controller for the watermover gt lt To change the active controllers the supervisor must assign gt lt another controller gt lt Controller for discharge from segment 1 gt lt setpointctrl cid 101 label SPCtrl 1 wmID 1 window all control on setlow 0 0 sethigh 1 0 triglow 500 0 trighigh 505 0 trigger on gt lt segmentmonitor id 1 attr head gt lt segmentmonitor gt lt setpointctrl gt lt Controller for discharge from segment 1 gt lt setpointctrl cid 102 label SPCtrl 1A wmID 1 window all control on setlow 0 0 sethigh 0 5 triglow 495 0 trighigh 500 0 trigger on gt lt segm
20. If the supervisor is selecting a controller from among multiple controllers then there may not be a lt varOut gt for each entry in the lt ctr1ID gt list 8 2 3 varIn attributes The lt varIn gt environments define the state input s and provide a link be tween the inputs defined in the shared library function and the RSM state variables The name arguments define a key which is used in the user defined function code to access input state variables Refer to section 4 Input Variables for a description and usage of the lt varIn gt environment 8 2 4 varOut attributes The lt varOut gt attributes specify which controller is modified by which out put variable linked to a shared library module function or to activate a single controller for a watermover from among multiple controllers attached to a watermover Section 5 details the allowable XML entities for lt varOut gt In the case where a controller variable is to be changed the ctr1ID attribute is used to specify the controller the name defines the the output variable function name in the shared library module and the func specifies the con troller variable to be changed It is possible to have multiple lt varOut gt entries for a single controller For example a supervisor may define three lt var0ut gt terms to modify the on off minimum output and maximum out put behaviors of a single controller Each lt var0ut gt would have a distinct func and name entry Section 2 1
21. R Grp US441 Stage IS med THEN SY76 Control IS on RULE 2 IF S76 US441 Stage IS high THEN S76 Control IS off RULE 3 IF S76 Stage IS low OR S76 Stage IS med THEN S76_Control IS on RULE 4 IF S76 Stage IS high THEN SY76 Control IS off RULE 5 IF canalPoint_Stage IS low OR canalPoint_Stage IS med THEN S352_Control IS on RULE 6 IF canalPoint_Stage IS high THEN S352_Control IS off RULE 7 IF S155 Stage IS low OR S155 Stage IS med THEN 8352 Control IS on RULE 8 IF S155 Stage IS high THEN S352 Control IS off END RULEBLOCK END FUNCTION BLOCK 47 The following FCL shows an example of the fuzzy supervisor applied to the setpoint controller FUNCTION BLOCK 8340 Supervise VAR INPUT S340 Stage REAL season REAL END VAR VAR OUTPUT 8340 Control trigLow REAL END VAR FUZZIFY S340 Stage TERM low 4 1 5 0 TERM med 4 0 5 1 6 0 TERM high 5 0 6 1 END_FUZZIFY FUZZIFY season TERM dryi 4 1 4 1 0 TERM wet 4 5 0 4 5 1 9 5 1 9 5 0 TERM dry2 9 9 0 10 1 END_FUZZIFY DEFUZZIFY S340 Control trigLow TERM one 1 TERM five 5 RANGE 0 5 END_DEFUZZIFY RULEBLOCK 5340_Rules RULE 1 IF 5340_Stage IS low AND season is wet THEN 340_Control_trigLow IS one RULE 2 IF 5340_Stage IS low AND season is NOT wet THEN 340_Control_trigLow IS one RULE 3 IF 5340_Stage IS med AND season is wet THEN S340_Control_trigL
22. Regional Simulation Model RSM Management Simulation Engine MSE Version 2 2 9 Supervisors Documentation and User Manual South Florida Water Management District Office of Modeling Model Development Division 4540 February 15 2005 Abstract This document provides descriptions and documentation of super visory control facilities implemented in the Management Simulation Engine MSE component of the Regional Simulation Model RSM Contents 1 Introduction 11 1 2 RSM Architecture MSE Architecture roa So ea E a Supervisory Control of Controllers 2 1 2 2 2 3 Controller Functional Attributes 2 1 1 General Controller Function XML 2 1 2 Fuzzy Controller Function XML 2 1 3 Setpoint Controller Function XML 2 1 4 Sigmoid Controller Function XML 2 1 5 PID Controller Function XML 2 1 6 User Controller Function XML 2 1 7 LP Controller Function XML 2 1 8 Alpha Controller Function XML Multiple Controller Selection e 2 2 1 Multiple Controller Selection XML Controller Override ea iea ee a a 2 3 1 Controller Override XML MSE Network Input Variables 4 1 4 2 4 3 RSM Monitor Inputs e XML Inputs ia EE a e ESA E RE AN A MSE Network Inuputs e o Output Variables Supervisor Monitors Supervisors General Usage
23. SC method gmres precond ilu units METRIC controllers on supervisors on gt lt control gt lt mesh gt lt geometry file mesh3x3 2dm gt lt geometry gt lt shead gt lt gms file hin3x3 dat gt lt gms gt lt shead gt lt surface gt lt gms file elev3x3 dat gt lt gms gt lt surface gt lt bottom gt lt const value 50 0 gt lt const gt lt bottom gt lt Overland flow gt lt conveyance gt lt mannings a 0 1 detent 0 00001 gt lt mannings gt lt conveyance gt lt Groundwater flow gt lt transmissivity gt lt unconfined k 0 001 gt lt unconfined gt lt transmissivity gt lt svconverter gt lt constsv sc 0 2 gt lt constsv gt lt svconverter gt lt mesh gt lt watermovers gt lt R1 Release from lake gt lt setflow wmID 1 idi 2 id2 20 label Ri Lake Release gt lt const value 30 0 dbintl 1440 gt lt const gt lt setflow gt lt D1 Demand removed from wetland gt lt setflow wmID 2 idi 5 id2 21 label D1 Demand gt lt const value 30 0 dbintl 1440 gt lt const gt lt setflow gt lt watermovers gt 57 lt Controller Section gt lt controller id 1 gt lt Controller for Ri gt lt lpctrl cid 101 wmID 1 label FlowCtrl Binz lt lpctrl gt lt Controller for Di gt lt lpctrl cid 102 wmID 2 label FlowCtrl D1 gt lt lpctrl gt lt controller gt lt
24. acteristics may be enabled in varying state variable regimes suitable to each controller For example a simple piecewise linear transfer function may be used under dry conditions while a rule based expert system fuzzy controller may be more effective in flood conditions A MSE supervisor can select and activate one of multiple controllers attached to a watermover Note that the MSE to HSE controller interface does not allow multiple concurrent controllers to provide flow modulation commands to a water mover Although multiple controllers may be attached to a watermover and can perform control algorithm computations concurrently in the same timestep only one controller per timestep will have it s control output ap plied to a watermover It is the user s responsibility to ensure that multiple controllers are supervised accordingly When multiple controllers per watermover are initially parsed and cre ated from the XML model file specifications the first controller that is parsed will be set as the active controller for the watermover Subsequently con trollers that are encountered for the same watermover will replace the ex isting active watermover if the controller attribute control on is set Examples of a user defined supervisor activating single controllers from multiple watermover controllers are shown in section 8 10 14 2 2 1 Multiple Controller Selection XML attribute value meaning func
25. ailable meta control attributes for each controller are described in section 2 1 However it is notable that all controllers imple ment the control XML attribute which is used to activate deactivate the controller If the value of control is set to any value other than on the controller will be deactivated This means that the control output will be forced to a value of 1 no control output variations will occur Since the con trol outputs are applied as amplitude modulation factors to the watermover flow the watermover flow will default to it s uncontrolled values It is worth noting that there is a special controller dedicated solely to Linear Programming LP supervisory control the lt 1pctr1 gt controller The purpose of this controller is to provide a transparent interface from a LP supervisory control variable to control of a watermover flow The lt lpctr1 gt controller therefore has no control algorithm and does not process state information The lt lpctr1 gt controller simply links a LP supervisor output variable to a watermover flow such that the value of the supervisor output variable directly scales multiplies the watermover flow value Description and implementation details of the MSE controllers can be found in the MSE Controllers Manual 4 2 1 Controller Functional Attributes Each controller has specific attributes which may be controlled by the super visor The interface to these functions is specif
26. ally set one of the multiple output variables int SetVarOut string string double map lt string OutputControl gt lpQutputControlMap func varOutName control0ut Table 8 9 1 SetVar0ut function prototype The function returns an integer value of either 0 failure or 1 success The input arguments are described below Name Type Description func string name of function in user library calling Get MSENodeVal used for error reporting var OutName string name of the varOut output variable controlOut double numeric output value of supervisor to varOut IpOutputControlMap map lt string pointer to the Output ControlMap OutputControl gt passed into the user defined supervisor function Table 8 9 1 SetVar0Out function arguments An example of lt varOut gt XML entries from a supervisor are shown below lt This uses wmID to specify a controller via cid output gt lt varOut wmID 1 func controller name wm1_ctr1 gt lt varOut gt lt This uses ctrlID to set specific controller attributes gt lt varOut ctrlID 102 func triglow name ctrl 102 gt lt varOut gt 34 A corresponding C supervisory function could be written as shown below extern C int MySupervise map lt string InputState gt 1pISMap map lt string OutputControl gt lpOCMap string func MySupervise double spvrOuti 0 double spvrOut2 0
27. attributes The id is a unique supervisor identifier label is an optional string which will label the outputs of the supervisor The fcl attribute must specify a valid FCL definition file The supervisor time interval control attributes days hours minutes provide a mechanism to run the supervisor at se lected intervals see section 7 2 9 1 2 ctrlID environment The lt ctrlID gt environment defines a list of RSM controllers that will be supervised The values in this list must match a cid attribute of a valid controller definition For example if the following controller is defined lt setpointctrl cid 125 wmID 25 label 538 Culvert gt then a valid entry in the lt ctrlID gt list is 125 Each controller id in the list will have at least one corresponding lt varOut gt entry which couples the controller modifier with the corresponding specification in the rule FCL file 9 1 3 varIn attributes The lt varIn gt define the state input s and provide a link between the in puts defined in the FCL file and the RSM state variables The name ar guments must correspond to VAR INPUT variables defined in the specified FCL file Each lt varIn gt entry will have an associated lt monitor gt i e lt segmentmonitor gt entry The monitor monID and monType attributes must match the attributes of the associated state lt monitor gt For example the following are valid XML entries lt varIn name S76 Stage monitor segm
28. ble 8 8 C user supervisor function prototype The C map pointed to by 1pISMap contains pointers to InputState classes one pointer for each varIn variable defined in the supervisor XML file The map key to each pointer is the variable name var In as defined in the userspvr section of the XML file To access an input state variable the supervisor function calls the GetVarIn API function as described in section GetVarIn in the MSE Controller Manual The definition of the InputState structure can be found in the C source file mseT0 h which is a required header file In an analogous fashion the C map pointed to by 1pOCMap contains pointers to QutputControl classes one pointer for each varOut variable de fined in the supervisor XML file The map key to each pointer is the variable name varOut as defined in the userspvr section of the XML file To assign an output value the supervisor function calls the SetVarOut API function as described in section 8 9 1 The definition of the OutputControl structure can be found in the C source file mseI0O h The C supervisors must return an integer value A return value of O indicates no error occurred in the supervisor function A non zero return value indicated that an error occurred in the user supervisor function In this case an MseError exception is thrown by the MSE ending the simulation An example of a user defined supervisor function interface is shown be low 32 includ
29. cular controller from among multiple controllers attached to a watermover the wmID attribute is used to specify the affected watermover the func controller must be set and the name defines the output variable name from the FCL file which will return a controller id number positive integer of the controller to be activated Currently the fuzzy supervisor can only return floating point values The natural process of fuzzy inferencing and defuzzification may make precise control of controller id problematic The following lt management gt environment XML excerpt demonstrates the usage of lt varOut gt to change the behavior triglow threshold of two controllers ctrlID 101 ctrlID 102 lt management id 1 label multi control gt lt fuz supervise id 801 label fuz_sprv fcl multictrl_sprv fcl gt lt ctrlID gt 101 102 103 104 lt ctrlID gt lt Input variables to multictrl sprv fcl gt lt varIn name segmentiHead monitor segmentmonitor monID 1 monType head gt lt varIn gt lt varIn name segment4Head monitor segmentmonitor monID 4 monType head gt lt varIn gt lt Input variable monitors from hse to varIn gt lt segmentmonitor id 1 attr head gt lt segmentmonitor gt lt segmentmonitor id 4 attr head gt lt segmentmonitor gt lt These use ctrlID to set specific controller attributes gt lt varOut ctrlID 101 func triglow name segi TrigLow gt lt varUut gt
30. e lt map gt include hse src msel0 h include hse mse_tools state_mapI0 cc extern C int MySupervise map lt string InputState gt 1pISMap map lt string OutputControl gt 1p0CMap string func MySupervise double spvrOuti 0 double spvrOut2 0 double hi GetVarIn func segmentiHead lpISMap double h2 GetVarIn func segment4Head 1pISMap Provide supervsory function based on input state variable Set the output variables if not SetVarOut func ctrl 101 spvr0ut1 lpOCMap gt return 1 if not SetVarOut func ctrl 102 spvr0ut2 lpOCMap gt return 1 return 0 8 9 C User Supervisor API functions MSE provides a set of API functions to be used for the access of input state variables setting of output state variables and accessing data members from the MSE Network With the exception of the SetVarOut function all user API functions can be used from a controller as well as a supervisor For this reason the API functions are documented in the MSE Controllers Manual 4 in section C User Controller API functions 8 9 1 SetVarOut To set the value of an output variable from a user defined supervisor the su pervisory function makes a call to the SetVarOut function The SetVarOut function is not used with MSE controllers as the controllers are MISO multi 33 input single output processors SetVarOut is used only with MSE supervi sors to individu
31. ead gt lt segmentmonitor gt lt tkprmonitor attr month gt lt tkprmonitor gt lt fuz_supervise gt lt management gt 45 Following is an example of the FCL supervisor control file for supervision of the two fuzzy controllers FUNCTION BLOCK S76 5352 Supervise VAR INPUT S76 US441 Stage REAL S76 Stage REAL canalPoint Stage REAL 8155 Stage REAL END VAR VAR OUTPUT S76 Control REAL 8352 Control REAL END VAR FUZZIFY S76 US441 Stage low ramp med triangle high ramp TERM low 15 1 18 0 TERM med 15 0 18 1 20 0 TERM high 18 0 20 1 END_FUZZIFY FUZZIFY S76_Stage low ramp med rectangle high ramp TERM low 15 1 18 0 TERM med 16 0 16 1 19 1 19 0 TERM high 18 0 20 1 END_FUZZIFY FUZZIFY canalPoint_Stage low ramp med trapezoid high ramp TERM low 15 1 18 0 TERM med 15 0 16 1 18 1 20 0 TERM high 18 0 20 1 END_FUZZIFY FUZZIFY S155 Stage low ramp med triangle high ramp TERM low 15 1 18 0 TERM med 15 0 18 1 20 0 TERM high 18 0 20 1 END FUZZIFY 46 DEFUZZIFY S76 Control All outputs are singletons TERM off 0 TERM on LL RANGE 0510 END_DEFUZZIFY DEFUZZIFY S352_Control All outputs are singletons TERM off 0 TERM on 1 RANGE 0 1 END_DEFUZZIFY RULEBLOCK S76 5352 Rules RULE 1 IF S76 US441 Stage IS low O
32. entmonitor monID 1 monType head gt lt varIn gt lt varIn name segment4Head monitor segmentmonitor monID 4 monType head gt lt varIn gt lt Input variable monitors from hse to varln gt lt segmentmonitor id 1 attr head gt lt segmentmonitor gt lt segmentmonitor id 4 attr head gt lt segmentmonitor gt lt These use ctrlID to set specific controller attributes gt lt varOut ctrlID 101 func triglow name ctrl 101 TrigLow gt lt varOut gt lt varOut ctrlID 102 func triglow name ctrl 102 TrigLow gt lt varOut gt lt user supervise gt lt management gt 37 To compile this example code into a shared library named UserSprv so on a Linux platform gcc usersprv cc BSymbolic shared o UserSprv so The c code for each of the supervisor functions is shown below include lt cstdio gt include if you want to use C style printf include lt map gt include hse src msel0 h THIS FILE MUST BE INCLUDED include hse mse tools state mapl0 cc THIS FILE MUST BE INCLUDED extern C double SetWMiController map lt string InputState gt lpInputStateMap map lt string OutputControl gt lpOutputControlMap int status 0 double superviseOut 0 output value Get the current state value for each variable double segmentiHead GetVarIn func segmentiHead lpInputStateMap Select controller id 101 or 102 based on input state variable if s
33. entmonitor monID 7 monType head gt lt varIn gt lt segmentmonitor id 7 attr head gt lt segmentmonitor gt However if the monitor is a timekeeper monitor lt tkprmonitor gt the monID attribute is not used The timekeeper monitor does not use the id attribute as do the other state monitors An example of this invocation would be lt varIn name season monitor tkprmonitor monType month gt lt varIn gt lt tkprmonitor attr month gt lt tkprmonitor gt 42 9 1 4 varOut attributes The lt varOut gt attributes specify which controller is modified by which out put variable in the FCL definition or activate a single controller for a water mover from among multiple controllers attached to a watermover Section 5 details the allowable XML entities for lt varOut gt In the case where a controller variable is to be changed the ctr1ID attribute is used to specify the controller the name defines the the output variable name from the FCL file and the func specifies the controller variable to be changed It is pos sible to have multiple lt var0ut gt entries for a single controller For example a supervisor may define three lt varOut gt terms to modify the on off mini mum output and maximum output behaviors of a single controller Each lt varOut gt would have a distinct func and name entry Section 2 1 describes the available func attributes for each controller When a supervisor is used to activate a parti
34. entmonitor id 1 attr head gt lt segmentmonitor gt lt setpointctrl gt lt controller gt 36 The XML section which defines the supervisors to select the active con troller and to adjust the lower trigger threshold of the controllers is shown below lt management id 1 label user multi control gt lt Select a controller for watermover 1 gt lt user supervise id 801 label SetWMiController libType C module UserSprv so func SetWM1Controller gt lt ctrlID gt 101 102 lt ctrlID gt lt Input variables to SetWMiController gt lt varIn name segmentiHead monitor segmentmonitor monID 1 monType head gt lt varIn gt lt varIn name segment4Head monitor segmentmonitor monID 4 monType head gt lt varIn gt lt Input variable monitors from hse to varIn gt lt segmentmonitor id 1 attr head gt lt segmentmonitor gt lt segmentmonitor id 4 attr head gt lt segmentmonitor gt lt This uses wmID to specify a controller via cid output gt lt varOut wmID 1 func controller name segment1_Controller gt lt var0ut gt lt user_supervise gt lt Set the triglow threshold for controllers 101 amp 102 gt lt user_supervise id 803 label SetWMiCtrlTriggers libType C module UserSprv so func SetWM1CtrlTriggers gt lt ctrlID gt 101 102 lt ctrlID gt lt Input variables to SetWMiCtrlTriggers gt lt varIn name segmentiHead monitor segm
35. ete or continuous variables Developed at Bell Laboratories AMPL lets you use common notation and familiar concepts to formulate optimization models and examine solutions while the computer manages communication with an appropriate solver See www ampl com 49 10 2 GLPK Supervisor Usage The RSM GLPK Supervisor gplk supervise is defined by a MathProg model definition file which specifies the parameters variables and optimiza tion function of the supervisor The model definition file may also contain a data section which defines parametric values and initial values for variables If the data section is not included in the model definition file then a sepa rate data definition file must exist The MSE GLPK supervisor reads these files creates the GLPK problem objects and calls the appropriate GLPK API routines to solve the supervisory constrained optimization problem Four information items have to be supplied to the supervisor for correct coupling to the RSM state and control information controller id s input state variables output control variables GLPK model and data file s CO r this is done by use of the XML attributes available for the GLPK super visor glpk supervise shown in Table 10 2 50 environment attribute meaning lt glpk supervise gt id supervisor id label optional supervisor label modelFile name of GLPK model file modelName optional model label dataFile name of
36. face i e lt segmentmonitor gt set the source monitor or omit the source attribute In this case the varIn will have an associated lt monitor gt entry The monitor monID and monType attributes must match the attributes of the associated state lt monitor gt For example the following are valid XML entries for a varIn and monitor pair 18 lt varIn name Segment1 monitor segmentmonitor monID 1 monType head gt lt varIn gt lt segmentmonitor id 1 attr head gt lt segmentmonitor gt However if the monitor is a timekeeper monitor lt tkprmonitor gt the monID attribute is not used The timekeeper monitor does not use the id attribute as do the other state monitors An example of this invocation would be lt varIn name season monitor tkprmonitor monType month gt lt varIn gt lt tkprmonitor attr month gt lt tkprmonitor gt 4 2 XML Inputs To define static input variables directly in the XML of the varIn set source xml Three variable formats are supported scalar vector ma trix The scalar is simply a single data value A vector is a one dimensional list of values and the matrix is a two dimensional table of columns and rows Within a single varIn environment one XML input variable environ ment may be created as shown below lt varIn name xmlScalar source xml gt lt scalar gt 325 43 lt scalar gt lt varIn gt lt varIn name xmlVector source xml gt lt vector
37. gger threshold for the controller 44 management id 1 label FuzzySupervisor gt lt fuz supervise id 1 label S76 S352 Supervise fcl spvr ST76 S352 fcl gt lt ctrlID gt 101 102 lt ctrlID gt lt varOut ctrlID 101 func control0n name S76_Control gt lt varOut gt lt varOut ctrlID 102 func control0n name S352_Control gt lt var0ut gt lt varIn name S76 US441 Stage monitor segmentmonitor monID 6 monType head gt lt varIn gt lt varIn name S76_Stage monitor segmentmonitor monID 7 monType head gt lt varIn gt lt varIn name canalPoint Stage monitor segmentmonitor monID 142 monType head gt lt varIn gt lt varIn name S155 Stage monitor segmentmonitor monID 78 monType head gt lt varIn gt lt segmentmonitor id 6 attr head gt lt segmentmonitor gt lt segmentmonitor id 7 attr head gt lt segmentmonitor gt lt segmentmonitor id 142 attr head gt lt segmentmonitor gt lt segmentmonitor id 78 attr head gt lt segmentmonitor gt lt fuz_supervise gt lt fuz supervise id 2 label S340_Supervise fcl spvr_5340 fc1 gt lt ctrlID gt 123 lt ctrlID gt lt var0ut ctrlID 123 func triglow name S340 Control trigLow gt lt var0ut gt lt varIn name S340 Stage monitor segmentmonitor monID 363 monType head gt lt varIn gt lt varIn name season monitor tkprmonitor monType month gt lt varIn gt lt segmentmonitor id 363 attr h
38. gt 1 2 3 4 5 6 7 8 9 1 lt vector gt lt varIn gt lt varIn name xmlMatrix source xml gt lt matrix gt 1 2 3 4 5 6 7 8 9 1 2 3 lt matrix gt lt varIn gt Vector datamembers are delimited by whitespace Matrix columns mem bers of a row are delimited by whitespace Matrix rows are delineated by or All vector and matrix indices follow C C semantics 0 is the first element To access these members from a user defined supervisor several interface functions are provided as described in the MSE Controllers Man ual 4 in section C User Controller API functions The XML inputs are currently only supported for C user defined controllers and supervisors 19 4 3 MSE Network Inputs The supervisor can also obtain input variables from objects of the MSE Network see section MSE Network of the MSE Controllers Manual 4 Any variable that is contained in an mse_unit mse_arc or mse_node can be accessed Currently only the User Defined supervisor is capable of accessing these values through the use of API function calls Sections C User Controller API functions and MSE Network XML in the MSE Controllers Manual 4 provide details and examples on the usage of these functions 20 5 Output Variables The varOut environment is used to couple the possibly multiple output of a supervisor function to the appropriate controller or watermover The XML attributes and environments supported by lt var0ut
39. heory solution type days supervise interval in days hours supervise interval in hours minutes supervise interval in minutes lt ctrlID gt list of controller IDs lt varIn gt input variable s lt var0ut gt output variable s lt monitor gt state variable to varIn Table 8 2 User Defined Supervisor System 8 2 1 user supervise attributes The id is a required unique supervisor identifier The label is an optional string which will label the outputs of the supervisor The module attribute must specify a valid shared library path name The func must specify a valid function symbol name contained within the module shared library The libType attribute must specify one of the following options e C Cpp c cpp e C c The supervisor time interval control attributes days hours minutes provide a mechanism to run the supervisor at selected intervals see section hed 8 2 2 ctrlID environment The lt ctrlID gt environment defines a list of RSM controllers that will be supervised The values in this list must match a cid attribute of a valid controller definition For example if the following controller is defined 27 lt setpointctrl cid 125 wmID 25 label 538 Culvert gt then a valid entry in the lt ctr1ID gt list is 125 Each controller id in the list should have at least one corresponding lt var0ut gt entry which couples the controller modifier with the corresponding function in the shared library
40. ied with the func attribute of the lt var0ut gt supervisor tag see section 7 Generally there is a func 10 attribute which directly corresponds to an XML attribute of the controller definitions For example the Setpoint controller has an attribute setlow as shown here lt setpointctrl cid 125 wmID 25 label 538 Culvert setlow 0 gt The exact same effect can be achieved by the supervisor by specifying an output variable with a value of 0 that is linked to the func setLow Sec tions 2 1 1 2 1 8 define the allowed functional attributes for each controller Refer to the RSM Controllers Manual 4 for descriptions of the individual controller functional attributes 2 1 1 General Controller Function XML In addition to the controller specific functions all controllers share some common functions that can be controlled by the supervisor These common functions and values are shown in Table 2 1 1 attribute value meaning func controlOn 0 or 1 on or off ctrlMin 0 1 minimum output ctrlMax 0 1 maximum output Table 2 1 1 Common Controller Functions If the value of control0n is set to any value other than 1 the controller will be deactivated This is directly analogous to the control off XML attribute in the controllers XML definition If the controller is deactivated the control output will be forced to a value of 1 no control output variations will occur Since
41. is purpose The RSM controllers include a fuzzy controller which resides in an RSM library developed by the Model Development Division The MSE leverages on the independent control functionality of the FCL library and uses it to enact a multi controller supervisory agent 40 9 1 Fuzzy Supervisor Usage The Expert System Supervisor fuz supervise relies on a user supplied knowledge base to enact controller supervision Four information items have to be supplied to the supervisor for correct coupling to the RSM state and control information controller id s input state variables output control variables VG V Ne rule base this is done by use of the XML attributes available for the rule based expert system fuz_supervise shown in Table 9 1 environment attribute meaning lt fuz_supervise gt id supervisor id label optional supervisor label fcl name of FCL rule file days supervise interval in days hours supervise interval in hours minutes supervise interval in minutes lt ctrlID gt list of controller IDs lt varIn gt input variable s name input variable name monitor monitor specification monID monitor ID monType monitor type lt varQut gt output variable s ctrlID controller ID wmID watermover ID func controller function name output variable name lt monitor gt State variable specification Table 9 1 Rule based Expert System Al 9 1 1 fuz supervise
42. lt management gt lt hse gt 58 11 Graph Flow Algorithm Supervisor Note Currently the flow results from a Graph supervisor are not output to the HSE watermovers or controllers From the perspective of mathematical graph theory there is a well de veloped body of work regarding the assessment of flows in interconnected networks 11 12 Graph representations of flow networks for water dis tribution and stream flow networks are common and useful 13 14 The MSE maintains a graph theory based representation of the managed canal network in the MSE Network section 3 As described in the MSE Network section of the MSE Controllers Manual the MSE Network may be defined with an XML file or a flat file representation The Graph supervisor implements the maxflow feasible flow and min cost feasible flow algorithms These algorithms are highly efficient numerical procedures which solve constrained optimization problems on the network flow by taking advantage of the network properties rather than by solving a set of simultaneous equations explicitly The constraints consist of the canal arc capacity the hydraulic structure capacity demand and supply flows at the structures and flow cost weights assigned to the canal arcs Each graph supervisor solves the network flow based on it s own MSE Network representation however this representation can be degenerate with other supervisor MSE Network representations therefore supervisors ma
43. lt var0ut ctrlID 102 func triglow name seg4_TrigLow gt lt varUut gt lt fuz_supervise gt lt management gt 43 9 2 Expert System Supervisor Example The following example illustrates two rule based supervisors one applied to two fuzzy controllers the other to a setpoint controller The fuzzy controllers have control ids of 101 and 102 the setpoint controller id is 123 The supervisor for the fuzzy controllers label S 76_S352_Supervise is defined in the rule file fcl spvr S76 S352 fcl and has two control outputs one for each controller and four inputs The output variables of the fuzzy controller supervisor are name S76 Control and name S352 Control These names match the definition of output variables VAR OUTPUT in the spvr S76 S352 fcl file The ctrlID 101 and ctrlID 102 specify the controllers listed in the lt ctrlID gt that will have the output values ap plied to them Since the func control0n the output of the FCL variable S76 Control will be applied to the controller on off attribute of the con troller with the control id 101 The lt varIn gt environment couples the FCL file input variables defined as VAR_INPUT in the FCL file with the RSM state monitors The setpoint controller supervisor will modify the behavior of the con troller with a control id of 123 The func trigLow specification means that the output value of the variable S340 Control triglLow will be applied to set a new lower tri
44. meseries amplitude modulation consisting of the usual arithmetic operations multiplication division addition subtrac tion or may compute simple timeseries or spatial variable statistics such as arithmetic geometric or other expectations or may act as an accumulator Information on filters may be found in the MSE Controllers Manual 4 in section Data Monitor Filters The MSE accesses any raw assessed or filtered state information through a lt monitor gt interface Based on the hydrological state information as well as any needed supervisory or control information the MSE sets controller variables for each supervised controller The controller then modulates the maximum available flow of the HSE watermover 1 2 MSE Architecture The MSE is tasked with a multi dimensional objective function resolution based on finite resource allocations and possibly interactive multi variate constraint imposition This task sounds complex and it is To achieve this in a generalized algorithmic independent implementation requires signifi cant complexity in the design of the MSE Nonetheless it is intended that utilization of industry standardized rule base formulations mathematical programming language interpreters and application specific heuristic su pervisory algorithms can serve to isolate the modeler from such complexity Woda Vaualoygwan 014191910 MSE Supervisor Controller Interface E Processed T 2
45. ml file The fifth argument is an array of character strings Each array element contains the name of an output variable as defined in the lt var0ut name gt section of the xml file The sixth argument is an ar ray of floating point double values which are used to contain the output value computed by the supervisor The array indices of the fifth and sixth arguments match on a one to one basis That is for the variable with the name var0utNames 2 the output value is set into var0utValues 2 The fact that the user has to properly track and access these I O pointers makes the C function interface hazardous It is safer and less error prone to rely on the C user interface wherein the assignment of lt var0ut gt values is performed with a function call to the API function SetVarOut refer to section 8 9 1 31 The supervisor functions must return an integer int status value A value of 0 indicates no error a non zero return value indicates that an error has occurred in the supervisor function in which case a MseError exception will be thrown and the simulation terminated 8 8 C User Supervisor Interface User defined supervisors developed in C receive two input variables which are pointers to an inputStateMap and an outputControlMap associative array as illustrated in the following prototype extern C int MySupervise map lt string InputState gt 1pISMap map lt string OutputControl gt lpOCMap Ta
46. model with full 2D and partial 3D flow capability HSE includes struc ture flow equations for a wide variety of control structures and implements efficient numerical solutions of conjunctive hydrological simulations 1 2 3 The MSE is designed to simulate the operational control characteris tics encompassed by the wide spectrum of water flow control structures and algorithms currently in use The MSE is comprised of two primary subcom ponents 1 Controllers 2 Supervisors The controllers are a suite of low level control algorithms which serve as flow regulators for individual structures The controllers are defined within the RSM XML model file lt controller gt tag environment and are detailed in a separate document 4 The supervisors comprise a set of high level su pervisory control functions which provide dynamic controller modification and coordination intended to facilitate regional control objectives The su pervisors therefore enable regional and subregional operational policy sim ulation in the RSM by interacting with and controlling the behavior of the watermover controllers Each supervisor must be defined in the RSM XML input file within the lt management gt tag environment This document provides development implementation and usage details for the MSE su pervisors MSE is intended to provide two major modes of functionality in assisting the hydrological modeler involved in analysis and prediction of water control
47. monitor id 2 attr head gt lt cellmonitor gt If the monitor is a timekeeper monitor lt tkprmonitor gt the monID attribute is not used The timekeeper monitor does not use the id attribute as do the other state monitors An example of this invocation would be 54 lt varIn param season name month monitor tkprmonitor monType month gt lt varIn gt lt tkprmonitor attr month gt lt tkprmonitor gt 10 2 12 varOut attributes The lt varOut gt environments specify which controller is modified by which output variable in the GLPK model definition or activate a single controller for a watermover from among multiple controllers attached to a watermover Section 5 details the allowable XML entities for lt varOut gt In the case where a controller variable is to be changed the ctr1ID attribute is used to specify the controller the name defines the the output variable name from the GLPK model file and the func specifies the controller variable to be changed It is possible to have multiple lt varOut gt entries for a single controller For example a supervisor may define three lt varOut gt terms to modify the on off minimum output maximum output behaviors of a single controller Each lt var0ut gt would have a distinct func and name entry Section 2 1 describes the available func attributes for each controller When a supervisor is used to activate a particular controller from among multiple controllers attached to a
48. outputFile attributes define optionally created information files which contain plain text outputs of the GLPK problem statement GLPK solution statement and any runtime messages 10 2 3 method attribute Specification of the GLPK solution method is provided by the method at tribute which may be assigned one of the following values simplex or interior which enact either a two phase revised simplex method or a pri mal dual point interior method Interior point methods are more modern and more powerful numerical methods for large scale linear programming They work well for very sparse LP problems and can solve such problems much more efficiently than simplex methods The default is simplex 10 2 4 optimize attribute To specify the direction of the optimization the user can set the optimize attribute to either maximize or minimize The default is minimize 10 2 5 presolve attribute The simplex solver has a built in LP presolver which is a subprogram that transforms the original LP problem to an equivalent LP problem which may be easier to solve than the original problem Access to this feature is provided by the presolve attribute which may be assigned the values of on or off the default is off This option is only useful for cases where a reoptimization is performed 10 2 6 msglevel attribute The user can control the level of message reporting from the GLPK solver with the msglevel attribute The msglevel can be set to one of fou
49. ow IS one RULE 4 IF S340_Stage IS med AND season is NOT wet THEN S340_Control_trigLow IS five RULE 5 IF 5340_Stage IS high AND season is wet THEN S340_Control_trigLow IS five RULE 6 IF 5340_Stage IS high AND season is NOT wet THEN 340_Control_trigLow IS five END_RULEBLOCK END_FUNCTION_BLOCK 48 10 GNU Linear Programming Kit GLPK Super visor RSM provides an interface to the GNU Linear Programming Kit GLPK 10 The GLPK package is intended for solving large scale linear program ming LP mixed integer programming MIP and other related problems It is a set of routines written in ANSI C and organized in the form of a callable library The GLPK package includes the following main components e Revised simplex method e Primal dual interior point method e Branch and bound method e Translator for GNU MathProg e Application program interface APT e Stand alone LP MIP solver The GLPK distribution can be found in the subdirectory gnu glpk on your favorite GNU mirror 10 The GLPK documentation consists of the Reference Manual and the description of the GNU MathProg language Both these documents are included in the distribution in LaTeX DVI and PostScript formats 10 1 GLPK MathProg Language GLPK supports the GNU MathProg language which is a subset of the AMPL language AMPL is a comprehensive and powerful algebraic model ing language for linear and nonlinear optimization problems in discr
50. pervisors are interoperable and may be dynamically switched This observation forms a core motivation for design of the MSE information processing facilities as an algorithmic independent implementation In this manner maximum extensibility and flexibility is retained for the application of existing or future resource allocation or policy optimization schemes 2 Supervisory Control of Controllers The MSE supervisor is effectively a meta controller a controller of con trollers It is therefore important to understand the essential implementa tion details of the MSE controllers significantly the controllers are imple mented as flow control regulators The output of the controller is applied as an amplitude scale factor to the computed flow of the watermover The intended range of controller outputs is in the interval of 0 1 The user may define the control output range for all of the controllers except the Sigmoid controller The user is strongly cautioned that implementation of controllers with output control ranges outside of the interval 0 1 may result in un intended modulation of watermover flow values The output control value may be interpreted as a percentage of the total allowable structure flow MSE supervisors have the ability to change individual response char acteristics of the MSE controllers or in the case of multiple controllers attached to a watermover to select and activate a specific controller for a watermover The av
51. r attribute is assigned the varIn or varOut name of the corresponding variable Examples of supervisor monitors for output to dss files are shown below The first example outputs the supervisor output variable ctr1_103_TrigLow while the second entry writes the supervisor input variable segment 1Head 22 lt output gt lt spvrmonitor spvrID 801 attr output montype vector var ctrl 103 TrigLow gt lt dss file t3x30ut dss pn hse spvr801 output 15min calc1 gt lt dss gt lt spvrmonitor gt lt spvrmonitor spvrID 801 attr state montype vector var segmentiHead gt lt dss file t3x30ut dss pn hse spvr801 seg1_state 15min calc1 gt lt dss gt lt spvrmonitor gt lt output gt An example of a supervisor monitor is shown below for a User supervisor that is monitoring the output value of another supervisor lt user_supervise id 803 label user_supervisel lt varin name ctrl 101 monitor spvrmonitor monType output gt lt varIn gt lt spvrmonitor spvrID 801 attr output montype vector var ctr1_101 gt lt user_supervise gt 23 7 Supervisors General Usage The supervisors that are currently available within the MSE are e User Defined Finite State Machine section 8 e Expert System Rule Base Fuzzy section 9 e Linear Programming Optimization section 10 e Graph Flow Algorithm section 11 e ORM section 12 Each supervisor must be defined in the RSM XML input file in the
52. r defined supervisors de veloped in C if the RSM is statically linked If the RSM is dynamically linked then C user defined shared libraries are supported 30 8 7 C User Supervisor Interface If the shared library is developed in C the supervisor functions are called from the MSE with six input variables as shown in the prototype below int MySupervise int var InNum char varInNames double varInValues int varOutNum char varOutNames double varOutValues Table 8 7 C user supervisor function prototype The first argument is an integer which defines the number of input variables being passed to the function This corresponds to the number of lt varIn gt variables defined within the lt user_supervise gt section of the xml file The second argument is an array of character strings Each array element contains the name of an input variable as defined in the lt varIn name gt section of the xml file The third argument is an ar ray of floating point double values which contain the current numerical values of the state variables The array indices of the second and third arguments match on a one to one correspondence That is for the vari able with the name varInNames 2 the current state value is contained in varInValues 2 The fourth argument is the number of output variables which corre sponds to the number of lt varOut gt variables defined within the lt user supervise gt section of the x
53. r values 52 O No messages 1 Error messages only 2 Normal messages 3 All messages The default value is msglevel 1 10 2 7 timelimit attribute The timelimit attribute specifies the amount of time in seconds that the LP solution algorithm will be allowed to search for a solution The default value is 1800 seconds 10 2 8 outfreq The outfreq attribute output defines the frequency in iterations of the LP solver at which solver output information is written The default value is 200 iterations 10 2 9 days hours minutes attribute The supervisor time interval control attributes days hours minutes pro vide a mechanism to run the supervisor at selected intervals see section 1 2 10 2 10 ctrlID environment The lt ctrlID gt environment defines a list of RSM controllers that will be supervised The values in this list must match a cid attribute of a valid controller definition For example if the following controller is defined lt setpointctrl cid 125 wmID 25 label 538 Culvert gt then a valid entry in the lt ctrlID gt list is 125 Each controller id in the list will have at least one corresponding lt varOut gt entry which couples the controller modifier with a corresponding GLPK problem variable defined in the GLPK model file 53 10 2 11 varIn attributes The lt varIn gt environment defines the HSE state input variables which will be linked to GLPK parameters defined in the GLPK model file
54. riable names Fourth is the integer number of output variables fifth an array of character pointers to output variable names and finally an array of floating point double pointers each reference to an output variable with the same array index listed in the array of output variable names 7 If you compile with a C compiler declare the functions as extern C to avoid name mangling in the shared object 8 4 User Supervisor Library Compilation To convert C code into a shared object with the name UserSpvr so assuming that the function is in a file named userspvr cc the following com mand can be used in Linux gcc userspvr cc Bsymbolic shared o UserSpvr so 29 8 5 User Supervisor Initialization and Cleanup If the user desires to have a one time initialization call and one time cleanup call made to the library at the time the library is loaded and unloaded respectively the user must define two functions within the library 1 void _initQ 2 void _fini The _initO function will be called after the shared library loader suc cessfully imports the shared library and the _fini function will be called before the library is unloaded To prevent linkage conflicts with common standard library functions add the nostdlib argument to the compiler com mand gcc userspvr cc Bsymbolic shared o UserSpvr so nostdlib 8 6 User Supervisor and Statically Linked HSE The current version of RSM does not support use
55. sor is reads it s MSE Network representation from the flat file maxflow fig22 28 dat and computes a maxflow solution The second ex ample reads it s MSE Network from the XML file mse_network xml and computes a feasible flow solution lt graph supervise id 801 label graph supervise graph maxflow fig22 28 dat flow maxflow gt lt ctrlID gt 701 lt ctrlID gt lt graph supervise gt lt graph supervise id 802 label graph supervise xml mse_network xml flow feasible gt lt ctrlID gt 702 lt ctrlID gt lt graph supervise gt 61 12 Object Routing Model Assessor Supervisor The ORM supervisor is currently under development The functionality of the ORM is being decomposed into a suite of Assessors Refer to benchmark BM63 for the latest information on this development 62 References 1 User manual for the Hydrologic Simulation Engine HSE October 2003 Office of Modeling Model Development Division 4540 South Florida Water Management District 3301 Gun Club Road West Palm Beach FL Lal Wasantha Weighted implicit finite volume model for overland flow ASCE Journal of Hydraulic Eng 124 9 Sep 1998 pp 941 950 Lal Wasantha A M Van Zee Randy and Belnap Mark Case Study Model to Simulate Regional Flow in South Florida ASCE Journal of Hydraulic Engineering in publication manu script HY 2003 023398 April 2005 MSE Controllers Documentation and User Manual Office of Modeling Model De
56. structure operational behaviors e Simulate existing water resource policies Assessment of currently im plemented management operational policies in response to hydrologi cal forcing e Develop alternative resource control strategies through the optimiza tion of operational policies The first task is a critical capability for the assessment of water control operations in response to historic real time or forecast forcing conditions In this mode the MSE modifies the behavior of the controllers to achieve a predefined subregional or regional water resource allocation Elucidation of the imposed watermover flows can then be used to develop appropriate oper ational policies consistent with the available resources and desired objectives The latter facility forms an important analysis tool aimed at identification of alternative operational policies which must perform complex multi variate resource allocation functions under the control of system boundary condi tions and constraints The MSE is formulated to address both of these needs by providing a flexible extensible and interoperable suite of super visory processors such as a rule based expert system and a generic mathe matical programming language interface which provides access to a suite of state of the art optimization algorithms 1 1 RSM Architecture A schematic representation of the RSM information processing architecture is depicted in figure 1 The HSE reads boundary condi
57. t Gi R integral term gain Gd R derivative term gain Gp R proportional term gain integral R error integral type 0 or 1 negative or positive target R new target error R error integral Table 2 1 5 PID Controller Functions 2 1 6 User Controller Function XML attribute value meaning func newControl 0 or 1 reset controller module shared object name string Not Implemented func control function name string Not Implemented Table 2 1 6 User Controller Functions 2 1 7 LP Controller Function XML attribute value meaning func ControlOut R control value TargetFlow R LP desired flow cfs Table 2 1 7 LP Controller Functions 13 2 1 8 Alpha Controller Function XML attribute value meaning func fullopen R control cutoff alpha R control parameter offset R target offset nvals int no integration points target R new target Table 2 1 8 Alpha Controller Functions 2 2 Multiple Controller Selection Implementation of generic nonlinear field controllers such as those com monly employed by the District may be difficult to achieve with a single control algorithm per structure The MSE controllers therefore support the notion of controller overloading This means that more than one con troller may be attached to a watermover The intention is that separate controllers with distinct control response char
58. the control outputs are applied as amplitude modulation factors to the watermover flow the watermover flow will default to it s un controlled values The ctrlMin and ctrlMax attributes will set the minimum and max imum controller output limits The user is cautioned to exercise care in setting these values outside of the interval 0 1 11 2 1 2 Fuzzy Controller Function XML attribute value meaning func newControl 0 or 1 reset controller FCLFile string new FCL file name Not Implemented Table 2 1 2 Fuzzy Controller Functions 2 1 3 Setpoint Controller Function XML attribute value meaning func setpoint R constant setpoint setlow R low setpoint sethigh R high setpoint triglow R low trigger trighigh R high trigger window 0 1 2 outside inside all trigger orl off or on step 0 or 1 down or up Table 2 1 3 Setpoint Controller Functions 2 1 4 Sigmoid Controller Function XML attribute value meaning func offset R target offset Gi R integral term gain Gp R proportional term gain integral R error integral c R sigmoid parameter scale R output scale factor type 0 or 1 negative or positive target R new target error R error integral Table 2 1 4 Sigmoid Controller Functions 12 2 1 5 PID Controller Function XML attribute value meaning func offset R target offse
59. tion information con cerning the spatial characteristics of the model from the cell mesh 2dm canal network map and associated initial head and flow files Input in formation also may be obtained from rainfall ET or other hydrological process coverage timeseries files Based on this information HSE computes flow and water levels for each component of the model at each timestep This comprises a set of state information 2 which describes the hydrolog ical response of the system to the imposed boundary conditions and forcing functions For the purposes of water management decisions it may appropriate to process the hydrological state information 2 with a variety of filters such as spatio temporal expectations spatio temporal integration differentiation or timeseries amplitude or phase modulations These operations are performed by the Assessors and Filters Assessors are specialized data processing al gorithms suited to particular needs of water resource management such as assessing the water supply needs for a water control unit WCU Currently Assessed f X State Info Y Control Vector WaterMover Controller xorg bat E Figure 1 RSM Schematic the Assessors are still in development and are not documented Refer to the Benchmarks for the latest usage and implementations of Assessors Filters are generic data processors intended to provide common data preprocessing functions such as scalar or ti
60. uperviseOut 101 else supervise0ut 102 Set the output variable if not SetVarOut func segmenti Controller control0ut lpOutputControlMap gt status 1 return status 38 extern C double SetWMiCtrlTriggers map lt string InputState gt lpInputStateMap map lt string OutputControl gt lpOutputControlMap int status 0 double superviseOut 0 output value Get the current state value for each variable double segmentiHead GetVarIn func segmentiHead lpInputStateMap Provide control function based on input state variable W Cite controlOut 495 else if A control0ut 498 else control0ut 500 gt if not SetVarOut func ctrl 101 TrigLow control0ut IlpOutputControlMap gt Y status 1 return status 39 9 Expert System Rule Based Fuzzy Supervisor The ability to simulate application of operational rules to water control structures on a regional scale is an important requirement of the MSE This feature enables the RSM to simulate the actual operational policies in re sponse to historical real time or forecast forcing events beyond the scope of individual control structures which are acting solely to achieve a local objective Over the span of many years District personnel have amassed a large and complex knowledge base of operational control guidelines and rules Application of this knowledge in response to situational
61. value of lt var0ut name OverrideOn0ff gt evaluates to non zero This assumes that a supervisor has previously activated a controller override for this controller with the func control0ut attribute If the lt var0ut name OverrideOn0ff gt value evaluates to zero then the controller override is deactivated and the control value computed by the controller will be applied to the watermover modulation 15 2 3 1 Controller Override XML attribute value meaning func override 0 1 0 off 1 on controlOut R control value Table 2 3 1 Controller Override XML 16 3 MSE Network An important feature of the MSE in general is the usage of Assessors and the MSE Network to provide synoptic state variable inputs for the con trollers and supervisors The MSE Network is an abstraction of the canal network and water control structures based on graph theory It provides im plicit aggregation of HSE canal network segments into Water Control Units WCU s The WCU is an integrated data object which stores assessed val ues of state variables relevant to the collection of HSE segments Through the use of assessors and monitors the controllers and supervisors access this synoptic information The MSE Network also contains information rele vant to management policies of the WCU s and operational characteristics of the structure watermovers The MSE Network is fully described in the RSM Controllers Manual 4 in section MSE
62. velopment Division 4540 South Florida Water Management District 3301 Gun Club Road West Palm Beach FL The Water Resources Development Act of 2000 WRDA2000 was signed into law by the President of the United States on Dec 11 2000 Public Law No 106 541 of the 106th Congress Title VI Section 601 of the Act describes authorizations spe cific to the Comprehensive Everglades Restoration Plan see http www evergladesplan org Belaineh G Peralta R C and Hughes T C Simulation Opti mization Modeling for Water Resources Management J Water Resour Ping and Mgmt ASCE 125 3 pp 154 161 Clemmens A J and Wahlin B T Performance of various proportional integral feedback controllers for ASCE test cases Workshop on Modernization of Irrigation Water Delivery Systems Proc U S Committee on Irrigation Drainage Workshop Phoenix AZ October 17 21 1999 p510 516 Fuzzy Control Library Description and Application Programming Interface 63 10 11 12 13 14 December 10 2003 Office of Modeling Model Development Division 4540 South Florida Water Management District International Electrotechnical Commission IEC Technical Committee No 65 Industrial Process Measurement and Control Sub committee 65B Devices IEC 1131 Programmable Controllers Part 7 Fuzzy Control Programming GNU Linear Programming Kit GLPK Version 4 2 November 2003 http www gnu org software glpk glpk html http
63. y share the same MSE Network representation As a result a graph supervisor can solve the flow for the entire network or for any subset of the network for which a graph has been defined 59 11 1 Graph Flow Supervisor XML XML attributes available for the Graph flow supervisor are shown in Ta ble 11 1 environment attribute meaning lt graph supervise gt id supervisor id label optional supervisor label xml MSE Network XML file graph MSE Network flat file flow flow solution type days supervise interval in days hours supervise interval in hours minutes supervise interval in minutes lt ctrlID gt list of controller IDs Table 11 1 Graph Flow XML 11 1 1 graph supervise attributes The id is a unique supervisor identifier label is an optional string which will label the outputs of the supervisor The xml attribute can specify a valid MSE Network XML file refer to the MSE Network XML section of the Controllers Manual Alternatively the graph attribute can define a flat file MSE Network representation see the MSE Network Flat File sec tion of the Controllers Manual The flow attribute can be set to feasible or maxflow the default The supervisor time interval control attributes days hours minutes provide a mechanism to run the supervisor at se lected intervals see section 7 2 60 11 2 Graph Supervise Example An example XML entry for two graph supervisors is shown below The first supervi

MSE Supervisor User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents