[OpenFOAM-1.6.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.0
| blob | 93ac1f4fff0d59add85ae4224cf70e14e7ca87db |
1 README_USERD_2.0
2 ================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.0)
5 --------------------------------------
6 A user defined reader capability is included in EnSight which can allow
7 otherwise unsupported structured or unstructured data to be read. The user
8 defined reader capability utilizes dynamic shared libraries composed of
9 routines defined in this document but produced by you, the user, (or some
10 third party). This capability is currently available for dec, ibm, hp, sgi,
11 sun, linux, alpha linux, and NT servers.
13 Two versions of this API are available starting with EnSight Version 7.2. The
14 1.0 API (which was designed to be friendly to those producing it, but requires
15 more manipulation internally by EnSight) may be a little easier to
16 produce, but requires more memory and processing time. The 2.0 API is
17 considerably more efficient, and was designed more with that in mind. It
18 requires that all data be provided on a part basis.
20 If you already have a working 1.0 API reader and are happy with it - there is
21 probably no reason to modify it to the 2.0 API unless:
22 - you deal with large models and the memory use and load times are a
23 problem or
24 - you need tensor variable support or
25 - you need complex variable support or
26 - you need multiple timeset capability or
27 _ you want to provide your own "border" elements (as opposed to EnSight's
28 computation of them).
30 If you are producing a new reader, you should consider which will work best
31 for your needs.
34 API 1.0 (defined in README_USERD_1.0 document)
35 =======
36 The original user defined reader API (used with EnSight Versions 6 through
37 7.1) will continue to be supported. (Note that there was a change in the way
38 that the libraries were made at version 7.1 of EnSight, but underlying code
39 was kept the same.) Thus, any readers that work with EnSight 7.1, should still
40 function with EnSight 7.2.
43 API 2.0 (defined in this README_USERD_2.0 document)
44 =======
45 This new API has been defined to be more efficient and includes access to new
46 capabilities of EnSight 7.2. It lends itself closely to the EnSight "gold"
47 type format.
49 Some of its advantages are::
51 * Most intermediate temporary arrays have been eliminated, such that the user
52 defined routines write directly into internal part structures. This is a
53 considerable improvement in memory use, and improves speed as well since
54 far less memory need be allocated, initialized, etc.
56 * Parts are self contained. Coordinates, connectivity and all variables are
57 provided on a part basis. This eliminates the need for several global to
58 local coordinate mapping operations and the need for node id connectivity
59 hashing. This can greatly improve the speed at which models are loaded.
61 * Model extents can be provided directly, such that EnSight need not read
62 all the coordinate data at load time.
64 * Tensor variables are supported
66 * Complex variables are supported
68 * A routine is provided as EnSight exits, so cleanup operations such as
69 removing temporary files can be easily accomplished.
71 * Geometry and variables can be provided on different time lines (timesets).
73 * If your data format already provides boundary shell information, you can
74 use it instead of the "border" representation that EnSight would compute.
76 Further discussion on the philosophical differences between the two API's and
77 an efficiency comparison example can be found in the README_1.0_to_2.0 file.
78 This file also contains guidance on necessary changes to modify an existing
79 1.0 API to the new 2.0 API.
82 ****************************************************************************
83 Note: A default dummy_gold reader and an Ensight Gold example of this new 2.0
84 user defined reader API has been included with your EnSight release.
85 Also, the SILO reader included in the release utilizes the 2.0 API.
87 And while not identical, the API 1.0 readers might be useful to
88 examine as examples. Many of the routines are the same or similar.
89 ****************************************************************************
92 The process for producing a user defined reader is:
93 ---------------------------------------------------
94 1. Write code for all pertinent routines in the library (Unless someone else
95 has done this for you).
97 This is of course where the work is done by the user. The word
98 "pertinent" is used because depending on the nature of the data, some
99 of the routines in the library may be dummy routines.
101 The source code for a dummy_gold library and for various other
102 working or sample libraries is copied from the installation CD during
103 installation. These will be located in directories under:
105 $CEI_HOME/ensight76/user_defined_src/readers
107 examples:
108 --------
109 Basic dummy_gold routines provide skeleton for a new reader
110 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
112 Sample library which reads unstructured binary EnSight Gold data
113 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
115 You may find it useful to place your library source in this area as
116 well, but are not limited to this location.
118 * ===> The descriptions of each library routine and the order that the
119 routines are called, which is provided in this file, along with
120 the example libraries, should make it possible for you to produce
121 code for your own data reader.
124 2. Produce the dynamic shared library.
126 This is a compiling and loading process which varies according to
127 the type of machine you are on. In the user-defined-reader source
128 tree we have tried to isolate the machine dependent parts of the
129 build process using a set of files in the 'config' directory. In this
130 directory there is a configuration file for each platform on which
131 EnSight is supported. Before you can compile the installed readers
132 you should run the script called 'init' in the config directory.
134 i.e. (for UNIX)
135 cd config
136 ./init sgi_6.5_n64
137 cd ..
138 make
140 If you are compiling for Windows NT, there are two options. If you
141 have the Cygwin GNU utilities installed, you can use GNU make as for
142 Unix. Otherwise, there is a script called makeall.cmd which will
143 build all of the readers using nmake. The Makefiles in each reader
144 directory will work using either make or nmake.
146 i.e. (WIN32 Cygwin) (using nmake)
147 cd config cd config
148 sh init win32 cp win32 config
149 cd .. cd ..
150 mkdir lib
151 make makeall.cmd
153 If you have platform-specific portions of code in your reader, the
154 build system defines a set of flags which can be used within
155 #ifdef ... #endif regions in your source, as shown in the table
156 below.
158 Because the readers are now dynamically opened by EnSight, you may
159 have to include dependent libraries on your link-line to avoid having
160 unresolved symbols. If you are having problems with a reader, start
161 ensight as "ensight7 -readerdbg" and you will get feedback on any
162 problems encountered in loading a reader. If there are unresolved
163 symbols, you need to find the library which contains the missing
164 symbols and link it into your reader by adding it to the example
165 link commands below.
167 If you choose to use a different build environment for your reader,
168 you should take care to use compatible compilation flags to ensure
169 compatibilty with the EnSight executables, most notably on the SGI
170 and HP-UX 11.0 platforms, which should use the following flags:
172 sgi_6.2_o32: -mips2
173 sgi_6.2_n64: -mips4 -64
174 sgi_6.5_n32: -mips3
175 sgi_6.5_n64: -mips4 -64
176 hp_11.0_32: +DA2.0
177 hp_11.0_64: +DA2.0W
179 ______________________________________________________________________
180 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
181 | TYPE |------------------------------------------------------------|
182 | | LD COMMAND USED IN MAKEFILE |
183 ======================================================================
184 ______________________________________________________________________
185 | sgi | -DSGI | libuserd-X.so |
186 | |------------------------------------------------------------|
187 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
188 ----------------------------------------------------------------------
189 ______________________________________________________________________
190 | hp | -DHP | libuserd-X.sl |
191 | |------------------------------------------------------------|
192 | | ld -b -o libuserd-X.sl libuserd-X.o |
193 ----------------------------------------------------------------------
194 ______________________________________________________________________
195 | sun | -DSUN | libuserd-X.so |
196 | |------------------------------------------------------------|
197 | | ld -G -o libuserd-X.so libuserd-X.o |
198 ----------------------------------------------------------------------
199 ______________________________________________________________________
200 | dec | -DDEC | libuserd-X.so |
201 | |------------------------------------------------------------|
202 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
203 ----------------------------------------------------------------------
204 ______________________________________________________________________
205 | linux | -DLINUX | libuserd-X.so |
206 | |------------------------------------------------------------|
207 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
208 ----------------------------------------------------------------------
209 ______________________________________________________________________
210 | alpha | -DALINUX | libuserd-X.so |
211 | linux |------------------------------------------------------------|
212 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
213 ----------------------------------------------------------------------
214 ______________________________________________________________________
215 | ibm | -DIBM | libuserd-X.so |
216 | |------------------------------------------------------------|
217 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
218 ----------------------------------------------------------------------
220 Once you have created your library, you should place it in a directory
221 of your choice or in the standard reader location:
223 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
225 For example, if you created a reader for "mydata", you should create
226 the reader libuserd-mydata.so and place the file in your own reader
227 directory (see section 3 below) or in the standard location:
229 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
232 3. By default EnSight will load all readers found in the directory:
234 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
236 Files with names "libuserd-X.so" (where X is a name unique to the reader)
237 are assumed to be user-defined readers.
239 There are two methods which can be used to supplement the default
240 behavior.
242 (1) A feature which is useful for site-level or user-level configuration
243 is the optional environment variable $ENSIGHT7_READER. This
244 variable directs EnSight to load all readers in the specified reader
245 directory (you should probably specify a full path) before loading
246 the built-in readers. If the same reader exists in both directories
247 (as determined by the name returned by USERD_get_name_of_reader(),
248 NOT by the filename), the locally configured reader will take
249 precedence.
251 (2) A useful feature for end-users is the use of the libuserd-devel
252 reader. EnSight will search for a reader named libuserd-devel.so
253 (.sl for HP or .dll for NT). This reader can exist anywhere in the
254 library path (see below) of the user. This is useful for an
255 individual actively developing a reader because the existence of a
256 libuserd-devel library will take precedence over any other library
257 which returns the same name from USERD_get_name_of_reader().
259 As an example, a site may install commonly used readers in a common
260 location, and users can set the ENSIGHT7_READER variable to access them:
262 setenv ENSIGHT7_READER /usr/local/lib/e7readers
264 A user working on a new reader may compile the reader and place it in
265 a directory specified by the library path:
267 cp libuserd-myreader.so ~/lib/libuserd-devel.so
268 setenv <librarypath> ~/lib:$<librarypath>
270 The user is responsible for correctly configuring the library path
271 variable in order to make use of the libuserd-devel feature. The
272 library environment variables used are:
274 Machine type Environment variable to set
275 ------------ ---------------------------
276 sgi LD_LIBRARY_PATH
277 dec LD_LIBRARY_PATH
278 sun LD_LIBRARY_PATH
279 linux LD_LIBRARY_PATH
280 alpha linux LD_LIBRARY_PATH
281 hp SHLIB_PATH
282 ibm LIBPATH
284 As always, EnSight support is available if you need it.
288 -------------------------------
289 Quick Index of Library Routines
290 -------------------------------
292 Generally Needed for UNSTRUCTURED data
293 --------------------------------------
294 USERD_get_part_coords part's node coordinates
295 USERD_get_part_node_ids part's node ids
296 USERD_get_part_elements_by_type part's element connectivites
297 USERD_get_part_element_ids_by_type part's element ids
300 Generally Needed for BLOCK data
301 --------------------------------------
302 USERD_get_block_coords_by_component block coordinates
303 USERD_get_block_iblanking block iblanking values
306 Generally needed for either or both kinds of data
307 -------------------------------------------------
308 USERD_get_name_of_reader name of reader for GUI
309 USERD_get_reader_version provide reader version number
310 USERD_get_reader_descrip provide GUI more description(optional)
312 USERD_set_filenames filenames entered in GUI
313 USERD_set_server_number server which of how many
315 USERD_get_number_of_timesets number of timesets
316 USERD_get_timeset_description description of timeset
317 USERD_get_geom_timeset_number timeset # to use for geom
319 USERD_get_num_of_time_steps number of time steps
320 USERD_get_sol_times solution time values
321 USERD_set_time_set_and_step current timeset and time step
324 USERD_get_changing_geometry_status changing geometry?
325 USERD_get_node_label_status node labels?
326 USERD_get_element_label_status element labels?
327 USERD_get_model_extents provide model bounding extents
328 USERD_get_number_of_files_in_dataset number of files in model
329 USERD_get_dataset_query_file_info info about each model file
330 USERD_get_descrip_lines file associated description lines
331 USERD_get_number_of_model_parts number of model parts
332 USERD_get_part_build_info part/block type/descrip etc.
333 USERD_get_maxsize_info part/block allocation maximums
335 USERD_get_border_availability part border provided?
336 USERD_get_border_elements_by_type part border conn and parent info
338 USERD_get_number_of_variables number of variables
339 USERD_get_gold_variable_info variable type/descrip etc.
340 USERD_get_var_by_component part or block variable values
341 USERD_get_constant_val constant variable's value
342 USERD_get_var_value_at_specific node's or element's variable
343 value over time
344 USERD_stop_part_building cleanup after part build routine
346 USERD_bkup archive routine
348 USERD_exit_routine cleanup upon exit routine
351 -------------------------
352 Order Routines are called
353 -------------------------
355 The various main operations are given basically in the order they will
356 be performed. Within each operation, the order the routines will be
357 called is given.
359 1. Setting name in the gui, and specifying one or two input fields
361 USERD_get_name_of_reader
362 USERD_get_reader_descrip (optional)
364 2. Getting the reader version (also distinguishes between API's)
366 USERD_get_reader_version
368 3. Setting filenames and getting timeset and time info
370 USERD_set_server_number
371 USERD_set_filenames
372 USERD_get_number_of_timesets
373 USERD_get_geom_timeset_number
375 for each timeset:
376 USERD_get_timeset_description
377 USERD_get_num_of_time_steps
378 USERD_get_sol_times
380 USERD_set_time_set_and_step
382 4. Gathering info for part builder
384 USERD_set_time_set_and_step
385 USERD_get_changing_geometry_status
386 USERD_get_node_label_status
387 USERD_get_element_label_status
388 USERD_get_number_of_files_in_dataset
389 USERD_get_dataset_query_file_info
390 USERD_get_descrip_lines (for geometry)
391 USERD_get_number_of_model_parts
392 USERD_get_gold_part_build_info
393 USERD_get_maxsize_info
394 USERD_get_model_extents OR (for model extents)
395 USERD_get_part_coords AND/OR
396 USERD_get_block_coords_by_component
398 5. Gathering Variable info
400 USERD_get_number_of_variables
401 USERD_get_gold_variable_info
403 6. Part building (per part created)
405 USERD_set_time_set_and_step
406 USERD_get_part_element_ids_by_type
407 USERD_get_part_elements_by_type
408 USERD_get_part_coords
409 USERD_get_part_node_ids
410 USERD_get_block_iblanking
411 USERD_get_block_coords_by_component
413 USERD_get_border_availability (If border representation
414 USERD_get_border_elements_by_type is selected)
416 USERD_stop_part_building (only once when part builder
417 dialog is closed)
419 7. Loading Variables
421 constants:
422 ---------
423 USERD_set_time_set_and_step
424 USERD_get_constant_val
426 scalars/vectors/tensors:
427 ------------------------
428 USERD_get_descrip_lines
429 USERD_set_time_set_and_step
430 USERD_get_var_by_component
432 8. Changing geometry
434 changing coords only (per part):
435 --------------------
436 USERD_set_time_set_and_step
437 USERD_get_descrip_lines
438 USERD_get_part_coords
439 USERD_get_block_coords_by_component
441 changing connectivity (per part):
442 ---------------------
443 USERD_set_time_set_and_step
444 USERD_get_descrip_lines
445 USERD_get_number_of_model_parts
446 USERD_get_gold_part_build_info
447 USERD_get_model_extents OR
448 USERD_get_part_coords AND/OR
449 USERD_get_block_coords_by_component
450 USERD_get_part_element_ids_by_type
451 USERD_get_part_elements_by_type
452 USERD_get_part_coords
453 USERD_get_part_node_ids
454 USERD_get_block_iblanking
455 USERD_get_block_coords_by_component
457 USERD_get_border_availability (If border representation
458 USERD_get_border_elements_by_type is selected)
461 9. Node or Element queries over time
463 USERD_get_var_value_at_specific
466 -----------------------
467 Detailed Specifications
468 -----------------------
470 Include files:
471 --------------
472 The following header file is required in any file containing these library
473 routines.
475 #include "global_extern.h"
478 Basis of arrays:
479 ---------------
480 Unless explicitly stated otherwise, all arrays are zero based - in true C
481 fashion.
484 Global variables:
485 ----------------
486 You will generally need to have a few global variables which are shared by
487 the various library routines. The detailed specifications below have assumed
488 the following are available. (Their names describe their purpose, and they
489 will be used in helping describe the details of the routines below).
491 static int Numparts_available = 0;
492 static int Num_unstructured_parts = 0;
493 static int Num_structured_blocks = 0;
495 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
497 static int Num_timesets = 1;
498 static int Current_timeset = 1;
499 static int Geom_timeset_number = 1;
501 static int Num_time_steps[Z_MAXSETS] = 1;
502 static int Current_time_step = 0;
503 static int Num_variables = 0;
504 static int Num_dataset_files = 0;
506 static int Server_Number = 1; Which server of
507 static int Tot_Servers = 1; the total number of servers
511 _________________________________________
512 -----------------------------------------
513 Library Routines (in alphabetical order):
514 _________________________________________
515 -----------------------------------------
517 --------------------------------------------------------------------
518 USERD_bkup
520 Description:
521 -----------
522 This routine is called during the EnSight archive process. You can
523 use it to save or restore info relating to your user defined reader.
525 Specification:
526 -------------
527 int USERD_bkup(FILE *archive_file,
528 int backup_type)
530 Returns:
531 -------
532 Z_OK if successful
533 Z_ERR if not successful
535 Arguments:
536 ---------
537 (IN) archive_file = The archive file pointer
539 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
540 Z_REST_ARCHIVE for restoring archive
542 Notes:
543 -----
544 * Since EnSight's archive file is saved in binary form, you should
545 also do any writing to it or reading from it in binary.
547 * You should archive any variables, which will be needed for
548 future operations, that will not be read or computed again
549 before they will be needed. These are typically global
550 variables.
552 * Make sure that the number of bytes that you write on a save and
553 the number of bytes that you read on a restore are identical!!
555 * If any of the variables you save are allocated arrays, you must
556 do the allocations before restoring into them.
558 --------------------------------------------------------------------
559 USERD_exit_routine
561 Description:
562 -----------
563 This routine is called as EnSight is exiting. It can be used to clean
564 up anything needed - such as removing temporary files, etc. - or can simply
565 be a dummy.
567 Specification:
568 -------------
569 void USERD_exit_routine( void )
571 Arguments:
572 ---------
573 none
575 --------------------------------------------------------------------
576 USERD_get_block_coords_by_component
578 Description:
579 -----------
580 Get the coordinates of a given structured block, a component at a time.
582 Specification:
583 -------------
584 int USERD_get_block_coords_by_component(int block_number,
585 int which_component,
586 float *coord_array)
588 Returns:
589 -------
590 Z_OK if successful
591 Z_ERR if not successful
593 Arguments:
594 ---------
595 (IN) block_number = The block part number
596 (1-based index of part table, namely:
598 1 ... Numparts_available.
600 It is NOT the part_id that
601 is loaded in USERD_get_gold_part_build_info)
603 (IN) which_component = Z_COMPX if x component wanted
604 = Z_COMPY if y component wanted
605 = Z_COMPZ if z component wanted
607 (OUT) coord_array = 1D array containing x,y, or z
608 coordinate component of each node
610 (Array will have been allocated
611 i*j*k for the block long)
613 Notes:
614 -----
615 * Not called unless Num_structured_blocks is > 0
617 * Will be based on Current_time_step
621 --------------------------------------------------------------------
622 USERD_get_block_iblanking
624 Description:
625 -----------
626 Get the iblanking value at each node of a block (if the block is
627 iblanked).
629 Specification:
630 -------------
631 int USERD_get_block_iblanking(int block_number,
632 int *iblank_array)
634 Returns:
635 -------
636 Z_OK if successful
637 Z_ERR if not successful
639 Arguments:
640 ---------
641 (IN) block_number = The block part number
642 (1-based index of part table, namely:
644 1 ... Numparts_available.
646 It is NOT the part_id that
647 is loaded in USERD_get_gold_part_build_info)
649 (OUT) iblank_array = 1D array containing iblank value
650 for each node.
652 (Array will have been allocated
653 i*j*k for the block long)
655 possible values are: Z_EXT = exterior
656 Z_INT = interior
657 Z_BND = boundary
658 Z_INTBND = internal boundary
659 Z_SYM = symmetry plane
661 Notes:
662 -----
663 * Not called unless Num_structured_blocks is > 0 and you have
664 some iblanked blocks
666 * Will be based on Current_time_step
670 --------------------------------------------------------------------
671 USERD_get_border_availability
673 Description:
674 -----------
675 Finds out if border elements are provided by the reader for the
676 desired part, or will need to be computed internally by EnSight.
678 Specification:
679 -------------
680 int USERD_get_border_availability(int part_number,
681 int number_of_elements[Z_MAXTYPE])
683 Returns:
684 -------
685 Z_OK if border elements will be provided by the reader.
686 (number_of_elements array will be loaded and
687 USERD_get_border_elements_by_type will be called)
689 Z_ERR if border elements are not available - thus EnSight must compute.
690 (USERD_get_border_elements_by_type will not be called)
693 Arguments:
694 ---------
695 (IN) part_number = The part number
696 (1-based index of part table, namely:
698 1 ... Numparts_available.
700 It is NOT the part_id that
701 is loaded in USERD_get_gold_part_build_info)
703 (OUT) number_of_elements = 2D array containing number of
704 each type of border element in
705 the part.
706 ------------
707 Possible types are:
709 Z_POINT = point
710 Z_BAR02 = 2-noded bar
711 Z_BAR03 = 3-noded bar
712 Z_TRI03 = 3-noded triangle
713 Z_TRI06 = 6-noded triangle
714 Z_QUA04 = 4-noded quadrilateral
715 Z_QUA08 = 8-noded quadrilateral
717 Notes:
718 -----
719 * Only called if border representation is used.
721 * Will be based on Current_time_step
725 --------------------------------------------------------------------
726 USERD_get_border_elements_by_type
728 Description:
729 -----------
730 Provides border element connectivity and parent information.
732 Specification:
733 -------------
734 int USERD_get_border_elements_by_type(int part_number,
735 int element_type,
736 int **conn_array,
737 short *parent_element_type,
738 int *parent_element_num)
740 Returns:
741 -------
742 Z_OK if successful
743 Z_ERR if not successful
745 Arguments:
746 ---------
747 (IN) part_number = The part number
748 (1-based index of part table, namely:
750 1 ... Numparts_available.
752 It is NOT the part_id that
753 is loaded in USERD_get_gold_part_build_info)
755 (IN) element_type = One of the following (See global_extern.h)
756 Z_POINT node point element
757 Z_BAR02 2 node bar
758 Z_BAR03 3 node bar
759 Z_TRI03 3 node triangle
760 Z_TRI06 6 node triangle
761 Z_QUA04 4 node quad
762 Z_QUA08 8 node quad
764 (OUT) conn_array = 2D array containing connectivity
765 of each border element of the type.
767 (Array will have been allocated
768 num_of_elements of the type by
769 connectivity length of the type)
771 ex) If number_of_elements[Z_TRI03] = 25
772 number_of_elements[Z_QUA04] = 100
773 number_of_elements[Z_QUA08] = 30
774 as obtained in:
775 USERD_get_border_availability
777 Then the allocated dimensions available
778 for this routine will be:
779 conn_array[25][3] when called with Z_TRI03
781 conn_array[100][4] when called with Z_QUA04
783 conn_array[30][8] when called with Z_QUA08
785 (OUT) parent_element_type = 1D array containing element type of the
786 parent element (the one that the border
787 element is a face/edge of).
789 (Array will have been allocated
790 num_of_elements of the type long)
792 (OUT) parent_element_num = 1D array containing element number of the
793 parent element (the one that the border
794 element is a face/edge of).
796 (Array will have been allocated
797 num_of_elements of the type long)
800 Notes:
801 -----
802 * Not called unless USERD_get_border_availability returned Z_OK
804 * Will be based on Current_time_step
808 --------------------------------------------------------------------
809 USERD_get_changing_geometry_status
811 Description:
812 -----------
813 Gets the changing geometry status for the model
815 Specification:
816 -------------
817 int USERD_get_changing_geometry_status( void )
819 Returns:
820 -------
821 Z_STATIC if geometry does not change
822 Z_CHANGE_COORDS if changing coordinates only
823 Z_CHANGE_CONN if changing connectivity
825 Arguments:
826 ---------
827 none
829 Notes:
830 -----
831 * EnSight does not support changing number of parts. But the
832 coords and/or the connectivity of the parts can change. Note that
833 a part is allowed to be empty (number of nodes and elements equal
834 to zero).
837 --------------------------------------------------------------------
838 USERD_get_constant_val
840 Description:
841 -----------
842 Get the value of a constant at a time step
844 Specification:
845 -------------
846 float USERD_get_constant_value(int which_var,
847 int imag_data)
849 Returns:
850 -------
851 Value of the requested constant variable
853 Arguments:
854 ---------
855 (IN) which_var = The variable number
857 (IN) imag_data = TRUE if want imaginary data value.
858 FALSE if want real data value.
860 Notes:
861 -----
862 * Will be based on Current_time_step
866 --------------------------------------------------------------------
867 USERD_get_dataset_query_file_info
869 Description:
870 -----------
871 Get the information about files in the dataset. Used for the
872 dataset query option within EnSight.
874 Specification:
875 -------------
876 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
878 Returns:
879 -------
880 Z_OK if successful
881 Z_ERR if not successful
883 Arguments:
884 ---------
885 (OUT) qfiles = Structure containing information about each file
886 of the dataset. The Z_QFILES structure is defined
887 in the global_extern.h file
889 (The structure will have been allocated
890 Num_dataset_files long, with 10 description
891 lines per file).
893 qfiles[].name = The name of the file
894 (Z_MAXFILENP is the dimensioned length
895 of the name)
897 qfiles[].sizeb = The number of bytes in the file
898 (Typically obtained with a call to the
899 "stat" system routine) (Is a long)
901 qfiles[].timemod = The time the file was last modified
902 (Z_MAXTIMLEN is the dimensioned length
903 of this string)
904 (Typically obtained with a call to the
905 "stat" system routine)
907 qfiles[].num_d_lines = The number of description lines you
908 are providing from the file. Max = 10
910 qfiles[].f_desc[] = The description line(s) per file,
911 qfiles[].num_d_lines of them
912 (Z_MAXFILENP is the allocated length of
913 each line)
915 Notes:
916 -----
917 * If Num_dataset_files is 0, this routine will not be called.
918 (See USERD_get_number_of_files_in_dataset)
921 --------------------------------------------------------------------
922 USERD_get_descrip_lines
924 Description:
925 -----------
926 Get two description lines associated with geometry per time step,
927 or one description line associated with a variable per time step.
929 Specification:
930 -------------
931 int USERD_get_descrip_lines(int which_type,
932 int which_var,
933 int imag_data,
934 char line1[Z_BUFL],
935 char line2[Z_BUFL])
937 Returns:
938 -------
939 Z_OK if successful
940 Z_ERR if not successful
942 Arguments:
943 ---------
944 (IN) which_type = Z_GEOM for geometry (2 lines)
945 = Z_VARI for variable (1 line)
947 (IN) which_var = If it is a variable, which one.
948 Ignored if geometry type.
950 (IN) imag_data = TRUE if want imaginary data file.
951 FALSE if want real data file.
953 (OUT) line1 = The 1st geometry description line,
954 or the variable description line.
956 (OUT) line2 = The 2nd geometry description line
957 Not used if variable type.
959 Notes:
960 -----
961 * Will be based on Current_time_step
963 * These are the lines EnSight can echo to the screen in
964 annotation mode.
968 --------------------------------------------------------------------
969 USERD_get_element_label_status
971 Description:
972 -----------
973 Answers the question as to whether element labels will be provided.
975 Specification:
976 -------------
977 int USERD_get_element_label_status( void )
979 Returns:
980 -------
981 TRUE if element labels will be provided
982 FALSE if element labels will NOT be provided
984 Arguments:
985 ---------
986 none
988 Notes:
989 -----
990 * element lables are needed in order to do any element querying, or
991 element labeling on-screen within EnSight.
993 For unstructured parts, you can read them from your file if
994 available, or can assign them, etc. They need to be unique
995 per part, and are often unique per model.
997 USERD_get_part_element_ids_by_type is used to obtain the ids,
998 on a per part, per type basis, if TRUE status is returned here.
1000 For structured parts, EnSight will assign ids if you return a
1001 status of TRUE here. You cannot assign them youself!!
1004 --------------------------------------------------------------------
1005 USERD_get_geom_timeset_number -
1007 Description:
1008 -----------
1009 Gets the timeset number to be used for geometry
1011 Specification:
1012 -------------
1013 int USERD_get_geom_timeset_number( void )
1015 Returns:
1016 -------
1017 Geom_timeset_number = The timeset number that will be used for geometry.
1018 For example, if USERD_get_number_of timesets
1019 returns 2, the valid timeset numbers would be
1020 1 or 2.
1022 Arguments:
1023 ---------
1024 none
1026 Notes:
1027 -----
1028 * If your model is static, which you indicated by returning a zero
1029 in USERD_get_number_of_timesets, you can return a zero here as well.
1033 --------------------------------------------------------------------
1034 USERD_get_gold_part_build_info
1036 Description:
1037 -----------
1038 Gets the info needed for the part building process.
1040 Specification:
1041 -------------
1042 int USERD_get_gold_part_build_info(int *part_id,
1043 int *part_types,
1044 char *part_description[Z_BUFL],
1045 int *number_of_nodes,
1046 int *number_of_elements[Z_MAXTYPE],
1047 int *ijk_dimensions[3],
1048 int *iblanking_options[6])
1050 Returns:
1051 -------
1052 Z_OK if successful
1053 Z_ERR if not successful
1055 Arguments:
1056 ---------
1057 (OUT) part_id = Array containing the external part
1058 ids for each of the model parts.
1060 IMPORTANT:
1061 Parts numbers must be >= 1, because
1062 of the way they are used in the GUI
1064 *******************************************
1065 The ids provided here are the numbers by
1066 which the parts will be referred to in the
1067 GUI (if possible). They are basically
1068 labels as far as you are concerned.
1070 Note: The part numbers you pass to routines
1071 which receive a part_number or block_number
1072 or which_part as an argument are the 1-based
1073 table index of the parts!
1075 example: If Numparts_available = 3
1077 Table index part_id
1078 ----------- -------
1079 1 13
1080 2 57
1081 3 125
1083 ^ ^
1084 | |
1085 | These are placed in:
1086 | part_id[0] = 13
1087 | part_id[1] = 57
1088 | part_id[2] = 125
1089 | for GUI labeling purposes.
1090 |
1091 These implied table indices are the part_number,
1092 block_number, or which_part numbers that you would
1093 pass to routines like:
1095 USERD_get_part_coords(int part_number,...
1096 USERD_get_part_node_ids(int part_number,...
1097 USERD_get_part_elements_by_type(int part_number,...
1098 USERD_get_part_element_ids_by_type(int part_number,...
1099 USERD_get_block_coords_by_component(int block_number,...
1100 USERD_get_block_iblanking(int block_number,...
1101 USERD_get_block_ghost_flags(int block_number,...
1102 USERD_get_ghosts_in_block_flag(int block_number)
1103 USERD_get_border_availability( int part_number,...
1104 USERD_get_border_elements_by_type( int part_number,...
1105 USERD_get_var_by_component(int which_variable,
1106 int which_part,...
1107 USERD_get_var_value_at_specific(int which_var,
1108 int which_node_or_elem,
1109 int which_part,...
1110 ********************************************
1112 (Array will have been allocated
1113 Numparts_available long)
1115 (OUT) part_types = Array containing one of the
1116 following for each model part:
1118 Z_UNSTRUCTURED or
1119 Z_STRUCTURED or
1120 Z_IBLANKED
1122 (Array will have been allocated
1123 Numparts_available long)
1125 (OUT) part_description = Array containing a description
1126 for each of the model parts
1128 (Array will have been allocated
1129 Numparts_available by Z_BUFL
1130 long)
1132 (OUT) number_of_nodes = Number of unstructured nodes in the part
1134 (Array will have been allocated
1135 Numparts_available long)
1137 (OUT) number_of_elements = 2D array containing number of
1138 each type of element for each
1139 unstructured model part.
1140 ------------
1141 Possible types are:
1143 Z_POINT = point
1144 Z_BAR02 = 2-noded bar
1145 Z_BAR03 = 3-noded bar
1146 Z_TRI03 = 3-noded triangle
1147 Z_TRI06 = 6-noded triangle
1148 Z_QUA04 = 4-noded quadrilateral
1149 Z_QUA08 = 8-noded quadrilateral
1150 Z_TET04 = 4-noded tetrahedron
1151 Z_TET10 = 10-noded tetrahedron
1152 Z_PYR05 = 5-noded pyramid
1153 Z_PYR13 = 13-noded pyramid
1154 Z_PEN06 = 6-noded pentahedron
1155 Z_PEN15 = 15-noded pentahedron
1156 Z_HEX08 = 8-noded hexahedron
1157 Z_HEX20 = 20-noded hexahedron
1159 (Ignored unless Z_UNSTRUCTURED type)
1161 (Array will have been allocated
1162 Numparts_available by
1163 Z_MAXTYPE long)
1165 (OUT) ijk_dimensions = 2D array containing ijk dimensions
1166 for each structured model part.
1167 ----------
1168 (Ignored if Z_UNSTRUCTURED type)
1170 (Array will have been allocated
1171 Numparts_available by 3 long)
1173 ijk_dimensions[][0] = I dimension
1174 ijk_dimensions[][1] = J dimension
1175 ijk_dimensions[][2] = K dimension
1177 (OUT) iblanking_options = 2D array containing iblanking
1178 options possible for each
1179 structured model part.
1180 ----------
1181 (Ignored unless Z_IBLANKED type)
1183 (Array will have been allocated
1184 Numparts_available by 6 long)
1186 iblanking_options[][Z_EXT] = TRUE if external (outside)
1187 [][Z_INT] = TRUE if internal (inside)
1188 [][Z_BND] = TRUE if boundary
1189 [][Z_INTBND] = TRUE if internal boundary
1190 [][Z_SYM] = TRUE if symmetry surface
1193 Notes:
1194 -----
1195 * If you haven't built a table of pointers to the different parts,
1196 you might want to do so here as you gather the needed info.
1198 * Will be based on Current_time_step
1201 --------------------------------------------------------------------
1202 USERD_get_gold_variable_info
1204 Description:
1205 -----------
1206 Get the variable descriptions, types and filenames
1208 Specification:
1209 -------------
1210 int USERD_get_gold_variable_info(char **var_description,
1211 char **var_filename,
1212 int *var_type,
1213 int *var_classify,
1214 int *var_complex,
1215 char **var_ifilename,
1216 float *var_freq,
1217 int *var_contran,
1218 int *var_timeset)
1220 Returns:
1221 -------
1222 Z_OK if successful
1223 Z_ERR if not successful
1225 Arguments:
1226 ---------
1227 (OUT) var_description = Variable descriptions
1229 (Array will have been allocated
1230 Num_variables by Z_BUFL long)
1232 variable description restrictions:
1233 ----------------------------------
1234 1. Only first 19 characters used in EnSight.
1235 2. Leading and trailing whitespace will be removed by EnSight.
1236 3. Illegal characters will be replaced by underscores.
1237 4. Thay may not start with a numeric digit.
1238 4. No two variables may have the same description.
1241 (OUT) var_filename = Variable real filenames
1243 (Array will have been allocated
1244 Num_variables by Z_BUFL long)
1246 (OUT) var_type = Variable type
1248 (Array will have been allocated
1249 Num_variables long)
1251 types are: Z_CONSTANT
1252 Z_SCALAR
1253 Z_VECTOR
1254 Z_TENSOR
1255 Z_TENSOR9
1257 (OUT) var_classify = Variable classification
1259 (Array will have been allocated
1260 Num_variables long)
1262 types are: Z_PER_NODE
1263 Z_PER_ELEM
1265 (OUT) var_complex = TRUE if complex, FALSE otherwise
1267 (Array will have been allocated
1268 Num_variables long)
1270 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1272 (Array will have been allocated
1273 Num_variables by Z_BUFL long)
1275 (OUT) var_freq = complex frequency (if complex)
1277 (Array will have been allocated
1278 Num_variables long)
1280 (OUT) var_contran = TRUE if constant changes per time step
1281 FALSE if constant truly same at all time steps
1283 (Array will have been allocated
1284 Num_variables long)
1286 (OUT) var_timeset = Timeset the variable will use (1 based).
1287 (For static models, set it to 1)
1289 (Array will have been allocated
1290 Num_variables long)
1292 For example: If USERD_get_number_of_timesets
1293 returns 2, the valid
1294 timeset_number's would be 1 or 2
1297 Notes:
1298 -----
1299 * The implied variable numbers apply, but be aware that the
1300 arrays are zero based.
1301 So for variable 1, will need to provide var_description[0]
1302 var_filename[0]
1303 var_type[0]
1304 var_classify[0]
1305 var_complex[0]
1306 var_ifilename[0]
1307 var_freq[0]
1308 var_contran[0]
1309 var_timeset[0]
1312 for variable 2, will need to provide var_description[1]
1313 var_filename[1]
1314 var_type[1]
1315 var_classify[1]
1316 var_complex[1]
1317 var_ifilename[1]
1318 var_freq[1]
1319 var_contran[1]
1320 var_timeset[1]
1321 etc.
1324 --------------------------------------------------------------------
1325 USERD_get_maxsize_info
1327 Description:
1328 -----------
1329 Gets maximum part sizes for efficient memory allocation.
1331 Transient models (especially those that increase in size) can cause
1332 reallocations, at time step changes, to keep chewing up more and
1333 more memory. The way to avoid this is to know what the maximum
1334 size of such memory will be, and allocate for this maximum initially.
1336 Accordingly, if you choose to provide this information (it is optional),
1337 EnSight will take advantage of it.
1340 Specification:
1341 -------------
1342 int USERD_get_maxsize_info(int *max_number_of_nodes,
1343 int *max_number_of_elements[Z_MAXTYPE],
1344 int *max_ijk_dimensions[3])
1346 Returns:
1347 -------
1348 Z_OK if supplying maximum data
1349 Z_ERR if not supplying maximum data, or some error occurred
1350 while trying to obtain it.
1352 Arguments:
1353 ---------
1354 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1355 in the part (over all time).
1357 (Array will have been allocated
1358 Numparts_available long)
1360 (OUT) max_number_of_elements = 2D array containing maximum number of
1361 each type of element for each
1362 unstructured model part (over all time).
1363 ------------
1364 Possible types are:
1366 Z_POINT = point
1367 Z_BAR02 = 2-noded bar
1368 Z_BAR03 = 3-noded bar
1369 Z_TRI03 = 3-noded triangle
1370 Z_TRI06 = 6-noded triangle
1371 Z_QUA04 = 4-noded quadrilateral
1372 Z_QUA08 = 8-noded quadrilateral
1373 Z_TET04 = 4-noded tetrahedron
1374 Z_TET10 = 10-noded tetrahedron
1375 Z_PYR05 = 5-noded pyramid
1376 Z_PYR13 = 13-noded pyramid
1377 Z_PEN06 = 6-noded pentahedron
1378 Z_PEN15 = 15-noded pentahedron
1379 Z_HEX08 = 8-noded hexahedron
1380 Z_HEX20 = 20-noded hexahedron
1382 (Ignored unless Z_UNSTRUCTURED type)
1384 (Array will have been allocated
1385 Numparts_available by
1386 Z_MAXTYPE long)
1388 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1389 for each structured model part (over all time).
1390 ----------
1391 (Ignored if Z_UNSTRUCTURED type)
1393 (Array will have been allocated
1394 Numparts_available by 3 long)
1396 max_ijk_dimensions[][0] = maximum I dimension
1397 max_ijk_dimensions[][1] = maximum J dimension
1398 max_ijk_dimensions[][2] = maximum K dimension
1400 Notes:
1401 -----
1402 * You need to have first called USERD_get_number_of_model_parts and
1403 USERD_get_gold_part_build_info, so Numparts_available is known and
1404 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1405 or Z_IBLANKED) of each part.
1407 * This will NOT be based on Current_time_step - it is to be the maximum
1408 values over all time!!
1410 * This information is optional. If you return Z_ERR, Ensight will still
1411 process things fine, reallocating as needed, etc. However, for
1412 large transient models you will likely use considerably more memory
1413 and take more processing time for the memory reallocations. So, if it
1414 is possible to provide this information "up front", it is recommended
1415 to do so.
1420 --------------------------------------------------------------------
1421 USERD_get_model_extents
1423 Description:
1424 -----------
1425 Gets the model bounding box extents. If this routine supplys them
1426 EnSight will not have to spend time doing so. If this routine
1427 returns Z_ERR, EnSight will have to take the time to touch all the
1428 nodes and gather the extent info.
1430 Specification:
1431 -------------
1432 int USERD_get_model_extents(float extents[6])
1434 Returns:
1435 -------
1436 Z_OK if successful
1437 Z_ERR if not successful (whereupon EnSight will determine by reading
1438 all coords of all parts)
1440 Arguments:
1441 ---------
1442 (OUT) extents[0] = min x
1443 [1] = max x
1444 [2] = min y
1445 [3] = max y
1446 [4] = min z
1447 [5] = max z
1449 Notes:
1450 -----
1451 * This will be based on Current_time_step
1454 --------------------------------------------------------------------
1455 USERD_get_name_of_reader
1457 Description:
1458 -----------
1459 Gets the name of your user defined reader. The user interface will
1460 ask for this and include it in the available reader list.
1462 Specification:
1463 -------------
1464 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1465 int *two_fields)
1467 Returns:
1468 -------
1469 Z_OK if successful
1470 Z_ERR if not successful
1472 Arguments:
1473 ---------
1474 (OUT) reader_name = the name of the your reader or data format.
1475 (max length is Z_MAX_USERD_NAME, which is 20)
1477 (OUT) *two_fields = FALSE if only one data field required
1478 in the data dialog of EnSight.
1479 TRUE if two data fields required.
1481 Notes:
1482 -----
1483 * Always called. Please be sure to provide a name for your custom
1484 reader format.
1488 --------------------------------------------------------------------
1489 USERD_get_node_label_status
1491 Description:
1492 -----------
1493 Answers the question as to whether node labels will be provided.
1495 Specification:
1496 -------------
1497 int USERD_get_node_label_status( void )
1499 Returns:
1500 -------
1501 TRUE if node labels will be provided
1502 FALSE if node labels will NOT be provided
1504 Arguments:
1505 ---------
1506 none
1508 Notes:
1509 -----
1510 * Node ids are needed in order to do any node querying, or node
1511 labeling on-screen within EnSight.
1513 For unstructured parts, you can read them from your file if
1514 available, or can assign them, etc. They need to be unique
1515 per part, and are often unique per model. They must also be
1516 positive numbers greater than zero.
1518 USERD_get_part_node_ids is used to obtain the ids, if the
1519 status returned here is TRUE.
1521 (Unlike API 1.0, where the connectivity of elements had to be
1522 according to the node ids - API 2.0's element connectivities
1523 are not affected either way by the status here.)
1525 For structured parts, EnSight will assign ids if you return a
1526 status of TRUE here. You cannot assign them yourself!!
1530 --------------------------------------------------------------------
1531 USERD_get_num_of_time_steps
1533 Description:
1534 -----------
1535 Gets the number of time steps of data available for desired timeset.
1537 Specification:
1538 -------------
1539 int USERD_get_num_of_time_steps( int timeset_number )
1541 Returns:
1542 -------
1543 Number of time steps in timeset (>0 if okay, <=0 if problems).
1545 Arguments:
1546 ---------
1547 (IN) timeset number = the timeset number
1549 For example: If USERD_get_number_of_timesets
1550 returns 2, the valid
1551 timeset_number's would be 1 and 2
1553 Notes:
1554 -----
1555 * This should be >= 1 1 indicates a static model
1556 >1 indicates a transient model
1558 * Num_time_steps[timeset_number] would be set here
1562 --------------------------------------------------------------------
1563 USERD_get_number_of_files_in_dataset
1565 Description:
1566 -----------
1567 Get the total number of files in the dataset. Used for the
1568 dataset query option within EnSight.
1570 Specification:
1571 -------------
1572 int USERD_get_number_of_files_in_dataset( void )
1574 Returns:
1575 -------
1576 The total number of files in the dataset.
1578 Arguments:
1579 ---------
1580 none
1582 Notes:
1583 -----
1584 * You can be as complete as you want about this. If you don't
1585 care about the dataset query option, return a value of 0
1586 If you only want certain files, you can just include them. But,
1587 you will need to supply the info in USERD_get_dataset_query_file_info
1588 for each file you include here.
1590 * Num_dataset_files would be set here
1594 --------------------------------------------------------------------
1595 USERD_get_number_of_model_parts
1597 Description:
1598 -----------
1599 Gets the total number of unstructured and structured parts
1600 in the model, for which you can supply information.
1602 Specification:
1603 -------------
1604 int USERD_get_number_of_model_parts( void )
1606 Returns:
1607 -------
1608 Number of parts (>0 if okay, <=0 if problems).
1610 Arguments:
1611 ---------
1612 none
1614 Notes:
1615 -----
1616 * If going to have to read down through the parts in order to
1617 know how many, you may want to build a table of pointers to
1618 the various parts, so you can easily get to particular parts in
1619 later processes. If you can simply read the number of parts
1620 at the head of the file, then you would probably not build the
1621 table at this time.
1623 * This routine would set Numparts_available, which is equal to
1624 Num_unstructured_parts + Num_structured_blocks.
1628 --------------------------------------------------------------------
1629 USERD_get_number_of_timesets
1631 Description:
1632 -----------
1633 Gets the number of timesets used in the model.
1635 Specification:
1636 -------------
1637 int USERD_get_number_of_timesets( void )
1639 Returns:
1640 -------
1641 Number of timesets in the model
1643 Arguments:
1644 ---------
1645 none
1647 Notes:
1648 -----
1649 * Num_timesets would be set here
1651 * If you have a static model, both geometry and variables, you should
1652 return a value of zero.
1654 * If you have a transient model, then you should return one or more.
1656 For example:
1658 Geometry Variables No. of timesets
1659 --------- ------------------------------ ---------------
1660 static static 0
1661 static transient, all using same timeset 1
1663 transient transient, all using same timeset as geom 1
1665 static transient, using 3 different timesets 3
1667 transient transient, using 3 different timesets and
1668 none of them the same as the
1669 geometry timeset 4
1670 etc.
1672 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
1673 the timeset number to use
1674 for geometry in:
1675 USERD_get_geom_timeset_number
1677 Variables can use the same timeset as the geometry, or can use
1678 other timesets. More than one variable can use the same timeset.
1680 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
1681 variable 1 provided at these same five steps
1682 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
1684 This routine should return a value of 2, because only
1685 two different timesets are needed. Timeset 1 would be for the
1686 geometry and variable 1 (they both use it). Timeset 2 would
1687 be for variable 2, which needs its own in this case.
1693 --------------------------------------------------------------------
1694 USERD_get_number_of_variables
1696 Description:
1697 -----------
1698 Get the number of variables for which you will be providing info.
1700 Specification:
1701 -------------
1702 int USERD_get_number_of_variables( void )
1704 Returns:
1705 -------
1706 Number of variables (includes constant, scalar, vector and tensor types)
1707 (>=0 if okay, <0 if problem)
1709 Arguments:
1710 ---------
1711 none
1713 Notes:
1714 -----
1715 *****************************************************************
1716 * Variable numbers, by which references will be made, are implied
1717 here. If you say there are 3 variables, the variable numbers
1718 will be 1, 2, and 3.
1719 *****************************************************************
1721 * Num_variables would be set here
1725 --------------------------------------------------------------------
1726 USERD_get_part_coords
1728 Description:
1729 -----------
1730 Gets the coordinates for an unstructured part.
1732 Specification:
1733 -------------
1734 int USERD_get_part_coords(int part_number, float **coord_array)
1736 Returns:
1737 -------
1738 Z_OK if successful
1739 Z_ERR if not successful
1741 Arguments:
1742 ---------
1743 (IN) part_number = The part number
1744 (1-based index of part table, namely:
1746 1 ... Numparts_available.
1748 It is NOT the part_id that
1749 is loaded in USERD_get_gold_part_build_info)
1751 (OUT) coord_array = 2D float array which contains,
1752 x,y,z coordinates of each node
1753 in the part.
1755 (IMPORTANT: The second dimension of this aray is 1-based!!!)
1757 (Array will have been allocated
1758 3 by (number_of_nodes + 1) for the part
1759 long - see USERD_get_gold_part_build_info)
1762 ex) If number_of_nodes = 100
1763 as obtained in:
1764 USERD_get_gold_part_build_info
1766 Then the allocated dimensions of the
1767 pointer sent to this routine will be:
1768 coord_array[3][101]
1770 Ignore the coord_array[0][0]
1771 coord_array[1][0]
1772 coord_array[2][0] locations and start
1773 the node coordinates at:
1774 coord_array[0][1]
1775 coord_array[1][1]
1776 coord_array[2][1]
1778 coord_array[0][2]
1779 coord_array[1][2]
1780 coord_array[2][2]
1782 etc.
1784 Notes:
1785 -----
1786 * Not called unless Num_unstructured_parts is > 0
1788 * Will be based on Current_time_step
1791 --------------------------------------------------------------------
1792 USERD_get_part_element_ids_by_type
1794 Description:
1795 -----------
1796 Gets the ids for the elements of a particular type for an unstructured part.
1798 Specification:
1799 -------------
1800 int USERD_get_part_element_ids_by_type(int part_number,
1801 int element_type,
1802 int *elemid_array)
1804 Returns:
1805 -------
1806 Z_OK if successful
1807 Z_ERR if not successful
1809 Arguments:
1810 ---------
1811 (IN) part_number = The part number
1812 (1-based index of part table, namely:
1814 1 ... Numparts_available.
1816 It is NOT the part_id that
1817 is loaded in USERD_get_gold_part_build_info)
1819 (IN) element_type = One of the following (See global_extern.h)
1820 Z_POINT node point element
1821 Z_BAR02 2 node bar
1822 Z_BAR03 3 node bar
1823 Z_TRI03 3 node triangle
1824 Z_TRI06 6 node triangle
1825 Z_QUA04 4 node quad
1826 Z_QUA08 8 node quad
1827 Z_TET04 4 node tetrahedron
1828 Z_TET10 10 node tetrahedron
1829 Z_PYR05 5 node pyramid
1830 Z_PYR13 13 node pyramid
1831 Z_PEN06 6 node pentahedron
1832 Z_PEN15 15 node pentahedron
1833 Z_HEX08 8 node hexahedron
1834 Z_HEX20 20 node hexahedron
1836 (OUT) elemid_array = 1D array containing id of each
1837 element of the type.
1839 (Array will have been allocated
1840 number_of_elements of the type long)
1842 ex) If number_of_elements[Z_TRI03] = 25
1843 number_of_elements[Z_QUA04] = 100
1844 number_of_elements[Z_HEX08] = 30
1845 as obtained in:
1846 USERD_get_gold_part_build_info
1848 Then the allocated dimensions available
1849 for this routine will be:
1850 conn_array[25] when called with Z_TRI03
1852 conn_array[100] when called with Z_QUA04
1854 conn_array[30] when called with Z_HEX08
1856 Notes:
1857 -----
1858 * Not called unless Num_unstructured_parts is > 0 and element
1859 label status is TRUE
1861 * Will be based on Current_time_step
1865 --------------------------------------------------------------------
1866 USERD_get_part_elements_by_type
1868 Description:
1869 -----------
1870 Gets the connectivities for the elements of a particular type in an
1871 unstructured part
1873 Specification:
1874 -------------
1875 int USERD_get_part_elements_by_type(int part_number,
1876 int element_type,
1877 int **conn_array)
1879 Returns:
1880 -------
1881 Z_OK if successful
1882 Z_ERR if not successful
1884 Arguments:
1885 ---------
1886 (IN) part_number = The part number
1887 (1-based index of part table, namely:
1889 1 ... Numparts_available.
1891 It is NOT the part_id that
1892 is loaded in USERD_get_gold_part_build_info)
1894 (IN) element_type = One of the following (See global_extern.h)
1895 Z_POINT node point element
1896 Z_BAR02 2 node bar
1897 Z_BAR03 3 node bar
1898 Z_TRI03 3 node triangle
1899 Z_TRI06 6 node triangle
1900 Z_QUA04 4 node quad
1901 Z_QUA08 8 node quad
1902 Z_TET04 4 node tetrahedron
1903 Z_TET10 10 node tetrahedron
1904 Z_PYR05 5 node pyramid
1905 Z_PYR13 13 node pyramid
1906 Z_PEN06 6 node pentahedron
1907 Z_PEN15 15 node pentahedron
1908 Z_HEX08 8 node hexahedron
1909 Z_HEX20 20 node hexahedron
1911 (OUT) conn_array = 2D array containing connectivity
1912 of each element of the type.
1914 (Array will have been allocated
1915 num_of_elements of the type by
1916 connectivity length of the type)
1918 ex) If number_of_elements[Z_TRI03] = 25
1919 number_of_elements[Z_QUA04] = 100
1920 number_of_elements[Z_HEX08] = 30
1921 as obtained in:
1922 USERD_get_gold_part_build_info
1924 Then the allocated dimensions available
1925 for this routine will be:
1926 conn_array[25][3] when called with Z_TRI03
1928 conn_array[100][4] when called with Z_QUA04
1930 conn_array[30][8] when called with Z_HEX08
1932 Notes:
1933 -----
1934 * Not called unless Num_unstructured_parts is > 0
1936 * Will be based on Current_time_step
1939 --------------------------------------------------------------------
1940 USERD_get_part_node_ids
1942 Description:
1943 -----------
1944 Gets the node ids of an unstructured part.
1946 Specification:
1947 -------------
1948 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
1950 Returns:
1951 -------
1952 Z_OK if successful
1953 Z_ERR if not successful
1955 Arguments:
1956 ---------
1957 (IN) part_number = The part number
1958 (1-based index of part table, namely:
1960 1 ... Numparts_available.
1962 It is NOT the part_id that
1963 is loaded in USERD_get_gold_part_build_info)
1965 (OUT) nodeid_array = 1D array containing node ids of
1966 each node in the part.
1968 (IMPORTANT: This array is 1-based!!!)
1970 (Array will have been allocated
1971 (number_of_nodes + 1) for the part long
1972 see USERD_get_gold_part_build_info)
1974 ex) If number_of_nodes = 100
1975 as obtained in:
1976 USERD_get_gold_part_build_info
1978 Then the allocated dimensions of the
1979 pointer sent to this routine will be:
1980 nodeid_array[101]
1982 Ignore the nodeid_array[0] location and start
1983 the node ids at:
1984 nodeid_array[1]
1986 nodeid_array[2]
1988 etc.
1990 Notes:
1991 -----
1992 * Not called unless Num_unstructured_parts is > 0 and node label
1993 status is TRUE
1995 * Will be based on Current_time_step
1997 * The ids are purely labels, used when displaying or querying node ids.
1998 However, any node id < 0 will never be displayed
2001 --------------------------------------------------------------------
2002 USERD_get_reader_descrip
2004 Description:
2005 -----------
2006 Gets the description of the reader, so gui can give more info
2008 Specification:
2009 -------------
2010 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
2012 Returns:
2013 -------
2014 Z_OK if successful
2015 Z_ERR if not successful
2017 Arguments:
2018 ---------
2019 (OUT) descrip = the description of the reader (max length is MAXFILENP,
2020 which is 255)
2022 Notes:
2023 -----
2024 * OPTIONAL ROUTINE! You can have it or not.
2027 --------------------------------------------------------------------
2028 USERD_get_reader_version
2030 Description:
2031 -----------
2032 Gets the version number of the user defined reader
2034 Specification:
2035 -------------
2036 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
2038 Returns:
2039 -------
2040 Z_OK if successful
2041 Z_ERR if not successful (and will assume is version 1.0)
2043 Arguments:
2044 ---------
2045 (OUT) version_number = the version number of the reader
2046 (max length is Z_MAX_USERD_NAME, which
2047 is 20)
2049 Notes:
2050 -----
2051 * This needs to be "2.000" or greater. Otherwise EnSight will assume
2052 this reader is API 1.0 instead of 2.0
2056 --------------------------------------------------------------------
2057 USERD_get_sol_times
2059 Description:
2060 -----------
2061 Get the solution times associated with each time step for
2062 desired timeset.
2064 Specification:
2065 -------------
2066 int USERD_get_sol_times(int timeset_number,
2067 float *solution_times)
2069 Returns:
2070 -------
2071 Z_OK if successful
2072 Z_ERR if not successful
2074 Arguments:
2075 ---------
2076 (IN) timeset_number = the timeset number
2078 For example: If USERD_get_number_of_timesets
2079 returns 2, the valid
2080 timeset_number's would be 1 and 2
2082 (OUT) solution_times = 1D array of solution times per time step
2084 (Array will have been allocated
2085 Num_time_steps[timeset_number] long)
2087 Notes:
2088 -----
2089 * The solution times must be non-negative and increasing.
2093 --------------------------------------------------------------------
2094 USERD_get_timeset_description -
2096 Description:
2097 -----------
2098 Get the description to associate with the desired timeset.
2100 Specification:
2101 -------------
2102 int USERD_get_timeset_description(int timeset_number,
2103 char timeset_description[Z_BUFL])
2105 Returns:
2106 -------
2107 Z_OK if successful
2108 Z_ERR if not successful
2110 Arguments:
2111 ---------
2112 (IN) timeset_number = the timeset number
2114 For example: If USERD_get_number_of_timesets
2115 returns 2, the valid
2116 timeset_number's would be 1 and 2
2118 (OUT) timeset_description = timeset description string
2121 Notes:
2122 -----
2123 * A string of NULLs is valid for timeset_description
2128 --------------------------------------------------------------------
2129 USERD_get_var_by_component
2131 Description:
2132 -----------
2133 Gets the values of a variable component. Both unstructured and structured
2134 parts use this routine.
2136 if Z_PER_NODE:
2137 Get the component value at each node for a given variable in the part.
2139 or if Z_PER_ELEM:
2140 Get the component value at each element of a specific part and type
2141 for a given variable.
2143 Specification:
2144 -------------
2145 int USERD_get_var_by_component(int which_variable,
2146 int which_part,
2147 int var_type,
2148 int which_type,
2149 int imag_data,
2150 int component,
2151 float *var_array)
2153 Returns:
2154 -------
2155 Z_OK if successful
2156 Z_ERR if not successful
2158 or: Z_UNDEF, in which case you need not load any values into var_array
2161 Arguments:
2162 ---------
2163 (IN) which_variable = The variable number
2165 (IN) which_part Since EnSight Version 7.4
2166 -------------------------
2167 = The part number
2169 (1-based index of part table, namely:
2171 1 ... Numparts_available.
2173 It is NOT the part_id that
2174 is loaded in USERD_get_gold_part_build_info)
2176 Prior to EnSight Version 7.4
2177 ----------------------------
2178 = The part id This is the part_id label loaded
2179 in USERD_get_gold_part_build_info.
2180 It is NOT the part table index.
2182 (IN) var_type = Z_SCALAR
2183 Z_VECTOR
2184 Z_TENSOR (symmetric tensor)
2185 Z_TENSOR9 (asymmetric tensor)
2187 (IN) which_type
2189 if Z_PER_NODE: Not used
2191 if Z_PER_ELEM: = The element type
2192 Z_POINT node point element
2193 Z_BAR02 2 node bar
2194 Z_BAR03 3 node bar
2195 Z_TRI03 3 node triangle
2196 Z_TRI06 6 node triangle
2197 Z_QUA04 4 node quad
2198 Z_QUA08 8 node quad
2199 Z_TET04 4 node tetrahedron
2200 Z_TET10 10 node tetrahedron
2201 Z_PYR05 5 node pyramid
2202 Z_PYR13 13 node pyramid
2203 Z_PEN06 6 node pentahedron
2204 Z_PEN15 15 node pentahedron
2205 Z_HEX08 8 node hexahedron
2206 Z_HEX20 20 node hexahedron
2208 (IN) imag_data = TRUE if imag component
2209 FALSE if real component
2211 (IN) component = The component: (0 if Z_SCALAR)
2212 (0 - 2 if Z_VECTOR)
2213 (0 - 5 if Z_TENSOR)
2214 (0 - 8 if Z_TENSOR9)
2216 * 6 Symmetric Indicies, 0:5 *
2217 * ---------------------------- *
2218 * | 11 12 13 | | 0 3 4 | *
2219 * | | | | *
2220 * T = | 22 23 | = | 1 5 | *
2221 * | | | | *
2222 * | 33 | | 2 | *
2225 * 9 General Indicies, 0:8 *
2226 * ---------------------------- *
2227 * | 11 12 13 | | 0 3 4 | *
2228 * | | | | *
2229 * T = | 21 22 23 | = | 6 1 5 | *
2230 * | | | | *
2231 * | 31 32 33 | | 7 8 2 | *
2233 (OUT) var_array
2235 -----------------------------------------------------------------------
2236 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
2237 -----------------------------------------------------------------------
2239 if Z_PER_NODE: = 1D array containing variable component value
2240 for each node.
2242 (Array will have been allocated
2243 (number_of_nodes + 1) long)
2245 Info stored in this fashion:
2246 var_array[0] = not used
2247 var_array[1] = var component for node 1 of part
2248 var_array[2] = var_component for node 2 of part
2249 var_array[3] = var_component for node 3 of part
2250 etc.
2252 if Z_PER_ELEM: = 1D array containing variable component
2253 value for each element of a particular
2254 part and type.
2256 (Array will have been allocated
2257 (number_of_elements[which_part][which_type] + 1)
2258 long. See USERD_get_gold_part_build_info)
2260 Info stored in this fashion:
2261 var_array[1] = var component for elem 1 (of part and type)
2262 var_array[2] = var component for elem 2 (of part and type)
2263 var_array[3] = var component for elem 3 (of part and type)
2264 etc.
2266 Notes:
2267 -----
2268 * Not called unless Num_variables is > 0
2270 * The per_node or per_elem classification must be obtainable from the
2271 variable number (a var_classify array needs to be retained)
2273 * Will be based on Current_time_step
2275 * If the variable is not defined for this part, simply return with a
2276 value of Z_UNDEF. EnSight will treat the variable as undefined for
2277 this part.
2280 --------------------------------------------------------------------
2281 USERD_get_var_value_at_specific
2283 Description:
2284 -----------
2285 if Z_PER_NODE:
2286 Get the value of a particular variable at a particular node in a
2287 particular part at a particular time.
2289 or if Z_PER_ELEM:
2290 Get the value of a particular variable at a particular element of
2291 a particular type in a particular part at a particular time.
2294 Specification:
2295 -------------
2296 int USERD_get_var_value_at_specific(int which_var,
2297 int which_node_or_elem,
2298 int which_part,
2299 int which_elem_type,
2300 int time_step,
2301 float values[3],
2302 int imag_data)
2304 Returns:
2305 -------
2306 Z_OK if successful
2307 Z_ERR if not successful
2309 Arguments:
2310 ---------
2311 (IN) which_var = The variable number
2313 (IN) which_node_or_elem
2315 If Z_PER_NODE:
2316 = The node number. This is not the id, but is
2317 the index of the global node
2318 list (1 based), or the block's
2319 node list (1 based).
2321 Thus, coord_array[1]
2322 coord_array[2]
2323 coord_array[3]
2324 . |
2325 . |which_node_or_elem index
2326 . ----
2329 If Z_PER_ELEM:
2330 = The element number. This is not the id, but is
2331 the element number index
2332 of the number_of_element array
2333 (see USERD_get_gold_part_build_info),
2334 or the block's element list (1 based).
2336 Thus, for which_part:
2337 conn_array[which_elem_type][0]
2338 conn_array[which_elem_type][1]
2339 conn_array[which_elem_type][2]
2340 . |
2341 . which_node_or_elem index
2342 . ----
2345 (IN) which_part Since EnSight Version 7.4
2346 -------------------------
2347 = The part number
2349 (1-based index of part table, namely:
2351 1 ... Numparts_available.
2353 It is NOT the part_id that
2354 is loaded in USERD_get_gold_part_build_info)
2356 Prior to EnSight Version 7.4
2357 ----------------------------
2358 = The part id This is the part_id label loaded
2359 in USERD_get_gold_part_build_info.
2360 It is NOT the part table index.
2362 (IN) which_elem_type
2364 If Z_PER_NODE, or block part:
2365 = Not used
2367 If Z_PER_ELEM:
2368 = The element type. This is the element type index
2369 of the number_of_element array
2370 (see USERD_get_gold_part_build_info)
2372 (IN) time_step = The time step
2374 (IN) imag_data = TRUE if want imaginary value.
2375 FALSE if want real value.
2377 (OUT) values = scalar or vector component value(s)
2378 values[0] = scalar or vector[0]
2379 values[1] = vector[1]
2380 values[2] = vector[2]
2383 Notes:
2384 -----
2385 * This routine is used in node querys over time (or element querys over
2386 time for Z_PER_ELEM variables). If these operations are not critical
2387 to you, this can be a dummy routine.
2389 * The per_node or per_elem classification must be obtainable from the
2390 variable number (a var_classify array needs to be retained)
2392 * The time step given is for the proper variable timeset.
2395 --------------------------------------------------------------------
2396 USERD_set_filenames
2398 Description:
2399 -----------
2400 Receives the geometry and result filenames entered in the data
2401 dialog. The user written code will have to store and use these
2402 as needed. The user written code must manage its own files!!
2404 Specification:
2405 -------------
2406 int USERD_set_filenames(char filename_1[],
2407 char filename_2[],
2408 char the_path[],
2409 int swapbytes)
2411 Returns:
2412 -------
2413 Z_OK if successful
2414 Z_ERR if not successful
2416 Arguments:
2417 ---------
2418 (IN) filename_1 = the filename entered into the geometry
2419 field of the data dialog.
2421 (IN) filename_2 = the filename entered into the result
2422 field of the data dialog.
2423 (If the two_fields flag in USERD_get_name_of_reader
2424 is FALSE, this will be null string)
2426 (IN) the_path = the path info from the data dialog.
2427 Note: filename_1 and filename_2 have already
2428 had the path prepended to them. This
2429 is provided in case it is needed for
2430 filenames contained in one of the files
2432 (IN) swapbytes = TRUE if should swap bytes when reading data.
2433 = FALSE normally.
2435 Notes:
2436 -----
2437 * Since you must manage everything from the input that is entered in
2438 these data dialog fields, this is an important routine!
2440 * It may be that you will need to have an executive type file that contains
2441 info and other filenames within it, like EnSight6's case file.
2444 --------------------------------------------------------------------
2445 USERD_set_server_number
2447 Description:
2448 -----------
2449 Receives the server number of how many total servers.
2451 Specification:
2452 -------------
2453 int USERD_set_server_number(int cur_serv,
2454 int tot_servs)
2456 Returns:
2457 -------
2458 nothing
2460 Arguments:
2461 ---------
2462 (IN) cur_serv = the current server.
2464 (IN) tot_servs = the total number of servers.
2466 Notes:
2467 -----
2468 * Only useful if your user defined reader is being used with EnSight's
2469 Server-of-Server capability. And even then, it may or may not be
2470 something that you can take advantage of. If your data is already
2471 partitioned in some manner, such that you can access the proper
2472 portions using this information.
2474 For all non-SOS uses, this will simply be 1 of 1
2478 --------------------------------------------------------------------
2479 USERD_set_time_set_and_step
2481 Description:
2482 -----------
2483 Set the current time step in the desired timeset. All functions that
2484 need time, and that do not explicitly pass it in, will use the timeset
2485 and step set by this routine, if needed.
2487 Specification:
2488 -------------
2489 void USERD_set_time_set_and_step(int timeset_number,
2490 int time_step)
2492 Returns:
2493 -------
2494 nothing
2496 Arguments:
2497 ---------
2498 (IN) timeset_number = the timeset number (1 based).
2500 For example: If USERD_get_number_of_timesets
2501 returns 2, the valid timeset_number's
2502 would be 1 and 2.
2504 (IN) time_step = The current time step to set
2506 Notes:
2507 -----
2508 * Current_time_step and Current_timeset would be set here
2512 --------------------------------------------------------------------
2513 USERD_stop_part_building
2515 Description:
2516 -----------
2517 This routine called when the part building dialog is closed. It is
2518 provided in case you desire to release memory, etc. that was only needed
2519 during the part building process.
2521 Specification:
2522 -------------
2523 void USERD_stop_part_building( void )
2525 Returns:
2526 -------
2527 nothing
2529 Arguments:
2530 ---------
2531 none
2533 Notes:
2534 -----
2537 ---- end of doucment ----