]> SALOME platform Git repositories - modules/yacs.git/blob - doc/operations.rst
Salome HOME
mergefrom branch BR_V511_PR tag mergeto_trunk_03feb09
[modules/yacs.git] / doc / operations.rst
1
2 General operations
3 ==================
4
5
6 Activate YACS module
7 --------------------
8 To work with YACS module the user can activate it in two ways:
9
10
11
12
13 #. by activating YACS item in :ref:`modules`,
14
15
16 #. by click YACS toolbar button on :ref:`modules`.
17
18
19
20
21
22 For the correct activation of YACS module it is necessary to install YACS GUI libraries and set YACS_ROOT_DIR environment variable pointed to the directory with installed binaries.
23
24 If there is no any study opened/created, during the YACS module activation the user has possibility to choose between opening an existing study and creating a new one. When YACS module has been activated, YACS GUI :ref:`main_menu` and :ref:`toolbars` corresponding to the state when no calculation schema is being edited or run are shown:
25
26
27
28 .. image:: images/functionality_list_0.jpg
29   :align: center
30   :width: 69ex
31
32
33
34 In such a case there are only possibilities for the user to create or import (YACS or SUPERV XML) a schema.
35
36 :ref:`object_browser` shows tree representation of YACS objects in the current study.
37
38
39 Import/Export a schema
40 ----------------------
41 To display either in :ref:`viewer` or in the :ref:`object_browser` and :ref:`tree_view` and edit a schema the user can import the schemas' XML file. The modified schema object can be saved into the specified XML file with help of :ref:`export_schema` YACS GUI command.
42
43 .. _import_yacs_schema:
44
45 Import YACS calculation schema
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47 The command **Import Schema --> YACS XML** is accessible from :ref:`file` or from the corresponding toolbar button on the :ref:`schema`. On this command call a standard open file dialog box appears and lets user to select desirable YACS XML file.
48
49
50
51 .. image:: images/functionality_list_1.jpg
52   :align: center
53   :width: 60ex
54
55 .. centered::
56   **Import YACS XML schema dialog**
57
58
59 Imported schema is shown as an entry in :ref:`object_browser`.
60
61 If a selected YACS XML file has incorrect structure, a part of a schema that has been imported successfully (before an error occurred) will be represented in :ref:`object_browser` and :ref:`viewer` and the user will be able to work with it. YACS GUI shows an error message with error description in such a
62 case.
63
64 Dimensions of drawing area occupied by a graph, positions and dimensions of node presentations, positions of internal link points and type of :ref:`change_2d_representation_schema` is retrieved from YACS XML file in order to correct 2D representation of the schema in the 2D Viewer.
65
66 .. _import_supervisor_graph:
67
68 Import SALOME Supervisor graph
69 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70 This operation is intended for importing an XML files containing description of calculation schema and having logical structure adopted by existing SALOME 4 Supervisor module. The command **Import Schema --> SUPERV XML** is available from :ref:`file` or from the corresponding toolbar button on the :ref:`schema`. On this command
71 call a standard open file dialog box appears and lets user to select desirable SUPERV XML file.
72
73
74
75 .. image:: images/functionality_list_2.jpg
76   :align: center
77   :width: 61ex
78
79 .. centered::
80   **Import SUPERV XML schema dialog**
81
82
83 Imported schema is shown as an entry in Object Browser.
84
85 If a selected SUPERV XML file has incorrect structure, a part of a schema that has been imported successfully (before an error occurred) will be represented in Object Browser and 2D Viewer and the user will be able to work with it. YACS GUI shows an error message with error description in such a case.
86
87 After importing of the SUPERV XML file has been completed a 2D representation of the schema (nodes and links) is displayed in the 2D Viewer.
88
89 .. _export_schema:
90
91 Export a schema to a file
92 ~~~~~~~~~~~~~~~~~~~~~~~~~
93 If user wants to store modifications done in the existing schema or save a new created graph into the YACS XML file, it is needed to make the schema active and choose the **Export schema** command from :ref:`file` or the corresponding toolbar button on the :ref:`schema`. As a result a standard save file dialog appears and lets
94 user to input or select desirable YACS XML file name to export the active schema in it.
95
96
97
98 .. image:: images/functionality_list_3.jpg
99   :align: center
100   :width: 60ex
101
102 .. centered::
103   **Export schema dialog**
104
105
106 YACS module writes description of a schema and its child objects into an XML file. Additionally, schema 2D presentation data is saved in new created XML file.
107
108
109 Open/Save a study
110 -----------------
111 The user can start his work with the saved earlier study document. To open a saved study, the user has to activate common SALOME 4 GUI operation with help of **Open** command from :ref:`file` or **Open document** toolbar button on the :ref:`standard`. SALOME unpacks YACS XML files from the study. YACS module reads them and re-
112 creates the study structure. If XML files in a study have incorrect structure, YACS GUI says that the loaded study is incomplete by showing an error message.
113
114
115
116 .. image:: images/functionality_list_4.jpg
117   :align: center
118   :width: 60ex
119
120 .. centered::
121   **Open a study dialog**
122
123
124 If the user finished his work, he can save a study for the future by calling **Save** command from :ref:`file` or **Save document** toolbar button on the :ref:`standard`. YACS module stores all schemas from the current study to XML files, which are then packed into a single HDF5 study file by SALOME.
125
126
127
128 .. image:: images/functionality_list_5.jpg
129   :align: center
130   :width: 60ex
131
132 .. centered::
133   **Save a study dialog**
134
135
136 .. _set_user_preferences:
137
138 Set user preferences
139 --------------------
140 In the frames of the YACS module the user has a possibility to set his own preferences. There are the following preferences in the YACS GUI for SALOME 4.1:
141
142
143
144
145 + Link draw color
146
147
148 + Stream link draw color
149
150
151 + Link select color
152
153
154 + Link highlight color
155
156
157
158
159
160 These preferences can be set by the user with help of standard SALOME 4 GUI operation of editing preferences: **Preferences ...** command from :ref:`file`. But in versions after YASC GUI for SALOME 4.1 the set of preferences can be extended by colors for various node types and states during execution, by preferences for external Python code editor and probably some
161 others.
162
163 After the user changed the preferences in the Preferences dialog box for YACS module
164
165
166
167 .. image:: images/functionality_list_6.jpg
168   :align: center
169 ..  :width: 86ex 
170
171 .. centered::
172   **Preferences dialog for YACS module**
173
174
175 the system applies the new values of preferences to relevant objects immediately.
176
177
178 Select an object
179 ----------------
180 Object Browser, Tree View and 2D Viewer provides user with the possibility to select an object. The user can select objects in 2D Viewer or Tree View. There is the mechanism to synchronize selection between 2D Viewer and Tree View in YACS module.
181
182
183
184 .. image:: images/functionality_list_7.jpg
185   :align: center
186 ..  :width: 76ex 
187
188 .. centered::
189   **Port selection**
190
191
192 In 2D Viewer the user can select/hilight nodes, ports and links. In the Tree View the user can select containers definitions, component instances definitions, nodes, ports, data types and links.
193
194 At the current moment YACS module supports only single selection, i.e. the user clicks on a single object with the mouse. However, the following kinds of interactive selection will be implemented in further versions:
195
196
197
198
199 + **Multiple** - the user clicks on different objects while holding SHIFT key pressed. This type of selection is needed, for example, for creation of link between two ports selected in the Object Browser.
200
201
202 + **With rectangle** - the user selects one or several objects by clicking first corner of a rectangle in 2D Viewer and dragging the mouse pointer to the opposite corner with the left mouse button pressed. All objects inside the rectangle become selected.
203
204
205 + **SHIFT mode** - the user clicks on the same object or select object(s) with a rectangle holding SHIFT key pressed, and the system deselects objects that were selected and select objects that were not selected before.
206
207
208
209
210
211 The 2D Viewer displays selected/hilighted objects in a distinctive way that allows the user to identify the selected/hilighted objects easily.
212
213 The system state after interactive selection depends on the type of selected object(s):
214
215
216
217
218 + **A single editable object is selected:** Input Panel is shown and contains property pages for the selected object and in some cases for its parent objects in a schema hierarchy. For instance, if an inline script node is selected either in 2D Viewer or in the Tree View, the property page for the selected node will be displayed in the Input Panel.
219
220 .. image:: images/functionality_list_8.jpg
221   :align: center
222 ..  :width: 107ex
223
224 .. centered::
225   **Node selection**
226
227 If the user selects SALOME service node, property pages for node, its component and container will be shown in the Input Panel.
228
229
230 + **Several objects or a single object that has no editable properties is selected:** Input Panel is hidden.
231
232
233 + **Nothing is selected:** Input Panel is hidden.
234
235
236
237
238 .. _activate_context_popup_menu:
239
240 Activate context popup menu
241 ---------------------------
242 In the YACS module the user can perform a set of operations on the different types of objects shown in the Object Browser and Tree View of the schema with help of context popup menu. For this purpose, the user has to click the right mouse button in the Object Browser or in the Tree View of the schema to select the object and choose needed menu item from context popup menu, which contains commands
243 applicable to the current selection. For empty selection, only commands applicable to the window (Object Browser, schema Tree View or 2D Viewer) in general are shown in context menu:
244
245
246
247
248 + Object Browser: **Refresh** and **Find** operations are available.
249
250
251 + Schema Tree View: nothing.
252
253
254 + 2D Viewer: **Change background color** operation is available.
255
256
257
258
259
260 When a single object is selected in the Object Browser, its context popup menu contains all operations applicable to objects of the given type. Additionally, it contains **Expand all** command for expanding all collapsed items in the selected objects' sub-tree.
261
262 Specific operations available for each type of objects selected in the Object Browser are given in the Table 1 below.
263
264 .. |schema| image:: images/schema.png
265 .. |yacs| image:: images/yacs.png
266 .. |run| image:: images/run.png
267
268 +---------------------------+-----------+---------------------------------------------------------------------------------+
269 | **Selected object type**  | **Icon**  |     **Available context menu commands**                                         |
270 +===========================+===========+=================================================================================+
271 | YACS root item            | |yacs|    | Standard Salome **Refresh** and **Find** popup menu items.                      |
272 +---------------------------+-----------+---------------------------------------------------------------------------------+
273 | Schema                    | |schema|  | **New execution** - create a run schema object.                                 |
274 |                           |           |                                                                                 |
275 |                           |           | **Load execution state** - restore execution state for the                      |
276 |                           |           | selected schema from an XML file. It is useful if the user                      |
277 |                           |           | wants to continue the execution from a state saved                              |
278 |                           |           | previously. For more detailed information see                                   |
279 |                           |           | :ref:`save_restore_execution_state` section.                                    |
280 |                           |           |                                                                                 |
281 |                           |           | Standard Salome **Refresh** and **Find** popup menu items.                      |
282 +---------------------------+-----------+---------------------------------------------------------------------------------+
283 |Execution (run) of a schema| |run|     | **New edition** - create a run schema copy for edition.                         |
284 |                           |           | For more detailed information see :ref:`create_new_edition`                     |
285 |                           |           | section.                                                                        |
286 |                           |           |                                                                                 |
287 |                           |           | Standard Salome **Refresh** and **Find** popup menu items.                      |
288 +---------------------------+-----------+---------------------------------------------------------------------------------+
289
290 .. centered::
291   **Table 1. Context popup menus in the Object Browser**
292
293 When a single object is selected in the Tree View of a schema, its context popup menu contains all operations applicable to objects of the given type.
294
295 Specific operations available in the **edition mode** for each type of objects selected in the Tree View are given in the Table 2 below.
296
297 .. |container| image:: images/container.png
298 .. |component| image:: images/component.png
299 .. |block| image:: images/block_node.png
300 .. |switch| image:: images/switch_node.png
301 .. |loop| image:: images/loop_node.png
302 .. |node| image:: images/node.png
303 .. |inport| image:: images/in_port.png
304 .. |outport| image:: images/out_port.png
305 .. |control| image:: images/control_link.png
306 .. |data| image:: images/data_link.png
307 .. |stream| image:: images/stream_link.png
308
309 .. _Table_2:
310
311 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
312 | **Selected object type**       | **Icon**    |     **Available context menu commands**                                             |
313 +================================+=============+=====================================================================================+
314 |Schema                          | |schema|    |                                                                                     |
315 |                                |             |**Export** - export the selected schema into the                                     |
316 |                                |             |YACS XML file.                                                                       |
317 |                                |             |                                                                                     |
318 |                                |             |**Create a Data Type** (further version) - create a user                             |
319 |                                |             |defined data type inside the schema.                                                 |
320 |                                |             |                                                                                     |
321 |                                |             |**Create a Container definition** - create an empty container                        |
322 |                                |             |with the default name **containerN** (where N = 0,1,2,...)                           |
323 |                                |             |inside the current schema.                                                           |
324 |                                |             |                                                                                     |
325 |                                |             |**Create a node** - menu which contains submenu for creation                         |
326 |                                |             |different types of nodes inside the current schema.                                  |
327 |                                |             |                                                                                     |
328 |                                |             |**Execute** - execute the selected schema, i.e. create a run                         |
329 |                                |             |schema object.                                                                       |
330 |                                |             |                                                                                     |
331 |                                |             |**Copy** (further version) - copy a schema with all its                              |
332 |                                |             |components to the buffer.                                                            |
333 |                                |             |                                                                                     |
334 |                                |             |**Paste** (further version) - paste items (if any) from the                          |
335 |                                |             |buffer into the current schema.                                                      |
336 |                                |             |                                                                                     |
337 |                                |             |**Display** (further version) - display the content of the                           |
338 |                                |             |selected schema in the 2D Viewer.                                                    |
339 |                                |             |                                                                                     |
340 |                                |             |**Erase** (further version) - close the 2D Viewer of the                             |
341 |                                |             |selected schema.                                                                     |
342 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
343 |Data Types                      |             |**Edit** (further version) - gives the possibility to edit                           |
344 |                                |             |data types inside the current schema.                                                |
345 |                                |             |                                                                                     |
346 |                                |             |**Import a Data Type** - add a data type from the session                            |
347 |                                |             |catalog or data types catalog of another schema into the                             |
348 |                                |             |current schema.                                                                      |
349 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
350 |Containers                      |             |**Create a Container definition** - create an empty container                        |
351 |                                |             |with the default name **containerN** (where N = 0,1,2,...)                           |
352 |                                |             |inside the current schema.                                                           |
353 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
354 |SALOME container definition     | |container| |                                                                                     |
355 |                                |             |**Create a component instance definition --> SALOME** - create a new SALOME component|
356 |                                |             |and publish it in the Tree View.                                                     |
357 |                                |             |                                                                                     |
358 |                                |             |**Create a component instance definition --> SALOME Python** (further version) -     |
359 |                                |             |create a new SALOME Python component and publish it in the Tree View.                |
360 |                                |             |                                                                                     |
361 |                                |             |**Copy** (further version) - copy a container object.                                |
362 |                                |             |                                                                                     |
363 |                                |             |**Paste** (further version) - insert copied objects (if any SALOME components have   |
364 |                                |             |been copied) under the selected container.                                           |
365 |                                |             |                                                                                     |
366 |                                |             |**Delete** - delete a container object with all its content.                         |
367 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
368 |SALOME component instance       | |component| |                                                                                     |
369 |                                |             |**Create a node --> From catalog** - create a SALOME service node within the active  |
370 |                                |             |schema and publish it in the Tree View. In such a case the type of service node is   |
371 |                                |             |chosen from the catalog of services available inside the selected component.         |
372 |SALOME Python component instance| |component| |                                                                                     |
373 |                                |             |**Create a node --> Service inline** (further version) - create a service inline     |
374 |                                |             |node within the active schema and publish it in the Tree View.                       |
375 |                                |             |                                                                                     |
376 |                                |             |**Copy** (further version) - copy a component object.                                |
377 |                                |             |                                                                                     |
378 |                                |             |**Delete** - delete a component object with all its content.                         |
379 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
380 |CORBA component instance        | |component| |**Copy** (further version) - copy a component object.                                |
381 |                                |             |                                                                                     |
382 |                                |             |**Delete** - delete a component object with all its content.                         |
383 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
384
385 Node objects.
386
387 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
388 | **Selected object type**       | **Icon**    |     **Available context menu commands**                                             |
389 +================================+=============+=====================================================================================+
390 |Block node                      | |block|     |**Create a node** - menu which contains submenu for creation different types of      |
391 |                                |             |nodes inside the selected composed node.                                             |
392 |SWITCH node                     | |switch|    |                                                                                     |
393 |                                |             |**Create a loop** - menu which contains submenu for creation FOR, FOREACH or WHILE   |
394 |                                |             |loop nodes inside the corresponding level of the current schema hierarchy.           |
395 |                                |             |Such new created loop node has the selected node as a body.                          |
396 |                                |             |                                                                                     |
397 |                                |             |**Add to library** (further version) - save selected node to the selected directory  |
398 |                                |             |as XML file.                                                                         |
399 |                                |             |                                                                                     |
400 |                                |             |**Add control link to other node** - connect the selected node and the next selected |
401 |                                |             |node with the control flow link. The first selected node is the output node and the  |
402 |                                |             |second selected node is the input node for the new created control link.             |
403 |                                |             |                                                                                     |
404 |                                |             |**Copy** (further version) - copy the selected composed node object.                 |
405 |                                |             |                                                                                     |
406 |                                |             |**Delete** - delete the selected composed node object with all its content.          |
407 |                                |             |                                                                                     |
408 |                                |             |**Display** (further version) - display the composed node in the 2D Viewer.          |
409 |                                |             |                                                                                     |
410 |                                |             |**Erase** (further version) - erase the composed node from the 2D Viewer             |
411 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
412 |FOR loop node                   | |loop|      |**Create a body** - menu which contains submenu for creation different types of      |
413 |                                |             |nodes inside the selected loop node. Such new created node becomes a body of the     |
414 |                                |             |selected loop node.                                                                  |
415 |FOREACH loop node               | |loop|      |                                                                                     |
416 |                                |             |**Create a loop** - menu which contains submenu for creation FOR, FOREACH or WHILE   |
417 |                                |             |loop nodes inside the corresponding level of the current schema hierarchy.           |
418 |                                |             |Such new created loop node has the selected node as a body.                          |
419 |WHILE loop node                 | |loop|      |                                                                                     |
420 |                                |             |**Add to library** (further version) - save selected node to the selected            |
421 |                                |             |directory as XML file.                                                               |
422 |                                |             |                                                                                     |
423 |                                |             |**Add control link to other node** - connect the selected node and the next selected |
424 |                                |             |node with the control flow link. The first selected node is the output node and      |
425 |                                |             |the second selected node is the input node for the new created control link.         |
426 |                                |             |                                                                                     |
427 |                                |             |**Copy** (further version) - copy the selected loop node object.                     |
428 |                                |             |                                                                                     |
429 |                                |             |**Delete** - delete the selected loop node object with all its content.              |
430 |                                |             |                                                                                     |
431 |                                |             |**Display** (further version) - display the loop node in the 2D Viewer.              |
432 |                                |             |                                                                                     |
433 |                                |             |**Erase** (further version) - erase the loop node from the 2D Viewer.                |
434 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
435 |Node of any other type          | |node|      |**Create a loop** - menu which contains submenu for creation FOR, FOREACH or WHILE   |
436 |                                |             |loop nodes inside the corresponding level of the current schema hierarchy. Such new  |
437 |                                |             |created loop node has the selected node as a body.                                   |
438 |                                |             |                                                                                     |
439 |                                |             |**Add to library** (further version) - save selected node to the selected directory  |
440 |                                |             |as XML file.                                                                         |
441 |                                |             |                                                                                     |
442 |                                |             |**Add control link to other node** - connect the selected node and the next selected |
443 |                                |             |node with the control flow link. The first selected node is the output node and the  |
444 |                                |             |second selected node is the input node for the new created control link.             |
445 |                                |             |                                                                                     |
446 |                                |             |**Copy** (further version) - copy the selected node object.                          |
447 |                                |             |                                                                                     |
448 |                                |             |**Delete** - delete the selected node object.                                        |
449 |                                |             |                                                                                     |
450 |                                |             |**Display** (further version) - display the selected node in the 2D Viewer.          |
451 |                                |             |                                                                                     |
452 |                                |             |**Erase** (further version) - erase the selected node from the 2D Viewer.            |
453 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
454
455 Port and link objects.
456
457 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
458 | **Selected object type**       | **Icon**    |     **Available context menu commands**                                             |
459 +================================+=============+=====================================================================================+
460 |Input port                      | |inport|    |**Delete** - delete the selected input port object. This menu item is available only |
461 |                                |             |for input ports of non-service nodes.                                                |
462 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
463 |Output port                     | |outport|   |**Add dataflow link** - add the data (flow or stream) / control link from the        |
464 |                                |             |selected port to the other (selected later).                                         |
465 |                                |             |                                                                                     |
466 |                                |             |**Add data link** - add a simple data link from the selected port to the other       |
467 |                                |             |(selected later) without control link automatically added. This functionality is     |
468 |                                |             |needed inside loop nodes.                                                            |
469 |                                |             |                                                                                     |
470 |                                |             |**Delete** - delete the selected output port object. This menu item is available     |
471 |                                |             |only for output ports of non-service nodes.                                          |
472 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
473 |Control link                    | |control|   |**Delete** - delete the selected link object, update Tree View and 2D Viewer content |
474 |                                |             |according to this operation.                                                         |
475 |Data link                       | |data|      |                                                                                     |
476 |                                |             |                                                                                     |
477 |Datastream link                 | |stream|    |                                                                                     |
478 |                                |             |                                                                                     |
479 +--------------------------------+-------------+-------------------------------------------------------------------------------------+
480
481 .. centered::
482   **Table 2. Context popup menus in the Tree View of a schema, edition mode**
483
484 There are no any popup menus available on the objects selected in the Tree View of a schema in the **run mode** .
485
486 .. _set_active_schema_or_run:
487
488 Set active schema or run of a schema
489 ------------------------------------
490 Active schema is a YACS schema from the current study that is used implicitly in all YACS GUI operations working with a schema. Typically, a study can contain several YACS schemas and several executions (run) for a schema. For some YACS GUI operations such as creation of a node, it is convenient to add a new object (node) to the currently active schema.
491
492 YACS GUI allows the user to set a schema/run as active by double click on the schema/run object in the Object Browser or by switching between 2D Viewers showing different schemas/runs.
493
494 The active schema is used in creation/execution operations.
495
496