OpenMI Developers Training

1. OpenMI Developers Training Jan Gregersen http://www.LicTek.com Jan Gregersen 1

2. Simple River Runoff Model Simple River OutputExchangeItem InputExchangeItem Quantity ID : Runoff Quantity ID : Inflow DataOperaiton : Distributed ElementSet : Polygons ElementSet : Polyline Y (km) 5 10 Y (km) 10 10 Node:0 Branch:0 Node:1 5 5 Branch:1 Node:2 Branch:2 Node:3 X (km) X (km) 5 10 Jan Gregersen 2

3. How it works Load components: Query exchange items: Add links: Jan Gregersen 3

4. How it works Prepare: Run (GetValues): Finish: Jan Gregersen 4

5. The OpenMI standard DHI - Water & Environment Jan Gregersen

6. Jan Gregersen 6

7. Migration of models DHI - Water & Environment Jan Gregersen

8. Now What ??? Jan Gregersen 8

9. Org.OpenMI.Utilities Org.OpenMI.Utilities.Buffer Buffers results from the engine core SmartBuffer Mapping of values associated to one array of times /timespans to values represented on another array of times/timespans t t Org.OpenMI.Utilities.Spatial Mapping of values associated to ElementMapper one ElementSet to be represented on another ElementSet Org.OpenMI.Utilities.Wrapper Generic wrapper suited for time SmartWrapper stepping model engines Jan Gregersen 9

10. LinkableEngine features • Provides a default implementation of the ILinkableComponent interface • Links bookkeeping • Event handling • Buffering • Temporal interpolations, aggregations, extrapolations • Spatial interpolations, aggregations, extrapolations Jan Gregersen 10

11. Wrapper design pattern Jan Gregersen 11

12. IEngine Interface // -- Execution control methods (Inherited from IRunEngine) -- void Initialize(Hashtable properties); bool PerformTimeStep(); void Finish(); //-- Time methods (Inherited from IRunEngine) -- ITime GetCurrentTime(); ITime GetInputTime(string QuantityID, string ElementSetID); ITimeStamp GetEarliestNeededTime(); //-- Data access methods (Inherited from IRunEngine) -- void SetValues(string QuantityID, string ElementSetID, IValueSet values); IValueSet GetValues(string QuantityID, string ElementSetID); //-- Component description methods (Inherited from IRunEngine) -- double GetMissingValueDefinition(); string GetComponentID(); string GetComponentDescription(); // -- Model description methods -- string GetModelID(); string GetModelDescription(); double GetTimeHorizon(); // -- Exchange items -- int GetInputExchangeItemCount(); int GetOutputExchangeItemCount(); org.OpenMI.Backbone GetInputExchangeItem(int exchangeItemIndex); org.OpenMI.Backbone GetOutputExchangeItem(int exchangeItemIndex); Jan Gregersen 12

13. Inside the LinkableEngine has SmartWrapper has SmartInputLinkSet SmartOutputLinkSet UpdateInput() UpdateBuffer() 1 GetValues() access has Link access 1 Link has * * SmartInputLink SmartOutputLink UpdateInput() has UpdateBuffer() GetValues() has SmartBuffer ElementMapper Jan Gregersen 13

14. GetValues() Model B Model A GetValues(time, LinkID) GetValues(time, LinkID) 1. Update with input from linked models 2. Perform time step and fill internal buffers While (CurrentTime < time & State is “Not Busy”) 3. Map values in time and space Return values Jan Gregersen 14

16. GetValues() Engine Smart A Smart A Smart A Smart A Smart Model B Model A AIP Output Output Element InputLink Input Buffer Access LInkSet LInk Mapper Set Link GetValues(tl LinkID) GetCurrentTime() IsBusy = true UpdateInput(ct) UpdateInput(ct) GetValues(ct,LinkID) SetValues(Quantity,LocationID,Values) For each Input Link Jan Gregersen 16

