]> SALOME platform Git repositories - modules/yacs.git/blob - doc/calciumapi.rst
Salome HOME
0022328: [CEA 942] Worrying traces at YACS launch and SALOME closure
[modules/yacs.git] / 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