doc/calciumapi.rst

   1
   2 .. _calciumapi:
   3
   4
   5 ==========================================================
   6 CALCIUM C and Fortran coupling library
   7 ==========================================================
   8 This section is the CALCIUM coupling library reference for C and Fortran.
   9 For python, see module :mod:`calcium`.
  10
  11 Presentation is done in the following order:
  12
  13 - include files : constants
  14 - functions to connect and disconnect
  15 - functions to export data
  16 - functions to import data
  17 - functions to erase data
  18 - examples
  19 - error codes
  20
  21 Include files
  22 ====================
  23 All constants used with the coupling library are defined in an include file.
  24
  25 **C:**
  26
  27 .. code-block:: c
  28
  29    #include "calcium.h"
  30
  31 **Fortran:**
  32
  33 .. code-block:: fortran
  34
  35    INCLUDE 'calcium.hf'
  36
  37 These constants are:
  38
  39 - Error codes (see :ref:`errcodes`)
  40 - Dependency modes (CP_TEMPS, CP_ITERATION or CP_SEQUENTIEL)
  41 - Disconnection modes (CP_CONT or CP_ARRET)
  42
  43
  44 .. default-domain:: c
  45
  46 Functions to connect and disconnect
  47 ===============================================
  48
  49 **C:**
  50
  51 .. function:: int info = cp_cd(long *compo, char *instance_name)
  52
  53    Initialize the connection with YACS.
  54
  55 **Fortran:**
  56
  57 .. function:: call cpcd(compo, instance_name, info)
  58
  59    :param compo: component address
  60    :type compo: long
  61    :param instance_name: instance name given by YACS
  62    :type instance_name: 64 characters string, output
  63    :param info: error code (possible codes: CPMACHINE)
  64    :type info: int, return
  65
  66
  67 **C:**
  68
  69 .. function:: int info = cp_fin(long *compo, int directive)
  70
  71    Close the connection with YACS.
  72
  73 **Fortran:**
  74
  75 .. function:: call cpfin(compo, directive, info)
  76
  77    :param compo: component address
  78    :type compo: long
  79    :param directive: indicate how variables will be handled after disconnection. If directive = CP_CONT,
  80      variables produced by this component are defined constant beyond the last time or iteration number. If
  81      directive = CP_ARRET, variables are not defined beyond the last step.
  82    :type directive: int
  83    :param info: error code (possible codes: CPDNDI)
  84    :type info: int, return
  85
  86
  87 Functions to export data
  88 ===============================
  89 Writing requests is the way for a component to export data through one of its
  90 output ports. nm_var is the port name.
  91
  92 Each request exports n values from the var_xxx array. Exported values are defined
  93 at time t if mode is CP_TEMPS or at iteration number i if mode is CP_ITERATION.
  94
  95 It is mandatory to export data at increasing times or iteration numbers.
  96 The export is done in an asynchronous way. Control is given back to the caller as
  97 soon as data have been sent.
  98
  99 There is generally one request for each data type to export. Each request can be used with one and only port type.
 100 For long type, two requests are available (cp_elg and cp_eln). One (cp_elg) is working with CALCIUM_integer port type
 101 and the second (cp_eln) is working with CALCIUM_long port type.
 102
 103 The available port types are :
 104
 105 - CALCIUM_integer
 106 - CALCIUM_long
 107 - CALCIUM_float
 108 - CALCIUM_double
 109 - CALCIUM_complex
 110 - CALCIUM_string
 111 - CALCIUM_logical
 112
 113 **C:**
 114
 115 .. function:: int info = cp_ere(long *compo, int dep, float t, int i, char *nm_var, int n, float *var_real)
 116
 117         for single precision floating point values (C float type and CALCIUM_float port type)
 118 .. function:: int info = cp_edb(long *compo, int dep, double td, int i, char *nm_var, int n, double *var_double)
 119
 120         for double precision floating point values (C double type and CALCIUM_double port type)
 121 .. function:: int info = cp_ecp(long *compo, int dep, float t, int i, char *nm_var, int n, float *var_complex)
 122
 123         for complex values (C float type and CALCIUM_complex port type)
 124 .. function:: int info = cp_een(long *compo, int dep, float t, int i, char *nm_var, int n, int *var_integer)
 125
 126         for integer values (C int type and CALCIUM_integer port type)
 127 .. function:: int info = cp_elg(long *compo, int dep, float t, int i, char *nm_var, int n, long *var_long)
 128
 129         for integer values (C long type and CALCIUM_integer port type)
 130 .. function:: int info = cp_eln(long *compo, int dep, float t, int i, char *nm_var, int n, long *var_long)
 131
 132         for integer values (C long type and CALCIUM_long port type)
 133 .. function:: int info = cp_elo(long *compo, int dep, float t, int i, char *nm_var, int n, int *var_boolean)
 134
 135         for boolean values (C int type and CALCIUM_logical port type)
 136 .. function:: int info = cp_ech(long *compo, int dep, float t, int i, char *nm_var, int n, char **var_string, int strSize)
 137
 138         for string values (C char* type and CALCIUM_string port type)
 139
 140 **Fortran:**
 141
 142 .. function:: CALL CPERE(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, REAL*4 var_real,      INTEGER info)
 143 .. function:: CALL CPEDB(LONGP compo, INTEGER dep, REAL*8 td, INTEGER i, nm_var, INTEGER n, REAL*8 var_double,    INTEGER info)
 144 .. function:: CALL CPECP(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, REAL*4 var_complex,   INTEGER info)
 145 .. function:: CALL CPEEN(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, INTEGER var_integer,  INTEGER info)
 146 .. function:: CALL CPELG(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, INTEGER*8 var_long,   INTEGER info)
 147
 148                can only be used on 64 bits architecture.
 149 .. function:: CALL CPELN(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, INTEGER*8 var_long,   INTEGER info)
 150
 151                can only be used on 64 bits architecture.
 152 .. function:: CALL CPEIN(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, INTEGER*4 var_int,    INTEGER info)
 153 .. function:: CALL CPELO(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, INTEGER*4 var_boolean,INTEGER info)
 154 .. function:: CALL CPECH(LONGP compo, INTEGER dep, REAL*4 t,  INTEGER i, nm_var, INTEGER n, var_string,           INTEGER info)
 155
 156    :param compo: component address
 157    :type compo: long
 158    :param dep: dependency type - CP_TEMPS (time dependency) or CP_ITERATION (iteration dependency)
 159    :type dep: int
 160    :param t: time value if dep=CP_TEMPS
 161    :type t: float
 162    :param td: time value if dep=CP_TEMPS
 163    :type td: double
 164    :param i: iteration number if dep=CP_ITERATION
 165    :type i: int
 166    :param nm_var: port name
 167    :type nm_var: string (64 characters)
 168    :param n: number of values to export (from var_xxx array)
 169    :type n: int
 170    :param var_real: array containing the values to export
 171    :type var_real: float array
 172    :param var_complex: array containing the values to export (array size is twice the number of complex numbers)
 173    :type var_complex: float array
 174    :param var_integer: array containing the values to export
 175    :type var_integer: int array
 176    :param var_long: array containing the values to export
 177    :type var_long: long array
 178    :param var_boolean: array containing the values to export
 179    :type var_boolean: int array
 180    :param var_string: array containing the values to export
 181    :type var_string: array of strings
 182    :param var_double: array containing the values to export
 183    :type var_double: double array
 184    :param strSize: size of strings in var_string
 185    :type strSize: int
 186    :param info: error code (possible codes: CPIT, CPITVR, CPNMVR, CPNTNULL, CPIOVR, CPTPVR or CPCTVR)
 187    :type info: int, return
 188
 189 .. note::
 190    LONGP is a Fortran type that is same size as the C long type, so, most of a time, INTEGER\*4 for 32 bits architecture
 191    and INTEGER\*8 for 64 bits architecture.
 192
 193 .. warning::
 194    CPELG (or cp_elg) can produce wrong results (conversion problem) on 64 bits architecture if the KERNEL module is built
 195    with the default option (--with-cal_int=int)
 196
 197 See :ref:`fortran64bits` for more details.
 198
 199
 200 Functions to import data
 201 =============================
 202 Reading requests is the way for a component to import data through one of its
 203 input ports. nm_var is the port name. Import is only possible if the input port
 204 is connected to an output port.
 205
 206 Reading requests can be of two kinds:
 207   - standard request
 208   - sequential request
 209
 210 A standard request imports data at a given time or iteration number. In case of time dependency, the effective time
 211 is calculated by YACS from the interval time (ti, tf) and the interpolation scheme that is given in the coupling file.
 212
 213 A sequential request imports data in a sequential way. Each request returns
 214 the next data with its associated time or iteration number.
 215
 216 There is generally one request for each data type to import. Each request can be used with one and only port type.
 217 For long type, two requests are available (cp_llg and cp_lln). One (cp_llg) is working with CALCIUM_integer port type
 218 and the second (cp_lln) is working with CALCIUM_long port type.
 219
 220 **C:**
 221
 222 .. function:: int info = cp_lre(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, float *var_real)
 223 .. function:: int info = cp_ldb(long *compo, int dep, double *tid, double *tfd, int *i, char *nm_var, int len, int *n, double *var_double)
 224 .. function:: int info = cp_lcp(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, float *var_complex)
 225 .. function:: int info = cp_len(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, int *var_integer)
 226 .. function:: int info = cp_llg(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, long *var_long)
 227 .. function:: int info = cp_lln(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, long *var_long)
 228 .. function:: int info = cp_llo(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, int *var_boolean)
 229 .. function:: int info = cp_lch(long *compo, int dep, float *ti, float *tf, int *i, char *nm_var, int len, int *n, char **var_string, int strSize)
 230
 231 **Fortran:**
 232
 233 .. function:: CALL CPLRE(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,REAL*4 var_real,      INTEGER info)
 234 .. function:: CALL CPLDB(LONGP compo, INTEGER dep, REAL*8 tid, tf, INTEGER i, nm_var,INTEGER len, INTEGER n,REAL*8 var_double,    INTEGER info)
 235 .. function:: CALL CPLCP(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,REAL*4 var_complex,   INTEGER info)
 236 .. function:: CALL CPLEN(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,INTEGER var_integer,  INTEGER info)
 237 .. function:: CALL CPLLG(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,INTEGER*8 var_long,   INTEGER info)
 238
 239                can only be used on 64 bits architecture.
 240 .. function:: CALL CPLLN(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,INTEGER*8 var_long,   INTEGER info)
 241
 242                can only be used on 64 bits architecture.
 243 .. function:: CALL CPLIN(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,INTEGER*4 var_int,    INTEGER info)
 244 .. function:: CALL CPLLO(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,INTEGER*4 var_boolean,INTEGER info)
 245 .. function:: CALL CPLCH(LONGP compo, INTEGER dep, REAL*4 ti,  tf, INTEGER i, nm_var,INTEGER len, INTEGER n,var_string,           INTEGER info)
 246
 247    :param compo: component address
 248    :type compo: long
 249    :param dep: dependency type - CP_TEMPS (time dependency) or CP_ITERATION (iteration dependency)
 250    :type dep: int
 251    :param ti: interval start time if dep=CP_TEMPS or associated time if dep=CP_SEQUENTIEL
 252    :type ti: float, inout
 253    :param tf: interval end time if dep=CP_TEMPS
 254    :type tf: float
 255    :param tid: interval start time if dep=CP_TEMPS or associated time if dep=CP_SEQUENTIEL
 256    :type tid: double, inout
 257    :param tfd: interval end time if dep=CP_TEMPS
 258    :type tfd: double
 259    :param i: iteration number if dep=CP_ITERATION or dep=CP_SEQUENTIEL
 260    :type i: int, inout
 261    :param nm_var: port name
 262    :type nm_var: string (64 characters)
 263    :param len: size of var_xxx array
 264    :type len: int
 265    :param n: effective number of values imported (into var_xxx array)
 266    :type n: int, out
 267    :param var_real: array containing the values imported
 268    :type var_real: float array, out
 269    :param var_complex: array containing the values imported (array size is twice the number of complex numbers)
 270    :type var_complex: float array, out
 271    :param var_integer: array containing the values imported
 272    :type var_integer: int array, out
 273    :param var_long: array containing the values imported
 274    :type var_long: long array, out
 275    :param var_boolean: array containing the values imported
 276    :type var_boolean: int array, out
 277    :param var_string: array containing the values imported
 278    :type var_string: array of strings (char*), out
 279    :param var_double: array containing the values imported
 280    :type var_double: double array, out
 281    :param strSize: size of strings in var_string
 282    :type strSize: int
 283    :param info: error code (possible codes: CPIT, CPITVR, CPNMVR, CPNTNULL, CPIOVR, CPTPVR, CPLIEN, CPATTENTE, CPLGVR or CPSTOP)
 284    :type info: int, return
 285
 286 .. note::
 287    LONGP is a Fortran type that is same size as the C long type, so, most of a time, INTEGER\*4 for 32 bits architecture
 288    and INTEGER\*8 for 64 bits architecture.
 289
 290 .. warning::
 291    CPLLG (or cp_llg) can produce wrong results (conversion problem) on 64 bits architecture if the KERNEL module is built
 292    with the default option (--with-cal_int=int)
 293
 294 See :ref:`fortran64bits` for more details.
 295
 296 Functions to erase data
 297 ==========================
 298 The functions cp_fini and cp_fint are used to request that all values of the specified
 299 variable defined for iteration number or time before a given one be erased.
 300
 301 The functions cp_effi and cp_efft are used to request that all values of the specified
 302 variable defined for iteration number or time after a given one be erased.
 303
 304 **C:**
 305
 306 .. function:: int info = cp_fini(long *compo, char *nm_var, int i)
 307
 308    Erase all values of port nm_var before iteration i
 309
 310 **Fortran:**
 311
 312 .. function:: call cpfini(compo, nm_var, i, info)
 313
 314    :param compo: component address
 315    :type compo: long
 316    :param nm_var: port name
 317    :type nm_var: string
 318    :param i: iteration number
 319    :type i: int
 320    :param info: error code
 321    :type info: int, return
 322
 323 **C:**
 324
 325 .. function:: int info = cp_fint(long *compo, char *nm_var, float t)
 326
 327    Erase all values of port nm_var before time t
 328
 329 **Fortran:**
 330
 331 .. function:: call cpfint(compo, nm_var, t, info)
 332
 333    :param compo: component address
 334    :type compo: long
 335    :param nm_var: port name
 336    :type nm_var: string
 337    :param t: time
 338    :type t: float
 339    :param info: error code
 340    :type info: int, return
 341
 342 **C:**
 343
 344 .. function:: int info = cp_effi(long *compo, char *nm_var, int i)
 345
 346    Erase all values of port nm_var after iteration i
 347
 348 **Fortran:**
 349
 350 .. function:: call cpfini(compo, nm_var, i, info)
 351
 352    :param compo: component address
 353    :type compo: long
 354    :param nm_var: port name
 355    :type nm_var: string
 356    :param i: iteration number
 357    :type i: int
 358    :param info: error code
 359    :type info: int, return
 360
 361 **C:**
 362
 363 .. function:: int info = cp_efft(long *compo, char *nm_var, float t)
 364
 365    Erase all values of port nm_var after time t
 366
 367 **Fortran:**
 368
 369 .. function:: call cpfint(compo, nm_var, t, info)
 370
 371    :param compo: component address
 372    :type compo: long
 373    :param nm_var: port name
 374    :type nm_var: string
 375    :param t: time
 376    :type t: float
 377    :param info: error code
 378    :type info: int, return
 379
 380 Examples
 381 ===========
 382 Fortran example
 383 -------------------
 384 If you want to export a single precision real array and import an integer array in iteration mode,
 385 you could write a subroutine as follows. Connection and disconnection must be done only once.
 386
 387 .. code-block:: fortran
 388
 389           subroutine coupling(compo)
 390           include 'calcium.hf'
 391           integer*8 compo
 392           real*4 t,af(10)
 393           integer i, info, n, ai(10), nval
 394           character*64 name
 395    C connect to YACS
 396           call cpcd(compo,name,info)
 397           n=10
 398           af(1)=2.5
 399    C export 10 real values at iteration 1 on port outa
 400           call cpere(compo,CP_ITERATION,t,i,'outa',n,af,info)
 401    C import 10 integer values at iteration 1 on port ina
 402           call cplen(compo,CP_ITERATION,ti,tf,i,'ina',n,nval,ai,info)
 403           write(6,*)ai(1)
 404    C disconnect
 405           call cpfin(compo,CP_CONT,info)
 406           end
 407
 408 C example
 409 -------------------
 410 If you want to export a double precision real array and import an integer array in time mode,
 411 you could write a function as follows. Connection and disconnection must be done only once.
 412
 413 .. code-block:: c
 414
 415
 416    void coupling(void* compo)
 417    {
 418      int info, i, n;
 419      char[64] name;
 420      double af[10], td,tf;
 421      int ai[10];
 422      // connect to YACS
 423      info = cp_cd(compo,name);
 424      af[0]=10.99;
 425      n=10;
 426      td=0.;
 427      // export 10 double values at time 0. on port outa
 428      info = cp_edb(compo,CP_TEMPS,td,i,"outa",n,af);
 429      tf=1.;
 430      // import 10 integer values at interval time (0.,1.) on port ina
 431      // (by default, it is imported at start time 0.)
 432      info = cp_len(compo,CP_TEMPS,&td,&tf,&i,"ina",n,&nval,ai);
 433      // disconnect
 434      info = cp_fin(compo,CP_CONT);
 435    }
 436
 437
 438
 439 .. _errcodes:
 440
 441 Error codes
 442 ==============
 443
 444 ========= ============ =================================
 445 Code      Value        Explanation
 446 ========= ============ =================================
 447 CPOK        0             No error
 448 CPERIU      1             Emitter unknown
 449 CPNMVR      2             Variable name unknown
 450 CPIOVR      3             Different input/output codes in code and supervisor
 451 CPTP        4             Variable type unknown
 452 CPTPVR      5             Different variable types in code and supervisor
 453 CPIT        6             Dependency mode unknown
 454 CPITVR      7             Different dependency modes in code and supervisor
 455 CPRENA      8             Unauthorized request
 456 CPDNTP      9             Unauthorized disconnection request type
 457 CPDNDI     10             Unauthorized disconnection directive
 458 CPNMCD     11             Code name unknown
 459 CPNMIN     12             Instance name unknown
 460 CPATTENTE  13             Waiting request
 461 CPBLOC     14             Blocking
 462 CPNTNUL    15             Zero value number
 463 CPLGVR     16             Insufficient variable length
 464 CPSTOP     17             Instance is going to stop
 465 CPATAL     18             Unexpected instance stop
 466 CPNOCP     19             Manual execution
 467 CPCTVR     20             Output variable not connected
 468 CPPASNULL  21             Number of steps to execute is nul
 469 CPMACHINE  22             Computer not declared
 470 CPGRNU     23             Environment variable COUPLAGE_GROUPE is not set
 471 CPGRIN     24             Instance group given by COUPLAGE_GROUPE is wrong
 472 CPERRFICH  26             Format error in input file
 473 CPNORERR   27             Request ignored because of switching to NORMAL mode
 474 CPRUNERR   28             Supervisor is in normal execution mode
 475 CPOPT      29             Unknown option
 476 CPVALOPT   30             Option value is wrong
 477 CPECREFF   31             Impossible to write because of an erasing request
 478 CPLIEN     32             Reading of a variable wrongly connected
 479 CPDECL     35             Error in declaration
 480 CPINEXEC   36             Error in instance launching
 481 CPCOM      37             Communication error
 482 CPMODE     39             Execution mode not defined
 483 CPINSTDEC  40             Disconnected instance
 484 ========= ============ =================================
 485
 486 .. _fortran64bits:
 487
 488 Some considerations about architecture (32, 64 bits) and programming language (C, Fortran)
 489 =============================================================================================
 490 Depending on the architecture and the language, types have varying sizes.
 491 For example, below we compare the size of C and Fortran types for two Linux distributions. One is Debian etch 32 bits
 492 and the other is Debian lenny 64 bits.
 493
 494 **Type size (in bytes) in C:**
 495
 496 ======================= ==================== ===================
 497 Architecture, compiler     32 bits, gcc 3.3   64 bits, gcc 4.3
 498 ======================= ==================== ===================
 499 short                         2                        2
 500 int                           4                        4
 501 long                          4                        8
 502 long long                     8                        8
 503 float                         4                        4
 504 double                        8                        8
 505 long double                  12                       16
 506 ======================= ==================== ===================
 507
 508 **Type size (in bytes) in Fortran:**
 509
 510 ======================= ================== ======================= =======================================================
 511 Architecture, compiler   32 bits, g77 3.3   64 bits, gfortran 4.3   64bits, gfortran -fdefault-integer-8 -fdefault-real-8
 512 ======================= ================== ======================= =======================================================
 513 integer                      4                    4                    8
 514 integer*8                    8                    8                    8
 515 real                         4                    4                    8
 516 double precision             8                    8                    8
 517 real*8                       8                    8                    8
 518 ======================= ================== ======================= =======================================================
 519
 520 With another architecture or compiler, sizes can be different.
 521
 522 Most of a time, Fortran INTEGER is mapped on C int type. So it is 4 bytes wide and equivalent to INTEGER\*4.
 523 This is the case for 32 bits architecture and 64 bits architecture with standard fortran options.
 524
 525 It is possible, with special options, to map Fortran INTEGER on C long type (-i8 with intel compiler or
 526 -fdefault-integer-8 with gnu fortran, for example). In this case, using the standard CALCIUM API can be cumbersome.
 527
 528 It is possible to build the SALOME KERNEL module with a special option (--with-cal_int=long) to match this kind of mapping.
 529
 530 By using the cp_een call (or CPEEN fortran call), it is possible to write a code that is independent from the mapping
 531 and that can always use fortran INTEGER type.
 532