How to use Map Editor

[home]

When started, the MapEditor will look like this:


By moving your mouse over most widgets and areas, you should have help ballons popping to help you use the tool.


Loading action descriptions Back to top

The first thing you have to do is to load some factories.
You've two options there :
  • either you've just specified your factory, have no underlying implementation, and want to check your factory specification or build your process specification to check it.
    You'll then use the MapEditor in specification mode.
  • or your integrator has provided you with an implementation of your specified factory, and you want to use it to run real computation with the MapEditor as a process controller.
    You'll then use the MapEditor in execution mode.
Be aware that as soon as you've loaded any factory in specification mode, you won't be able to switch back in execution mode (unless restarting the MapEditor), because it means that some loaded components have no underlying implementation.
Be aware that if the MapEditor may handle a mix of several factories in a process, the underlying FactoryAction is not yet capable of that, so you should currently restrain to using a single action factory at a time.
In
specification
mode

To switch to specification mode, you will first have to push the "Execution" button, which label should change to "Specification":

=>

You'll now select the right loading button (which help balloon should read "Load actions from configuration files"):

And select your saved XML description of your action factory from the FactoryEditor visual tool.

In
execution
mode

Remembrer you should have started your FactoryAction, using the script provided by your integrator.
You'll now select the left loading button (which help balloon should read "Load actions from a running action factory"):


You now have to choose the way for the MapEditor to connect to your running FactoryAction.

