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).
  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
 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.
 108
 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:
 111
 112 ::
 113
 114     #include "DSC_Engines.idl"
 115
 116     /*! \file CALCIUM_TESTS.idl
 117       This file contains the first installation test of CALCIUM product.
 118       Each engine contains one service.
 119     */
 120     module CALCIUM_TESTS {
 121
 122       interface ECODE : Engines::Superv_Component {
 123         void EcodeGo();
 124       };
 125
 126       interface SCODE : Engines::Superv_Component {
 127         void ScodeGo();
 128       };
 129
 130       interface ESPION : Engines::Superv_Component {
 131         void EspionGo();
 132       };
 133
 134     };
 135
 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):
 140
 141 .. code-block:: cpp
 142
 143   #include “Superv_Component_i.hxx”
 144
 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.
 147
 148 Example ECODE.hxx declaration file for the ECODE component:
 149
 150 .. code-block:: cpp
 151
 152     #ifndef _ECODE_HXX_
 153     #define _ECODE_HXX_
 154
 155     #include "Superv_Component_i.hxx"
 156     //Header CORBA generated from the CALCIUM_TESTS module
 157     #include "CALCIUM_TESTS.hh"
 158
 159     //Interface for the wrapped code, in this case C code ecode
 160     extern "C" { int ecode(void *); }
 161
 162     class ECODE_impl :
 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 {
 167
 168     public :
 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);
 175
 176       virtual ~ECODE_impl();
 177
 178       //Initialisation of the service EcodeGo()
 179       CORBA::Boolean init_service(const char * service_name);
 180       void EcodeGo();
 181     };
 182
 183     extern "C"
 184     {
 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);
 190     }
 191
 192     #endif
 193
 194
 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).
 198
 199 Extract from the CALCIUM_TESTSCatalog.xml catalog concerning the ECODE component:
 200
 201 Our ECODE component provides a unique EcodeGo() service that has no input parameters and no output parameters.
 202
 203 The Creating CALCIUM ports section describes how this resource file will be extended by the declaration of datastream ports.
 204
 205 .. code-block:: xml
 206
 207     ....
 208       <component>
 209             <component-name>ECODE</component-name>
 210           ....
 211             <component-interface-list>
 212                 <component-interface-name>ECODE</component-interface-name>
 213                 <component-interface-comment></component-interface-comment>
 214                 <component-service-list>
 215                     <component-service>
 216                         <!-- service-identification -->
 217                         <service-name>EcodeGo</service-name>
 218                          ...
 219                         <!-- service-connexion -->
 220                         <inParameter-list>
 221                         </inParameter-list>
 222                         <outParameter-list>
 223                         </outParameter-list>
 224                         <DataStream-list>
 225                          </DataStream-list>
 226                     </component-service>
 227                 </component-service-list>
 228             </component-interface-list>
 229       </component>
 230
 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.
 238
 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.
 242
 243 .. code-block:: cpp
 244
 245      add_port< typing_of_my_fabricated_port >( "the type of port to be fabricated",
 246                                               "provides"|”uses”,
 247                                               "the port name")
 248
 249
 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”,
 254   “CALCIUM_string”
 255 *“provides”|”uses”*:
 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.
 258 *“the port name”*:
 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:
 263
 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
 270
 271
 272 Extract from the init_service method in the ECODE.cxx file for the ECODE component:
 273
 274 .. code-block:: cpp
 275
 276     CORBA::Boolean ECODE_impl::init_service(const char * service_name) {
 277
 278       CORBA::Boolean rtn = false;
 279       string s_name(service_name);
 280
 281       if (s_name == "EcodeGo") {
 282
 283         try {
 284
 285         add_port<calcium_integer_port_provides>("CALCIUM_integer","provides","ETP_EN")->
 286           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 287
 288          add_port<calcium_real_port_provides>("CALCIUM_real","provides","ETP_RE") ->
 289           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 290
 291         add_port<calcium_double_port_provides>("CALCIUM_double","provides","ETP_DB")->
 292           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 293
 294         add_port<calcium_complex_port_provides>("CALCIUM_complex","provides","ETP_CX")->
 295           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 296
 297         add_port<calcium_string_port_provides>("CALCIUM_string","provides","ETP_CH")->
 298           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 299
 300         add_port<calcium_logical_port_provides>("CALCIUM_logical","provides","ETP_LQ")->
 301           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 302      ....
 303         rtn = true;
 304         } catch ( const DSC_Exception & ex ) {
 305           std::cerr << ex.what() << std::endl;;
 306         }
 307       } //FIN (s_name == "Ecode")
 308
 309       return rtn;
 310     }
 311
 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.
 317
 318 Extract from the init_service method in the ECODE.cxx file for the ECODE component:
 319
 320
 321 .. code-block:: cpp
 322
 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")   {
 327             try   {
 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");
 335     ...      }
 336            catch(const PortAlreadyDefined& ex)   {
 337                std::cerr << "ECODE: " << ex.what() << std::endl;
 338                //Ports already created : we use them
 339             }
 340            catch ( ... )   {
 341                std::cerr << "ECODE: unknown exception" << std::endl;
 342             }
 343            rtn = true;
 344          }
 345        return rtn;
 346      }
 347
 348
 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.
 353
 354 Extract from the CALCIUM_TESTSCatalog.xml catalog for the ECODE component:
 355
 356 .. code-block:: xml
 357
 358     .....
 359                         <DataStream-list>
 360                            <inParameter>
 361                               <inParameter-name>ETP_EN</inParameter-name>
 362                               <inParameter-type>CALCIUM_integer</inParameter-type>
 363                               <inParameter-dependency>T</inParameter-dependency>
 364                            </inParameter>
 365                            <inParameter>
 366                               <inParameter-name>ETP_RE</inParameter-name>
 367                               <inParameter-type>CALCIUM_real</inParameter-type>
 368                               <inParameter-dependency>T</inParameter-dependency>
 369                            </inParameter>
 370                            <inParameter>
 371                               <inParameter-name>ETP_DB</inParameter-name>
 372                               <inParameter-type>CALCIUM_double</inParameter-type>
 373                               <inParameter-dependency>T</inParameter-dependency>
 374                            </inParameter>
 375     .....
 376                         </DataStream-list>
 377
 378
 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:
 385
 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:
 391
 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).
 399
 400 - The interpolation type to be used for a port in time mode:
 401      L0_SCHEM, L1_SCHEM
 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.
 405
 406 All of the keywords used when the ports are configured are defined in the CalciumTypes C++ namespace in the CalciumTypes.hxx file.
 407
 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:
 412
 413 .. code-block:: cpp
 414
 415       add_port<calcium_integer_port_provides>("CALCIUM_integer","provides","ETP_EN")->
 416           setDependencyType(CalciumTypes::TIME_DEPENDENCY);
 417
 418
 419 The following methods are available to configure CALCIUM ports:
 420
 421 * Set / Query the dependency type:
 422
 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.
 426
 427 .. code-block:: cpp
 428
 429      void setDependencyType (DependencyType dependencyType);
 430      DependencyType getDependencyType () const;
 431
 432
 433 * Set / Query the storage level of the data produced:
 434
 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.
 438
 439 .. code-block:: cpp
 440
 441      void   setStorageLevel   (size_t storageLevel);
 442      size_t getStorageLevel   () const;
 443
 444
 445 * Set / Query the time scheme used to define the read date:
 446
 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.
 448
 449 .. code-block:: cpp
 450
 451       void                  setDateCalSchem   (DateCalSchem   dateCalSchem);
 452       DateCalSchem getDateCalSchem () const;
 453
 454
 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.
 456
 457
 458 .. code-block:: cpp
 459
 460     void     setAlpha(double alpha);
 461     double getAlpha() const ;
 462
 463
 464 * Set / Query the tolerated deviation within which two dates will be considered to be identical:
 465
 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).
 468
 469 .. code-block:: cpp
 470
 471       void     setDeltaT(double deltaT );
 472       double getDeltaT() const ;
 473
 474
 475 * Set / Query the type of time interpolation to be used:
 476
 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”.
 478
 479 .. code-block:: cpp
 480
 481       void setInterpolationSchem (InterpolationSchem interpolationSchem);
 482       InterpolationSchem getInterpolationSchem () const ;
 483
 484 * Set / Query the type of the extrapolation to be used:
 485
 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).
 487
 488 .. code-block:: cpp
 489
 490      void setExtrapolationSchem (ExtrapolationSchem extrapolationSchem);
 491      ExtrapolationSchem getExtrapolationSchem () const ;
 492
 493
 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.
 498
 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.
 500
 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.
 503
 504 Extract from the SALOME_Component.idl file of the SALOME KERNEL:
 505
 506 ::
 507
 508      struct KeyValuePair  {
 509         string key;
 510         any value;
 511       };
 512      typedef sequence<KeyValuePair> FieldsDict;
 513      void setProperties(in FieldsDict dico);
 514      FieldsDict getProperties();
 515
 516
 517
 518 CALCIUM declares the following types in the SALOME KERNEL Calcium_Ports.idl file:
 519
 520 ::
 521
 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};
 527
 528
 529 Therefore, the recognised properties are the following pairs:
 530
 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)
 538
 539 Example dynamic configuration by a python script (extract from file CAS_1.py):
 540
 541 .. code-block:: python
 542
 543     ...
 544     port1=ecode.get_provides_port("ETS_DB",0);
 545     myAny1_1=4
 546     port1.set_property("StorageLevel",any.to_any(myAny1_1))
 547
 548
 549 The get_provides_port and set_property methods are provided by the default implementation of supervisable SALOME components.
 550
 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.
 556
 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.
 559
 560 Extract from the CAS_1.xml calculation scheme, first test case of CALCIUM functions:
 561
 562 Example configuration of the ETS_DB port at a history level of 4.
 563
 564 .. code-block:: xml
 565
 566      <stream>
 567           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
 568           <tonode>ECODE</tonode> <toport>ETS_DB</toport>
 569           <property name="StorageLevel" value="4"/>
 570        </stream>
 571
 572
 573 (Keys, value) pairs used to describe properties are as listed in the previous section.
 574
 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.
 579
 580 See :ref:`calciumapi` for C and Fortran API documentation and :mod:`calcium` for Python API documentation.
 581
 582 The classical C / C++ API is extended by a zero copy version that transfers data without an intermediate copy.
 583
 584 C++ developers can use an API more specific to C++ that proposes parameter types more adapted to the language.
 585
 586 It is also possible to use CALCIUM DSC ports more directly with their associated CORBA types.
 587
 588
 589
 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.
 594
 595 The code containing CALCIUM calls is written directly in the SALOME service of the C++ component, or is accessible through a procedure call.
 596
 597 In the first case, the code must be written in C / C++ / Python because there is no SALOME component written directly in Fortran.
 598
 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]_.
 602
 603 Extract from the implementation of the EcodeGo() (ECODE.cxx) service calling the ecode wrapped code (void* component)(Ecode.c):
 604
 605
 606 .. code-block:: cpp
 607
 608     void ECODE_impl::EcodeGo() {
 609       Superv_Component_i * component = dynamic_cast<Superv_Component_i*>(this);
 610       try {
 611         ecode(component);
 612       }
 613       catch ( const CalciumException & ex)
 614     ....
 615     }
 616
 617
 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.
 621
 622 Extract from the implementation of the calcium source code applied by the service (Ecode.c):
 623
 624 .. code-block:: c
 625
 626     ...
 627     #include <calcium.h>
 628     ...
 629     int    ecode(void * component)
 630     {
 631     ...
 632     /*    Connection to the coupler   */
 633         info = cp_cd(component,nom_instance);
 634
 635         info= cp_len(component,CP_TEMPS,&ti_re,&tf_re,&i,"ETP_EN",1,&n,EDATA_EN);
 636     ...
 637         info = cp_fin(component,CP_CONT);
 638     }
 639
 640
 641
 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.
 648
 649 The scheme is the same in fortran, the following is an extract from the Ecode.f file:
 650
 651 .. code-block:: fortran
 652
 653         SUBROUTINE ECODE(compo)
 654         INCLUDE 'calcium.hf'
 655         INTEGER compo
 656         ----
 657         CALL CPCD(compo,nom_instance, info)
 658         ----
 659         CALL CPLEN(compo,CP_TEMPS,ti_re,tf_re,i,'ETP_EN',1,n,EDATA_EN,info)
 660         ----
 661         CALL CPFIN(compo,CP_CONT, info)
 662         ----
 663
 664
 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:
 672
 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).
 680
 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.
 683
 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.
 687
 688 Extract from the zero copy implementation of the CALCIUM source code called by the (Ecode.c) service:
 689
 690
 691 .. code-block:: c
 692
 693         float *sav_EDATA_RE = _EDATA_RE; //keep a ptr to previously received data
 694         _EDATA_RE = NULL;
 695         ti_re = 1.1;
 696         tf_re = 1.2;
 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]);
 699         ti_re = 0.0;
 700         tf_re = 1.0;
 701
 702         ecp_lre_free(sav_EDATA_RE);
 703         ecp_lre_free(_EDATA_RE);
 704
 705
 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.
 709
 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.
 714
 715 .. code-block:: cpp
 716
 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 )
 721
 722
 723
 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 )
 729
 730
 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.
 733
 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.
 736
 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>.
 739
 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.
 743
 744 Instantiation for the logical type is done with <int, bool>.
 745
 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.
 748
 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.
 753
 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).
 756
 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.
 759
 760 Reads/writes are implemented in blocking mode;  non-blocking mode is not yet implemented.
 761
 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.
 764
 765 The extrapolation has not yet been implemented.
 766
 767 File ports have not yet been implemented, however there are some DSC file ports in SALOME.
 768
 769 Ports not connected do not cause any error in execution of coupling unless they are used.
 770
 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.
 775
 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.
 778
 779 Data type exchange will be extended to complex types such as MED fields or meshes.
 780
 781
 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.
 787
 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.
 792
 793 This step is no specific to CALCIUM components, it is necessary for all SALOME components.
 794
 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.
 799
 800 Example declaration of the CALCIUM_TESTS module in bash:
 801
 802 .. code-block:: sh
 803
 804     INSTALLROOT="/local/salome/SALOME5/V5NoDebug"
 805     export CALCIUM_TESTS=${INSTALLROOT}/DEV/INSTALL/CALCIUM_TESTS
 806
 807
 808 The appli_gen.py tool will prepare the appropriate environment in the env.d directory for a SALOME application (see :ref:`appli`).
 809
 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.
 813
 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.
 817
 818 The following is an example for the CALCIUM_TESTS module:
 819
 820 .. code-block:: xml
 821
 822      <section name="launch">
 823      ....
 824      <parameter name="modules"    value="GEOM,SMESH,VISU,YACS,MED,CALCIUM_TESTS"/>
 825      ....
 826      </section>
 827
 828
 829
 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).
 834
 835 .. code-block:: sh
 836
 837     ./runAppli  --module=YACS,CALCIUM_TESTS
 838
 839
 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.
 845
 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:
 847
 848 .. code-block:: python
 849
 850
 851     import LifeCycleCORBA
 852     import Engines
 853     import Ports
 854     import CALCIUM_TESTS
 855     import orbmodule
 856     import user
 857
 858     import sys
 859     import threading
 860     from omniORB import any
 861
 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")
 868
 869     #Display the content of the naming server
 870     #Obtain a reference to the connection manager
 871
 872     clt=orbmodule.client()
 873     clt.showNS()
 874     connection_manager = clt.Resolve("ConnectionManager")
 875
 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);
 887     myAny1_1=4
 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")
 898
 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")
 904
 905     #If the spy is run last, CAS_1 works but test 15 does not work
 906     handler3=threading.Thread(target=espion.EspionGo)
 907     handler3.start()
 908     handler=threading.Thread(target=ecode.EcodeGo)
 909     handler.start()
 910     handler2=threading.Thread(target=scode.ScodeGo)
 911     handler2.start()
 912
 913     handler.join()
 914     handler2.join()
 915     handler3.join()
 916
 917
 918
 919 The script can be run using the following command:
 920
 921 .. code-block:: sh
 922
 923   ./runAppli -t --module=YACS,CALCIUM_TESTS -u CAS_1.py
 924
 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.
 929
 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.
 931
 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.
 933
 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.
 935
 936 Once the scheme has been created, it can be exported in the YACS coupling scheme XML format (see toolbar).
 937
 938 The following is a graphic example of the coupling scheme for the first CALCIUM test case:
 939
 940 .. image:: images/calcium1.png
 941   :align: center
 942
 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/.
 948
 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.
 952
 953 Any container configuration is possible:
 954
 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.
 958
 959 Current limitations:
 960
 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).
 964
 965
 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`).
 970
 971
 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.
 977
 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.
 982
 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:
 985
 986 .. code-block:: xml
 987
 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"/>
 996       </service>
 997
 998 As a consequence, the timeout will be active for all the services in the container of the service (container A in the example).
 999
1000 It is not yet possible to specify a timeout limited to one port or one link.
1001
1002 Creating a SALOME application
1003 --------------------------------------------
1004 Example command invoked to create a SALOME application after adapting the config_appli.xml file:
1005
1006 .. code-block:: sh
1007
1008     python $KERNEL_ROOT_DIR/bin/salome/appli_gen.py --prefix=/local/salome5_my_appli \
1009                                                     --config=config_appli_mod.xml
1010
1011
1012
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):
1016
1017 .. code-block:: xml
1018
1019     <?xml version='1.0'?>
1020     <proc>
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=""/>
1049        </container>
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"/>
1068        </service>
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"/>
1086        </service>
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"/>
1095        </service>
1096        <stream>
1097           <fromnode>SCODE</fromnode> <fromport>STP_EN</fromport>
1098           <tonode>ECODE</tonode> <toport>ETP_EN</toport>
1099        </stream>
1100        <stream>
1101           <fromnode>SCODE</fromnode> <fromport>STP_RE</fromport>
1102           <tonode>ECODE</tonode> <toport>ETP_RE</toport>
1103        </stream>
1104        <stream>
1105           <fromnode>SCODE</fromnode> <fromport>STP_DB</fromport>
1106           <tonode>ECODE</tonode> <toport>ETP_DB</toport>
1107        </stream>
1108        <stream>
1109           <fromnode>SCODE</fromnode> <fromport>STP_CX</fromport>
1110           <tonode>ECODE</tonode> <toport>ETP_CX</toport>
1111        </stream>
1112        <stream>
1113           <fromnode>SCODE</fromnode> <fromport>STP_CH</fromport>
1114           <tonode>ECODE</tonode> <toport>ETP_CH</toport>
1115        </stream>
1116        <stream>
1117           <fromnode>SCODE</fromnode> <fromport>STP_LQ</fromport>
1118           <tonode>ECODE</tonode> <toport>ETP_LQ</toport>
1119        </stream>
1120        <stream>
1121           <fromnode>SCODE</fromnode> <fromport>SIP_EN</fromport>
1122           <tonode>ECODE</tonode> <toport>EIP_EN</toport>
1123        </stream>
1124        <stream>
1125           <fromnode>SCODE</fromnode> <fromport>SIP_DB</fromport>
1126           <tonode>ECODE</tonode> <toport>EIP_DB</toport>
1127        </stream>
1128        <stream>
1129           <fromnode>SCODE</fromnode> <fromport>SIP_DB</fromport>
1130           <tonode>Espion</tonode> <toport>EIP_DB</toport>
1131        </stream>
1132        <stream>
1133           <fromnode>SCODE</fromnode> <fromport>STP_DB2</fromport>
1134           <tonode>ECODE</tonode> <toport>ETP_DB2</toport>
1135        </stream>
1136        <stream>
1137           <fromnode>SCODE</fromnode> <fromport>SIS_EN</fromport>
1138           <tonode>ECODE</tonode> <toport>EIS_EN</toport>
1139        </stream>
1140        <stream>
1141           <fromnode>SCODE</fromnode> <fromport>SIS_DB</fromport>
1142           <tonode>ECODE</tonode> <toport>EIS_DB</toport>
1143        </stream>
1144        <stream>
1145           <fromnode>SCODE</fromnode> <fromport>STS_EN</fromport>
1146           <tonode>ECODE</tonode> <toport>ETS_EN</toport>
1147        </stream>
1148        <stream>
1149           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1150           <tonode>ECODE</tonode> <toport>ETS_DB</toport>
1151           <property name="level" value="4"/>
1152        </stream>
1153        <stream>
1154           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1155           <tonode>Espion</tonode> <toport>SIP_DB2</toport>
1156        </stream>
1157        <stream>
1158           <fromnode>SCODE</fromnode> <fromport>STS_DB</fromport>
1159           <tonode>Espion</tonode> <toport>EIP_DB</toport>
1160        </stream>
1161        <stream>
1162           <fromnode>SCODE</fromnode> <fromport>SIP_DB2</fromport>
1163           <tonode>Espion</tonode> <toport>SIP_DB2</toport>
1164        </stream>
1165        <stream>
1166           <fromnode>Espion</fromnode> <fromport>STP_DB2</fromport>
1167           <tonode>ECODE</tonode> <toport>ETP_DB2</toport>
1168        </stream>
1169        <stream>
1170           <fromnode>Espion</fromnode> <fromport>SIP_DB</fromport>
1171           <tonode>ECODE</tonode> <toport>EIP_DB</toport>
1172        </stream>
1173     </proc>
1174
1175
1176
1177
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.
1179