6 YACS general principles
7 ===============================
8 A calculation scheme is constructed based on the calculation node concept.
9 A calculation node represents an elementary calculation that can be the local execution of a Python
10 script or the remote execution of a SALOME component service.
12 The calculation scheme is a more or less complex assembly of calculation nodes.
14 This assembly is made by connecting input and output ports of these calculation nodes.
16 Data are exchanged between nodes through ports. They are typed.
18 Composite nodes: Block, Loop, Switch are used to modularise a calculation scheme and define
19 iterative processes, parametric calculations or branches.
21 Finally, containers can be used to define where SALOME components will be executed (on a network or in a cluster).
26 ----------------------
27 Data exchanged between calculation nodes through ports are typed.
28 There are four categories of types: basic types, object references, sequences and structures.
29 User types can be defined by combining these basic elements.
30 Many types are predefined either by YACS or by the components used such as GEOM or SMESH.
34 There are 5 basic types: int, double, bool, string and file. They are predefined by YACS.
36 ================= =====================================
38 ================= =====================================
40 double for double reals
42 string for character strings
44 ================= =====================================
49 YACS adds a special type for exchanging generic Python objects between Python inline nodes (See :ref:`scriptnode`
50 and :ref:`functionnode`). The type is named **pyobj** and uses the pickle module to exchange Python objects.
51 Consequently only Python objects that are pickable could be used for YACS **pyobj** ports.
53 It's forbidden to define the object's type into the node, it should be defined in an external Python module. To avoid
54 problems with YACS, you should add the module into your **PYTHONPATH** before launching SALOME.
57 ''''''''''''''''''''''''''
58 Object references are used to type CORBA objects managed by SALOME components. In general, these types
59 are defined by the components that use them. All that is necessary to define a YACS object reference type, is to
60 give it a name and associate it with the CORBA Repository ID.
61 Some examples of pre-defined types are given below.
63 ================= ==============================
64 YACS type CORBA Repository ID
65 ================= ==============================
66 Study IDL:SALOMEDS/Study:1.0
67 SObject IDL:SALOMEDS/SObject:1.0
68 GEOM_Shape IDL:GEOM/GEOM_Object:1.0
69 MESH IDL:SALOME_MED/MESH:1.0
70 FIELD IDL:SALOME_MED/FIELD:1.0
71 ================= ==============================
73 Simple or multiple inheritance relations can be defined between these types.
74 The following gives an example of the MED component.
76 ================= ============================== =====================================
77 YACS type Base type CORBA Repository ID
78 ================= ============================== =====================================
79 FIELDDOUBLE FIELD IDL:SALOME_MED/FIELDDOUBLE:1.0
80 ================= ============================== =====================================
84 YACS also defines types for datastream ports:
86 ================= =======================================================
87 YACS type CORBA Repository ID
88 ================= =======================================================
89 CALCIUM_integer IDL:Ports/Calcium_Ports/Calcium_Integer_Port:1.0
90 CALCIUM_real IDL:Ports/Calcium_Ports/Calcium_Real_Port:1.0
91 CALCIUM_double IDL:Ports/Calcium_Ports/Calcium_Double_Port:1.0
92 CALCIUM_string IDL:Ports/Calcium_Ports/Calcium_String_Port:1.0
93 CALCIUM_logical IDL:Ports/Calcium_Ports/Calcium_Logical_Port:1.0
94 CALCIUM_boolean IDL:Ports/Calcium_Ports/Calcium_Logical_Port:1.0
95 CALCIUM_complex IDL:Ports/Calcium_Ports/Calcium_Complex_Port:1.0
96 ================= =======================================================
98 A list of available types can be obtained by consulting catalogs of SALOME components: GEOMCatalog.xml,
99 SMESHCatalog.xml, MEDCalatog.xml, etc. These catalogs are in the XML format that is described in :ref:`schemaxml`.
100 A view is also possible in the graphic user interface by viewing the components catalog.
104 A sequence type is used to type a list of homogenous elements. The type contained in the list is the same for
105 all elements. A sequence type is defined by giving it a name and specifying the type of elements in the sequence.
107 The SALOME KERNEL defines sequence types for basic types.
109 ================= ==============================
110 YACS type Type of elements
111 ================= ==============================
116 ================= ==============================
118 A sequence type can be defined for a sequence. In this case, the element type is a sequence type.
122 The structure type is used to type a data structured as a C structure. This data contains named and typed members.
123 A structure type is defined by giving it a name and specifying the list of members (name, type).
125 For example, the GEOM component defines a structure type with name “BCError” comprising a single member with name “incriminated”
126 and type “ListOfLong”. “ListOfLong” itself is a sequence of “int”.
130 A port can be considered as an interface of a node with the exterior. There are three types of port: control ports,
131 data ports and datastream ports. Each has different semantics.
134 ''''''''''''''''''''''''
135 This type of port is used to apply constraints on node execution chains. An elementary or composite node
136 usually has an input control port and an output control port. A node for which the input control port is connected
137 to the output control port of another node will not be executed until the second node is terminated.
140 ''''''''''''''''''''''''
141 This type of port is used to define data that will be used by a node when it is executed, and the data that will be produced
142 by the node at the end of its execution. A data port has a name, a direction (input, output) and the data contained in it
143 have a type. The order in which ports are defined is important because this order is used as the order of the arguments
144 during the call for SALOME component services.
146 In general, an elementary calculation node is executed as follows:
147 - control is given to the node through the input control port
148 - input data are acquired by the node through the input data ports
149 - the node is executed
150 - output data are provided to output ports
151 - control is returned by the node through the output control port.
153 An input data port can be initialized or connected to an output data port.
158 ''''''''''''''''''''''''
159 This type of port is used to exchange data during execution. Not all elementary nodes support this type of port.
160 For the moment, this type of port is only supported by nodes related to SALOME components. A datastream port has a name,
161 a direction (input, output) and a type. This type is not a data type directly but is rather the type of a CORBA object
162 that manages the data exchange (see :ref:`progDSC` for further information on how to implement a datastream port).
164 It is not a simple task to implement a datastream port so SALOME provides a ready made port called CALCIUM datastream
165 port. It has been designed to ease scientific code coupling. You can see more about these ports in :ref:`calcium`.
166 Only a limited set of data types can be used to define these ports (see :ref:`CALCIUM types<calciumtypes>`).
168 A CALCIUM port can be configured by way of properties. A property is a pair (name, value), where name is the name of the property and value
169 is a character string that gives its value. Following is the list of properties supported by CALCIUM ports :
171 .. tabularcolumns:: |p{2.5cm}|p{3.5cm}|L|
173 ================= ============================== =====================================
174 Property name Default value Description
175 ================= ============================== =====================================
176 DependencyType TIME_DEPENDENCY specify if data exchanged depend on time (TIME_DEPENDENCY) or on iteration (ITERATION_DEPENDENCY)
177 ================= ============================== =====================================
180 Elementary calculation nodes
181 -------------------------------------
182 An elementary calculation node represents a particular calculation function (for example multiplication of 2 matrices).
183 Every calculation node has a type. There can be one node type that executes a service of a SALOME component and another
184 node type that executes a piece of Python script.
185 Elementary calculation nodes are distributed into two categories: inline nodes that are executed mainly in the YACS coupler,
186 and service nodes that are executed remotely and correspond to the use of SALOME components.
188 Every calculation node has a name used as an identifier. This identifier must be unique in its definition context. A context is
189 defined by a calculation scheme or a composite node.
191 A calculation node has an input control port and an output control port. These control ports are connected through the control flow.
193 A calculation node usually has input and output data ports. The number and type of data ports is determined by the type of
194 calculation node. These data ports are connected through the data flow.
196 A calculation node may have properties. A property is a pair (name, value), where name is the name of the property and value
197 is a character string that gives its value.
201 Python script inline node
202 ''''''''''''''''''''''''''''''
203 A Python script node executes the Python code in a context in which variables are present with a value equal to the content
204 of input data ports when this execution is started. For example, if the node has an input data port named “matrix”, the
205 variable “matrix” will be present in the execution context of the script and its value will be the content of the port with the
206 same name. At the end of execution of the script, the output data ports will contain the values of variables with the same
207 name present in the execution context. These variables must necessarily be present.
209 When this type of node is an internal node in a loop, the execution context is reinitialised for each iteration of the loop.
211 This type of node is executed mainly in the YACS process but it can be executed in remote
212 processes (but only in YACS containers :ref:`containers`).
214 To create this type of node:
216 - from the GUI, see :ref:`inline_script`
217 - in a XML file, see :ref:`xml_script_node`
218 - from python interface, see :ref:`pyscript`
222 Python function inline node
223 ''''''''''''''''''''''''''''''
224 A Python function node executes a Python function, for which the arguments correspond to the node input data ports.
225 The name of the function to be executed is given by a parameter of the node. If such a node has 3 input data ports
226 named 'a', 'b', 'c' and the name of the function is 'f', execution of the node will correspond to calling f(a,b,c) where a, b and c
227 are the values of data ports with the same name.
229 Node output data are expected in return from the function in the form of a Python tuple. For example, if there are three
230 output data ports named 'x', 'y', 'z', the function should terminate by "return x,y,z" where x, y and z are values
231 for the output ports of the same name.
233 When this type of node is an internal node in a loop, the execution context is kept for every iteration of the loop, so
234 that variables can be reused during iterations.
236 This type of node is executed mainly in the YACS process but it can be executed in remote
237 processes (but only in YACS containers :ref:`containers`).
239 To create this type of node:
241 - from the GUI, see :ref:`inline_function`
242 - in a XML file, see :ref:`xml_function_node`
243 - from python interface, see :ref:`pyfunc`
248 ''''''''''''''''''''''''''''''
249 A SALOME service node executes a service of a SALOME component.
250 A service node can be defined in two ways:
252 1. by indicating the component type (GEOM, SMESH, etc.) and the service to be executed
253 2. by indicating an existing service node and the service to be executed
255 The second form exists because in some cases, it is required to use the state of the component at the end of execution of the
256 first service to execute the second service. The state of the component is kept in a component instance that is created
257 every time that the first form is used. If the second form is used, the existing instance is reused and a new component
258 instance will not be created.
260 A service node has input and output data ports and it may also have input and output datastream ports.
262 A service node is loaded and executed on a SALOME container. This placement is managed using the YACS container concept
263 (see :ref:`containers`) that is a slight abstraction of the SALOME container.
264 Placement of the SALOME service can be managed by the same name to denote the YACS container on which it is to be placed.
265 This is only possible with the first node definition form. If no placement information is given, the service will be placed
266 on the default container of the SALOME platform: FactoryServer container on the local machine.
268 The properties of a SALOME service node are converted into environment variables when the service is executed and can be retrieved
269 in the component with the method getProperties that returns an Engines::FieldsDict struct. The retrieved properties are the
270 properties of the node completed by the properties of the including Blocs.
272 To create this type of node:
274 - from the GUI, see :ref:`salome_service`
275 - in a XML file, see :ref:`xml_service_node`
276 - from python interface, see :ref:`pyservice`
279 ''''''''''''''''''''''''''''''
280 A SalomePython node is a Python function node to which YACS provides the information necessary to run SALOME
281 components and execute their services (in the Python execution context). It is the address of the container into
282 which the component is to be loaded and executed. This address is given in the "_container_from_YACS_" variable
283 in the form <machine name>/<container name>. Therefore, parameters can be set for this node using container placement
284 information like a SALOME service node.
286 Restriction: this type of node cannot execute a SALOME service with datastream ports. The node is seen by YACS
287 as being a Python node. Datastream ports are not managed.
290 ''''''''''''''''''''''''''''''
291 A Data node is used to define data (DataIn node) or to collect results (DataOut node) of a calculation scheme.
295 A DataIn node has output data ports only that are used to define input data for the calculation scheme. These data have a name (the port name), a type (the port type) and an initial value.
297 To create this type of node:
299 - from the GUI, see :ref:`datain_node`
300 - in a XML file, see :ref:`xml_datain`
301 - from python interface, see :ref:`py_datain`
305 A DataOut node only has input data ports that are used to store output results from the calculation scheme. These results have a name (the port name) and a type (the port type). If the result is a file, a name can be given to the file into which the result file will be copied.
307 All values of node results can be saved in a file at the end of the calculation.
309 To create this type of node:
311 - from the GUI, see :ref:`dataout_node`
312 - in a XML file, see :ref:`xml_dataout`
313 - from python interface, see :ref:`py_dataout`
316 ''''''''''''''''''''''''''''''
317 A Study node is used to relate the elements of a SALOME study to the data and results of a calculation scheme.
321 A StudyIn node has output data ports only. It is used to define data in the calculation scheme originating from a SALOME study. The associated study is given by its SALOME StudyID.
323 A port corresponds to data stored in the associated study. The data has a name (the port name), a type (the port type), and a reference that gives the entry into the study. This reference is either a SALOME Entry (for example 0:1:1:2) or a path in the SALOME study tree (for example, /Geometry/box_1).
325 To create this type of node:
327 - from the GUI, see :ref:`studyin_node`
328 - in a XML file, see :ref:`xml_studyin`
329 - from python interface, see :ref:`py_studyin`
333 A StudyOut node only has input data ports. It is used to store results in a SALOME study. The associated study is given by its SALOME StudyID.
335 A port corresponds to a result to be stored in an associated study. The result has a name (the port name), a type (the port type), and a reference that gives the entry into the study. This reference is either a SALOME Entry (for example 0:1:1:2) or a path in the SALOME study tree (for example, /Geometry/box_1).
337 The associated study may be saved in a file at the end of the calculation.
339 To create this type of node:
341 - from the GUI, see :ref:`studyout_node`
342 - in a XML file, see :ref:`xml_studyout`
343 - from python interface, see :ref:`py_studyout`
347 Connections between input and output ports of elementary or composite nodes are made by creating links between these ports.
350 ''''''''''''''''''''''''''''''
351 Control links are used to define an order in which nodes will be executed. They relate an output port of one node to an input port of another node. These two nodes must be defined in the same context. The definition of the link consists simply of giving the name of the input side node and the name of the output side node.
354 ''''''''''''''''''''''''''''''
355 Dataflow links are used to define a dataflow between an output data port for one node and an input data
356 port for another node. There is no need for these nodes to be defined in the same context. A dataflow link adds a control
357 link between the two nodes concerned or between the appropriate parent nodes to respect the rule for definition of the
358 control links. The dataflow link guarantees consistency between the dataflow and the execution order.
359 All that is necessary to define the link is to give the names of the input side node and port and the names of the output
361 The port types must be compatible (see :ref:`compatibility`).
364 ''''''''''''''''''''''''''''''
365 In some cases (mainly loops), it is useful to be able to define dataflows without defining the associated control link
366 as in the dataflow link. The datalink is then used. The definition is exactly the same as for the dataflow link.
367 The port types must be compatible (see :ref:`compatibility`).
372 ''''''''''''''''''''''''''''''
373 Datastream links are used to define a data stream between an output datastream port for one node and an input datastream port
374 for another node. These two nodes must be defined in the same context and it must be possible to execute them in parallel.
375 Therefore, there must not be direct or indirect control link between them. The link is defined by giving output node and port
376 names and input node and port names. The definition of the datastream links may be complemented by properties that
377 define parameters of the behaviour of the DSC port that makes the data exchange (see :ref:`progDSC`).
378 The port types must be compatible (see :ref:`compatibility`).
380 For CALCIUM datastream ports, links can be configured by way of properties that are listed here (more information about them
381 can be found in :ref:`calcium`):
383 .. tabularcolumns:: |p{3cm}|p{3cm}|L|
385 ==================== ============================== =====================================
386 Property name Default value Description
387 ==================== ============================== =====================================
388 DateCalSchem TI_SCHEM specify the temporal scheme (TI_SCHEM, TF_SCHEM, ALPHA_SCHEM) for ports with time dependency
389 StorageLevel infinite specify the maximum number of data kept in the destination port
390 Alpha 0.0 specify the coefficient of the ALPHA_SCHEM
391 DeltaT 1.e-6 tolerance to check if two dates are identical
392 InterpolationSchem L1_SCHEM specify the interpolation function (linear:L1_SCHEM or step:L0_SCHEM)
393 ExtrapolationSchem not defined specify the extrapolation function (E0_SCHEM or E1_SCHEM) in case of timeout (not implemented)
394 ==================== ============================== =====================================
396 As for other ports, CALCIUM port types must be compatible to be connected. But they must also have the same DependencyType
397 property (see :ref:`datastreamports`).
401 Compatibility of data types
402 '''''''''''''''''''''''''''''''''''''''''
403 A data, dataflow or datastream link may only be created if the data type of the output port is compatible with the data type
404 of the input port. There are three forms of compatibility:
406 - identity of types (for example double -> double)
407 - specialization of types (for example FIELDDOUBLE -> FIELD)
408 - type conversion (for example int -> double)
410 Compatibility by conversion
411 ......................................
412 Compatibility by conversion is applicable to basic types and to their derivatives (sequence, structure).
413 The following conversions are accepted:
415 ================= ============================== ====================================
416 YACS type Conversion possible into Comment
417 ================= ============================== ====================================
419 int bool true if int != 0 else false
420 ================= ============================== ====================================
422 The conversion is also applicable to types constructed as a sequence of ints that may be converted into a
423 sequence of doubles. YACS controls the conversion. This is also applicable to nested sequence of sequence, structure
424 of structure, sequence of structure structures and types, etc.
426 Compatibility by specialization
427 ......................................
428 The compatibility rule is expressed differently for data (or dataflow) links and datastream links.
430 For data (or dataflow) links, the type of output data port must be derived from (or identical to) the type of input
431 data port. For example, an output data port with a FIELDDOUBLE type may be connected to an input data port with
432 the FIELD type because the FIELDDOUBLE type is derived from the FIELD type (where FIELD is the basic type of FIELDDOUBLE).
434 The rule for datastream links is exactly the opposite of the rule for data links: the type of the input datastream port
435 must be derived from the type of the output port.
436 At the moment there is no derived datastream type. Therefore the only applicable rule is identity of types.
440 Control ports support 1 to N and N to 1 multiple links.
442 Data ports support 1 to N and N to 1 multiple links. 1 to N links do not create any problem. N to 1 links should be used with
443 caution, because the final result depends on the order in which the exchanges are made. This type of link will be reserved
444 for looping back in iterative loops. In this case, the order in which exchanges are made is perfectly reproducible.
446 Datastream ports also support 1 to N and N to 1 multiple links. 1 to N datastream links do not create any particular problems: data
447 exchanges are simply duplicated for all connected input ports. However, data exchanges for N to 1 datastream links will be
448 overlapped in the single input port. The final result may depend on the order in which exchanges are made.
451 --------------------------------
452 There are several types of composite nodes, namely block, loop and switch nodes.
453 A composite node may contain one or several nodes of an arbitrary type (elementary or composite).
454 By default, the set of node inputs and outputs making up the composite node are accessible from the outside.
455 It can be said that composite node inputs are composed of the set of internal node inputs. The same is applicable for outputs.
456 This is the white box concept.
460 This is a group of nodes with dependency links between internal nodes.
461 The Bloc is a white box (internal nodes are visible).
462 A calculation scheme is a Bloc. The Bloc is manipulated in a manner similar to an elementary node.
463 It is provided with a single input control port and a single output control port.
464 Consequently, two blocks connected through a dataflow data link will be executed in sequence, all nodes in the
465 first block will be executed before starting the second block.
467 A Bloc node may have properties. A property is a pair (name, value), where name is the name of the property and value
468 is a character string that gives its value. The properties of a Bloc are inherited by the nodes in the Bloc.
470 To create this type of node:
472 - from the GUI, see :ref:`block_node`
473 - in a XML file, see :ref:`xml_block`
474 - from python interface, see :ref:`py_block`
477 '''''''''''''''''''''
478 A loop is used to make iterations on an internal node.
479 This internal node may be a composite node or an elementary node.
480 Some internal node outputs may be explicitly looped back onto inputs of this internal node.
481 A ForLoop loop executes the internal node a fixed number of times. This number is given by a data port in the loop
482 named “nsteps” or by a parameter of the loop of the same name. The current step number is accessible through
483 an output port of the loop named "index".
485 To create this type of node:
487 - from the GUI, see :ref:`forloop_node`
488 - in a XML file, see :ref:`xml_forloop`
489 - from python interface, see :ref:`py_forloop`
493 A While loop executes the internal node as long as a condition is true.
494 The value of the condition is given by a data port of the loop named “condition”.
496 To create this type of node:
498 - from the GUI, see :ref:`whileloop_node`
499 - in a XML file, see :ref:`xml_whileloop`
500 - from python interface, see :ref:`py_whileloop`
503 ''''''''''''''''''''''
504 The ForEach node is also a loop, but it executes a loop body in parallel by iterating on one and only one data collection.
505 A data collection is of the sequence type.
506 An input data port of the ForEach node named “SmplsCollection” receives the data collection on which the loop iterates.
507 This data collection is typed. The data type on which the loop iterates is unique. The number of parallel branches managed
508 by the loop is fixed by a parameter of the loop (input port named "nbBranches").
509 If the collection size is 100 and this parameter is fixed at 25, the loop will execute 4 packets of 25 calculations in parallel.
510 The internal node can access the current iteration of the data collection through the output data port from the loop named “evalSamples”.
512 Typed data collections can be constructed at the output from the loop. All that is necessary is to connect an output data
513 port of the internal node to an input data port of a node outside the loop. The loop automatically constructs the data collection.
515 To create this type of node:
517 - from the GUI, see :ref:`foreachloop_node`
518 - in a XML file, see :ref:`xml_foreachloop`
519 - from python interface, see :ref:`py_foreachloop`
522 ''''''''''''''''''''''
523 The Switch node performs the conditional execution (among N) of a node (composite, elementary).
524 These nodes must have a minimum number of compatible inputs and outputs.
525 The switch condition (integer, real) is used to switch execution of one node among N.
526 The switch condition is given by an input data port of the Switch node named “select” or by a parameter of this node with the same name.
528 If the nodes are terminal (nothing is executed from their outputs), they do not need to have compatible outputs.
529 Output ports used at the node output must be compatible with each other (i.e. they must be derived from a common generic
530 type that can be used by another input node).
532 To create this type of node:
534 - from the GUI, see :ref:`switch_node`
535 - in a XML file, see :ref:`xml_switch`
536 - from python interface, see :ref:`py_switch`
538 The OptimizerLoop node
539 '''''''''''''''''''''''''
540 This node can be used to build an optimization process.
541 It has one and only one internal node as all the loop nodes. It is the internal node that is "optimized".
542 The optimization algorithm must be defined by the user. The main idea behind is : the OptimizerLoop iterates until
543 the user optimization algorithm says the process is ended (convergence or error). At each iteration, the
544 OptimizerLoop gives the data provided by the internal node to the algorithm. The algorithm returns a new sample
545 that is given by the OptimizerLoop to the internal node and so on until the end. In most optimization processes, the sample
546 is the variable (x) and the data that is returned by the internal node is the function to optimize (f(x)). Sometimes, the
547 gradient is also returned.
549 The definition of the optimization algorithm is done by way of plugin.
550 The plugin can be a C++ plugin implemented in a dynamic library (.so file) or a Python plugin implemented in a Python module (.py).
551 It is possible to implement two kinds of algorithm : synchronous or asynchronous.
552 The implementation of an optimization algorithm as a plugin is described in :ref:`optimizationplugin`.
554 The plugin is defined by 2 parameters :
556 - **lib** the file name of the dynamic library or of the Python module. The name of the dynamic library must be given without
557 extension (.so) but the name of the Python must be given with extension (.py).
558 - **entry**, the name of an entry point in the dynamic library or in the Python module that will return the algorithm plugin
559 factory (see :ref:`optimizationplugin` for more informations)
561 The node has five ports:
563 - **algoInit**, an input port that takes an object used for the initialization of the algorithm
564 - **evalSamples**, an output port that gives the samples in the optimization process
565 - **evalResults**, an input port that collects the results given by the internal node
566 - **nbBranches**, an input port that can be used to parallelize the optimization process as in the ForEach node (number of
567 branches). Most of a time, the optimization process is sequential so the number of branches will be 1, but in some cases
568 it is possible to parallelize the process so the number of branches will be greater than 1.
569 - **algoResults**, an output port that gives the results of the optimization algorithm
571 To create this type of node:
573 - from the GUI, see :ref:`optimizerloop_node`
574 - in a XML file, see :ref:`xml_optimizerloop`
575 - from python interface, see :ref:`py_optimizerloop`
582 ---------------------
584 **WARNING !** Their are two notions of containers in the Salome world that must be clearly distinguished.
586 - YACS container, that will be explained extensively here.
587 - KERNEL container which is a single process managed by the plateform that may be executed on any resource in the resource catalog of the current SALOME application.
588 This single process can perform a set of jobs.
590 To avoid misleading, in this chapter, container word will be systematically explicited.
592 YACS Container objects are used in the definition of a scheme to define constraints on the placement of some tasks (run remotely) of a YACS scheme. YACS containers objects are parts of a scheme as nodes are.
593 So the job of the conceptor of a YACS scheme is to correctly allocate remotely executed elementary nodes over YACS container objects of the scheme to respect the states of KERNEL components running on KERNEL container and the states of KERNEL container itself.
594 Exactly one YACS container is attached (directy or indirectly through YACS components) to elementary nodes (or tasks) that can be run remotely.
596 The tasks (elementary nodes) that can be run remotely are ( or the tasks that are attached to a YACS container are ) :
598 - Python script node.
599 - Python function node.
602 So all elementary nodes of a scheme (whatever their types in the list above) that are supposed to be executed remotely are supposed to be attached to a set of YACS container objects.
604 YACS container can be seen as a placement request at edition time of a scheme. **During the execution of a scheme, a YACS container is incarnated into one or several KERNEL containers** depending on the type of the YACS container.
606 Presently, there are 3 types of containers that incarnates the 3 different mapping strategies between YACS container and KERNEL container :
608 - Mono YACS container : The most simple. There is exactly one KERNEL container attached on one mono YACS container. **WARNING**, this type of YACS container can be dangerous into the context of foreach because several tasks can be invoked in parallel inside of a same process that can leads to problem if the service owning this YACS container is not thread safe. This type of YACS container leads to no special treatment from Executor point of view.
609 - Multi YACS container : There is as KERNEL containers attached on a multi YACS container as there are YACS component instances attached to it in the scheme. In the context of foreach, it can leads to a pool of KERNEL containers attached to a YACS container. The KERNEL container is obtained using as key the pointer to the YACS component object. This type of YACS container leads to no special treatment from Executor point of view.
610 - HP YACS container : HP stands for Homogeneous Pool of KERNEL container. A HP YACS container is mapped to a fixed size set of KERNEL containers. This pool is homogeneous which means that each of the KERNEL container inside the pool can be used indifferentely (and will be used during execution) by the nodes attached to a same HP YACS container. The KERNEL container is obtainer using the requesting node. Contrary to the 2 YACS containers type above, the Executor is active with that type of YACS container by performing, if needed, a cutoff towards remotely executed tasks list in READY state regarding the availability of different YACS HP containers.
612 To create containers from TUI, see :ref:`py_container_creation`.
614 All of these 3 types of YACS containers are sharing a common important features : set of properties.
616 Properties are a set of (key,value) pairs which are designed to be forwarded directly to the KERNEL (expected "name" property and "attached_on_cloning" property, see :ref:`containers_aoc_property`) when a task attached to the YACS container has LOAD status during the execution of a scheme.
618 The array below presents extensively the list of available keys and corresponding values expected that are common to 3 types of YACS container.
619 Those properties (excepted "name" and "attached_on_cloning" property) are the way to specify the request to the KERNEL when the mapping will be requested by the Executor of YACS.
620 For your information the dump in XML file of each YACS container object contains exclusively those (key,value) pairs.
622 - To set properties from GUI to a YACS container, see :ref:`pp_for_container`.
623 - To set properties from python interface, see :ref:`py_container`.
625 .. note:: One important property is the "container_name" that must not be confused with property "name". "name" is relative to YACS container only (that will appear in XML file)
626 "container_name" is a part of the request at run time when attaching KERNEL container with YACS container. Warning, the behaviour of mapping is sensitive to the fact that
627 "container_name" property is empty or not.
629 .. note:: HP YACS containers have 2 additionnal properties compared to Mono and Multi YACS Container. The first one is the "SizeOfPool" that defines the size of the set of KERNEL containers. The second one is "InitializeScriptKey" which contains the string of a python code that will be passed to each of the KERNEL containers of the pool to initialize it (if necessary).
631 .. tabularcolumns:: |p{3cm}|p{3cm}|p{10cm}|
633 =================== ============= =============================================
634 Name Type Type of constraint
635 =================== ============= =============================================
636 name string if given imposes the resource to use. If not given, the resource manager will try
637 to find the best resource according to the constraints given by the other attributes.
638 attached_on_cloning bool By default false for Multi and Mono YACS containers. Always true and not settable for HP containers. See :ref:`containers_aoc_property`
639 container_name string if given imposes the SALOME container name
640 hostname string if given imposes the machine (constraint used if name is not given)
641 policy "best", Choose the best or the first or the next in
642 "first" or the list of resources, once other criteria
643 "cycl" have been applied. By default, YACS uses the “altcycl” policy
644 "altcycl" that selects the next resource in the list of known resources (constraint used if name is not given)
645 OS string if given restricts the choice of the OS (constraint used if name is not given)
646 workingdir string if given specifies the execution directory.
647 By default, the YACS run directory will be used
648 on the local machine and the $HOME directory will be used on remote machines.
649 isMPI bool indicates if the container has to support MPI
650 mem_mb int minimum requested memory size (constraint used if name is not given)
651 cpu_clock int minimum requested CPU speed (constraint used if name is not given)
652 nb_proc_per_node int number of processors by node (constraint used if name is not given)
653 nb_node int number of nodes (constraint used if name is not given)
654 nb_component_nodes int ??
655 parallelLib string ??
656 =================== ============= =============================================
658 When using the "best" policy, a price is computed for each resource based on some criteria and the resource with the best price is chosen.
659 The list of these criteria, from the most important to the least important, is:
660 1. Number of processors (nb procs). For a resource, it is given by "nb_node" * "nb_proc_per_node".
661 2. Number of nodes (nb nodes)
662 3. Number of processors by node (nb proc/node)
663 4. CPU frequency (cpu clock)
665 Undefined criteria are ignored. The price of each criterion is:
666 - the highest (3) if the expected value of the criterion is equal to the value of the criterion in the resource
667 - medium (2) if the expected value of the criterion is less than the value of the criterion in the resource
668 - the lowest (1) if the expected value of the criterion is higher than the value of the criterion in the resource
670 .. _containers_aoc_property:
672 Attached On cloning property
673 ''''''''''''''''''''''''''''''
675 A specific chapter is dedicated to that property of YACS container. This property is only used by YACS not forwarded at all to KERNEL. The value of this property is either False or True.
676 This property is writable and by default set to false for mono YACS container and multi YACS container. For HP YACS container this property is not writable and set to true.
677 This property controles the behaviour of the YACS container it belongs to when cloning is triggered.
679 A cloning is triggered during execution of a scheme for ForEachLoop and OptimizerLoop nodes of the scheme.
680 In fact, when a ForEachLoop or OpmizerLoop node is executed it immediatly clones nbOfBranches times the node inside it (and performs right connections on these copies) using Node::clone method that recurvively creates a deep copy of the node.
682 The question is : What is done for deep copied elementary nodes executed remotely ? Are the copied node and base node share the same YACS container object or Are the copied node is lying on a deep copy of the YACS container of the base node ?
684 It is here where "attached_on_cloning" property of YACS container is considered. If false, a deep copy of YACS container is done when cloning of remotely executed node is done. If true, the cloned node and the node itself will share the same YACS container.
686 So it appears natural that HP YACS containers have this property set to true because it is the aim of HP YACS container to share a same pool of workers accross all the nodes especially in the ForEachLoop or OptimizerLoop context.
688 .. _catalogResources:
690 The resources catalog
691 ''''''''''''''''''''''''''''''''''''''''''
692 The list of resources (machines and SALOME installations) known to SALOME is given in the resources catalog, the CatalogResources.xml file
693 that must be located in the directory of the SALOME application used.
694 This file is in the XML format. Each resource is described with the **machine** tag that has several attributes that characterize it.
696 .. tabularcolumns:: |p{3cm}|p{3cm}|p{10cm}|
698 ================================== =========================== ==============================================
699 Characteristic XML attribute Description
700 ================================== =========================== ==============================================
701 resource name name the resource name
702 computer name hostname the complete machine name: this is the key that uniquely determines the machine
703 (for example : "nickel.ccc.cea.fr")
704 access protocol protocol "ssh" (default), "rsh" or "sh"
705 Type type "single_machine" (default) or "cluster"
706 user name userName user name to be used to connect to the machine
709 clock frequency CPUFreqMHz
710 Number of nodes nbOfNodes
711 Number of processors per node nbOfProcPerNode
712 SALOME application appliPath directory of the SALOME application to be used on this machine
713 mpi implementation mpi indicates which MPI implementation is used on this machine
716 batch manager batch if the machine has to be used through a batch system, gives the
717 name of the batch manager
718 ("pbs", "lsf", "slurm").
720 Can Launch Batch Jobs canLaunchBatchJobs Indicate if the resource can be used to launch
721 batch jobs, through the JOBMANAGER module for
722 instance. It can be "false" (default) or
724 Can Run Containers canRunContainers Indicate if the resource can be used to run
725 containers. It must be set to "true" if you
726 want to use this resource with YACS. It can be
727 "false" (default) or "true".
728 ================================== =========================== ==============================================
730 The list of SALOME modules of the resource can also be indicated. By default, SALOME assumes that all components
731 requested by YACS are present.
733 If only some components are available within a resource, the list of components must be specified.
734 This list can be specified with the sub-tag **component** that has two attributes : **name** (the name of the component)
735 and **moduleName** (the name of the module) that is optional. You can use also the sub-tag **modules** that is provided
736 for compatibility with older versions. If the **modules** sub-tag is used, a component with the same name as
737 the moduleName attribute is added to the list.
739 The following is an example of a resource catalog:
743 <!DOCTYPE ResourcesCatalog>
745 <machine hostname="is111790" name="is111790"
746 OS="LINUX" CPUFreqMHz="2992" memInMB="1024"
747 protocol="rsh" type="single_machine"
748 nbOfNodes="1" nbOfProcPerNode="1"
749 canRunContainers="true">
751 <machine hostname="is111915" name="is111915"
752 OS="LINUX" CPUFreqMHz="2992" memInMB="1024"
753 protocol="ssh" type="single_machine"
754 nbOfNodes="1" nbOfProcPerNode="1"
755 appliPath="SALOME/Run"
756 canRunContainers="true">
757 <modules moduleName="GEOM"/>
758 <component name="SMESH"/>
759 <component name="VISU" moduleName="VISU"/>
766 -----------------------------
767 The possible states of a node when a calculation scheme is being edited are as follows:
769 =================== =============================================
771 =================== =============================================
772 READY The node is valid, ready to be executed
773 INVALID The node is invalid, the scheme cannot be executed
774 =================== =============================================
776 A node may be in the following states during execution of a calculation scheme:
778 =================== =============================================================
780 =================== =============================================================
781 READY the node is valid, ready to be executed
782 TOLOAD the component associated with the node can be loaded
783 LOADED the component associated with the node is loaded
784 TOACTIVATE the node can be executed
785 ACTIVATED the node is being executed
786 DONE execution of the node is finished with no error
787 ERROR execution of the node is finished with error
788 FAILED node in error because previous nodes were in error
789 DISABLED execution of the node is disabled
790 PAUSE execution of the node is paused
791 =================== =============================================================
795 Context sensitive naming of nodes
796 -------------------------------------
797 We have seen that elementary and composite nodes have a unique name in the definition context that corresponds
798 to the parent node (calculation scheme or composite node). Several sorts of naming are used to denote nodes in all
801 - local naming: this is the name of the node in its definition context
802 - absolute naming: this is the name of the node seen from the highest level of the calculation scheme
803 - relative naming: this is the name of a node seen from a parent composite node.
805 The general rule is that absolute and relative names are constructed by concatenating local names of the node and
806 its parents, and separating them with dots.
808 Consider the example of an elementary node with name “n” defined in a block name “b”, that is itself defined in a block name “c”
809 itself defined at the highest level of the scheme. The local name of the node is “n”. The absolute name is “c.b.n”.
810 The relative name in block “c” is “b.n”.
812 The same rule is applied for naming ports. If node “n” has a port name “p”, then all that is necessary to obtain the port
813 name is to add “.p” to the node name.
815 There is an exception to this rule that concerns the Switch node. In this case, it is necessary to take account of case
816 that is not a genuine node. If it is said that block “b” in the previous example is a switch that has a case with a
817 value of 1 and a default case, then the absolute name of node “n” in the case 1 will be “c.b.p1_n” and the absolute name of the node in
818 the default case will be “c.b.default_n”.
822 A schema can be executed without using the SALOME study manager. But when a schema must be executed in the context
823 of a SALOME study, it is possible to specify the studyId to use.
825 The way to do that is to set the schema property **DefaultStudyID** to the study id.
827 In the GUI, this is set automatically to the current active studyId.
828 For execution in console mode, see :ref:`xml_active_study`
834 Every node has an associated error report if its state is INVALID, ERROR or FAILED. This report is in the XML format.
836 Elementary nodes produce a simple report that contains a single (error) tag with 2 attributes:
838 - node: that gives the node name
839 - state: that indicates its state.
841 The tag content is the text of the error. For a Python script node, this will usually be the traceback of the exception
842 encountered. For a service node, it will be either the content of a SALOME exception or the content of a CORBA exception.
844 Composite nodes produce a composite report contained in a tag with the same name (error) with the same two node and state
845 attributes. The tag contains all error reports for erroneous child nodes.
847 The following shows an error report for a division by zero in a Python node contained in a loop:
851 <error node= proc state= FAILED>
852 <error node= l1 state= FAILED>
853 <error node= node2 state= ERROR>
854 Traceback (most recent call last):
855 File "<string>", line 1, in ?
856 ZeroDivisionError: integer division or modulo by zero
862 Execution trace files
863 --------------------------
864 For each execution several trace files are produced:
866 - the ouput file of the YACS process that executes the scheme
867 - a trace file that reports all the events that have occured during the execution
868 - the output files of all launched containers
870 YACS process output file
871 ''''''''''''''''''''''''''''''''''''''''''
872 In this file you will find all the outputs of the inline nodes and error reports (:ref:`errorreport`).
874 YACS events trace file
875 ''''''''''''''''''''''''''''''''''''''''''
876 The file name is: traceExec_<scheme name>, in which <scheme name> is the name given to the scheme.
878 Each line of the file represents an event related to a node. It contains two character strings.
879 The first is the node name. The second describes the event.
881 The following shows a trace for the same example as above::
892 l1.node2 connectService
894 l1.node2 start execution
895 l1.node2 end execution ABORT, Error during execution
896 l1.node2 disconnectService
898 Container output file
899 ''''''''''''''''''''''''''''''''''''''''''
900 In this file you will find all the outputs of the SALOME components (calculation codes).
901 Most of the time, the file name is : /tmp/<yacs pid>_<container name>_<container id>_<computer name>_<user name>.log, where:
903 - <yacs pid> is the id of the YACS process
904 - <container name> is the name given to the container in :ref:`containers`.
905 - <container id> is an internal id for the container
906 - <computer name> is the name of the computer on which the container runs
907 - <user name> is the login name of the user on the container computer
909 By default this file is put in the /tmp directory. It is possible to change that default by setting the SALOME_TMP_DIR environment
910 variable to a different location.
912 If the SALOME component uses CALCIUM datasream ports, this file will also contain a trace of all the calls
913 to the CALCIUM library.
914 This trace has the following form::
916 Elapsed time | Request | Container | Instance | Port | Error | Infos
917 34:54:23:112 | CP_CD | clic6_23_B_0x1e080 | SOL_inst_1 | | |
918 34:54:23:134 | WRITE | clic6_23_B_0x1e080 | SOL_inst_1 | temp | | i=0
919 34:54:23:162 | WRITE | clic6_23_B_0x1e080 | SOL_inst_1 | tpi | | i=0
920 34:54:23:162 | BEGIN_READ | clic6_23_B_0x1e080 | SOL_inst_1 | puis | | i=0
921 34:54:23:174 | END_READ | clic6_23_B_0x1e080 | SOL_inst_1 | puis | | read i=0
922 34:54:23:174 | BEGIN_READ | clic6_23_B_0x1e080 | SOL_inst_1 | tfi | | i=0
924 - column "Elapsed time" gives the elapsed time since a reference time that is given by the computer system (January 1, 1970 on Linux).
925 The time format is: hours:minutes:seconds:milliseconds.
926 - column "Request" gives the name of the CALCIUM call.
927 - column "Container" gives the container identification (<computer name>_<yacs pid>_<container name>_<container_id>)
928 - column "Instance" gives the name of the SALOME component that has issued the call
929 - column "Port" gives the name of the port on which the request is done
930 - column "Error" gives the error description if there is one
931 - column "Infos" gives more information about the request or the error
933 By default, the trace is produced in the container output file. It is possible to disable the trace by setting
934 the DSC_TRACELEVEL environment variable to 0 (export DSC_TRACELEVEL=0, for bash shell). It is also possible to redirect
935 the trace in an another file by setting the DSC_TRACE environment variable to 1 (export DSC_TRACE=1, for bash shell).
936 In this case the trace is written in a file with name : $SALOME_TMP_DIR/<container identification>.tce.
941 When YACS executes a schema, it starts new containers or uses existing containers. When the execution is finished, YACS can shutdown (or stop)
942 containers but the user can control how these containers are shutdown.
944 There are several level of shutdown:
946 - level 0: nothing is shutdown
947 - level 1: shutdown all new containers not named by the user
948 - level 2: same as level 1 plus all new containers named by the user
949 - level 3: same as level 2 plus all existing containers used by the schema
951 To shutdown a schema:
953 - from GUI, see :ref:`shutdown`
954 - from console, see :ref:`xml_shutdown`
958 YACS general architecture
959 ------------------------------
961 YACS module implements API of a full SALOME module only for the schema execution. The schema edition is done in the GUI process alone.
962 For execution, YACS has a CORBA servant that implements Engines::EngineComponent CORBA interface (see SALOME KERNEL IDL interfaces).
963 YACS GUI and YACS CORBA engine share YACS core libraries (engine and runtime): GUI uses them at schema design time, then a schema XML
964 file is saved and passed to YACS CORBA API, and finally YACS core libraries execute the schema at YACS CORBA server side.
966 YACS GUI differs from standard full SALOME modules (such as Geometry or Mesh) in that it does not use SALOMEDS objects to create
967 Object Browser representation of its data, and creates this representation in a way light SALOME modules do.
968 This is done in order to avoid publishing lots of objects in SALOMEDS study just to create visual representation of data and
969 thus to improve GUI performance.
971 YACS architecture scheme is shown on the picture below.
973 .. image:: images/general_architecture_0.jpg
976 The YACS module is a SALOME module with one document (study) per desktop.
978 YACS is composed of several packages. The main things are mentioned in the next sections.
981 '''''''''''''''''''''''
982 Bases package contains common base classes (exception, threads, etc.) and constants.
985 '''''''''''''''''''''''
986 Engine package consists of calculation schema generic classes (calculation nodes, control nodes, control and data
989 Engine is in charge to:
996 graphs independently from the context (i.e. Runtime) the graph is destined to run.
998 SALOME Runtime package
999 '''''''''''''''''''''''
1000 Runtime package provides implementation of YACS generic calculation nodes for SALOME platform.
1001 Runtime exists in a given Context.
1003 Runtime is in charge to:
1005 * treat physically the basic execution of elementary tasks in a given context,
1006 * transfer data in this context,
1007 * perform the physical deployment of the execution.
1009 Runtime simply appears in Engine as an interface that a concrete Runtime must implement to be piloted by Engine.
1011 The SALOME Runtime implements following nodes:
1013 * Inline function node. A function inline node is implemented by a Python function.
1014 * Inline script node. A script inline node is implemented by a Python script.
1015 * Component service node. This is a calculation node associated with a SALOME component service.
1016 * CORBA reference service node. Reference service node for CORBA objects. This is a node that executes a CORBA service.
1017 * CPP node. This is a C++ node (in process component), i.e. local C++ implementation - single process.
1019 XML file loader package
1020 ''''''''''''''''''''''''''''''''
1021 This is XML reader for generic calculation schema.
1023 XML file loader provides
1025 * a possibility to load a calculation schema in memory by reading and parsing a XML file describing it,
1026 * an executable named driver that can be used to load and execute (see :ref:`execxml`) a calculation
1027 schema given as a XML file (see :ref:`schemaxml`).
1030 ''''''''''''''''''''''''''''''''
1031 Goals of Graphic User Interface design are the following:
1033 * Provide a general mechanism for the synchronisation of several views (tree views, 2D canvas views, edition dialogs).
1034 For this goal, a subject/observers design pattern is used: several observers can attach or detach themselves to/from the subject.
1035 The subject send update events to the lists of observers and does not know the implementation of the observers. The observers
1036 correspond to the different views in case of YACS.
1037 * Provide an interface of Engine for edition with a general mechanism for undo-redo.
1038 * Be as independent as possible of Qt (and SALOME) to allow a potential re-use of YACS GUI outside SALOME.
