[OpenFOAM-2.0.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_1.0
| blob | 6453be2655961e483172748fd93e4ab758410e89 |
1 README_USERD_1.0
2 ================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 1.0)
5 --------------------------------------
6 A user defined reader capability is included in EnSight which can allow
7 otherwise unsupported structured or unstructured data to be read. The user
8 defined reader capability utilizes dynamic shared libraries composed of
9 routines defined in this document but produced by you, the user, (or some
10 third party). This capability is currently available for dec, ibm, hp, sgi,
11 sun, linux, alpha linux, and NT servers.
13 Two versions of this API are available starting with EnSight Version 7.2. The
14 1.0 API (which was designed to be friendly to those producing it, but requires
15 more manipulation internally by EnSight) may be a little easier to
16 produce, but requires more memory and processing time. The 2.0 API is
17 considerably more efficient, and was designed more with that in mind. It
18 requires that all data be provided on a part basis.
20 If you already have a working 1.0 API reader and are happy with it - there is
21 probably no reason to modify it to the 2.0 API unless:
22 - you deal with large models and the memory use and load times are a
23 problem or
24 - you need tensor variable support or
25 - you need complex variable support or
26 - you need multiple timeset capability or
27 _ you want to provide your own "border" elements (as opposed to EnSight's
28 computation of them).
30 If you are producing a new reader, you should consider which will work best
31 for your needs.
34 API 1.0 (defined in this README_USERD_1.0 document)
35 =======
36 The original user defined reader API (used with EnSight Versions 6 through
37 7.1) will continue to be supported. (Note that there was a change in the way
38 that the libraries were made at version 7.1 of EnSight, but underlying code
39 was kept the same.) Thus, any readers that work with EnSight 7.1, should still
40 function with EnSight 7.2.
43 API 2.0 (defined in README_USERD_2.0 document)
44 =======
45 This new API has been defined to be more efficient and includes access to new
46 capabilities of EnSight 7.2. It lends itself closely to the EnSight "gold"
47 type format.
49 Some of its advantages are::
51 * Most intermediate temporary arrays have been eliminated, such that the user
52 defined routines write directly into internal part structures. This is a
53 considerable improvement in memory use, and improves speed as well since
54 far less memory need be allocated, initialized, etc.
56 * Parts are self contained. Coordinates, connectivity and all variables are
57 provided on a part basis. This eliminates the need for several global to
58 local coordinate mapping operations and the need for node id connectivity
59 hashing. This can greatly improve the speed at which models are loaded.
61 * Model extents can be provided directly, such that EnSight need not read
62 all the coordinate data at load time.
64 * Tensor variables are supported
66 * Complex variables are supported
68 * A routine is provided as EnSight exits, so cleanup operations such as
69 removing temporary files can be easily accomplished.
71 * Geometry and variables can be provided on different time lines.
73 * If your data format already provides boundary shell information, you can
74 use it instead of the "border" representation that EnSight would compute.
76 Further discussion on the philosophical differences between the two API's and
77 an efficiency comparison example can be found in the README_1.0_to_2.0 file.
78 This file also contains guidance on necessary changes to modify an existing
79 1.0 API to the new 2.0 API.
82 ****************************************************************************
83 Note: Several (1.0 API) user defined readers have been included with your
84 EnSight release and are configured by default. There are site- and
85 user-configurable options outlined in step 3 below. Please be aware
86 that these are "unsupported" readers, but many of them are being used
87 successfully.
88 ****************************************************************************
91 The process for producing a user defined reader is:
92 ---------------------------------------------------
93 1. Write code for all pertinent routines in the library (Unless someone else
94 has done this for you).
96 This is of course where the work is done by the user. The word
97 "pertinent" is used because depending on the nature of the data, some
98 of the routines in the library may be dummy routines.
100 The source code for a dummy library and for various other working or
101 sample libraries is copied from the installation CD during
102 installation. These will be located in directories under:
104 $ENSIGHT7_HOME/user_defined_src/readers
106 examples of API 1.0:
107 -------------------
108 Basic dummy routines provide skeleton for a new reader
109 $ENSIGHT7_HOME/user_defined_src/readers/dummy
111 Sample library which reads unstructured binary EnSight6 data
112 $ENSIGHT7_HOME/user_defined_src/readers/ensight6
114 Sample library which reads binary static plot3d data
115 $ENSIGHT7_HOME/user_defined_src/readers/plot3d
117 Reads binary LS-DYNA3D state database
118 $ENSIGHT7_HOME/user_defined_src/readers/ls-dyna3d
120 Reads FORTRAN binary Unstructured dytran data base
121 $ENSIGHT7_HOME/user_defined_src/readers/dytran
123 Reads FlowScience "flsgrf" flow3d data
124 $ENSIGHT7_HOME/user_defined_src/readers/flow3d
126 Reads Tecplot "plt" files
127 $ENSIGHT7_HOME/user_defined_src/readers/tecplot
129 Reads Common File Format data
130 $ENSIGHT7_HOME/user_defined_src/readers/cff
132 Reads Cobalt grid and picture/restart file data
133 $ENSIGHT7_HOME/user_defined_src/readers/cobalt
135 Reads binary Nastran OP2 data base
136 $ENSIGHT7_HOME/user_defined_src/readers/nastran
138 Reads binary and ascii cfx data
139 $ENSIGHT7_HOME/user_defined_src/readers/cfx4
141 Reads Exodus II data base
142 $ENSIGHT7_HOME/user_defined_src/readers/exodus
144 Reads Parallel Exodus data base
145 $ENSIGHT7_HOME/user_defined_src/readers/pxi
147 Reads FORTRAN binary SCRYU data
148 $ENSIGHT7_HOME/user_defined_src/readers/scryu
150 Reads binary and ascii STL data
151 $ENSIGHT7_HOME/user_defined_src/readers/stl
153 Reads Vectis data
154 $ENSIGHT7_HOME/user_defined_src/readers/vectis
156 You may find it useful to place your library source in this area as
157 well, but are not limited to this location.
159 * ===> The descriptions of each library routine and the order that the
160 routines are called, which is provided in this file, along with
161 the example libraries, should make it possible for you to produce
162 code for your own data reader.
165 2. Produce the dynamic shared library.
167 This is a compiling and loading process which varies according to
168 the type of machine you are on. In the user-defined-reader source
169 tree we have tried to isolate the machine dependent parts of the
170 build process using a set of files in the 'config' directory. In this
171 directory there is a configuration file for each platform on which
172 EnSight is supported. Before you can compile the installed readers
173 you should run the script called 'init' in the config directory.
175 i.e. (for UNIX)
176 cd config
177 ./init sgi_6.5_n64
178 cd ..
179 make
181 If you are compiling for Windows NT, there are two options. If you
182 have the Cygwin GNU utilities installed, you can use GNU make as for
183 Unix. Otherwise, there is a script called makeall.cmd which will
184 build all of the readers using nmake. The Makefiles in each reader
185 directory will work using either make or nmake.
187 i.e. (WIN32 Cygwin) (using nmake)
188 cd config cd config
189 sh init win32 cp win32 config
190 cd .. cd ..
191 mkdir lib
192 make makeall.cmd
194 If you have platform-specific portions of code in your reader, the
195 build system defines a set of flags which can be used within
196 #ifdef ... #endif regions in your source, as shown in the table
197 below.
199 Because the readers are now dynamically opened by EnSight, you may
200 have to include dependent libraries on your link-line to avoid having
201 unresolved symbols. If you are having problems with a reader, start
202 ensight as "ensight7 -readerdbg" and you will get feedback on any
203 problems encountered in loading a reader. If there are unresolved
204 symbols, you need to find the library which contains the missing
205 symbols and link it into your reader by adding it to the example
206 link commands below.
208 If you choose to use a different build environment for your reader,
209 you should take care to use compatible compilation flags to ensure
210 compatibilty with the EnSight executables, most notably on the SGI
211 and HP-UX 11.0 platforms, which should use the following flags:
213 sgi_6.2_o32: -mips2
214 sgi_6.2_n64: -mips4 -64
215 sgi_6.5_n32: -mips3
216 sgi_6.5_n64: -mips4 -64
217 hp_11.0_32: +DA2.0
218 hp_11.0_64: +DA2.0W
220 ______________________________________________________________________
221 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
222 | TYPE |------------------------------------------------------------|
223 | | LD COMMAND USED IN MAKEFILE |
224 ======================================================================
225 ______________________________________________________________________
226 | sgi | -DSGI | libuserd-X.so |
227 | |------------------------------------------------------------|
228 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
229 ----------------------------------------------------------------------
230 ______________________________________________________________________
231 | hp | -DHP | libuserd-X.sl |
232 | |------------------------------------------------------------|
233 | | ld -b -o libuserd-X.sl libuserd-X.o |
234 ----------------------------------------------------------------------
235 ______________________________________________________________________
236 | sun | -DSUN | libuserd-X.so |
237 | |------------------------------------------------------------|
238 | | ld -G -o libuserd-X.so libuserd-X.o |
239 ----------------------------------------------------------------------
240 ______________________________________________________________________
241 | dec | -DDEC | libuserd-X.so |
242 | |------------------------------------------------------------|
243 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
244 ----------------------------------------------------------------------
245 ______________________________________________________________________
246 | linux | -DLINUX | libuserd-X.so |
247 | |------------------------------------------------------------|
248 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
249 ----------------------------------------------------------------------
250 ______________________________________________________________________
251 | alpha | -DALINUX | libuserd-X.so |
252 | linux |------------------------------------------------------------|
253 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
254 ----------------------------------------------------------------------
255 ______________________________________________________________________
256 | ibm | -DIBM | libuserd-X.so |
257 | |------------------------------------------------------------|
258 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
259 ----------------------------------------------------------------------
261 Once you have created your library, you should place it in a directory
262 of your choice or in the standard reader location:
264 $ENSIGHT7_HOME/machines/$ENSIGHT7_ARCH/lib_readers
266 For example, if you created a reader for "mydata", you should create
267 the reader libuserd-mydata.so and place the file in your own reader
268 directory (see section 3 below) or in the standard location:
270 $ENSIGHT7_HOME/machines/$ENSIGHT7_ARCH/lib_readers/libuserd-mydata.so
273 3. By default EnSight will load all readers found in the directory:
275 $ENSIGHT7_HOME/machines/$ENSIGHT7_ARCH/lib_readers
277 Files with names "libuserd-X.so" (where X is a name unique to the reader)
278 are assumed to be user-defined readers.
280 There are two methods which can be used to supplement the default
281 behavior.
283 (1) A feature which is useful for site-level or user-level configuration
284 is the optional environment variable $ENSIGHT7_READER. This
285 variable directs EnSight to load all readers in the specified reader
286 directory (you should probably specify a full path) before loading
287 the built-in readers. If the same reader exists in both directories
288 (as determined by the name returned by USERD_get_name_of_reader(),
289 NOT by the filename), the locally configured reader will take
290 precedence.
292 (2) A useful feature for end-users is the use of the libuserd-devel
293 reader. EnSight will search for a reader named libuserd-devel.so
294 (.sl for HP or .dll for NT). This reader can exist anywhere in the
295 library path (see below) of the user. This is useful for an
296 individual actively developing a reader because the existence of a
297 libuserd-devel library will take precedence over any other library
298 which returns the same name from USERD_get_name_of_reader().
300 As an example, a site may install commonly used readers in a common
301 location, and users can set the ENSIGHT7_READER variable to access them:
303 setenv ENSIGHT7_READER /usr/local/lib/e7readers
305 A user working on a new reader may compile the reader and place it in
306 a directory specified by the library path:
308 cp libuserd-myreader.so ~/lib/libuserd-devel.so
309 setenv <librarypath> ~/lib:$<librarypath>
311 The user is responsible for correctly configuring the library path
312 variable in order to make use of the libuserd-devel feature. The
313 library environment variables used are:
315 Machine type Environment variable to set
316 ------------ ---------------------------
317 sgi LD_LIBRARY_PATH
318 dec LD_LIBRARY_PATH
319 sun LD_LIBRARY_PATH
320 linux LD_LIBRARY_PATH
321 alpha linux LD_LIBRARY_PATH
322 hp SHLIB_PATH
323 ibm LIBPATH
325 As always, EnSight support is available if you need it.
329 -------------------------------
330 Quick Index of Library Routines
331 -------------------------------
333 Generally Needed for UNSTRUCTURED data
334 --------------------------------------
335 USERD_get_number_of_global_nodes number of global nodes
336 USERD_get_global_coords global node coordinates
337 USERD_get_global_node_ids global node ids
338 USERD_get_element_connectivities_for_part part's element connectivites
339 USERD_get_element_ids_for_part part's element ids
340 USERD_get_scalar_values global scalar variables
341 USERD_get_vector_values global vector variables
344 Generally Needed for BLOCK data
345 -----------------------------------------
346 USERD_get_block_coords_by_component block coordinates
347 USERD_get_block_iblanking block iblanking values
348 USERD_get_block_scalar_values block scalar variables
349 USERD_get_block_vector_values_by_component block vector variables
352 Generally needed for either or both kinds of data
353 -------------------------------------------------
354 USERD_set_filenames filenames entered in GUI
355 USERD_set_time_step current time step
357 USERD_get_name_of_reader name of reader for GUI
358 USERD_get_number_of_files_in_dataset number of files in model
359 USERD_get_dataset_query_file_info info about each model file
360 USERD_get_changing_geometry_status changing geometry?
361 USERD_get_node_label_status node labels?
362 USERD_get_element_label_status element labels?
363 USERD_get_number_of_time_steps number of time steps
364 USERD_get_solution_times solution time values
365 USERD_get_description_lines file associated descrip lines
366 USERD_get_number_of_variables number of variables
367 USERD_get_variable_info variable type/descrip etc.
368 USERD_get_constant_value constant variable's value
369 USERD_get_number_of_model_parts number of model parts
370 USERD_get_part_build_info part type/descrip etc.
371 USERD_get_variable_value_at_specific node's or element's variable
372 value over time
374 USERD_stop_part_building cleanup routine
375 USERD_bkup archive routine
378 -------------------------
379 Order Routines are called
380 -------------------------
382 The various main operations are given basically in the order they will
383 be performed. Within each operation, the order the routines will be
384 called is given.
386 1. Setting name in the gui, and specifying one or two input fields
388 USERD_get_name_of_reader
390 2. Setting filenames and getting time info
391 USERD_set_filenames
392 USERD_get_number_of_time_steps
393 USERD_get_solution_times
394 USERD_set_time_step
396 3. Gathering info for part builder
398 USERD_set_time_step
399 USERD_get_changing_geometry_status
400 USERD_get_node_label_status
401 USERD_get_element_label_status
402 USERD_get_number_of_files_in_dataset
403 USERD_get_dataset_query_file_info
404 USERD_get_description_lines (for geometry)
405 USERD_get_number_of_model_parts
406 USERD_get_part_build_info
407 USERD_get_number_global_nodes
408 USERD_get_global_coords (for model extents)
409 USERD_get_block_coords_by_component (for model extents)
411 4. Gathering Variable info
413 USERD_get_number_of_variables
414 USERD_get_variable_info
416 5. Part building (per part created)
418 USERD_set_time_step
419 USERD_get_global_coords
420 USERD_get_global_node_ids
421 USERD_get_element_connectivities_for_part
422 USERD_get_element_ids_for_part
423 USERD_get_block_iblanking
424 USERD_get_block_coords_by_component
426 USERD_stop_part_building (only once when part builder
427 dialog is closed)
429 6. Loading Variables
431 constants:
432 ---------
433 USERD_set_time_step
434 USERD_get_constant_value
436 scalars:
437 -------
438 USERD_get_description_lines
439 USERD_set_time_step
440 USERD_get_scalar_values
441 USERD_get_block_scalar_values
443 vectors:
444 -------
445 USERD_get_description_lines
446 USERD_set_time_step
447 USERD_get_vector_values
448 USERD_get_block_vector_values_by_component
450 7. Changing geometry
452 changing coords only:
453 --------------------
454 USERD_set_time_step
455 USERD_get_global_coords
456 USERD_get_block_coords_by_component
458 changing connectivity:
459 ---------------------
460 USERD_set_time_step
461 USERD_get_number_of_model_parts
462 USERD_get_part_build_info
463 USERD_get_number_global_nodes
464 USERD_get_global_coords
465 USERD_get_global_node_ids
466 USERD_get_element_connectivities_for_part
467 USERD_get_element_ids_for_part
468 USERD_get_block_iblanking
469 USERD_get_block_coords_by_component
471 8. Node or Element queries over time
473 USERD_get_variable_value_at_specific
476 -----------------------
477 Detailed Specifications
478 -----------------------
480 Include files:
481 --------------
482 The following header file is required in any file containing these library
483 routines.
485 #include "global_extern.h"
488 Basis of arrays:
489 ---------------
490 Unless explicitly stated otherwise, all arrays are zero based - in true C
491 fashion.
494 Global variables:
495 ----------------
496 You will generally need to have a few global variables which are shared by
497 the various library routines. The detailed specifications below have assumed
498 the following are available. (Their names describe their purpose, and they
499 will be used in helping describe the details of the routines below).
501 static int Numparts_available = 0;
502 static int Num_unstructured_parts = 0;
503 static int Num_structured_blocks = 0;
505 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
507 static int Num_time_steps = 1;
508 static int Num_global_nodes = 0;
509 static int Num_variables = 0;
510 static int Num_dataset_files = 0;
511 static int Current_time_step = 0;
517 _________________________________________
518 -----------------------------------------
519 Library Routines (in alphabetical order):
520 _________________________________________
521 -----------------------------------------
523 --------------------------------------------------------------------
524 USERD_bkup
526 Description:
527 -----------
528 This routine is called during the EnSight archive process. You can
529 use it to save or restore info relating to your user defined reader.
531 Specification:
532 -------------
533 int USERD_bkup(FILE *archive_file,
534 int backup_type)
536 Returns:
537 -------
538 Z_OK if successful
539 Z_ERR if not successful
541 Arguments:
542 ---------
543 (IN) archive_file = The archive file pointer
545 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
546 Z_REST_ARCHIVE for restoring archive
548 Notes:
549 -----
550 * Since EnSight's archive file is saved in binary form, you should
551 also do any writing to it or reading from it in binary.
553 * You should archive any variables, which will be needed for
554 future operations, that will not be read or computed again
555 before they will be needed. These are typically global
556 variables.
558 * Make sure that the number of bytes that you write on a save and
559 the number of bytes that you read on a restore are identical!!
561 * If any of the variables you save are allocated arrays, you must
562 do the allocations before restoring into them.
566 --------------------------------------------------------------------
567 USERD_get_block_coords_by_component
569 Description:
570 -----------
571 Get the coordinates of a given structured block, a component at a time.
573 Specification:
574 -------------
575 int USERD_get_block_coords_by_component(int block_number,
576 int which_component,
577 float *coord_array)
579 Returns:
580 -------
581 Z_OK if successful
582 Z_ERR if not successful
584 Arguments:
585 ---------
586 (IN) block_number = The block part number
588 (IN) which_component = Z_COMPX if x component wanted
589 = Z_COMPY if y component wanted
590 = Z_COMPZ if z component wanted
592 (OUT) coord_array = 1D array containing x,y, or z
593 coordinate component of each node
595 (Array will have been allocated
596 i*j*k for the block long)
598 Notes:
599 -----
600 * Not called unless Num_structured_blocks is > 0
602 * Will be based on Current_time_step
606 --------------------------------------------------------------------
607 USERD_get_block_iblanking
609 Description:
610 -----------
611 Get the iblanking value at each node of a block (if the block is
612 iblanked).
614 Specification:
615 -------------
616 int USERD_get_block_iblanking(int block_number,
617 int *iblank_array)
619 Returns:
620 -------
621 Z_OK if successful
622 Z_ERR if not successful
624 Arguments:
625 ---------
626 (IN) block_number = The block part number
627 (OUT) iblank_array = 1D array containing iblank value
628 for each node.
630 (Array will have been allocated
631 i*j*k for the block long)
633 possible values are: Z_EXT = exterior
634 Z_INT = interior
635 Z_BND = boundary
636 Z_INTBND = internal boundary
637 Z_SYM = symmetry plane
639 Notes:
640 -----
641 * Not called unless Num_structured_blocks is > 0 and you have
642 some iblanked blocks
644 * Will be based on Current_time_step
648 --------------------------------------------------------------------
649 USERD_get_block_scalar_values
651 Description:
652 -----------
653 if Z_PER_NODE:
654 Get the values at each node of a block, for a given scalar variable
656 or if Z_PER_ELEM:
657 Get the values at each element of a block, for a given scalar variable
659 Specification:
660 -------------
661 int USERD_get_block_scalar_values(int block_number,
662 int which_scalar,
663 float *scalar_array)
665 Returns:
666 -------
667 Z_OK if successful
668 Z_ERR if not successful
670 Arguments:
671 ---------
672 (IN) block_number = The block part number
673 (IN) which_scalar = The variable number
674 (OUT) scalar_array = 1D array containing scalar values
675 for each node or element.
677 Array will have been allocated:
679 if Z_PER_NODE:
680 i*j*k for the block long
682 if Z_PER_ELEM:
683 (i-1)*(i-1)*(k-1) for the block long
685 Notes:
686 -----
687 * Not called unless Num_structured_blocks is > 0,
688 Num_variables is > 0, and there are some scalar type variables
690 * The per_node or per_elem classification must be obtainable from the
691 variable number (a var_classify array needs to be retained)
693 * Will be based on Current_time_step
697 --------------------------------------------------------------------
698 USERD_get_block_vector_values_by_component
700 Description:
701 -----------
702 if Z_PER_NODE:
703 Get the values at each node of a block, for a given vector
704 variable, one component at a time.
706 or if Z_PER_ELEM:
707 Get the values at each element of a block, for a given vector
708 variable, one component at a time.
711 Specification:
712 -------------
713 int USERD_get_block_vector_values_by_component(int block_number,
714 int which_vector,
715 int which_component,
716 float *vector_array)
718 Returns:
719 -------
720 Z_OK if successful
721 Z_ERR if not successful
723 Arguments:
724 ---------
725 (IN) block_number = The block part number
727 (IN) which_vector = The variable number
729 (IN) which_component = Z_COMPX if x component wanted
730 = Z_COMPY if y component wanted
731 = Z_COMPZ if z component wanted
733 (OUT) vector_array = 1D array containing vector
734 component value for each node or element.
736 Array will have been allocated:
738 if Z_PER_NODE:
739 i*j*k for the block long
741 if Z_PER_ELEM:
742 (i-1)*(i-1)*(k-1) for the block long
744 Notes:
745 -----
746 * Not called unless Num_structured_blocks is > 0,
747 Num_variables is > 0, and there are some vector type variables
749 * The per_node or per_elem classification must be obtainable from the
750 variable number (a var_classify array needs to be retained)
752 * Will be based on Current_time_step
756 --------------------------------------------------------------------
757 USERD_get_changing_geometry_status
759 Description:
760 -----------
761 Gets the changing geometry status for the model
763 Specification:
764 -------------
765 int USERD_get_changing_geometry_status( void )
767 Returns:
768 -------
769 Z_STATIC if geometry does not change
770 Z_CHANGE_COORDS if changing coordinates only
771 Z_CHANGE_CONN if changing connectivity
773 Arguments:
774 ---------
775 none
777 Notes:
778 -----
779 * EnSight does not support changing number of parts. But the
780 coords and/or the connectivity of the parts can change.
784 --------------------------------------------------------------------
785 USERD_get_constant_value
787 Description:
788 -----------
789 Get the value of a constant at a time step
791 Specification:
792 -------------
793 float USERD_get_constant_value(int which_var)
795 Returns:
796 -------
797 Value of the requested constant variable
799 Arguments:
800 ---------
801 (IN) which_var = The variable number
803 Notes:
804 -----
805 * Will be based on Current_time_step
809 --------------------------------------------------------------------
810 USERD_get_dataset_query_file_info
812 Description:
813 -----------
814 Get the information about files in the dataset. Used for the
815 dataset query option within EnSight.
817 Specification:
818 -------------
819 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
821 Returns:
822 -------
823 Z_OK if successful
824 Z_ERR if not successful
826 Arguments:
827 ---------
828 (OUT) qfiles = Structure containing information about each file
829 of the dataset. The Z_QFILES structure is defined
830 in the global_extern.h file
832 (The structure will have been allocated
833 Num_dataset_files long, with 10 description
834 lines per file).
836 qfiles[].name = The name of the file
837 (Z_MAXFILENP is the dimensioned length
838 of the name)
840 qfiles[].sizeb = The number of bytes in the file
841 (Typically obtained with a call to the
842 "stat" system routine) (Is a long)
844 qfiles[].timemod = The time the file was last modified
845 (Z_MAXTIMLEN is the dimensioned length
846 of this string)
847 (Typically obtained with a call to the
848 "stat" system routine)
850 qfiles[].num_d_lines = The number of description lines you
851 are providing from the file. Max = 10
853 qfiles[].f_desc[] = The description line(s) per file,
854 qfiles[].num_d_lines of them
855 (Z_MAXFILENP is the allocated length of
856 each line)
858 Notes:
859 -----
860 * If Num_dataset_files is 0, this routine will not be called.
864 --------------------------------------------------------------------
865 USERD_get_description_lines
867 Description:
868 -----------
869 Get two description lines associated with geometry per time step,
870 or one description line associated with a variable per time step.
872 Specification:
873 -------------
874 int USERD_get_description_lines(int which_type,
875 int which_var,
876 char line1[Z_BUFL],
877 char line2[Z_BUFL])
879 Returns:
880 -------
881 Z_OK if successful
882 Z_ERR if not successful
884 Arguments:
885 ---------
886 (IN) which_type = Z_GEOM for geometry (2 lines)
887 = Z_VARI for variable (1 line)
889 (IN) which_var = If it is a variable, which one.
890 Ignored if geometry type.
892 (OUT) line1 = The 1st geometry description line,
893 or the variable description line.
895 (OUT) line2 = The 2nd geometry description line
896 Not used if variable type.
898 Notes:
899 -----
900 * Will be based on Current_time_step
902 * These are the lines EnSight can echo to the screen in
903 annotation mode.
907 --------------------------------------------------------------------
908 USERD_get_element_connectivities_for_part
910 Description:
911 -----------
912 Gets the connectivities for the elements of an unstructured part
914 Specification:
915 -------------
916 int USERD_get_element_connectivities_for_part(int part_number,
917 int **conn_array[Z_MAXTYPE])
919 Returns:
920 -------
921 Z_OK if successful
922 Z_ERR if not successful
924 Arguments:
925 ---------
926 (IN) part_number = The part number
928 (OUT) conn_array = 3D array containing connectivity
929 of each element of each type.
931 (Array will have been allocated
932 Z_MAXTYPE by num_of_elements of
933 each type by connectivity length
934 of each type)
936 ex) If num_of_elements[Z_TRI03] = 25
937 num_of_elements[Z_QUA04] = 100
938 num_of_elements[Z_HEX08] = 30
939 as obtained in:
940 USERD_get_part_build_info
942 Then the allocated dimensions available
943 for this routine will be:
944 conn_array[Z_TRI03][25][3]
945 conn_array[Z_QUA04][100][4]
946 conn_array[Z_HEX08][30][8]
948 Notes:
949 -----
950 * Not called unless Num_unstructured_parts is > 0
952 * Will be based on Current_time_step
954 * The coord_array loaded in USERD_get_global_coords is zero-based,
955 but within EnSight it will become a one-based array.
956 Thus, coord_array[0] will be accessed by node 1 from the conn_array,
957 coord_array[1] will be accessed by node 2 from the conn_array, etc.
959 ex) Given a model of two triangles, you should load coord_array in
960 USERD_get_global_coords as follows:
962 node coordinates
963 ---- -----------
964 4 --------- 3 1 coord_array[0].xyz[0] = 0.0
965 |\ | coord_array[0].xyz[1] = 0.0
966 | \ T2 | coord_array[0].xyz[2] = 0.0
967 | \ |
968 | \ | 2 coord_array[1].xyz[0] = 1.0
969 | \ | coord_array[1].xyz[1] = 0.0
970 | \ | coord_array[1].xyz[2] = 0.0
971 | \ |
972 | T1 \ | 3 coord_array[2].xyz[0] = 1.0
973 | \| coord_array[2].xyz[1] = 1.6
974 1 --------- 2 coord_array[2].xyz[2] = 0.0
976 4 coord_array[3].xyz[0] = 0.0
977 coord_array[3].xyz[1] = 1.6
978 coord_array[3].xyz[2] = 0.0
981 And conn_array here as follows:
983 Triangle Connectivity
984 -------- ------------
985 T1 conn_array[Z_TRI03][0][0] = 1
986 conn_array[Z_TRI03][0][1] = 2
987 conn_array[Z_TRI03][0][2] = 4
989 T2 conn_array[Z_TRI03][1][0] = 2
990 conn_array[Z_TRI03][1][1] = 3
991 conn_array[Z_TRI03][1][2] = 4
995 --------------------------------------------------------------------
996 USERD_get_element_ids_for_part
998 Description:
999 -----------
1000 Gets the ids for the elements of an unstructured part.
1002 Specification:
1003 -------------
1004 int USERD_get_element_ids_for_part(int part_number,
1005 int *elemid_array[Z_MAXTYPE])
1007 Returns:
1008 -------
1009 Z_OK if successful
1010 Z_ERR if not successful
1012 Arguments:
1013 ---------
1014 (IN) part_number = The part number
1016 (OUT) elemid_array = 2D array containing id of each
1017 element of each type.
1019 (Array will have been allocated
1020 Z_MAXTYPE by num_of_elements of
1021 each type)
1023 ex) If num_of_elements[Z_TRI03] = 25
1024 num_of_elements[Z_QUA04] = 100
1025 num_of_elements[Z_HEX08] = 30
1026 as obtained in:
1027 USERD_get_part_build_info
1029 Then the allocated dimensions available
1030 for this routine will be:
1031 conn_array[Z_TRI03][25]
1032 conn_array[Z_QUA04][100]
1033 conn_array[Z_HEX08][30]
1035 Notes:
1036 -----
1037 * Not called unless Num_unstructured_parts is > 0 and element
1038 label status is TRUE
1040 * Will be based on Current_time_step
1044 --------------------------------------------------------------------
1045 USERD_get_element_label_status
1047 Description:
1048 -----------
1049 Answers the question as to whether element labels will be provided.
1051 Specification:
1052 -------------
1053 int USERD_get_element_label_status( void )
1055 Returns:
1056 -------
1057 TRUE if element labels will be provided
1058 FALSE if element labels will NOT be provided
1060 Arguments:
1061 ---------
1062 none
1064 Notes:
1065 -----
1066 * element lables are needed in order to do any element querying, or
1067 element labeling on-screen within EnSight.
1069 For unstructured parts, you can read them from your file if
1070 available, or can assign them, etc. They need to be unique
1071 per part, and are often unique per model.
1073 USERD_get_element_ids_for_part is used to obtain the ids,
1074 on a part by part basis, if TRUE status is returned here.
1076 For structured parts, EnSight will assign ids if you return a
1077 status of TRUE here. You cannot assign them youself!!
1081 --------------------------------------------------------------------
1082 USERD_get_global_coords
1084 Description:
1085 -----------
1086 Gets the coordinates for the global nodes.
1088 Specification:
1089 -------------
1090 int USERD_get_global_coords(CRD *coord_array)
1092 Returns:
1093 -------
1094 Z_OK if successful
1095 Z_ERR if not successful
1097 Arguments:
1098 ---------
1099 (OUT) coord_array = 1D array of CRD structures,
1100 which contains x,y,z coordinates
1101 of each node.
1103 (Array will have been allocated
1104 Num_global_nodes long)
1106 For reference, CRD structure (which is in global_extern) is:
1108 typedef struct {
1109 float xyz[3];
1110 }CRD;
1112 Notes:
1113 -----
1114 * Not called unless Num_unstructured_parts is > 0
1116 * Will be based on Current_time_step
1118 * The coord_array is zero-based, but within EnSight it will become
1119 a one-based array.
1120 Thus, coord_array[0] will be accessed by node 1 from the conn_array,
1121 coord_array[1] will be accessed by node 2 from the conn_array, etc.
1123 ex) Given a model of two triangles, you should load coord_array as
1124 follows:
1126 node coordinates
1127 ---- -----------
1128 4 --------- 3 1 coord_array[0].xyz[0] = 0.0
1129 |\ | coord_array[0].xyz[1] = 0.0
1130 | \ T2 | coord_array[0].xyz[2] = 0.0
1131 | \ |
1132 | \ | 2 coord_array[1].xyz[0] = 1.0
1133 | \ | coord_array[1].xyz[1] = 0.0
1134 | \ | coord_array[1].xyz[2] = 0.0
1135 | \ |
1136 | T1 \ | 3 coord_array[2].xyz[0] = 1.0
1137 | \| coord_array[2].xyz[1] = 1.6
1138 1 --------- 2 coord_array[2].xyz[2] = 0.0
1140 4 coord_array[3].xyz[0] = 0.0
1141 coord_array[3].xyz[1] = 1.6
1142 coord_array[3].xyz[2] = 0.0
1145 And conn_array in USERD_get_element_connectivities_for_part
1146 as follows:
1148 Triangle Connectivity
1149 -------- ------------
1150 T1 conn_array[Z_TRI03][0][0] = 1
1151 conn_array[Z_TRI03][0][1] = 2
1152 conn_array[Z_TRI03][0][2] = 4
1154 T2 conn_array[Z_TRI03][1][0] = 2
1155 conn_array[Z_TRI03][1][1] = 3
1156 conn_array[Z_TRI03][1][2] = 4
1158 --------------------------------------------------------------------
1159 USERD_get_global_node_ids
1161 Description:
1162 -----------
1163 Gets the node ids assigned to each of the global nodes.
1165 Specification:
1166 -------------
1167 int USERD_get_global_node_ids(int *nodeid_array)
1169 Returns:
1170 -------
1171 Z_OK if successful
1172 Z_ERR if not successful
1174 Arguments:
1175 ---------
1176 (OUT) nodeid_array = 1D array containing node ids of
1177 each node. The ids must be > 0
1179 (Array will have been allocated
1180 Num_global_nodes long)
1181 Notes:
1182 -----
1183 * Not called unless Num_unstructured_parts is > 0 and node label
1184 status is TRUE
1186 * Will be based on Current_time_step
1190 --------------------------------------------------------------------
1191 USERD_get_name_of_reader
1193 Description:
1194 -----------
1195 Gets the name of your user defined reader. The user interface will
1196 ask for this and include it in the available reader list.
1198 Specification:
1199 -------------
1200 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1201 int *two_fields)
1203 Returns:
1204 -------
1205 Z_OK if successful
1206 Z_ERR if not successful
1208 Arguments:
1209 ---------
1210 (OUT) reader_name = the name of the your reader or data format.
1211 (max length is Z_MAX_USERD_NAME, which is 20)
1213 (OUT) *two_fields = FALSE if only one data field required
1214 in the data dialog of EnSight.
1215 TRUE if two data fields required.
1217 Notes:
1218 -----
1219 * Always called. Provide a name for your custom reader format.
1221 * If you don't want a custom reader to show up in the data dialog
1222 choices, return a name of "No_Custom"
1226 --------------------------------------------------------------------
1227 USERD_get_node_label_status
1229 Description:
1230 -----------
1231 Answers the question as to whether node labels will be provided.
1233 Specification:
1234 -------------
1235 int USERD_get_node_label_status( void )
1237 Returns:
1238 -------
1239 TRUE if node labels will be provided
1240 FALSE if node labels will NOT be provided
1242 Arguments:
1243 ---------
1244 none
1246 Notes:
1247 -----
1248 * Node ids are needed in order to do any node querying, or node
1249 labeling on-screen within EnSight.
1251 For unstructured parts, you can read them from your file if
1252 available, or can assign them, etc. They need to be unique
1253 per part, and are often unique per model. The must also be
1254 positive numbers greater than zero.
1256 USERD_get_global_node_ids is used to obtain the ids, if the
1257 status returned here is TRUE.
1259 Also be aware that if you say node labels are available,
1260 the connectivity of elements must be according to these
1261 node ids.
1263 For structured parts, EnSight will assign ids if you return a
1264 status of TRUE here. You cannot assign them yourself!!
1268 --------------------------------------------------------------------
1269 USERD_get_number_of_files_in_dataset
1271 Description:
1272 -----------
1273 Get the total number of files in the dataset. Used for the
1274 dataset query option within EnSight.
1276 Specification:
1277 -------------
1278 int USERD_get_number_of_files_in_dataset( void )
1280 Returns:
1281 -------
1282 The total number of files in the dataset.
1284 Arguments:
1285 ---------
1286 none
1288 Notes:
1289 -----
1290 * You can be as complete as you want about this. If you don't
1291 care about the dataset query option, return a value of 0
1292 If you only want certain files, you can just include them. But,
1293 you will need to supply the info in USERD_get_dataset_query_file_info
1294 for each file you include here.
1296 * Num_dataset_files would be set here
1300 --------------------------------------------------------------------
1301 USERD_get_number_of_global_nodes
1303 Description:
1304 -----------
1305 Gets the number of global nodes, used for unstructured parts.
1307 Specification:
1308 -------------
1309 int USERD_get_number_of_global_nodes()
1311 Returns:
1312 -------
1313 Number of global nodes (>=0 if okay, <0 if problems)
1315 Arguments:
1316 ---------
1317 none
1319 Notes:
1320 -----
1321 * Not called unless Num_unstructured_parts is > 0
1323 * Will be based on Current_time_step
1325 * For unstructured data:
1326 EnSight wants 1. A global array of nodes
1327 2. Element connectivities by part, which
1328 reference the node numbers of the global
1329 node array.
1330 IMPORTANT:
1331 ---------
1332 If you provide node ids, then element connectivities
1333 must be in terms of the node ids. If you do not
1334 provide node ids, then element connectivities must be
1335 in terms of the index into the node array, but shifted
1336 to start at 1
1338 * Num_global_nodes would be set here
1342 --------------------------------------------------------------------
1343 USERD_get_number_of_model_parts
1345 Description:
1346 -----------
1347 Gets the total number of unstructured and structured parts
1348 in the model, for which you can supply information.
1350 Specification:
1351 -------------
1352 int USERD_get_number_of_model_parts( void )
1354 Returns:
1355 -------
1356 Number of parts (>0 if okay, <=0 if probs).
1358 Arguments:
1359 ---------
1360 none
1362 Notes:
1363 -----
1364 * If going to have to read down through the parts in order to
1365 know how many, you may want to build a table of pointers to
1366 the various parts, so you can easily get to particular parts in
1367 later processes. If you can simply read the number of parts
1368 at the head of the file, then you would probably not build the
1369 table at this time.
1371 * This routine would set Numparts_available, which is equal to
1372 Num_unstructured_parts + Num_structured_blocks.
1376 --------------------------------------------------------------------
1377 USERD_get_number_of_time_steps
1379 Description:
1380 -----------
1381 Gets the number of time steps of data available.
1383 Specification:
1384 -------------
1385 int USERD_get_number_of_time_steps( void )
1387 Returns:
1388 -------
1389 Number of time steps (>0 if okay, <=0 if problems).
1391 Arguments:
1392 ---------
1393 none
1395 Notes:
1396 -----
1397 * This should be >= 1 1 indicates a static model
1398 >1 indicates a transient model
1400 * Num_time_steps would be set here
1404 --------------------------------------------------------------------
1405 USERD_get_number_of_variables
1407 Description:
1408 -----------
1409 Get the number of variables for which you will be providing info.
1411 Specification:
1412 -------------
1413 int USERD_get_number_of_variables( void )
1415 Returns:
1416 -------
1417 Number of variables (includes constant, scalar, and vector types)
1418 (>=0 if okay, <0 if problem)
1420 Arguments:
1421 ---------
1422 none
1424 Notes:
1425 -----
1426 *****************************************************************
1427 * Variable numbers, by which references will be made, are implied
1428 here. If you say there are 3 variables, the variable numbers
1429 will be 1, 2, and 3.
1430 *****************************************************************
1432 * Num_variables would be set here
1436 --------------------------------------------------------------------
1437 USERD_get_part_build_info
1439 Description:
1440 -----------
1441 Gets the info needed for the part building process.
1443 Specification:
1444 -------------
1445 int USERD_get_part_build_info(int *part_numbers,
1446 int *part_types,
1447 char *part_description[Z_BUFL],
1448 int *number_of_elements[Z_MAXTYPE],
1449 int *ijk_dimensions[3],
1450 int *iblanking_options[6])
1452 Returns:
1453 -------
1454 Z_OK if successful
1455 Z_ERR if not successful
1457 Arguments:
1458 ---------
1459 (OUT) part_numbers = Array containing part numbers for
1460 each of the model parts.
1462 IMPORTANT:
1463 Parts numbers must be >= 1
1465 ********************************************
1466 The numbers provided here are the ones by
1467 which the parts will be referred to in any
1468 of the other routines which receive a part
1469 number or block number as an argument!!
1470 ********************************************
1472 (Array will have been allocated
1473 Numparts_available long)
1475 (OUT) part_types = Array containing one of the
1476 following for each model part:
1478 Z_UNSTRUCTURED or
1479 Z_STRUCTURED or
1480 Z_IBLANKED
1482 (Array will have been allocated
1483 Numparts_available long)
1485 (OUT) part_description = Array containing a description
1486 for each of the model parts
1488 (Array will have been allocated
1489 Numparts_available by Z_BUFL
1490 long)
1492 (OUT) number_of_elements = 2D array containing number of
1493 each type of element for each
1494 unstructured model part.
1495 ------------
1496 Possible types are:
1498 Z_POINT = point
1499 Z_BAR02 = 2-noded bar
1500 Z_BAR03 = 3-noded bar
1501 Z_TRI03 = 3-noded triangle
1502 Z_TRI06 = 6-noded triangle
1503 Z_QUA04 = 4-noded quadrilateral
1504 Z_QUA08 = 8-noded quadrilateral
1505 Z_TET04 = 4-noded tetrahedron
1506 Z_TET10 = 10-noded tetrahedron
1507 Z_PYR05 = 5-noded pyramid
1508 Z_PYR13 = 13-noded pyramid
1509 Z_PEN06 = 6-noded pentahedron
1510 Z_PEN15 = 15-noded pentahedron
1511 Z_HEX08 = 8-noded hexahedron
1512 Z_HEX20 = 20-noded hexahedron
1514 (Ignored unless Z_UNSTRUCTURED type)
1516 (Array will have been allocated
1517 Numparts_available by
1518 Z_MAXTYPE long)
1520 (OUT) ijk_dimensions = 2D array containing ijk dimensions
1521 for each structured model part.
1522 ----------
1523 (Ignored if Z_UNSTRUCTURED type)
1525 (Array will have been allocated
1526 Numparts_available by 3 long)
1528 ijk_dimensions[][0] = I dimension
1529 ijk_dimensions[][1] = J dimension
1530 ijk_dimensions[][2] = K dimension
1532 (OUT) iblanking_options = 2D array containing iblanking
1533 options possible for each
1534 structured model part.
1535 ----------
1536 (Ignored unless Z_IBLANKED type)
1538 (Array will have been allocated
1539 Numparts_available by 6 long)
1541 iblanking_options[][Z_EXT] = TRUE if external (outside)
1542 [][Z_INT] = TRUE if internal (inside)
1543 [][Z_BND] = TRUE if boundary
1544 [][Z_INTBND] = TRUE if internal boundary
1545 [][Z_SYM] = TRUE if symmetry surface
1548 Notes:
1549 -----
1550 * If you haven't built a table of pointers to the different parts,
1551 you might want to do so here as you gather the needed info.
1553 * Will be based on Current_time_step
1557 --------------------------------------------------------------------
1558 USERD_get_scalar_values
1560 Description:
1561 -----------
1562 if Z_PER_NODE:
1563 Get the values at each global node for a given scalar variable.
1565 or if Z_PER_ELEM:
1566 Get the values at each element of a specific part and type for a
1567 given scalar variable.
1569 Specification:
1570 -------------
1571 int USERD_get_scalar_values(int which_scalar,
1572 int which_part,
1573 int which_type,
1574 float *scalar_array)
1576 Returns:
1577 -------
1578 Z_OK if successful
1579 Z_ERR if not successful
1581 Arguments:
1582 ---------
1583 (IN) which_scalar = The variable number (of scalar type)
1585 (IN) which_part
1587 if Z_PER_NODE: Not used
1589 if Z_PER_ELEM: = The part number
1591 (IN) which_type
1593 if Z_PER_NODE: Not used
1595 if Z_PER_ELEM: = The element type
1597 (OUT) scalar_array
1599 if Z_PER_NODE: = 1D array containing scalar values
1600 for each node.
1602 (Array will have been allocated
1603 Num_global_nodes long)
1605 if Z_PER_ELEM: = 1d array containing scalar values for
1606 each element of a particular part and type.
1608 (Array will have been allocated
1609 number_of_elements[which_part][which_type]
1610 long. See USERD_get_part_build_info)
1612 Notes:
1613 -----
1614 * Not called unless Num_unstructured_parts is > 0,
1615 Num_variables is > 0, and you have some scalar type variables.
1617 * The per_node or per_elem classification must be obtainable from the
1618 variable number (a var_classify array needs to be retained)
1620 * Will be based on Current_time_step
1624 --------------------------------------------------------------------
1625 USERD_get_solution_times
1627 Description:
1628 -----------
1629 Get the solution times associated with each time step.
1631 Specification:
1632 -------------
1633 int USERD_get_solution_times(float *solution_times)
1635 Returns:
1636 -------
1637 Z_OK if successful
1638 Z_ERR if not successful
1640 Arguments:
1641 ---------
1642 (OUT) solution_times = 1D array of solution times/time step
1644 (Array will have been allocated
1645 Num_time_steps long)
1647 Notes:
1648 -----
1649 * The solution times must be non-negative and increasing.
1653 --------------------------------------------------------------------
1654 USERD_get_variable_info
1656 Description:
1657 -----------
1658 Get the variable descriptions, types and filenames
1660 Specification:
1661 -------------
1662 int USERD_get_variable_info(char **var_description,
1663 char **var_filename,
1664 int *var_type,
1665 int *var_classify)
1667 Returns:
1668 -------
1669 Z_OK if successful
1670 Z_ERR if not successful
1672 Arguments:
1673 ---------
1674 (OUT) var_description = Variable descriptions
1676 (Array will have been allocated
1677 Num_variables by Z_BUFL long)
1679 (OUT) var_filename = Variable filenames
1681 (Array will have been allocated
1682 Num_variables by Z_BUFL long)
1684 (OUT) var_type = Variable type
1686 (Array will have been allocated
1687 Num_variables long)
1689 types are: Z_CONSTANT
1690 Z_SCALAR
1691 Z_VECTOR
1693 (OUT) var_classify = Variable classification
1695 (Array will have been allocated
1696 Num_variables long)
1698 types are: Z_PER_NODE
1699 Z_PER_ELEM
1701 Notes:
1702 -----
1703 * The implied variable numbers apply, but be aware that the
1704 arrays are zero based.
1705 So for variable 1, will need to provide var_description[0]
1706 var_filename[0]
1707 var_type[0]
1708 var_classify[0]
1710 for variable 2, will need to provide var_description[1]
1711 var_filename[1]
1712 var_type[1]
1713 var_classify[1]
1714 etc.
1718 --------------------------------------------------------------------
1719 USERD_get_variable_value_at_specific
1721 Description:
1722 -----------
1723 if Z_PER_NODE:
1724 Get the value of a particular variable at a particular node in a
1725 particular part at a particular time.
1727 or if Z_PER_ELEM:
1728 Get the value of a particular variable at a particular element of
1729 a particular type in a particular part at a particular time.
1732 Specification:
1733 -------------
1734 int USERD_get_variable_value_at_specific(int which_var,
1735 int which_node_or_elem,
1736 int which_part,
1737 int which_elem_type,
1738 int time_step,
1739 float values[3])
1741 Returns:
1742 -------
1743 Z_OK if successful
1744 Z_ERR if not successful
1746 Arguments:
1747 ---------
1748 (IN) which_var = The variable number
1750 (IN) which_node_or_elem
1752 If Z_PER_NODE:
1753 = The node number. This is not the id, but is
1754 the index of the global node
1755 list (1 based), or the block's
1756 node list (1 based).
1758 Thus, coord_array[1]
1759 coord_array[2]
1760 coord_array[3]
1761 . |
1762 . |which_node_or_elem index
1763 . ----
1766 If Z_PER_ELEM:
1767 = The element number. This is not the id, but is
1768 the element number index
1769 of the number_of_element array
1770 (see USERD_get_part_build_info),
1771 or the block's element list (1 based).
1773 Thus, for which_part:
1774 conn_array[which_elem_type][0]
1775 conn_array[which_elem_type][1]
1776 conn_array[which_elem_type][2]
1777 . |
1778 . which_node_or_elem index
1779 . ----
1782 (IN) which_part
1784 If Z_PER_NODE, or block part:
1785 = Not used
1787 If Z_PER_ELEM:
1788 = The part number
1790 (IN) which_elem_type
1792 If Z_PER_NODE, or block part:
1793 = Not used
1795 If Z_PER_ELEM:
1796 = The element type. This is the element type index
1797 of the number_of_element array
1798 (see USERD_get_part_build_info)
1800 (IN) time_step = The time step
1802 (OUT) values = scalar or vector component value(s)
1803 values[0] = scalar or vector[0]
1804 values[1] = vector[1]
1805 values[2] = vector[2]
1808 Notes:
1809 -----
1810 * This routine is used in node querys over time (or element querys over
1811 time for Z_PER_ELEM variables). If these operations are not critical
1812 to you, this can be a dummy routine.
1814 * The per_node or per_elem classification must be obtainable from the
1815 variable number (a var_classify array needs to be retained)
1818 --------------------------------------------------------------------
1819 USERD_get_vector_values
1821 Description:
1822 -----------
1823 if Z_PER_NODE:
1824 Get the values at each global node for a given vector variable.
1826 or if Z_PER_ELEM:
1827 Get the values at each element of a specific part and type for a
1828 given vector variable.
1830 Specification:
1831 -------------
1832 int USERD_get_vector_values(int which_vector,
1833 int which_part,
1834 int which_type,
1835 float *vector_array)
1837 Returns:
1838 -------
1839 Z_OK if successful
1840 Z_ERR if not successful
1842 Arguments:
1843 ---------
1844 (IN) which_vector = The variable number
1846 (IN) which_part
1848 if Z_PER_NODE: Not used
1850 if Z_PER_ELEM: = The part number
1852 (IN) which_type
1854 if Z_PER_NODE: Not used
1856 if Z_PER_ELEM: = The element type
1858 (OUT) vector_array
1860 if Z_PER_NODE: = 1D array containing vector values
1861 for each node.
1863 (Array will have been allocated
1864 3 by Num_global_nodes long)
1866 Info stored in this fashion:
1867 vector_array[0] = xcomp of node 1
1868 vector_array[1] = ycomp of node 1
1869 vector_array[2] = zcomp of node 1
1871 vector_array[3] = xcomp of node 2
1872 vector_array[4] = ycomp of node 2
1873 vector_array[5] = zcomp of node 2
1875 vector_array[6] = xcomp of node 3
1876 vector_array[7] = ycomp of node 3
1877 vector_array[8] = zcomp of node 3
1878 etc.
1880 if Z_PER_ELEM: = 1D array containing vector values for
1881 each element of a particular part and type.
1883 (Array will have been allocated
1884 3 by number_of_elements[which_part][which_type]
1885 long. See USERD_get_part_build_info)
1887 Info stored in this fashion:
1888 vector_array[0] = xcomp of elem 1 (of part and type)
1889 vector_array[1] = ycomp of elem 1 "
1890 vector_array[2] = zcomp of elem 1 "
1892 vector_array[3] = xcomp of elem 2 "
1893 vector_array[4] = ycomp of elem 2 "
1894 vector_array[5] = zcomp of elem 2 "
1896 vector_array[6] = xcomp of elem 3 "
1897 vector_array[7] = ycomp of elem 3 "
1898 vector_array[8] = zcomp of elem 3 "
1899 etc.
1901 Notes:
1902 -----
1903 * Not called unless Num_unstructured_parts is > 0,
1904 Num_variables is > 0, and you have some vector type variables
1906 * The per_node or per_elem classification must be obtainable from the
1907 variable number (a var_classify array needs to be retained)
1909 * Will be based on Current_time_step
1912 --------------------------------------------------------------------
1913 USERD_set_filenames
1915 Description:
1916 -----------
1917 Receives the geometry and result filenames entered in the data
1918 dialog. The user written code will have to store and use these
1919 as needed.
1921 Specification:
1922 -------------
1923 int USERD_set_filenames(char filename_1[],
1924 char filename_2[],
1925 char the_path[],
1926 int swapbytes)
1928 Returns:
1929 -------
1930 Z_OK if successful
1931 Z_ERR if not successful
1933 Arguments:
1934 ---------
1935 (IN) filename_1 = the filename entered into the geometry
1936 field of the data dialog.
1937 (IN) filename_2 = the filename entered into the result
1938 field of the data dialog.
1939 (If the two_fields flag in USERD_get_name_of_reader
1940 is FALSE, this will be null string)
1941 (IN) the_path = the path info from the data dialog.
1942 Note: filename_1 and filename_2 have already
1943 had the path prepended to them. This
1944 is provided in case it is needed for
1945 filenames contained in one of the files
1946 (IN) swapbytes = TRUE if should swap bytes when reading data.
1948 Notes:
1949 -----
1950 * Since you must manage everything from the input that is entered in
1951 these data dialog fields, this is an important routine!
1953 * It may be that you will need to have an executive type file that contains
1954 info and other filenames within it, like EnSight6's case file.
1958 --------------------------------------------------------------------
1959 USERD_set_time_step
1961 Description:
1962 -----------
1963 Set the current time step. All functions that need time, and
1964 that do not explicitly pass it in, will use the time step set by
1965 this routine.
1967 Specification:
1968 -------------
1969 void USERD_set_time_step(int time_step)
1971 Returns:
1972 -------
1973 nothing
1975 Arguments:
1976 ---------
1977 (IN) time_step - The current time step to set
1979 Notes:
1980 -----
1981 * Current_time_step would be set here
1985 --------------------------------------------------------------------
1986 USERD_stop_part_building
1988 Description:
1989 -----------
1990 This routine called when the part building dialog is closed. It is
1991 provided in case you desire to release memory, etc. that was only needed
1992 during the part building process.
1994 Specification:
1995 -------------
1996 void USERD_stop_part_building( void )
1998 Returns:
1999 -------
2000 nothing
2002 Arguments:
2003 ---------
2004 none
2006 Notes:
2007 -----
2011 ---- end of doucment ----