[OpenFOAM-1.6.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.03
| blob | 14d40c799a11f9ed321b5f35cce01a62df232658 |
1 README_USERD_2.03
2 =================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.03)
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 You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0
14 for a discussion of the differences between API 1.0 and API 2.*.
17 ***>> API 2.03 additional capabilities (beyond API 2.01):
18 1. Routines to handle materials
19 2. Routines to handle nsided and nfaced elements
20 3. Modified routine to handle structured ranges
23 ****************************************************************************
24 Note: The dummy_gold reader, the Ensight Gold example reader, and the
25 SILO reader have been moved to this 2.03 API level.
26 ****************************************************************************
29 The process for producing a user defined reader is:
30 ---------------------------------------------------
31 1. Write code for all pertinent routines in the library (Unless someone else
32 has done this for you).
34 This is of course where the work is done by the user. The word
35 "pertinent" is used because depending on the nature of the data, some
36 of the routines in the library may be dummy routines.
38 The source code for a dummy_gold library and for various other
39 working or sample libraries is copied from the installation CD during
40 installation. These will be located in directories under:
42 $CEI_HOME/ensight76/user_defined_src/readers
44 examples:
45 --------
46 Basic dummy_gold routines provide skeleton for a new reader
47 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
49 Sample library which reads unstructured binary EnSight Gold data
50 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
52 You may find it useful to place your library source in this area as
53 well, but are not limited to this location.
55 * ===> The descriptions of each library routine and the order that the
56 routines are called, which is provided in this file, along with
57 the example libraries, should make it possible for you to produce
58 code for your own data reader.
61 2. Produce the dynamic shared library.
63 This is a compiling and loading process which varies according to
64 the type of machine you are on. In the user-defined-reader source
65 tree we have tried to isolate the machine dependent parts of the
66 build process using a set of files in the 'config' directory. In this
67 directory there is a configuration file for each platform on which
68 EnSight is supported. Before you can compile the installed readers
69 you should run the script called 'init' in the config directory.
71 i.e. (for UNIX)
72 cd config
73 ./init sgi_6.5_n64
74 cd ..
75 make
77 If you are compiling for Windows NT, there are two options. If you
78 have the Cygwin GNU utilities installed, you can use GNU make as for
79 Unix. Otherwise, there is a script called makeall.cmd which will
80 build all of the readers using nmake. The Makefiles in each reader
81 directory will work using either make or nmake.
83 i.e. (WIN32 Cygwin) (using nmake)
84 cd config cd config
85 sh init win32 cp win32 config
86 cd .. cd ..
87 mkdir lib
88 make makeall.cmd
90 If you have platform-specific portions of code in your reader, the
91 build system defines a set of flags which can be used within
92 #ifdef ... #endif regions in your source, as shown in the table
93 below.
95 Because the readers are now dynamically opened by EnSight, you may
96 have to include dependent libraries on your link-line to avoid having
97 unresolved symbols. If you are having problems with a reader, start
98 ensight as "ensight7 -readerdbg" and you will get feedback on any
99 problems encountered in loading a reader. If there are unresolved
100 symbols, you need to find the library which contains the missing
101 symbols and link it into your reader by adding it to the example
102 link commands below.
104 If you choose to use a different build environment for your reader,
105 you should take care to use compatible compilation flags to ensure
106 compatibilty with the EnSight executables, most notably on the SGI
107 and HP-UX 11.0 platforms, which should use the following flags:
109 sgi_6.2_o32: -mips2
110 sgi_6.2_n64: -mips4 -64
111 sgi_6.5_n32: -mips3
112 sgi_6.5_n64: -mips4 -64
113 hp_11.0_32: +DA2.0
114 hp_11.0_64: +DA2.0W
116 ______________________________________________________________________
117 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
118 | TYPE |------------------------------------------------------------|
119 | | LD COMMAND USED IN MAKEFILE |
120 ======================================================================
121 ______________________________________________________________________
122 | sgi | -DSGI | libuserd-X.so |
123 | |------------------------------------------------------------|
124 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
125 ----------------------------------------------------------------------
126 ______________________________________________________________________
127 | hp | -DHP | libuserd-X.sl |
128 | |------------------------------------------------------------|
129 | | ld -b -o libuserd-X.sl libuserd-X.o |
130 ----------------------------------------------------------------------
131 ______________________________________________________________________
132 | sun | -DSUN | libuserd-X.so |
133 | |------------------------------------------------------------|
134 | | ld -G -o libuserd-X.so libuserd-X.o |
135 ----------------------------------------------------------------------
136 ______________________________________________________________________
137 | dec | -DDEC | libuserd-X.so |
138 | |------------------------------------------------------------|
139 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
140 ----------------------------------------------------------------------
141 ______________________________________________________________________
142 | linux | -DLINUX | libuserd-X.so |
143 | |------------------------------------------------------------|
144 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
145 ----------------------------------------------------------------------
146 ______________________________________________________________________
147 | alpha | -DALINUX | libuserd-X.so |
148 | linux |------------------------------------------------------------|
149 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
150 ----------------------------------------------------------------------
151 ______________________________________________________________________
152 | ibm | -DIBM | libuserd-X.so |
153 | |------------------------------------------------------------|
154 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
155 ----------------------------------------------------------------------
157 Once you have created your library, you should place it in a directory
158 of your choice or in the standard reader location:
160 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
162 For example, if you created a reader for "mydata", you should create
163 the reader libuserd-mydata.so and place the file in your own reader
164 directory (see section 3 below) or in the standard location:
166 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
169 3. By default EnSight will load all readers found in the directory:
171 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
173 Files with names "libuserd-X.so" (where X is a name unique to the reader)
174 are assumed to be user-defined readers.
176 There are two methods which can be used to supplement the default
177 behavior.
179 (1) A feature which is useful for site-level or user-level configuration
180 is the optional environment variable $ENSIGHT7_READER. This
181 variable directs EnSight to load all readers in the specified reader
182 directory (you should probably specify a full path) before loading
183 the built-in readers. If the same reader exists in both directories
184 (as determined by the name returned by USERD_get_name_of_reader(),
185 NOT by the filename), the locally configured reader will take
186 precedence.
188 (2) A useful feature for end-users is the use of the libuserd-devel
189 reader. EnSight will search for a reader named libuserd-devel.so
190 (.sl for HP or .dll for NT). This reader can exist anywhere in the
191 library path (see below) of the user. This is useful for an
192 individual actively developing a reader because the existence of a
193 libuserd-devel library will take precedence over any other library
194 which returns the same name from USERD_get_name_of_reader().
196 As an example, a site may install commonly used readers in a common
197 location, and users can set the ENSIGHT7_READER variable to access them:
199 setenv ENSIGHT7_READER /usr/local/lib/e7readers
201 A user working on a new reader may compile the reader and place it in
202 a directory specified by the library path:
204 cp libuserd-myreader.so ~/lib/libuserd-devel.so
205 setenv <librarypath> ~/lib:$<librarypath>
207 The user is responsible for correctly configuring the library path
208 variable in order to make use of the libuserd-devel feature. The
209 library environment variables used are:
211 Machine type Environment variable to set
212 ------------ ---------------------------
213 sgi LD_LIBRARY_PATH
214 dec LD_LIBRARY_PATH
215 sun LD_LIBRARY_PATH
216 linux LD_LIBRARY_PATH
217 alpha linux LD_LIBRARY_PATH
218 hp SHLIB_PATH
219 ibm LIBPATH
221 As always, EnSight support is available if you need it.
223 -------------------------------
224 Quick Index of Library Routines
225 -------------------------------
227 Generally Needed for UNSTRUCTURED data
228 --------------------------------------
229 USERD_get_part_coords part's node coordinates
230 USERD_get_part_node_ids part's node ids
231 USERD_get_part_elements_by_type part's element connectivites
232 USERD_get_part_element_ids_by_type part's element ids
235 Generally Needed for BLOCK data
236 --------------------------------------
237 USERD_get_block_coords_by_component block coordinates
238 USERD_get_block_iblanking block iblanking values
239 USERD_get_ghosts_in_block_flag block ghost cell existence?
240 USERD_get_block_ghost_flags block ghost cell flags
242 These routines, which formerly were only for unstructured data, will now
243 also be called for structured data if you specify that ids will be given
244 in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
245 ------------------------------------------------------------------------------
246 USERD_get_part_node_ids part's node ids
247 USERD_get_part_element_ids_by_type part's element ids
250 Generally needed for either or both kinds of data
251 -------------------------------------------------
252 USERD_get_name_of_reader name of reader for GUI
253 USERD_get_reader_version provide reader version number
254 USERD_get_reader_descrip provide GUI more description (optional)
256 USERD_set_filenames filenames entered in GUI
257 USERD_set_server_number server which of how many
259 USERD_get_number_of_timesets number of timesets
260 USERD_get_timeset_description description of timeset
261 USERD_get_geom_timeset_number timeset # to use for geom
263 USERD_get_num_of_time_steps number of time steps
264 USERD_get_sol_times solution time values
265 USERD_set_time_set_and_step current timeset and time step
267 USERD_get_gold_part_build_info Gets the info needed for part building process
268 USERD_get_changing_geometry_status changing geometry?
269 USERD_get_node_label_status node labels?
270 USERD_get_element_label_status element labels?
271 USERD_get_model_extents provide model bounding extents
272 USERD_get_number_of_files_in_dataset number of files in model
273 USERD_get_dataset_query_file_info info about each model file
274 USERD_get_descrip_lines file associated description lines
275 USERD_get_number_of_model_parts number of model parts
276 USERD_get_part_build_info part/block type/descrip etc.
277 USERD_get_maxsize_info part/block allocation maximums
278 USERD_get_ghosts_in_model_flag model contains ghost cells?
279 USERD_get_nsided_conn Gets the element connectivities for nsided
280 elements. (utilizes the number of nodes
281 per element obtained in
282 USERD_get_part_elements_by_type)
283 USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced
284 elements (utilizes the number of faces
285 per element obtained in
286 USERD_get_part_elements_by_type)
287 USERD_get_nfaced_conn Gets the element connectivities for nfaced
288 elements (utilizes the number of nodes
289 per face obtained in
290 USERD_get_nfaced_nodes_per_face)
293 USERD_get_border_availability part border provided?
294 USERD_get_border_elements_by_type part border conn and parent info
296 USERD_get_number_of_variables number of variables
297 USERD_get_gold_variable_info variable type/descrip etc.
298 USERD_get_var_by_component part or block variable values
299 USERD_get_constant_val constant variable's value
300 USERD_get_var_value_at_specific node's or element's variable value over time
301 USERD_stop_part_building cleanup after part build routine
303 USERD_get_number_of_material_sets Gets the number of material sets
304 USERD_get_matf_set_info Gets the material set indices and names
305 USERD_get_number_of_materials Gets the number of materials
306 USERD_get_matf_var_info Gets the material indices and descriptions
307 USERD_size_matf_data Gets the length of either the
308 material ids list,
309 mixed-material ids list, or
310 mixed-material values list
311 USERD_load_matf_data Gets the material ids list,
312 mixed-material ids list, or
313 mixed-material values list
315 USERD_bkup archive routine
317 USERD_exit_routine cleanup upon exit routine
320 -------------------------
321 Order Routines are called
322 -------------------------
324 The various main operations are given basically in the order they will
325 be performed. Within each operation, the order the routines will be
326 called is given.
328 1. Setting name in the gui, and specifying one or two input fields
330 USERD_get_name_of_reader
331 USERD_get_reader_descrip (optional)
333 2. Getting the reader version (also distinguishes between API's)
335 USERD_get_reader_version
337 3. Setting filenames and getting timeset and time info
339 USERD_set_server_number
340 USERD_set_filenames
341 USERD_get_number_of_timesets
342 USERD_get_geom_timeset_number
344 for each timeset:
345 USERD_get_timeset_description
346 USERD_get_num_of_time_steps
347 USERD_get_sol_times
349 USERD_set_time_set_and_step
351 4. Gathering info for part builder
353 USERD_set_time_set_and_step
354 USERD_get_changing_geometry_status
355 USERD_get_node_label_status
356 USERD_get_element_label_status
357 USERD_get_number_of_files_in_dataset
358 USERD_get_dataset_query_file_info
359 USERD_get_descrip_lines (for geometry)
360 USERD_get_number_of_model_parts
361 USERD_get_gold_part_build_info
362 USERD_get_ghosts_in_model_flag
363 USERD_get_maxsize_info
364 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
365 USERD_get_model_extents OR (for model extents)
366 USERD_get_part_coords AND/OR
367 USERD_get_block_coords_by_component
369 5. Gathering Variable info
371 USERD_get_number_of_variables
372 USERD_get_gold_variable_info
374 6. Part building (per part created)
376 both unstructured and structured:
377 --------------------------------
378 USERD_set_time_set_and_step
380 if unstructured part:
381 --------------------
382 USERD_get_part_element_ids_by_type
383 USERD_get_part_elements_by_type
385 If any nsided elements:
387 USERD_get_nsided_conn
389 If any nfaced elements:
391 USERD_get_nfaced_nodes_per_face
392 USERD_get_nfaced_conn
394 USERD_get_part_coords
395 USERD_get_part_node_ids
397 else if structured part:
398 -----------------------
399 USERD_get_block_iblanking
400 USERD_get_block_coords_by_component
401 USERD_get_block_ghost_flags (If ghost cells in part)
402 USERD_get_part_node_ids (If node ids given)
403 USERD_get_part_element_ids_by_type (If element ids given)
405 both again:
406 ----------
407 USERD_get_border_availability (If border representation
408 USERD_get_border_elements_by_type is selected)
410 USERD_stop_part_building (only once when part builder
411 dialog is closed)
413 7. Loading Variables
415 constants:
416 ---------
417 USERD_set_time_set_and_step
418 USERD_get_constant_val
420 scalars/vectors/tensors:
421 ------------------------
422 USERD_get_descrip_lines
423 USERD_set_time_set_and_step
424 USERD_get_var_by_component
426 8. Changing geometry
428 changing coords only (per part):
429 --------------------
430 USERD_set_time_set_and_step
431 USERD_get_descrip_lines
432 USERD_get_part_coords
433 USERD_get_block_coords_by_component
435 changing connectivity (per part):
436 ---------------------
437 USERD_set_time_set_and_step
438 USERD_get_descrip_lines
439 USERD_get_number_of_model_parts
440 USERD_get_gold_part_build_info
441 USERD_get_ghosts_in_model_flag
442 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
443 USERD_get_model_extents OR
444 USERD_get_part_coords AND/OR
445 USERD_get_block_coords_by_component
446 USERD_get_part_element_ids_by_type
447 USERD_get_part_elements_by_type
448 USERD_get_part_coords
449 USERD_get_part_node_ids
450 USERD_get_block_iblanking
451 USERD_get_block_coords_by_component
452 USERD_get_block_ghost_flags (If ghost cells in part)
453 USERD_get_part_node_ids (If node ids given)
454 USERD_get_part_element_ids_by_type (If element ids given)
456 USERD_get_border_availability (If border representation
457 USERD_get_border_elements_by_type is selected)
460 9. Node or Element queries over time
462 USERD_get_var_value_at_specific
464 10. To see if materials in the model
466 USERD_get_number_of_material_sets
467 USERD_get_matf_set_info
469 If any material sets in the model (calls these once per material set):
470 USERD_get_number_of_materials
471 USERD_get_matf_var_info
473 For each elment type of each part containing material ids, calls:
474 USERD_size_matf_data
475 USERD_load_matf_data
477 If there are any elements with mixed materials, when a domain or
478 interface is created, calls these again per part:
480 USERD_size_matf_data
481 USERD_load_matf_data
485 -----------------------
486 Detailed Specifications
487 -----------------------
489 Include files:
490 --------------
491 The following header file is required in any file containing these library
492 routines.
494 #include "global_extern.h"
496 And it references:
498 #include "global_extern_proto.h"
502 *******************************************************************************
503 ****************************** Special Note ***********************************
504 *******************************************************************************
506 Make sure you use the proper define in the global_extern.h header file, namely:
507 #define USERD_API_203
509 Also, Make sure the api version in the USERD_get_reader_version routine is set
510 to "2.03" or larger.
512 Make sure your reader has access to the global_extern_proto.h This is a new
513 file which is accessed from the new global_extern.h
515 *******************************************************************************
516 *******************************************************************************
519 Basis of arrays:
520 ---------------
521 Unless explicitly stated otherwise, all arrays are zero based - in true C
522 fashion.
525 Global variables:
526 ----------------
527 You will generally need to have a few global variables which are shared by
528 the various library routines. The detailed specifications below have assumed
529 the following are available. (Their names describe their purpose, and they
530 will be used in helping describe the details of the routines below).
532 static int Numparts_available = 0;
533 static int Num_unstructured_parts = 0;
534 static int Num_structured_blocks = 0;
536 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
538 static int Num_timesets = 1;
539 static int Current_timeset = 1;
540 static int Geom_timeset_number = 1;
542 static int Num_time_steps[Z_MAXSETS] = 1;
543 static int Current_time_step = 0;
544 static int Num_variables = 0;
545 static int Num_dataset_files = 0;
547 static int Server_Number = 1; Which server of
548 static int Tot_Servers = 1; the total number of servers
552 _________________________________________
553 -----------------------------------------
554 Library Routines (in alphabetical order):
555 _________________________________________
556 -----------------------------------------
558 --------------------------------------------------------------------
559 USERD_bkup
561 Description:
562 -----------
563 This routine is called during the EnSight archive process. You can
564 use it to save or restore info relating to your user defined reader.
566 Specification:
567 -------------
568 int USERD_bkup(FILE *archive_file,
569 int backup_type)
571 Returns:
572 -------
573 Z_OK if successful
574 Z_ERR if not successful
576 Arguments:
577 ---------
578 (IN) archive_file = The archive file pointer
580 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
581 Z_REST_ARCHIVE for restoring archive
583 Notes:
584 -----
585 * Since EnSight's archive file is saved in binary form, you should
586 also do any writing to it or reading from it in binary.
588 * You should archive any variables, which will be needed for
589 future operations, that will not be read or computed again
590 before they will be needed. These are typically global
591 variables.
593 * Make sure that the number of bytes that you write on a save and
594 the number of bytes that you read on a restore are identical!!
596 * If any of the variables you save are allocated arrays, you must
597 do the allocations before restoring into them.
599 --------------------------------------------------------------------
600 USERD_exit_routine
602 Description:
603 -----------
604 This routine is called as EnSight is exiting. It can be used to clean
605 up anything needed - such as removing temporary files, etc. - or can simply
606 be a dummy.
608 Specification:
609 -------------
610 void USERD_exit_routine( void )
612 Arguments:
613 ---------
614 none
616 --------------------------------------------------------------------
617 USERD_get_block_coords_by_component
619 Description:
620 -----------
621 Get the coordinates of a given structured block, a component at a time.
623 Specification:
624 -------------
625 int USERD_get_block_coords_by_component(int block_number,
626 int which_component,
627 float *coord_array)
629 Returns:
630 -------
631 Z_OK if successful
632 Z_ERR if not successful
634 Arguments:
635 ---------
636 (IN) block_number = The block part number
637 (1-based index of part table, namely:
639 1 ... Numparts_available.
641 It is NOT the part_id that
642 is loaded in USERD_get_gold_part_build_info)
644 (IN) which_component = Z_COMPX if x component wanted
645 = Z_COMPY if y component wanted
646 = Z_COMPZ if z component wanted
648 (OUT) coord_array = 1D array containing x,y, or z
649 coordinate component of each node
651 (Array will have been allocated
652 i*j*k for the block long)
654 Notes:
655 -----
656 * Not called unless Num_structured_blocks is > 0
658 * Will be based on Current_time_step
662 --------------------------------------------------------------------
663 USERD_get_block_iblanking
665 Description:
666 -----------
667 Get the iblanking value at each node of a block (if the block is
668 iblanked).
670 Specification:
671 -------------
672 int USERD_get_block_iblanking(int block_number,
673 int *iblank_array)
675 Returns:
676 -------
677 Z_OK if successful
678 Z_ERR if not successful
680 Arguments:
681 ---------
682 (IN) block_number = The block part number
683 (1-based index of part table, namely:
685 1 ... Numparts_available.
687 It is NOT the part_id that
688 is loaded in USERD_get_gold_part_build_info)
690 (OUT) iblank_array = 1D array containing iblank value
691 for each node.
693 (Array will have been allocated
694 i*j*k for the block long)
696 possible values are: Z_EXT = exterior
697 Z_INT = interior
698 Z_BND = boundary
699 Z_INTBND = internal boundary
700 Z_SYM = symmetry plane
702 Notes:
703 -----
704 * Not called unless Num_structured_blocks is > 0 and you have
705 some iblanked blocks
707 * Will be based on Current_time_step
711 ----------------------------------------------------------------------
712 USERD_get_block_ghost_flags
714 Description:
715 -----------
716 Get the ghost_flags value at each element of a block containing ghost cells.
718 Specification:
719 -------------
720 int USERD_get_block_ghost_flags(int block_number,
721 int *ghost_flags)
722 Returns:
723 -------
724 Z_OK if successful
725 Z_ERR if not successful
727 Arguments:
728 ---------
729 (IN) block_number = The block number
730 (1-based index of part table, namely:
732 1 ... Numparts_available.
734 It is NOT the part_id that
735 is loaded in USERD_get_gold_part_build_info)
737 (OUT) ghost_flags = 1D array containing ghost flag value
738 for each block cell.
740 (Array will have been allocated
741 (i-1)*(j-1)*(k-1) for the block long)
743 possible values are: 0 = non-ghost cell (normal cell)
744 >0 = ghost cell
746 Notes:
747 -----
748 * This routine is new in the 2.01 API
750 * This will be based on Current_time_step
752 * Only called for structured "block" parts that have some ghost cells
753 as indicated by the USERD_get_ghost_in_block_flag. The model must
754 of course also have been indicated to have some ghost cells in the
755 USERD_get_ghost_in_model_flag routine.
757 * It is sufficient to set the value to be 1 to flag as a ghost cell,
758 but the value can be any non-zero value, so you could use it to
759 indicate which block or which server (for Server-of-server use) the
760 cell is actually in.
764 --------------------------------------------------------------------
765 USERD_get_border_availability
767 Description:
768 -----------
769 Finds out if border elements are provided by the reader for the
770 desired part, or will need to be computed internally by EnSight.
772 Specification:
773 -------------
774 int USERD_get_border_availability(int part_number,
775 int number_of_elements[Z_MAXTYPE])
777 Returns:
778 -------
779 Z_OK if border elements will be provided by the reader.
780 (number_of_elements array will be loaded and
781 USERD_get_border_elements_by_type will be called)
783 Z_ERR if border elements are not available - thus EnSight must compute.
784 (USERD_get_border_elements_by_type will not be called)
787 Arguments:
788 ---------
789 (IN) part_number = The part number
790 (1-based index of part table, namely:
792 1 ... Numparts_available.
794 It is NOT the part_id that
795 is loaded in USERD_get_gold_part_build_info)
797 (OUT) number_of_elements = 2D array containing number of
798 each type of border element in
799 the part.
800 ------------
801 Possible types are:
803 Z_POINT = point
804 Z_BAR02 = 2-noded bar
805 Z_BAR03 = 3-noded bar
806 Z_TRI03 = 3-noded triangle
807 Z_TRI06 = 6-noded triangle
808 Z_QUA04 = 4-noded quadrilateral
809 Z_QUA08 = 8-noded quadrilateral
811 Notes:
812 -----
813 * Only called if border representation is used.
815 * Will be based on Current_time_step
819 --------------------------------------------------------------------
820 USERD_get_border_elements_by_type
822 Description:
823 -----------
824 Provides border element connectivity and parent information.
826 Specification:
827 -------------
828 int USERD_get_border_elements_by_type(int part_number,
829 int element_type,
830 int **conn_array,
831 short *parent_element_type,
832 int *parent_element_num)
834 Returns:
835 -------
836 Z_OK if successful
837 Z_ERR if not successful
839 Arguments:
840 ---------
841 (IN) part_number = The part number
842 (1-based index of part table, namely:
844 1 ... Numparts_available.
846 It is NOT the part_id that
847 is loaded in USERD_get_gold_part_build_info)
849 (IN) element_type = One of the following (See global_extern.h)
850 Z_POINT node point element
851 Z_BAR02 2 node bar
852 Z_BAR03 3 node bar
853 Z_TRI03 3 node triangle
854 Z_TRI06 6 node triangle
855 Z_QUA04 4 node quad
856 Z_QUA08 8 node quad
858 (OUT) conn_array = 2D array containing connectivity
859 of each border element of the type.
861 (Array will have been allocated
862 num_of_elements of the type by
863 connectivity length of the type)
865 ex) If number_of_elements[Z_TRI03] = 25
866 number_of_elements[Z_QUA04] = 100
867 number_of_elements[Z_QUA08] = 30
868 as obtained in:
869 USERD_get_border_availability
871 Then the allocated dimensions available
872 for this routine will be:
873 conn_array[25][3] when called with Z_TRI03
875 conn_array[100][4] when called with Z_QUA04
877 conn_array[30][8] when called with Z_QUA08
879 (OUT) parent_element_type = 1D array containing element type of the
880 parent element (the one that the border
881 element is a face/edge of).
883 (Array will have been allocated
884 num_of_elements of the type long)
886 (OUT) parent_element_num = 1D array containing element number of the
887 parent element (the one that the border
888 element is a face/edge of).
890 (Array will have been allocated
891 num_of_elements of the type long)
894 Notes:
895 -----
896 * Not called unless USERD_get_border_availability returned Z_OK
898 * Will be based on Current_time_step
902 --------------------------------------------------------------------
903 USERD_get_changing_geometry_status
905 Description:
906 -----------
907 Gets the changing geometry status for the model
909 Specification:
910 -------------
911 int USERD_get_changing_geometry_status( void )
913 Returns:
914 -------
915 Z_STATIC if geometry does not change
916 Z_CHANGE_COORDS if changing coordinates only
917 Z_CHANGE_CONN if changing connectivity
919 Arguments:
920 ---------
921 none
923 Notes:
924 -----
925 * EnSight does not support changing number of parts. But the
926 coords and/or the connectivity of the parts can change. Note that
927 a part is allowed to be empty (number of nodes and elements equal
928 to zero).
931 --------------------------------------------------------------------
932 USERD_get_constant_val
934 Description:
935 -----------
936 Get the value of a constant at a time step
938 Specification:
939 -------------
940 float USERD_get_constant_value(int which_var,
941 int imag_data)
943 Returns:
944 -------
945 Value of the requested constant variable
947 Arguments:
948 ---------
949 (IN) which_var = The variable number
951 (IN) imag_data = TRUE if want imaginary data value.
952 FALSE if want real data value.
954 Notes:
955 -----
956 * Will be based on Current_time_step
960 --------------------------------------------------------------------
961 USERD_get_dataset_query_file_info
963 Description:
964 -----------
965 Get the information about files in the dataset. Used for the
966 dataset query option within EnSight.
968 Specification:
969 -------------
970 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
972 Returns:
973 -------
974 Z_OK if successful
975 Z_ERR if not successful
977 Arguments:
978 ---------
979 (OUT) qfiles = Structure containing information about each file
980 of the dataset. The Z_QFILES structure is defined
981 in the global_extern.h file
983 (The structure will have been allocated
984 Num_dataset_files long, with 10 description
985 lines per file).
987 qfiles[].name = The name of the file
988 (Z_MAXFILENP is the dimensioned length
989 of the name)
991 qfiles[].sizeb = The number of bytes in the file
992 (Typically obtained with a call to the
993 "stat" system routine) (Is a long)
995 qfiles[].timemod = The time the file was last modified
996 (Z_MAXTIMLEN is the dimensioned length
997 of this string)
998 (Typically obtained with a call to the
999 "stat" system routine)
1001 qfiles[].num_d_lines = The number of description lines you
1002 are providing from the file. Max = 10
1004 qfiles[].f_desc[] = The description line(s) per file,
1005 qfiles[].num_d_lines of them
1006 (Z_MAXFILENP is the allocated length of
1007 each line)
1009 Notes:
1010 -----
1011 * If Num_dataset_files is 0, this routine will not be called.
1012 (See USERD_get_number_of_files_in_dataset)
1015 --------------------------------------------------------------------
1016 USERD_get_descrip_lines
1018 Description:
1019 -----------
1020 Get two description lines associated with geometry per time step,
1021 or one description line associated with a variable per time step.
1023 Specification:
1024 -------------
1025 int USERD_get_descrip_lines(int which_type,
1026 int which_var,
1027 int imag_data,
1028 char line1[Z_BUFL],
1029 char line2[Z_BUFL])
1031 Returns:
1032 -------
1033 Z_OK if successful
1034 Z_ERR if not successful
1036 Arguments:
1037 ---------
1038 (IN) which_type = Z_GEOM for geometry (2 lines)
1039 = Z_VARI for variable (1 line)
1041 (IN) which_var = If it is a variable, which one.
1042 Ignored if geometry type.
1044 (IN) imag_data = TRUE if want imaginary data file.
1045 FALSE if want real data file.
1047 (OUT) line1 = The 1st geometry description line,
1048 or the variable description line.
1050 (OUT) line2 = The 2nd geometry description line
1051 Not used if variable type.
1053 Notes:
1054 -----
1055 * Will be based on Current_time_step
1057 * These are the lines EnSight can echo to the screen in
1058 annotation mode.
1062 --------------------------------------------------------------------
1063 USERD_get_element_label_status
1065 Description:
1066 -----------
1067 Answers the question as to whether element labels will be provided.
1069 Specification:
1070 -------------
1071 int USERD_get_element_label_status( void )
1073 Returns:
1074 -------
1075 TRUE if element labels will be provided
1076 FALSE if element labels will NOT be provided
1078 Arguments:
1079 ---------
1080 none
1082 Notes:
1083 -----
1084 * element lables are needed in order to do any element querying, or
1085 element labeling on-screen within EnSight.
1087 * Prior to API 2.01:
1088 -----------------
1089 For unstructured parts, you can read them from your file if
1090 available, or can assign them, etc. They need to be unique
1091 per part, and are often unique per model.
1093 API 1.0:
1094 USERD_get_element_ids_for_part is used to obtain the ids,
1095 on a part by part basis, if TRUE status is returned here.
1097 API 2.0:
1098 USERD_get_part_element_ids_by_type is used to obtain the ids,
1099 on a per part, per type basis, if TRUE status is returned here.
1101 For structured parts, EnSight will assign ids if you return a
1102 status of TRUE here. You cannot assign them youself!!
1104 * Starting at API 2.01:
1105 --------------------
1106 For both unstructured and structured parts, you can read them
1107 from your file if available, or can assign them, etc. They need
1108 to be unique per part, and are often unique per model (especially
1109 if you are dealing with a decomposed dataset).
1111 USERD_get_part_element_ids_by_type is used to obtain the ids,
1112 on an element type by part basis, if TRUE status is returned here.
1114 * Will call USERD_get_part_element_ids_by_type for each type of
1115 of each part if this routine returns TRUE.
1116 --------------------------------------------------------------------
1117 USERD_get_geom_timeset_number -
1119 Description:
1120 -----------
1121 Gets the timeset number to be used for geometry
1123 Specification:
1124 -------------
1125 int USERD_get_geom_timeset_number( void )
1127 Returns:
1128 -------
1129 Geom_timeset_number = The timeset number that will be used for geometry.
1130 For example, if USERD_get_number_of timesets
1131 returns 2, the valid timeset numbers would be
1132 1 or 2.
1134 Arguments:
1135 ---------
1136 none
1138 Notes:
1139 -----
1140 * If your model is static, which you indicated by returning a zero
1141 in USERD_get_number_of_timesets, you can return a zero here as well.
1145 --------------------------------------------------------------------
1146 USERD_get_gold_part_build_info
1148 Description:
1149 -----------
1150 Gets the info needed for the part building process.
1152 Specification:
1153 -------------
1154 int USERD_get_gold_part_build_info(int *part_id,
1155 int *part_types,
1156 char *part_description[Z_BUFL],
1157 int *number_of_nodes,
1158 int *number_of_elements[Z_MAXTYPE],
1159 int *ijk_dimensions[9],
1160 int *iblanking_options[6])
1162 Returns:
1163 -------
1164 Z_OK if successful
1165 Z_ERR if not successful
1167 Arguments:
1168 ---------
1169 (OUT) part_id = Array containing the external part
1170 ids for each of the model parts.
1172 IMPORTANT:
1173 Parts numbers must be >= 1, because
1174 of the way they are used in the GUI
1176 *******************************************
1177 The ids provided here are the numbers by
1178 which the parts will be referred to in the
1179 GUI (if possible). They are basically
1180 labels as far as you are concerned.
1182 Note: The part numbers you pass to routines
1183 which receive a part_number or block_number
1184 or which_part as an argument are the 1-based
1185 table index of the parts!
1187 example: If Numparts_available = 3
1189 Table index part_id
1190 ----------- -------
1191 1 13
1192 2 57
1193 3 125
1195 ^ ^
1196 | |
1197 | These are placed in:
1198 | part_id[0] = 13
1199 | part_id[1] = 57
1200 | part_id[2] = 125
1201 | for GUI labeling purposes.
1202 |
1203 These implied table indices are the part_number,
1204 block_number, or which_part numbers that you would
1205 pass to routines like:
1207 USERD_get_part_coords(int part_number,...
1208 USERD_get_part_node_ids(int part_number,...
1209 USERD_get_part_elements_by_type(int part_number,...
1210 USERD_get_part_element_ids_by_type(int part_number,...
1211 USERD_get_block_coords_by_component(int block_number,...
1212 USERD_get_block_iblanking(int block_number,...
1213 USERD_get_block_ghost_flags(int block_number,...
1214 USERD_get_ghosts_in_block_flag(int block_number)
1215 USERD_get_border_availability(int part_number,...
1216 USERD_get_border_elements_by_type(int part_number,...
1217 USERD_get_var_by_component(int which_variable,
1218 int which_part,...
1219 USERD_get_var_value_at_specific(int which_var,
1220 int which_node_or_elem,
1221 int which_part,...
1222 ********************************************
1224 (Array will have been allocated
1225 Numparts_available long)
1227 (OUT) part_types = Array containing one of the
1228 following for each model part:
1230 Z_UNSTRUCTURED or
1231 Z_STRUCTURED or
1232 Z_IBLANKED
1234 (Array will have been allocated
1235 Numparts_available long)
1237 (OUT) part_description = Array containing a description
1238 for each of the model parts
1240 (Array will have been allocated
1241 Numparts_available by Z_BUFL
1242 long)
1244 (OUT) number_of_nodes = Number of unstructured nodes in the part
1246 (Array will have been allocated
1247 Numparts_available long)
1249 (OUT) number_of_elements = 2D array containing number of
1250 each type of element for each
1251 unstructured model part.
1252 ------------
1253 Possible types are:
1255 Z_POINT = point
1256 Z_BAR02 = 2-noded bar
1257 Z_BAR03 = 3-noded bar
1258 Z_TRI03 = 3-noded triangle
1259 Z_TRI06 = 6-noded triangle
1260 Z_QUA04 = 4-noded quadrilateral
1261 Z_QUA08 = 8-noded quadrilateral
1262 Z_TET04 = 4-noded tetrahedron
1263 Z_TET10 = 10-noded tetrahedron
1264 Z_PYR05 = 5-noded pyramid
1265 Z_PYR13 = 13-noded pyramid
1266 Z_PEN06 = 6-noded pentahedron
1267 Z_PEN15 = 15-noded pentahedron
1268 Z_HEX08 = 8-noded hexahedron
1269 Z_HEX20 = 20-noded hexahedron
1271 Z_G_POINT = ghost node point element
1272 Z_G_BAR02 = 2 node ghost bar
1273 Z_G_BAR03 = 3 node ghost bar
1274 Z_G_TRI03 = 3 node ghost triangle
1275 Z_G_TRI06 = 6 node ghost triangle
1276 Z_G_QUA04 = 4 node ghost quad
1277 Z_G_QUA08 = 8 node ghost quad
1278 Z_G_TET04 = 4 node ghost tetrahedron
1279 Z_G_TET10 = 10 node ghost tetrahedron
1280 Z_G_PYR05 = 5 node ghost pyramid
1281 Z_G_PYR13 = 13 node ghost pyramid
1282 Z_G_PEN06 = 6 node ghost pentahedron
1283 Z_G_PEN15 = 15 node ghost pentahedron
1284 Z_G_HEX08 = 8 node ghost hexahedron
1285 Z_G_HEX20 = 20 node ghost hexahedron
1287 (Ignored unless Z_UNSTRUCTURED type)
1289 (Array will have been allocated
1290 Numparts_available by
1291 Z_MAXTYPE long)
1293 (OUT) ijk_dimensions = 2D array containing ijk dimension info
1294 for structured blocks
1296 For Z_UNSTRUCTURED - is ignored
1298 For Z_STRUCTURED or Z_IBLANKED
1300 Prior to version 2.03:
1301 ----------------------
1302 (Array will have been allocated
1303 Numparts_available by 3 long)
1305 ijk_dimensions[][0] = I dimension
1306 ijk_dimensions[][1] = J dimension
1307 ijk_dimensions[][2] = K dimension
1310 Starting at version 2.03:
1311 ------------------------
1312 (Array will have been allocated
1313 Numparts_available by 9 long)
1315 There are two ways to do this:
1316 ------------------------------
1317 1. The simple one, without ranges.
1319 This is good for all structured models
1320 that will NOT be used in EnSight's
1321 Server of Servers
1323 Simply provide the ijk dimensions in the
1324 first three slots and place a -1 in
1325 the 4th slot. (The remaining slots will
1326 be ignored).
1328 Thus,
1329 ijk_dimensions[][0] = I dimension of block
1330 ijk_dimensions[][1] = J dimension of block
1331 ijk_dimensions[][2] = K dimension of block
1332 ijk_dimensions[][3] = -1
1334 (J planes)
1335 4 *-------*-------*
1336 | | | ijk_dimension[0][0] = 3
1337 | | | ijk_dimension[0][1] = 4
1338 | | | ijk_dimension[0][2] = 1
1339 3 *-------*-------*
1340 | | | ijk_dimension[0][4] = -1
1341 | | |
1342 | | |
1343 2 *-------*-------*
1344 | | |
1345 | | |
1346 | | |
1347 1 *-------*-------*
1348 1 2 3 (I planes)
1352 2. Using ranges.
1354 This one can be used anytime, but MUST
1355 be used if EnSight's Server of Servers
1356 is to be used!
1358 The first 3 slots contain the ijk dimension
1359 of the complete block (of which this may be
1360 a portion). The last 6 slots contain the
1361 ijk min and max ranges within the complete.
1363 Thus,
1364 ijk_dimensions[][0] = I dim of complete block
1365 ijk_dimensions[][1] = J dim of complete block
1366 ijk_dimensions[][2] = K dim of complete block
1368 ijk_dimensions[][3] = Imin of portion (1-based)
1369 ijk_dimensions[][4] = Imax of portion (1-based)
1370 ijk_dimensions[][5] = Jmin of portion (1-based)
1371 ijk_dimensions[][6] = Jmax of portion (1-based)
1372 ijk_dimensions[][7] = Kmin of portion (1-based)
1373 ijk_dimensions[][8] = Kmax of portion (1-based)
1376 example1: (Model has one part, a simple 2D block,
1377 and want whole thing)
1379 (J planes)
1380 4 *-------*-------*
1381 | | | ijk_dimension[0][0] = 3
1382 | | | ijk_dimension[0][1] = 4
1383 | | | ijk_dimension[0][2] = 1
1384 3 *-------*-------*
1385 | | | ijk_dimension[0][3] = 1
1386 | | | ijk_dimension[0][4] = 3
1387 | | | ijk_dimension[0][5] = 1
1388 2 *-------*-------* ijk_dimension[0][6] = 4
1389 | | | ijk_dimension[0][7] = 1
1390 | | | ijk_dimension[0][8] = 1
1391 | | |
1392 1 *-------*-------*
1393 1 2 3 (I planes)
1396 example2: (Want to have the block represented
1397 in two portions - 2 parts)
1399 (J planes) top portion
1400 4 *-------*-------*
1401 | | | ijk_dimension[0][0] = 3
1402 | | | ijk_dimension[0][1] = 4
1403 | | | ijk_dimension[0][2] = 1
1404 3 *-------*-------*
1405 . . . ijk_dimension[0][3] = 1
1406 . . . ijk_dimension[0][4] = 3
1407 . . . ijk_dimension[0][5] = 3
1408 2 ................. ijk_dimension[0][6] = 4
1409 . . . ijk_dimension[0][7] = 1
1410 . . . ijk_dimension[0][8] = 1
1411 . . .
1412 1 .................
1413 1 2 3 (I planes)
1416 (J planes) bottom portion
1417 4 .................
1418 . . . ijk_dimension[1][0] = 3
1419 . . . ijk_dimension[2][1] = 4
1420 . . . ijk_dimension[3][2] = 1
1421 3 *-------*-------*
1422 | | | ijk_dimension[1][3] = 1
1423 | | | ijk_dimension[1][4] = 3
1424 | | | ijk_dimension[1][5] = 1
1425 2 *-------*-------* ijk_dimension[1][6] = 3
1426 | | | ijk_dimension[1][7] = 1
1427 | | | ijk_dimension[1][8] = 1
1428 | | |
1429 1 *-------*-------*
1430 1 2 3 (I planes)
1433 And note that if you were partioning this block for
1434 EnSight's Server of Servers, you would only have one part,
1435 instead of two. Each SOS server would return its appropriate
1436 ranges in the last 6 slots. The first 3 slots would remain constant.
1439 (OUT) iblanking_options = 2D array containing iblanking
1440 options possible for each
1441 structured model part.
1442 ----------
1443 (Ignored unless Z_IBLANKED type)
1445 (Array will have been allocated
1446 Numparts_available by 6 long)
1448 iblanking_options[][Z_EXT] = TRUE if external (outside)
1449 [][Z_INT] = TRUE if internal (inside)
1450 [][Z_BND] = TRUE if boundary
1451 [][Z_INTBND] = TRUE if internal boundary
1452 [][Z_SYM] = TRUE if symmetry surface
1455 Notes:
1456 -----
1457 * If you haven't built a table of pointers to the different parts,
1458 you might want to do so here as you gather the needed info.
1460 * Will be based on Current_time_step
1463 --------------------------------------------------------------------
1464 USERD_get_gold_variable_info
1466 Description:
1467 -----------
1468 Get the variable descriptions, types and filenames
1470 Specification:
1471 -------------
1472 int USERD_get_gold_variable_info(char **var_description,
1473 char **var_filename,
1474 int *var_type,
1475 int *var_classify,
1476 int *var_complex,
1477 char **var_ifilename,
1478 float *var_freq,
1479 int *var_contran,
1480 int *var_timeset)
1482 Returns:
1483 -------
1484 Z_OK if successful
1485 Z_ERR if not successful
1487 Arguments:
1488 ---------
1489 (OUT) var_description = Variable descriptions
1491 (Array will have been allocated
1492 Num_variables by Z_BUFL long)
1494 variable description restrictions:
1495 ----------------------------------
1496 1. Only first 19 characters used in EnSight.
1497 2. Leading and trailing whitespace will be removed by EnSight.
1498 3. Illegal characters will be replaced by underscores.
1499 4. Thay may not start with a numeric digit.
1500 4. No two variables may have the same description.
1503 (OUT) var_filename = Variable real filenames
1505 (Array will have been allocated
1506 Num_variables by Z_BUFL long)
1508 (OUT) var_type = Variable type
1510 (Array will have been allocated
1511 Num_variables long)
1513 types are: Z_CONSTANT
1514 Z_SCALAR
1515 Z_VECTOR
1516 Z_TENSOR
1517 Z_TENSOR9
1519 (OUT) var_classify = Variable classification
1521 (Array will have been allocated
1522 Num_variables long)
1524 types are: Z_PER_NODE
1525 Z_PER_ELEM
1527 (OUT) var_complex = TRUE if complex, FALSE otherwise
1529 (Array will have been allocated
1530 Num_variables long)
1532 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1534 (Array will have been allocated
1535 Num_variables by Z_BUFL long)
1537 (OUT) var_freq = complex frequency (if complex)
1539 (Array will have been allocated
1540 Num_variables long)
1542 (OUT) var_contran = TRUE if constant changes per time step
1543 FALSE if constant truly same at all time steps
1545 (Array will have been allocated
1546 Num_variables long)
1548 (OUT) var_timeset = Timeset the variable will use (1 based).
1549 (For static models, set it to 1)
1551 (Array will have been allocated
1552 Num_variables long)
1554 For example: If USERD_get_number_of_timesets
1555 returns 2, the valid
1556 timeset_number's would be 1 or 2
1559 Notes:
1560 -----
1561 * The implied variable numbers apply, but be aware that the
1562 arrays are zero based.
1563 So for variable 1, will need to provide var_description[0]
1564 var_filename[0]
1565 var_type[0]
1566 var_classify[0]
1567 var_complex[0]
1568 var_ifilename[0]
1569 var_freq[0]
1570 var_contran[0]
1571 var_timeset[0]
1574 for variable 2, will need to provide var_description[1]
1575 var_filename[1]
1576 var_type[1]
1577 var_classify[1]
1578 var_complex[1]
1579 var_ifilename[1]
1580 var_freq[1]
1581 var_contran[1]
1582 var_timeset[1]
1583 etc.
1588 --------------------------------------------------------------------
1589 USERD_get_ghosts_in_block_flag
1591 Description:
1592 -----------
1593 Gets whether ghost cells present in block or not
1595 Specification:
1596 -------------
1597 int USERD_get_ghosts_in_block_flag(int block_number)
1599 Returns:
1600 -------
1601 TRUE if any ghost cells in this structured part
1602 FALSE if no ghost cells in this structured part
1604 Arguments:
1605 ---------
1606 (IN) block_number = The block part number
1607 (1-based index of part table, namely:
1609 1 ... Numparts_available.
1611 It is NOT the part_id that
1612 is loaded in USERD_get_gold_part_build_info)
1614 Notes:
1615 -----
1616 * This routine is new in the 2.01 API
1617 * This will be based on Current_time_step
1619 * Intended for structured parts only, value will be ignored for
1620 unstructured parts
1624 --------------------------------------------------------------------
1625 USERD_get_ghosts_in_model_flag
1627 Description:
1628 -----------
1629 Answers the question as to whether any ghost cells in the model.
1631 Specification:
1632 -------------
1633 int USERD_get_ghosts_in_model_flag( void )
1635 Returns:
1636 -------
1637 TRUE if any ghost cells in the model
1638 FALSE if no ghost cells in the model
1640 Arguments:
1641 ---------
1643 Notes:
1644 -----
1645 * This routine is new in the 2.01 API
1647 -------------------------------------------------------------------------
1648 USERD_get_matf_set_info
1650 Description:
1651 -----------
1652 Get the material set ids and names
1654 Specification:
1655 -------------
1656 int USERD_get_matf_set_info(int *mat_set_ids,
1657 char **mat_set_name)
1659 Returns:
1660 -------
1661 Z_OK if successful
1662 Z_ERR if not successful
1664 Arguments:
1665 ---------
1666 (OUT) mat_set_ids = 1D material set ids array
1668 (Array will have been allocated
1669 Num_material_sets long)
1671 (OUT) mat_set_name = 2D material set name array
1673 (Array will have been allocated
1674 Num_material_sets by Z_BUFL long)
1676 Notes:
1677 -----
1678 * Will not be called if Num_material_sets is zero
1679 * See USERD_get_number_of_material_sets header for explanatory example
1682 --------------------------------------------------------------------
1683 USERD_get_matf_var_info
1685 Description:
1686 -----------
1687 Gets the material ids and descriptions for the material set
1689 Specification:
1690 -------------
1691 int USERD_get_matf_var_info(int set_index,
1692 int *mat_ids,
1693 char **mat_desc)
1695 Returns:
1696 -------
1697 Z_OK if successful
1698 Z_ERR if not successful
1700 Arguments:
1701 ---------
1702 (IN) set_index = the material set index (zero based)
1704 (OUT) mat_ids[set_index] = 1D integer array containing the material
1705 ids to associated with each material
1707 (Array will have been allocated
1708 Num_materials[set_index] long)
1710 (OUT) mat_desc[set_index] = 2D char array containing the material
1711 descriptions to associated with each material
1713 (Array will have been allocated
1714 Num_materials[set_index] by Z_BUFL long)
1716 Notes:
1717 -----
1718 * See USERD_get_number_of_material_sets header for explanatory example
1719 * Will not be called if Num_material_sets is zero, or
1720 Num_materials[set_index] is zero
1725 --------------------------------------------------------------------
1726 USERD_get_maxsize_info
1728 Description:
1729 -----------
1730 Gets maximum part sizes for efficient memory allocation.
1732 Transient models (especially those that increase in size) can cause
1733 reallocations, at time step changes, to keep chewing up more and
1734 more memory. The way to avoid this is to know what the maximum
1735 size of such memory will be, and allocate for this maximum initially.
1737 Accordingly, if you choose to provide this information (it is optional),
1738 EnSight will take advantage of it.
1741 Specification:
1742 -------------
1743 int USERD_get_maxsize_info(int *max_number_of_nodes,
1744 int *max_number_of_elements[Z_MAXTYPE],
1745 int *max_ijk_dimensions[3])
1747 Returns:
1748 -------
1749 Z_OK if supplying maximum data
1750 Z_ERR if not supplying maximum data, or some error occurred
1751 while trying to obtain it.
1753 Arguments:
1754 ---------
1755 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1756 in the part (over all time).
1758 (Array will have been allocated
1759 Numparts_available long)
1761 (OUT) max_number_of_elements = 2D array containing maximum number of
1762 each type of element for each
1763 unstructured model part (over all time).
1764 ------------
1765 Possible types are:
1767 Z_POINT = point
1768 Z_BAR02 = 2-noded bar
1769 Z_BAR03 = 3-noded bar
1770 Z_TRI03 = 3-noded triangle
1771 Z_TRI06 = 6-noded triangle
1772 Z_QUA04 = 4-noded quadrilateral
1773 Z_QUA08 = 8-noded quadrilateral
1774 Z_TET04 = 4-noded tetrahedron
1775 Z_TET10 = 10-noded tetrahedron
1776 Z_PYR05 = 5-noded pyramid
1777 Z_PYR13 = 13-noded pyramid
1778 Z_PEN06 = 6-noded pentahedron
1779 Z_PEN15 = 15-noded pentahedron
1780 Z_HEX08 = 8-noded hexahedron
1781 Z_HEX20 = 20-noded hexahedron
1783 Z_G_POINT = ghost node point element
1784 Z_G_BAR02 = 2 node ghost bar
1785 Z_G_BAR03 = 3 node ghost bar
1786 Z_G_TRI03 = 3 node ghost triangle
1787 Z_G_TRI06 = 6 node ghost triangle
1788 Z_G_QUA04 = 4 node ghost quad
1789 Z_G_QUA08 = 8 node ghost quad
1790 Z_G_TET04 = 4 node ghost tetrahedron
1791 Z_G_TET10 = 10 node ghost tetrahedron
1792 Z_G_PYR05 = 5 node ghost pyramid
1793 Z_G_PYR13 = 13 node ghost pyramid
1794 Z_G_PEN06 = 6 node ghost pentahedron
1795 Z_G_PEN15 = 15 node ghost pentahedron
1796 Z_G_HEX08 = 8 node ghost hexahedron
1797 Z_G_HEX20 = 20 node ghost hexahedron
1799 (Ignored unless Z_UNSTRUCTURED type)
1801 (Array will have been allocated
1802 Numparts_available by
1803 Z_MAXTYPE long)
1805 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1806 for each structured model part (over all time).
1807 ----------
1808 (Ignored if Z_UNSTRUCTURED type)
1810 (Array will have been allocated
1811 Numparts_available by 3 long)
1813 max_ijk_dimensions[][0] = maximum I dimension
1814 max_ijk_dimensions[][1] = maximum J dimension
1815 max_ijk_dimensions[][2] = maximum K dimension
1817 Notes:
1818 -----
1819 * You need to have first called USERD_get_number_of_model_parts and
1820 USERD_get_gold_part_build_info, so Numparts_available is known and
1821 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1822 or Z_IBLANKED) of each part.
1824 * This will NOT be based on Current_time_step - it is to be the maximum
1825 values over all time!!
1827 * This information is optional. If you return Z_ERR, Ensight will still
1828 process things fine, reallocating as needed, etc. However, for
1829 large transient models you will likely use considerably more memory
1830 and take more processing time for the memory reallocations. So, if it
1831 is possible to provide this information "up front", it is recommended
1832 to do so.
1835 --------------------------------------------------------------------
1836 USERD_get_model_extents
1838 Description:
1839 -----------
1840 Gets the model bounding box extents. If this routine supplys them
1841 EnSight will not have to spend time doing so. If this routine
1842 returns Z_ERR, EnSight will have to take the time to touch all the
1843 nodes and gather the extent info.
1845 Specification:
1846 -------------
1847 int USERD_get_model_extents(float extents[6])
1849 Returns:
1850 -------
1851 Z_OK if successful
1852 Z_ERR if not successful (whereupon EnSight will determine by reading
1853 all coords of all parts)
1855 Arguments:
1856 ---------
1857 (OUT) extents[0] = min x
1858 [1] = max x
1859 [2] = min y
1860 [3] = max y
1861 [4] = min z
1862 [5] = max z
1864 Notes:
1865 -----
1866 * This will be based on Current_time_step
1869 --------------------------------------------------------------------
1870 USERD_get_name_of_reader
1872 Description:
1873 -----------
1874 Gets the name of your user defined reader. The user interface will
1875 ask for this and include it in the available reader list.
1877 Specification:
1878 -------------
1879 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1880 int *two_fields)
1882 Returns:
1883 -------
1884 Z_OK if successful
1885 Z_ERR if not successful
1887 Arguments:
1888 ---------
1889 (OUT) reader_name = the name of the your reader or data format.
1890 (max length is Z_MAX_USERD_NAME, which is 20)
1892 (OUT) *two_fields = FALSE if only one data field required
1893 in the data dialog of EnSight.
1894 TRUE if two data fields required.
1896 Notes:
1897 -----
1898 * Always called. Please be sure to provide a name for your custom
1899 reader format.
1901 --------------------------------------------------------------------
1902 USERD_get_nfaced_conn
1904 Description:
1905 -----------
1906 Gets the array containing the connectivity of nsided faces of nfaced elements
1908 Specification:
1909 -------------int
1910 int USERD_get_nfaced_conn(int part_number,
1911 int *nfaced_conn_array)
1913 Returns:
1914 -------
1915 Z_OK if successful
1916 Z_ERR if not successful
1918 Arguments:
1919 ---------
1920 (IN) part_number = the part number
1922 (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced
1923 elements
1925 (int array will have been allocated long enough to
1926 hold all the nsided face connectivities. Which is
1927 the sum of all the nodes per face values in the
1928 nfaced_npf_array of USERD_get_nfaced_nodes_per_face)
1930 Notes:
1931 -----
1932 * Will not be called unless there are some nfaced elements in the part
1934 * Providing nfaced information to Ensight:
1936 1. In USERD_get_gold_part_build_info, provide the number of nfaced
1937 polyhedral elements in the part.
1939 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
1940 the number of faces per nfaced element. (as if connectivity
1941 length of an nfaced element is one)
1943 3. In this routine, provide the streamed number of nodes per face
1944 for each of the faces of the nfaced elements.
1947 Simple example: 11 10 12
1948 +--------+-----+
1949 2 nfaced elements: /| |\ /|
1950 (1 7-faced / | | \ / |
1951 1 5-sided) / | | +9 |
1952 / | | /| |
1953 /7 | 8 / | |
1954 +-----------+/ | | |
1955 | |5 | |4 | |6
1956 | +-----|--+--|--+
1957 | / | \ | /
1958 | / | \|/3
1959 | / | +
1960 | / | /
1961 |/1 |2 /
1962 +-----------+/
1964 1. In USERD_get_gold_part_build_info:
1965 number_of_elements[Z_NFACED] = 2
1966 .
1967 /|\
1968 |
1969 2. In USERD_get_part_elements_by_type:
1970 length of conn_array will be: 2 x 1
1971 for element_type of Z_NFACED:
1972 conn_array[0][0] = 7 (for the 7-faced element)
1973 conn_array[1][0] = 5 (for the 5-faced element)
1975 ==
1976 Sum 12 <---------+
1977 |
1978 3. In USERD_get_faced_nodes_per_face: |
1979 length of nfaced_npf_array will be: 12
1981 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
1982 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
1983 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
1984 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
1985 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
1986 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
1987 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
1989 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
1990 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
1991 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
1992 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
1993 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
1995 ==
1996 Sum 48 <-------------+
1997 |
1998 4. In this function: |
1999 length of the nfaced_conn_array will be: 48
2001 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2002 nsided_conn_array[1] = 8
2003 nsided_conn_array[2] = 9
2004 nsided_conn_array[3] = 10
2005 nsided_conn_array[4] = 11
2007 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2008 nsided_conn_array[6] = 5
2009 nsided_conn_array[7] = 4
2010 nsided_conn_array[8] = 3
2011 nsided_conn_array[9] = 2
2013 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2014 nsided_conn_array[11] = 2
2015 nsided_conn_array[12] = 8
2016 nsided_conn_array[13] = 7
2018 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2019 nsided_conn_array[15] = 1
2020 nsided_conn_array[16] = 7
2021 nsided_conn_array[17] = 11
2023 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2024 nsided_conn_array[19] = 5
2025 nsided_conn_array[20] = 11
2026 nsided_conn_array[21] = 10
2028 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2029 nsided_conn_array[23] = 3
2030 nsided_conn_array[24] = 9
2031 nsided_conn_array[25] = 8
2033 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2034 nsided_conn_array[27] = 4
2035 nsided_conn_array[28] = 10
2036 nsided_conn_array[29] = 9
2038 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2039 nsided_conn_array[32] = 12
2040 nsided_conn_array[32] = 10
2042 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2043 nsided_conn_array[34] = 4
2044 nsided_conn_array[35] = 6
2046 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2047 nsided_conn_array[37] = 4
2048 nsided_conn_array[38] = 10
2049 nsided_conn_array[39] = 12
2051 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2052 nsided_conn_array[41] = 6
2053 nsided_conn_array[42] = 12
2054 nsided_conn_array[43] = 9
2056 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2057 nsided_conn_array[45] = 3
2058 nsided_conn_array[46] = 9
2059 nsided_conn_array[47] = 10
2063 --------------------------------------------------------------------
2064 USERD_get_nfaced_nodes_per_face -
2066 Description:
2067 -----------
2068 Gets the array containing the number of nodes per face for each face
2069 of the nfaced elements.
2071 Specification:
2072 -------------
2073 int USERD_get_nfaced_nodes_per_face(int part_number,
2074 int *nfaced_npf_array)
2076 Returns:
2077 -------
2078 Z_OK if successful
2079 Z_ERR if not successful
2081 Arguments:
2082 ---------
2083 (IN) part_number = the part number
2085 (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of
2086 nfaced elements
2088 (int array will have been allocated long enough
2089 to hold all the nodes_per_face values. Which is
2090 the sum of all the number of faces per element
2091 values in the conn_array of
2092 USERD_get_part_elements_by_type)
2094 Notes:
2095 -----
2096 * Will not be called unless there are some nfaced elements in the
2097 the part
2099 * Providing nfaced information to Ensight:
2101 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2102 polyhedral elements in the part.
2104 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2105 the number of faces per nfaced element. (as if connectivity
2106 length of an nfaced element is one)
2108 3. In this routine, provide the streamed number of nodes per face
2109 for each of the faces of the nfaced elements.
2112 Simple example: 11 10 12
2113 +--------+-----+
2114 2 nfaced elements: /| |\ /|
2115 (1 7-faced / | | \ / |
2116 1 5-sided) / | | +9 |
2117 / | | /| |
2118 /7 | 8 / | |
2119 +-----------+/ | | |
2120 | |5 | |4 | |6
2121 | +-----|--+--|--+
2122 | / | \ | /
2123 | / | \|/3
2124 | / | +
2125 | / | /
2126 |/1 |2 /
2127 +-----------+/
2129 1. In USERD_get_gold_part_build_info:
2130 number_of_elements[Z_NFACED] = 2
2131 .
2132 /|\
2133 |
2134 2. In USERD_get_part_elements_by_type:
2135 length of conn_array will be: 2 x 1
2136 for element_type of Z_NFACED:
2137 conn_array[0][0] = 7 (for the 7-faced element)
2138 conn_array[1][0] = 5 (for the 5-faced element)
2140 ==
2141 Sum 12 <---------+
2142 |
2143 3. In this routine: |
2144 length of nfaced_npf_array will be: 12
2146 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2147 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2148 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2149 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2150 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2151 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2152 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2154 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2155 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2156 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2157 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2158 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2160 ==
2161 Sum 48 <-------------+
2162 |
2163 4. In USERD_get_nfaced_conn: |
2164 length of the nfaced_conn_array will be: 48
2166 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2167 nsided_conn_array[1] = 8
2168 nsided_conn_array[2] = 9
2169 nsided_conn_array[3] = 10
2170 nsided_conn_array[4] = 11
2172 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2173 nsided_conn_array[6] = 5
2174 nsided_conn_array[7] = 4
2175 nsided_conn_array[8] = 3
2176 nsided_conn_array[9] = 2
2178 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2179 nsided_conn_array[11] = 2
2180 nsided_conn_array[12] = 8
2181 nsided_conn_array[13] = 7
2183 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2184 nsided_conn_array[15] = 1
2185 nsided_conn_array[16] = 7
2186 nsided_conn_array[17] = 11
2188 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2189 nsided_conn_array[19] = 5
2190 nsided_conn_array[20] = 11
2191 nsided_conn_array[21] = 10
2193 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2194 nsided_conn_array[23] = 3
2195 nsided_conn_array[24] = 9
2196 nsided_conn_array[25] = 8
2198 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2199 nsided_conn_array[27] = 4
2200 nsided_conn_array[28] = 10
2201 nsided_conn_array[29] = 9
2203 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2204 nsided_conn_array[32] = 12
2205 nsided_conn_array[32] = 10
2207 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2208 nsided_conn_array[34] = 4
2209 nsided_conn_array[35] = 6
2211 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2212 nsided_conn_array[37] = 4
2213 nsided_conn_array[38] = 10
2214 nsided_conn_array[39] = 12
2216 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2217 nsided_conn_array[41] = 6
2218 nsided_conn_array[42] = 12
2219 nsided_conn_array[43] = 9
2221 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2222 nsided_conn_array[45] = 3
2223 nsided_conn_array[46] = 9
2224 nsided_conn_array[47] = 10
2229 --------------------------------------------------------------------
2230 USERD_get_node_label_status
2232 Description:
2233 -----------
2234 Answers the question as to whether node labels will be provided.
2236 Specification:
2237 -------------
2238 int USERD_get_node_label_status( void )
2240 Returns:
2241 -------
2242 TRUE if node labels will be provided
2243 FALSE if node labels will NOT be provided
2245 Arguments:
2246 ---------
2247 none
2249 Notes:
2250 -----
2251 * Node ids are needed in order to do any node querying, or node
2252 labeling on-screen within EnSight.
2254 * Prior to API 2.01:
2255 -----------------
2256 For unstructured parts, you can read them from your file if
2257 available, or can assign them, etc. They need to be unique
2258 per part, and are often unique per model. They must also be
2259 positive numbers greater than zero.
2261 USERD_get_part_node_ids is used to obtain the ids, if the
2262 status returned here is TRUE.
2264 (Unlike API 1.0, where the connectivity of elements had to be
2265 according to the node ids - API 2.0's element connectivities
2266 are not affected either way by the status here.)
2268 For structured parts, EnSight will assign ids if you return a
2269 status of TRUE here. You cannot assign them yourself!!
2271 * Starting at API 2.01:
2272 --------------------
2273 For both unstructured and structured parts, you can read them
2274 from your file if available, or can assign them, etc. They need
2275 to be unique per part, and are often unique per model. They must
2276 also be positive numbers greater than zero.
2278 USERD_get_part_node_ids is used to obtain the ids, if the
2279 status returned here is TRUE.
2281 * Will call USERD_get_part_node_ids for each part if this routine
2282 returns TRUE.
2284 --------------------------------------------------------------------
2285 USERD_get_nsided_conn -
2287 Description:
2288 -----------
2289 Gets the array containing the connectivity of nsided elements
2291 Specification:
2292 -------------
2293 int USERD_get_nsided_conn(int part_number,
2294 int *nsided_conn_array)
2296 Returns:
2297 -------
2298 Z_OK if successful
2299 Z_ERR if not successful
2301 Arguments:
2302 ---------
2303 (IN) part_number = the part number
2305 (OUT) nsided_conn_array = 1D array of nsided connectivies
2307 (int array will have been allocated long enough
2308 to hold all the nsided connectivities. Which is
2309 the sum of all the nodes_per_element values in
2310 the conn_array of USERD_get_part_elements_by_type)
2313 Notes:
2314 -----
2315 * Will not be called unless there are some nsided elements in the the part.
2317 * Providing nsided information to Ensight:
2319 1. In USERD_get_gold_part_build_info, provide the number of nsided
2320 elements in the part.
2322 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2323 the number of nodes per nsided element. (as if connectivity
2324 length of an nsided element is one)
2326 3. In this routine, provide the streamed connectivities for each of the
2327 nsided elements.
2330 Simple example: 5 6
2331 +--------+
2332 3 nsided elements: /| \
2333 (1 4-sided / | \
2334 1 3-sided / | \
2335 1 7-sided) / | \ 7
2336 /3 |4 +
2337 +-----+ |
2338 | | |
2339 | | |8
2340 | | +
2341 | | /
2342 | | /
2343 | | /
2344 |1 |2 /9
2345 +-----+--------+
2347 1. In USERD_get_gold_part_build_info:
2348 number_of_elements[Z_NSIDED] = 3
2349 .
2350 /|\
2351 |
2352 2. In USERD_get_part_elements_by_type:
2353 length of conn_array will be: 3 x 1
2355 for element_type of Z_NSIDED:
2356 conn_array[0][0] = 4 (for the 4-sided element)
2357 conn_array[1][0] = 3 (for the 3-sided element)
2358 conn_array[2][0] = 7 (for the 7-sided element)
2360 Sum ===
2361 14 <---------+
2362 |
2363 3. In this routine: |
2364 length of nsided_conn_array will be: 14
2366 nsided_conn_array[0] = 1 (connectivity of 4-sided element)
2367 nsided_conn_array[1] = 2
2368 nsided_conn_array[2] = 4
2369 nsided_conn_array[3] = 3
2371 nsided_conn_array[4] = 3 (connectivity of 3-sided element)
2372 nsided_conn_array[5] = 4
2373 nsided_conn_array[6] = 5
2375 nsided_conn_array[7] = 2 (connectivity of 7-sided element)
2376 nsided_conn_array[8] = 9
2377 nsided_conn_array[9] = 8
2378 nsided_conn_array[10] = 7
2379 nsided_conn_array[11] = 6
2380 nsided_conn_array[12] = 5
2381 nsided_conn_array[13] = 4
2386 --------------------------------------------------------------------
2387 USERD_get_num_of_time_steps
2389 Description:
2390 -----------
2391 Gets the number of time steps of data available for desired timeset.
2393 Specification:
2394 -------------
2395 int USERD_get_num_of_time_steps( int timeset_number )
2397 Returns:
2398 -------
2399 Number of time steps in timeset (>0 if okay, <=0 if problems).
2401 Arguments:
2402 ---------
2403 (IN) timeset number = the timeset number
2405 For example: If USERD_get_number_of_timesets
2406 returns 2, the valid
2407 timeset_number's would be 1 and 2
2409 Notes:
2410 -----
2411 * This should be >= 1 1 indicates a static model
2412 >1 indicates a transient model
2414 * Num_time_steps[timeset_number] would be set here
2418 --------------------------------------------------------------------
2419 USERD_get_number_of_files_in_dataset
2421 Description:
2422 -----------
2423 Get the total number of files in the dataset. Used for the
2424 dataset query option within EnSight.
2426 Specification:
2427 -------------
2428 int USERD_get_number_of_files_in_dataset( void )
2430 Returns:
2431 -------
2432 The total number of files in the dataset.
2434 Arguments:
2435 ---------
2436 none
2438 Notes:
2439 -----
2440 * You can be as complete as you want about this. If you don't
2441 care about the dataset query option, return a value of 0
2442 If you only want certain files, you can just include them. But,
2443 you will need to supply the info in USERD_get_dataset_query_file_info
2444 for each file you include here.
2446 * Num_dataset_files would be set here
2449 --------------------------------------------------------------------
2450 USERD_get_number_of_material_sets -
2452 Description:
2453 -----------
2454 Get the number of material sets in the model
2456 Specification:
2457 -------------
2458 int USERD_get_number_of_material_sets( void )
2461 Returns:
2462 -------
2463 Num_material_sets = number of material sets
2464 (Zero would indicate that you have no materials
2465 to deal with in the model)
2467 or
2469 -1 if an error condition
2471 Arguments:
2472 ---------
2473 none
2475 Notes:
2476 -----
2477 * You may want to keep this as a global for use in other routines.
2479 ###############################################################
2480 NOTE: For EnSight 7.6, only one material set is supported
2481 within EnSight.
2482 Thus the only valid returns here are:
2483 0 (no materials)
2484 1 (for the one material set allowed)
2485 or -1 (if an error)
2487 If the casefile has more than this, this reader will
2488 read them, but EnSight will issue an error message and
2489 choke on them!
2490 ###############################################################
2492 ================================================================
2493 A very simple explanatory example, to use as a reference for the
2494 materials routines:
2496 Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials.
2497 Most of the model is material 1, but the top left corner is material 9 -
2498 basically as shown:
2501 *--------*--------*--------*
2502 | | / | |
2503 | Mat 9 / | |
2504 | | / | |
2505 | |/ | |
2506 | e7 / e8 | e9 |
2507 | /| | |
2508 | / | | |
2509 | / | | |
2510 *----/---*--------*--------*
2511 | / | | |
2512 | / | | |
2513 | / | Mat 1 |
2514 |/ | | |
2515 | e4 | e5 | e6 |
2516 | | | |
2517 | | | |
2518 | | | |
2519 *--------*--------*--------*
2520 | | | |
2521 | | | |
2522 | | | |
2523 | | | |
2524 | e1 | e2 | e3 |
2525 | | | |
2526 | | | |
2527 | | | |
2528 *--------*--------*--------*
2531 Thus, in this routine, set:
2532 Num_material_sets = 1
2534 In USERD_get_matf_set_info, set:
2535 mat_set_ids[0] = 1
2536 mat_set_name[0] = "Material Set 1" (or whatever name desired)
2538 In USERD_get_number_of_materials, input would be set_index = 0, and
2539 would need to set:
2540 Num_materials[0] = 2
2542 For simplicity, the ids and descriptions that would be returned in
2543 USERD_get_matf_var_info could be:
2544 mat_ids[0] = 1
2545 mat_ids[1] = 9
2546 mat_desc[0] = "mat 1" (or whatever desired)
2547 mat_desc[2] = "mat 9"
2549 The per element material ids list would need to be:
2551 material ids:
2552 -------------
2553 ids_list[0] = 1 (material id 1, for elem e1)
2554 ids_list[1] = 1 ( " e2)
2555 ids_list[2] = 1 ( " e3)
2556 ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4)
2557 ids_list[5] = 1 (material id 1, for elem e5)
2558 ids_list[5] = 1 ( " e6)
2559 ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7)
2560 ids_list[5] = -9 ( " e8)
2561 ids_list[5] = 1 (material id 1, for elem e9)
2563 Finally we need the mixed material ids list and the mixed materials values list,
2564 which would need to be:
2566 mixed-material ids:
2567 -------------------
2568 ==> 1 ids_list[0] = 2 (the -1 in the material variable points here,
2569 2 indicates that two materials are present)
2570 2 ids_list[1] = 1 (1st material is 1)
2571 3 ids_list[2] = 9 (2nd material is 9)
2572 4 ids_list[3] = -1 (negative of index into mixed-material val_list)
2573 ==> 5 ids_list[4] = 2 (the -5 in the material variable points here,
2574 2 indicates that two materials are present)
2575 6 ids_list[5] = 1 (1st material is 1)
2576 7 ids_list[6] = 9 (2nd material is 9)
2577 8 ids_list[7] = -3 (negative of index into mixed-material val_list)
2578 ==> 9 ids_list[8] = 2 etc.
2579 10 ids_list[9] = 1
2580 11 ids_list[10] = 9
2581 12 ids_list[11] = -5
2583 mixed-material values:
2584 ----------------------
2585 ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here,
2586 and this is the value for material 1)
2587 2 val_list[1] = 0.125 (the value for material 9)
2588 ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here)
2589 4 val_list[3] = 0.875
2590 ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here)
2591 6 val_list[5] = 0.125
2593 So, USERD_size_matf_data would need to return
2594 matf_size = 8, when called with set_id = 1
2595 part_id = 1
2596 wtyp = Z_QUA04
2597 mat_type = Z_MAT_INDEX
2599 matf_size = 12, when called with set_id = 1
2600 part_id = 1
2601 mat_type = Z_MIX_INDEX
2603 = 6, when called with set_id = 1
2604 part_id = 1
2605 mat_type = Z_MIX_VALUE
2607 And, USERD_load_matf_data would need to return:
2608 the int array ids_list as shown above when called with:
2609 set_id = 1
2610 part_id = 1
2611 wtyp = Z_QUA04
2612 mat_type = Z_MAT_INDEX (indicating id list).
2614 the int array ids_list as shown above when called with:
2615 set_id = 1
2616 part_id = 1
2617 mat_type = Z_MIX_INDEX (indicating id list).
2619 the float array val_list as shown above when called with:
2620 set_id = 1
2621 part_id = 1
2622 mat_type = Z_MIX_VALUE (indicating val list).
2625 -------------------------------------------------------------------------
2626 USERD_get_number_of_materials
2628 Description:
2629 -----------
2630 Gets the number of materials in the material set
2632 Specification:
2633 -------------
2634 int USERD_get_number_of_materials( int set_index )
2636 Returns:
2637 -------
2638 Num_materials[set_index] = Number of materials in the set
2639 0 indicates no materials information present
2640 -1 indicates an error
2641 Arguments:
2642 ---------
2643 (IN) set_index = the material set index (zero based)
2645 Notes:
2646 -----
2647 * See USERD_get_number_of_material_sets header for explanatory example
2648 * Will not be called if Num_material_sets is zero
2649 * You may want to keep this as a global for use in other routines.
2653 --------------------------------------------------------------------
2654 USERD_get_number_of_model_parts
2656 Description:
2657 -----------
2658 Gets the total number of unstructured and structured parts
2659 in the model, for which you can supply information.
2661 Specification:
2662 -------------
2663 int USERD_get_number_of_model_parts( void )
2665 Returns:
2666 -------
2667 Number of parts (>0 if okay, <=0 if problems).
2669 Arguments:
2670 ---------
2671 none
2673 Notes:
2674 -----
2675 * If going to have to read down through the parts in order to
2676 know how many, you may want to build a table of pointers to
2677 the various parts, so you can easily get to particular parts in
2678 later processes. If you can simply read the number of parts
2679 at the head of the file, then you would probably not build the
2680 table at this time.
2682 * This routine would set Numparts_available, which is equal to
2683 Num_unstructured_parts + Num_structured_blocks.
2687 --------------------------------------------------------------------
2688 USERD_get_number_of_timesets
2690 Description:
2691 -----------
2692 Gets the number of timesets used in the model.
2694 Specification:
2695 -------------
2696 int USERD_get_number_of_timesets( void )
2698 Returns:
2699 -------
2700 Number of timesets in the model
2702 Arguments:
2703 ---------
2704 none
2706 Notes:
2707 -----
2708 * Num_timesets would be set here
2710 * If you have a static model, both geometry and variables, you should
2711 return a value of zero.
2713 * If you have a transient model, then you should return one or more.
2715 For example:
2717 Geometry Variables No. of timesets
2718 --------- ------------------------------ ---------------
2719 static static 0
2720 static transient, all using same timeset 1
2722 transient transient, all using same timeset as geom 1
2724 static transient, using 3 different timesets 3
2726 transient transient, using 3 different timesets and
2727 none of them the same as the
2728 geometry timeset 4
2729 etc.
2731 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
2732 the timeset number to use
2733 for geometry in:
2734 USERD_get_geom_timeset_number
2736 Variables can use the same timeset as the geometry, or can use
2737 other timesets. More than one variable can use the same timeset.
2739 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
2740 variable 1 provided at these same five steps
2741 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
2743 This routine should return a value of 2, because only
2744 two different timesets are needed. Timeset 1 would be for the
2745 geometry and variable 1 (they both use it). Timeset 2 would
2746 be for variable 2, which needs its own in this case.
2752 --------------------------------------------------------------------
2753 USERD_get_number_of_variables
2755 Description:
2756 -----------
2757 Get the number of variables for which you will be providing info.
2759 Specification:
2760 -------------
2761 int USERD_get_number_of_variables( void )
2763 Returns:
2764 -------
2765 Number of variables (includes constant, scalar, vector and tensor types)
2766 (>=0 if okay, <0 if problem)
2768 Arguments:
2769 ---------
2770 none
2772 Notes:
2773 -----
2774 *****************************************************************
2775 * Variable numbers, by which references will be made, are implied
2776 here. If you say there are 3 variables, the variable numbers
2777 will be 1, 2, and 3.
2778 *****************************************************************
2780 * Num_variables would be set here
2784 --------------------------------------------------------------------
2785 USERD_get_part_coords
2787 Description:
2788 -----------
2789 Gets the coordinates for an unstructured part.
2791 Specification:
2792 -------------
2793 int USERD_get_part_coords(int part_number, float **coord_array)
2795 Returns:
2796 -------
2797 Z_OK if successful
2798 Z_ERR if not successful
2800 Arguments:
2801 ---------
2802 (IN) part_number = The part number
2803 (1-based index of part table, namely:
2805 1 ... Numparts_available.
2807 It is NOT the part_id that
2808 is loaded in USERD_get_gold_part_build_info)
2810 (OUT) coord_array = 2D float array which contains,
2811 x,y,z coordinates of each node
2812 in the part.
2814 (IMPORTANT: The second dimension of this aray is 1-based!!!)
2816 (Array will have been allocated
2817 3 by (number_of_nodes + 1) for the part
2818 long - see USERD_get_gold_part_build_info)
2821 ex) If number_of_nodes = 100
2822 as obtained in:
2823 USERD_get_gold_part_build_info
2825 Then the allocated dimensions of the
2826 pointer sent to this routine will be:
2827 coord_array[3][101]
2829 Ignore the coord_array[0][0]
2830 coord_array[1][0]
2831 coord_array[2][0] locations and start
2832 the node coordinates at:
2833 coord_array[0][1]
2834 coord_array[1][1]
2835 coord_array[2][1]
2837 coord_array[0][2]
2838 coord_array[1][2]
2839 coord_array[2][2]
2841 etc.
2843 Notes:
2844 -----
2845 * Not called unless Num_unstructured_parts is > 0
2847 * Will be based on Current_time_step
2850 --------------------------------------------------------------------
2851 USERD_get_part_element_ids_by_type
2853 Description:
2854 -----------
2855 Gets the ids for the elements of a particular type for an unstructured
2856 or structured part.
2858 Specification:
2859 -------------
2860 int USERD_get_part_element_ids_by_type(int part_number,
2861 int element_type,
2862 int *elemid_array)
2864 Returns:
2865 -------
2866 Z_OK if successful
2867 Z_ERR if not successful
2869 Arguments:
2870 ---------
2871 (IN) part_number = The part number
2872 (1-based index of part table, namely:
2874 1 ... Numparts_available.
2876 It is NOT the part_id that
2877 is loaded in USERD_get_gold_part_build_info)
2879 (IN) element_type = One of the following (See global_extern.h)
2880 Z_POINT node point element
2881 Z_BAR02 2 node bar
2882 Z_BAR03 3 node bar
2883 Z_TRI03 3 node triangle
2884 Z_TRI06 6 node triangle
2885 Z_QUA04 4 node quad
2886 Z_QUA08 8 node quad
2887 Z_TET04 4 node tetrahedron
2888 Z_TET10 10 node tetrahedron
2889 Z_PYR05 5 node pyramid
2890 Z_PYR13 13 node pyramid
2891 Z_PEN06 6 node pentahedron
2892 Z_PEN15 15 node pentahedron
2893 Z_HEX08 8 node hexahedron
2894 Z_HEX20 20 node hexahedron
2896 Z_G_POINT ghost node point element
2897 Z_G_BAR02 2 node ghost bar
2898 Z_G_BAR03 3 node ghost bar
2899 Z_G_TRI03 3 node ghost triangle
2900 Z_G_TRI06 6 node ghost triangle
2901 Z_G_QUA04 4 node ghost quad
2902 Z_G_QUA08 8 node ghost quad
2903 Z_G_TET04 4 node ghost tetrahedron
2904 Z_G_TET10 10 node ghost tetrahedron
2905 Z_G_PYR05 5 node ghost pyramid
2906 Z_G_PYR13 13 node ghost pyramid
2907 Z_G_PEN06 6 node ghost pentahedron
2908 Z_G_PEN15 15 node ghost pentahedron
2909 Z_G_HEX08 8 node ghost hexahedron
2910 Z_G_HEX20 20 node ghost hexahedron
2912 (OUT) elemid_array = 1D array containing id of each
2913 element of the type.
2915 (Array will have been allocated
2916 number_of_elements of the type long)
2918 ex) If number_of_elements[Z_TRI03] = 25
2919 number_of_elements[Z_QUA04] = 100
2920 number_of_elements[Z_HEX08] = 30
2921 as obtained in:
2922 USERD_get_gold_part_build_info
2924 Then the allocated dimensions available
2925 for this routine will be:
2926 conn_array[25] when called with Z_TRI03
2928 conn_array[100] when called with Z_QUA04
2930 conn_array[30] when called with Z_HEX08
2932 Notes:
2933 -----
2934 * Not called unless element label status is set to TRUE in
2935 USERD_get_element_label_status
2937 * Will be based on Current_time_step
2941 --------------------------------------------------------------------
2942 USERD_get_part_elements_by_type
2944 Description:
2945 -----------
2946 Gets the connectivities for the elements of a particular type in an
2947 unstructured part
2949 Specification:
2950 -------------
2951 int USERD_get_part_elements_by_type(int part_number,
2952 int element_type,
2953 int **conn_array)
2955 Returns:
2956 -------
2957 Z_OK if successful
2958 Z_ERR if not successful
2960 Arguments:
2961 ---------
2962 (IN) part_number = The part number
2963 (1-based index of part table, namely:
2965 1 ... Numparts_available.
2967 It is NOT the part_id that
2968 is loaded in USERD_get_gold_part_build_info)
2970 (IN) element_type = One of the following (See global_extern.h)
2971 Z_POINT node point element
2972 Z_BAR02 2 node bar
2973 Z_BAR03 3 node bar
2974 Z_TRI03 3 node triangle
2975 Z_TRI06 6 node triangle
2976 Z_QUA04 4 node quad
2977 Z_QUA08 8 node quad
2978 Z_TET04 4 node tetrahedron
2979 Z_TET10 10 node tetrahedron
2980 Z_PYR05 5 node pyramid
2981 Z_PYR13 13 node pyramid
2982 Z_PEN06 6 node pentahedron
2983 Z_PEN15 15 node pentahedron
2984 Z_HEX08 8 node hexahedron
2985 Z_HEX20 20 node hexahedron
2987 Z_G_POINT ghost node point element
2988 Z_G_BAR02 2 node ghost bar
2989 Z_G_BAR03 3 node ghost bar
2990 Z_G_TRI03 3 node ghost triangle
2991 Z_G_TRI06 6 node ghost triangle
2992 Z_G_QUA04 4 node ghost quad
2993 Z_G_QUA08 8 node ghost quad
2994 Z_G_TET04 4 node ghost tetrahedron
2995 Z_G_TET10 10 node ghost tetrahedron
2996 Z_G_PYR05 5 node ghost pyramid
2997 Z_G_PYR13 13 node ghost pyramid
2998 Z_G_PEN06 6 node ghost pentahedron
2999 Z_G_PEN15 15 node ghost pentahedron
3000 Z_G_HEX08 8 node ghost hexahedron
3001 Z_G_HEX20 20 node ghost hexahedron
3004 (OUT) conn_array = 2D array containing connectivity
3005 of each element of the type.
3007 (Array will have been allocated
3008 num_of_elements of the type by
3009 connectivity length of the type)
3011 ex) If number_of_elements[Z_TRI03] = 25
3012 number_of_elements[Z_QUA04] = 100
3013 number_of_elements[Z_HEX08] = 30
3014 as obtained in:
3015 USERD_get_gold_part_build_info
3017 Then the allocated dimensions available
3018 for this routine will be:
3019 conn_array[25][3] when called with Z_TRI03
3021 conn_array[100][4] when called with Z_QUA04
3023 conn_array[30][8] when called with Z_HEX08
3025 Notes:
3026 -----
3027 * Not called unless Num_unstructured_parts is > 0
3029 * Will be based on Current_time_step
3032 --------------------------------------------------------------------
3033 USERD_get_part_node_ids
3035 Description:
3036 -----------
3037 Gets the node ids of an unstructured or structured part.
3039 Specification:
3040 -------------
3041 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
3043 Returns:
3044 -------
3045 Z_OK if successful
3046 Z_ERR if not successful
3048 Arguments:
3049 ---------
3050 (IN) part_number = The part number
3051 (1-based index of part table, namely:
3053 1 ... Numparts_available.
3055 It is NOT the part_id that
3056 is loaded in USERD_get_gold_part_build_info)
3058 (OUT) nodeid_array = 1D array containing node ids of
3059 each node in the part.
3061 (IMPORTANT: This array is 1-based!!!)
3063 (Array will have been allocated
3064 (number_of_nodes + 1) for the part long
3065 see USERD_get_gold_part_build_info)
3067 ex) If number_of_nodes = 100
3068 as obtained in:
3069 USERD_get_gold_part_build_info
3071 Then the allocated dimensions of the
3072 pointer sent to this routine will be:
3073 nodeid_array[101]
3075 Ignore the nodeid_array[0] location and start
3076 the node ids at:
3077 nodeid_array[1]
3079 nodeid_array[2]
3081 etc.
3083 Notes:
3084 -----
3085 * Not called unless node label status is TRUE, as returned from
3086 USERD_get_node_label_status
3088 * Will be based on Current_time_step
3090 * The ids are purely labels, used when displaying or querying node ids.
3091 However, any node id < 0 will never be displayed
3094 --------------------------------------------------------------------
3095 USERD_get_reader_descrip
3097 Description:
3098 -----------
3099 Gets the description of the reader, so gui can give more info
3101 Specification:
3102 -------------
3103 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
3105 Returns:
3106 -------
3107 Z_OK if successful
3108 Z_ERR if not successful
3110 Arguments:
3111 ---------
3112 (OUT) descrip = the description of the reader (max length is MAXFILENP,
3113 which is 255)
3115 Notes:
3116 -----
3117 * OPTIONAL ROUTINE! You can have it or not.
3121 --------------------------------------------------------------------
3122 USERD_get_reader_version
3124 Description:
3125 -----------
3126 Gets the version number of the user defined reader
3128 Specification:
3129 -------------
3130 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
3132 Returns:
3133 -------
3134 Z_OK if successful
3135 Z_ERR if not successful (and will assume is version 1.0)
3137 Arguments:
3138 ---------
3139 (OUT) version_number = the version number of the reader
3140 (max length is Z_MAX_USERD_NAME, which
3141 is 20)
3143 Notes:
3144 -----
3145 * This needs to be "2.000" or greater. Otherwise EnSight will assume
3146 this reader is API 1.0
3148 * should set it to "2.010" for this version of the API
3153 --------------------------------------------------------------------
3154 USERD_get_sol_times
3156 Description:
3157 -----------
3158 Get the solution times associated with each time step for
3159 desired timeset.
3161 Specification:
3162 -------------
3163 int USERD_get_sol_times(int timeset_number,
3164 float *solution_times)
3166 Returns:
3167 -------
3168 Z_OK if successful
3169 Z_ERR if not successful
3171 Arguments:
3172 ---------
3173 (IN) timeset_number = the timeset number
3175 For example: If USERD_get_number_of_timesets
3176 returns 2, the valid
3177 timeset_number's would be 1 and 2
3179 (OUT) solution_times = 1D array of solution times per time step
3181 (Array will have been allocated
3182 Num_time_steps[timeset_number] long)
3184 Notes:
3185 -----
3186 * The solution times must be non-negative and increasing.
3190 --------------------------------------------------------------------
3191 USERD_get_timeset_description -
3193 Description:
3194 -----------
3195 Get the description to associate with the desired timeset.
3197 Specification:
3198 -------------
3199 int USERD_get_timeset_description(int timeset_number,
3200 char timeset_description[Z_BUFL])
3202 Returns:
3203 -------
3204 Z_OK if successful
3205 Z_ERR if not successful
3207 Arguments:
3208 ---------
3209 (IN) timeset_number = the timeset number
3211 For example: If USERD_get_number_of_timesets
3212 returns 2, the valid
3213 timeset_number's would be 1 and 2
3215 (OUT) timeset_description = timeset description string
3218 Notes:
3219 -----
3220 * A string of NULLs is valid for timeset_description
3225 --------------------------------------------------------------------
3226 USERD_get_var_by_component
3228 Description:
3229 -----------
3230 Gets the values of a variable component. Both unstructured and structured
3231 parts use this routine.
3233 if Z_PER_NODE:
3234 Get the component value at each node for a given variable in the part.
3236 or if Z_PER_ELEM:
3237 Get the component value at each element of a specific part and type
3238 for a given variable.
3240 Specification:
3241 -------------
3242 int USERD_get_var_by_component(int which_variable,
3243 int which_part,
3244 int var_type,
3245 int which_type,
3246 int imag_data,
3247 int component,
3248 float *var_array)
3250 Returns:
3251 -------
3252 Z_OK if successful
3253 Z_ERR if not successful
3255 or: Z_UNDEF, in which case you need not load any values into var_array
3258 Arguments:
3259 ---------
3260 (IN) which_variable = The variable number
3262 (IN) which_part Since EnSight Version 7.4
3263 -------------------------
3264 = The part number
3266 (1-based index of part table, namely:
3268 1 ... Numparts_available.
3270 It is NOT the part_id that
3271 is loaded in USERD_get_gold_part_build_info)
3273 Prior to EnSight Version 7.4
3274 ----------------------------
3275 = The part id This is the part_id label loaded
3276 in USERD_get_gold_part_build_info.
3277 It is NOT the part table index.
3279 (IN) var_type = Z_SCALAR
3280 Z_VECTOR
3281 Z_TENSOR (symmetric tensor)
3282 Z_TENSOR9 (asymmetric tensor)
3284 (IN) which_type
3286 if Z_PER_NODE: Not used
3288 if Z_PER_ELEM: = The element type
3289 Z_POINT node point element
3290 Z_BAR02 2 node bar
3291 Z_BAR03 3 node bar
3292 Z_TRI03 3 node triangle
3293 Z_TRI06 6 node triangle
3294 Z_QUA04 4 node quad
3295 Z_QUA08 8 node quad
3296 Z_TET04 4 node tetrahedron
3297 Z_TET10 10 node tetrahedron
3298 Z_PYR05 5 node pyramid
3299 Z_PYR13 13 node pyramid
3300 Z_PEN06 6 node pentahedron
3301 Z_PEN15 15 node pentahedron
3302 Z_HEX08 8 node hexahedron
3303 Z_HEX20 20 node hexahedron
3305 Z_G_POINT ghost node point element
3306 Z_G_BAR02 2 node ghost bar
3307 Z_G_BAR03 3 node ghost bar
3308 Z_G_TRI03 3 node ghost triangle
3309 Z_G_TRI06 6 node ghost triangle
3310 Z_G_QUA04 4 node ghost quad
3311 Z_G_QUA08 8 node ghost quad
3312 Z_G_TET04 4 node ghost tetrahedron
3313 Z_G_TET10 10 node ghost tetrahedron
3314 Z_G_PYR05 5 node ghost pyramid
3315 Z_G_PYR13 13 node ghost pyramid
3316 Z_G_PEN06 6 node ghost pentahedron
3317 Z_G_PEN15 15 node ghost pentahedron
3318 Z_G_HEX08 8 node ghost hexahedron
3319 Z_G_HEX20 20 node ghost hexahedron
3321 (IN) imag_data = TRUE if imag component
3322 FALSE if real component
3324 (IN) component = The component: (0 if Z_SCALAR)
3325 (0 - 2 if Z_VECTOR)
3326 (0 - 5 if Z_TENSOR)
3327 (0 - 8 if Z_TENSOR9)
3329 * 6 Symmetric Indicies, 0:5 *
3330 * ---------------------------- *
3331 * | 11 12 13 | | 0 3 4 | *
3332 * | | | | *
3333 * T = | 22 23 | = | 1 5 | *
3334 * | | | | *
3335 * | 33 | | 2 | *
3338 * 9 General Indicies, 0:8 *
3339 * ---------------------------- *
3340 * | 11 12 13 | | 0 3 4 | *
3341 * | | | | *
3342 * T = | 21 22 23 | = | 6 1 5 | *
3343 * | | | | *
3344 * | 31 32 33 | | 7 8 2 | *
3346 (OUT) var_array
3348 -----------------------------------------------------------------------
3349 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
3350 -----------------------------------------------------------------------
3352 if Z_PER_NODE: = 1D array containing variable component value
3353 for each node.
3355 (Array will have been allocated
3356 (number_of_nodes + 1) long)
3358 Info stored in this fashion:
3359 var_array[0] = not used
3360 var_array[1] = var component for node 1 of part
3361 var_array[2] = var_component for node 2 of part
3362 var_array[3] = var_component for node 3 of part
3363 etc.
3365 if Z_PER_ELEM: = 1D array containing variable component
3366 value for each element of a particular
3367 part and type.
3369 (Array will have been allocated
3370 (number_of_elements[which_part][which_type] + 1)
3371 long. See USERD_get_gold_part_build_info)
3373 Info stored in this fashion:
3374 var_array[1] = var component for elem 1 (of part and type)
3375 var_array[2] = var component for elem 2 (of part and type)
3376 var_array[3] = var component for elem 3 (of part and type)
3377 etc.
3379 Notes:
3380 -----
3381 * Not called unless Num_variables is > 0
3383 * The per_node or per_elem classification must be obtainable from the
3384 variable number (a var_classify array needs to be retained)
3386 * Will be based on Current_time_step
3388 * If the variable is not defined for this part, simply return with a
3389 value of Z_UNDEF. EnSight will treat the variable as undefined for
3390 this part.
3393 --------------------------------------------------------------------
3394 USERD_get_var_value_at_specific
3396 Description:
3397 -----------
3398 if Z_PER_NODE:
3399 Get the value of a particular variable at a particular node in a
3400 particular part at a particular time.
3402 or if Z_PER_ELEM:
3403 Get the value of a particular variable at a particular element of
3404 a particular type in a particular part at a particular time.
3407 Specification:
3408 -------------
3409 int USERD_get_var_value_at_specific(int which_var,
3410 int which_node_or_elem,
3411 int which_part,
3412 int which_elem_type,
3413 int time_step,
3414 float values[3],
3415 int imag_data)
3417 Returns:
3418 -------
3419 Z_OK if successful
3420 Z_ERR if not successful
3422 Arguments:
3423 ---------
3424 (IN) which_var = The variable number
3426 (IN) which_node_or_elem
3428 If Z_PER_NODE:
3429 = The node number. This is not the id, but is
3430 the index of the global node
3431 list (1 based), or the block's
3432 node list (1 based).
3434 Thus, coord_array[1]
3435 coord_array[2]
3436 coord_array[3]
3437 . |
3438 . |which_node_or_elem index
3439 . ----
3442 If Z_PER_ELEM:
3443 = The element number. This is not the id, but is
3444 the element number index
3445 of the number_of_element array
3446 (see USERD_get_gold_part_build_info),
3447 or the block's element list (1 based).
3449 Thus, for which_part:
3450 conn_array[which_elem_type][0]
3451 conn_array[which_elem_type][1]
3452 conn_array[which_elem_type][2]
3453 . |
3454 . which_node_or_elem index
3455 . ----
3458 (IN) which_part Since EnSight Version 7.4
3459 -------------------------
3460 = The part number
3462 (1-based index of part table, namely:
3464 1 ... Numparts_available.
3466 It is NOT the part_id that
3467 is loaded in USERD_get_gold_part_build_info)
3469 Prior to EnSight Version 7.4
3470 ----------------------------
3471 = The part id This is the part_id label loaded
3472 in USERD_get_gold_part_build_info.
3473 It is NOT the part table index.
3476 (IN) which_elem_type
3478 If Z_PER_NODE, or block part:
3479 = Not used
3481 If Z_PER_ELEM:
3482 = The element type. This is the element type index
3483 of the number_of_element array
3484 (see USERD_get_gold_part_build_info)
3486 (IN) time_step = The time step
3488 (IN) imag_data = TRUE if want imaginary value.
3489 FALSE if want real value.
3491 (OUT) values = scalar or vector component value(s)
3492 values[0] = scalar or vector[0]
3493 values[1] = vector[1]
3494 values[2] = vector[2]
3497 Notes:
3498 -----
3499 * This routine is used in node querys over time (or element querys over
3500 time for Z_PER_ELEM variables). If these operations are not critical
3501 to you, this can be a dummy routine.
3503 * The per_node or per_elem classification must be obtainable from the
3504 variable number (a var_classify array needs to be retained)
3506 * The time step given is for the proper variable timeset.
3509 ----------------------------------------------------------------------
3510 USERD_load_matf_data
3512 Description:
3513 -----------
3514 Get the material id list, mixed-material id list, or
3515 mixed-material values list for the given material set and part (and
3516 element type if material id list)
3518 Specification:
3519 -------------
3520 int USERD_load_matf_data( int set_index,
3521 int part_id,
3522 int wtyp,
3523 int mat_type,
3524 int *ids_list,
3525 float *val_list)
3528 Returns:
3529 -------
3530 Z_OK if successful
3531 Z_ERR if not successful
3533 Arguments:
3534 ---------
3535 (IN) set_index = the material set index (zero based)
3537 (IN) part_id = the part number desired
3539 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3541 Z_POINT node point element
3542 Z_BAR02 2 node bar
3543 Z_BAR03 3 node bar
3544 Z_TRI03 3 node triangle
3545 Z_TRI06 6 node triangle
3546 Z_QUA04 4 node quad
3547 Z_QUA08 8 node quad
3548 Z_TET04 4 node tetrahedron
3549 Z_TET10 10 node tetrahedron
3550 Z_PYR05 5 node pyramid
3551 Z_PYR13 13 node pyramid
3552 Z_PEN06 6 node pentahedron
3553 Z_PEN15 15 node pentahedron
3554 Z_HEX08 8 node hexahedron
3555 Z_HEX20 20 node hexahedron
3556 Z_NSIDED nsided polygon
3557 Z_NFACED nfaced polyhedron
3559 Z_G_POINT ghost node point element
3560 Z_G_BAR02 2 node ghost bar
3561 Z_G_BAR03 3 node ghost bar
3562 Z_G_TRI03 3 node ghost triangle
3563 Z_G_TRI06 6 node ghost triangle
3564 Z_G_QUA04 4 node ghost quad
3565 Z_G_QUA08 8 node ghost quad
3566 Z_G_TET04 4 node ghost tetrahedron
3567 Z_G_TET10 10 node ghost tetrahedron
3568 Z_G_PYR05 5 node ghost pyramid
3569 Z_G_PYR13 13 node ghost pyramid
3570 Z_G_PEN06 6 node ghost pentahedron
3571 Z_G_PEN15 15 node ghost pentahedron
3572 Z_G_HEX08 8 node ghost hexahedron
3573 Z_G_HEX20 20 node ghost hexahedron
3574 Z_G_NSIDED ghost nsided polygon
3575 Z_G_NFACED ghost nfaced polyhedron
3577 (IN) mat_type = Z_MAT_INDEX for material ids list
3578 Z_MIX_INDEX for mixed-material ids list
3579 Z_MIX_VALUE for mixed-material values list
3581 (OUT) ids_list = If mat_type is Z_MAT_INDEX:
3582 ---------------------------
3583 1D material id list
3584 (Int array will have been allocated
3585 the appropriate size, as returned in
3586 USERD_size_matf_data for mat_type Z_MAT_INDEX)
3588 If mat_type is Z_MIX_INDEX:
3589 ---------------------------
3590 1D mixed-material id list
3591 (Int array will have been allocated
3592 the appropriate size, as returned in
3593 USERD_size_matf_data for mat_type Z_MIX_INDEX)
3595 (OUT) val_list = 1D mixed-materials values list
3596 (only used if mat_type is Z_MIX_VALUE)
3598 (Float array will have been allocated
3599 the appropriate size, as returned in
3600 USERD_size_matf_data for mat_type Z_MIX_VALUE)
3602 Notes:
3603 -----
3604 * See USERD_get_number_of_material_sets header for explanatory example
3605 * Will not be called if Num_material_sets is zero,
3606 or Num_materials[set_index] is zero,
3607 or the appropriate size from USERD_size_matf_data is zero
3611 --------------------------------------------------------------------
3612 USERD_set_filenames
3614 Description:
3615 -----------
3616 Receives the geometry and result filenames entered in the data
3617 dialog. The user written code will have to store and use these
3618 as needed. The user written code must manage its own files!!
3620 Specification:
3621 -------------
3622 int USERD_set_filenames(char filename_1[],
3623 char filename_2[],
3624 char the_path[],
3625 int swapbytes)
3627 Returns:
3628 -------
3629 Z_OK if successful
3630 Z_ERR if not successful
3632 Arguments:
3633 ---------
3634 (IN) filename_1 = the filename entered into the geometry
3635 field of the data dialog.
3637 (IN) filename_2 = the filename entered into the result
3638 field of the data dialog.
3639 (If the two_fields flag in USERD_get_name_of_reader
3640 is FALSE, this will be null string)
3642 (IN) the_path = the path info from the data dialog.
3643 Note: filename_1 and filename_2 have already
3644 had the path prepended to them. This
3645 is provided in case it is needed for
3646 filenames contained in one of the files
3648 (IN) swapbytes = TRUE if should swap bytes when reading data.
3649 = FALSE normally.
3651 Notes:
3652 -----
3653 * Since you must manage everything from the input that is entered in
3654 these data dialog fields, this is an important routine!
3656 * It may be that you will need to have an executive type file that contains
3657 info and other filenames within it, like EnSight6's case file.
3660 --------------------------------------------------------------------
3661 USERD_set_server_number
3663 Description:
3664 -----------
3665 Receives the server number of how many total servers.
3667 Specification:
3668 -------------
3669 int USERD_set_server_number(int cur_serv,
3670 int tot_servs)
3672 Returns:
3673 -------
3674 nothing
3676 Arguments:
3677 ---------
3678 (IN) cur_serv = the current server.
3680 (IN) tot_servs = the total number of servers.
3682 Notes:
3683 -----
3684 * Only useful if your user defined reader is being used with EnSight's
3685 Server-of-Server capability. And even then, it may or may not be
3686 something that you can take advantage of. If your data is already
3687 partitioned in some manner, such that you can access the proper
3688 portions using this information.
3690 For all non-SOS uses, this will simply be 1 of 1
3694 --------------------------------------------------------------------
3695 USERD_set_time_set_and_step
3697 Description:
3698 -----------
3699 Set the current time step in the desired timeset. All functions that
3700 need time, and that do not explicitly pass it in, will use the timeset
3701 and step set by this routine, if needed.
3703 Specification:
3704 -------------
3705 void USERD_set_time_set_and_step(int timeset_number,
3706 int time_step)
3708 Returns:
3709 -------
3710 nothing
3712 Arguments:
3713 ---------
3714 (IN) timeset_number = the timeset number (1 based).
3716 For example: If USERD_get_number_of_timesets
3717 returns 2, the valid timeset_number's
3718 would be 1 and 2.
3720 (IN) time_step = The current time step to set
3722 Notes:
3723 -----
3724 * Current_time_step and Current_timeset would be set here
3727 --------------------------------------------------------------------
3728 USERD_size_matf_data
3730 Description:
3731 -----------
3732 Get the length of the material id list, mixed-material id list, or
3733 mixed-material values list for the given material set and part (and
3734 element type if material id list)
3736 Specification:
3737 -------------
3738 int USERD_size_matf_data( int set_index,
3739 int part_id,
3740 int wtyp,
3741 int mat_type,
3742 int *matf_size)
3745 Returns:
3746 -------
3747 Z_OK if successful
3748 Z_ERR if not successful
3750 Arguments:
3751 ---------
3752 (IN) set_index = the material set index (zero based)
3754 (IN) part_id = the part number desired
3756 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3758 Z_POINT node point element
3759 Z_BAR02 2 node bar
3760 Z_BAR03 3 node bar
3761 Z_TRI03 3 node triangle
3762 Z_TRI06 6 node triangle
3763 Z_QUA04 4 node quad
3764 Z_QUA08 8 node quad
3765 Z_TET04 4 node tetrahedron
3766 Z_TET10 10 node tetrahedron
3767 Z_PYR05 5 node pyramid
3768 Z_PYR13 13 node pyramid
3769 Z_PEN06 6 node pentahedron
3770 Z_PEN15 15 node pentahedron
3771 Z_HEX08 8 node hexahedron
3772 Z_HEX20 20 node hexahedron
3773 Z_NSIDED nsided polygon
3774 Z_NFACED nfaced polyhedron
3776 Z_G_POINT ghost node point element
3777 Z_G_BAR02 2 node ghost bar
3778 Z_G_BAR03 3 node ghost bar
3779 Z_G_TRI03 3 node ghost triangle
3780 Z_G_TRI06 6 node ghost triangle
3781 Z_G_QUA04 4 node ghost quad
3782 Z_G_QUA08 8 node ghost quad
3783 Z_G_TET04 4 node ghost tetrahedron
3784 Z_G_TET10 10 node ghost tetrahedron
3785 Z_G_PYR05 5 node ghost pyramid
3786 Z_G_PYR13 13 node ghost pyramid
3787 Z_G_PEN06 6 node ghost pentahedron
3788 Z_G_PEN15 15 node ghost pentahedron
3789 Z_G_HEX08 8 node ghost hexahedron
3790 Z_G_HEX20 20 node ghost hexahedron
3791 Z_G_NSIDED ghost nsided polygon
3792 Z_G_NFACED ghost nfaced polyhedron
3794 (IN) mat_type = Z_MAT_INDEX for material ids list
3795 Z_MIX_INDEX for mixed-material ids list
3796 Z_MIX_VALUE for mixed-material values list
3798 (OUT) matf_size = the length of the material id list, or
3799 mixed-material id list, or
3800 mixed-material values list
3801 for the given material set and part number
3802 (and element type if Z_MAT_INDEX)
3804 Notes:
3805 -----
3806 * See USERD_get_number_of_material_sets header for explanatory example
3807 * Will not be called if Num_material_sets is zero, or
3808 Num_materials[set_index] is zero
3813 --------------------------------------------------------------------
3814 USERD_stop_part_building
3816 Description:
3817 -----------
3818 This routine called when the part building dialog is closed. It is
3819 provided in case you desire to release memory, etc. that was only needed
3820 during the part building process.
3822 Specification:
3823 -------------
3824 void USERD_stop_part_building( void )
3826 Returns:
3827 -------
3828 nothing
3830 Arguments:
3831 ---------
3832 none
3834 Notes:
3835 -----
3838 ---- end of doucment ----