If your FactoryAction registered itself in the ORB naming service (let's see that as a "Yello page" directory of running servers), you sould see it available in the "Naming" tab:


Just press the button corresponding to your Factory in the list.
The MapEditor will then connect to the FactoryAction, and discover on the fly which actions this FactoryActio implements.

If your FactoryAction does not register itself in the ORB naming service, then you should select the "Reffile" tab, and enter the name of a file where the "stringified IOR" of your FactoryAction is stored.
Enter "foo" if yout IOR is stored in file "foo.ref":


You should check that with your integrator, but an IOR looks like that:
IOR:0000000000000.......5365727669636500
The MapEditor will then connect to the FactoryAction, and discover on the fly which actions this FactoryActio implements.


Creating and interacting with action boxes Back to top

We will now have to define the actions that take part in our process.
Press the right mouse key in the background of the MapEditor:

Discard for the moment the first two entries ("New group" and "New parameter action"). You should find below the name of the loaded factory, with a sub-menu detailing all of the actions available from this factory.
Select one of the actions, to make an action box appear in the working area:

Each time you'll select an action from the background popup menu, you'll create such an action box. You'll so be able to create an action box for each of the steps of your process.
Now, let's see the basic way of interacting with these action boxes, to organize our workspace ares :
  • First, by dragging the left mouse button on the background, you'll move the complete area.
  • By dragging the left mouse button on the name of the action box, you'll move this box alone.
    (just clicking with left mouse will pop the action box to the front)
  • By pushing the "O" button, you'll open the action box to edit various parameter values (we'll see that in detail later), and pushing the "o" button again will close the action box to it's previous state.
  • By pushing the ">" button, you'll ask the action to be executed.
    Note that when the button is not green, the action can't be executed because data are missing on the input port.
    If (like on the previous figure) the button is green, it means that there are data on the input ports, available and ready to be processed; or that the action has no input port so it is always ready to fire.
  • By pushing the "X" button, you'll delete this action box.
  • By pressing the right mouse key on the lower left orange rectangular area, you'll get a popping menu with the available input ports.
    (we'll see later how to use it for connecting actions).
  • By similarily pressing the right mouse key on the lower right orange rectangular area, you'll get a popping menu with the available input ports.
  • By pressing the middle mouse key on either orange rectangular port area, you'll get on the standard output (listing) a dump of the connection status.
Help balloons should help you to remember these commands.


Action boxes internal details Back to top

Let's see now how to set the details of each action box. Fist, you'll need to open it using the "O" button, which shoud make your action box look like :

The first lines shows the parameters, that were specified as required for the action (here in this figure "Filename" and "InitialSolValue"). For each of them, an entry field allow interactive input of their values.
At the end of each parameter line, is a radio-button with three mutually exclusive options: "GS", "GU" and "Local". For understanding these, please create two identical action boxes (two instances of the some action), and open them.
  • "GS" stands for "Global Shared". When this option is selected, the corresponding parameter is replicated in the "Global Area", at the left of the MapEditor.

    Set one of your parameters as "Global Shared", and try changing it's value : any change in the action box area is repercuted instantly in the global area and vice-versa.
    Set now the same parameter as "Global Shared" in your other action box : the three values are now linked. Changing the value in any of the two action boxes or the global area immediately update the two others.
    The parameter value is shared globally over the simulation, among all of the action boxes which declared it "Global Shared". This is usefull to insure that some parameter values are unique among the simulation (physical parameters such as altitude, or numeriacl parameters such as global iteration number).
  • "GU" stands for "Global Unshared". When this option is selected, the corresponding parameter is replicated in the "Global Area", at the left of the MapEditor.
    But he's now prefixed by it's action name and internal unique number.

    Set one of your parameters as "Global Unshared", and try changing it's value : any change in the action box area is always repercuted instantly in the global area and vice-versa.
    Set now the same parameter as "Global Unshared" in your other action box : another different field is set in the global area (differing by the action internal unique id, seen here as a number). This secong global field is linked to the second action box parameter in the same way the first is linked to the first action box parameter.
    The parameter values is shown globally regarding to the simulation, but their values are not shared. This is mostly usefull from the user-interface point of view, to bring in the global area some important parameters of the simulation for which you don't want to have to find the action box and open it to edit the parameter value.
  • "Local" stands for "Local" (!). Well, that's the default behaviour : the only way to change a "Local" parameter is to open the action box and set it's value.

At the bottom of the action box is the underlying servers description. If you're in specification mode, you may forget that part, but in execution mode, you'll have to fill it.
Check with your integrator for filling this part, which should be improved in next release. Especially, you'll need to know if you've an automatic activation available or not (it's recommended and available with most commercial packages such as Orbix and Visibroker. We provide a custom one for Orbacus in FactoryAction).
If you've an automatic activation available, you'll just have to fill the name of the underlying servers to be activated, the host on which you wish them to be spawned, and leave the port number to "1".
If you've no automatic activation, you'll have to start manually the underlying servers, then specify their name, the host on which they were started, and their listening port number.


Connecting action boxes Back to top

Let's now connect action boxes together, to streamline the process and express how data flows from action to another.
Push right key mouse on the output port (right) bottom orange area of the upstream action, and select the data to be flushed downward :

Then push right key mouse on the input port (left) bottom orange area of the downstream action, and select the data to be accepted as input :

The two boxes are now connected, and you may check that connection prerssing middle mouse button either on upstream action output port area or downstream action input port area (and look at the listing) :

Note that you may delete the link by just clicking on it (you've to be precise !) with the left mouse key.


Loading and saving a map Back to top

You may now save your defined computationnal path, by selecting the usual "save" icon in the upper toolbar (i.e. the floppy) :

You'll be able to reload it later in the MapEditor using the usual "open" icon.


Firing action boxes Back to top

Now clicking on the fire (">") button of upstream action (in the exemple shown "LoadMesh") should send data downstream and make next action (here "Solver") ready to fire (the ">" button should pass to green) :

Clicking on the fire (">") button of downstream action ("Solver") should start this action and consume the available input data (the ">" button should pass to red) :

If you try to fire N times the upstream action, you'll be able to fire N times the downstream action before the fire button turns to red, because the inputs are buffered.
The same if you've two upstream actions filling a downstream action and fire both upstream actions, two data will be buffered on the input port of downstream action, allowing her to fire two time (collector default behaviour) :


Auto-fire and parallel pathes Back to top

If we build now a chained sequence of three actions :

You may fire all three modules one by one in manual mode, or press button "Manual fire" in the upper toolbar. The button should switch to "Auto fire" :

If you fire now manually the first action of the sequence, all downstream actions are fired as soon as all input ports have been provided with data.
Let's now build a two path computationnal sequence :

Fire first action : when its execution if finished, data is sent downstream to both connected "Solver" modules which start simultaneously. For each action execution, the MapEditor create an independant thread, thus allowing several actions from paralel pathes to execute simultaneously.
Be aware that the standard generated FactoryActions are not yet multi-threaded in this version, so that some FactoryActions will not be able to take advantage of that.


Execution control with conditions Back to top

You may set conditions on the global values, by pressing left mouse key on the button which is on the right of the global value entry field :

While the condition is verified, the test appears surrounded in green :

If as a result of any action changing the parameter value, the test is not any more verified, it will appears surrounded in red, and the execution mode is automaticazlly switched back to "Manual fire" thus stopping the process (except by manual continuation or analysis) :


Triggers Back to top

There are some cases, when you'll want to sequence two actions without having any data to be flushed from one to the other (ex: start a plotting software when the output file has been generated). You will then need a way for upstream action to signal downstream action that it should start.
Triggers are designed to solve this problem.
You may connect any output port to an input trigger port, especially an output trigger if you've nothing else to send downstream. For the trigger to be active, the "Use trigger" checkbox should be activated :

Be aware that once the input trigger is activated, it may receive any kind of data which it will not try to understand, but will need to have data available as any other port, for the action to start.


Parameter actions Back to top

Parameter actions are Python affectations concerning global parameters.
In some cases, you'll want to modify a global parameter without to have a specific action doing it (ex: increment a global iteration loop counter). You will then need a way to do it directly from the MapEditor.
Parameter actions are designed to solve this problem.
They should be fired via triggers, and will accept any Python expression of the form :

<global variable name>= function of (<global variable name>)

Be aware that you should for the moment strictly respect Python syntax, and Python is a dynamically but strictly typed language. This makes expressions difficult and will be improved in next version.
Here is an example for incrementing a global iteration counter named "Value":

The "Manual trigger" button allow you to test your syntax by running the action without flushing any output.
You may customize a parameter actions name by pressing right mouse key on its name.


Command actions Back to top

Command actions are system commands which parameters may contain global parameters.
In some cases, you'll want to run a system command with one or several global parameter as arguments, without to have a specific action doing it (ex: launch an editor on your output listing, or a plotting software on your generated output file). You will then need a way to do it directly from the MapEditor.
Command actions are designed to solve this problem.
They should be fired via triggers, and will accept any system expression including global variable which value will be replaced before execution by their current value.
Here is an example for editing automatically an output file :

The "Manual trigger" button allow you to test your syntax by running the action without flushing any output. You may customize a command actions name by pressing right mouse key on its name.


Groups Back to top

Groups are a way to wrap several actions and make them appear as a single one. It may be seen (and it is as a matter of fact !) as an Action Box containing itself a sub-map editor.
When opened, the Group shows it's internal map editor in which all of the previously described behavior are available.
The only two specific things about group are :
  • First the size grow ("+") and size reduce ("-") buttons, on which you should push to adapt opened group size (sorry, it's yet still a little ugly and you cat set size independantly in both directions : there are many improvements planned around that...).
    They are located in the internal map editor toolbar :

  • Group ports are the replication of internal Action Boxes ports. To establish connection from an outer Action box to an inner action box, connect the outer action ports to the group ports corresponding to the inner action you want to connect with :

Please be aware that group handling is in alpha development in this version, and especially the Load/Save is still buggy when dealing with groups.
So experiment with it and provide feedback, but don't rely on them ! Thanks.


Python and C/C++ static generation of a hard wired process controller from a MapEditor's map is still at prototype version for the moment, so the corresponding buttons remain inactive:



Comments, bugs, fixes to t_chevalier@libertysurf.fr.


[Home]