Tutorial Advanced Users

From ILMS-Wiki
(Difference between revisions)
Jump to: navigation, search
(Modellvalidierung und Parameteroptimierung)
(JUICE - Jams User Interface Component Editor)
 
(32 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=JUICE - Jams User Interface Component Editor=
+
[[de:Tutorium_Fortgeschrittene_Anwender]]
 +
[[pt:Tutorial_para_Usuários_Avançados]]
 +
=JUICE - Jams Model Editor=
  
 
The JAMS Builder (JUICE) was developed in order to set up and/or configure environmental models. By using JUICE any models can be combined and configured by the "module principle". For this purpose, there are two types of "modules" available. On the one hand, those are components which describe the individual processes. On the other hand, there are context components which control the model run. For the data exchange between components and contexts attributes are needed. Those can be variables but also parameters.
 
The JAMS Builder (JUICE) was developed in order to set up and/or configure environmental models. By using JUICE any models can be combined and configured by the "module principle". For this purpose, there are two types of "modules" available. On the one hand, those are components which describe the individual processes. On the other hand, there are context components which control the model run. For the data exchange between components and contexts attributes are needed. Those can be variables but also parameters.
Line 10: Line 12:
  
  
[[Bild:1.JUICE1_en.jpg]]
+
[[File:1.JUICE1_en.jpg]]
  
 
====Structure of the Menu Bar====
 
====Structure of the Menu Bar====
  
[[Bild:JUICE1_en.jpg]]
+
[[File:JUICE1_en.jpg]]
  
The menu bar contains the items '''File''', '''Edit''', '''Model''', '''Logs''', '''Window''' and '''Help'''. In addition, the following functions are integrated in the form of icons:
+
The menu bar contains the items '''File''', '''Edit''', '''Model''', '''Logs''', '''Windows''' and '''Help'''. In addition, the following functions are integrated in the form of icons:
  
  
Line 52: Line 54:
 
Under the menu item '''File''' models can be loaded, saved and closed.
 
Under the menu item '''File''' models can be loaded, saved and closed.
  
[[Bild:JUICE_File_en.jpg]]
+
[[File:JUICE_File_en.jpg]]
  
 
The menu item '''Edit''' allows to edit, load or save settings and offers a search function.
 
The menu item '''Edit''' allows to edit, load or save settings and offers a search function.
  
[[Bild:JUICE_Edit_en.jpg]]
+
[[File:JUICE_Edit_en.jpg]]
  
Under the item ''Edit settings'' you can edit the libraries which are used, the extent of the output, the output of logs and information on the model window. Those settings can be saved for subsequent modeling under the item ''Save settings'' and they can be reused by clicking on ''Load settings''.
+
Under the item ''Edit Preferences'' you can edit the libraries which are used, the extent of the output, the output of logs and information on the model window. Those settings can be saved for subsequent modeling under the item ''Save Preferences'' and they can be reused by clicking on ''Load Preferences''.
  
 
The menu item '''Model''' is only activated when a model has been loaded. It can start or configure the model. Moreover, the [[Tutorial Basic Users|JAMS Explorer]] is linked which is used for analyzing used input data and results of the modeling. Its scope of services is explained in detail in the Tutorial Basic User.  
 
The menu item '''Model''' is only activated when a model has been loaded. It can start or configure the model. Moreover, the [[Tutorial Basic Users|JAMS Explorer]] is linked which is used for analyzing used input data and results of the modeling. Its scope of services is explained in detail in the Tutorial Basic User.  
 
Loading and saving parameter sets can be done by using ''Load Model Parameters'' and ''Save Model Parameters''. In addition, the model can be started by using the [[Tutorial Basic Users|JAMS Launcher]].
 
Loading and saving parameter sets can be done by using ''Load Model Parameters'' and ''Save Model Parameters''. In addition, the model can be started by using the [[Tutorial Basic Users|JAMS Launcher]].
The ''Optimization Assistant'' serves as a platform for automatic parameter optimization.
+
The ''Optimization Wizard'' serves as a platform for automatic parameter optimization.
  
[[Bild:JUICE_model_en.jpg]]
+
[[File:JUICE_model_en.jpg]]
  
 
Under the menu item '''Logs''' the '''Info Log''' can be shown. It contains information about the model's author, its version and user and also about the model's efficiency (How well displayed are the measured values in the model?), the model's structure (Which components were used how often?) and the time of the modeling. The ''Error Log'' shows errors which may have occurred.
 
Under the menu item '''Logs''' the '''Info Log''' can be shown. It contains information about the model's author, its version and user and also about the model's efficiency (How well displayed are the measured values in the model?), the model's structure (Which components were used how often?) and the time of the modeling. The ''Error Log'' shows errors which may have occurred.
  
[[Bild:JUICE_Logs_en.jpg]]
+
[[File:JUICE_Logs_en.jpg]]
  
The menu item '''Window''' lists all windows which are currently open.
+
The menu item '''Windows''' lists all windows which are currently open.
  
 
Under the menu item '''Help''' you can obtain online help by clicking on ''JAMS online''.
 
Under the menu item '''Help''' you can obtain online help by clicking on ''JAMS online''.
  
[[Bild:Systemleiste_Help_en.jpg]]
+
[[File:Systemleiste_Help_en.jpg]]
  
 
==Application of JUICE for Model Design and Model Configuration==
 
==Application of JUICE for Model Design and Model Configuration==
Line 86: Line 88:
  
  
[[Bild:JUICE_NewModel_Step1_en.jpg]]
+
[[File:JUICE_NewModel_Step1_en.jpg]]
  
  
Line 94: Line 96:
 
Click on the library jams-main.jar which is listed in the top left window. There you will find the JAMSTemporalContext under jams.model. Drag it to the right window into the "New Model".
 
Click on the library jams-main.jar which is listed in the top left window. There you will find the JAMSTemporalContext under jams.model. Drag it to the right window into the "New Model".
  
[[Bild:JUICE_TemporalContext_Step2_en.jpg]]
+
[[File:JUICE_TemporalContext_Step2_en.jpg]]
  
 
Create the context attribute '''modelTimeIntervall''' within the model. Click on '''Component Attributes''' in the '''Attribute List''' under the item '''New Model'''.
 
Create the context attribute '''modelTimeIntervall''' within the model. Click on '''Component Attributes''' in the '''Attribute List''' under the item '''New Model'''.
Line 100: Line 102:
 
Click on '''Add'''. Take '''modelTimeIntervall''' as name. Select '''TimeInterval''' as attribute type. You have to determine a time span for the simulation. (Note that data for the selected time span have to be available.) Take 01.01.1970 to 01.01.1975 as time span. Select '''Month''' as temporal unit. Then click on '''SET'''. The attribute modelTimeIntervall is now linked to the time interval you selected.
 
Click on '''Add'''. Take '''modelTimeIntervall''' as name. Select '''TimeInterval''' as attribute type. You have to determine a time span for the simulation. (Note that data for the selected time span have to be available.) Take 01.01.1970 to 01.01.1975 as time span. Select '''Month''' as temporal unit. Then click on '''SET'''. The attribute modelTimeIntervall is now linked to the time interval you selected.
  
[[Bild:JUICE_TimeInterval_Step3_en.jpg]]
+
[[File:JUICE_TimeInterval_Step3_en.jpg]]
  
 
Go to component JAMSTemporalContext. Link the component attribute '''timeInterval''' to the model attribute '''modelTimeIntervall''' which has already been created. Select it from the attribute list in the bottom right box. Click on '''LINK'''.
 
Go to component JAMSTemporalContext. Link the component attribute '''timeInterval''' to the model attribute '''modelTimeIntervall''' which has already been created. Select it from the attribute list in the bottom right box. Click on '''LINK'''.
  
[[Bild:JUICE_NeuesModell_Step4_en.jpg]]
+
[[File:JUICE_NeuesModell_Step4_en.jpg]]
  
 
Create a new attribute '''time''' and link it to the component attribute '''current'''.
 
Create a new attribute '''time''' and link it to the component attribute '''current'''.
  
[[Bild:JUICE_NeuesModell_Step5_en.jpg]]
+
[[File:JUICE_NeuesModell_Step5_en.jpg]]
  
 
'''Step 3'''
 
'''Step 3'''
  
Add the component '''ABCDataReader''' to the model. You can find it in the library jams-democomponents.jar in the folder jams.components.demo.abc. The component ABCDataReader allows reading data. It reads the date and values for precipitation and runoff from a text file.
+
Add the component '''ABCDataReader''' to the model. You can find it in the library jams-democomponents.jar in the folder jams.components.demo.abc. The component ABCDataReader allows reading data. It reads the date and values for precipitation and runoff from a text file. This text file can be downloaded here: [[File:abc.txt]]
  
[[Bild:JUICE_ABCDataReader_Step6_en.jpg]]
+
[[File:JUICE_ABCDataReader_Step6_en.jpg]]
  
 
The location of the data file has to be transferred to the component attribute '''fileName'''. For this reason, you have to enter the file path of your data file as '''value''' of the attribute fileName. Click on  '''SET'''.
 
The location of the data file has to be transferred to the component attribute '''fileName'''. For this reason, you have to enter the file path of your data file as '''value''' of the attribute fileName. Click on  '''SET'''.
Line 121: Line 123:
 
Select the component attribute precip. It should be shaded in BLUE now. Enter the name '''precip''' into the box '''Modified Attribute'''. Click on '''LINK'''. The context attribute '''precip''' from the context '''JAMSTemporalContext''' has been created and linked.
 
Select the component attribute precip. It should be shaded in BLUE now. Enter the name '''precip''' into the box '''Modified Attribute'''. Click on '''LINK'''. The context attribute '''precip''' from the context '''JAMSTemporalContext''' has been created and linked.
  
[[Bild:JUICE_NeuesModell_Step8_en.jpg]]
+
[[File:JUICE_NeuesModell_Step8_en.jpg]]
  
  
Line 127: Line 129:
 
Click on '''LINK'''. The context attribute '''obsQ''' from the context '''JAMSTemporalContext''' has been created and linked.
 
Click on '''LINK'''. The context attribute '''obsQ''' from the context '''JAMSTemporalContext''' has been created and linked.
  
[[Bild:JUICE_NeuesModell_Step9_en.jpg]]
+
[[File:JUICE_NeuesModell_Step9_en.jpg]]
  
 
'''Step 4'''
 
'''Step 4'''
Line 135: Line 137:
  
  
[[Bild:JUICE_NeuesModell_Step10_en.jpg]]
+
[[File:JUICE_NeuesModell_Step10_en.jpg]]
  
 
Link the precipitation data to the component. Select the component attribute '''precip'''. Select '''precip''' for the box '''Modified Attribute''' from the list of attributes which are already in the JAMSTemporalContext. Click on '''LINK'''.
 
Link the precipitation data to the component. Select the component attribute '''precip'''. Select '''precip''' for the box '''Modified Attribute''' from the list of attributes which are already in the JAMSTemporalContext. Click on '''LINK'''.
 
Create new attributes for the water storage (storage) and the simulated runoff (simQ) as desribed in Step 3. The following window should appear:
 
Create new attributes for the water storage (storage) and the simulated runoff (simQ) as desribed in Step 3. The following window should appear:
  
[[Bild:JUICE_NeuesModell_Step11_en.jpg]]
+
[[File:JUICE_NeuesModell_Step11_en.jpg]]
  
 
The component attributes a,b,c and initStorage allow the parameterization of the component. Assign the following values: a=0.2, b=0.2, c=0.75 and initstorage=50.
 
The component attributes a,b,c and initStorage allow the parameterization of the component. Assign the following values: a=0.2, b=0.2, c=0.75 and initstorage=50.
  
[[Bild:JUICE_NeuesModell_Step12_en.jpg]]
+
[[File:JUICE_NeuesModell_Step12_en.jpg]]
  
 
'''Step 5'''
 
'''Step 5'''
Line 150: Line 152:
 
For the visualization of results you need the component '''TSPlot'''. Add this component to the model. You will find it in the libary jams-components.jar in the folder jams.components.gui.
 
For the visualization of results you need the component '''TSPlot'''. Add this component to the model. You will find it in the libary jams-components.jar in the folder jams.components.gui.
  
[[Bild:JUICE_NeuesModell_Step13_en.jpg]]
+
[[File:JUICE_NeuesModell_Step13_en.jpg]]
  
 
Link the component attribute '''time''' to the attribute time from the context '''New Model'''. Select the component attribute '''time'''. Select the context '''New Model''' from the bottom right box and select the attribute '''time'''. Click on '''LINK'''.
 
Link the component attribute '''time''' to the attribute time from the context '''New Model'''. Select the component attribute '''time'''. Select the context '''New Model''' from the bottom right box and select the attribute '''time'''. Click on '''LINK'''.
Line 156: Line 158:
 
The following window should appear:
 
The following window should appear:
  
[[Bild:JUICE_NeuesModell_Step14_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_en.jpg]]
  
 
'''Step 6'''
 
'''Step 6'''
Line 162: Line 164:
 
Now a model surface is to be created for the ABC model. Go to view '''GUI Builder'''.  
 
Now a model surface is to be created for the ABC model. Go to view '''GUI Builder'''.  
  
[[Bild:JUICE_NeuesModell_Step14_1_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_1_en.jpg]]
  
The attributes '''a''','''b''', and '''c''' are to be edited on the model's surface. In order to do that, create a '''add group''' with the nam "ABC model". By clicking on the button '''Add Property''' one box has to be created for each attribute. Note that the attribute has to be linked to the right component. In addition, the range of values can be defined by an upper and a lower boundary for the attribute. For example, the entries for parameter '''a''' in the parameter editor look like this:
+
The attributes '''a''','''b''', and '''c''' are to be edited on the model's surface. In order to do that, create a new group clicking on '''add Group''' and give it the name "ABC model". By clicking on the button '''Add Property''' one box has to be created for each attribute. Note that the attribute has to be linked to the right component. In addition, the range of values can be defined by an upper and a lower boundary for the attribute. For example, the entries for parameter '''a''' in the parameter editor look like this:
  
  
[[Bild:JUICE_NeuesModell_Step14_2_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_2_en.jpg]]
  
 
The group '''ABC Model''' is now finished and should look like this:
 
The group '''ABC Model''' is now finished and should look like this:
  
[[Bild:JUICE_NeuesModell_Step14_3_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_3_en.jpg]]
  
Moreover, the display of results of the modeling in terms of color should be adjustable in the diagram. Therefore, create a '''Add Group''' named "diagram". Create editors for the attributes '''colorLeft''' and '''colorRight'''. Name them '''colors left''' and '''colors right''' and link the created attributes to the attributes of the component TSPlot.
+
Moreover, the display of results of the modeling in terms of color should be adjustable in the diagram. Therefore, create a new group clicking on '''Add Group''' and name it "diagram". Create editors for the attribute '''colorLeft'''. Name it '''colors left''' and link the created attributes to the attributes of the component TSPlot.
  
 
The group '''diagram''' is now finished and should look like this:
 
The group '''diagram''' is now finished and should look like this:
  
[[Bild:JUICE_NeuesModell_Step14_4_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_4_en.jpg]]
  
Go to '''Component attributes'''. To change the colors of the runoff plot link '''blue;red''' in the value field.  
+
In order to link the colors of the outflow curves, go to TSplot component configuration. In the field '''colorleft''' enter the value '''blue;red'''. Doing so, the colors can be changed later during model runtime.  
  
[[Bild:JUICE_NeuesModell_Step14_4_1_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_4_1_en.jpg]]
  
  
Line 190: Line 192:
 
The model is finished. Now you can launch it directly by using the JUICE or by using the JAMSLauncher. If you launch it via the JAMSLauncher, you can edit all attributes which have been linked to the model's surface..  
 
The model is finished. Now you can launch it directly by using the JUICE or by using the JAMSLauncher. If you launch it via the JAMSLauncher, you can edit all attributes which have been linked to the model's surface..  
  
[[Bild:JUICE_NeuesModell_Step14_5_en.jpg]]
+
[[File:JUICE_NeuesModell_Step14_5_en.jpg]]
  
  
 
The following output window appears. The measured runoff is displayed in blue, the simulated runoff in red.
 
The following output window appears. The measured runoff is displayed in blue, the simulated runoff in red.
  
[[Bild:JUICE_NeuesModell_Schritt15.jpg]]
+
[[File:JUICE_NeuesModell_Schritt15.jpg]]
  
 
===Configuring Model Components===
 
===Configuring Model Components===
Line 206: Line 208:
 
In the created model no parameter values for component attributes were defined. As a result, default values were assumed for the various parameters. Of course they can be modified in order to make the resulting diagram, which visualizes the results of the modeling, more attractive.  
 
In the created model no parameter values for component attributes were defined. As a result, default values were assumed for the various parameters. Of course they can be modified in order to make the resulting diagram, which visualizes the results of the modeling, more attractive.  
  
[[Bild:JUICE_Modifizieren_Step1_en.jpg]]
+
[[File:JUICE_Modifizieren_Step1_en.jpg]]
  
 
We set the following values for the modification:
 
We set the following values for the modification:
Line 225: Line 227:
 
Overview of new attributes:
 
Overview of new attributes:
  
[[Bild:JUICE_Modifizieren_Step2_en.jpg]]
+
[[File:JUICE_Modifizieren_Step2_en.jpg]]
  
 
The following graph results from the modification:
 
The following graph results from the modification:
  
[[Bild:JUICE_Modifizieren_Schritt3.jpg]]
+
[[File:JUICE_Modifizieren_Schritt3.jpg]]
  
 
===Exchanging Components===
 
===Exchanging Components===
Line 243: Line 245:
 
Load the model '''j2k_gehlberg.jam''' from the example data sets which were made available when downloading the software. Clicking on the component '''CalcPotentialET''' of the '''HRULoop''' creates the following image. Delete the component '''CalcPotentialET''' in order to integrate another evaporation component into the model. Right-click on the component and select '''delete'''.
 
Load the model '''j2k_gehlberg.jam''' from the example data sets which were made available when downloading the software. Clicking on the component '''CalcPotentialET''' of the '''HRULoop''' creates the following image. Delete the component '''CalcPotentialET''' in order to integrate another evaporation component into the model. Right-click on the component and select '''delete'''.
  
[[Bild:JUICE_Austauschen_Step2_en.jpg]]
+
[[File:JUICE_Austauschen_Step2_en.jpg]]
  
 
'''''Step 3: Add New Component'''''
 
'''''Step 3: Add New Component'''''
  
In the library library J2K.jar in the folder org.unijena.j2k.potET you will find the component '''Penman'''. Drag it to the position of the former component CalcPotentialET.
+
In the library J2K.jar in the folder org.unijena.j2k.potET you will find the component '''Penman'''. Drag it to the position of the former component CalcPotentialET.
  
[[Bild:JUICE_Austauschen_Step3_en.jpg]]
+
[[File:JUICE_Austauschen_Step3_en.jpg]]
  
 
'''''Step 4: Parameterization'''''
 
'''''Step 4: Parameterization'''''
Line 255: Line 257:
 
Assign the value '''d''' to the attribute '''tempRes''' and the value '''1.2''' to the attribute '''et_cal'''.
 
Assign the value '''d''' to the attribute '''tempRes''' and the value '''1.2''' to the attribute '''et_cal'''.
  
[[Bild:JUICE_Austauschen_Step4_en.jpg]]
+
[[File:JUICE_Austauschen_Step4_en.jpg]]
 
   
 
   
 
'''''Step 5: Link Context Attributes'''''
 
'''''Step 5: Link Context Attributes'''''
Line 261: Line 263:
 
Link the context attributes '''wind''','''tmean''','''rhum''','''netRad''','''elevation''','''area''','''potET''' and '''actET''' to the corresponding context attributes of the HRULoop (interaction across all spatial units).
 
Link the context attributes '''wind''','''tmean''','''rhum''','''netRad''','''elevation''','''area''','''potET''' and '''actET''' to the corresponding context attributes of the HRULoop (interaction across all spatial units).
  
[[Bild:JUICE_Austauschen_Step5_en.jpg]]
+
[[File:JUICE_Austauschen_Step5_en.jpg]]
  
The former component which is used for calculating potential evaporation (CalcPotentialET) created the attributes '''rs''' and '''ra'''. Those attributes were weighted and summarized in the component '''SpatialWeightedSumAggregator1'''. Since the new component does not create these attributes, they have to be deleted from links in the component '''SpatialWeightedSumAggregator1'''.
+
The former component which is used for calculating potential evaporation (CalcPotentialET) created the attributes '''rs''' and '''ra'''. Those attributes were summarized according to their importance in the component '''SpatialWeightedSumAggregator1'''. Since the new component does not create these attributes, they have to be deleted from links in the component '''SpatialWeightedSumAggregator1'''.
  
Select the component '''SpatialWeightedSumAggregator1''' and delete the links of the component attribute'''value ''' with the context attributes '''rs ''' and '''ra ''' by deleting these attribute from the box '''Modified Attribute''' and then linking them again.
+
Select the component '''SpatialWeightedSumAggregator1''' and delete the links of the component attribute '''value ''' with the context attributes '''rs ''' and '''ra ''' by deleting these attribute from the box '''Modified Attribute''' and then linking them again.
  
[[Bild:JUICE_Austauschen_Step6_en.jpg]]
+
[[File:JUICE_Austauschen_Step6_en.jpg]]
  
 
Start the new model.
 
Start the new model.
 
The following image shows you the graph resulting from the modeling:
 
The following image shows you the graph resulting from the modeling:
  
[[Bild:JUICE_Austauschen_Schritt7.jpg]]
+
[[File:JUICE_Austauschen_Schritt7.jpg]]
  
===Solution potential conflicts and interactions===
+
==Generating a Model Documentation==
 +
(Hydrological) Models consist of various model components. In order to document your model in terms of its scientific basis as well as its software realization you have the JAMS-Doc software tool at your disposal which has been integrated into JUICE. Its functioning is described in detail in the [[Tutorial_Model_Documentation|Tutorial Model Documentation]].
  
===Model Validation and Parameter Optimization===
+
==Model Validation and Parameter Optimization==
 +
In order to apply hydrological models successfully it is necessary to define model parameters accurately. A direct measurement of the parameters is mostly not possible, too expensive or there is no clear physical relation. For those reasons the parameters are adjusted in a trial and error process in so far that the simulated factors (e.g. runoff) correspond best to the values measured. This task can be time-consuming and difficult if the corresponding model is complex or has a large number of parameters. Therefore it makes sense to automatize the optimization process with a software tool for the optimization of model parameters and sensitivity analysis which is available.
 +
The model validation serves to check the suitability of a model for a specific purpose which was intended (Bratley et al. 1987) and is an important tool for quality assurance. A model is useful for an application if the simulation is reliable with regard to real processes (Power 1993). Subject to the purpose and type of the model different key figures and proof are required to validate the model.
 +
Its functionality is described in detail in the [[Tutorial_Calibration|Tutorial Calibration and Sensitivity Analysis]].
  
=Debugging und Laufzeitanalysen mit Hilfe von Inspektionskomponenten=
+
=Debugging and Runtime Analyses Using Inspection Components=
  
===Die Ping-Komponente===
+
===The Ping Component===
  
Um die Arbeitsweise Ihres Modells nachzuvollziehen, steht Ihnen eine Komponente namens '''Ping''' zur Verfügung. Diese kann an jede beliebige Stelle des Modells eingebaut werden und gibt ein Signal (Ping) wenn sie durchlaufen wird im Infoprotokoll zum Modelllauf. Weiterhin zeigt die Komponente '''Ping'''
+
In order to reconstruct the processing of your model, a component called '''Ping''' is at your disposal. It can be integrated into the model at every possible position and it makes a signal (ping) in the information log for the model runtime when it starts running. In addition, the '''Ping''' component shows how many times a component (e.g. within a temporal iteration - modeling during a few days - or within a spatial iteration - modeling within various spatial entities) has been recalled.
an, zum wievielten Mal eine Komponente (z.B. innerhalb einer zeitlichen Iteration (Modellierung über meherere Tage) oder innerhalb einer räumlichen Iteration (Modellierung innerhalb verschiedener räumlicher Einheiten)) aufgerufen worden ist.
+
  
Im folgenden wurde die '''Ping-Komponente''' in das ABC-Modell integriert, welches in Punkt '''1.2.1 - Aufsetzten''' eines Modells erstellt worden ist. Die Komponente ist in Ordner '''jams-components''' unter '''jams.components.debug''' zu finden.
+
Below the '''Ping Component''' has been integrated into the ABC model which has been established in section '''1.2.1 - Setting up a Model'''. The component can be found in folder '''jams-components''' in '''jams.components.debug'''.
  
[[Bild:JUICE_Ping.png]]
+
[[File:JUICE_Ping.png]]
  
Nach der Modellierung ist die folgende Ausgabe im Infoprotokoll zu finden. Dieses ist im JUICE unter dem Menüpunkt Protokolle einzusehen. Hierbei muss darauf geachtet werden, dass unter dem Menüpunkte '''Bearbeiten/Einstellungen ändern''' im Ausgabe-Umfang 2 oder 3 eingestellt worden ist.
+
After the modeling, the following output can be found in the information log. This is saved in the JUICE under the menu item Protocols. It has to be noted that under the menu item '''Edit/Change Settings''' the output size has to be set to 2 or 3.
  
[[Bild:Ping_Infoprotokoll.png]]
+
[[File:Ping_Infoprotokoll.png]]
  
Somit ist für den Anwender ersichtlich, dass die Komponente '''Ping''' im ABC-Modell einmal bei der Modell-Initialisierung, 61 mal während der Modellierung (zeitlicher Kontext) und einmal beim Modell-Cleanup durchlaufen worden ist.
+
In this way, the user can see that the component '''Ping''' in the ABC model ran once during model initialization, 61 times during modeling (temporal context) and once during model cleanup.
  
===Laufzeitanalyse===
+
===Runtime Analysis===
  
Es ist möglich, die Laufzeiten der einzelnen Modellkomponenten im Infoprotokoll anzeigen zu lassen. Dieses ist im JUICE unter dem Menüpunkt Protokolle einzusehen. Hierbei muss darauf geachtet werden, dass unter dem Menüpunkte '''Bearbeiten/Einstellungen ändern''' im Ausgabe-Umfang 2 oder 3 eingestellt worden ist.
+
It is possible to show the individual components in the information protocol. This can be accessed in the JUICE under the menu item Protocols. This is saved in the JUICE under the menu item Protocols. It has to be noted that under the menu item '''Edit/Change Settings''' the output size has to be set to 2 or 3.
  
Im folgenden Bild ist beispeilhaft die Laufzeitenanalyse für das Gehlbergmodell angegeben, welches unter http://www.geoinf.uni-jena.de/5580.0.html herruntergeladen werden kann.
+
In the following image, the runtime analysis for the Gehlberg model is shown as an example. It can be downloaded at http://www.geoinf.uni-jena.de/5580.0.html.
  
[[Bild:Laufzeitanalyse.png]]
+
[[File:Laufzeitanalyse.png]]
  
=Anwendung von unterschiedlichen JAMS Ausführungsumgebungen=
+
=Application of Different JAMS Execution Environments=
  
Die Laufzeitumgebung (runtime system) stellt in JAMS verschiedene zentrale Dienste zur Ausführung von Modellen bereit, wie z.B.
+
The runtime environment (runtime system) makes different major services available for the model runtime in JAMS such as
*das Laden, Starten, Stoppen und Speichern von Modellen
+
*loading, starting, stopping and saving models
*ein zentrales Logging-System für Fehler- und Informationsausgaben (wärend des Ladens und Ausführens von Modellen)
+
*a central logging system for error and information output (when loading and executing models)
*die Verwaltung grafischer Modellausgaben
+
*managing graphical model outputs
  
Um die Ausführung von Modellen an individuelle Anforderungen anzupassen, bietet JAMS einerseits eine Schnittstelle zur Implementierung eigener, angepasster Laufzeitumgebungen durch erfahrene Benutzer. Um auch weniger versierten Anwendern die Anpassung der Laufzeitumgebung an eigene Anforderungen zu ermöglichen, wurde die Standard-Laufzeitumgebung mit einer Reihe von Konfigurationsoptionen versehen. Hierzu gehören insbesondere die Steuerung des Umfangs der Modellausgaben und eine Option zum Abschalten sämtlicher grafischer Modellelemente, wie sie etwa zur Modellausführung auf Rechnern ohne grafische Benutzerschnittstelle notwendig wird.
+
In order to adapt the execution of models to individual requirements, JAMS on the one hand serves as an interface for implementing one's own, adapted runtime environments by advanced users. In order to allow more unexperienced users to adapt the runtime environments to their own requirements, a default runtime environment was developed including various configuration options. Among these are especially the control of model output size and an option for deactivating all graphical model elements which is required for model execution on computers without graphical user interface.
Letzteres wird durch Start von JAMS von der Kommandozeile (Eingabeaufforderung in Windows) unter Angabe des Parameters "-n" (alternativ "--nogui") erzwungen. Da hierbei keinerlei grafische Oberfläche zum Laden des Modells angezeigt wird, muss das auszuführende Modell mit dem Parameter "-m" (alternativ "--model") angegeben werden.
+
The latter is activated when starting JAMS by the command line (prompt in Windows) by indicating the parameter "-n" (or "--nogui"). Since there is no graphical interface for loading models, the model has to be indicated using the parameter "-m" (or "--model")
So kann zum Beispiel das Modell J2000 mit folgendem Befehl ausgeführt werden:
+
In this way, for example the model J2000 can be executed by using the following command:  
 
C:\Program Files\jams>jams.bat -n -m data\j2k_gehlberg\j2k_gehlberg.jam
 
C:\Program Files\jams>jams.bat -n -m data\j2k_gehlberg\j2k_gehlberg.jam
  
Im Ergebnis lädt die Laufzeitumgebung das angegebene Modell und führt es sofort aus. Eventuell vorhandene grafische Modellkomponenten werden dabei nicht geladen, sämtliche Modellausgaben erfolgen an der Kommandozeile und werden -- falls konfiguriert -- in entsprechende Log-Dateien geschrieben.
+
As a result, the runtime environment loads the model and executes it immediately. Graphical model components which may exist are not loaded, all model outputs are carried out in the command line and they are written -- if configured -- in the corresponding log files.
Mit dieser Methodik können JAMS-Modelle auf einfache Weise etwa auf entfernten Servern über eine Konsolenverbindung oder automatisiert mit Hilfe eines Batch-Skriptes aufgeführt werden.
+
Using this methodology, the JAMS models can be carried out easily from remote servers by using a shell connection or automatized using a Batch script.

Latest revision as of 21:47, 18 May 2012

Contents

JUICE - Jams Model Editor

The JAMS Builder (JUICE) was developed in order to set up and/or configure environmental models. By using JUICE any models can be combined and configured by the "module principle". For this purpose, there are two types of "modules" available. On the one hand, those are components which describe the individual processes. On the other hand, there are context components which control the model run. For the data exchange between components and contexts attributes are needed. Those can be variables but also parameters.

JUICE: Structure and Scope of Use

The interface of the JAMS Builder will be explained below.

The installation of your JAMS creates a JAMS builder button on your desktop and in the Start menu. It refers to the JAMS User Interface Component Editor (JUICE). After starting JUICE the following window appears which is divided into three areas. In the top left window you can see the libraries which are loaded. The bottom left window shows the running processes. The right area shows the model.


1.JUICE1 en.jpg

Structure of the Menu Bar

JUICE1 en.jpg

The menu bar contains the items File, Edit, Model, Logs, Windows and Help. In addition, the following functions are integrated in the form of icons:


1. Open new model

2. Load model

3. Save model

4. Search function

5. Jams settings

6. Start model

7. Open JAMS Launcher

8. Open JAMS Datastore Editor

9. Open JADE

10. Copy model surface

11. Paste model surface

12. Show info log

13. Show error log

14. JAMS Website

15. Close


Under the menu item File models can be loaded, saved and closed.

JUICE File en.jpg

The menu item Edit allows to edit, load or save settings and offers a search function.

JUICE Edit en.jpg

Under the item Edit Preferences you can edit the libraries which are used, the extent of the output, the output of logs and information on the model window. Those settings can be saved for subsequent modeling under the item Save Preferences and they can be reused by clicking on Load Preferences.

The menu item Model is only activated when a model has been loaded. It can start or configure the model. Moreover, the JAMS Explorer is linked which is used for analyzing used input data and results of the modeling. Its scope of services is explained in detail in the Tutorial Basic User. Loading and saving parameter sets can be done by using Load Model Parameters and Save Model Parameters. In addition, the model can be started by using the JAMS Launcher. The Optimization Wizard serves as a platform for automatic parameter optimization.

JUICE model en.jpg

Under the menu item Logs the Info Log can be shown. It contains information about the model's author, its version and user and also about the model's efficiency (How well displayed are the measured values in the model?), the model's structure (Which components were used how often?) and the time of the modeling. The Error Log shows errors which may have occurred.

JUICE Logs en.jpg

The menu item Windows lists all windows which are currently open.

Under the menu item Help you can obtain online help by clicking on JAMS online.

Systemleiste Help en.jpg

Application of JUICE for Model Design and Model Configuration

Setting up a Model

The JUICE can set up models. In the following steps, the procedure is carried out exemplarily by using the ABC model.

Step 1

Select the item New Model in the menu item File. An empty model is opened. The left part of the opened window displays the (context) components which are part of the model. The right part of the window can show two different views. On the one hand Component Configuration where the model's (context) components are edited. Their attributes are linked. Moreover, a parameterization can be carried out. The second view shows the Surface Editor which can edit the model's surface.


JUICE NewModel Step1 en.jpg


Step 2

Create a context component of the Type "JAMS Temporal Context". It allows a temporal iteration of the simulation. Click on the library jams-main.jar which is listed in the top left window. There you will find the JAMSTemporalContext under jams.model. Drag it to the right window into the "New Model".

JUICE TemporalContext Step2 en.jpg

Create the context attribute modelTimeIntervall within the model. Click on Component Attributes in the Attribute List under the item New Model.

Click on Add. Take modelTimeIntervall as name. Select TimeInterval as attribute type. You have to determine a time span for the simulation. (Note that data for the selected time span have to be available.) Take 01.01.1970 to 01.01.1975 as time span. Select Month as temporal unit. Then click on SET. The attribute modelTimeIntervall is now linked to the time interval you selected.

JUICE TimeInterval Step3 en.jpg

Go to component JAMSTemporalContext. Link the component attribute timeInterval to the model attribute modelTimeIntervall which has already been created. Select it from the attribute list in the bottom right box. Click on LINK.

JUICE NeuesModell Step4 en.jpg

Create a new attribute time and link it to the component attribute current.

JUICE NeuesModell Step5 en.jpg

Step 3

Add the component ABCDataReader to the model. You can find it in the library jams-democomponents.jar in the folder jams.components.demo.abc. The component ABCDataReader allows reading data. It reads the date and values for precipitation and runoff from a text file. This text file can be downloaded here: File:Abc.txt

JUICE ABCDataReader Step6 en.jpg

The location of the data file has to be transferred to the component attribute fileName. For this reason, you have to enter the file path of your data file as value of the attribute fileName. Click on SET.

Create the attributes precip (for precipitation) and obsQ (for runoff measures) in the JAMSTemporalContext. They should contain the values of the precipitation and runoff which is measured for the current time step. Select the component attribute precip. It should be shaded in BLUE now. Enter the name precip into the box Modified Attribute. Click on LINK. The context attribute precip from the context JAMSTemporalContext has been created and linked.

JUICE NeuesModell Step8 en.jpg


Now select the component attribute runoff. It should be shaded in BLUE now. Enter obsQ into the box Modified Attribute Click on LINK. The context attribute obsQ from the context JAMSTemporalContext has been created and linked.

JUICE NeuesModell Step9 en.jpg

Step 4

The central component of the model is the component of the ABC model. The ABC model is a linear model which relates precipitation and runoff to each other. Add the component ABCModel to the model. You will find it in the library jams-democomponents.jar in the folder jams.components.demo.abc.


JUICE NeuesModell Step10 en.jpg

Link the precipitation data to the component. Select the component attribute precip. Select precip for the box Modified Attribute from the list of attributes which are already in the JAMSTemporalContext. Click on LINK. Create new attributes for the water storage (storage) and the simulated runoff (simQ) as desribed in Step 3. The following window should appear:

JUICE NeuesModell Step11 en.jpg

The component attributes a,b,c and initStorage allow the parameterization of the component. Assign the following values: a=0.2, b=0.2, c=0.75 and initstorage=50.

JUICE NeuesModell Step12 en.jpg

Step 5

For the visualization of results you need the component TSPlot. Add this component to the model. You will find it in the libary jams-components.jar in the folder jams.components.gui.

JUICE NeuesModell Step13 en.jpg

Link the component attribute time to the attribute time from the context New Model. Select the component attribute time. Select the context New Model from the bottom right box and select the attribute time. Click on LINK. Link the component attribute valueLeft to the attributes simQ and obsQ from the JAMSTemporalContext. If you want to link one component attribute to more than one context attribute, you have to separate them by semicolon. The following window should appear:

JUICE NeuesModell Step14 en.jpg

Step 6

Now a model surface is to be created for the ABC model. Go to view GUI Builder.

JUICE NeuesModell Step14 1 en.jpg

The attributes a,b, and c are to be edited on the model's surface. In order to do that, create a new group clicking on add Group and give it the name "ABC model". By clicking on the button Add Property one box has to be created for each attribute. Note that the attribute has to be linked to the right component. In addition, the range of values can be defined by an upper and a lower boundary for the attribute. For example, the entries for parameter a in the parameter editor look like this:


JUICE NeuesModell Step14 2 en.jpg

The group ABC Model is now finished and should look like this:

JUICE NeuesModell Step14 3 en.jpg

Moreover, the display of results of the modeling in terms of color should be adjustable in the diagram. Therefore, create a new group clicking on Add Group and name it "diagram". Create editors for the attribute colorLeft. Name it colors left and link the created attributes to the attributes of the component TSPlot.

The group diagram is now finished and should look like this:

JUICE NeuesModell Step14 4 en.jpg

In order to link the colors of the outflow curves, go to TSplot component configuration. In the field colorleft enter the value blue;red. Doing so, the colors can be changed later during model runtime.

JUICE NeuesModell Step14 4 1 en.jpg


Step 7

Save the model.

The model is finished. Now you can launch it directly by using the JUICE or by using the JAMSLauncher. If you launch it via the JAMSLauncher, you can edit all attributes which have been linked to the model's surface..

JUICE NeuesModell Step14 5 en.jpg


The following output window appears. The measured runoff is displayed in blue, the simulated runoff in red.

JUICE NeuesModell Schritt15.jpg

Configuring Model Components

JUICE allows the configuration of model components which makes it easy to change the parameterization of a component. The procedure will be explained by taking the component TSPlot from the ABC model of section "Setting up a Model" as an example.

An Example

In the created model no parameter values for component attributes were defined. As a result, default values were assumed for the various parameters. Of course they can be modified in order to make the resulting diagram, which visualizes the results of the modeling, more attractive.

JUICE Modifizieren Step1 en.jpg

We set the following values for the modification:

  • titleLeft (title of the left diagram axis) : simulated runoff; measured runoff
  • titelRight (title of the right diagram axis): precipitation
  • colorLeft (color shades of values displayed on the left): red; blue
  • colorRight (color shades of values displayed on the right): gray
  • typeLeft (type of graphic rendition, e.g. as line chart or bar chart): 0 (line)
  • typeRight (type of graphic rendition, e.g. as line chart or bar chart): 1 (bar)
  • xAxisTitle (title of x-axis): time
  • leftAxisTitle (title of left y-axis): runoff [m³/s]
  • rightAxisTitle (title of right y-axis): precipitation[mm]
  • rightAxisInverted: 1


Moreover, the component attribute valueright has to be linked to precip from the JAMSTemporalContext to display precipitation values.

Overview of new attributes:

JUICE Modifizieren Step2 en.jpg

The following graph results from the modification:

JUICE Modifizieren Schritt3.jpg

Exchanging Components

The JUICE allows to substitute model components by other components. For this purpose, input and output attributes have to be accurately linked.

An Example

As an example, the component CalcPotentialET is substituted by the component Penman in the precipitation-runoff model J2K. Both components calculate the potential evaporation but each one using different algorithms.

Step 1: Open Model and Step 2: Delete Component

Load the model j2k_gehlberg.jam from the example data sets which were made available when downloading the software. Clicking on the component CalcPotentialET of the HRULoop creates the following image. Delete the component CalcPotentialET in order to integrate another evaporation component into the model. Right-click on the component and select delete.

JUICE Austauschen Step2 en.jpg

Step 3: Add New Component

In the library J2K.jar in the folder org.unijena.j2k.potET you will find the component Penman. Drag it to the position of the former component CalcPotentialET.

JUICE Austauschen Step3 en.jpg

Step 4: Parameterization

Assign the value d to the attribute tempRes and the value 1.2 to the attribute et_cal.

JUICE Austauschen Step4 en.jpg

Step 5: Link Context Attributes

Link the context attributes wind,tmean,rhum,netRad,elevation,area,potET and actET to the corresponding context attributes of the HRULoop (interaction across all spatial units).

JUICE Austauschen Step5 en.jpg

The former component which is used for calculating potential evaporation (CalcPotentialET) created the attributes rs and ra. Those attributes were summarized according to their importance in the component SpatialWeightedSumAggregator1. Since the new component does not create these attributes, they have to be deleted from links in the component SpatialWeightedSumAggregator1.

Select the component SpatialWeightedSumAggregator1 and delete the links of the component attribute value with the context attributes rs and ra by deleting these attribute from the box Modified Attribute and then linking them again.

JUICE Austauschen Step6 en.jpg

Start the new model. The following image shows you the graph resulting from the modeling:

JUICE Austauschen Schritt7.jpg

Generating a Model Documentation

(Hydrological) Models consist of various model components. In order to document your model in terms of its scientific basis as well as its software realization you have the JAMS-Doc software tool at your disposal which has been integrated into JUICE. Its functioning is described in detail in the Tutorial Model Documentation.

Model Validation and Parameter Optimization

In order to apply hydrological models successfully it is necessary to define model parameters accurately. A direct measurement of the parameters is mostly not possible, too expensive or there is no clear physical relation. For those reasons the parameters are adjusted in a trial and error process in so far that the simulated factors (e.g. runoff) correspond best to the values measured. This task can be time-consuming and difficult if the corresponding model is complex or has a large number of parameters. Therefore it makes sense to automatize the optimization process with a software tool for the optimization of model parameters and sensitivity analysis which is available. The model validation serves to check the suitability of a model for a specific purpose which was intended (Bratley et al. 1987) and is an important tool for quality assurance. A model is useful for an application if the simulation is reliable with regard to real processes (Power 1993). Subject to the purpose and type of the model different key figures and proof are required to validate the model. Its functionality is described in detail in the Tutorial Calibration and Sensitivity Analysis.

Debugging and Runtime Analyses Using Inspection Components

The Ping Component

In order to reconstruct the processing of your model, a component called Ping is at your disposal. It can be integrated into the model at every possible position and it makes a signal (ping) in the information log for the model runtime when it starts running. In addition, the Ping component shows how many times a component (e.g. within a temporal iteration - modeling during a few days - or within a spatial iteration - modeling within various spatial entities) has been recalled.

Below the Ping Component has been integrated into the ABC model which has been established in section 1.2.1 - Setting up a Model. The component can be found in folder jams-components in jams.components.debug.

JUICE Ping.png

After the modeling, the following output can be found in the information log. This is saved in the JUICE under the menu item Protocols. It has to be noted that under the menu item Edit/Change Settings the output size has to be set to 2 or 3.

Ping Infoprotokoll.png

In this way, the user can see that the component Ping in the ABC model ran once during model initialization, 61 times during modeling (temporal context) and once during model cleanup.

Runtime Analysis

It is possible to show the individual components in the information protocol. This can be accessed in the JUICE under the menu item Protocols. This is saved in the JUICE under the menu item Protocols. It has to be noted that under the menu item Edit/Change Settings the output size has to be set to 2 or 3.

In the following image, the runtime analysis for the Gehlberg model is shown as an example. It can be downloaded at http://www.geoinf.uni-jena.de/5580.0.html.

Laufzeitanalyse.png

Application of Different JAMS Execution Environments

The runtime environment (runtime system) makes different major services available for the model runtime in JAMS such as

  • loading, starting, stopping and saving models
  • a central logging system for error and information output (when loading and executing models)
  • managing graphical model outputs

In order to adapt the execution of models to individual requirements, JAMS on the one hand serves as an interface for implementing one's own, adapted runtime environments by advanced users. In order to allow more unexperienced users to adapt the runtime environments to their own requirements, a default runtime environment was developed including various configuration options. Among these are especially the control of model output size and an option for deactivating all graphical model elements which is required for model execution on computers without graphical user interface. The latter is activated when starting JAMS by the command line (prompt in Windows) by indicating the parameter "-n" (or "--nogui"). Since there is no graphical interface for loading models, the model has to be indicated using the parameter "-m" (or "--model") In this way, for example the model J2000 can be executed by using the following command: C:\Program Files\jams>jams.bat -n -m data\j2k_gehlberg\j2k_gehlberg.jam

As a result, the runtime environment loads the model and executes it immediately. Graphical model components which may exist are not loaded, all model outputs are carried out in the command line and they are written -- if configured -- in the corresponding log files. Using this methodology, the JAMS models can be carried out easily from remote servers by using a shell connection or automatized using a Batch script.

Personal tools
In other languages