[foam-extend-3.2.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README7
| blob | 59183d5fafdeb61be269bf98b6b578f699198815 |
1 --------------------------------------
2 EnSight User Defined Reader Capability
3 --------------------------------------
5 A user defined reader capability is included in EnSight which allows otherwise
6 unsupported structured or unstructured data to be read. The user defined
7 reader utilizes a dynamic shared library composed of routines defined in this
8 document, but produced by the user (or some third party). This capability is
9 currently available for dec, ibm, hp, sgi, and sun servers.
11 ****************************************************************************
12 Note: Several user defined readers have been included with your EnSight
13 release and can be accessed by changing the ENSIGHT6_READER
14 environment variable as outlined in step 3. below. Please be aware
15 that these are "unsupported" readers, but many of them are being used
16 successfully.
17 ****************************************************************************
20 The process for producing a user defined reader is:
21 --------------------------------------------------
22 1. Write code for all pertinent routines in the library (Unless someone else
23 has done this for you).
25 This is of course where the work is done by the user. The word
26 "pertinent" is used because depending on the nature of the data, some
27 of the routines in the library may be dummy routines.
29 The source code for a dummy library and for various other working or
30 sample libraries is copied from the installation CD during
31 installation. These will be located in directories under:
33 $ENSIGHT6_HOME/ensight62/user_defined_src/readers
35 examples:
36 --------
37 The default library. Basic dummy routines.
38 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/dummy
40 Sample library which reads unstructured binary EnSight6 data.
41 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/ensight6
43 Sample library which reads binary static plot3d data.
44 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/plot3d
46 Reads binary LS-DYNA3D state database.
47 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/ls-dyna3d
49 Reads FORTRAN binary Unstrutured dytran data base.
50 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/dytran
52 Reads FlowScience "flsgrf" flow3d data.
53 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/flow3d
55 Reads Tecplot "plt" files.
56 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/tecplot
58 Reads Common File Format data.
59 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/cff
61 Reads Cobalt grid and picture/restart file data.
62 $ENSIGHT6_HOME/ensight62/user_defined_src/readers/cobalt
64 You may find it useful to place your library source in this area as
65 well, but are not limited to this location.
67 * ===> The descriptions of each library routine and the order that the
68 routines are called, which is provided in this file, along with
69 the example libraries, should make it possible for you to produce
70 code for your own data reader.
73 2. Produce the dynamic shared library.
75 This is a compiling and loading process which varies according to
76 the type of machine you are on. Thus, a separate makefile is provided
77 for each machine type. Operating system level differences could cause
78 you to have to modify these makefiles slightly, but the general
79 process is very straightforward. Note that for the SGI environment you
80 must compile with the following flags to ensure compatability with
81 the EnSight server: Irix_5.3 -mips1
82 Irix_6.2 -mips2
83 Irix_6.5_n32 -mips3
84 Irix_6.5_n64 -mips4 -64
86 __________________________________________________________________
87 | MACHINE | MAKEFILE TO USE | SHARED LIBRARY NAME PRODUCED |
88 | TYPE |--------------------------------------------------------|
89 | | LD COMMAND USED IN MAKEFILE |
90 ==================================================================
91 __________________________________________________________________
92 | sgi | makefile.sgi | libuserd.so |
93 | |--------------------------------------------------------|
94 | | ld -shared -all -o libuserd.so libuserd.o |
95 ------------------------------------------------------------------
96 __________________________________________________________________
97 | hp | makefile.hp | libuserd.sl |
98 | |--------------------------------------------------------|
99 | | ld -b -o libuserd.sl libuserd.o |
100 ------------------------------------------------------------------
101 __________________________________________________________________
102 | sun | makefile.sun | libuserd.so |
103 | |--------------------------------------------------------|
104 | | ld -G -o libuserd.so libuserd.o |
105 ------------------------------------------------------------------
106 __________________________________________________________________
107 | dec | makefile.dec | libuserd.so |
108 | |--------------------------------------------------------|
109 | | ld -shared -all -o libuserd.so libuserd.o -lc |
110 ------------------------------------------------------------------
111 __________________________________________________________________
112 | ibm | makefile.ibm | libuserd.so |
113 | |--------------------------------------------------------|
114 | | ld -G -o libuserd.so libuserd.o -bnoentry -bexpall -lc |
115 ------------------------------------------------------------------
117 Once you have created your library, you should place it in a directory
118 of your choice under:
120 $ENSIGHT6_HOME/machines/$ENSIGHT6_ARCH/lib_readers
122 Thus, if you created a reader for "mydata", you should create the
123 following directory, and place your libuserd.so into it:
125 $ENSIGHT6_HOME/machines/$ENSIGHT6_ARCH/lib_readers/mydata
128 3. Set up the ENSIGHT6_READER environment variable so EnSight will know
129 which reader directory to use at runtime.
131 Ensight will look for the library under:
133 $ENSIGHT6_HOME/machines/$ENSIGHT6_ARCH/lib_readers/$ENSIGHT6_READER
135 When EnSight was installed, you set this variable to "dummy", with:
137 setenv ENSIGHT6_READER dummy
139 You can use any of the other provided readers by changing this variable.
140 For example, to use the dytran reader:
142 setenv ENSIGHT6_READER dytran
144 Thus, you can use your reader in the same way. If you provided "mydata",
145 change ENSIGHT6_READER to:
147 setenv ENSIGHT6_READER mydata
150 For your information, EnSight makes sure that the appropriate library
151 environment variable is set for your machine architecture. You do not
152 have to deal with this if you locate your library as outlined above.
153 The library environment variables used are:
155 Machine type Environment variable to set
156 ------------ ---------------------------
157 sgi LD_LIBRARY_PATH
158 dec LD_LIBRARY_PATH
159 sun LD_LIBRARY_PATH
160 hp SHLIB_PATH
161 ibm LIBPATH
163 IMPORTANT: Unless the shared library is available in the
164 .../$ENSIGHT6_READER directory, EnSight will not run.
166 As always, EnSight support is available if you need it.
170 -------------------------------
171 Quick Index of Library Routines
172 -------------------------------
174 Generally Needed for UNSTRUCTURED data
175 --------------------------------------
176 USERD_get_number_of_global_nodes number of global nodes
177 USERD_get_global_coords global node coordinates
178 USERD_get_global_node_ids global node ids
179 USERD_get_element_connectivities_for_part part's element connectivites
180 USERD_get_element_ids_for_part part's element ids
181 USERD_get_scalar_values global scalar variables
182 USERD_get_vector_values global vector variables
185 Generally Needed for BLOCK data
186 -----------------------------------------
187 USERD_get_block_coords_by_component block coordinates
188 USERD_get_block_iblanking block iblanking values
189 USERD_get_block_scalar_values block scalar variables
190 USERD_get_block_vector_values_by_component block vector variables
193 Generally needed for either or both kinds of data
194 -------------------------------------------------
195 USERD_set_filenames filenames entered in GUI
196 USERD_set_time_step current time step
198 USERD_get_name_of_reader name of reader for GUI
199 USERD_get_number_of_files_in_dataset number of files in model
200 USERD_get_dataset_query_file_info info about each model file
201 USERD_get_changing_geometry_status changing geometry?
202 USERD_get_node_label_status node labels?
203 USERD_get_element_label_status element labels?
204 USERD_get_number_of_time_steps number of time steps
205 USERD_get_solution_times solution time values
206 USERD_get_description_lines file associated descrip lines
207 USERD_get_number_of_variables number of variables
208 USERD_get_variable_info variable type/descrip etc.
209 USERD_get_constant_value constant variable's value
210 USERD_get_number_of_model_parts number of model parts
211 USERD_get_part_build_info part type/descrip etc.
212 USERD_get_variable_value_at_specific node's or element's variable
213 value over time
215 USERD_stop_part_building cleanup routine
216 USERD_bkup archive routine
220 -------------------------
221 Order Routines are called
222 -------------------------
224 The various main operations are given basically in the order they will
225 be performed. Within each operation, the order the routines will be
226 called is given.
228 1. Setting name in the gui, and specifying one or two input fields
230 USERD_get_name_of_reader
232 2. Setting filenames and getting time info
233 USERD_set_filenames
234 USERD_get_number_of_time_steps
235 USERD_get_solution_times
236 USERD_set_time_step
238 3. Gathering info for part builder
240 USERD_set_time_step
241 USERD_get_changing_geometry_status
242 USERD_get_node_label_status
243 USERD_get_element_label_status
244 USERD_get_number_of_files_in_dataset
245 USERD_get_dataset_query_file_info
246 USERD_get_description_lines (for geometry)
247 USERD_get_number_of_model_parts
248 USERD_get_part_build_info
249 USERD_get_number_global_nodes
250 USERD_get_global_coords (for model extents)
251 USERD_get_block_coords_by_component (for model extents)
253 4. Gathering Variable info
255 USERD_get_number_of_variables
256 USERD_get_variable_info
258 5. Part building (per part created)
260 USERD_set_time_step
261 USERD_get_global_coords
262 USERD_get_global_node_ids
263 USERD_get_element_connectivities_for_part
264 USERD_get_element_ids_for_part
265 USERD_get_block_iblanking
266 USERD_get_block_coords_by_component
268 USERD_stop_part_building (only once when part builder
269 dialog is closed)
271 6. Loading Variables
273 constants:
274 ---------
275 USERD_set_time_step
276 USERD_get_constant_value
278 scalars:
279 -------
280 USERD_get_description_lines
281 USERD_set_time_step
282 USERD_get_scalar_values
283 USERD_get_block_scalar_values
285 vectors:
286 -------
287 USERD_get_description_lines
288 USERD_set_time_step
289 USERD_get_vector_values
290 USERD_get_block_vector_values_by_component
292 7. Changing geometry
294 changing coords only:
295 --------------------
296 USERD_set_time_step
297 USERD_get_global_coords
298 USERD_get_block_coords_by_component
300 changing connectivity:
301 ---------------------
302 USERD_set_time_step
303 USERD_get_number_of_model_parts
304 USERD_get_part_build_info
305 USERD_get_number_global_nodes
306 USERD_get_global_coords
307 USERD_get_global_node_ids
308 USERD_get_element_connectivities_for_part
309 USERD_get_element_ids_for_part
310 USERD_get_block_iblanking
311 USERD_get_block_coords_by_component
315 -----------------------
316 Detailed Specifications
317 -----------------------
319 Include files:
320 --------------
321 The following header file is required in any file containing these library
322 routines.
324 #include "global_extern.h"
327 Basis of arrays:
328 ---------------
329 Unless explicitly stated otherwise, all arrays are zero based - in true C
330 fashion.
333 Global variables:
334 ----------------
335 You will generally need to have a few global variables which are shared by
336 the various library routines. The detailed specifications below have assumed
337 the following are available. (Their names describe their purpose, and they
338 will be used in helping describe the details of the routines below).
340 static int Numparts_available = 0;
341 static int Num_unstructured_parts = 0;
342 static int Num_structured_blocks = 0;
344 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
346 static int Num_time_steps = 1;
347 static int Num_global_nodes = 0;
348 static int Num_variables = 0;
349 static int Num_dataset_files = 0;
350 static int Current_time_step = 0;
356 _________________________________________
357 -----------------------------------------
358 Library Routines (in alphabetical order):
359 _________________________________________
360 -----------------------------------------
362 --------------------------------------------------------------------
363 USERD_bkup
365 Description:
366 -----------
367 This routine is called during the EnSight archive process. You can
368 use it to save or restore info relating to your user defined reader.
370 Specification:
371 -------------
372 int USERD_bkup(FILE *archive_file,
373 int backup_type)
375 Returns:
376 -------
377 Z_OK if successful
378 Z_ERR if not successful
380 Arguments:
381 ---------
382 (IN) archive_file = The archive file pointer
384 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
385 Z_REST_ARCHIVE for restoring archive
387 Notes:
388 -----
389 * Since EnSight's archive file is saved in binary form, you should
390 also do any writing to it or reading from it in binary.
392 * You should archive any variables, which will be needed for
393 future operations, that will not be read or computed again
394 before they will be needed. These are typically global
395 variables.
397 * Make sure that the number of bytes that you write on a save and
398 the number of bytes that you read on a restore are identical!!
400 * If any of the variables you save are allocated arrays, you must
401 do the allocations before restoring into them.
405 --------------------------------------------------------------------
406 USERD_get_block_coords_by_component
408 Description:
409 -----------
410 Get the coordinates of a given structured block, a component at a time.
412 Specification:
413 -------------
414 int USERD_get_block_coords_by_component(int block_number,
415 int which_component,
416 float *coord_array)
418 Returns:
419 -------
420 Z_OK if successful
421 Z_ERR if not successful
423 Arguments:
424 ---------
425 (IN) block_number = The block part number
427 (IN) which_component = Z_COMPX if x component wanted
428 = Z_COMPY if y component wanted
429 = Z_COMPZ if z component wanted
431 (OUT) coord_array = 1D array containing x,y, or z
432 coordinate component of each node
434 (Array will have been allocated
435 i*j*k for the block long)
437 Notes:
438 -----
439 * Not called unless Num_structured_blocks is > 0
441 * Will be based on Current_time_step
445 --------------------------------------------------------------------
446 USERD_get_block_iblanking
448 Description:
449 -----------
450 Get the iblanking value at each node of a block (if the block is
451 iblanked).
453 Specification:
454 -------------
455 int USERD_get_block_iblanking(int block_number,
456 int *iblank_array)
458 Returns:
459 -------
460 Z_OK if successful
461 Z_ERR if not successful
463 Arguments:
464 ---------
465 (IN) block_number = The block part number
466 (OUT) iblank_array = 1D array containing iblank value
467 for each node.
469 (Array will have been allocated
470 i*j*k for the block long)
472 possible values are: Z_EXT = exterior
473 Z_INT = interior
474 Z_BND = boundary
475 Z_INTBND = internal boundary
476 Z_SYM = symmetry plane
478 Notes:
479 -----
480 * Not called unless Num_structured_blocks is > 0 and you have
481 some iblanked blocks
483 * Will be based on Current_time_step
487 --------------------------------------------------------------------
488 USERD_get_block_scalar_values
490 Description:
491 -----------
492 if Z_PER_NODE:
493 Get the values at each node of a block, for a given scalar variable
495 or if Z_PER_ELEM:
496 Get the values at each element of a block, for a given scalar variable
498 Specification:
499 -------------
500 int USERD_get_block_scalar_values(int block_number,
501 int which_scalar,
502 float *scalar_array)
504 Returns:
505 -------
506 Z_OK if successful
507 Z_ERR if not successful
509 Arguments:
510 ---------
511 (IN) block_number = The block part number
512 (IN) which_scalar = The variable number
513 (OUT) scalar_array = 1D array containing scalar values
514 for each node or element.
516 Array will have been allocated:
518 if Z_PER_NODE:
519 i*j*k for the block long
521 if Z_PER_ELEM:
522 (i-1)*(i-1)*(k-1) for the block long
524 Notes:
525 -----
526 * Not called unless Num_structured_blocks is > 0,
527 Num_variables is > 0, and there are some scalar type variables
529 * The per_node or per_elem classification must be obtainable from the
530 variable number (a var_classify array needs to be retained)
532 * Will be based on Current_time_step
536 --------------------------------------------------------------------
537 USERD_get_block_vector_values_by_component
539 Description:
540 -----------
541 if Z_PER_NODE:
542 Get the values at each node of a block, for a given vector
543 variable, one component at a time.
545 or if Z_PER_ELEM:
546 Get the values at each element of a block, for a given vector
547 variable, one component at a time.
550 Specification:
551 -------------
552 int USERD_get_block_vector_values_by_component(int block_number,
553 int which_vector,
554 int which_component,
555 float *vector_array)
557 Returns:
558 -------
559 Z_OK if successful
560 Z_ERR if not successful
562 Arguments:
563 ---------
564 (IN) block_number = The block part number
566 (IN) which_vector = The variable number
568 (IN) which_component = Z_COMPX if x component wanted
569 = Z_COMPY if y component wanted
570 = Z_COMPZ if z component wanted
572 (OUT) vector_array = 1D array containing vector
573 component value for each node or element.
575 Array will have been allocated:
577 if Z_PER_NODE:
578 i*j*k for the block long
580 if Z_PER_ELEM:
581 (i-1)*(i-1)*(k-1) for the block long
583 Notes:
584 -----
585 * Not called unless Num_structured_blocks is > 0,
586 Num_variables is > 0, and there are some vector type variables
588 * The per_node or per_elem classification must be obtainable from the
589 variable number (a var_classify array needs to be retained)
591 * Will be based on Current_time_step
595 --------------------------------------------------------------------
596 USERD_get_changing_geometry_status
598 Description:
599 -----------
600 Gets the changing geometry status for the model
602 Specification:
603 -------------
604 int USERD_get_changing_geometry_status( void )
606 Returns:
607 -------
608 Z_STATIC if geometry does not change
609 Z_CHANGE_COORDS if changing coordinates only
610 Z_CHANGE_CONN if changing connectivity
612 Arguments:
613 ---------
614 none
616 Notes:
617 -----
618 * EnSight does not support changing number of parts. But the
619 coords and/or the connectivity of the parts can change.
623 --------------------------------------------------------------------
624 USERD_get_constant_value
626 Description:
627 -----------
628 Get the value of a constant at a time step
630 Specification:
631 -------------
632 float USERD_get_constant_value(int which_var)
634 Returns:
635 -------
636 Value of the requested constant variable
638 Arguments:
639 ---------
640 (IN) which_var = The variable number
642 Notes:
643 -----
644 * Will be based on Current_time_step
648 --------------------------------------------------------------------
649 USERD_get_dataset_query_file_info
651 Description:
652 -----------
653 Get the information about files in the dataset. Used for the
654 dataset query option within EnSight.
656 Specification:
657 -------------
658 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
660 Returns:
661 -------
662 Z_OK if successful
663 Z_ERR if not successful
665 Arguments:
666 ---------
667 (OUT) qfiles = Structure containing information about each file
668 of the dataset. The Z_QFILES structure is defined
669 in the global_extern.h file
671 (The structure will have been allocated
672 Num_dataset_files long, with 10 description
673 lines per file).
675 qfiles[].name = The name of the file
676 (Z_MAXFILENP is the dimensioned length
677 of the name)
679 qfiles[].sizeb = The number of bytes in the file
680 (Typically obtained with a call to the
681 "stat" system routine) (Is a long)
683 qfiles[].timemod = The time the file was last modified
684 (Z_MAXTIMLEN is the dimensioned length
685 of this string)
686 (Typically obtained with a call to the
687 "stat" system routine)
689 qfiles[].num_d_lines = The number of description lines you
690 are providing from the file. Max = 10
692 qfiles[].f_desc[] = The description line(s) per file,
693 qfiles[].num_d_lines of them
694 (Z_MAXFILENP is the allocated length of
695 each line)
697 Notes:
698 -----
699 * If Num_dataset_files is 0, this routine will not be called.
703 --------------------------------------------------------------------
704 USERD_get_description_lines
706 Description:
707 -----------
708 Get two description lines associated with geometry per time step,
709 or one description line associated with a variable per time step.
711 Specification:
712 -------------
713 int USERD_get_description_lines(int which_type,
714 int which_var,
715 char line1[Z_BUFL],
716 char line2[Z_BUFL])
718 Returns:
719 -------
720 Z_OK if successful
721 Z_ERR if not successful
723 Arguments:
724 ---------
725 (IN) which_type = Z_GEOM for geometry (2 lines)
726 = Z_VARI for variable (1 line)
728 (IN) which_var = If it is a variable, which one.
729 Ignored if geometry type.
731 (OUT) line1 = The 1st geometry description line,
732 or the variable description line.
734 (OUT) line2 = The 2nd geometry description line
735 Not used if variable type.
737 Notes:
738 -----
739 * Will be based on Current_time_step
741 * These are the lines EnSight can echo to the screen in
742 annotation mode.
746 --------------------------------------------------------------------
747 USERD_get_element_connectivities_for_part
749 Description:
750 -----------
751 Gets the connectivities for the elements of an unstructured part
753 Specification:
754 -------------
755 int USERD_get_element_connectivities_for_part(int part_number,
756 int **conn_array[Z_MAXTYPE])
758 Returns:
759 -------
760 Z_OK if successful
761 Z_ERR if not successful
763 Arguments:
764 ---------
765 (IN) part_number = The part number
767 (OUT) conn_array = 3D array containing connectivity
768 of each element of each type.
770 (Array will have been allocated
771 Z_MAXTYPE by num_of_elements of
772 each type by connectivity length
773 of each type)
775 ex) If num_of_elements[Z_TRI03] = 25
776 num_of_elements[Z_QUA04] = 100
777 num_of_elements[Z_HEX08] = 30
778 as obtained in:
779 USERD_get_part_build_info
781 Then the allocated dimensions available
782 for this routine will be:
783 conn_array[Z_TRI03][25][3]
784 conn_array[Z_QUA04][100][4]
785 conn_array[Z_HEX08][30][8]
787 Notes:
788 -----
789 * Not called unless Num_unstructured_parts is > 0
791 * Will be based on Current_time_step
793 * The coord_array loaded in USERD_get_global_coords is zero-based,
794 but within EnSight it will become a one-based array.
795 Thus, coord_array[0] will be accessed by node 1 from the conn_array,
796 coord_array[1] will be accessed by node 2 from the conn_array, etc.
798 ex) Given a model of two triangles, you should load coord_array in
799 USERD_get_global_coords as follows:
801 node coordinates
802 ---- -----------
803 4 --------- 3 1 coord_array[0].xyz[0] = 0.0
804 |\ | coord_array[0].xyz[1] = 0.0
805 | \ T2 | coord_array[0].xyz[2] = 0.0
806 | \ |
807 | \ | 2 coord_array[1].xyz[0] = 1.0
808 | \ | coord_array[1].xyz[1] = 0.0
809 | \ | coord_array[1].xyz[2] = 0.0
810 | \ |
811 | T1 \ | 3 coord_array[2].xyz[0] = 1.0
812 | \| coord_array[2].xyz[1] = 1.6
813 1 --------- 2 coord_array[2].xyz[2] = 0.0
815 4 coord_array[3].xyz[0] = 0.0
816 coord_array[3].xyz[1] = 1.6
817 coord_array[3].xyz[2] = 0.0
820 And conn_array here as follows:
822 Triangle Connectivity
823 -------- ------------
824 T1 conn_array[Z_TRI03][0][0] = 1
825 conn_array[Z_TRI03][0][1] = 2
826 conn_array[Z_TRI03][0][2] = 4
828 T2 conn_array[Z_TRI03][1][0] = 2
829 conn_array[Z_TRI03][1][1] = 3
830 conn_array[Z_TRI03][1][2] = 4
834 --------------------------------------------------------------------
835 USERD_get_element_ids_for_part
837 Description:
838 -----------
839 Gets the ids for the elements of an unstructured part.
841 Specification:
842 -------------
843 int USERD_get_element_ids_for_part(int part_number,
844 int *elemid_array[Z_MAXTYPE])
846 Returns:
847 -------
848 Z_OK if successful
849 Z_ERR if not successful
851 Arguments:
852 ---------
853 (IN) part_number = The part number
855 (OUT) elemid_array = 2D array containing id of each
856 element of each type.
858 (Array will have been allocated
859 Z_MAXTYPE by num_of_elements of
860 each type)
862 ex) If num_of_elements[Z_TRI03] = 25
863 num_of_elements[Z_QUA04] = 100
864 num_of_elements[Z_HEX08] = 30
865 as obtained in:
866 USERD_get_part_build_info
868 Then the allocated dimensions available
869 for this routine will be:
870 conn_array[Z_TRI03][25]
871 conn_array[Z_QUA04][100]
872 conn_array[Z_HEX08][30]
874 Notes:
875 -----
876 * Not called unless Num_unstructured_parts is > 0 and element
877 label status is TRUE
879 * Will be based on Current_time_step
883 --------------------------------------------------------------------
884 USERD_get_element_label_status
886 Description:
887 -----------
888 Answers the question as to whether element labels will be provided.
890 Specification:
891 -------------
892 int USERD_get_element_label_status( void )
894 Returns:
895 -------
896 TRUE if element labels will be provided
897 FALSE if element labels will NOT be provided
899 Arguments:
900 ---------
901 none
903 Notes:
904 -----
905 * element lables are needed in order to do any element querying, or
906 element labeling on-screen within EnSight.
908 For unstructured parts, you can read them from your file if
909 available, or can assign them, etc. They need to be unique
910 per part, and are often unique per model.
912 USERD_get_element_ids_for_part is used to obtain the ids,
913 on a part by part basis, if TRUE status is returned here.
915 For structured parts, EnSight will assign ids if you return a
916 status of TRUE here. You cannot assign them youself!!
920 --------------------------------------------------------------------
921 USERD_get_global_coords
923 Description:
924 -----------
925 Gets the coordinates for the global nodes.
927 Specification:
928 -------------
929 int USERD_get_global_coords(CRD *coord_array)
931 Returns:
932 -------
933 Z_OK if successful
934 Z_ERR if not successful
936 Arguments:
937 ---------
938 (OUT) coord_array = 1D array of CRD structures,
939 which contains x,y,z coordinates
940 of each node.
942 (Array will have been allocated
943 Num_global_nodes long)
945 For reference, CRD structure (which is in global_extern) is:
947 typedef struct {
948 float xyz[3];
949 }CRD;
951 Notes:
952 -----
953 * Not called unless Num_unstructured_parts is > 0
955 * Will be based on Current_time_step
957 * The coord_array is zero-based, but within EnSight it will become
958 a one-based array.
959 Thus, coord_array[0] will be accessed by node 1 from the conn_array,
960 coord_array[1] will be accessed by node 2 from the conn_array, etc.
962 ex) Given a model of two triangles, you should load coord_array as
963 follows:
965 node coordinates
966 ---- -----------
967 4 --------- 3 1 coord_array[0].xyz[0] = 0.0
968 |\ | coord_array[0].xyz[1] = 0.0
969 | \ T2 | coord_array[0].xyz[2] = 0.0
970 | \ |
971 | \ | 2 coord_array[1].xyz[0] = 1.0
972 | \ | coord_array[1].xyz[1] = 0.0
973 | \ | coord_array[1].xyz[2] = 0.0
974 | \ |
975 | T1 \ | 3 coord_array[2].xyz[0] = 1.0
976 | \| coord_array[2].xyz[1] = 1.6
977 1 --------- 2 coord_array[2].xyz[2] = 0.0
979 4 coord_array[3].xyz[0] = 0.0
980 coord_array[3].xyz[1] = 1.6
981 coord_array[3].xyz[2] = 0.0
984 And conn_array in USERD_get_element_connectivities_for_part
985 as follows:
987 Triangle Connectivity
988 -------- ------------
989 T1 conn_array[Z_TRI03][0][0] = 1
990 conn_array[Z_TRI03][0][1] = 2
991 conn_array[Z_TRI03][0][2] = 4
993 T2 conn_array[Z_TRI03][1][0] = 2
994 conn_array[Z_TRI03][1][1] = 3
995 conn_array[Z_TRI03][1][2] = 4
997 --------------------------------------------------------------------
998 USERD_get_global_node_ids
1000 Description:
1001 -----------
1002 Gets the node ids assigned to each of the global nodes.
1004 Specification:
1005 -------------
1006 int USERD_get_global_node_ids(int *nodeid_array)
1008 Returns:
1009 -------
1010 Z_OK if successful
1011 Z_ERR if not successful
1013 Arguments:
1014 ---------
1015 (OUT) nodeid_array = 1D array containing node ids of
1016 each node. The ids must be > 0
1018 (Array will have been allocated
1019 Num_global_nodes long)
1020 Notes:
1021 -----
1022 * Not called unless Num_unstructured_parts is > 0 and node label
1023 status is TRUE
1025 * Will be based on Current_time_step
1029 --------------------------------------------------------------------
1030 USERD_get_name_of_reader
1032 Description:
1033 -----------
1034 Gets the name of your user defined reader. The user interface will
1035 ask for this and include it in the available reader list.
1037 Specification:
1038 -------------
1039 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1040 int *two_fields)
1042 Returns:
1043 -------
1044 Z_OK if successful
1045 Z_ERR if not successful
1047 Arguments:
1048 ---------
1049 (OUT) reader_name = the name of the your reader or data format.
1050 (max length is Z_MAX_USERD_NAME, which is 20)
1052 (OUT) *two_fields = FALSE if only one data field required
1053 in the data dialog of EnSight.
1054 TRUE if two data fields required.
1056 Notes:
1057 -----
1058 * Always called. Provide a name for your custom reader format.
1060 * If you don't want a custom reader to show up in the data dialog
1061 choices, return a name of "No_Custom"
1065 --------------------------------------------------------------------
1066 USERD_get_node_label_status
1068 Description:
1069 -----------
1070 Answers the question as to whether node labels will be provided.
1072 Specification:
1073 -------------
1074 int USERD_get_node_label_status( void )
1076 Returns:
1077 -------
1078 TRUE if node labels will be provided
1079 FALSE if node labels will NOT be provided
1081 Arguments:
1082 ---------
1083 none
1085 Notes:
1086 -----
1087 * Node ids are needed in order to do any node querying, or node
1088 labeling on-screen within EnSight.
1090 For unstructured parts, you can read them from your file if
1091 available, or can assign them, etc. They need to be unique
1092 per part, and are often unique per model. The must also be
1093 positive numbers greater than zero.
1095 USERD_get_global_node_ids is used to obtain the ids, if the
1096 status returned here is TRUE.
1098 Also be aware that if you say node labels are available,
1099 the connectivity of elements must be according to these
1100 node ids.
1102 For structured parts, EnSight will assign ids if you return a
1103 status of TRUE here. You cannot assign them yourself!!
1107 --------------------------------------------------------------------
1108 USERD_get_number_of_files_in_dataset
1110 Description:
1111 -----------
1112 Get the total number of files in the dataset. Used for the
1113 dataset query option within EnSight.
1115 Specification:
1116 -------------
1117 int USERD_get_number_of_files_in_dataset( void )
1119 Returns:
1120 -------
1121 The total number of files in the dataset.
1123 Arguments:
1124 ---------
1125 none
1127 Notes:
1128 -----
1129 * You can be as complete as you want about this. If you don't
1130 care about the dataset query option, return a value of 0
1131 If you only want certain files, you can just include them. But,
1132 you will need to supply the info in USERD_get_dataset_query_file_info
1133 for each file you include here.
1135 * Num_dataset_files would be set here
1139 --------------------------------------------------------------------
1140 USERD_get_number_of_global_nodes
1142 Description:
1143 -----------
1144 Gets the number of global nodes, used for unstructured parts.
1146 Specification:
1147 -------------
1148 int USERD_get_number_of_global_nodes()
1150 Returns:
1151 -------
1152 Number of global nodes (>=0 if okay, <0 if problems)
1154 Arguments:
1155 ---------
1156 none
1158 Notes:
1159 -----
1160 * Not called unless Num_unstructured_parts is > 0
1162 * Will be based on Current_time_step
1164 * For unstructured data:
1165 EnSight wants 1. A global array of nodes
1166 2. Element connectivities by part, which
1167 reference the node numbers of the global
1168 node array.
1169 IMPORTANT:
1170 ---------
1171 If you provide node ids, then element connectivities
1172 must be in terms of the node ids. If you do not
1173 provide node ids, then element connectivities must be
1174 in terms of the index into the node array, but shifted
1175 to start at 1
1177 * Num_global_nodes would be set here
1181 --------------------------------------------------------------------
1182 USERD_get_number_of_model_parts
1184 Description:
1185 -----------
1186 Gets the total number of unstructured and structured parts
1187 in the model, for which you can supply information.
1189 Specification:
1190 -------------
1191 int USERD_get_number_of_model_parts( void )
1193 Returns:
1194 -------
1195 Number of parts (>0 if okay, <=0 if probs).
1197 Arguments:
1198 ---------
1199 none
1201 Notes:
1202 -----
1203 * If going to have to read down through the parts in order to
1204 know how many, you may want to build a table of pointers to
1205 the various parts, so you can easily get to particular parts in
1206 later processes. If you can simply read the number of parts
1207 at the head of the file, then you would probably not build the
1208 table at this time.
1210 * This routine would set Numparts_available, which is equal to
1211 Num_unstructured_parts + Num_structured_blocks.
1215 --------------------------------------------------------------------
1216 USERD_get_number_of_time_steps
1218 Description:
1219 -----------
1220 Gets the number of time steps of data available.
1222 Specification:
1223 -------------
1224 int USERD_get_number_of_time_steps( void )
1226 Returns:
1227 -------
1228 Number of time steps (>0 if okay, <=0 if problems).
1230 Arguments:
1231 ---------
1232 none
1234 Notes:
1235 -----
1236 * This should be >= 1 1 indicates a static model
1237 >1 indicates a transient model
1239 * Num_time_steps would be set here
1243 --------------------------------------------------------------------
1244 USERD_get_number_of_variables
1246 Description:
1247 -----------
1248 Get the number of variables for which you will be providing info.
1250 Specification:
1251 -------------
1252 int USERD_get_number_of_variables( void )
1254 Returns:
1255 -------
1256 Number of variables (includes constant, scalar, and vector types)
1257 (>=0 if okay, <0 if problem)
1259 Arguments:
1260 ---------
1261 none
1263 Notes:
1264 -----
1265 *****************************************************************
1266 * Variable numbers, by which references will be made, are implied
1267 here. If you say there are 3 variables, the variable numbers
1268 will be 1, 2, and 3.
1269 *****************************************************************
1271 * Num_variables would be set here
1275 --------------------------------------------------------------------
1276 USERD_get_part_build_info
1278 Description:
1279 -----------
1280 Gets the info needed for the part building process.
1282 Specification:
1283 -------------
1284 int USERD_get_part_build_info(int *part_numbers,
1285 int *part_types,
1286 char *part_description[Z_BUFL],
1287 int *number_of_elements[Z_MAXTYPE],
1288 int *ijk_dimensions[3],
1289 int *iblanking_options[6])
1291 Returns:
1292 -------
1293 Z_OK if successful
1294 Z_ERR if not successful
1296 Arguments:
1297 ---------
1298 (OUT) part_numbers = Array containing part numbers for
1299 each of the model parts.
1301 IMPORTANT:
1302 Parts numbers must be >= 1
1304 ********************************************
1305 The numbers provided here are the ones by
1306 which the parts will be referred to in any
1307 of the other routines which receive a part
1308 number or block number as an argument!!
1309 ********************************************
1311 (Array will have been allocated
1312 Numparts_available long)
1314 (OUT) part_types = Array containing one of the
1315 following for each model part:
1317 Z_UNSTRUCTURED or
1318 Z_STRUCTURED or
1319 Z_IBLANKED
1321 (Array will have been allocated
1322 Numparts_available long)
1324 (OUT) part_description = Array containing a description
1325 for each of the model parts
1327 (Array will have been allocated
1328 Numparts_available by Z_BUFL
1329 long)
1331 (OUT) number_of_elements = 2D array containing number of
1332 each type of element for each
1333 unstructured model part.
1334 ------------
1335 Possible types are:
1337 Z_POINT = point
1338 Z_BAR02 = 2-noded bar
1339 Z_BAR03 = 3-noded bar
1340 Z_TRI03 = 3-noded triangle
1341 Z_TRI06 = 6-noded triangle
1342 Z_QUA04 = 4-noded quadrilateral
1343 Z_QUA08 = 8-noded quadrilateral
1344 Z_TET04 = 4-noded tetrahedron
1345 Z_TET10 = 10-noded tetrahedron
1346 Z_PYR05 = 5-noded pyramid
1347 Z_PYR13 = 13-noded pyramid
1348 Z_PEN06 = 6-noded pentahedron
1349 Z_PEN15 = 15-noded pentahedron
1350 Z_HEX08 = 8-noded hexahedron
1351 Z_HEX20 = 20-noded hexahedron
1353 (Ignored unless Z_UNSTRUCTURED type)
1355 (Array will have been allocated
1356 Numparts_available by
1357 Z_MAXTYPE long)
1359 (OUT) ijk_dimensions = 2D array containing ijk dimensions
1360 for each structured model part.
1361 ----------
1362 (Ignored if Z_UNSTRUCTURED type)
1364 (Array will have been allocated
1365 Numparts_available by 3 long)
1367 ijk_dimensions[][0] = I dimension
1368 ijk_dimensions[][1] = J dimension
1369 ijk_dimensions[][2] = K dimension
1371 (OUT) iblanking_options = 2D array containing iblanking
1372 options possible for each
1373 structured model part.
1374 ----------
1375 (Ignored unless Z_IBLANKED type)
1377 (Array will have been allocated
1378 Numparts_available by 6 long)
1380 iblanking_options[][Z_EXT] = TRUE if external (outside)
1381 [][Z_INT] = TRUE if internal (inside)
1382 [][Z_BND] = TRUE if boundary
1383 [][Z_INTBND] = TRUE if internal boundary
1384 [][Z_SYM] = TRUE if symmetry surface
1387 Notes:
1388 -----
1389 * If you haven't built a table of pointers to the different parts,
1390 you might want to do so here as you gather the needed info.
1392 * Will be based on Current_time_step
1396 --------------------------------------------------------------------
1397 USERD_get_scalar_values
1399 Description:
1400 -----------
1401 if Z_PER_NODE:
1402 Get the values at each global node for a given scalar variable.
1404 or if Z_PER_ELEM:
1405 Get the values at each element of a specific part and type for a
1406 given scalar variable.
1408 Specification:
1409 -------------
1410 int USERD_get_scalar_values(int which_scalar,
1411 int which_part,
1412 int which_type,
1413 float *scalar_array)
1415 Returns:
1416 -------
1417 Z_OK if successful
1418 Z_ERR if not successful
1420 Arguments:
1421 ---------
1422 (IN) which_scalar = The variable number (of scalar type)
1424 (IN) which_part
1426 if Z_PER_NODE: Not used
1428 if Z_PER_ELEM: = The part number
1430 (IN) which_type
1432 if Z_PER_NODE: Not used
1434 if Z_PER_ELEM: = The element type
1436 (OUT) scalar_array
1438 if Z_PER_NODE: = 1D array containing scalar values
1439 for each node.
1441 (Array will have been allocated
1442 Num_global_nodes long)
1444 if Z_PER_ELEM: = 1d array containing scalar values for
1445 each element of a particular part and type.
1447 (Array will have been allocated
1448 number_of_elements[which_part][which_type]
1449 long. See USERD_get_part_build_info)
1451 Notes:
1452 -----
1453 * Not called unless Num_unstructured_parts is > 0,
1454 Num_variables is > 0, and you have some scalar type variables.
1456 * The per_node or per_elem classification must be obtainable from the
1457 variable number (a var_classify array needs to be retained)
1459 * Will be based on Current_time_step
1463 --------------------------------------------------------------------
1464 USERD_get_solution_times
1466 Description:
1467 -----------
1468 Get the solution times associated with each time step.
1470 Specification:
1471 -------------
1472 int USERD_get_solution_times(float *solution_times)
1474 Returns:
1475 -------
1476 Z_OK if successful
1477 Z_ERR if not successful
1479 Arguments:
1480 ---------
1481 (OUT) solution_times = 1D array of solution times/time step
1483 (Array will have been allocated
1484 Num_time_steps long)
1486 Notes:
1487 -----
1488 * The solution times must be non-negative and increasing.
1492 --------------------------------------------------------------------
1493 USERD_get_variable_info
1495 Description:
1496 -----------
1497 Get the variable descriptions, types and filenames
1499 Specification:
1500 -------------
1501 int USERD_get_variable_info(char **var_description,
1502 char **var_filename,
1503 int *var_type,
1504 int *var_classify)
1506 Returns:
1507 -------
1508 Z_OK if successful
1509 Z_ERR if not successful
1511 Arguments:
1512 ---------
1513 (OUT) var_description = Variable descriptions
1515 (Array will have been allocated
1516 Num_variables by Z_BUFL long)
1518 (OUT) var_filename = Variable filenames
1520 (Array will have been allocated
1521 Num_variables by Z_BUFL long)
1523 (OUT) var_type = Variable type
1525 (Array will have been allocated
1526 Num_variables long)
1528 types are: Z_CONSTANT
1529 Z_SCALAR
1530 Z_VECTOR
1532 (OUT) var_classify = Variable classification
1534 (Array will have been allocated
1535 Num_variables long)
1537 types are: Z_PER_NODE
1538 Z_PER_ELEM
1540 Notes:
1541 -----
1542 * The implied variable numbers apply, but be aware that the
1543 arrays are zero based.
1544 So for variable 1, will need to provide var_description[0]
1545 var_filename[0]
1546 var_type[0]
1547 var_classify[0]
1549 for variable 2, will need to provide var_description[1]
1550 var_filename[1]
1551 var_type[1]
1552 var_classify[1]
1553 etc.
1557 --------------------------------------------------------------------
1558 USERD_get_variable_value_at_specific
1560 Description:
1561 -----------
1562 if Z_PER_NODE:
1563 Get the value of a particular variable at a particular node in a
1564 particular part at a particular time.
1566 or if Z_PER_ELEM:
1567 Get the value of a particular variable at a particular element of
1568 a particular type in a particular part at a particular time.
1571 Specification:
1572 -------------
1573 int USERD_get_variable_value_at_specific(int which_var,
1574 int which_node_or_elem,
1575 int which_part,
1576 int which_elem_type,
1577 int time_step,
1578 float values[3])
1580 Returns:
1581 -------
1582 Z_OK if successful
1583 Z_ERR if not successful
1585 Arguments:
1586 ---------
1587 (IN) which_var = The variable number
1589 (IN) which_node_or_elem
1591 If Z_PER_NODE:
1592 = The node number. This is not the id, but is
1593 the index of the global node
1594 list (1 based), or the block's
1595 node list (1 based).
1597 Thus, coord_array[1]
1598 coord_array[2]
1599 coord_array[3]
1600 . |
1601 . |which_node_or_elem index
1602 . ----
1605 If Z_PER_ELEM:
1606 = The element number. This is not the id, but is
1607 the element number index
1608 of the number_of_element array
1609 (see USERD_get_part_build_info),
1610 or the block's element list
1611 zzzzz (1 based).
1613 Thus, for which_part:
1614 conn_array[which_elem_type][0]
1615 conn_array[which_elem_type][1]
1616 conn_array[which_elem_type][2]
1617 . |
1618 . which_node_or_elem index
1619 . ----
1622 (IN) which_part
1624 If Z_PER_NODE, or block part:
1625 = Not used
1627 If Z_PER_ELEM:
1628 = The part number
1630 (IN) which_elem_type
1632 If Z_PER_NODE, or block part:
1633 = Not used
1635 If Z_PER_ELEM:
1636 = The element type. This is the element type index
1637 of the number_of_element array
1638 (see USERD_get_part_build_info)
1640 (IN) time_step = The time step
1642 (OUT) values = scalar or vector component value(s)
1643 values[0] = scalar or vector[0]
1644 values[1] = vector[1]
1645 values[2] = vector[2]
1648 Notes:
1649 -----
1650 * This routine is used in node querys over time (or element querys over
1651 time for Z_PER_ELEM variables). If these operations are not critical
1652 to you, this can be a dummy routine.
1654 * The per_node or per_elem classification must be obtainable from the
1655 variable number (a var_classify array needs to be retained)
1658 --------------------------------------------------------------------
1659 USERD_get_vector_values
1661 Description:
1662 -----------
1663 if Z_PER_NODE:
1664 Get the values at each global node for a given vector variable.
1666 or if Z_PER_ELEM:
1667 Get the values at each element of a specific part and type for a
1668 given vector variable.
1670 Specification:
1671 -------------
1672 int USERD_get_vector_values(int which_vector,
1673 int which_part,
1674 int which_type,
1675 float *vector_array)
1677 Returns:
1678 -------
1679 Z_OK if successful
1680 Z_ERR if not successful
1682 Arguments:
1683 ---------
1684 (IN) which_vector = The variable number
1686 (IN) which_part
1688 if Z_PER_NODE: Not used
1690 if Z_PER_ELEM: = The part number
1692 (IN) which_type
1694 if Z_PER_NODE: Not used
1696 if Z_PER_ELEM: = The element type
1698 (OUT) vector_array
1700 if Z_PER_NODE: = 1D array containing vector values
1701 for each node.
1703 (Array will have been allocated
1704 3 by Num_global_nodes long)
1706 Info stored in this fashion:
1707 vector_array[0] = xcomp of node 1
1708 vector_array[1] = ycomp of node 1
1709 vector_array[2] = zcomp of node 1
1711 vector_array[3] = xcomp of node 2
1712 vector_array[4] = ycomp of node 2
1713 vector_array[5] = zcomp of node 2
1715 vector_array[6] = xcomp of node 3
1716 vector_array[7] = ycomp of node 3
1717 vector_array[8] = zcomp of node 3
1718 etc.
1720 if Z_PER_ELEM: = 1d array containing vector values for
1721 each element of a particular part and type.
1723 (Array will have been allocated
1724 3 by number_of_elements[which_part][which_type]
1725 long. See USERD_get_part_build_info)
1727 Info stored in this fashion:
1728 vector_array[0] = xcomp of elem 1 (of part and type)
1729 vector_array[1] = ycomp of elem 1 "
1730 vector_array[2] = zcomp of elem 1 "
1732 vector_array[3] = xcomp of elem 2 "
1733 vector_array[4] = ycomp of elem 2 "
1734 vector_array[5] = zcomp of elem 2 "
1736 vector_array[6] = xcomp of elem 3 "
1737 vector_array[7] = ycomp of elem 3 "
1738 vector_array[8] = zcomp of elem 3 "
1739 etc.
1741 Notes:
1742 -----
1743 * Not called unless Num_unstructured_parts is > 0,
1744 Num_variables is > 0, and you have some vector type variables
1746 * The per_node or per_elem classification must be obtainable from the
1747 variable number (a var_classify array needs to be retained)
1749 * Will be based on Current_time_step
1752 --------------------------------------------------------------------
1753 USERD_set_filenames
1755 Description:
1756 -----------
1757 Receives the geometry and result filenames entered in the data
1758 dialog. The user written code will have to store and use these
1759 as needed.
1761 Specification:
1762 -------------
1763 int USERD_set_filenames(char filename_1[],
1764 char filename_2[],
1765 char the_path[],
1766 int swapbytes)
1768 Returns:
1769 -------
1770 Z_OK if successful
1771 Z_ERR if not successful
1773 Arguments:
1774 ---------
1775 (IN) filename_1 = the filename entered into the geometry
1776 field of the data dialog.
1777 (IN) filename_2 = the filename entered into the result
1778 field of the data dialog.
1779 (If the two_fields flag in USERD_get_name_of_reader
1780 is FALSE, this will be null string)
1781 (IN) the_path = the path info from the data dialog.
1782 Note: filename_1 and filename_2 have already
1783 had the path prepended to them. This
1784 is provided in case it is needed for
1785 filenames contained in one of the files
1786 (IN) swapbytes = TRUE if should swap bytes when reading data.
1788 Notes:
1789 -----
1790 * Since you must manage everything from the input that is entered in
1791 these data dialog fields, this is an important routine!
1793 * It may be that you will need to have an executive type file that contains
1794 info and other filenames within it, like EnSight6's case file.
1798 --------------------------------------------------------------------
1799 USERD_set_time_step
1801 Description:
1802 -----------
1803 Set the current time step. All functions that need time, and
1804 that do not explicitly pass it in, will use the time step set by
1805 this routine.
1807 Specification:
1808 -------------
1809 void USERD_set_time_step(int time_step)
1811 Returns:
1812 -------
1813 nothing
1815 Arguments:
1816 ---------
1817 (IN) time_step - The current time step to set
1819 Notes:
1820 -----
1821 * Current_time_step would be set here
1825 --------------------------------------------------------------------
1826 USERD_stop_part_building
1828 Description:
1829 -----------
1830 This routine called when the part building dialog is closed. It is
1831 provided in case you desire to release memory, etc. that was only needed
1832 during the part building process.
1834 Specification:
1835 -------------
1836 void USERD_stop_part_building( void )
1838 Returns:
1839 -------
1840 nothing
1842 Arguments:
1843 ---------
1844 none
1846 Notes:
1847 -----