5 From the old CALCIUM product to CALCIUM in SALOME
6 -------------------------------------------------------
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.
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.
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).
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).
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.
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:
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.
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).
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.
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.
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.
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:
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.
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).
96 Customisation of the SALOME component for the use of CALCIUM ports consists of:
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.
104 The IDL declaration of components using CALCIUM ports
105 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
106 Since ports are dynamically declared in the init_service method, CALCIUM ports do not need to be previously declared
107 in the IDL file. However, the DSC_Engine.idl file must be included in the components IDL file(s) to benefit from DSC ports.
109 Example of the CALCIUM_TESTS.idl file for the CALCIUM_TEST module defining the three ECODE, SCODE, ESPION components, each
110 of which offers a unique service to start up the corresponding wrapped code:
114 #include "DSC_Engines.idl"
116 /*! \file CALCIUM_TESTS.idl
117 This file contains the first installation test of CALCIUM product.
118 Each engine contains one service.
120 module CALCIUM_TESTS {
122 interface ECODE : Engines::Superv_Component {
126 interface SCODE : Engines::Superv_Component {
130 interface ESPION : Engines::Superv_Component {
136 Declaration of a C++ component using CALCIUM ports
137 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
138 Only one header is necessary in the case of a wrapper component (that does nothing except to call an
139 implementation of another compilation unit):
143 #include “Superv_Component_i.hxx”
145 This header file is necessary to make our component supervisable and to use DSC ports. The component will
146 virtually inherit the Superv_Component_i class.
148 Example ECODE.hxx declaration file for the ECODE component:
155 #include "Superv_Component_i.hxx"
156 //Header CORBA generated from the CALCIUM_TESTS module
157 #include "CALCIUM_TESTS.hh"
159 //Interface for the wrapped code, in this case C code ecode
160 extern "C" { int ecode(void *); }
163 //Implements the CORBA interface for the ECODE component
164 public virtual POA_CALCIUM_TESTS::ECODE,
165 //Makes the component supervisable
166 public virtual Superv_Component_i {
169 //Classical SALOME component constructor
170 ECODE_impl(CORBA::ORB_ptr orb,
171 PortableServer::POA_ptr poa,
172 PortableServer::ObjectId * contId,
173 const char *instanceName,
174 const char *interfaceName);
176 virtual ~ECODE_impl();
178 //Initialisation of the service EcodeGo()
179 CORBA::Boolean init_service(const char * service_name);
185 PortableServer::ObjectId * ECODEEngine_factory(CORBA::ORB_ptr orb,
186 PortableServer::POA_ptr poa,
187 PortableServer::ObjectId * contId,
188 const char *instanceName,
189 const char *interfaceName);
195 Declaration of component resources (part 1)
196 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
197 Components publish signatures of their services in an XML resource file called the module catalog (or components catalog).
199 Extract from the CALCIUM_TESTSCatalog.xml catalog concerning the ECODE component:
201 Our ECODE component provides a unique EcodeGo() service that has no input parameters and no output parameters.
203 The Creating CALCIUM ports section describes how this resource file will be extended by the declaration of datastream ports.
209 <component-name>ECODE</component-name>
211 <component-interface-list>
212 <component-interface-name>ECODE</component-interface-name>
213 <component-interface-comment></component-interface-comment>
214 <component-service-list>
216 <!-- service-identification -->
217 <service-name>EcodeGo</service-name>
219 <!-- service-connexion -->
227 </component-service-list>
228 </component-interface-list>
231 Definition of a component using CALCIUM ports
232 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
233 The component creates the ports that it needs. The step to create a CALCIUM port consists of calling the add_port method
234 provided by the virtual inheritance from the Superv_Component_i class. It must be done before the service(s) that use
235 the port is (are) started. This is why this declaration is located in the
236 standard init_service(char * name_of_service_to_be_initialised) method. There are two methods of creating a
237 CALCIUM port, firstly the create_calcium_port method and secondly the add_port method.
239 Creating CALCIUM ports using the add_port method
240 ++++++++++++++++++++++++++++++++++++++++++++++++++++
241 This method is used to create any type of DSC port. It can be used to create CALCIUM ports in particular.
245 add_port< typing_of_my_fabricated_port >( "the type of port to be fabricated",
250 *"the type of port to be fabricated"*:
251 This string notifies the DSC port factory in the KERNEL module about the name of the type of port
252 to be created. The following types are possible for CALCIUM:
253 “CALCIUM_integer”, “CALCIUM_real”, “CALCIUM_double”, “CALCIUM_logical”, “CALCIUM_complex”,
256 This string indicates if it is a CALCIUM output (uses) port or an input provides port. Note that in the DSC semantic,
257 the provides port provides a write interface used by the uses port.
259 The port name corresponds to the name of the variable used in CALCIUM primitives.
260 *typing_of_my_fabricated_port*:
261 This type types the pointer returned by add_port. The objective for CALCIUM is to indicate the typing corresponding to
262 the type name already given in the factory plus the uses or provides information:
264 - calcium_integer_port_provides or calcium_integer_port_uses
265 - calcium_real_port_provides or calcium_real_port_uses
266 - calcium_double_port_provides or calcium_double_port_uses
267 - calcium_string_port_provides or calcium_string_port_uses
268 - calcium_complex_port_provides or calcium_complex_port_uses
269 - calcium_logical_port_provides or calcium_logical_port_uses
272 Extract from the init_service method in the ECODE.cxx file for the ECODE component:
276 CORBA::Boolean ECODE_impl::init_service(const char * service_name) {
278 CORBA::Boolean rtn = false;
279 string s_name(service_name);
281 if (s_name == "EcodeGo") {
285 add_port<calcium_integer_port_provides>("CALCIUM_integer","provides","ETP_EN")->
286 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
288 add_port<calcium_real_port_provides>("CALCIUM_real","provides","ETP_RE") ->
289 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
291 add_port<calcium_double_port_provides>("CALCIUM_double","provides","ETP_DB")->
292 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
294 add_port<calcium_complex_port_provides>("CALCIUM_complex","provides","ETP_CX")->
295 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
297 add_port<calcium_string_port_provides>("CALCIUM_string","provides","ETP_CH")->
298 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
300 add_port<calcium_logical_port_provides>("CALCIUM_logical","provides","ETP_LQ")->
301 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
304 } catch ( const DSC_Exception & ex ) {
305 std::cerr << ex.what() << std::endl;;
307 } //FIN (s_name == "Ecode")
312 Creating CALCIUM ports using the create_calcium_port method
313 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
314 This method is specially written for the creation of CALCIUM ports, and simplifies the creation of ports.
315 It is used by YACSGEN. The “IN”|”OUT” parameter indicates whether it is a CALCIUM input or output port.
316 The “T”|”I” parameter indicates the port mode, time or iterative.
318 Extract from the init_service method in the ECODE.cxx file for the ECODE component:
323 ECODE_i::init_service(const char * service_name) {
324 CORBA::Boolean rtn = false;
325 string s_name(service_name);
326 if (s_name == "EcodeGo") {
328 //initialisation CALCIUM ports IN
329 create_calcium_port(this,"ETP_EN","CALCIUM_integer","IN","T");
330 create_calcium_port(this,"ETP_RE","CALCIUM_real","IN","T");
331 create_calcium_port(this,"ETP_DB","CALCIUM_double","IN","T");
332 create_calcium_port(this,"ETP_CX","CALCIUM_complex","IN","T");
333 create_calcium_port(this,"ETP_CH","CALCIUM_string","IN","T");
334 create_calcium_port(this,"ETP_LQ","CALCIUM_logical","IN","T");
336 catch(const PortAlreadyDefined& ex) {
337 std::cerr << "ECODE: " << ex.what() << std::endl;
338 //Ports already created : we use them
341 std::cerr << "ECODE: unknown exception" << std::endl;
349 Declaration of component resources (part 2)
350 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
351 The XML component resource file must be completed to declare that CALCIUM ports exist in the different components.
352 YACSGEN takes account of CALCIUM ports in the generation of the module catalog.
354 Extract from the CALCIUM_TESTSCatalog.xml catalog for the ECODE component:
361 <inParameter-name>ETP_EN</inParameter-name>
362 <inParameter-type>CALCIUM_integer</inParameter-type>
363 <inParameter-dependency>T</inParameter-dependency>
366 <inParameter-name>ETP_RE</inParameter-name>
367 <inParameter-type>CALCIUM_real</inParameter-type>
368 <inParameter-dependency>T</inParameter-dependency>
371 <inParameter-name>ETP_DB</inParameter-name>
372 <inParameter-type>CALCIUM_double</inParameter-type>
373 <inParameter-dependency>T</inParameter-dependency>
379 Configuring a CALCIUM port
380 ''''''''''''''''''''''''''''''''''
381 The step to configure ports uses all possible link parameter settings in the CALCIUM coupling file outside SALOME.
382 This step can be done when the port is created in the component (init_service method) by a coupling parameter
383 setting component / script, or by the YACS supervisor. This step indicates the following characteristics
384 for each port in the provides class:
386 - time / iteration dependency of received data:
387 TIME_DEPENDENCY or ITERATION_DEPENDENCY
388 - The data storage level (size of the history stack):
389 UNLIMITED_STORAGE_LEVEL (by default) or a strictly positive integer
390 - The time scheme selected to define the date used in read primitives (CPLxx) in time mode:
392 * TI_SCHEM (default value): Values of the input variable used are taken at the time corresponding to the beginning of
393 the current time step in the calculation (see parameter **ti** of CPLxx)
394 * TF_SCHEM: Values of the input variable are taken at the time corresponding to the end of the current time step
395 in the calculation (see parameter **tf** of CPLxx)
396 * ALPHA_SCHEM: Values of the input variable are taken at an instant equal to TF * *ALPHA* + TI * (1 - *ALPHA*).
397 *ALPHA* can be equal to values strictly between 0 and 1. The value 0 is replaced by the TI_SCHEM option and
398 the value 1 is replaced by the TF_SCHEM option).
400 - The interpolation type to be used for a port in time mode:
402 - The extrapolation type to be used in the case of blockage / timeout:
403 E0_SCHEM, E1_SCHEM (not yet functional)
404 - The value of the DELTAT parameter that indicates if two dates are identical.
406 All of the keywords used when the ports are configured are defined in the CalciumTypes C++ namespace in the CalciumTypes.hxx file.
408 Configuration when the PORT is created
409 +++++++++++++++++++++++++++++++++++++++++++++++++
410 When a port is created, the add_port method returns a pointer to the port useful to its configuration. One example
411 configuration in the init_service method consists of indicating if the port is in time dependency or iteration dependency mode:
415 add_port<calcium_integer_port_provides>("CALCIUM_integer","provides","ETP_EN")->
416 setDependencyType(CalciumTypes::TIME_DEPENDENCY);
419 The following methods are available to configure CALCIUM ports:
421 * Set / Query the dependency type:
423 The dependency type informs the port if the data are stamped by a date or (exclusive) an iteration number. The default
424 dependency type is undefined (CalciumTypes::UNDEFINED_DEPENDENCY). CalciumTYpes::TIME_DEPENDENCY or
425 CalciumTypes::ITERATION_DEPENDENCY can be defined.
429 void setDependencyType (DependencyType dependencyType);
430 DependencyType getDependencyType () const;
433 * Set / Query the storage level of the data produced:
435 The storage level in the history of data produced must be greater than or equal to 1. By default it is
436 unlimited (CalciumTypes::UNLIMITED_STORAGE_LEVEL). It may have to be reduced, to limit memory consumption for the
437 case of a coupling with many iterations.
441 void setStorageLevel (size_t storageLevel);
442 size_t getStorageLevel () const;
445 * Set / Query the time scheme used to define the read date:
447 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 void setDateCalSchem (DateCalSchem dateCalSchem);
452 DateCalSchem getDateCalSchem () const;
455 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.
460 void setAlpha(double alpha);
461 double getAlpha() const ;
464 * Set / Query the tolerated deviation within which two dates will be considered to be identical:
466 Two dates D1 and D2 are identical if abs(T1-T2) <CalciumTypes::EPSILON. Epsilon is equal to 1E-6 by default.
467 Parameters can be set for it on each port (0 <= deltaT <= 1).
471 void setDeltaT(double deltaT );
472 double getDeltaT() const ;
475 * Set / Query the type of time interpolation to be used:
477 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 void setInterpolationSchem (InterpolationSchem interpolationSchem);
482 InterpolationSchem getInterpolationSchem () const ;
484 * Set / Query the type of the extrapolation to be used:
486 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 void setExtrapolationSchem (ExtrapolationSchem extrapolationSchem);
491 ExtrapolationSchem getExtrapolationSchem () const ;
494 Configuration using properties of DSC ports
495 +++++++++++++++++++++++++++++++++++++++++++++++++
496 This section explains advanced use of the properties of DSC ports to perform the CALCIUM ports configuration step, it can
497 be ignored if CALCIUM ports are used in a simple manner.
499 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.
501 The [set|get]_property methods of DSC ports manipulate a list of pairs with a key equal to the name of the property in
502 the first position and the associated value in the second position.
504 Extract from the SALOME_Component.idl file of the SALOME KERNEL:
508 struct KeyValuePair {
512 typedef sequence<KeyValuePair> FieldsDict;
513 void setProperties(in FieldsDict dico);
514 FieldsDict getProperties();
518 CALCIUM declares the following types in the SALOME KERNEL Calcium_Ports.idl file:
522 const long UNLIMITED_STORAGE_LEVEL = -70;
523 enum DependencyType { UNDEFINED_DEPENDENCY, TIME_DEPENDENCY, ITERATION_DEPENDENCY};
524 enum DateCalSchem { TI_SCHEM, TF_SCHEM , ALPHA_SCHEM};
525 enum InterpolationSchem { L0_SCHEM, L1_SCHEM };
526 enum ExtrapolationSchem { UNDEFINED_EXTRA_SCHEM, E0_SCHEM, E1_SCHEM};
529 Therefore, the recognised properties are the following pairs:
531 - (“StorageLevel”, int > 0 )
532 - (“Alpha”, 0 <= double <= 1 )
533 - (“DeltaT”, 0 <= double <= 1 )
534 - (“DependencyType”, enum CORBA DependencyType)
535 - (“DateCalSchem”, enum CORBA DateCalSchem)
536 - (“InterpolationSchem”,enum CORBA InterpolationSchem)
537 - (“ExtrapolationSchem”,enum CORBA ExtrapolationSchem)
539 Example dynamic configuration by a python script (extract from file CAS_1.py):
541 .. code-block:: python
544 port1=ecode.get_provides_port("ETS_DB",0);
546 port1.set_property("StorageLevel",any.to_any(myAny1_1))
549 The get_provides_port and set_property methods are provided by the default implementation of supervisable SALOME components.
551 The configuration in the YACS XML file
552 ++++++++++++++++++++++++++++++++++++++++++++
553 The YACS supervisor module is capable of importing / exporting calculation schemes in the XML format. In particular, this
554 includes the declaration of links between the ports of the different component instances. The YACS GUI generates all sorts of
555 calculation schemes and starts their execution.
557 At the present time, properties cannot be added to CALCIUM ports with YACS GUI. Therefore, they have to be added into
558 the XML file manually. In YACS, calcium ports are configured by declaring properties on the links.
560 Extract from the CAS_1.xml calculation scheme, first test case of CALCIUM functions:
562 Example configuration of the ETS_DB port at a history level of 4.
567 <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
568 <tonode>ECODE</tonode> <toport>ETS_DB</toport>
569 <property name="StorageLevel" value="4"/>
573 (Keys, value) pairs used to describe properties are as listed in the previous section.
575 Calls to CALCIUM methods
576 '''''''''''''''''''''''''''''''
577 The CALCIUM C / C++ / Fortran API in SALOME is globally identical to the API for the CALCIUM product outside SALOME.
578 It is now also available in Python.
580 See :ref:`calciumapi` for C and Fortran API documentation and :mod:`calcium` for Python API documentation.
582 The classical C / C++ API is extended by a zero copy version that transfers data without an intermediate copy.
584 C++ developers can use an API more specific to C++ that proposes parameter types more adapted to the language.
586 It is also possible to use CALCIUM DSC ports more directly with their associated CORBA types.
590 Classical CALCIUM calls in C / C++ / F / Python
591 +++++++++++++++++++++++++++++++++++++++++++++++++
592 The classical CALCIUM API remains essentially the same, regardless of whether the objective is to include an existing
593 CALCIUM C / C ++ / Fortran code in the SALOME platform or to develop a new CALCIUM component.
595 The code containing CALCIUM calls is written directly in the SALOME service of the C++ component, or is accessible through a procedure call.
597 In the first case, the code must be written in C / C++ / Python because there is no SALOME component written directly in Fortran.
599 In the second case, the calling service must transmit the access pointer to its component. Unlike the CALCIUM outside
600 SALOME API, the first argument of all procedures is the pointer of the component that holds the associated ports.
601 This enables the CALCIUM library to identify the component that holds the requested ports [1]_.
603 Extract from the implementation of the EcodeGo() (ECODE.cxx) service calling the ecode wrapped code (void* component)(Ecode.c):
608 void ECODE_impl::EcodeGo() {
609 Superv_Component_i * component = dynamic_cast<Superv_Component_i*>(this);
613 catch ( const CalciumException & ex)
618 A code already written to use CALCIUM only needs to be adapted to transmit the pointer of its component as a first
619 parameter of calls to CALCIUM procedures. Apart from this observation, the code remains exactly the same as the
620 initial calcium code.
622 Extract from the implementation of the calcium source code applied by the service (Ecode.c):
629 int ecode(void * component)
632 /* Connection to the coupler */
633 info = cp_cd(component,nom_instance);
635 info= cp_len(component,CP_TEMPS,&ti_re,&tf_re,&i,"ETP_EN",1,&n,EDATA_EN);
637 info = cp_fin(component,CP_CONT);
642 The C ecode procedure connects to the CALCIUM coupler through the cp_cd procedure and then formulates a blocking read
643 request to the ETP_EN port / connection point according to a time scheme between ti_re and tf_re. Only one data is
644 requested, it will be stored in the EDATA_EN buffer. The procedure finishes when the coupler is disconnected, using
645 the CP_CONT flag to indicate that any clients of ports associated with ecode will receive the most recent known value
646 if there are any new read requests. If the CP_ARRET flag was used, any subsequent read request on the ports associated
647 with ecode() would exit in error.
649 The scheme is the same in fortran, the following is an extract from the Ecode.f file:
651 .. code-block:: fortran
653 SUBROUTINE ECODE(compo)
657 CALL CPCD(compo,nom_instance, info)
659 CALL CPLEN(compo,CP_TEMPS,ti_re,tf_re,i,'ETP_EN',1,n,EDATA_EN,info)
661 CALL CPFIN(compo,CP_CONT, info)
665 CALCIUM C/C++ calls in zero copy mode
666 +++++++++++++++++++++++++++++++++++++++
667 CALCIUM DSC ports of the provides type (CALCIUM entry connection points) keep the received data to be able to create the
668 requested history (unlimited by default). When the user formulates a read for data that are already available, the port
669 copies these data into the buffer provided by the user. An extended CALCIUM API allows the user to supply a null pointer
670 to replace the pre-allocated reception pointer, so as to obtain a pointer to the internal buffer of the CALCIUM provides
671 class port directly. This prevents a potentially large copy, but it obliges the user to be vigilant on the following points:
673 1. The buffer obtained must be used in read only. Unless it is used in a particular manner, any modification to the buffer
674 would be reflected in new read requests for the same stamp or during an interpolation calculation using this stamp.
675 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
676 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.
677 3. Zero copy is not used on integers and booleans because these types do not exist in CORBA.
678 4. The user must call the CALCIUM procedure once only to release the pointer obtained. This releases any buffers created for
679 cases in which a zero copy is impossible. This also helps to count distributed references to prevent early release (not yet implemented).
681 The zero copy API consists of calling ecp_lxx read procedures instead of their corresponding procedure cp_lxx and transferring
682 the address of a pointer for which the value is initialized to zero.
684 The write procedures API is not modified because these procedures still operate in zero copy. If the sender and receiver
685 components are placed in the same container, a copy is triggered on reception of data to prevent any interaction between
686 the sender's buffer and the receiver's buffer.
688 Extract from the zero copy implementation of the CALCIUM source code called by the (Ecode.c) service:
693 float *sav_EDATA_RE = _EDATA_RE; //keep a ptr to previously received data
697 info = ecp_lre(component,CP_TEMPS,&ti_re,&tf_re,&i,"ETP_RE",0,&n,&_EDATA_RE);
698 fprintf(file_2,"%f\n", _EDATA_RE[0]);
702 ecp_lre_free(sav_EDATA_RE);
703 ecp_lre_free(_EDATA_RE);
706 CALCIUM calls with API specific to C++
707 +++++++++++++++++++++++++++++++++++++++++
708 C++ developers can use a specific API that proposes parameters with types better adapted to the language.
710 Time stamps are always of the double type and iterations are always of the long type, regardless of whether it is in write or
711 read and regardless of the type of transmitted data. Variable names are STL strings. The name of read and write methods is
712 the same regardless of the type of data manipulated. The type of data is found automatically, except for complex types,
713 logical types and character strings.
717 template <typename T1, typename T2> static void
718 ecp_ecriture ( Superv_Component_i & component, int const & dependencyType,
719 double const & t, long const & i,
720 const string & nomVar, size_t bufferLength, T1 const & data )
724 template <typename T1, typename T2 > static void
725 ecp_lecture ( Superv_Component_i & component, int const & dependencyType,
726 double & ti, double const & tf, long & i,
727 const string & nomVar, size_t bufferLength,
728 size_t & nRead, T1 * &data )
731 These methods are defined in the CalciumCxxInterface.hxx header file. Therefore the user will include
732 the ``#include ”CalciumCxxInterface.hxx”`` directive in the code.
734 Note: the CalciumInterface.hxx file has to be included only once because it declares and defines C++ template methods.
735 This does not create any problem with compilation, but there is a multiple definition problem during link editing.
737 But there is no need to specify T1 and T2 for integer, float or double CALCIUM types, because there is a write method
738 and a read method with a single template parameter that calls their corresponding methods with the constraint T1==T2==<Type of Data Used>.
740 For complex types, the <float,cplx> instantiation has to be used and the number of complexes has to be multiplied by two to
741 transfer the bufferLength parameter. In this case, the only difference from use of the float type is the typing of the ports
742 used, namely calcium_complex_port_provides instead of calcium_real_port_provides.
744 Instantiation for the logical type is done with <int, bool>.
746 Instantiation for character strings is <char*, str>. The character strings can be read without giving the maximum string
747 length parameter located in the classical C / C++ / Fortran API.
749 Differences from the CALCIUM product outside SALOME
750 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
751 All that are implemented are read / write procedures and connection/disconnection procedures. Step back, query, dynamic
752 configuration and debugging procedures are not implemented.
754 However, it is possible to dynamically create and connect components that read/write on ports of other component services.
755 Any SALOME service using CALCIUM ports has the privileges of a spy (in production mode).
757 Several output ports can be connected to the same input port and one output port can be connected to several input ports.
758 The first case was not possible in CALCIUM outside SALOME.
760 Reads/writes are implemented in blocking mode; non-blocking mode is not yet implemented.
762 All ports created by the different services of a single component are visible / usable by all these services.
763 However, it is not recommended that they should be used in this way.
765 The extrapolation has not yet been implemented.
767 File ports have not yet been implemented, however there are some DSC file ports in SALOME.
769 Ports not connected do not cause any error in execution of coupling unless they are used.
771 CALCIUM error codes returned by primitives are the same as for CALCIUM outside SALOME. By using the specific C++ API,
772 CalciumException class exceptions (CalciumException.hxx) that contain the CALCIUM error code and an explanation message
773 can be caught. The error code contained in the exception is obtained by calling the CalciumTypes::InfoType getInfo() method.
774 The CalciumException class also inherits from the C++ SALOME_Exception exception.
776 A compilation option has to be used to allow C++ exceptions to pass through the C and Fortran codes called from
777 the SALOME component service. This option for GNU compilers is -fexceptions.
779 Data type exchange will be extended to complex types such as MED fields or meshes.
782 Starting CALCIUM coupling
783 --------------------------------
784 CALCIUM coupling can be started in three different ways. The first is to use the SALOME KERNEL only and to manage
785 component instances by a python script. The second is to create a component that would control coupling. The third
786 is to use the YACS supervisor component with or without its GUI.
788 Setting up the environment
789 '''''''''''''''''''''''''''''''''''
790 Regardless of what method is chosen, the KERNEL module has to be notified about the existence of new modules to be used.
791 Only one module needs to be declared if all components are within the same module.
793 This step is no specific to CALCIUM components, it is necessary for all SALOME components.
795 Declaration of <my module>_ROOT_DIR
796 ++++++++++++++++++++++++++++++++++++
797 The KERNEL module is based on a <my module>_ROOT_DIR variable in either a envSalome.sh shell script containing all environment
798 variables useful to SALOME or in the user console, to locate the installation directory of the <my module> module.
800 Example declaration of the CALCIUM_TESTS module in bash:
804 INSTALLROOT="/local/salome/SALOME5/V5NoDebug"
805 export CALCIUM_TESTS=${INSTALLROOT}/DEV/INSTALL/CALCIUM_TESTS
808 The appli_gen.py tool will prepare the appropriate environment in the env.d directory for a SALOME application (see :ref:`appli`).
810 Loading the <my module> module when running SALOME
811 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
812 There are two solutions for loading the <my module> module when SALOME is run.
814 Declaration in the SalomeApp.xml file.
815 #########################################
816 All that is necessary is to declare the name of its module in the modules parameter in the SalomeApp.xml file.
818 The following is an example for the CALCIUM_TESTS module:
822 <section name="launch">
824 <parameter name="modules" value="GEOM,SMESH,VISU,YACS,MED,CALCIUM_TESTS"/>
830 Using the --module option.
831 ################################
832 This option limits loading of modules to the list indicated in the command line (it assumes that the user’s environment
833 indicates the location of the modules).
837 ./runAppli --module=YACS,CALCIUM_TESTS
840 Running a simple coupling through a python script
841 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
842 Components can be created and their ports can be connected using a Python SALOME session.
843 The script CAS_1.py loads instances of the ECODE, SCODE and ESPION components, connects their ports, makes the necessary
844 configurations and starts executions.
846 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:
848 .. code-block:: python
851 import LifeCycleCORBA
860 from omniORB import any
862 #Load component instances through the LifeCycle
863 lcc = LifeCycleCORBA.LifeCycleCORBA()
864 ecode = lcc.FindOrLoad_Component('FactoryServer3', 'ECODE')
865 ecode.init_service("EcodeGo")
866 scode = lcc.FindOrLoad_Component('FactoryServer4', 'SCODE')
867 scode.init_service("ScodeGo")
869 #Display the content of the naming server
870 #Obtain a reference to the connection manager
872 clt=orbmodule.client()
874 connection_manager = clt.Resolve("ConnectionManager")
876 #Create CALCIUM links through the connection manager
877 connection_manager.connect(scode, "STP_EN",ecode, "ETP_EN")
878 connection_manager.connect(scode, "STP_RE", ecode, "ETP_RE")
879 connection_manager.connect(scode, "STP_DB", ecode, "ETP_DB")
880 connection_manager.connect(scode, "SIP_EN", ecode, "EIP_EN")
881 connection_manager.connect(scode, "SIP_DB", ecode, "EIP_DB")
882 connection_manager.connect(scode, "SIS_EN", ecode, "EIS_EN")
883 connection_manager.connect(scode, "SIS_DB", ecode, "EIS_DB")
884 connection_manager.connect(scode, "STS_EN", ecode, "ETS_EN")
885 connection_manager.connect(scode, "STS_DB", ecode, "ETS_DB")
886 port1=ecode.get_provides_port("ETS_DB",0);
888 port1.set_property("StorageLevel",any.to_any(myAny1_1))
889 connection_manager.connect(scode, "STS_DB", ecode, "ETP_DB2")
890 connection_manager.connect(scode, "STP_CX", ecode, "ETP_CX")
891 connection_manager.connect(scode, "STP_CH", ecode, "ETP_CH")
892 connection_manager.connect(scode, "STP_LQ", ecode, "ETP_LQ")
893 #Create and connect the spy (espion)
894 #The ESPION can be created after the instances of ECODE and SCODE have been run,
895 #however data produced before the connection will be lost
896 espion = lcc.FindOrLoad_Component('FactoryServer5', 'ESPION')
897 espion.init_service("EspionGo")
899 connection_manager.connect(scode, "STP_DB2", ecode, "ETP_DB2")
900 connection_manager.connect(espion, "STP_DB2", ecode, "ETP_DB2")
901 connection_manager.connect(scode, "SIP_DB2", espion, "SIP_DB2")
902 connection_manager.connect(espion, "SIP_DB" , ecode , "EIP_DB" )
903 connection_manager.connect(scode, "SIP_DB" , espion, "EIP_DB")
905 #If the spy is run last, CAS_1 works but test 15 does not work
906 handler3=threading.Thread(target=espion.EspionGo)
908 handler=threading.Thread(target=ecode.EcodeGo)
910 handler2=threading.Thread(target=scode.ScodeGo)
919 The script can be run using the following command:
923 ./runAppli -t --module=YACS,CALCIUM_TESTS -u CAS_1.py
925 Running coupling through the YACS GUI
926 '''''''''''''''''''''''''''''''''''''''''''
927 If the module catalog contains the description of components and their services, it is easy to create a coupling scheme by
928 inserting the services of components that are to be linked.
930 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.
932 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.
934 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.
936 Once the scheme has been created, it can be exported in the YACS coupling scheme XML format (see toolbar).
938 The following is a graphic example of the coupling scheme for the first CALCIUM test case:
940 .. image:: images/calcium1.png
943 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/.
944 The study tree becomes the execution tree in which the state of the different services appears. Once it has been
945 run (by pressing the appropriate button in the tool bar), the services are in the ‘done’ state if everything took place correctly.
946 The log of a container associated with execution of a service can be displayed by doing a right click on the service concerned
947 and selecting /Node container Log/. If an error occurs, reports are displayed by selecting /Error Details/ or /Error Report/.
949 As many executions as are necessary can be created. Modifying the edit scheme does not modify existing execution schemes.
950 One execution has to be recreated to start the modified scheme. Do a right click and select /New Edition/ in order to find
951 the edit scheme corresponding to an execution scheme again.
953 Any container configuration is possible:
955 1. several CALCIUM services (for one component or different components) coupled within a single container
956 2. several CALCIUM services (for one component or different components) coupled within different containers
957 3. an intermediate configuration between the previous two cases.
961 1. It is impossible to have several services of a single component simultaneously using distinct CALCIUM ports with the same name.
962 2. It is not possible to restart the same execution because the init_service method will attempt to create existing
963 ports (an execution has to be created or init_service has to be modified so as to memorise the creation of ports).
966 Running coupling through YACS without GUI
967 ''''''''''''''''''''''''''''''''''''''''''
968 To do this, you have to create a schema file in XML format (see :ref:`schemaxml`) and to execute it in console
969 mode (see :ref:`execxml`).
972 Setting up a timeout to interrupt execution in case of interlocking
973 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
974 Sometimes (mainly during development phases), a calculation can ends up in a deadlock. A component waits for a data that
975 another component must send but this component is also waiting and all these components are waiting in a loop, so the calculation
976 never ends : it's a deadlock.
978 There is no way in CALCIUM to detect this deadlock, but it is possible to set a timeout to go out of the deadlock.
979 A timeout is a time in seconds. When a component waits longer than timeout, an error occurs and the calculation is interrupted.
980 The timeout can be specified by setting the environment variable DSC_TIMEOUT (export DSC_TIMEOUT=600, in bash to set a 10 minutes timeout).
981 It must be set before launching a SALOME session and is therefore globally used for all the calculations in the session.
983 It is also possible to specify a timeout in the XML coupling file by way of a service node property (DSC_TIMEOUT) as in
984 the following example:
988 <service name="canal" >
989 <component>FLUIDE</component>
990 <method>prun</method>
991 <load container="A"/>
992 <property name="DSC_TIMEOUT" value="20"/>
993 <instream name="tpi" type="CALCIUM_real"/>
994 <instream name="iconv" type="CALCIUM_integer"/>
995 <outstream name="tfi" type="CALCIUM_real"/>
998 As a consequence, the timeout will be active for all the services in the container of the service (container A in the example).
1000 It is not yet possible to specify a timeout limited to one port or one link.
1002 Creating a SALOME application
1003 --------------------------------------------
1004 Example command invoked to create a SALOME application after adapting the config_appli.xml file:
1008 python $KERNEL_ROOT_DIR/bin/salome/appli_gen.py --prefix=/local/salome5_my_appli \
1009 --config=config_appli_mod.xml
1013 Coupling scheme: example of YACS XML file
1014 -----------------------------------------------
1015 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):
1019 <?xml version='1.0'?>
1021 <type name="Bool" kind="bool"/>
1022 <type name="Double" kind="double"/>
1023 <type name="Int" kind="int"/>
1024 <type name="String" kind="string"/>
1025 <objref name="CALCIUM_complex"
1026 id="IDL:Ports/Calcium_Ports/Calcium_Complex_Port:1.0"/>
1027 <objref name="CALCIUM_double"
1028 id="IDL:Ports/Calcium_Ports/Calcium_Double_Port:1.0"/>
1029 <objref name="CALCIUM_integer"
1030 id="IDL:Ports/Calcium_Ports/Calcium_Integer_Port:1.0"/>
1031 <objref name="CALCIUM_logical"
1032 id="IDL:Ports/Calcium_Ports/Calcium_Logical_Port:1.0"/>
1033 <objref name="CALCIUM_real"
1034 id="IDL:Ports/Calcium_Ports/Calcium_Real_Port:1.0"/>
1035 <objref name="CALCIUM_string"
1036 id="IDL:Ports/Calcium_Ports/Calcium_String_Port:1.0"/>
1037 <objref name="file" id="file"/>
1038 <container name="DefaultContainer">
1039 <property name="container_name" value=""/>
1040 <property name="cpu_clock" value="0"/>
1041 <property name="hostname" value=""/>
1042 <property name="isMPI" value="false"/>
1043 <property name="mem_mb" value="0"/>
1044 <property name="nb_component_nodes" value="0"/>
1045 <property name="nb_node" value="0"/>
1046 <property name="nb_proc_per_node" value="0"/>
1047 <property name="parallelLib" value=""/>
1048 <property name="workingdir" value=""/>
1050 <service name="SCODE">
1051 <component>SCODE</component>
1052 <load container="DefaultContainer"/>
1053 <method>ScodeGo</method>
1054 <outstream name="STP_EN" type="CALCIUM_integer"/>
1055 <outstream name="STP_RE" type="CALCIUM_real"/>
1056 <outstream name="STP_DB" type="CALCIUM_double"/>
1057 <outstream name="STP_CX" type="CALCIUM_complex"/>
1058 <outstream name="STP_CH" type="CALCIUM_string"/>
1059 <outstream name="STP_LQ" type="CALCIUM_logical"/>
1060 <outstream name="SIP_EN" type="CALCIUM_integer"/>
1061 <outstream name="SIP_DB" type="CALCIUM_double"/>
1062 <outstream name="STP_DB2" type="CALCIUM_double"/>
1063 <outstream name="SIS_EN" type="CALCIUM_integer"/>
1064 <outstream name="SIS_DB" type="CALCIUM_double"/>
1065 <outstream name="STS_EN" type="CALCIUM_integer"/>
1066 <outstream name="STS_DB" type="CALCIUM_double"/>
1067 <outstream name="SIP_DB2" type="CALCIUM_double"/>
1069 <service name="ECODE">
1070 <component>ECODE</component>
1071 <load container="DefaultContainer"/>
1072 <method>EcodeGo</method>
1073 <instream name="ETP_EN" type="CALCIUM_integer"/>
1074 <instream name="ETP_RE" type="CALCIUM_real"/>
1075 <instream name="ETP_DB" type="CALCIUM_double"/>
1076 <instream name="ETP_CX" type="CALCIUM_complex"/>
1077 <instream name="ETP_CH" type="CALCIUM_string"/>
1078 <instream name="ETP_LQ" type="CALCIUM_logical"/>
1079 <instream name="EIP_EN" type="CALCIUM_integer"/>
1080 <instream name="EIP_DB" type="CALCIUM_double"/>
1081 <instream name="ETP_DB2" type="CALCIUM_double"/>
1082 <instream name="EIS_EN" type="CALCIUM_integer"/>
1083 <instream name="EIS_DB" type="CALCIUM_double"/>
1084 <instream name="ETS_EN" type="CALCIUM_integer"/>
1085 <instream name="ETS_DB" type="CALCIUM_double"/>
1087 <service name="Espion">
1088 <component>ESPION</component>
1089 <load container="DefaultContainer"/>
1090 <method>EspionGo</method>
1091 <instream name="SIP_DB2" type="CALCIUM_double"/>
1092 <instream name="EIP_DB" type="CALCIUM_double"/>
1093 <outstream name="STP_DB2" type="CALCIUM_double"/>
1094 <outstream name="SIP_DB" type="CALCIUM_double"/>
1097 <fromnode>SCODE</fromnode> <fromport>STP_EN</fromport>
1098 <tonode>ECODE</tonode> <toport>ETP_EN</toport>
1101 <fromnode>SCODE</fromnode> <fromport>STP_RE</fromport>
1102 <tonode>ECODE</tonode> <toport>ETP_RE</toport>
1105 <fromnode>SCODE</fromnode> <fromport>STP_DB</fromport>
1106 <tonode>ECODE</tonode> <toport>ETP_DB</toport>
1109 <fromnode>SCODE</fromnode> <fromport>STP_CX</fromport>
1110 <tonode>ECODE</tonode> <toport>ETP_CX</toport>
1113 <fromnode>SCODE</fromnode> <fromport>STP_CH</fromport>
1114 <tonode>ECODE</tonode> <toport>ETP_CH</toport>
1117 <fromnode>SCODE</fromnode> <fromport>STP_LQ</fromport>
1118 <tonode>ECODE</tonode> <toport>ETP_LQ</toport>
1121 <fromnode>SCODE</fromnode> <fromport>SIP_EN</fromport>
1122 <tonode>ECODE</tonode> <toport>EIP_EN</toport>
1125 <fromnode>SCODE</fromnode> <fromport>SIP_DB</fromport>
1126 <tonode>ECODE</tonode> <toport>EIP_DB</toport>
1129 <fromnode>SCODE</fromnode> <fromport>SIP_DB</fromport>
1130 <tonode>Espion</tonode> <toport>EIP_DB</toport>
1133 <fromnode>SCODE</fromnode> <fromport>STP_DB2</fromport>
1134 <tonode>ECODE</tonode> <toport>ETP_DB2</toport>
1137 <fromnode>SCODE</fromnode> <fromport>SIS_EN</fromport>
1138 <tonode>ECODE</tonode> <toport>EIS_EN</toport>
1141 <fromnode>SCODE</fromnode> <fromport>SIS_DB</fromport>
1142 <tonode>ECODE</tonode> <toport>EIS_DB</toport>
1145 <fromnode>SCODE</fromnode> <fromport>STS_EN</fromport>
1146 <tonode>ECODE</tonode> <toport>ETS_EN</toport>
1149 <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1150 <tonode>ECODE</tonode> <toport>ETS_DB</toport>
1151 <property name="level" value="4"/>
1154 <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1155 <tonode>Espion</tonode> <toport>SIP_DB2</toport>
1158 <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1159 <tonode>Espion</tonode> <toport>EIP_DB</toport>
1162 <fromnode>SCODE</fromnode> <fromport>SIP_DB2</fromport>
1163 <tonode>Espion</tonode> <toport>SIP_DB2</toport>
1166 <fromnode>Espion</fromnode> <fromport>STP_DB2</fromport>
1167 <tonode>ECODE</tonode> <toport>ETP_DB2</toport>
1170 <fromnode>Espion</fromnode> <fromport>SIP_DB</fromport>
1171 <tonode>ECODE</tonode> <toport>EIP_DB</toport>
1178 .. [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.