18. GetValues() Engine Smart A Smart A Smart A Smart A Smart Model B Model A AIP Output Output Element InputLink Input Buffer Access LInkSet LInk Mapper Set Link PerformTimeStep() UpdateBuffers() UpdateBuffer() Getvalues(Quantity,LocationIDs) Addvalues(time, valueSet) For each output link IsBusy = false Jan Gregersen 18

20. GetValues() Engine Smart A Smart A Smart A Smart A Smart Model B Model A AIP Output Output Element InputLink Input Buffer Access LInkSet LInk Mapper Set Link GetValues(time, LinkID) GetValues(time) GetValues(time) MapValues(inpuValues) Jan Gregersen 20

21. IEngine Interface // -- Execution control methods (Inherited from IRunEngine) -- void Initialize(Hashtable properties); bool PerformTimeStep(); void Finish(); //-- Time methods (Inherited from IRunEngine) -- ITime GetCurrentTime(); ITime GetInputTime(string QuantityID, string ElementSetID); ITimeStamp GetEarliestNeededTime(); //-- Data access methods (Inherited from IRunEngine) -- void SetValues(string QuantityID, string ElementSetID, IValueSet values); IValueSet GetValues(string QuantityID, string ElementSetID); //-- Component description methods (Inherited from IRunEngine) -- double GetMissingValueDefinition(); string GetComponentID(); string GetComponentDescription(); // -- Model description methods -- string GetModelID(); string GetModelDescription(); double GetTimeHorizon(); // -- Exchange items -- int GetInputExchangeItemCount(); int GetOutputExchangeItemCount(); org.OpenMI.Backbone GetInputExchangeItem(int exchangeItemIndex); org.OpenMI.Backbone GetOutputExchangeItem(int exchangeItemIndex); Jan Gregersen 21

23. Migration steps • Change your engine to a dll • Implement Initialize, PerformTimeStep and Finish • Create the EngineDllWrapper class Jan Gregersen 23

25. Migration steps • Create your MyEnigneWrapper • Implement Initialize and Finish • Implement remaining Ienigne methods Jan Gregersen 25

26. Jan Gregersen 26

27. The ElementMapper Ground water River Model Model GetValues(time, link) Calculate Return values Has Link Has ElementSet Quantity “GW Recharge” Jan Gregersen 27

28. Spatial mapping Jan Gregersen 28

29. ElementMapper Org.OpenMI.Utilties.Spatial ElementMapper Initialise(string methodDescription, IElementSet fromElements, IElementSet toElements) IValueSet MapValues(IValueSet inputValues)  r1   m11 m12 m13 . m1n  x1        r2   m21 m22 m23 . m2 n  x2  r m m32 m33 . m3n  x3   3   31    .  . . . . .  .  r  m mmn  xn   m   m1 mm 2 mm3 .   Jan Gregersen 29

30. Element Mapping RE1  1 1/ 3 0    RE1  0 2 / 3 1/ 2 GE1 GE2 A 0  RE3 0 0    0 0 1/ 2 GE3 GE4   I  L A Jan Gregersen 30

31. Element • ID Based “Node127” • Point (x1,y1) • Line (x1,y1) (x2,y2) • Polyline (x1,y1) (x2,y2) (x3,y3) (x4,y4) (x1,y1) (x5,y5) • Polygon (x4,y4) (x2,y2) (x3,y3)

32. ElementSet example H Q H H Q Q H Q H H Q Q H H Q Q H Q H Q H Q H

33. Quantity • ID ( “Runoff” ) • Description ( “Rainfall runoff” ) • Dimension ( e.g. L3 T-1 ) – GetPower ( <dimensionBase> ) • Unit: – ID ( “CFS” ) – Descr ( “Cubic feet per second “ ) – ConversionFactorToSI ( 0,0283168439 ) – OffsetToSI ( 0 )

