This section is the CALCIUM coupling library reference for C and Fortran. For python, see module calcium.
Presentation is done in the following order:
All constants used with the coupling library are defined in an include file.
C:
#include "calcium.h"
Fortran:
INCLUDE 'calcium.hf'
These constants are:
C:
Initialize the connection with YACS.
Fortran:
| Parameters: |
|
|---|
C:
Close the connection with YACS.
Fortran:
| Parameters: |
|
|---|
Writing requests is the way for a component to export data through one of its output ports. nm_var is the port name.
Each request exports n values from the var_xxx array. Exported values are defined at time t if mode is CP_TEMPS or at iteration number i if mode is CP_ITERATION.
It is mandatory to export data at increasing times or iteration numbers. The export is done in an asynchronous way. Control is given back to the caller as soon as data have been sent.
There is generally one request for each data type to export. Each request can be used with one and only port type. For long type, two requests are available (cp_elg and cp_eln). One (cp_elg) is working with CALCIUM_integer port type and the second (cp_eln) is working with CALCIUM_long port type.
The available port types are :
C:
for single precision floating point values (C float type and CALCIUM_float port type)
for double precision floating point values (C double type and CALCIUM_double port type)
for complex values (C float type and CALCIUM_complex port type)
for integer values (C int type and CALCIUM_integer port type)
for integer values (C long type and CALCIUM_integer port type)
for integer values (C long type and CALCIUM_long port type)
for boolean values (C int type and CALCIUM_logical port type)
for string values (C char* type and CALCIUM_string port type)
Fortran:
can only be used on 64 bits architecture.
can only be used on 64 bits architecture.
| Parameters: |
|
|---|
Note
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 and INTEGER*8 for 64 bits architecture.
Warning
CPELG (or cp_elg) can produce wrong results (conversion problem) on 64 bits architecture if the KERNEL module is built with the default option (–with-cal_int=int)
See Some considerations about architecture (32, 64 bits) and programming language (C, Fortran) for more details.
Reading requests is the way for a component to import data through one of its input ports. nm_var is the port name. Import is only possible if the input port is connected to an output port.
A standard request imports data at a given time or iteration number. In case of time dependency, the effective time is calculated by YACS from the interval time (ti, tf) and the interpolation scheme that is given in the coupling file.
A sequential request imports data in a sequential way. Each request returns the next data with its associated time or iteration number.
There is generally one request for each data type to import. Each request can be used with one and only port type. For long type, two requests are available (cp_llg and cp_lln). One (cp_llg) is working with CALCIUM_integer port type and the second (cp_lln) is working with CALCIUM_long port type.
C:
Fortran:
can only be used on 64 bits architecture.
can only be used on 64 bits architecture.
| Parameters: |
|
|---|
Note
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 and INTEGER*8 for 64 bits architecture.
Warning
CPLLG (or cp_llg) can produce wrong results (conversion problem) on 64 bits architecture if the KERNEL module is built with the default option (–with-cal_int=int)
See Some considerations about architecture (32, 64 bits) and programming language (C, Fortran) for more details.
The functions cp_fini and cp_fint are used to request that all values of the specified variable defined for iteration number or time before a given one be erased.
The functions cp_effi and cp_efft are used to request that all values of the specified variable defined for iteration number or time after a given one be erased.
C:
Erase all values of port nm_var before iteration i
Fortran:
| Parameters: |
|
|---|
C:
Erase all values of port nm_var before time t
Fortran:
| Parameters: |
|
|---|
C:
Erase all values of port nm_var after iteration i
Fortran:
| Parameters: |
|
|---|
C:
Erase all values of port nm_var after time t
Fortran:
| Parameters: |
|
|---|
If you want to export a single precision real array and import an integer array in iteration mode, you could write a subroutine as follows. Connection and disconnection must be done only once.
subroutine coupling(compo)
include 'calcium.hf'
integer*8 compo
real*4 t,af(10)
integer i, info, n, ai(10), nval
character*64 name
C connect to YACS
call cpcd(compo,name,info)
n=10
af(1)=2.5
C export 10 real values at iteration 1 on port outa
call cpere(compo,CP_ITERATION,t,i,'outa',n,af,info)
C import 10 integer values at iteration 1 on port ina
call cplen(compo,CP_ITERATION,ti,tf,i,'ina',n,nval,ai,info)
write(6,*)ai(1)
C disconnect
call cpfin(compo,CP_CONT,info)
end
If you want to export a double precision real array and import an integer array in time mode, you could write a function as follows. Connection and disconnection must be done only once.
void coupling(void* compo)
{
int info, i, n;
char[64] name;
double af[10], td,tf;
int ai[10];
// connect to YACS
info = cp_cd(compo,name);
af[0]=10.99;
n=10;
td=0.;
// export 10 double values at time 0. on port outa
info = cp_edb(compo,CP_TEMPS,td,i,"outa",n,af);
tf=1.;
// import 10 integer values at interval time (0.,1.) on port ina
// (by default, it is imported at start time 0.)
info = cp_len(compo,CP_TEMPS,&td,&tf,&i,"ina",n,&nval,ai);
// disconnect
info = cp_fin(compo,CP_CONT);
}
| Code | Value | Explanation |
|---|---|---|
| CPOK | 0 | No error |
| CPERIU | 1 | Emitter unknown |
| CPNMVR | 2 | Variable name unknown |
| CPIOVR | 3 | Different input/output codes in code and supervisor |
| CPTP | 4 | Variable type unknown |
| CPTPVR | 5 | Different variable types in code and supervisor |
| CPIT | 6 | Dependency mode unknown |
| CPITVR | 7 | Different dependency modes in code and supervisor |
| CPRENA | 8 | Unauthorized request |
| CPDNTP | 9 | Unauthorized disconnection request type |
| CPDNDI | 10 | Unauthorized disconnection directive |
| CPNMCD | 11 | Code name unknown |
| CPNMIN | 12 | Instance name unknown |
| CPATTENTE | 13 | Waiting request |
| CPBLOC | 14 | Blocking |
| CPNTNUL | 15 | Zero value number |
| CPLGVR | 16 | Insufficient variable length |
| CPSTOP | 17 | Instance is going to stop |
| CPATAL | 18 | Unexpected instance stop |
| CPNOCP | 19 | Manual execution |
| CPCTVR | 20 | Output variable not connected |
| CPPASNULL | 21 | Number of steps to execute is nul |
| CPMACHINE | 22 | Computer not declared |
| CPGRNU | 23 | Environment variable COUPLAGE_GROUPE is not set |
| CPGRIN | 24 | Instance group given by COUPLAGE_GROUPE is wrong |
| CPERRFICH | 26 | Format error in input file |
| CPNORERR | 27 | Request ignored because of switching to NORMAL mode |
| CPRUNERR | 28 | Supervisor is in normal execution mode |
| CPOPT | 29 | Unknown option |
| CPVALOPT | 30 | Option value is wrong |
| CPECREFF | 31 | Impossible to write because of an erasing request |
| CPLIEN | 32 | Reading of a variable wrongly connected |
| CPDECL | 35 | Error in declaration |
| CPINEXEC | 36 | Error in instance launching |
| CPCOM | 37 | Communication error |
| CPMODE | 39 | Execution mode not defined |
| CPINSTDEC | 40 | Disconnected instance |
Depending on the architecture and the language, types have varying sizes. For example, below we compare the size of C and Fortran types for two Linux distributions. One is Debian etch 32 bits and the other is Debian lenny 64 bits.
Type size (in bytes) in C:
| Architecture, compiler | 32 bits, gcc 3.3 | 64 bits, gcc 4.3 |
|---|---|---|
| short | 2 | 2 |
| int | 4 | 4 |
| long | 4 | 8 |
| long long | 8 | 8 |
| float | 4 | 4 |
| double | 8 | 8 |
| long double | 12 | 16 |
Type size (in bytes) in Fortran:
| Architecture, compiler | 32 bits, g77 3.3 | 64 bits, gfortran 4.3 | 64bits, gfortran -fdefault-integer-8 -fdefault-real-8 |
|---|---|---|---|
| integer | 4 | 4 | 8 |
| integer*8 | 8 | 8 | 8 |
| real | 4 | 4 | 8 |
| double precision | 8 | 8 | 8 |
| real*8 | 8 | 8 | 8 |
With another architecture or compiler, sizes can be different.
Most of a time, Fortran INTEGER is mapped on C int type. So it is 4 bytes wide and equivalent to INTEGER*4. This is the case for 32 bits architecture and 64 bits architecture with standard fortran options.
It is possible, with special options, to map Fortran INTEGER on C long type (-i8 with intel compiler or -fdefault-integer-8 with gnu fortran, for example). In this case, using the standard CALCIUM API can be cumbersome.
It is possible to build the SALOME KERNEL module with a special option (–with-cal_int=long) to match this kind of mapping.
By using the cp_een call (or CPEEN fortran call), it is possible to write a code that is independent from the mapping and that can always use fortran INTEGER type.