applications/utilities/postProcessing/graphics/ensightFoamReader/README_1.0_to_2.0

   1 README_1.0_to_2.0
   2 =================
   3 This document exists to help those who already have a working user defined
   4 reader (using the 1.0 API) to change it into the 2.0 API format - if desired.
   5
   6 Note that you do not have to update your (1.0 API) user defined reader if it
   7 is already working fine for you.
   8
   9 You should consider it if:
  10   - efficieny gains are needed or
  11   - you need access to complex variables or
  12   - you need access to tensor variables or
  13   - you need multiple timeset capability or
  14   - you want to provide your own "border" elements (as opposed to EnSight's
  15                                                     computation of them)
  16
  17 As an indication of the differences that might be realized in efficency,
  18 consider the following comparison on an unstructured model consisting of:
  19
  20 1,639,058 nodes
  21 7,079,211 elements      240530 tria3
  22                           3984 quad4
  23                        5927663 tetra4
  24                            653 pyramid5
  25                         906381 penta6
  26
  27 12 parts
  28
  29 The same model was represented in EnSight6 and EnSight Gold format.
  30
  31
  32                     EnSight6 format into:           EnSight Gold format into:
  33             ------------------------------------    -------------------------
  34             EnSight7.1  |Ensight7.2  |Ensight 7.1  |EnSight7.2  |Ensight7.2
  35             internal    |internal    |userd reader |internal    |userd reader
  36             reader      |reader      |(API 1.0)    |reader      |(API 2.0)
  37                         |            |             |            |
  38             Time | Mem  |Time | Mem  |Time | Mem   |Time | Mem  |Time | Mem
  39             (sec)| (Mb) |(sec)| (Mb) |(sec)| (Mb)  |(sec)| (Mb) |(sec)| (Mb)
  40             ----------- |----------- |-----------  |----------- |-----------
  41 @ part       4.3   27.6 | 3.5   28.4 | 4.0   27.6  | 3.3    8.8 | 3.3    8.9
  42 loader                  |            |             |            |
  43                         |            |             |            |
  44 after       14.0  243.4 |12.8  244.3 |49.8  475.8  | 6.0  211.5 | 6.2  211.6
  45 loading all             |            |             |            |
  46 12 parts                |            |             |            |
  47 (non-visual)            |            |             |            |
  48                         |            |             |            |
  49 after       16.8  263.2 |16.0  264.2 |52.8  490.7  | 9.1  236.2 | 9.5  236.2
  50 activate of             |            |             |            |
  51 a vector.               |            |             |            |
  52                                            ^                          ^
  53                                           /|\                        /|\
  54                                            |                          |
  55                                            |                          |
  56                                            |                          |
  57                                                 Compare these two!
  58
  59
  60 Significant is the inefficiency of the 1.0 API, and the fact that the
  61 2.0 API has the same improved efficiency (both in speed and memory) as
  62 the gold internal reader!
  63
  64 Note: Structured data will not show much difference between the two API's,
  65 but it was more efficient initially.
  66
  67
  68 =========================================================
  69 A note on philosophical differences between the two API's:
  70 =========================================================
  71
  72 API 1.0 deals with:
  73 -------------------
  74  -> global coordinate array  & corresponding
  75     -> global node id array
  76     -> global nodal variables
  77
  78  -> for each part:
  79     -> local element connectivities (grouped by type) & corresponding
  80        -> local element ids
  81        -> local elemental variables
  82
  83
  84 The element connectivities, within parts, reference the global coordinate
  85 array. If node ids are provided, the element connectivities have to be in
  86 terms of the node ids. If node ids are not provided, the connectivities are in
  87 terms of the (one-based) index number of each node in the global coordinate
  88 array. Thus, node ids are more than labels - they are a part of the
  89 connectivity referencing scheme. Element ids are purely labels.
  90
  91 This API was originally setup to try to make the interface to other codes as
  92 straightforward as possible.  Efficiency was not the major consideration.
  93
  94 EnSight must do a fair amount of work to get data provided in the manner
  95 described above into the form that it uses internally. There is mapping that
  96 has to be setup and maintained between the global arrays and the local part
  97 arrays so that updating over time can be accomplished efficiently. There is
  98 hashing that is required in order to deal efficently with node ids.
  99
 100 All of this leads to a considerable amount of temporary memory and processing,
 101 in order to get a model read into EnSight.
 102
 103
 104 API 2.0 deals with:
 105 -------------------
 106  -> for each part:
 107     -> part coordinates  & corresponding
 108     -> part node ids
 109     -> part nodal variables
 110
 111     -> part element connectivities (grouped by type) & corresponding
 112        -> part element ids
 113        -> part elemental variables
 114
 115 API 2.0 requires that the coordinates and corresponding nodal variables be
 116 provided per part. This eliminates the global to local mapping with all its
 117 associated temporary memory and processing time. The connectivity of the
 118 elements in each part reference the node indicies of its own (one-based) part
 119 coordinate array.  The connectivity of the elements do not reference the nodes
 120 according to node ids.  Node ids (and element ids for that matter) are purely
 121 labels for screen display and for query operations within EnSight. This
 122 eliminates the need for node id hashing as a model is read.
 123
 124 The 2.0 API has been created for those needing more efficiency - both in terms
 125 of memory use and speed. The increased efficiency is possible because data is
 126 requested in a manner which more closely represents the way that EnSight
 127 stores and manipulates information internally. The new API requests size
 128 information and allocates the actual internal structures and arrays
 129 accordingly.  Pointers to these arrays are passed directly to you in the
 130 routines which gather data, thus eliminating a considerable amount of
 131 temporary memory (and allocation time) that is needed in the old
 132 API. Depending on what you must do to get your data into the form required,
 133 the memory savings and the speed improvement when loading models can be quite
 134 significant!!
 135
 136 Additionally, the ability to handle tensor and complex variables has been
 137 added to the new API, and support for multiple timesets is provided.
 138 ------------------------------------------------
 139
 140
 141 So, with that said, if you determine that you want to convert your existing
 142 reader to the new API format, The following may be helpful.
 143
 144 ====================
 145 First the Good News!  The following routines are identical in both API's!!
 146 ====================  ----------------------------------------------------
 147 USERD_bkup
 148 USERD_get_block_coords_by_component
 149 USERD_get_block_iblanking
 150 USERD_get_changing_geometry_status
 151 USERD_get_dataset_query_file_info
 152 USERD_get_element_label_status
 153 USERD_get_name_of_reader
 154 USERD_get_node_label_status
 155 USERD_get_number_of_files_in_dataset
 156 USERD_get_number_of_model_parts
 157 USERD_get_number_of_variables
 158 USERD_set_filenames
 159 USERD_stop_part_building
 160
 161
 162
 163 ========================
 164 Second, pretty Good News!    The following routines have minor changes,
 165 ========================     namely a slight name change and the addition
 166                              of arguments related to complex data, constant
 167 (Note, the name changes      type, or self contained parts vs global coords.
 168  are needed so both
 169  API's can exist together)   The arguments must be added, but depending on
 170                              your situation, many might simply be place
 171                              holders.
 172 -------------------------------------------------------------------------------
 173
 174    -----------------------------------------------------
 175 A) Changes related to imaginary flag for complex data
 176    =====================================================
 177    If you don't deal with complex variables, simply add
 178    this flag to your argument list and ignore its value.
 179    -----------------------------------------------------
 180
 181 API 1.0                                 API 2.0
 182 -------                                 -------
 183 USERD_get_constant_value                USERD_get_constant_val
 184 (                                       (
 185  int which var                           int which_var,
 186                                          int imag_data
 187 )                                       )
 188
 189 USERD_get_description_lines             USERD_get_descrip_lines
 190 (                                       (
 191  int which_type,                         int which_type,
 192  int which_var,                          int which_var,
 193                                          int imag_data,
 194  char line1[Z_BUFL],                     char line1[Z_BUFL],
 195  char line2[Z_BUFL]                      char line2[Z_BUFL]
 196 )                                       )
 197
 198 USERD_get_variable_value_at_specific    USERD_get_var_value_at_specific
 199 (                                       (
 200  int which_var,                          int which_var,
 201  int which_node_or_elem,                 int which_node_or_elem,
 202  int which_part,                         int which_part,
 203  int which_elem_type,                    int which_elem_type,
 204  int time_step,                          int time_step,
 205  float values[3]                         float values[3],
 206                                          int imag_data
 207 )                                       )
 208
 209
 210    ---------------------------------------------------------
 211 B) Changes related to complex data info, and constant type
 212    (and some of the multiple timeset support)
 213    =========================================================
 214    If you don't deal with complex variables, simply add the
 215    arguments for var_complex, var_ifilename, and var_freq
 216    and assign var_complex to be FALSE.
 217
 218    The argument var_contran needs to be added, and set
 219    appropriately if you have constant variables, to indicate
 220    if the constant variable is fixed for all time or varies
 221    over time.
 222
 223    The argument var_timeset needs to be added, and set
 224    appropriately.
 225    ---------------------------------------------------------
 226
 227 API 1.0                                 API 2.0
 228 -------                                 -------
 229 USERD_get_variable_info                 USERD_get_gold_variable_info
 230 (                                       (
 231  char **var_description,                 char **var_description,
 232  char **var_filename,                    char **var_filename,
 233  int *var_type,                          int *var_type,
 234  int *var_classify                       int *var_classify,
 235                                          int *var_complex,
 236                                          char **var_ifilename,
 237                                          float *var_freq,
 238                                          int *var_contran,
 239                                          int *var_timeset
 240 )                                       )
 241
 242
 243    ------------------------------------------------------
 244 C) Changes related to self contained part coordinates
 245    ======================================================
 246    The number_of_nodes argument needs to be added and
 247    set for each part. This one is critical for you to do.
 248    ------------------------------------------------------
 249
 250 API 1.0                                 API 2.0
 251 -------                                 -------
 252 USERD_get_part_build_info               USERD_get_gold_part_build_info
 253 (                                       (
 254  int *part_numbers,                      int *part_types,
 255  int *part_types,                        int *part_types,
 256  char *part_description[Z_BUFL],         char *part_description[Z_BUFL],
 257                                          int *number_of_nodes,
 258  int *number_of_elements[Z_MAXTYPE],     int *number_of_elements[Z_MAXTYPE],
 259  int *ijk_dimensions[3],                 int *ijk_dimensions[3],
 260  int *iblanking_options[6]               int *iblanking_options[6]
 261 )                                       )
 262
 263
 264    ------------------------------------------------------
 265 D) Changes related to multiple timeset support
 266    ======================================================
 267    The timeset_number argument needs to be added for the
 268    following three routines.
 269
 270    The multiple timeset support also includes the change
 271    in B) above for USERD_get_gold_variable_info and the
 272    last three new routines in the third section of this
 273    readme file.
 274    ------------------------------------------------------
 275
 276 API 1.0                                 API 2.0
 277 -------                                 -------
 278 USERD_get_number_of_time_steps          USERD_get_num_of_time_steps
 279 (                                       (
 280  void                                    int timeset_number
 281 )                                       )
 282
 283 USERD_get_solution_times                USERD_get_sol_times
 284 (                                       (
 285                                          int timeset_number,
 286  float *solution_times                   float *solution_times
 287 )                                       )
 288
 289 USERD_set_time_step                     USERD_set_time_set_and_step
 290 (                                       (
 291                                          int timeset_number,
 292  int time_step                           int time_step
 293 )                                       )
 294
 295
 296    ------------------------------------------------------
 297 E) Changes related to global_extern.h
 298    ======================================================
 299
 300    Be sure to include the updated global_extern.h file that comes
 301    with the EnSight 7.2 release (not the one from previous releases).
 302
 303
 304
 305
 306 =================================================================
 307 Third, deleted and new routines.  (Here is where the work lies)
 308
 309   Several old routines are gone. You will have to create the new
 310   routines that replace them. I think you will find in most cases
 311   that your old routines will form the basis of the new routines,
 312   and that it isn't too difficult to provide the information in
 313   the new way.
 314
 315   The detailed specifications for these new routines can be found
 316   in README_USERD_2.0 (or the headers in libuserd.c of the
 317   dummy_gold or ensight_gold readers).
 318 =================================================================
 319
 320 API 1.0                                     API 2.0
 321 -------                                     -------
 322
 323 These routines:                             replaced by the single routine:
 324 ---------------------------                 -------------------------------
 325 USERD_get_block_scalar_values               USERD_get_var_by_component
 326 USERD_get_block_vector_values_by_component
 327 USERD_get_scalar_values
 328 USERD_get_vector_values
 329
 330 These global coordinate routines:           replaced by part coord routines:
 331 ---------------------------------           --------------------------------
 332 USERD_get_global_coords                     USERD_get_part_coords
 333 USERD_get_global_node_ids                   USERD_get_part_node_ids
 334 USERD_get_number_of_global_nodes
 335
 336 These part connectivity routines:           replaced by part by type routines:
 337 ---------------------------------           ----------------------------------
 338 USERD_get_element_connectivities_for_part   USERD_get_part_elements_by_type
 339 USERD_get_element_ids_for_part              USERD_get_part_element_ids_by_type
 340
 341
 342                                             These are New Routines
 343                                             ----------------------
 344                       (Can be a dummy) ->   USERD_exit_routine
 345                       (Can be a dummy) ->   USERD_get_model_extents
 346                             (Required) ->   USERD_get_reader_version
 347
 348      multiple timeset releated:
 349                             (Required) ->   USERD_get_number_timesets
 350                             (Required) ->   USERD_get_timeset_description
 351                             (Required) ->   USERD_get_geom_timeset_number
 352
 353      border provided by the reader option:
 354                             (Required) ->   USERD_get_border_availability
 355                       (Can be a dummy) ->   USERD_get_border_elements_by_type
 356
 357      transient model allocation efficency:
 358                       (Can be a dummy) ->   USERD_get_maxsize_info
 359
 360      Possible use with Server-of-Servers:
 361                       (Can be a dummy) ->   USERD_set_server_number