34. ExchangeItem • InputExchangeItem – Quantity – ElementSet • OutputExchangeItem – Quantity – ElementSet – [ DataOperations • ID • Arguments ]

35. Unidirectional link « t rae in f c» e « t rae in f c» e Re oe: ivr dl M Rm e: Ro l d M Pg m a r r in o a I in b C pnn L k le o oet a m I in b C pnn L k le o oet a m GVlusim t ,lin D r gr in e a e t e 1 k = ige k t ( = I T L ) [] 1 [] 2 GVlusim R t e _t lin D RRe e a e t e M + d k = t ivr t ( = im , I Ro ) Pro T e t p e r im e f m S [] 3 r t r VluSt R o e n a ee u f u : nf { h Rt e Rt e _t w ile Rim< M + d im } Pro T e t p e r im e f m S { h Rt e t } w ile M <1 im r t r VluSt Re lo e n a e e ivr w u : F

36. Bidirectional links «interface» «interface» RiverModel : GroundW aterModel : MainProgram ILinkableComponent ILinkableComponent GetValues(t2,TriggerLink) [1] GetValues(time=t1, linkID=QtoRiver) [2] GetValues(time=t2, linkID=HtoGW) [3] Extrapolate (t2) [4] return extrapolated ValueSet: HtoGW (t2) PerformTimeStep (t2) [5] return interpolated ValueSet QtoRiver (t1) PerformTimeStep (t1) [6] GetValues(time=t2, linkID=QtoRiver) [7] return ValueSet QtoRiver (t2) PerformTimeStep (t2) return ValueSet Hriver (t2) RiverModel us time s es tep t1, GroundwaterModel us time s es tep t2

37. IterationController «interface» «interface» : RiverM odel : GroundWaterM odel : ILinkableCom ponent ILinkableCom ponent ILinkableCom ponent M ainProgram GetValues(tim e=t2, linkID=H_SW) KeepCurrentState [1] RiverState_t_begin KeepCurrentState GWState_t_begin [2] InitialGuess(QtoGW) RestoreState(RiverState_t_begin) [3] RestoreState(GWState_t_begin) [4] GetValues(tim e=t2, linkID=H_GW) GetValues(time=t2, linkID=QtoGW) QtoGW_guess H_GW [5] GetValues(tim e=t2, linkID=H_SW) GetValues(tim e=t2, linkID=QtoGW) QtoGW_guess H_SW Evaluate [6] NewGuess(QtoGW) {untill QtoGW is stabilized} result: H_SW [7]

38. «interface» «interface» RiverModel : RR model : MainProgram ILinkableComponent ILinkableComponent User : IListener Start GetValues(time=t1,TriggerLinkID) [1] OnEvent(SourceAfterGetValuesCall) return computation thread GetValues(time=t1,linkID=QtoRiver) [2] OnEvent(SourceAfterGetValuesCall) return computation thread PerformTimeStep((_dt)) [3] OnEvent(DataChanged) return computation thread OnEvent(SourceBeforeGetValuesReturn) {until RRtime=t1} Pause [4] Resume [5] return computation thread return ValueSet(QtoRiver, t1) OnEvent(TargetAfterGetValuesReturn) [6] return computation thread PerformTimeStep(RM_dt) OnEvent(DataChanged) [7] OnEvent(SourceBeforeGetValuesReturn) return computation thead [8] return ValueSet(t1)

39. Persistency • OMI File – For identifying a linkable component • Composition – In org.OpenMI.Utilities.Configuration – Holds administration of links and linkable components – Can be run – Can be written and read to / from xml

40. Exercise 9: Unit Conversion Step 1 Open the DataCombinator Step 2 Adjust the code of GetValues so that it delivers data in the right unit Step 3 Adjust the test program to ask for a quantity which has a conversion factor not equal to one Step 4 Identify a value as missing value (e.g. -999) and adjust the input. Make sure this value is processed correctly. Step 5 Test the program using NUnit