]> SALOME platform Git repositories - modules/yacs.git/blob - doc/calciumyacs.rst
Salome HOME
0022328: [CEA 942] Worrying traces at YACS launch and SALOME closure
[modules/yacs.git] / doc / calciumyacs.rst
1
2 .. _calciumyacs:
3
4
5 From the old CALCIUM product to CALCIUM in SALOME
6 -------------------------------------------------------
7
8 This section describes why the CALCIUM product has been upgraded to CALCIUM in SALOME.  
9 After a brief presentation of the advantages and disadvantages of the existing CALCIUM product, the second section 
10 presents the implementation of CALCIUM in SALOME using the DSC ports.  
11 The final section describes the joint use of CALCIUM ports and the YACS supervisor.
12
13 The existing CALCIUM product
14 ''''''''''''''''''''''''''''''
15 The CALCIUM product enables fast and easy coupling of Fortran / C / C++ codes in a simple and only slightly 
16 intrusive manner.  Persons responsible for codes used in coupling make a distinction between general interest 
17 data by the definition of input and output connection points.  The person responsible for global coupling defines 
18 the number of simultaneous executions of the different codes and transmission links between connection points of 
19 these execution instances.  This description is called the coupling scheme and is stored in a coupling file.
20
21 Connection points are typed by simple types (integer, floating point, double, booleans, chain) and operate based 
22 on the time or iterative mode.  The data produced are stamped by a date or an iteration number.  Data are 
23 produced and read in codes by a call to write or read primitives.  Production is independent of requests on 
24 read connection points (asynchronism).
25
26 When data are requested for a date later than the data already produced, read instances wait on blocking read primitives 
27 or receive a code indicating that there are no data in non-blocking mode.  When data are requested at a date surrounded 
28 by previously produced data stamps, the reader can obtain interpolated data (L0 and L1) in time mode.  Coupling is 
29 interlocked if the reader(s) is (are) waiting for data that will never be produced.  CALCIUM detects this situation 
30 and proposes either that the execution of coupling should be stopped or that the requested data should be extrapolated 
31 to unlock the situation.  This management depends on mode in which CALCIUM is being used (production mode or debug mode).
32
33 CALCIUM has had two operating modes since its version 3.  The first called debug mode was the only mode available in 
34 earlier versions, and has a coupler process through which all data pass.  In the second so-called production mode, 
35 instances of codes communicate with each other directly.  In debug mode, the transfer flow is limited by the capacity 
36 of the coupler network link to manage simultaneous accesses.  In this mode, the coupler must store a copy of each 
37 received data so as to be able to deliver them at the required time and be capable of detecting an interlocked situation.  
38 Production mode enables a data transfer with performances that are not limited by the capacity of input and output 
39 links of the coupler because there is no longer a coupler.  However, this mode has the limitations that there is no 
40 detection of interlocking (but a timeout is managed), step back requests are controlled locally, there is no step 
41 by step execution mode and no dynamic management of coupling.
42
43 CALCIUM ports in SALOME
44 '''''''''''''''''''''''''''''
45 Several couplings were set up during the 2004 Summer school as a result of experimental use of the existing CALCIUM 
46 tool (in production mode) in SALOME.  It showed the relevance of getting datastream type ports to cohabit with 
47 SALOME dataflow / control flow ports.  However, it required a specific modification located in the CALCIUM start 
48 procedure and it highlighted the following limitations:
49
50 - the need to use a different container for each service using CALCIUM (even for services in the same 
51   component (CALCIUM is not multithread safe)).
52 - successive re-executions of coupling are difficult (need to not call MPI_FIN and problems related to the state of 
53   the MPI virtual machine)
54 - the SALOME SUPERVISOR has no control over execution of CALCIUM coupling
55 - no possible extension of transmitted CALCIUM types
56 - cohabitation of the MPI environment and the CORBA environment is sometimes difficult.
57
58 The SALOME KERNEL module is provided with new communication ports called DSC (Dynamic Software Component) ports 
59 that components use to dynamically add / delete new interfaces accessible to everyone.  
60 :ref:`progdsc` describes how these new ports are used / designed / and their usefulness.  
61 There are two classes of DSC ports, firstly ports that provide an interface (provides ports), and secondly ports 
62 that use the interfaces (uses ports).
63
64 An implementation of CALCIUM ports based on this technology has been available since SALOME KERNEL version V4.  
65 Therefore, CALCIUM couplings are possible simply by calling CALCIUM primitives in component services.  
66 This implementation reuses CALCIUM functions in its production mode.  Use of this technology only requires 
67 the SALOME KERNEL module.  However, unless the YACS supervisor is used, the user must write a python script or 
68 a component service to load and initialize the coupling components, connect the different ports and configure 
69 them, and start the services in the appropriate order.
70
71
72 CALCIUM / SALOME ports and the YACS supervisor
73 '''''''''''''''''''''''''''''''''''''''''''''''''
74 The YACS supervisor available in SALOME (since version V4.1) manages all types of DSC ports, and particularly CALCIUM  ports.  
75 It relieves the user from the need to implement a script or a service to connect and configure the ports.  It checks 
76 the validity of the calculation scheme and starts services in accordance with the described dependencies.  
77 A calculation scheme can be created mixing datastream type ports (calcium mode), dataflow ports (arrival of data that 
78 can trigger starting a service) and control flow ports (one service is started by the end of execution of another 
79 service), thus creating elaborated calculation schemes.
80
81 The calculation scheme thus created can be saved in the XML format.  This file represents the equivalent of the 
82 CALCIUM coupling file for the link declaration and parameter setting part, ports being declared in the XML file 
83 that catalogs component resources.
84
85 Creating a SALOME component using CALCIUM
86 ---------------------------------------------------
87 The use of CALCIUM in SALOME assumes that SALOME components are available offering services based on CALCIUM ports.  
88 There are several choices for creating such components:
89
90 - Create a SALOME module containing components for which the services have CALCIUM ports
91 - Create several SALOME modules containing at least one component for which the service(s) have CALCIUM ports.
92
93 Creating a SALOME module consists of structuring header, source, library and resource files in the form of a standard 
94 directory structure.  It can be done from a model module (HELLO, PYHELLO), or from a module generator (for example :ref:`yacsgen`)
95
96 Customisation of the SALOME component for the use of CALCIUM ports consists of:
97
98 - including a file declaring DSC ports in the IDL file of the component,
99 - including a file and declaring an inheritance to make our component supervisable,
100 - creating CALCIUM ports used in the definition of a standard method called init_service,
101 - declaration of CALCIUM ports of the component(s) in the module catalog file.
102
103 By using YACSGEN, the init_service method and the XML catalog of services provided by components are generated automatically.
104
105
106 The IDL declaration of components using CALCIUM ports
107 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
108 Since ports are dynamically declared in the init_service method, CALCIUM ports do not need to be previously declared 
109 in the IDL file.  However, the DSC_Engine.idl file must be included in the components IDL file(s) to benefit from DSC ports.
110
111 Example of the CALCIUM_TESTS.idl file for the CALCIUM_TEST module defining the three ECODE, SCODE, ESPION components, each 
112 of which offers a unique service to start up the corresponding wrapped code:
113
114 ::
115
116     #include "DSC_Engines.idl"
117     
118     /*! \file CALCIUM_TESTS.idl
119       This file contains the first installation test of CALCIUM product.
120       Each engine contains one service.
121     */
122     module CALCIUM_TESTS {
123     
124       interface ECODE : Engines::Superv_Component {
125         void EcodeGo();
126       };
127     
128       interface SCODE : Engines::Superv_Component {
129         void ScodeGo();
130       };
131     
132       interface ESPION : Engines::Superv_Component {
133         void EspionGo();
134       };
135     
136     };
137
138 Declaration of a C++ component using CALCIUM ports
139 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
140 Only one header is necessary in the case of a wrapper component (that does nothing except to call an 
141 implementation of another compilation unit):
142
143 .. code-block:: cpp
144
145   #include “Superv_Component_i.hxx”
146
147 This header file is necessary to make our component supervisable and to use DSC ports.  The component will 
148 virtually inherit the Superv_Component_i class.
149
150 Example ECODE.hxx declaration file for the ECODE component:
151
152 .. code-block:: cpp
153
154     #ifndef _ECODE_HXX_
155     #define _ECODE_HXX_
156     
157     #include "Superv_Component_i.hxx"
158     //Header CORBA generated from the CALCIUM_TESTS module
159     #include "CALCIUM_TESTS.hh"
160     
161     //Interface for the wrapped code, in this case C code ecode
162     extern "C" { int ecode(void *); }
163     
164     class ECODE_impl :
165       //Implements the CORBA interface for the ECODE component
166       public virtual POA_CALCIUM_TESTS::ECODE,
167       //Makes the component supervisable
168       public virtual Superv_Component_i {
169     
170     public :
171       //Classical SALOME component constructor
172       ECODE_impl(CORBA::ORB_ptr orb,
173              PortableServer::POA_ptr poa,
174              PortableServer::ObjectId * contId, 
175              const char *instanceName, 
176              const char *interfaceName);
177       
178       virtual ~ECODE_impl();
179     
180       //Initialisation of the service EcodeGo()
181       CORBA::Boolean init_service(const char * service_name);
182       void EcodeGo();
183     };
184     
185     extern "C"
186     {
187       PortableServer::ObjectId * ECODEEngine_factory(CORBA::ORB_ptr orb,
188                              PortableServer::POA_ptr poa,
189                              PortableServer::ObjectId * contId,
190                              const char *instanceName,
191                              const char *interfaceName);
192     }
193     
194     #endif
195
196
197 Declaration of component resources (part 1)
198 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
199 Components publish signatures of their services in an XML resource file called the module catalog (or components catalog).  
200 This file can be generated by YACSGEN.
201
202 Extract from the CALCIUM_TESTSCatalog.xml catalog concerning the ECODE component:
203
204 Our ECODE component provides a unique EcodeGo() service that has no input parameters and no output parameters.
205
206 The Creating CALCIUM ports section describes how this resource file will be extended by the declaration of datastream ports.
207
208 .. code-block:: xml
209
210     ....
211       <component>
212             <component-name>ECODE</component-name>
213           ....
214             <component-interface-list>
215                 <component-interface-name>ECODE</component-interface-name>
216                 <component-interface-comment></component-interface-comment>
217                 <component-service-list>
218                     <component-service>
219                         <!-- service-identification -->
220                         <service-name>EcodeGo</service-name>
221                          ...
222                         <!-- service-connexion -->
223                         <inParameter-list>
224                         </inParameter-list>
225                         <outParameter-list>
226                         </outParameter-list>
227                         <DataStream-list>
228                          </DataStream-list>
229                     </component-service>
230                 </component-service-list>
231             </component-interface-list>
232       </component>
233
234 Definition of a component using CALCIUM ports
235 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
236 The component creates the ports that it needs.  The step to create a CALCIUM port consists of calling the add_port method 
237 provided by the virtual inheritance from the Superv_Component_i class.  It must be done before the service(s) that use 
238 the port is (are) started.  This is why this declaration is located in the 
239 standard init_service(char * name_of_service_to_be_initialised) method.  There are two methods of creating a 
240 CALCIUM port, firstly the create_calcium_port method and secondly the add_port method.
241
242 Creating CALCIUM ports using the add_port method
243 ++++++++++++++++++++++++++++++++++++++++++++++++++++
244 This method is used to create any type of DSC port.  It can be used to create CALCIUM ports in particular.
245
246 .. code-block:: cpp
247
248      add_port< typing_of_my_fabricated_port >( "the type of port to be fabricated",
249                                               "provides"|”uses”,
250                                               "the port name")
251
252
253 *"the type of port to be fabricated"*:
254   This string notifies the DSC port factory in the KERNEL module about the name of the type of port 
255   to be created.  The following types are possible for CALCIUM:
256   “CALCIUM_integer”, “CALCIUM_real”, “CALCIUM_double”, “CALCIUM_logical”, “CALCIUM_complex”,
257   “CALCIUM_string”
258 *“provides”|”uses”*:
259   This string indicates if it is a CALCIUM output (uses) port or an input provides port.  Note that in the DSC semantic, 
260   the provides port provides a write interface used by the uses port.
261 *“the port name”*:
262   The port name corresponds to the name of the variable used in CALCIUM primitives.
263 *typing_of_my_fabricated_port*:
264   This type types the pointer returned by add_port.  The objective for CALCIUM is to indicate the typing corresponding to 
265   the type name already given in the factory plus the uses or provides information:
266
267   - calcium_integer_port_provides or calcium_integer_port_uses
268   - calcium_real_port_provides or calcium_real_port_uses
269   - calcium_double_port_provides or calcium_double_port_uses
270   - calcium_string_port_provides or calcium_string_port_uses
271   - calcium_complex_port_provides or calcium_complex_port_uses
272   - calcium_logical_port_provides or calcium_logical_port_uses
273
274
275 Extract from the init_service method in the ECODE.cxx file for the ECODE component:
276
277 .. code-block:: cpp
278
279     CORBA::Boolean ECODE_impl::init_service(const char * service_name) {
280     
281       CORBA::Boolean rtn = false;
282       string s_name(service_name);
283       
284       if (s_name == "EcodeGo") {
285     
286         try {
287       
288         add_port<calcium_integer_port_provides>("CALCIUM_integer","provides","ETP_EN")->
289           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
290      
291          add_port<calcium_real_port_provides>("CALCIUM_real","provides","ETP_RE") ->
292           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
293         
294         add_port<calcium_double_port_provides>("CALCIUM_double","provides","ETP_DB")->
295           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
296     
297         add_port<calcium_complex_port_provides>("CALCIUM_complex","provides","ETP_CX")->
298           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
299     
300         add_port<calcium_string_port_provides>("CALCIUM_string","provides","ETP_CH")->
301           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
302     
303         add_port<calcium_logical_port_provides>("CALCIUM_logical","provides","ETP_LQ")->
304           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
305      ....
306         rtn = true;
307         } catch ( const DSC_Exception & ex ) {
308           std::cerr << ex.what() << std::endl;;
309         }
310       } //FIN (s_name == "Ecode")
311     
312       return rtn;
313     }
314
315 Creating CALCIUM ports using the create_calcium_port method
316 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
317 This method is specially written for the creation of CALCIUM ports, and simplifies the creation of ports.  
318 It is used by YACSGEN.  The “IN”|”OUT” parameter indicates whether it is a CALCIUM input or output port.  
319 The “T”|”I” parameter indicates the port mode, time or iterative.
320
321 Extract from the init_service method in the ECODE.cxx file for the ECODE component:
322
323
324 .. code-block:: cpp
325
326     ECODE_i::init_service(const char * service_name) {
327        CORBA::Boolean rtn = false;
328        string s_name(service_name);
329        if (s_name == "EcodeGo")   {
330             try   {
331                 //initialisation CALCIUM ports IN
332                create_calcium_port(this,"ETP_EN","CALCIUM_integer","IN","T");
333                create_calcium_port(this,"ETP_RE","CALCIUM_real","IN","T");
334                create_calcium_port(this,"ETP_DB","CALCIUM_double","IN","T");
335                create_calcium_port(this,"ETP_CX","CALCIUM_complex","IN","T");
336                create_calcium_port(this,"ETP_CH","CALCIUM_string","IN","T");
337                create_calcium_port(this,"ETP_LQ","CALCIUM_logical","IN","T");
338     ...      }
339            catch(const PortAlreadyDefined& ex)   {
340                std::cerr << "ECODE: " << ex.what() << std::endl;
341                //Ports already created : we use them
342             }
343            catch ( ... )   {
344                std::cerr << "ECODE: unknown exception" << std::endl;
345             }
346            rtn = true;
347          }
348        return rtn;
349      }
350
351
352 Declaration of component resources (part 2)
353 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
354 The XML component resource file must be completed to declare that CALCIUM ports exist in the different components.  
355 YACSGEN takes account of CALCIUM ports in the generation of the module catalog.
356
357 Extract from the CALCIUM_TESTSCatalog.xml catalog for the ECODE component:
358
359 .. code-block:: xml
360
361     .....           
362                         <DataStream-list>
363                            <inParameter>
364                               <inParameter-name>ETP_EN</inParameter-name>
365                               <inParameter-type>CALCIUM_integer</inParameter-type>
366                               <inParameter-dependency>T</inParameter-dependency>
367                            </inParameter>
368                            <inParameter>
369                               <inParameter-name>ETP_RE</inParameter-name>
370                               <inParameter-type>CALCIUM_real</inParameter-type>
371                               <inParameter-dependency>T</inParameter-dependency>
372                            </inParameter>
373                            <inParameter>
374                               <inParameter-name>ETP_DB</inParameter-name>
375                               <inParameter-type>CALCIUM_double</inParameter-type>
376                               <inParameter-dependency>T</inParameter-dependency>
377                            </inParameter>
378     .....           
379                         </DataStream-list>
380
381
382 Configuring a CALCIUM port
383 ''''''''''''''''''''''''''''''''''
384 The step to configure ports uses all possible link parameter settings in the CALCIUM coupling file outside SALOME.  
385 This step can be done when the port is created in the component (init_service method) by a coupling parameter 
386 setting component / script, or by the YACS supervisor.  This step indicates the following characteristics 
387 for each port in the provides class:
388
389 - time / iteration dependency of received data:
390      TIME_DEPENDENCY or ITERATION_DEPENDENCY
391 - The data storage level (size of the history stack):
392      UNLIMITED_STORAGE_LEVEL (by default) or a strictly positive integer
393 - The time scheme selected to define the date used in read primitives (CPLxx) in time mode:
394  
395    * TI_SCHEM (default value):  Values of the input variable used are taken at the time corresponding to the beginning of 
396      the current time step in the calculation (see parameter **ti** of CPLxx)
397    * TF_SCHEM:  Values of the input variable are taken at the time corresponding to the end of the current time step 
398      in the calculation (see parameter **tf** of CPLxx)
399    * ALPHA_SCHEM:  Values of the input variable are taken at an instant equal to TF * *ALPHA* + TI * (1 - *ALPHA*).  
400      *ALPHA* can be equal to values strictly between 0 and 1.  The value 0 is replaced by the TI_SCHEM option and 
401      the value 1 is replaced by the TF_SCHEM option).
402
403 - The interpolation type to be used for a port in time mode:
404      L0_SCHEM, L1_SCHEM
405 - The extrapolation type to be used in the case of blockage / timeout:
406      E0_SCHEM, E1_SCHEM (not yet functional)
407 - The value of the DELTAT parameter that indicates if two dates are identical.
408
409 All of the keywords used when the ports are configured are defined in the CalciumTypes C++ namespace in the CalciumTypes.hxx file.
410
411 Configuration when the PORT is created
412 +++++++++++++++++++++++++++++++++++++++++++++++++
413 When a port is created, the add_port method returns a pointer to the port useful to its configuration.  One example 
414 configuration in the init_service method consists of indicating if the port is in time dependency or iteration dependency mode:
415
416 .. code-block:: cpp
417
418       add_port<calcium_integer_port_provides>("CALCIUM_integer","provides","ETP_EN")->
419           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
420
421
422 The following methods are available to configure CALCIUM ports:
423
424 * Set / Query the dependency type:
425
426 The dependency type informs the port if the data are stamped by a date or (exclusive) an iteration number.  The default 
427 dependency type is undefined (CalciumTypes::UNDEFINED_DEPENDENCY).  CalciumTYpes::TIME_DEPENDENCY or 
428 CalciumTypes::ITERATION_DEPENDENCY can be defined.
429
430 .. code-block:: cpp
431
432      void setDependencyType (DependencyType dependencyType);
433      DependencyType getDependencyType () const;
434     
435
436 * Set / Query the storage level of the data produced:
437
438 The storage level in the history of data produced must be greater than or equal to 1.  By default it is 
439 unlimited (CalciumTypes::UNLIMITED_STORAGE_LEVEL).  It may have to be reduced, to limit memory consumption for the 
440 case of a coupling with many iterations.
441
442 .. code-block:: cpp
443
444      void   setStorageLevel   (size_t storageLevel);
445      size_t getStorageLevel   () const;
446
447   
448 * Set / Query the time scheme used to define the read date:
449
450 The time scheme chosen to define the date used in read primitives in time mode is set to CalciumTypes::TI_SCHEM by default.  It is also possible to enter CalciumTypes::TF_SCHEM or CalciumTypes::ALPHA_SCHEM.
451
452 .. code-block:: cpp
453
454       void                  setDateCalSchem   (DateCalSchem   dateCalSchem);
455       DateCalSchem getDateCalSchem () const;
456
457   
458 If the time scheme used is ALPHA_SCHEM, the next method is used to indicate the value of ALPHA to be used.  Alpha is equal to zero by default (equivalent to TI_SCHEM) and it can be set to between 0 and 1 inclusive.
459
460
461 .. code-block:: cpp
462
463     void     setAlpha(double alpha);
464     double getAlpha() const ;
465
466
467 * Set / Query the tolerated deviation within which two dates will be considered to be identical:
468
469 Two dates D1 and D2 are identical if abs(T1-T2) <CalciumTypes::EPSILON.  Epsilon is equal to 1E-6 by default.  
470 Parameters can be set for it on each port (0 <= deltaT <= 1).
471
472 .. code-block:: cpp
473
474       void     setDeltaT(double deltaT );
475       double getDeltaT() const ;
476
477
478 * Set / Query the type of time interpolation to be used:
479
480 When a read request is formulated for a date T that has not been produced but is surrounded by dates T1(min) and T2(max) for which data have already been produced, CALCIUM produces a CalciumTypes::L1_SCHEM linear interpolation by default.  The user can request a CalciumTypes::L0_SCHEM step “interpolation”.
481
482 .. code-block:: cpp
483
484       void setInterpolationSchem (InterpolationSchem interpolationSchem);
485       InterpolationSchem getInterpolationSchem () const ;
486
487 * Set / Query the type of the extrapolation to be used:
488
489 This parameter is used to indicate whether an extrapolation is required to exit from a blocking case (a port waiting for data that will never be produced).  The default value is Calcium-Types::UNDEFINED_EXTRA_SCHEM.  Possible values are EO_SCHEM (step extrapolation) or E1-SCHEM (linear extrapolation).
490
491 .. code-block:: cpp
492
493      void setExtrapolationSchem (ExtrapolationSchem extrapolationSchem);
494      ExtrapolationSchem getExtrapolationSchem () const ;
495
496
497 Configuration using properties of DSC ports
498 +++++++++++++++++++++++++++++++++++++++++++++++++
499 This section explains advanced use of the properties of DSC ports to perform the CALCIUM ports configuration step, it can 
500 be ignored if CALCIUM ports are used in a simple manner.
501
502 All DSC ports can be configured by a list of properties.  Therefore, the configuration step can be made using a CORBA call on the ports concerned.
503
504 The [set|get]_property methods of DSC ports manipulate a list of pairs with a key equal to the name of the property in 
505 the first position and the associated value in the second position.
506
507 Extract from the SALOME_Component.idl file of the SALOME KERNEL:
508
509 ::
510
511      struct KeyValuePair  {
512         string key;
513         any value;
514       };
515      typedef sequence<KeyValuePair> FieldsDict;
516      void setProperties(in FieldsDict dico);
517      FieldsDict getProperties();
518
519
520
521 CALCIUM declares the following types in the SALOME KERNEL Calcium_Ports.idl file:
522
523 ::
524
525     const long UNLIMITED_STORAGE_LEVEL = -70;   
526     enum DependencyType { UNDEFINED_DEPENDENCY, TIME_DEPENDENCY, ITERATION_DEPENDENCY};
527     enum DateCalSchem           { TI_SCHEM, TF_SCHEM , ALPHA_SCHEM};
528     enum InterpolationSchem   { L0_SCHEM, L1_SCHEM };
529     enum ExtrapolationSchem  { UNDEFINED_EXTRA_SCHEM, E0_SCHEM, E1_SCHEM};
530
531
532 Therefore, the recognised properties are the following pairs:
533
534 - (“StorageLevel”, int > 0 )
535 - (“Alpha”, 0 <= double <= 1 )
536 - (“DeltaT”, 0 <= double <= 1 )
537 - (“DependencyType”, enum CORBA DependencyType)
538 - (“DateCalSchem”, enum CORBA DateCalSchem)
539 - (“InterpolationSchem”,enum CORBA InterpolationSchem)
540 - (“ExtrapolationSchem”,enum CORBA ExtrapolationSchem)
541
542 Example dynamic configuration by a python script (extract from file CAS_1.py):
543
544 .. code-block:: python
545
546     ...
547     port1=ecode.get_provides_port("ETS_DB",0);
548     myAny1_1=4
549     port1.set_property("StorageLevel",any.to_any(myAny1_1))
550     
551
552 The get_provides_port and set_property methods are provided by the default implementation of supervisable SALOME components.
553
554 The configuration in the YACS XML file
555 ++++++++++++++++++++++++++++++++++++++++++++
556 The YACS supervisor module is capable of importing / exporting calculation schemes in the XML format.  In particular, this 
557 includes the declaration of links between the ports of the different component instances.  The YACS GUI generates all sorts of 
558 calculation schemes and starts their execution.
559
560 At the present time, properties cannot be added to CALCIUM ports with YACS GUI.  Therefore, they have to be added into 
561 the XML file manually.  In YACS, calcium ports are configured by declaring properties on the links.
562
563 Extract from the CAS_1.xml calculation scheme, first test case of CALCIUM functions:
564
565 Example configuration of the ETS_DB port at a history level of 4.
566
567 .. code-block:: xml
568
569      <stream>
570           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
571           <tonode>ECODE</tonode> <toport>ETS_DB</toport>
572           <property name="StorageLevel" value="4"/>
573        </stream>
574     
575
576 (Keys, value) pairs used to describe properties are as listed in the previous section. 
577  
578 Calls to CALCIUM methods
579 '''''''''''''''''''''''''''''''
580 The CALCIUM C / C++ / Fortran API in SALOME is globally identical to the API for the CALCIUM product outside SALOME.  
581 It is now also available in Python.
582
583 See :ref:`calciumapi` for C and Fortran API documentation and :mod:`calcium` for Python API documentation.
584
585 The classical C / C++ API is extended by a zero copy version that transfers data without an intermediate copy.
586
587 C++ developers can use an API more specific to C++ that proposes parameter types more adapted to the language.
588
589 It is also possible to use CALCIUM DSC ports more directly with their associated CORBA types.
590
591
592
593 Classical CALCIUM calls in C / C++ / F / Python
594 +++++++++++++++++++++++++++++++++++++++++++++++++
595 The classical CALCIUM API remains essentially the same, regardless of whether the objective is to include an existing 
596 CALCIUM C / C ++ / Fortran code in the SALOME platform or to develop a new CALCIUM component.
597
598 The code containing CALCIUM calls is written directly in the SALOME service of the C++ component, or is accessible through a procedure call.
599
600 In the first case, the code must be written in C / C++ / Python because there is no SALOME component written directly in Fortran.
601
602 In the second case, the calling service must transmit the access pointer to its component.  Unlike the CALCIUM outside 
603 SALOME API, the first argument of all procedures is the pointer of the component that holds the associated ports.  
604 This enables the CALCIUM library to identify the component that holds the requested ports [1]_.
605
606 Extract from the implementation of the EcodeGo() (ECODE.cxx) service calling the ecode wrapped code (void* component)(Ecode.c):
607
608 (This code can be generated by YACSGEN)
609
610
611 .. code-block:: cpp
612
613     void ECODE_impl::EcodeGo() {
614       Superv_Component_i * component = dynamic_cast<Superv_Component_i*>(this);
615       try {
616         ecode(component);            
617       } 
618       catch ( const CalciumException & ex)
619     ....
620     }
621
622
623 A code already written to use CALCIUM only needs to be adapted to transmit the pointer of its component as a first 
624 parameter of calls to CALCIUM procedures.  Apart from this observation, the code remains exactly the same as the 
625 initial calcium code.
626
627 Extract from the implementation of the calcium source code applied by the service (Ecode.c):
628
629 .. code-block:: c
630
631     ...
632     #include <calcium.h>
633     ...
634     int    ecode(void * component)
635     {
636     ...
637     /*    Connection to the coupler   */
638         info = cp_cd(component,nom_instance);
639     
640         info= cp_len(component,CP_TEMPS,&ti_re,&tf_re,&i,"ETP_EN",1,&n,EDATA_EN);
641     ...
642         info = cp_fin(component,CP_CONT);
643     }
644
645
646
647 The C ecode procedure connects to the CALCIUM coupler through the cp_cd procedure and then formulates a blocking read 
648 request to the ETP_EN port / connection point according to a time scheme between ti_re and tf_re.  Only one data is 
649 requested, it will be stored in the EDATA_EN buffer.  The procedure finishes when the coupler is disconnected, using 
650 the CP_CONT flag to indicate that any clients of ports associated with ecode will receive the most recent known value 
651 if there are any new read requests.  If the CP_ARRET flag was used, any subsequent read request on the ports associated 
652 with ecode() would exit in error.
653
654 The scheme is the same in fortran, the following is an extract from the Ecode.f file:
655
656 .. code-block:: fortran
657
658         SUBROUTINE ECODE(compo)
659         INCLUDE 'calcium.hf'
660         INTEGER compo
661         ----
662         CALL CPCD(compo,nom_instance, info)
663         ----
664         CALL CPLEN(compo,CP_TEMPS,ti_re,tf_re,i,'ETP_EN',1,n,EDATA_EN,info)
665         ----
666         CALL CPFIN(compo,CP_CONT, info)
667         ----
668
669
670 CALCIUM C/C++ calls in zero copy mode
671 +++++++++++++++++++++++++++++++++++++++
672 CALCIUM DSC ports of the provides type (CALCIUM entry connection points) keep the received data to be able to create the 
673 requested history (unlimited by default).  When the user formulates a read for data that are already available, the port 
674 copies these data into the buffer provided by the user.  An extended CALCIUM API allows the user to supply a null pointer 
675 to replace the pre-allocated reception pointer, so as to obtain a pointer to the internal buffer of the CALCIUM provides 
676 class port directly.  This prevents a potentially large copy, but it obliges the user to be vigilant on the following points:
677
678 1. The buffer obtained must be used in read only.  Unless it is used in a particular manner, any modification to the buffer 
679    would be reflected in new read requests for the same stamp or during an interpolation calculation using this stamp.
680 2. The buffer is dependent on the history level set for the port.  If the history level set for the port is such that the 
681    stamp and the associated buffer will be deleted, the user will have a pointer to an invalid buffer and its use would probably corrupt memory.
682 3. Zero copy is not used on integers and booleans because these types do not exist in CORBA.
683 4. The user must call the CALCIUM procedure once only to release the pointer obtained.  This releases any buffers created for 
684    cases in which a zero copy is impossible.  This also helps to count distributed references to prevent early release (not yet implemented).
685
686 The zero copy API consists of calling ecp_lxx read procedures instead of their corresponding procedure cp_lxx and transferring 
687 the address of a pointer for which the value is initialized to zero.
688
689 The write procedures API is not modified because these procedures still operate in zero copy.  If the sender and receiver 
690 components are placed in the same container, a copy is triggered on reception  of data to prevent any interaction between 
691 the sender's buffer and the receiver's buffer.
692
693 Extract from the zero copy implementation of the CALCIUM source code called by the (Ecode.c) service:
694
695
696 .. code-block:: c
697
698         float *sav_EDATA_RE = _EDATA_RE; //keep a ptr to previously received data
699         _EDATA_RE = NULL;
700         ti_re = 1.1;
701         tf_re = 1.2;
702         info = ecp_lre(component,CP_TEMPS,&ti_re,&tf_re,&i,"ETP_RE",0,&n,&_EDATA_RE);
703         fprintf(file_2,"%f\n", _EDATA_RE[0]);
704         ti_re = 0.0;
705         tf_re = 1.0;
706     
707         ecp_lre_free(sav_EDATA_RE);
708         ecp_lre_free(_EDATA_RE);
709
710
711 CALCIUM calls with API specific to C++
712 +++++++++++++++++++++++++++++++++++++++++
713 C++ developers can use a specific API that proposes parameters with types better adapted to the language.
714
715 Time stamps are always of the double type and iterations are always of the long type, regardless of whether it is in write or 
716 read and regardless of the type of transmitted data.  Variable names are STL strings.  The name of read and write methods is 
717 the same regardless of the type of data manipulated.  The type of data is found automatically, except for complex types, 
718 logical types and character strings.
719
720 .. code-block:: cpp
721
722       template <typename T1, typename T2> static void
723       ecp_ecriture ( Superv_Component_i & component,  int const  & dependencyType,
724              double const & t,  long const  & i,
725              const   string & nomVar,  size_t bufferLength,  T1 const  & data ) 
726
727
728
729       template <typename T1, typename T2 > static void
730       ecp_lecture ( Superv_Component_i & component,   int    const  & dependencyType,
731                    double & ti,  double const  & tf,  long & i,
732                    const string  & nomVar,  size_t bufferLength,
733                    size_t  & nRead,  T1 * &data )
734
735
736 These methods are defined in the CalciumCxxInterface.hxx header file.  Therefore the user will include 
737 the ``#include ”CalciumCxxInterface.hxx”`` directive in the code.
738
739 Note:  the CalciumInterface.hxx file has to be included only once because it declares and defines C++ template methods.  
740 This does not create any problem with compilation, but there is a multiple definition problem during link editing.
741
742 But there is no need to specify T1 and T2 for integer, float or double CALCIUM types, because there is a write method 
743 and a read method with a single template parameter that calls their corresponding methods with the constraint T1==T2==<Type of Data Used>.
744
745 For complex types, the <float,cplx> instantiation has to be used and the number of complexes has to be multiplied by two to 
746 transfer the bufferLength parameter.  In this case, the only difference from use of the float type is the typing of the ports 
747 used, namely calcium_complex_port_provides instead of calcium_real_port_provides.
748
749 Instantiation for the logical type is done with <int, bool>.
750
751 Instantiation for character strings is <char*, str>.  The character strings can be read without giving the maximum string 
752 length parameter located in the classical C / C++ / Fortran API.
753
754 Differences from the CALCIUM product outside SALOME
755 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
756 All that are implemented are read / write procedures and connection/disconnection procedures. Step back, query, dynamic 
757 configuration and debugging procedures are not implemented.
758
759 However, it is possible to dynamically create and connect components that read/write on ports of other component services.  
760 Any SALOME service using CALCIUM ports has the privileges of a spy (in production mode).
761
762 Several output ports can be connected to the same input port and one output port can be connected to several input ports.  
763 The first case was not possible in CALCIUM outside SALOME.
764
765 Reads/writes are implemented in blocking mode;  non-blocking mode is not yet implemented.
766
767 All ports created by the different services of a single component are visible / usable by all these services.  
768 However, it is not recommended that they should be used in this way.
769
770 The extrapolation has not yet been implemented.
771
772 File ports have not yet been implemented, however there are some DSC file ports in SALOME.
773
774 Ports not connected do not cause any error in execution of coupling unless they are used.
775
776 CALCIUM error codes returned by primitives are the same as for CALCIUM outside SALOME.  By using the specific C++ API, 
777 CalciumException class exceptions (CalciumException.hxx) that contain the CALCIUM error code and an explanation message 
778 can be caught.  The error code contained in the exception is obtained by calling the CalciumTypes::InfoType getInfo() method.  
779 The CalciumException class also inherits from the C++ SALOME_Exception exception.
780
781 A compilation option has to be used to allow C++ exceptions to pass through the C and Fortran codes called from 
782 the SALOME component service.  This option for GNU compilers is -fexceptions.
783
784 Data type exchange will be extended to complex types such as MED fields or meshes.
785
786
787 Starting CALCIUM coupling
788 --------------------------------
789 CALCIUM coupling can be started in three different ways.  The first is to use the SALOME KERNEL only and to manage 
790 component instances by a python script.  The second is to create a component that would control coupling.  The third 
791 is to use the YACS supervisor component with or without its GUI.
792
793 Setting up the environment
794 '''''''''''''''''''''''''''''''''''
795 Regardless of what method is chosen, the KERNEL module has to be notified about the existence of new modules to be used.  
796 Only one module needs to be declared if all components are within the same module.
797
798 This step is no specific to CALCIUM components, it is necessary for all SALOME components.
799
800 Declaration of <my module>_ROOT_DIR
801 ++++++++++++++++++++++++++++++++++++
802 The KERNEL module is based on a <my module>_ROOT_DIR variable in either a envSalome.sh shell script containing all environment 
803 variables useful to SALOME or in the user console, to locate the installation directory of the <my module> module.
804
805 Example declaration of the CALCIUM_TESTS module in bash:
806
807 .. code-block:: sh
808
809     INSTALLROOT="/local/salome/SALOME5/V5NoDebug"
810     export CALCIUM_TESTS=${INSTALLROOT}/DEV/INSTALL/CALCIUM_TESTS
811     
812
813 The appli_gen.py tool will prepare the appropriate environment in the env.d directory for a SALOME application (see :ref:`appli`).
814
815 Loading the <my module> module when running SALOME 
816 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
817 There are two solutions for loading the <my module> module when SALOME is run.
818
819 Declaration in the SalomeApp.xml file. 
820 #########################################
821 All that is necessary is to declare the name of its module in the modules parameter in the SalomeApp.xml file.
822
823 The following is an example for the CALCIUM_TESTS module:
824
825 .. code-block:: xml
826
827      <section name="launch">
828      ....
829      <parameter name="modules"    value="GEOM,SMESH,VISU,YACS,MED,CALCIUM_TESTS"/>
830      ....
831      </section>
832
833
834
835 Using the --module option.  
836 ################################
837 This option limits loading of modules to the list indicated in the command line (it assumes that the user’s environment 
838 indicates the location of the modules).
839
840 .. code-block:: sh
841
842     ./runAppli  --module=YACS,CALCIUM_TESTS
843
844
845 Running a simple coupling through a python script
846 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
847 Components can be created and their ports can be connected using a Python SALOME session.
848 The script CAS_1.py loads instances of the ECODE, SCODE and ESPION components, connects their ports, makes the necessary 
849 configurations and starts executions.
850
851 The following is an extract from the CAS_1.py file that can be found in <path to CALCIUM_TESTS module>/CALCIUM_TESTS/lib/python2.4/site-packages/salome:
852
853 .. code-block:: python
854
855     
856     import LifeCycleCORBA
857     import Engines
858     import Ports
859     import CALCIUM_TESTS
860     import orbmodule
861     import user
862     
863     import sys
864     import threading
865     from omniORB import any
866     
867     #Load component instances through the LifeCycle 
868     lcc = LifeCycleCORBA.LifeCycleCORBA()
869     ecode = lcc.FindOrLoad_Component('FactoryServer3', 'ECODE')
870     ecode.init_service("EcodeGo")
871     scode = lcc.FindOrLoad_Component('FactoryServer4', 'SCODE')
872     scode.init_service("ScodeGo")
873     
874     #Display the content of the naming server
875     #Obtain a reference to the connection manager
876
877     clt=orbmodule.client()
878     clt.showNS()
879     connection_manager = clt.Resolve("ConnectionManager")
880     
881     #Create CALCIUM links through the connection manager
882     connection_manager.connect(scode, "STP_EN",ecode, "ETP_EN")
883     connection_manager.connect(scode, "STP_RE", ecode, "ETP_RE")
884     connection_manager.connect(scode, "STP_DB", ecode, "ETP_DB")
885     connection_manager.connect(scode, "SIP_EN", ecode, "EIP_EN")
886     connection_manager.connect(scode, "SIP_DB", ecode, "EIP_DB")
887     connection_manager.connect(scode, "SIS_EN", ecode, "EIS_EN")
888     connection_manager.connect(scode, "SIS_DB", ecode, "EIS_DB")
889     connection_manager.connect(scode, "STS_EN", ecode, "ETS_EN")
890     connection_manager.connect(scode, "STS_DB", ecode, "ETS_DB")
891     port1=ecode.get_provides_port("ETS_DB",0);
892     myAny1_1=4
893     port1.set_property("StorageLevel",any.to_any(myAny1_1))
894     connection_manager.connect(scode, "STS_DB", ecode, "ETP_DB2")
895     connection_manager.connect(scode, "STP_CX", ecode, "ETP_CX")
896     connection_manager.connect(scode, "STP_CH", ecode, "ETP_CH")
897     connection_manager.connect(scode, "STP_LQ", ecode, "ETP_LQ")
898     #Create and connect the spy (espion) 
899     #The ESPION can be created after the instances of ECODE and SCODE have been run,
900     #however data produced before the connection will be lost
901     espion = lcc.FindOrLoad_Component('FactoryServer5', 'ESPION')
902     espion.init_service("EspionGo")
903     
904     connection_manager.connect(scode,  "STP_DB2", ecode, "ETP_DB2")
905     connection_manager.connect(espion, "STP_DB2", ecode, "ETP_DB2")
906     connection_manager.connect(scode,  "SIP_DB2", espion, "SIP_DB2")
907     connection_manager.connect(espion, "SIP_DB" , ecode , "EIP_DB" )
908     connection_manager.connect(scode,  "SIP_DB" , espion, "EIP_DB")
909     
910     #If the spy is run last, CAS_1 works but test 15 does not work
911     handler3=threading.Thread(target=espion.EspionGo)
912     handler3.start()
913     handler=threading.Thread(target=ecode.EcodeGo)
914     handler.start()
915     handler2=threading.Thread(target=scode.ScodeGo)
916     handler2.start()
917     
918     handler.join()
919     handler2.join()
920     handler3.join()
921
922
923
924 The script can be run using the following command:
925
926 .. code-block:: sh
927
928   ./runAppli -t --module=YACS,CALCIUM_TESTS -u CAS_1.py
929
930 Running coupling through the YACS GUI
931 '''''''''''''''''''''''''''''''''''''''''''
932 If the module catalog contains the description of components and their services, it is easy to create a coupling scheme by 
933 inserting the services of components that are to be linked.
934
935 To insert a service, simply do a right click / CASE_1 / create a node / create a node from catalog / in the edit tree of the graph.
936
937 Linking two ports consists of selecting the output port (in the edit tree) and then doing a right click on the /add data link/ command, and then selecting the input port.
938
939 There is no consistency check on the branch of incompatible CALCIUM port types in current version of the YACS GUI.  However, an error will occur at the time of execution.
940
941 Once the scheme has been created, it can be exported in the YACS coupling scheme XML format (see toolbar).
942
943 The following is a graphic example of the coupling scheme for the first CALCIUM test case:
944
945 .. image:: images/calcium1.png
946   :align: center
947
948 Once the scheme has been created, all that is necessary is to create an execution by doing a right click on /YACS/CAS_1/New Execution/.  
949 The study tree becomes the execution tree in which the state of the different services appears.  Once it has been 
950 run (by pressing the appropriate button in the tool bar), the services are in the ‘done’ state if everything took place correctly.  
951 The log of a container associated with execution of a service can be displayed by doing a right click on the service concerned 
952 and selecting /Node container Log/.  If an error occurs, reports are displayed by selecting /Error Details/ or /Error Report/.
953
954 As many executions as are necessary can be created.  Modifying the edit scheme does not modify existing execution schemes. 
955 One execution has to be recreated to start the modified scheme.  Do a right click and select /New Edition/ in order to find 
956 the edit scheme corresponding to an execution scheme again.
957
958 Any container configuration is possible:
959
960 1. several CALCIUM services (for one component or different components) coupled within a single container
961 2. several CALCIUM services (for one component or different components) coupled within different containers
962 3. an intermediate configuration between the previous two cases.
963
964 Current limitations:
965
966 1. It is impossible to have several services of a single component simultaneously using distinct CALCIUM ports with the same name.
967 2. It is not possible to restart the same execution because the init_service method will attempt to create existing 
968    ports (an execution has to be created or init_service has to be modified so as to memorise the creation of ports).
969
970
971 Running coupling through YACS without GUI
972 ''''''''''''''''''''''''''''''''''''''''''
973 To do this, you have to create a schema file in XML format (see :ref:`schemaxml`) and to execute it in console
974 mode (see :ref:`execxml`).
975
976
977 Setting up a timeout to interrupt execution in case of interlocking
978 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
979 Sometimes (mainly during development phases), a calculation can ends up in a deadlock. A component waits for a data that 
980 another component must send but this component is also waiting and all these components are waiting in a loop, so the calculation
981 never ends : it's a deadlock.
982
983 There is no way in CALCIUM to detect this deadlock, but it is possible to set a timeout to go out of the deadlock. 
984 A timeout is a time in seconds. When a component waits longer than timeout, an error occurs and the calculation is interrupted.
985 The timeout can be specified by setting the environment variable DSC_TIMEOUT (export DSC_TIMEOUT=600, in bash to set a 10 minutes timeout).
986 It must be set before launching a SALOME session and is therefore globally used for all the calculations in the session. 
987  
988 It is also possible to specify a timeout in the XML coupling file by way of a service node property (DSC_TIMEOUT) as in
989 the following example:
990
991 .. code-block:: xml
992
993       <service name="canal" >
994         <component>FLUIDE</component>
995         <method>prun</method>
996         <load container="A"/>
997         <property name="DSC_TIMEOUT" value="20"/>
998         <instream name="tpi" type="CALCIUM_real"/>
999         <instream name="iconv" type="CALCIUM_integer"/>
1000         <outstream name="tfi" type="CALCIUM_real"/>
1001       </service>
1002
1003 As a consequence, the timeout will be active for all the services in the container of the service (container A in the example).
1004
1005 It is not yet possible to specify a timeout limited to one port or one link.
1006
1007 Creating a SALOME application
1008 --------------------------------------------
1009 Example command invoked to create a SALOME application after adapting the config_appli.xml file:
1010
1011 .. code-block:: sh
1012
1013     python $KERNEL_ROOT_DIR/bin/salome/appli_gen.py --prefix=/local/salome5_my_appli \
1014                                                     --config=config_appli_mod.xml                   
1015
1016
1017
1018 Coupling scheme: example of YACS XML file
1019 -----------------------------------------------
1020 The complete CAS_1.xml file for the coupling scheme of the CALCIUM CAS_1 test case (it can be generated by the YACS GUI):
1021
1022 .. code-block:: xml
1023
1024     <?xml version='1.0'?>
1025     <proc>
1026        <type name="Bool" kind="bool"/>
1027        <type name="Double" kind="double"/>
1028        <type name="Int" kind="int"/>
1029        <type name="String" kind="string"/>
1030        <objref name="CALCIUM_complex"
1031                id="IDL:Ports/Calcium_Ports/Calcium_Complex_Port:1.0"/>
1032        <objref name="CALCIUM_double"
1033                id="IDL:Ports/Calcium_Ports/Calcium_Double_Port:1.0"/>
1034        <objref name="CALCIUM_integer"
1035                id="IDL:Ports/Calcium_Ports/Calcium_Integer_Port:1.0"/>
1036        <objref name="CALCIUM_logical"
1037                id="IDL:Ports/Calcium_Ports/Calcium_Logical_Port:1.0"/>
1038        <objref name="CALCIUM_real" 
1039                id="IDL:Ports/Calcium_Ports/Calcium_Real_Port:1.0"/>
1040        <objref name="CALCIUM_string"
1041                id="IDL:Ports/Calcium_Ports/Calcium_String_Port:1.0"/>
1042        <objref name="file" id="file"/>
1043        <container name="DefaultContainer">
1044           <property name="container_name" value=""/>
1045           <property name="cpu_clock" value="0"/>
1046           <property name="hostname" value=""/>
1047           <property name="isMPI" value="false"/>
1048           <property name="mem_mb" value="0"/>
1049           <property name="nb_component_nodes" value="0"/>
1050           <property name="nb_node" value="0"/>
1051           <property name="nb_proc_per_node" value="0"/>
1052           <property name="parallelLib" value=""/>
1053           <property name="workingdir" value=""/>
1054        </container>
1055        <service name="SCODE">
1056           <component>SCODE</component>
1057           <load container="DefaultContainer"/>
1058           <method>ScodeGo</method>
1059           <outstream name="STP_EN" type="CALCIUM_integer"/>
1060           <outstream name="STP_RE" type="CALCIUM_real"/>
1061           <outstream name="STP_DB" type="CALCIUM_double"/>
1062           <outstream name="STP_CX" type="CALCIUM_complex"/>
1063           <outstream name="STP_CH" type="CALCIUM_string"/>
1064           <outstream name="STP_LQ" type="CALCIUM_logical"/>
1065           <outstream name="SIP_EN" type="CALCIUM_integer"/>
1066           <outstream name="SIP_DB" type="CALCIUM_double"/>
1067           <outstream name="STP_DB2" type="CALCIUM_double"/>
1068           <outstream name="SIS_EN" type="CALCIUM_integer"/>
1069           <outstream name="SIS_DB" type="CALCIUM_double"/>
1070           <outstream name="STS_EN" type="CALCIUM_integer"/>
1071           <outstream name="STS_DB" type="CALCIUM_double"/>
1072           <outstream name="SIP_DB2" type="CALCIUM_double"/>
1073        </service>
1074        <service name="ECODE">
1075           <component>ECODE</component>
1076           <load container="DefaultContainer"/>
1077           <method>EcodeGo</method>
1078           <instream name="ETP_EN" type="CALCIUM_integer"/>
1079           <instream name="ETP_RE" type="CALCIUM_real"/>
1080           <instream name="ETP_DB" type="CALCIUM_double"/>
1081           <instream name="ETP_CX" type="CALCIUM_complex"/>
1082           <instream name="ETP_CH" type="CALCIUM_string"/>
1083           <instream name="ETP_LQ" type="CALCIUM_logical"/>
1084           <instream name="EIP_EN" type="CALCIUM_integer"/>
1085           <instream name="EIP_DB" type="CALCIUM_double"/>
1086           <instream name="ETP_DB2" type="CALCIUM_double"/>
1087           <instream name="EIS_EN" type="CALCIUM_integer"/>
1088           <instream name="EIS_DB" type="CALCIUM_double"/>
1089           <instream name="ETS_EN" type="CALCIUM_integer"/>
1090           <instream name="ETS_DB" type="CALCIUM_double"/>
1091        </service>
1092        <service name="Espion">
1093           <component>ESPION</component>
1094           <load container="DefaultContainer"/>
1095           <method>EspionGo</method>
1096           <instream name="SIP_DB2" type="CALCIUM_double"/>
1097           <instream name="EIP_DB" type="CALCIUM_double"/>
1098           <outstream name="STP_DB2" type="CALCIUM_double"/>
1099           <outstream name="SIP_DB" type="CALCIUM_double"/>
1100        </service>
1101        <stream>
1102           <fromnode>SCODE</fromnode> <fromport>STP_EN</fromport>
1103           <tonode>ECODE</tonode> <toport>ETP_EN</toport>
1104        </stream>
1105        <stream>
1106           <fromnode>SCODE</fromnode> <fromport>STP_RE</fromport>
1107           <tonode>ECODE</tonode> <toport>ETP_RE</toport>
1108        </stream>
1109        <stream>
1110           <fromnode>SCODE</fromnode> <fromport>STP_DB</fromport>
1111           <tonode>ECODE</tonode> <toport>ETP_DB</toport>
1112        </stream>
1113        <stream>
1114           <fromnode>SCODE</fromnode> <fromport>STP_CX</fromport>
1115           <tonode>ECODE</tonode> <toport>ETP_CX</toport>
1116        </stream>
1117        <stream>
1118           <fromnode>SCODE</fromnode> <fromport>STP_CH</fromport>
1119           <tonode>ECODE</tonode> <toport>ETP_CH</toport>
1120        </stream>
1121        <stream>
1122           <fromnode>SCODE</fromnode> <fromport>STP_LQ</fromport>
1123           <tonode>ECODE</tonode> <toport>ETP_LQ</toport>
1124        </stream>
1125        <stream>
1126           <fromnode>SCODE</fromnode> <fromport>SIP_EN</fromport>
1127           <tonode>ECODE</tonode> <toport>EIP_EN</toport>
1128        </stream>
1129        <stream>
1130           <fromnode>SCODE</fromnode> <fromport>SIP_DB</fromport>
1131           <tonode>ECODE</tonode> <toport>EIP_DB</toport>
1132        </stream>
1133        <stream>
1134           <fromnode>SCODE</fromnode> <fromport>SIP_DB</fromport>
1135           <tonode>Espion</tonode> <toport>EIP_DB</toport>
1136        </stream>
1137        <stream>
1138           <fromnode>SCODE</fromnode> <fromport>STP_DB2</fromport>
1139           <tonode>ECODE</tonode> <toport>ETP_DB2</toport>
1140        </stream>
1141        <stream>
1142           <fromnode>SCODE</fromnode> <fromport>SIS_EN</fromport>
1143           <tonode>ECODE</tonode> <toport>EIS_EN</toport>
1144        </stream>
1145        <stream>
1146           <fromnode>SCODE</fromnode> <fromport>SIS_DB</fromport>
1147           <tonode>ECODE</tonode> <toport>EIS_DB</toport>
1148        </stream>
1149        <stream>
1150           <fromnode>SCODE</fromnode> <fromport>STS_EN</fromport>
1151           <tonode>ECODE</tonode> <toport>ETS_EN</toport>
1152        </stream>
1153        <stream>
1154           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1155           <tonode>ECODE</tonode> <toport>ETS_DB</toport>
1156           <property name="level" value="4"/>
1157        </stream>
1158        <stream>
1159           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1160           <tonode>Espion</tonode> <toport>SIP_DB2</toport>
1161        </stream>
1162        <stream>
1163           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1164           <tonode>Espion</tonode> <toport>EIP_DB</toport>
1165        </stream>
1166        <stream>
1167           <fromnode>SCODE</fromnode> <fromport>SIP_DB2</fromport>
1168           <tonode>Espion</tonode> <toport>SIP_DB2</toport>
1169        </stream>
1170        <stream>
1171           <fromnode>Espion</fromnode> <fromport>STP_DB2</fromport>
1172           <tonode>ECODE</tonode> <toport>ETP_DB2</toport>
1173        </stream>
1174        <stream>
1175           <fromnode>Espion</fromnode> <fromport>SIP_DB</fromport>
1176           <tonode>ECODE</tonode> <toport>EIP_DB</toport>
1177        </stream>
1178     </proc>
1179     
1180
1181
1182 Generating a CALCIUM module with YACSGEN: example
1183 -----------------------------------------------------
1184 Complete YACSGEN script to create a generated CALCIUM_TESTS module:
1185
1186 .. code-block:: python
1187
1188     from module_generator import Generator,Module,Service
1189     from module_generator import PYComponent,CPPComponent,F77Component
1190     context={"update":1,
1191              "prerequisites":"/local/salome5/SALOME5/V5NoDebug/prerequis-V5NoDebug.sh",
1192              "kernel":"/local/salome5/SALOME5/V5NoDebug/DEV/INSTALL/KERNEL/"
1193              }
1194            
1195     c1=CPPComponent("ECODE",
1196                     services=[
1197         Service("EcodeGo",
1198                 instream=[
1199         ("ETP_EN","CALCIUM_integer","T"),
1200         ("ETP_RE","CALCIUM_real","T"),
1201         ("ETP_DB","CALCIUM_double","T"),
1202         ("ETP_CX","CALCIUM_complex","T"),
1203         ("ETP_CH","CALCIUM_string","T"),
1204         ("ETP_LQ","CALCIUM_logical","T"),
1205         ("EIP_EN","CALCIUM_integer","I"),
1206         ("EIP_DB","CALCIUM_double","I"),
1207         ("ETP_DB2","CALCIUM_double","T"),
1208         ("EIS_EN","CALCIUM_integer","I"),
1209         ("EIS_DB","CALCIUM_double","I"),
1210         ("ETS_EN","CALCIUM_integer","T"),
1211         ("ETS_DB","CALCIUM_double","T") ],
1212                 outstream=[],
1213                 defs="""extern "C" {
1214     int ecode(void *);
1215     }""",
1216                 body="""
1217                 ecode(component);
1218                 """
1219                 ,),
1220         ],
1221                     libs="",
1222                     rlibs=""
1223                     )
1224     
1225     c2=CPPComponent("SCODE",
1226                     services=[
1227         Service("ScodeGo",
1228                 instream=[],
1229                 outstream=[
1230         ("STP_EN","CALCIUM_integer","T"),
1231         ("STP_RE","CALCIUM_real","T"),
1232         ("STP_DB","CALCIUM_double","T"),
1233         ("STP_CX","CALCIUM_complex","T"),
1234         ("STP_CH","CALCIUM_string","T"),
1235         ("STP_LQ","CALCIUM_logical","T"),
1236         ("SIP_EN","CALCIUM_integer","I"),
1237         ("SIP_DB","CALCIUM_double","I"),
1238         ("STP_DB2","CALCIUM_double","T"),
1239         ("SIS_EN","CALCIUM_integer","I"),
1240         ("SIS_DB","CALCIUM_double","I"),
1241         ("STS_EN","CALCIUM_integer","T"),
1242         ("STS_DB","CALCIUM_double","T"),
1243         ("SIP_DB2","CALCIUM_double","I") ],
1244                 defs="""extern "C" {
1245     int scode(void *);
1246     }""",
1247                 body="""
1248                 scode(component);
1249                 """
1250                 ,),
1251         ],
1252                     libs="",
1253                     rlibs=""
1254                     )
1255     
1256     c3=CPPComponent("ESPION",
1257                     services=[
1258         Service("EspionGo",
1259                 instream=[
1260         ("SIP_DB2","CALCIUM_double","I"),
1261         ("EIP_DB","CALCIUM_double","I")],
1262                 outstream=[           
1263         ("STP_DB2","CALCIUM_double","T"),
1264         ("SIP_DB","CALCIUM_double","I") ],
1265                 defs="""extern "C" {
1266     int espion(void *);
1267     }""",
1268                 body="""
1269                 espion(component);
1270                 """
1271                 ,),
1272         ],
1273                     libs="",
1274                     rlibs=""
1275                     )
1276     
1277     
1278     m=Module("CALCIUM_TESTS",components=[c1,c2,c3],prefix="INSTALL")
1279     
1280     g=Generator(m,context)
1281     g.generate()
1282     ##g.bootstrap()
1283     ##g.configure()
1284     ##g.make()
1285     ##g.install()
1286     ##g.make_appli("appli",restrict=["KERNEL","GUI","YACS"])
1287     
1288 .. [1] The CALCIUM library is shared between several components in a single container, therefore it needs a pointer to the component to identify the requested ports.
1289