[foam-extend-3.2.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_1.0_to_2.0
| blob | 1fc27a9b30086c6477ce3697039acdd9c5dea7aa |
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.
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.
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)
17 As an indication of the differences that might be realized in efficency,
18 consider the following comparison on an unstructured model consisting of:
20 1,639,058 nodes
21 7,079,211 elements 240530 tria3
22 3984 quad4
23 5927663 tetra4
24 653 pyramid5
25 906381 penta6
27 12 parts
29 The same model was represented in EnSight6 and EnSight Gold format.
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!
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!
64 Note: Structured data will not show much difference between the two API's,
65 but it was more efficient initially.
68 =========================================================
69 A note on philosophical differences between the two API's:
70 =========================================================
72 API 1.0 deals with:
73 -------------------
74 -> global coordinate array & corresponding
75 -> global node id array
76 -> global nodal variables
78 -> for each part:
79 -> local element connectivities (grouped by type) & corresponding
80 -> local element ids
81 -> local elemental variables
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.
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.
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.
100 All of this leads to a considerable amount of temporary memory and processing,
101 in order to get a model read into EnSight.
104 API 2.0 deals with:
105 -------------------
106 -> for each part:
107 -> part coordinates & corresponding
108 -> part node ids
109 -> part nodal variables
111 -> part element connectivities (grouped by type) & corresponding
112 -> part element ids
113 -> part elemental variables
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.
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!!
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 ------------------------------------------------
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.
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
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 -------------------------------------------------------------------------------
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 -----------------------------------------------------
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 ) )
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 ) )
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 ) )
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.
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.
223 The argument var_timeset needs to be added, and set
224 appropriately.
225 ---------------------------------------------------------
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 ) )
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 ------------------------------------------------------
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 ) )
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.
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 ------------------------------------------------------
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 ) )
283 USERD_get_solution_times USERD_get_sol_times
284 ( (
285 int timeset_number,
286 float *solution_times float *solution_times
287 ) )
289 USERD_set_time_step USERD_set_time_set_and_step
290 ( (
291 int timeset_number,
292 int time_step int time_step
293 ) )
296 ------------------------------------------------------
297 E) Changes related to global_extern.h
298 ======================================================
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).
306 =================================================================
307 Third, deleted and new routines. (Here is where the work lies)
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.
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 =================================================================
320 API 1.0 API 2.0
321 ------- -------
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
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
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
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
348 multiple timeset releated:
349 (Required) -> USERD_get_number_timesets
350 (Required) -> USERD_get_timeset_description
351 (Required) -> USERD_get_geom_timeset_number
353 border provided by the reader option:
354 (Required) -> USERD_get_border_availability
355 (Can be a dummy) -> USERD_get_border_elements_by_type
357 transient model allocation efficency:
358 (Can be a dummy) -> USERD_get_maxsize_info
360 Possible use with Server-of-Servers:
361 (Can be a dummy) -> USERD_set_server_number