]> SALOME platform Git repositories - modules/yacs.git/blob - doc/schemaxml.rst
Salome HOME
0022328: [CEA 942] Worrying traces at YACS launch and SALOME closure
[modules/yacs.git] / doc / schemaxml.rst
1 .. _schemaxml:
2
3 Defining a calculation scheme in the XML format
4 =================================================
5 An XML file that describes a calculation scheme can contain the following information:
6
7  - definitions of data types
8  - definitions of containers
9  - definitions of elementary calculation nodes
10  - definitions of composite nodes
11  - definitions of connections between nodes
12  - initialisations
13
14 These definitions will be presented progressively. We will start with:
15
16  - the definition of data types
17  - the definition of a sub-set of elementary nodes
18  - the definition of non-datastream connections
19  - the definition of composite nodes
20
21 We will then add complements on:
22
23  - the definition of containers
24  - the definition of node properties
25  - the definition of datastream connections
26  - the definition of the remaining elementary nodes.
27
28 A calculation scheme is defined using the XML proc tag.  The simplest calculation scheme is as follows:
29
30 .. code-block:: xml
31
32   <proc>
33   </proc>
34
35 It contains no definition and it does nothing.
36
37 Definition of data types
38 ---------------------------------
39 It is impossible to define basic types other than existing types.  All basic types are predefined by YACS.  
40 However, aliases can be defined.  For example, an alias for the double type can be written:
41
42 .. code-block:: xml
43
44   <type name="mydble" kind="double"/>
45
46 we can then write mydble instead of double.
47
48 Object reference
49 '''''''''''''''''''''
50 The simplest way of defining an object reference type is:
51
52 .. code-block:: xml
53
54   <objref name="mesh"/>
55
56 The name attribute of the objref tag gives the name of the new type.  
57 The complete form to define this type would be:
58
59 .. code-block:: xml
60
61   <objref name="mesh" id="IDL:mesh:1.0/>
62
63 where id is the CORBA repository id of the corresponding SALOME object.  This attribute has a default value 
64 that is IDL:<type name>:1.0.
65
66 All that is necessary to define an object reference type derived from another type is to add the name of the basic type(s).
67 For example, for a derived mesh type, we can write:
68
69 .. code-block:: xml
70
71   <objref name="refinedmesh">
72     <base>mesh</base>
73   </objref>
74
75 If there are several basic types, we will write:
76
77 .. code-block:: xml
78
79   <objref name="refinedmesh">
80     <base>mesh</base>
81     <base>unautretype</base>
82   </objref>
83
84 As for CORBA, we can use namespaces to define types.  
85 For example, if the SALOME mesh type is defined in the myns namespace, we will write:
86
87 .. code-block:: xml
88
89   <objref name="myns/mesh"/>
90
91 Sequence
92 ''''''''''
93 To define a double sequence, we will write:
94
95 .. code-block:: xml
96
97   <sequence name="myseqdble" content="double"/>
98
99 All attributes of the sequence tag are compulsory.  The name attribute gives the name of the new type.  
100 The content attribute gives the name of the type of elements in the sequence.  
101 A sequence of sequences can be defined by:
102
103 .. code-block:: xml
104
105   <sequence name="myseqseqdble" content="myseqdble"/>
106
107 We can also define a sequence of object references by:
108
109 .. code-block:: xml
110
111   <sequence name="myseqmesh" content="refinedmesh"/>
112  
113 Structure
114 '''''''''''''
115 A structure is defined using a struct tag with member sub-tags for the definition of structure members.  
116 The following is an example definition:
117
118 .. code-block:: xml
119
120     <struct name="S1" >
121       <member name="x" type="double"/>
122       <member name="y" type="int"/>
123       <member name="s" type="string"/>
124       <member name="b" type="bool"/>
125       <member name="vd" type="dblevec"/>
126     </struct>
127
128 The member tag has 2 compulsory attributes, firstly name that gives the member name and secondly type that gives its type.  
129 The struct tag has a compulsory "name" attribute that gives the name of the type.
130
131 Definition of elementary calculation nodes
132 -----------------------------------------------
133 .. _xml_script_node:
134
135 Python script node
136 '''''''''''''''''''''
137 A Python script inline node is defined using the inline tag with the script sub-tag as in 
138 the following example:
139
140 .. code-block:: xml
141
142     <inline name="node1" >
143       <script>
144         <code>p1=10</code>
145       </script>
146       <outport name="p1" type="int"/>
147     </inline>
148
149 The name attribute (compulsory) of the inline tag is the node name. The Python script is given using the code sub-tag.  As many code 
150 lines as necessary are added.  A CDATA section can be used if the script contains unusual characters.  This also makes it possible 
151 to assure that only one code tag is used for a complete script.  
152 For example:
153
154 .. code-block:: xml
155
156   <script>
157     <code><![CDATA[a=0
158   p1= 10
159   print "a:",a
160   ]]>
161     </code>
162   </script>
163
164 The script calculates the variable p1 that is to be set as a node output variable.  The output port “p1” of the node is defined 
165 with the outport sub-tag.  This tag has two compulsory attributes:  name that gives the port name, and type that gives the supported 
166 data type.  This type must already be defined.  
167 To add an input data port, the import tag will be used instead of the output tag.
168
169 An example node with input and output ports:
170
171 .. code-block:: xml
172
173          <inline name="node1" >
174            <script>
175              <code>p1=p1+10</code>
176            </script>
177            <inport name="p1" type="int"/>
178            <outport name="p1" type="int"/>
179          </inline>
180
181 The node now receives p1 as the input variable, adds 10 to it and exports it as an output variable.
182
183 If you want to execute your script node on a remote container, you have to change the tag from **inline** to **remote**
184 and to add a tag **load** in the definition of the node as in the following example: 
185
186 .. code-block:: xml
187
188          <remote name="node1" >
189            <script>
190              <code>p1=p1+10</code>
191            </script>
192            <load container="cont1" />
193            <inport name="p1" type="int"/>
194            <outport name="p1" type="int"/>
195          </remote>
196
197 .. _xml_function_node:
198
199 Python function node
200 ''''''''''''''''''''''''
201 A Python function node is defined using the inline tag and the function sub-tag as in the following example:
202
203 .. code-block:: xml
204
205     <inline name="node1" >
206       <function name="f">
207         <code>def f(p1):</code>
208         <code>  p1=p1+10</code>
209         <code>  return p1</code>
210       </function>
211       <inport name="p1" type="int"/>
212       <outport name="p1" type="int"/>
213     </inline>
214
215 The name attribute (compulsory) of the inline tag is the node name.  The only difference from the Python script node is in 
216 the execution part (function tag instead of the script tag).  The function tag has a compulsory name attribute that gives 
217 the name of the function to be executed.  The body of the function is given with code tags as for the script.
218
219 If you want to execute your function node on a remote container, you have to change the tag from **inline** to **remote**
220 and to add a tag **load** in the definition of the node as in the following example: 
221
222 .. code-block:: xml
223
224     <remote name="node1" >
225       <function name="f">
226         <code>def f(p1):</code>
227         <code>  p1=p1+10</code>
228         <code>  return p1</code>
229       </function>
230       <load container="cont1" />
231       <inport name="p1" type="int"/>
232       <outport name="p1" type="int"/>
233     </remote>
234
235 .. _xml_service_node:
236
237 SALOME service node
238 ''''''''''''''''''''''''
239 As stated in :ref:`principes`, there are two ways of describing a SALOME service node.
240
241 The first definition form uses the service tag and the component and method sub-tags as in the following example:
242
243 .. code-block:: xml
244
245     <service name="node4" >
246       <component>AddComponent</component>
247       <method>Add</method>
248       <inport name="x" type="double"/>
249       <inport name="y" type="double"/>
250       <outport name="FuncValue" type="double"/>
251       <outport name="z" type="double"/>
252     </service>
253
254 The compulsory name attribute of the service tag gives the node name.  The component tag gives the name of the SALOME 
255 component to be used and method gives the name of the service to be executed.  The objective in this case is to execute 
256 the AddComponent (Add component) service that is located in SALOME example components.
257
258 The second definition form uses the service tag and the node and method sub-tags as in the following example:
259
260 .. code-block:: xml
261
262   <service name="node5" >
263     <node>node4</node>
264     <method>Setx</method>
265     <inport name="x" type="double"/>
266   </service>
267
268 The node tag references the previously defined node4 so as to use the same component instance for node4 and node5.
269
270 Definition of connections
271 -----------------------------
272 We will need to define a source node and/or a target node for all of the following concerning port connections and initialisations.  
273 In all cases, the name that will be used is the relative node name, considering the connection definition context.
274
275 Control link
276 ''''''''''''''''''
277 A control link is defined using the control tag as in the following example:
278
279 .. code-block:: xml
280
281  <control> 
282    <fromnode>node1</fromnode> 
283    <tonode>node2</tonode> 
284  </control>
285
286 The fromnode sub-tag gives the name of the node that will be executed before the node with the name given by the tonode sub-tag.
287
288 Dataflow link
289 ''''''''''''''''
290 A dataflow link is defined using the datalink tag as in the following example:
291
292 .. code-block:: xml
293
294   <datalink> 
295     <fromnode>node1</fromnode> <fromport>p1</fromport>
296     <tonode>node2</tonode> <toport>p1</toport>
297   </datalink>
298
299 The fromnode and fromport sub-tags give the name of the node and the output data port that will be connected to the node 
300 and to the port for which the names are given by the tonode and toport sub-tags.  The above link example states that the output 
301 variable p1 of node node1 will be sent to node node2 and used as an input variable p1.
302
303 Data link
304 ''''''''''
305 A data link is defined using the same datalink tag, but adding the control attribute and setting the value equal to false.
306 Example:
307
308 .. code-block:: xml
309
310   <datalink control="false"> 
311     <fromnode>node1</fromnode> <fromport>p1</fromport>
312     <tonode>node2</tonode> <toport>p1</toport>
313   </datalink>
314
315 Therefore the above dataflow link can also be written as follows:
316
317 .. code-block:: xml
318
319   <control> 
320     <fromnode>node1</fromnode> 
321     <tonode>node2</tonode> 
322   </control>
323   <datalink control="false"> 
324     <fromnode>node1</fromnode> <fromport>p1</fromport>
325     <tonode>node2</tonode> <toport>p1</toport>
326   </datalink>
327
328 .. _initialisation:
329
330 Initialising an input data port
331 -----------------------------------------------
332 An input data port can be initialised with constants by using the parameter tag, and the tonode, toport and value sub-tags.  
333 The toport tag gives the name of the input port of the node with the name tonode to be initialised.  
334 The initialisation constant is given by the value tag. 
335 The constant is encoded using the XML-RPC coding convention (http://www.xmlrpc.com/).
336 Example initialisation:
337
338 .. code-block:: xml
339
340     <parameter>
341       <tonode>node1</tonode> <toport>p1</toport>
342       <value><string>coucou</string></value>
343     </parameter>
344
345 Port p1 of node node1 is initialised with a character string type constant (“coucou”).
346
347 The following gives some examples of XML-RPC coding:
348
349 ============================ ==============================================
350 Constant                        XML-RPC coding
351 ============================ ==============================================
352 string "coucou"                ``<string>coucou</string>``  
353 double 23.                      ``<double>23</double>``        
354 integer 0                      ``<int>0</int>``
355 boolean true                   ``<boolean>1</boolean>``
356 file                           ``<objref>/tmp/forma01a.med</objref>``
357 list of integers               .. code-block:: xml 
358
359                                  <array> <data>
360                                  <value><int>1</int> </value>
361                                  <value><int>0</int> </value>
362                                  </data> </array>
363 structure (2 members)          .. code-block:: xml
364
365                                  <struct> 
366                                  <member> <name>s</name>
367                                  <value><int>1</int> </value>
368                                  </member>
369                                  <member> <name>t</name>
370                                  <value><int>1</int> </value>
371                                  </member>
372                                  </struct>
373
374 ============================ ==============================================
375
376 First example starting from previous elements
377 ------------------------------------------------------
378 A complete calculation scheme can be defined with definitions of nodes, connections and initialisations.
379
380 .. code-block:: xml
381
382   <proc>
383     <inline name="node1" >
384       <script>
385         <code>p1=p1+10</code>
386       </script>
387       <inport name="p1" type="int"/>
388       <outport name="p1" type="int"/>
389     </inline>
390     <inline name="node2" >
391       <script>
392         <code>p1=2*p1</code>
393       </script>
394       <inport name="p1" type="int"/>
395       <outport name="p1" type="int"/>
396     </inline>
397     <service name="node4" >
398         <component>ECHO</component>
399         <method>echoDouble</method>
400         <inport name="p1" type="double"/>
401         <outport name="p1" type="double"/>
402     </service>
403     <control> 
404       <fromnode>node1</fromnode> <tonode>node2</tonode> 
405     </control>
406     <control> 
407       <fromnode>node1</fromnode> <tonode>node4</tonode> 
408     </control>
409     <datalink> 
410       <fromnode>node1</fromnode> <fromport>p1</fromport>
411       <tonode>node2</tonode> <toport>p1</toport>
412     </datalink>
413     <datalink> 
414       <fromnode>node1</fromnode> <fromport>p1</fromport>
415       <tonode>node4</tonode> <toport>p1</toport>
416     </datalink>
417     <parameter>
418       <tonode>node1</tonode> <toport>p1</toport>
419       <value><int>5</int></value>
420     </parameter>
421   </proc>
422
423 The scheme includes 2 Python nodes (node1, node2) and one SALOME node (node4).  
424 Nodes node2 and node4 can be executed in parallel as can be seen on the following diagram.
425
426 .. image:: images/ex1.png
427    :align: center
428
429 Definition of composite nodes
430 -----------------------------------
431 The next step is to define composite nodes, either to modularise the scheme (Block) or to introduce control structures (Loop, Switch).
432
433 .. _xml_block:
434
435 Block
436 ''''''''
437 All the previous definition elements (except for data types) can be put into a Block node.  
438 A Block can be created simply by using a bloc tag with a compulsory name attribute, the name of which will be the block name.  
439 The next step is to add definitions in this tag to obtain a composite node that is a Block.
440
441 The following is an example of a Block that uses part of the above example:
442
443 .. code-block:: xml
444
445   <bloc name="b">
446     <inline name="node1" >
447       <script>
448         <code>p1=p1+10</code>
449       </script>
450       <inport name="p1" type="int"/>
451       <outport name="p1" type="int"/>
452     </inline>
453     <service name="node4" >
454         <component>ECHO</component>
455         <method>echoDouble</method>
456         <inport name="p1" type="double"/>
457         <outport name="p1" type="double"/>
458     </service>
459     <control> 
460       <fromnode>node1</fromnode> <tonode>node4</tonode> 
461     </control>
462     <datalink> 
463       <fromnode>node1</fromnode> <fromport>p1</fromport>
464       <tonode>node4</tonode> <toport>p1</toport>
465     </datalink>
466   </bloc>
467
468 This block can now be connected to other nodes like a simple elementary node.  
469 A few rules have to be respected:
470
471 - a control link crossing a block boundary cannot be created
472 - input and output data links crossing the boundary can be created provided that a context sensitive naming system is used (see :ref:`nommage`)
473
474 .. _xml_forloop:
475
476 ForLoop
477 '''''''''''
478 A Forloop is defined using a forloop tag.  This tag has a compulsory name attribute, the name of which is the node name and an 
479 optional nsteps attribute that gives the number of loop iterations to be executed.  If this attribute is not specified, the node will 
480 use the value given in its input port named nsteps.  The forloop tag must contain the definition of one and only one internal node 
481 that can be an elementary node or a composite node.  Forloops can be nested on several levels, for example.  If we would like to have 
482 more than one calculation node in the ForLoop, a Block will have to be used as the internal node.
483
484 Consider an example:
485
486 .. code-block:: xml
487
488     <forloop name="l1" nsteps="5">
489       <inline name="node2" >
490         <script>
491           <code>p1=p1+10</code>
492         </script>
493         <inport name="p1" type="int"/>
494         <outport name="p1" type="int"/>
495       </inline>
496     </forloop>
497
498 This represents a loop that will be executed 5 times on a Python script node.  
499 The rules to be respected to create links are the same as for the blocks.  To make iterative calculations, it must be possible 
500 to connect an output port of an internal node with an input port of this internal node.  This is done using a data link that is 
501 defined in the context of the Forloop node.
502
503 The following example applies to looping on port p1:
504
505 .. code-block:: xml
506
507   <forloop name="l1" nsteps="5">
508       <inline name="node2" >
509         <script>
510           <code>p1=p1+10</code>
511         </script>
512         <inport name="p1" type="int"/>
513         <outport name="p1" type="int"/>
514       </inline>
515       <datalink control="false">
516         <fromnode>node2</fromnode> <fromport>p1</fromport>
517         <tonode>node2</tonode> <toport>p1</toport>
518       </datalink>
519   </forloop>
520
521 If the number of steps in the loop is calculated, the nsteps input port of the loop will be used as in the following example:
522
523 .. code-block:: xml
524
525     <inline name="n" >
526       <script>
527             <code>nsteps=3</code>
528       </script>
529       <outport name="nsteps" type="int"/>
530     </inline>
531
532     <forloop name="l1" >
533       <inline name="node2" >
534         <script>
535           <code>p1=p1+10</code>
536         </script>
537         <inport name="p1" type="int"/>
538         <outport name="p1" type="int"/>
539       </inline>
540     </forloop>
541
542     <datalink> 
543       <fromnode>n</fromnode><fromport>nsteps</fromport>
544       <tonode>l1</tonode> <toport>nsteps</toport> 
545     </datalink>
546
547 Finally, if the internal node needs to known the current step of the loop it can use the loop output port
548 named "index".
549
550 .. _xml_whileloop:
551
552 WhileLoop
553 ''''''''''''
554 A WhileLoop is defined using the while tag.  It has a single compulsory attribute “name”, that carries the node name.  
555 The input port with name “condition” must be connected for the loop to be valid.
556
557 The following is an example of a While loop that increments the variable p1 until it exceeds the value 40:
558
559 .. code-block:: xml
560
561   <while name="l1" >
562     <bloc name="b">
563       <inline name="node2" >
564         <script>
565           <code>p1=p1+10</code>
566           <code><![CDATA[condition=p1 < 40.]]> </code>
567         </script>
568         <inport name="p1" type="int"/>
569         <outport name="p1" type="int"/>
570         <outport name="condition" type="bool"/>
571       </inline>
572       <datalink control="false">
573         <fromnode>node2</fromnode> <fromport>p1</fromport>
574         <tonode>node2</tonode> <toport>p1</toport>
575       </datalink>
576     </bloc>
577   </while>
578   <datalink control="false">
579     <fromnode>l1.b.node2</fromnode> <fromport>condition</fromport>
580     <tonode>l1</tonode> <toport>condition</toport>
581   </datalink>
582   <parameter>
583     <tonode>l1.b.node2</tonode> <toport>p1</toport>
584     <value><int>23</int> </value>
585   </parameter>
586
587 Obviously, nested while loops can be defined.
588
589 .. _xml_foreachloop:
590
591 ForEach loop
592 ''''''''''''''''
593 The ForEach loop is defined using the foreach tag.  It has 2 compulsory attributes:  name that bears the name of the ForEach 
594 node and type that gives the type of elements in the collection on which the loop will iterate.  A third optional attribute 
595 nbranch is used to fix the number of parallel branches that the loop will manage.  If this attribute is not supplied, the input 
596 data port of the loop named "nbBranches" must be connected.  
597 The foreach tag must contain the definition of one and only one internal node (elementary or composite).
598
599 The following is a minimal example of the ForEach loop:
600
601 .. code-block:: xml
602
603     <inline name="node0" >
604       <script>
605         <code>p1=[i*0.5 for i in range(10)]</code>
606       </script>
607       <outport name="p1" type="dblevec"/>
608     </inline>
609     <foreach name="b1" nbranch="3" type="double" >
610       <inline name="node2" >
611         <function name="f">
612             <code>def f(p1):</code>
613             <code>  p1= p1+10.</code>
614             <code>  print p1</code>
615             <code>  return p1</code>
616         </function>
617         <inport name="p1" type="double"/>
618         <outport name="p1" type="double"/>
619       </inline>
620     </foreach>
621     <inline name="node1" >
622       <script>
623         <code>print p1</code>
624       </script>
625       <inport name="p1" type="dblevec"/>
626     </inline>
627     <datalink>
628       <fromnode>node0</fromnode><fromport>p1</fromport>
629       <tonode>b1</tonode> <toport>SmplsCollection</toport>
630     </datalink>
631     <datalink>
632       <fromnode>b1</fromnode><fromport>evalSamples</fromport>
633       <tonode>b1.node2</tonode> <toport>p1</toport>
634     </datalink>
635     <datalink>
636       <fromnode>b1.node2</fromnode><fromport>p1</fromport>
637       <tonode>node1</tonode> <toport>p1</toport>
638     </datalink>
639
640 A first Python script node constructs a list of doubles.  This list will be used by the ForEach loop to iterate (connection 
641 to the SmplsCollection input port).  The internal node of the loop is a Python function node that adds 10 to the element that it processes.  
642 Finally, the results are collected and received by the Python node node1 in the form of a list of doubles.
643
644 .. _xml_switch:
645
646 Switch
647 ''''''''''
648 A Switch node is defined with the switch tag.  It has a single compulsory name attribute that carries the name of the node.  
649 Each case is defined with the case sub-tag.  The default case is defined with the default sub-tag.  
650 The case tag has a compulsory id attribute that must be an integer.  The default tag has no attribute.
651
652 A minimal switch example:
653
654 .. code-block:: xml
655
656     <inline name="n" >
657         <script>
658             <code>select=3</code>
659         </script>
660         <outport name="select" type="int"/>
661     </inline>
662
663     <switch name="b1">
664       <case id="3">
665         <inline name="n2" >
666           <script><code>print p1</code></script>
667           <inport name="p1" type="double"/>
668           <outport name="p1" type="double"/>
669         </inline>
670       </case>
671       <default>
672         <inline name="n2" >
673           <script><code>print p1</code></script>
674           <inport name="p1" type="double"/>
675           <outport name="p1" type="double"/>
676         </inline>
677       </default>
678     </switch>
679
680     <control> <fromnode>n</fromnode> <tonode>b1</tonode> </control>
681     <datalink> <fromnode>n</fromnode><fromport>select</fromport>
682                <tonode>b1</tonode> <toport>select</toport> </datalink>
683     <parameter>
684         <tonode>b1.p3_n2</tonode> <toport>p1</toport>
685         <value><double>54</double> </value>
686     </parameter>
687     <parameter>
688         <tonode>b1.default_n2</tonode> <toport>p1</toport>
689         <value><double>54</double> </value>
690     </parameter>
691
692 .. _xml_optimizerloop:
693
694 OptimizerLoop
695 ''''''''''''''''
696 An OptimizerLoop node is defined with the **optimizer** tag.  It has a compulsory name attribute that carries the name of the node.  
697 It has two other compulsory attributes (**lib** and **entry**) that define the C++ or Python plugin (parameters with same names).
698 It can have the attribute **nbranch** or an input port **nbBranches** to define the number of branches of the loop.
699 The OptimizerLoop ports (**nbBranches**, **algoInit**, **evalSamples**, **evalResults** and **algoResults**) need not be defined as they
700 are already defined at the creation of the node.
701
702 A minimal OptimizerLoop example:
703
704 .. code-block:: xml
705
706     <optimizer name="b1" nbranch="1" lib="myalgo2.py" entry="async" >
707       <inline name="node2" >
708         <script>
709     <code><![CDATA[print "input node:",p1
710     p1=5
711     ]]></code>
712         </script>
713         <inport name="p1" type="double"/>
714         <outport name="p1" type="int"/>
715       </inline>
716     </optimizer>
717     <datalink>
718       <fromnode>b1</fromnode><fromport>evalSamples</fromport>
719       <tonode>b1.node2</tonode> <toport>p1</toport>
720     </datalink>
721     <datalink control="false" >
722       <fromnode>b1.node2</fromnode><fromport>p1</fromport>
723       <tonode>b1</tonode> <toport>evalResults</toport>
724     </datalink>
725
726
727
728 Definition of containers
729 --------------------------------
730 YACS containers must be defined immediately after data types have been defined and before calculation nodes are defined.  
731 A container is defined using the container tag.  This tag has a single compulsory attribute that is the container name.  
732 Constraints on placement of the container are specified using properties defined with the property sub-tag.  
733 This tag has two compulsory attributes, the name and the value, that give the name of the constraint and its value in the 
734 form of a character string.
735
736 The following is an example of a container defined by the graphic user interface:
737
738 .. code-block:: xml
739
740    <container name="DefaultContainer">
741      <property name="container_name" value="FactoryServer"/>
742      <property name="cpu_clock" value="0"/>
743      <property name="hostname" value="localhost"/>
744      <property name="isMPI" value="false"/>
745      <property name="mem_mb" value="0"/>
746      <property name="nb_component_nodes" value="0"/>
747      <property name="nb_node" value="0"/>
748      <property name="nb_proc_per_node" value="0"/>
749      <property name="parallelLib" value=""/>
750      <property name="workingdir" value=""/>
751    </container>
752
753 Once containers have been defined, SALOME components can be placed on this container.  
754 This information simply has to be added into the definition of the SALOME service node using the load sub-tag.  
755 This tag has a single compulsory attribute named container that gives the name of the container on which the SALOME component will be located.
756
757 If the SALOME service defined above is to be placed on the DefaultContainer container, we will write:
758
759 .. code-block:: xml
760
761     <service name="node4" >
762       <component>AddComponent</component>
763       <load container="DefaultContainer"/>
764       <method>Add</method>
765       <inport name="x" type="double"/>
766       <inport name="y" type="double"/>
767       <outport name="FuncValue" type="double"/>
768       <outport name="z" type="double"/>
769     </service>
770
771 Node properties
772 -----------------------------
773 Properties can be defined for all elementary and composite nodes.  
774 However, they will only really be useful for SALOME service nodes.
775
776 A property is defined by adding a property sub-tag in the definition of a node.  
777 The property tag has 2 compulsory attributes, name and value, that carry the name of the property and its value in the form of a character string.
778
779 Example with a SALOME service node:
780
781 .. code-block:: xml
782
783     <service name="node4" >
784       <component>AddComponent</component>
785       <method>Add</method>
786       <property name="VERBOSE" value="2" />
787       <inport name="x" type="double"/>
788       <inport name="y" type="double"/>
789       <outport name="FuncValue" type="double"/>
790       <outport name="z" type="double"/>
791     </service>
792
793 In the case of a SALOME service node, the property is transmitted to the component and by default is set as an environment variable.
794
795 .. _xml_active_study:
796
797 Active study
798 --------------
799 To execute a schema in the context of a SALOME study, you have to set the **DefaultStudyID** property of the schema.
800
801 Example to execute the schema in the study with studyId 5:
802
803 .. code-block:: xml
804
805   <proc name="myschema">
806      <property name="DefaultStudyID" value="5"/>
807      ...
808   </proc>
809
810
811 Datastream connections
812 ----------------------------
813 Datastream connections are only possible for SALOME service nodes, as we have seen in :ref:`principes`.  Firstly, datastream ports 
814 have to be defined in the service node.  An input datastream port is defined with the instream subtag.  
815 This tag has 2 compulsory attributes, firstly name that gives the port name and secondly type that gives the supported data 
816 type (see :ref:`principes` for datastream types).  
817 The outstream tag is used instead of the instream tag to define an output datastream port.  
818 The property sub-tag is used with its two attributes name and value to define a property associated with the port.  
819 See :ref:`calcium` for a list of possible properties.
820
821 The following gives an example definition of the SALOME service node with datastream ports.  It is the DSCCODC component 
822 that can be found in the DSCCODES module in the EXAMPLES base.  Datastream ports are of the integer type with time dependence.
823
824 .. code-block:: xml
825
826     <service name="node1" >
827       <component>DSCCODC</component>
828       <method>prun</method>
829       <inport name="niter" type="int"/>
830       <instream name="ETP_EN" type="CALCIUM_integer">
831         <property name="DependencyType" value="TIME_DEPENDENCY"/>
832       </instream>
833       <outstream name="STP_EN" type="CALCIUM_integer">
834         <property name="DependencyType" value="TIME_DEPENDENCY"/>
835       </outstream>
836     </service>
837
838 The stream tag is used to define datastream links.  Fromnode and fromport sub-tags give the name of the node and the output 
839 datastream port that will be connected to the node and to the port, the names of which are given by the tonode and toport sub-tags.  
840 The parameters for a datastream link can be set with properties (see :ref:`calcium`).  
841 A property is defined with the property sub-tag.
842
843 The following is a more complete example with parameters set for datastream links.  There are two SALOME components with 
844 integer type datastream ports with time dependency (TIME_DEPENDENCY).  
845 The datastream connections use an explicit time scheme (TI_SCHEM).
846
847 .. code-block:: xml
848
849     <service name="node1" >
850       <component>DSCCODC</component>
851       <method>prun</method>
852       <inport name="niter" type="int"/>
853       <instream name="ETP_EN" type="CALCIUM_integer">
854         <property name="DependencyType" value="TIME_DEPENDENCY"/>
855       </instream>
856       <outstream name="STP_EN" type="CALCIUM_integer">
857         <property name="DependencyType" value="TIME_DEPENDENCY"/>
858       </outstream>
859     </service>
860
861     <service name="node2" >
862       <component>DSCCODD</component>
863       <method>prun</method>
864       <inport name="niter" type="int"/>
865       <instream name="ETP_EN" type="CALCIUM_integer">
866         <property name="DependencyType" value="TIME_DEPENDENCY"/>
867       </instream>
868       <outstream name="STP_EN" type="CALCIUM_integer">
869         <property name="DependencyType" value="TIME_DEPENDENCY"/>
870       </outstream>
871     </service>
872
873     <stream>
874       <fromnode>node2</fromnode> <fromport>STP_EN</fromport>
875       <tonode>node1</tonode> <toport>ETP_EN</toport>
876       <property name="DateCalSchem" value="TI_SCHEM"/>
877     </stream>
878
879     <stream>
880       <fromnode>node1</fromnode> <fromport>STP_EN</fromport>
881       <tonode>node2</tonode> <toport>ETP_EN</toport>
882       <property name="DateCalSchem" value="TI_SCHEM"/>
883     </stream>
884
885 Other elementary nodes
886 --------------------------------
887 SalomePython node
888 '''''''''''''''''''''''
889 This type of node is defined with the sinline tag.  It has a compulsory attribute name that carries the node name.  
890 It is defined using the same sub-tags as for the Python function node:  function for the Python code to be executed, inport 
891 and outport to define its input and output data ports.  
892 The placement on a container is defined using the load sub-tag as for the SALOME service node.
893
894 The following is an example of a call to the PYHELLO component from a SalomePython node:
895
896 .. code-block:: xml
897
898     <sinline name="node1" >
899       <function name="f">
900         <code>import salome</code>
901         <code>salome.salome_init()</code>
902         <code>import PYHELLO_ORB</code>
903         <code>def f(p1):</code>
904         <code>  print __container__from__YACS__</code>
905         <code>  machine,container=__container__from__YACS__.split('/')</code>
906         <code>  param={}</code>
907         <code>  param['hostname']=machine</code>
908         <code>  param['container_name']=container</code>
909         <code>  compo=salome.lcc.LoadComponent(param, "PYHELLO")</code>
910         <code>  print compo.makeBanner(p1)</code>
911         <code>  print p1</code>
912       </function>
913       <load container="A"/>
914       <inport name="p1" type="string"/>
915     </sinline>
916
917 The PYHELLO component will be placed on container A.  YACS selects the container.  The result of the choice is accessible 
918 in the python __container_from_YACS__ variable and is used by the node to load the component using the SALOME LifeCycle.
919
920 .. _xml_datain:
921
922 Datain node
923 ''''''''''''''''
924 This type of node is defined with the datanode tag.  It has a compulsory attribute name that carries the node name.  
925 Node data are defined using the parameter sub-tag.  This tag has two compulsory attributes, name and type, that give 
926 the data name and its type respectively.  The initial value of the data is supplied by the value sub-tag of the parameter tag 
927 using the XML-RPC coding (see :ref:`initialisation`).
928
929 The following is an example of a DataIn node that defines two double type data (b and c) and a file type data (f):
930
931 .. code-block:: xml
932
933     <datanode name="a">
934       <parameter name="f" type="file">
935          <value><objref>f.data</objref></value>
936       </parameter>
937       <parameter name="b" type="double" ><value><double>5.</double></value></parameter>
938       <parameter name="c" type="double" ><value><double>-1.</double></value></parameter>
939     </datanode>
940
941 .. _xml_dataout:
942
943 DataOut node
944 ''''''''''''''''
945 This type of node is defined with the outnode tag.  It has a compulsory attribute, name and an optional attribute, ref.  
946 The name attribute carries the node name.  The ref attribute gives the file name in which the values of results will be saved.  
947 The parameter sub-tag is used to define results of the node.  This tag has two compulsory attributes, name and type, that 
948 give the result name and its type respectively, and one optional attribute, ref.  
949 The ref attribute is only useful for file results. If it is defined, the result file will be copied into the file with the 
950 name given by the attribute.  Otherwise, the file will be a temporary file usually located in the /tmp directory (possibly on a remote machine).
951
952 The following is an example of a DataOut node that defines 5 results (a, b, c, d, f) of different types (double, int, 
953 string, doubles vector, file) and writes the corresponding values in the g.data file.  
954 The result file will be copied into the local file myfile:
955
956 .. code-block:: xml
957
958         <outnode name="out" ref="g.data">
959           <parameter name="a" type="double" />
960           <parameter name="b" type="int" />
961           <parameter name="c" type="string" />
962           <parameter name="d" type="dblevec" />
963           <parameter name="f" type="file" ref="myfile"/>
964         </outnode>
965
966 .. _xml_studyin:
967
968 StudyIn node
969 '''''''''''''''
970 This type of node is defined as a DataIn node with the datanode tag.  All that is necessary is to add the kind attribute 
971 with the “study” value.  The associated study is given by a property (property tag) named StudyID (the value of which is an integer).
972
973 The parameter sub-tag will be used to define the node data.  This tag has two compulsory attributes, name and type, that give the 
974 data name and type respectively.  The ref attribute gives the input into the study in the form of a SALOME Entry, or a 
975 path in the study tree structure.
976
977 The following is an example of a StudyIn node that defines 2 data (b and c) with types GEOM_Object and Boolean.  It is assumed 
978 that SALOME has loaded the study (with StudyID 1) into memory.  Data b is referenced by a SALOME Entry.  
979 The data c is referenced by a path in the study tree structure.
980
981 .. code-block:: xml
982
983     <datanode name="s" kind="study" >
984       <property name="StudyID" value="1" />
985       <parameter name="b" type="GEOM/GEOM_Object" ref="0:1:2:2"/>
986       <parameter name="c" type="bool" ref="/Geometry/Box_1"/>
987     </datanode>
988
989 .. _xml_studyout:
990
991 StudyOut node
992 ''''''''''''''''''
993 This type of node is defined as a DataOut node with the outnode tag and the name attribute.  
994 All that is necessary is to add the kind attribute with the value “study”.  
995 The optional ref attribute gives the name of the file in which the study will be saved at the end of the calculation.  
996 The associated study is given by a property (property tag) with name StudyID (the value of which is an integer).
997
998 The parameter sub-tag will be used to define the node results.  This tag has two compulsory attributes, name and type, that 
999 give the data name and type respectively.  The ref attribute gives the entry into the study in the form of a SALOME Entry, or 
1000 a path in the study tree structure.
1001
1002 The following gives an example of the StudyOut node that defines 2 results (a and b) of the GEOM_Object type.  The study used has 
1003 the studyId 1.  The complete study is saved in the study1.hdf file at the end of the calculation:
1004
1005 .. code-block:: xml
1006
1007    <outnode name="o" kind="study" ref="stud1.hdf">
1008      <property name="StudyID" value="1"/>
1009      <parameter name="a" type="GEOM/GEOM_Object" ref="/Geometry/YacsFuse"/>
1010      <parameter name="b" type="GEOM/GEOM_Object" ref="0:1:1:6"/>
1011    </outnode>
1012