Tutorial Advanced Users
Contents |
JUICE - Jams User Interface Component 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.
Structure of the Menu Bar
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:
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.
The menu item Edit allows to edit, load or save settings and offers a search function.
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.
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 Assistant serves as a platform for automatic parameter optimization.
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.
The menu item Window lists all windows which are currently open.
Under the menu item Help you can obtain online help by clicking on JAMS online.
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.
Bild:JUICE_NeuesModell_Schritt1.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".
Bild:JUICE_NeuesModell_Schritt2.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.
Bild:JUICE_NeuesModell_Schritt3.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.
Bild:JUICE_NeuesModell_Schritt4.jpg
Create a new attribute time and link it to the component attribute current.
Bild:JUICE_NeuesModell_Schritt5.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.
Bild:JUICE_NeuesModell_Schritt6.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.
Bild:JUICE_NeuesModell_Schritt8.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.
Bild:JUICE_NeuesModell_Schritt9.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.
Bild:JUICE_NeuesModell_Schritt10.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:
Bild:JUICE_NeuesModell_Schritt11.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.
Bild:JUICE_NeuesModell_Schritt12.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.
Bild:JUICE_NeuesModell_Schritt13.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:
Bild:JUICE_NeuesModell_Schritt14.jpg
Step 6
Now a model surface is to be created for the ABC model. Go to view Surface Editor.
Bild:JUICE_NeuesModell_Schritt14_1.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 with the nam "ABC model". By clicking on the button New Editor 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_Schritt14_2.jpg
The group ABC Model is now finished and should look like this:
Bild:JUICE_NeuesModell_Schritt14_3.jpg
Moreover, the display of results of the modeling in terms of color should be adjustable in the diagram. Therefore, create a new 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.
The group diagram is now finished and should look like this:
Bild:JUICE_NeuesModell_Schritt14_4.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..
Bild:JUICE_NeuesModell_Schritt14_5.jpg
The following output window appears. The measured runoff is displayed in blue, the simulated runoff in red.
Bild: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.
Bild:JUICE_Modifizieren_Schritt1.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:
Bild:JUICE_Modifizieren_Schritt2.jpg
The following graph results from the modification:
Bild: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
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.
Bild:JUICE_Austauschen_Schritt1.jpg
Step 2: Delete Component
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_Schritt2.jpg
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.
Bild:JUICE_Austauschen_Schritt3.jpg
Step 4: Parameterization
Assign the value d to the attribute tempRes and the value 1.2 to the attribute et_cal.
Bild:JUICE_Austauschen_Schritt4.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).
Bild:JUICE_Austauschen_Schritt5.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.
Select the component SpatialWeightedSumAggregator1 and delete the links of the component attributevalue with the context attributes rs and ra by deleting these attribute from the box Modified Attribute and then linking them again.
Bild:JUICE_Austauschen_Schritt6.jpg
Start the new model. The following image shows you the graph resulting from the modeling:
Bild:JUICE_Austauschen_Schritt7.jpg
