doc/calciummod.rst

   1 .. _calciummod:
   2
   3 ==============================================
   4 :mod:`calcium` -- python interface
   5 ==============================================
   6
   7 .. module:: calcium
   8    :platform: Unix
   9    :synopsis: calcium interface (connect to YACS and exchange data between coupled components)
  10
  11 calcium python module provides all is needed to connect to YACS and exchange data between coupled components.
  12
  13 Presentation is done in the following order:
  14
  15 - constants
  16 - array types
  17 - functions to connect and disconnect
  18 - functions to export data
  19 - functions to import data
  20 - functions to erase data
  21 - example
  22
  23 Constants
  24 ================
  25 The constants defined in this module are:
  26
  27 .. data:: CP_TEMPS
  28
  29    This constant is used in cp_e* and cp_l* calls to indicate that data are associated to a time step.
  30
  31 .. data:: CP_ITERATION
  32
  33    This constant is used in cp_e* and cp_l* calls to indicate that data are associated to an iteration number.
  34
  35 .. data:: CP_SEQUENTIEL
  36
  37    This constant is used in cp_l* calls to indicate that the call requests the next data that has been produced.
  38
  39 .. data:: CP_CONT
  40
  41    This constant can be used in cp_fin to indicate that variables produced by the component are defined
  42    beyond the last time or iteration number and their value is equal to the last value produced.
  43
  44 .. data:: CP_ARRET
  45
  46    This constant can be used in cp_fin to indicate that variables produced by the component are not defined
  47    beyond the last time or iteration number.
  48
  49 and all the error codes as listed in :ref:`errcodes`.
  50
  51 Array types
  52 =============
  53 numpy arrays can be used to export or import data but if the numpy module is not installed
  54 calcium provides simple array types to replace them.
  55
  56 .. class:: calcium.intArray(nelem)
  57
  58        The constructor takes a single argument which is the number of elements of the array
  59
  60 .. class:: calcium.longArray(nelem)
  61
  62        The constructor takes a single argument which is the number of elements of the array
  63
  64 .. class:: calcium.floatArray(nelem)
  65
  66        The constructor takes a single argument which is the number of elements of the array
  67
  68 .. class:: calcium.doubleArray(nelem)
  69
  70        The constructor takes a single argument which is the number of elements of the array
  71
  72 .. class:: calcium.stringArray(nelem, eltsize)
  73
  74        The constructor takes two arguments: the number of elements of the array and the size
  75        of the elements (strings)
  76
  77 Functions to connect and disconnect
  78 ===============================================
  79
  80 .. function:: calcium.cp_cd(compo) -> info, name
  81
  82    Initialize the connection with YACS.
  83
  84    :param compo: component reference
  85    :type compo: SALOME component object
  86
  87    :param info: error code
  88    :type info: int
  89    :param name: instance name given by YACS
  90    :type name: string
  91
  92 .. function:: calcium.cp_fin(compo, directive) -> info
  93
  94    Close the connection with YACS.
  95
  96    :param compo: component reference
  97    :type compo: SALOME component object
  98    :param directive: indicate how variables will be handled after disconnection. If directive = CP_CONT,
  99      variables produced by this component are defined constant beyond the last time or iteration number. If
 100      directive = CP_ARRET, variables are not defined beyond the last step.
 101    :type directive: int
 102
 103    :param info: error code
 104    :type info: int
 105
 106 Functions to export data
 107 ============================
 108 .. function:: calcium.cp_ere(compo, dep, t, i, nm_var, n,var_real) -> info
 109 .. function:: calcium.cp_edb(compo, dep, t, i, nm_var, n,var_double) -> info
 110 .. function:: calcium.cp_ecp(compo, dep, t, i, nm_var, n,var_complex) -> info
 111 .. function:: calcium.cp_een(compo, dep, t, i, nm_var, n,var_integer) -> info
 112 .. function:: calcium.cp_elg(compo, dep, t, i, nm_var, n,var_long) -> info
 113 .. function:: calcium.cp_eln(compo, dep, t, i, nm_var, n,var_long) -> info
 114 .. function:: calcium.cp_elo(compo, dep, t, i, nm_var, n,var_boolean) -> info
 115 .. function:: calcium.cp_ech(compo, dep, t, i, nm_var, n,var_string) -> info
 116
 117    :param compo: component reference
 118    :type compo: SALOME component object
 119    :param dep: dependency mode (calcium.CP_TEMPS, calcium.CP_ITERATION)
 120    :type dep: int
 121    :param t: export time if mode=calcium.CP_TEMPS
 122    :type t: float
 123    :param i: export iteration number if mode=calcium.CP_ITERATION
 124    :type i: int
 125    :param nm_var: port name
 126    :type nm_var: string
 127    :param n: number of values to export
 128    :type n: int
 129    :param var_real: array containing float values to export
 130    :type var_real: float numpy array or :class:`calcium.floatArray`
 131    :param var_double: array containing double values to export
 132    :type var_double: double numpy array or :class:`calcium.doubleArray`
 133    :param var_complex: array containing complex values to export
 134    :type var_complex: complex numpy array or :class:`calcium.floatArray` (double size)
 135    :param var_integer: array containing integer values to export
 136    :type var_integer: integer numpy array or :class:`calcium.intArray`
 137    :param var_long: array containing long values to export
 138    :type var_long: long numpy array or :class:`calcium.longArray`
 139    :param var_boolean: array containing boolean values to export
 140    :type var_boolean: integer numpy array or :class:`calcium.intArray`
 141    :param var_string: array containing string values to export
 142    :type var_string: string numpy array or :class:`calcium.stringArray`
 143
 144    :param info: error code
 145    :type info: int
 146
 147 With numpy, the data types to use when creating the array, are the following:
 148
 149 ============ ====================
 150 Request       numpy data type
 151 ============ ====================
 152 cp_lre           'f'
 153 cp_ldb           'd'
 154 cp_lcp           'F'
 155 cp_len           'i'
 156 cp_llg           'l'
 157 cp_lln           'l'
 158 cp_llo           'i'
 159 cp_lch           'Sxx'
 160 ============ ====================
 161
 162 .. note::
 163
 164    For cp_lch xx is the size of the element string
 165
 166
 167 Functions to import data
 168 ===========================
 169 .. function:: calcium.cp_lre(compo, dep, ti, tf, i, nm_var, len, var_real) -> info, t, ii, n
 170 .. function:: calcium.cp_ldb(compo, dep, ti, tf, i, nm_var, len, var_double) -> info, t, ii, n
 171 .. function:: calcium.cp_lcp(compo, dep, ti, tf, i, nm_var, len, var_complex) -> info, t, ii, n
 172 .. function:: calcium.cp_len(compo, dep, ti, tf, i, nm_var, len, var_integer) -> info, t, ii, n
 173 .. function:: calcium.cp_llg(compo, dep, ti, tf, i, nm_var, len, var_long) -> info, t, ii, n
 174 .. function:: calcium.cp_lln(compo, dep, ti, tf, i, nm_var, len, var_long) -> info, t, ii, n
 175 .. function:: calcium.cp_llo(compo, dep, ti, tf, i, nm_var, len, var_boolean) -> info, t, ii, n
 176 .. function:: calcium.cp_lch(compo, dep, ti, tf, i, nm_var, len, var_string) -> info, t, ii, n
 177
 178    :param compo: component reference
 179    :type compo: SALOME component object
 180    :param dep: dependency mode (calcium.CP_TEMPS, calcium.CP_ITERATION or calcium.CP_SEQUENTIEL)
 181    :type dep: int
 182    :param ti: interval start time
 183    :type ti: float
 184    :param tf: interval end time
 185    :type tf: float
 186    :param i: iteration number
 187    :type i: int
 188    :param nm_var: port name
 189    :type nm_var: string
 190    :param len: number of values to import
 191    :type len: int
 192    :param var_real: array to store imported float values (must be large enough to contain imported values)
 193    :type var_real: float numpy array or :class:`calcium.floatArray`
 194    :param var_double: array to store imported double values
 195    :type var_double: double numpy array or :class:`calcium.doubleArray`
 196    :param var_complex: array to store imported complex values
 197    :type var_complex: complex numpy array or :class:`calcium.floatArray` (double size)
 198    :param var_integer: array to store imported integer values
 199    :type var_integer: integer numpy array or :class:`calcium.intArray`
 200    :param var_long: array to store imported long values
 201    :type var_long: long numpy array or :class:`calcium.longArray`
 202    :param var_boolean: array to store imported boolean values
 203    :type var_boolean: integer numpy array or :class:`calcium.intArray`
 204    :param var_string: array to store imported string values
 205    :type var_string: string numpy array or :class:`calcium.stringArray`
 206
 207    :param info: error code
 208    :type info: int
 209    :param t: effective time if mode=calcium.CP_TEMPS or associated time if mode=calcium.CP_SEQUENTIEL
 210    :type t: float
 211    :param ii: associated iteration number if mode=calcium.CP_SEQUENTIEL
 212    :type ii: int
 213    :param n: effective number of imported values (<= len)
 214    :type n: int
 215
 216 Functions to erase data
 217 ==========================
 218 The functions cp_fini and cp_fint are used to request that all values of the specified
 219 variable defined for iteration number or time before a given one be erased.
 220
 221 The functions cp_effi and cp_efft are used to request that all values of the specified
 222 variable defined for iteration number or time after a given one be erased.
 223
 224 .. function:: calcium.cp_fini(compo, nm_var, i) -> info
 225
 226    Erase all values of port nm_var before iteration i
 227
 228    :param compo: component reference
 229    :type compo: SALOME component object
 230    :param nm_var: port name
 231    :type nm_var: string
 232    :param i: iteration number
 233    :type i: int
 234    :param info: error code
 235    :type info: int, return
 236
 237 .. function:: calcium.cp_fint(compo, nm_var, t) -> info
 238
 239    Erase all values of port nm_var before time t
 240
 241    :param compo: component reference
 242    :type compo: SALOME component object
 243    :param nm_var: port name
 244    :type nm_var: string
 245    :param t: time
 246    :type t: float
 247    :param info: error code
 248    :type info: int, return
 249
 250 .. function:: calcium.cp_effi(compo, nm_var, i) -> info
 251
 252    Erase all values of port nm_var after iteration i
 253
 254    :param compo: component reference
 255    :type compo: SALOME component object
 256    :param nm_var: port name
 257    :type nm_var: string
 258    :param i: iteration number
 259    :type i: int
 260    :param info: error code
 261    :type info: int, return
 262
 263 .. function:: calcium.cp_efft(compo, nm_var, t) -> info
 264
 265    Erase all values of port nm_var after time t
 266
 267    :param compo: component reference
 268    :type compo: SALOME component object
 269    :param nm_var: port name
 270    :type nm_var: string
 271    :param t: time
 272    :type t: float
 273    :param info: error code
 274    :type info: int, return
 275
 276 Example
 277 ========
 278 If you want to export a double precision real array and import an integer array in time mode,
 279 you could write a function as follows. Connection and disconnection must be done only once.
 280
 281 .. code-block:: numpy
 282
 283    import calcium
 284    import numpy
 285
 286    def coupling(compo):
 287      # connect to YACS
 288      info, name = calcium.cp_cd(compo)
 289      # export 10 double values at time 0. on port outa
 290      af=numpy.zeros(10,'d')
 291      af[0]=4.3
 292      info = calcium.cp_edb(compo,calcium.CP_TEMPS,0.,0,"outa",10,af);
 293      tf=1.;
 294      # import 10 integer values at interval time (0.,1.) on port ina
 295      # (by default it is imported at the start time 0.)
 296      ai=numpy.zeros(10,'i')
 297      info,t,i,n = calcium.cp_len(compo,calcium.CP_TEMPS,0., 1.,0,"ina",10,ai);
 298      # disconnect
 299      info = calcium.cp_fin(compo,calcium.CP_CONT);
 300
 301
 302