README_USERD_2.01 ================= -------------------------------------- EnSight User Defined Reader Capability ===> (API 2.01) -------------------------------------- A user defined reader capability is included in EnSight which can allow otherwise unsupported structured or unstructured data to be read. The user defined reader capability utilizes dynamic shared libraries composed of routines defined in this document but produced by you, the user, (or some third party). This capability is currently available for dec, ibm, hp, sgi, sun, linux, alpha linux, and NT servers. You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0 for a discussion of the differences between API 1.0 and API 2.*. ***>> API 2.01 adds the capabilty of handling ghost cells. API 2.01 (defined in this README_USERD_2.01 document) ======== This new API has been defined to be more efficient and includes access to new capabilities of EnSight 7.4. It lends itself closely to the EnSight "gold" type format. Some of its advantages are:: * Most intermediate temporary arrays have been eliminated, such that the user defined routines write directly into internal part structures. This is a considerable improvement in memory use, and improves speed as well since far less memory need be allocated, initialized, etc. * Parts are self contained. Coordinates, connectivity and all variables are provided on a part basis. This eliminates the need for several global to local coordinate mapping operations and the need for node id connectivity hashing. This can greatly improve the speed at which models are loaded. * Model extents can be provided directly, such that EnSight need not read all the coordinate data at load time. * Tensor variables are supported * Complex variables are supported * A routine is provided as EnSight exits, so cleanup operations such as removing temporary files can be easily accomplished. * Geometry and variables can be provided on different time lines (timesets). * If your data format already provides boundary shell information, you can use it instead of the "border" representation that EnSight would compute. * Ghost cells are supported, for both unstructured and structured models. **************************************************************************** Note: A default dummy_gold reader and an Ensight Gold example of this new 2.01 user defined reader API has been included with your EnSight release. Also, the SILO and ExodusII_gold reader included in the release utilizes the 2.01 API. **************************************************************************** The process for producing a user defined reader is: --------------------------------------------------- 1. Write code for all pertinent routines in the library (Unless someone else has done this for you). This is of course where the work is done by the user. The word "pertinent" is used because depending on the nature of the data, some of the routines in the library may be dummy routines. The source code for a dummy_gold library and for various other working or sample libraries is copied from the installation CD during installation. These will be located in directories under: $CEI_HOME/ensight76/user_defined_src/readers examples: -------- Basic dummy_gold routines provide skeleton for a new reader $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold Sample library which reads unstructured binary EnSight Gold data $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold You may find it useful to place your library source in this area as well, but are not limited to this location. * ===> The descriptions of each library routine and the order that the routines are called, which is provided in this file, along with the example libraries, should make it possible for you to produce code for your own data reader. 2. Produce the dynamic shared library. This is a compiling and loading process which varies according to the type of machine you are on. In the user-defined-reader source tree we have tried to isolate the machine dependent parts of the build process using a set of files in the 'config' directory. In this directory there is a configuration file for each platform on which EnSight is supported. Before you can compile the installed readers you should run the script called 'init' in the config directory. i.e. (for UNIX) cd config ./init sgi_6.5_n64 cd .. make If you are compiling for Windows NT, there are two options. If you have the Cygwin GNU utilities installed, you can use GNU make as for Unix. Otherwise, there is a script called makeall.cmd which will build all of the readers using nmake. The Makefiles in each reader directory will work using either make or nmake. i.e. (WIN32 Cygwin) (using nmake) cd config cd config sh init win32 cp win32 config cd .. cd .. mkdir lib make makeall.cmd If you have platform-specific portions of code in your reader, the build system defines a set of flags which can be used within #ifdef ... #endif regions in your source, as shown in the table below. Because the readers are now dynamically opened by EnSight, you may have to include dependent libraries on your link-line to avoid having unresolved symbols. If you are having problems with a reader, start ensight as "ensight7 -readerdbg" and you will get feedback on any problems encountered in loading a reader. If there are unresolved symbols, you need to find the library which contains the missing symbols and link it into your reader by adding it to the example link commands below. If you choose to use a different build environment for your reader, you should take care to use compatible compilation flags to ensure compatibilty with the EnSight executables, most notably on the SGI and HP-UX 11.0 platforms, which should use the following flags: sgi_6.2_o32: -mips2 sgi_6.2_n64: -mips4 -64 sgi_6.5_n32: -mips3 sgi_6.5_n64: -mips4 -64 hp_11.0_32: +DA2.0 hp_11.0_64: +DA2.0W ______________________________________________________________________ | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED | | TYPE |------------------------------------------------------------| | | LD COMMAND USED IN MAKEFILE | ====================================================================== ______________________________________________________________________ | sgi | -DSGI | libuserd-X.so | | |------------------------------------------------------------| | | ld -shared -all -o libuserd-X.so libuserd-X.o | ---------------------------------------------------------------------- ______________________________________________________________________ | hp | -DHP | libuserd-X.sl | | |------------------------------------------------------------| | | ld -b -o libuserd-X.sl libuserd-X.o | ---------------------------------------------------------------------- ______________________________________________________________________ | sun | -DSUN | libuserd-X.so | | |------------------------------------------------------------| | | ld -G -o libuserd-X.so libuserd-X.o | ---------------------------------------------------------------------- ______________________________________________________________________ | dec | -DDEC | libuserd-X.so | | |------------------------------------------------------------| | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc | ---------------------------------------------------------------------- ______________________________________________________________________ | linux | -DLINUX | libuserd-X.so | | |------------------------------------------------------------| | | ld -shared -o libuserd-X.so libuserd-X.o -lc | ---------------------------------------------------------------------- ______________________________________________________________________ | alpha | -DALINUX | libuserd-X.so | | linux |------------------------------------------------------------| | | ld -shared -o libuserd-X.so libuserd-X.o -lc | ---------------------------------------------------------------------- ______________________________________________________________________ | ibm | -DIBM | libuserd-X.so | | |------------------------------------------------------------| | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc | ---------------------------------------------------------------------- Once you have created your library, you should place it in a directory of your choice or in the standard reader location: $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers For example, if you created a reader for "mydata", you should create the reader libuserd-mydata.so and place the file in your own reader directory (see section 3 below) or in the standard location: $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so 3. By default EnSight will load all readers found in the directory: $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers Files with names "libuserd-X.so" (where X is a name unique to the reader) are assumed to be user-defined readers. There are two methods which can be used to supplement the default behavior. (1) A feature which is useful for site-level or user-level configuration is the optional environment variable $ENSIGHT7_READER. This variable directs EnSight to load all readers in the specified reader directory (you should probably specify a full path) before loading the built-in readers. If the same reader exists in both directories (as determined by the name returned by USERD_get_name_of_reader(), NOT by the filename), the locally configured reader will take precedence. (2) A useful feature for end-users is the use of the libuserd-devel reader. EnSight will search for a reader named libuserd-devel.so (.sl for HP or .dll for NT). This reader can exist anywhere in the library path (see below) of the user. This is useful for an individual actively developing a reader because the existence of a libuserd-devel library will take precedence over any other library which returns the same name from USERD_get_name_of_reader(). As an example, a site may install commonly used readers in a common location, and users can set the ENSIGHT7_READER variable to access them: setenv ENSIGHT7_READER /usr/local/lib/e7readers A user working on a new reader may compile the reader and place it in a directory specified by the library path: cp libuserd-myreader.so ~/lib/libuserd-devel.so setenv ~/lib:$ The user is responsible for correctly configuring the library path variable in order to make use of the libuserd-devel feature. The library environment variables used are: Machine type Environment variable to set ------------ --------------------------- sgi LD_LIBRARY_PATH dec LD_LIBRARY_PATH sun LD_LIBRARY_PATH linux LD_LIBRARY_PATH alpha linux LD_LIBRARY_PATH hp SHLIB_PATH ibm LIBPATH As always, EnSight support is available if you need it. ------------------------------- Quick Index of Library Routines ------------------------------- Generally Needed for UNSTRUCTURED data -------------------------------------- USERD_get_part_coords part's node coordinates USERD_get_part_node_ids part's node ids USERD_get_part_elements_by_type part's element connectivites USERD_get_part_element_ids_by_type part's element ids Generally Needed for BLOCK data -------------------------------------- USERD_get_block_coords_by_component block coordinates USERD_get_block_iblanking block iblanking values USERD_get_ghosts_in_block_flag block ghost cell existence? USERD_get_block_ghost_flags block ghost cell flags These routines, which formerly were only for unstructured data, will now also be called for structured data if you specify that ids will be given in the USERD_get_node_label_status and USERD_get_element_label_status rotuines ------------------------------------------------------------------------------ USERD_get_part_node_ids part's node ids USERD_get_part_element_ids_by_type part's element ids Generally needed for either or both kinds of data ------------------------------------------------- USERD_get_name_of_reader name of reader for GUI USERD_get_reader_version provide reader version number USERD_get_reader_descrip provide GUI more description(optional) USERD_set_filenames filenames entered in GUI USERD_set_server_number server which of how many USERD_get_number_of_timesets number of timesets USERD_get_timeset_description description of timeset USERD_get_geom_timeset_number timeset # to use for geom USERD_get_num_of_time_steps number of time steps USERD_get_sol_times solution time values USERD_set_time_set_and_step current timeset and time step USERD_get_changing_geometry_status changing geometry? USERD_get_node_label_status node labels? USERD_get_element_label_status element labels? USERD_get_model_extents provide model bounding extents USERD_get_number_of_files_in_dataset number of files in model USERD_get_dataset_query_file_info info about each model file USERD_get_descrip_lines file associated description lines USERD_get_number_of_model_parts number of model parts USERD_get_part_build_info part/block type/descrip etc. USERD_get_maxsize_info part/block allocation maximums USERD_get_ghosts_in_model_flag model contains ghost cells? USERD_get_border_availability part border provided? USERD_get_border_elements_by_type part border conn and parent info USERD_get_number_of_variables number of variables USERD_get_gold_variable_info variable type/descrip etc. USERD_get_var_by_component part or block variable values USERD_get_constant_val constant variable's value USERD_get_var_value_at_specific node's or element's variable value over time USERD_stop_part_building cleanup after part build routine USERD_bkup archive routine USERD_exit_routine cleanup upon exit routine ------------------------- Order Routines are called ------------------------- The various main operations are given basically in the order they will be performed. Within each operation, the order the routines will be called is given. 1. Setting name in the gui, and specifying one or two input fields USERD_get_name_of_reader USERD_get_reader_descrip (optional) 2. Getting the reader version (also distinguishes between API's) USERD_get_reader_version 3. Setting filenames and getting timeset and time info USERD_set_server_number USERD_set_filenames USERD_get_number_of_timesets USERD_get_geom_timeset_number for each timeset: USERD_get_timeset_description USERD_get_num_of_time_steps USERD_get_sol_times USERD_set_time_set_and_step 4. Gathering info for part builder USERD_set_time_set_and_step USERD_get_changing_geometry_status USERD_get_node_label_status USERD_get_element_label_status USERD_get_number_of_files_in_dataset USERD_get_dataset_query_file_info USERD_get_descrip_lines (for geometry) USERD_get_number_of_model_parts USERD_get_gold_part_build_info USERD_get_ghosts_in_model_flag USERD_get_maxsize_info USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) USERD_get_model_extents OR (for model extents) USERD_get_part_coords AND/OR USERD_get_block_coords_by_component 5. Gathering Variable info USERD_get_number_of_variables USERD_get_gold_variable_info 6. Part building (per part created) both unstructured and structured: -------------------------------- USERD_set_time_set_and_step if unstructured part: -------------------- USERD_get_part_element_ids_by_type USERD_get_part_elements_by_type USERD_get_part_coords USERD_get_part_node_ids else if structured part: ----------------------- USERD_get_block_iblanking USERD_get_block_coords_by_component USERD_get_block_ghost_flags (If ghost cells in part) USERD_get_part_node_ids (If node ids given) USERD_get_part_element_ids_by_type (If element ids given) both again: ---------- USERD_get_border_availability (If border representation USERD_get_border_elements_by_type is selected) USERD_stop_part_building (only once when part builder dialog is closed) 7. Loading Variables constants: --------- USERD_set_time_set_and_step USERD_get_constant_val scalars/vectors/tensors: ------------------------ USERD_get_descrip_lines USERD_set_time_set_and_step USERD_get_var_by_component 8. Changing geometry changing coords only (per part): -------------------- USERD_set_time_set_and_step USERD_get_descrip_lines USERD_get_part_coords USERD_get_block_coords_by_component changing connectivity (per part): --------------------- USERD_set_time_set_and_step USERD_get_descrip_lines USERD_get_number_of_model_parts USERD_get_gold_part_build_info USERD_get_ghosts_in_model_flag USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) USERD_get_model_extents OR USERD_get_part_coords AND/OR USERD_get_block_coords_by_component USERD_get_part_element_ids_by_type USERD_get_part_elements_by_type USERD_get_part_coords USERD_get_part_node_ids USERD_get_block_iblanking USERD_get_block_coords_by_component USERD_get_block_ghost_flags (If ghost cells in part) USERD_get_part_node_ids (If node ids given) USERD_get_part_element_ids_by_type (If element ids given) USERD_get_border_availability (If border representation USERD_get_border_elements_by_type is selected) 9. Node or Element queries over time USERD_get_var_value_at_specific ----------------------- Detailed Specifications ----------------------- Include files: -------------- The following header file is required in any file containing these library routines. #include "global_extern.h" ******************************************************************************* ****************************** Special Note *********************************** ******************************************************************************* You must use the global_extern.h file associated with the proper release of EnSight when you build readers. Namely, this header file can change per EnSight release. For example, readers compiled for EnSight 7.3 will not run properly in EnSight 7.4 and vica versa because there was a critical change in the global_extern.h file between these two versions. In most cases the only thing needed to produce a workable reader is to remake it with the proper header file. ******************************************************************************* ******************************************************************************* Basis of arrays: --------------- Unless explicitly stated otherwise, all arrays are zero based - in true C fashion. Global variables: ---------------- You will generally need to have a few global variables which are shared by the various library routines. The detailed specifications below have assumed the following are available. (Their names describe their purpose, and they will be used in helping describe the details of the routines below). static int Numparts_available = 0; static int Num_unstructured_parts = 0; static int Num_structured_blocks = 0; /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */ static int Num_timesets = 1; static int Current_timeset = 1; static int Geom_timeset_number = 1; static int Num_time_steps[Z_MAXSETS] = 1; static int Current_time_step = 0; static int Num_variables = 0; static int Num_dataset_files = 0; static int Server_Number = 1; Which server of static int Tot_Servers = 1; the total number of servers _________________________________________ ----------------------------------------- Library Routines (in alphabetical order): _________________________________________ ----------------------------------------- -------------------------------------------------------------------- USERD_bkup Description: ----------- This routine is called during the EnSight archive process. You can use it to save or restore info relating to your user defined reader. Specification: ------------- int USERD_bkup(FILE *archive_file, int backup_type) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) archive_file = The archive file pointer (IN) backup_type = Z_SAVE_ARCHIVE for saving archive Z_REST_ARCHIVE for restoring archive Notes: ----- * Since EnSight's archive file is saved in binary form, you should also do any writing to it or reading from it in binary. * You should archive any variables, which will be needed for future operations, that will not be read or computed again before they will be needed. These are typically global variables. * Make sure that the number of bytes that you write on a save and the number of bytes that you read on a restore are identical!! * If any of the variables you save are allocated arrays, you must do the allocations before restoring into them. -------------------------------------------------------------------- USERD_exit_routine Description: ----------- This routine is called as EnSight is exiting. It can be used to clean up anything needed - such as removing temporary files, etc. - or can simply be a dummy. Specification: ------------- void USERD_exit_routine( void ) Arguments: --------- none -------------------------------------------------------------------- USERD_get_block_coords_by_component Description: ----------- Get the coordinates of a given structured block, a component at a time. Specification: ------------- int USERD_get_block_coords_by_component(int block_number, int which_component, float *coord_array) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) block_number = The block part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (IN) which_component = Z_COMPX if x component wanted = Z_COMPY if y component wanted = Z_COMPZ if z component wanted (OUT) coord_array = 1D array containing x,y, or z coordinate component of each node (Array will have been allocated i*j*k for the block long) Notes: ----- * Not called unless Num_structured_blocks is > 0 * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_block_iblanking Description: ----------- Get the iblanking value at each node of a block (if the block is iblanked). Specification: ------------- int USERD_get_block_iblanking(int block_number, int *iblank_array) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) block_number = The block part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (OUT) iblank_array = 1D array containing iblank value for each node. (Array will have been allocated i*j*k for the block long) possible values are: Z_EXT = exterior Z_INT = interior Z_BND = boundary Z_INTBND = internal boundary Z_SYM = symmetry plane Notes: ----- * Not called unless Num_structured_blocks is > 0 and you have some iblanked blocks * Will be based on Current_time_step ---------------------------------------------------------------------- USERD_get_block_ghost_flags Description: ----------- Get the ghost_flags value at each element of a block containing ghost cells. Specification: ------------- int USERD_get_block_ghost_flags(int block_number, int *ghost_flags) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) block_number = The block number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (OUT) ghost_flags = 1D array containing ghost flag value for each block cell. (Array will have been allocated (i-1)*(j-1)*(k-1) for the block long) possible values are: 0 = non-ghost cell (normal cell) >0 = ghost cell Notes: ----- * This routine is new in the 2.01 API * This will be based on Current_time_step * Only called for structured "block" parts that have some ghost cells as indicated by the USERD_get_ghost_in_block_flag. The model must of course also have been indicated to have some ghost cells in the USERD_get_ghost_in_model_flag routine. * It is sufficient to set the value to be 1 to flag as a ghost cell, but the value can be any non-zero value, so you could use it to indicate which block or which server (for Server-of-server use) the cell is actually in. -------------------------------------------------------------------- USERD_get_border_availability Description: ----------- Finds out if border elements are provided by the reader for the desired part, or will need to be computed internally by EnSight. Specification: ------------- int USERD_get_border_availability(int part_number, int number_of_elements[Z_MAXTYPE]) Returns: ------- Z_OK if border elements will be provided by the reader. (number_of_elements array will be loaded and USERD_get_border_elements_by_type will be called) Z_ERR if border elements are not available - thus EnSight must compute. (USERD_get_border_elements_by_type will not be called) Arguments: --------- (IN) part_number = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (OUT) number_of_elements = 2D array containing number of each type of border element in the part. ------------ Possible types are: Z_POINT = point Z_BAR02 = 2-noded bar Z_BAR03 = 3-noded bar Z_TRI03 = 3-noded triangle Z_TRI06 = 6-noded triangle Z_QUA04 = 4-noded quadrilateral Z_QUA08 = 8-noded quadrilateral Notes: ----- * Only called if border representation is used. * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_border_elements_by_type Description: ----------- Provides border element connectivity and parent information. Specification: ------------- int USERD_get_border_elements_by_type(int part_number, int element_type, int **conn_array, short *parent_element_type, int *parent_element_num) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) part_number = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (IN) element_type = One of the following (See global_extern.h) Z_POINT node point element Z_BAR02 2 node bar Z_BAR03 3 node bar Z_TRI03 3 node triangle Z_TRI06 6 node triangle Z_QUA04 4 node quad Z_QUA08 8 node quad (OUT) conn_array = 2D array containing connectivity of each border element of the type. (Array will have been allocated num_of_elements of the type by connectivity length of the type) ex) If number_of_elements[Z_TRI03] = 25 number_of_elements[Z_QUA04] = 100 number_of_elements[Z_QUA08] = 30 as obtained in: USERD_get_border_availability Then the allocated dimensions available for this routine will be: conn_array[25][3] when called with Z_TRI03 conn_array[100][4] when called with Z_QUA04 conn_array[30][8] when called with Z_QUA08 (OUT) parent_element_type = 1D array containing element type of the parent element (the one that the border element is a face/edge of). (Array will have been allocated num_of_elements of the type long) (OUT) parent_element_num = 1D array containing element number of the parent element (the one that the border element is a face/edge of). (Array will have been allocated num_of_elements of the type long) Notes: ----- * Not called unless USERD_get_border_availability returned Z_OK * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_changing_geometry_status Description: ----------- Gets the changing geometry status for the model Specification: ------------- int USERD_get_changing_geometry_status( void ) Returns: ------- Z_STATIC if geometry does not change Z_CHANGE_COORDS if changing coordinates only Z_CHANGE_CONN if changing connectivity Arguments: --------- none Notes: ----- * EnSight does not support changing number of parts. But the coords and/or the connectivity of the parts can change. Note that a part is allowed to be empty (number of nodes and elements equal to zero). -------------------------------------------------------------------- USERD_get_constant_val Description: ----------- Get the value of a constant at a time step Specification: ------------- float USERD_get_constant_value(int which_var, int imag_data) Returns: ------- Value of the requested constant variable Arguments: --------- (IN) which_var = The variable number (IN) imag_data = TRUE if want imaginary data value. FALSE if want real data value. Notes: ----- * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_dataset_query_file_info Description: ----------- Get the information about files in the dataset. Used for the dataset query option within EnSight. Specification: ------------- int USERD_get_dataset_query_file_info(Z_QFILES *qfiles) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (OUT) qfiles = Structure containing information about each file of the dataset. The Z_QFILES structure is defined in the global_extern.h file (The structure will have been allocated Num_dataset_files long, with 10 description lines per file). qfiles[].name = The name of the file (Z_MAXFILENP is the dimensioned length of the name) qfiles[].sizeb = The number of bytes in the file (Typically obtained with a call to the "stat" system routine) (Is a long) qfiles[].timemod = The time the file was last modified (Z_MAXTIMLEN is the dimensioned length of this string) (Typically obtained with a call to the "stat" system routine) qfiles[].num_d_lines = The number of description lines you are providing from the file. Max = 10 qfiles[].f_desc[] = The description line(s) per file, qfiles[].num_d_lines of them (Z_MAXFILENP is the allocated length of each line) Notes: ----- * If Num_dataset_files is 0, this routine will not be called. (See USERD_get_number_of_files_in_dataset) -------------------------------------------------------------------- USERD_get_descrip_lines Description: ----------- Get two description lines associated with geometry per time step, or one description line associated with a variable per time step. Specification: ------------- int USERD_get_descrip_lines(int which_type, int which_var, int imag_data, char line1[Z_BUFL], char line2[Z_BUFL]) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) which_type = Z_GEOM for geometry (2 lines) = Z_VARI for variable (1 line) (IN) which_var = If it is a variable, which one. Ignored if geometry type. (IN) imag_data = TRUE if want imaginary data file. FALSE if want real data file. (OUT) line1 = The 1st geometry description line, or the variable description line. (OUT) line2 = The 2nd geometry description line Not used if variable type. Notes: ----- * Will be based on Current_time_step * These are the lines EnSight can echo to the screen in annotation mode. -------------------------------------------------------------------- USERD_get_element_label_status Description: ----------- Answers the question as to whether element labels will be provided. Specification: ------------- int USERD_get_element_label_status( void ) Returns: ------- TRUE if element labels will be provided FALSE if element labels will NOT be provided Arguments: --------- none Notes: ----- * element lables are needed in order to do any element querying, or element labeling on-screen within EnSight. * Prior to API 2.01: ----------------- For unstructured parts, you can read them from your file if available, or can assign them, etc. They need to be unique per part, and are often unique per model. API 1.0: USERD_get_element_ids_for_part is used to obtain the ids, on a part by part basis, if TRUE status is returned here. API 2.0: USERD_get_part_element_ids_by_type is used to obtain the ids, on a per part, per type basis, if TRUE status is returned here. For structured parts, EnSight will assign ids if you return a status of TRUE here. You cannot assign them youself!! * Starting at API 2.01: -------------------- For both unstructured and structured parts, you can read them from your file if available, or can assign them, etc. They need to be unique per part, and are often unique per model (especially if you are dealing with a decomposed dataset). USERD_get_part_element_ids_by_type is used to obtain the ids, on an element type by part basis, if TRUE status is returned here. * Will call USERD_get_part_element_ids_by_type for each type of of each part if this routine returns TRUE. -------------------------------------------------------------------- USERD_get_geom_timeset_number - Description: ----------- Gets the timeset number to be used for geometry Specification: ------------- int USERD_get_geom_timeset_number( void ) Returns: ------- Geom_timeset_number = The timeset number that will be used for geometry. For example, if USERD_get_number_of timesets returns 2, the valid timeset numbers would be 1 or 2. Arguments: --------- none Notes: ----- * If your model is static, which you indicated by returning a zero in USERD_get_number_of_timesets, you can return a zero here as well. -------------------------------------------------------------------- USERD_get_gold_part_build_info Description: ----------- Gets the info needed for the part building process. Specification: ------------- int USERD_get_gold_part_build_info(int *part_id, int *part_types, char *part_description[Z_BUFL], int *number_of_nodes, int *number_of_elements[Z_MAXTYPE], int *ijk_dimensions[3], int *iblanking_options[6]) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (OUT) part_id = Array containing the external part ids for each of the model parts. IMPORTANT: Parts numbers must be >= 1, because of the way they are used in the GUI ******************************************* The ids provided here are the numbers by which the parts will be referred to in the GUI (if possible). They are basically labels as far as you are concerned. Note: The part numbers you pass to routines which receive a part_number or block_number or which_part as an argument are the 1-based table index of the parts! example: If Numparts_available = 3 Table index part_id ----------- ------- 1 13 2 57 3 125 ^ ^ | | | These are placed in: | part_id[0] = 13 | part_id[1] = 57 | part_id[2] = 125 | for GUI labeling purposes. | These implied table indices are the part_number, block_number, or which_part numbers that you would pass to routines like: USERD_get_part_coords(int part_number,... USERD_get_part_node_ids(int part_number,... USERD_get_part_elements_by_type(int part_number,... USERD_get_part_element_ids_by_type(int part_number,... USERD_get_block_coords_by_component(int block_number,... USERD_get_block_iblanking(int block_number,... USERD_get_block_ghost_flags(int block_number,... USERD_get_ghosts_in_block_flag(int block_number) USERD_get_border_availability(int part_number,... USERD_get_border_elements_by_type(int part_number,... USERD_get_var_by_component(int which_variable, int which_part,... USERD_get_var_value_at_specific(int which_var, int which_node_or_elem, int which_part,... ******************************************** (Array will have been allocated Numparts_available long) (OUT) part_types = Array containing one of the following for each model part: Z_UNSTRUCTURED or Z_STRUCTURED or Z_IBLANKED (Array will have been allocated Numparts_available long) (OUT) part_description = Array containing a description for each of the model parts (Array will have been allocated Numparts_available by Z_BUFL long) (OUT) number_of_nodes = Number of unstructured nodes in the part (Array will have been allocated Numparts_available long) (OUT) number_of_elements = 2D array containing number of each type of element for each unstructured model part. ------------ Possible types are: Z_POINT = point Z_BAR02 = 2-noded bar Z_BAR03 = 3-noded bar Z_TRI03 = 3-noded triangle Z_TRI06 = 6-noded triangle Z_QUA04 = 4-noded quadrilateral Z_QUA08 = 8-noded quadrilateral Z_TET04 = 4-noded tetrahedron Z_TET10 = 10-noded tetrahedron Z_PYR05 = 5-noded pyramid Z_PYR13 = 13-noded pyramid Z_PEN06 = 6-noded pentahedron Z_PEN15 = 15-noded pentahedron Z_HEX08 = 8-noded hexahedron Z_HEX20 = 20-noded hexahedron Z_G_POINT = ghost node point element Z_G_BAR02 = 2 node ghost bar Z_G_BAR03 = 3 node ghost bar Z_G_TRI03 = 3 node ghost triangle Z_G_TRI06 = 6 node ghost triangle Z_G_QUA04 = 4 node ghost quad Z_G_QUA08 = 8 node ghost quad Z_G_TET04 = 4 node ghost tetrahedron Z_G_TET10 = 10 node ghost tetrahedron Z_G_PYR05 = 5 node ghost pyramid Z_G_PYR13 = 13 node ghost pyramid Z_G_PEN06 = 6 node ghost pentahedron Z_G_PEN15 = 15 node ghost pentahedron Z_G_HEX08 = 8 node ghost hexahedron Z_G_HEX20 = 20 node ghost hexahedron (Ignored unless Z_UNSTRUCTURED type) (Array will have been allocated Numparts_available by Z_MAXTYPE long) (OUT) ijk_dimensions = 2D array containing ijk dimensions for each structured model part. ---------- (Ignored if Z_UNSTRUCTURED type) (Array will have been allocated Numparts_available by 3 long) ijk_dimensions[][0] = I dimension ijk_dimensions[][1] = J dimension ijk_dimensions[][2] = K dimension (OUT) iblanking_options = 2D array containing iblanking options possible for each structured model part. ---------- (Ignored unless Z_IBLANKED type) (Array will have been allocated Numparts_available by 6 long) iblanking_options[][Z_EXT] = TRUE if external (outside) [][Z_INT] = TRUE if internal (inside) [][Z_BND] = TRUE if boundary [][Z_INTBND] = TRUE if internal boundary [][Z_SYM] = TRUE if symmetry surface Notes: ----- * If you haven't built a table of pointers to the different parts, you might want to do so here as you gather the needed info. * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_gold_variable_info Description: ----------- Get the variable descriptions, types and filenames Specification: ------------- int USERD_get_gold_variable_info(char **var_description, char **var_filename, int *var_type, int *var_classify, int *var_complex, char **var_ifilename, float *var_freq, int *var_contran, int *var_timeset) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (OUT) var_description = Variable descriptions (Array will have been allocated Num_variables by Z_BUFL long) variable description restrictions: ---------------------------------- 1. Only first 19 characters used in EnSight. 2. Leading and trailing whitespace will be removed by EnSight. 3. Illegal characters will be replaced by underscores. 4. Thay may not start with a numeric digit. 4. No two variables may have the same description. (OUT) var_filename = Variable real filenames (Array will have been allocated Num_variables by Z_BUFL long) (OUT) var_type = Variable type (Array will have been allocated Num_variables long) types are: Z_CONSTANT Z_SCALAR Z_VECTOR Z_TENSOR Z_TENSOR9 (OUT) var_classify = Variable classification (Array will have been allocated Num_variables long) types are: Z_PER_NODE Z_PER_ELEM (OUT) var_complex = TRUE if complex, FALSE otherwise (Array will have been allocated Num_variables long) (OUT) var_ifilename = Variable imaginary filenames (if complex) (Array will have been allocated Num_variables by Z_BUFL long) (OUT) var_freq = complex frequency (if complex) (Array will have been allocated Num_variables long) (OUT) var_contran = TRUE if constant changes per time step FALSE if constant truly same at all time steps (Array will have been allocated Num_variables long) (OUT) var_timeset = Timeset the variable will use (1 based). (For static models, set it to 1) (Array will have been allocated Num_variables long) For example: If USERD_get_number_of_timesets returns 2, the valid timeset_number's would be 1 or 2 Notes: ----- * The implied variable numbers apply, but be aware that the arrays are zero based. So for variable 1, will need to provide var_description[0] var_filename[0] var_type[0] var_classify[0] var_complex[0] var_ifilename[0] var_freq[0] var_contran[0] var_timeset[0] for variable 2, will need to provide var_description[1] var_filename[1] var_type[1] var_classify[1] var_complex[1] var_ifilename[1] var_freq[1] var_contran[1] var_timeset[1] etc. -------------------------------------------------------------------- USERD_get_ghosts_in_block_flag Description: ----------- Gets whether ghost cells present in block or not Specification: ------------- int USERD_get_ghosts_in_block_flag(int block_number) Returns: ------- TRUE if any ghost cells in this structured part FALSE if no ghost cells in this structured part Arguments: --------- (IN) block_number = The block part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) Notes: ----- * This routine is new in the 2.01 API * This will be based on Current_time_step * Intended for structured parts only, value will be ignored for unstructured parts -------------------------------------------------------------------- USERD_get_maxsize_info Description: ----------- Gets maximum part sizes for efficient memory allocation. Transient models (especially those that increase in size) can cause reallocations, at time step changes, to keep chewing up more and more memory. The way to avoid this is to know what the maximum size of such memory will be, and allocate for this maximum initially. Accordingly, if you choose to provide this information (it is optional), EnSight will take advantage of it. Specification: ------------- int USERD_get_maxsize_info(int *max_number_of_nodes, int *max_number_of_elements[Z_MAXTYPE], int *max_ijk_dimensions[3]) Returns: ------- Z_OK if supplying maximum data Z_ERR if not supplying maximum data, or some error occurred while trying to obtain it. Arguments: --------- (OUT) max_number_of_nodes = Maximum number of unstructured nodes in the part (over all time). (Array will have been allocated Numparts_available long) (OUT) max_number_of_elements = 2D array containing maximum number of each type of element for each unstructured model part (over all time). ------------ Possible types are: Z_POINT = point Z_BAR02 = 2-noded bar Z_BAR03 = 3-noded bar Z_TRI03 = 3-noded triangle Z_TRI06 = 6-noded triangle Z_QUA04 = 4-noded quadrilateral Z_QUA08 = 8-noded quadrilateral Z_TET04 = 4-noded tetrahedron Z_TET10 = 10-noded tetrahedron Z_PYR05 = 5-noded pyramid Z_PYR13 = 13-noded pyramid Z_PEN06 = 6-noded pentahedron Z_PEN15 = 15-noded pentahedron Z_HEX08 = 8-noded hexahedron Z_HEX20 = 20-noded hexahedron Z_G_POINT = ghost node point element Z_G_BAR02 = 2 node ghost bar Z_G_BAR03 = 3 node ghost bar Z_G_TRI03 = 3 node ghost triangle Z_G_TRI06 = 6 node ghost triangle Z_G_QUA04 = 4 node ghost quad Z_G_QUA08 = 8 node ghost quad Z_G_TET04 = 4 node ghost tetrahedron Z_G_TET10 = 10 node ghost tetrahedron Z_G_PYR05 = 5 node ghost pyramid Z_G_PYR13 = 13 node ghost pyramid Z_G_PEN06 = 6 node ghost pentahedron Z_G_PEN15 = 15 node ghost pentahedron Z_G_HEX08 = 8 node ghost hexahedron Z_G_HEX20 = 20 node ghost hexahedron (Ignored unless Z_UNSTRUCTURED type) (Array will have been allocated Numparts_available by Z_MAXTYPE long) (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions for each structured model part (over all time). ---------- (Ignored if Z_UNSTRUCTURED type) (Array will have been allocated Numparts_available by 3 long) max_ijk_dimensions[][0] = maximum I dimension max_ijk_dimensions[][1] = maximum J dimension max_ijk_dimensions[][2] = maximum K dimension Notes: ----- * You need to have first called USERD_get_number_of_model_parts and USERD_get_gold_part_build_info, so Numparts_available is known and so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED, or Z_IBLANKED) of each part. * This will NOT be based on Current_time_step - it is to be the maximum values over all time!! * This information is optional. If you return Z_ERR, Ensight will still process things fine, reallocating as needed, etc. However, for large transient models you will likely use considerably more memory and take more processing time for the memory reallocations. So, if it is possible to provide this information "up front", it is recommended to do so. -------------------------------------------------------------------- USERD_get_ghosts_in_model_flag Description: ----------- Answers the question as to whether any ghost cells in the model. Specification: ------------- int USERD_get_ghosts_in_model_flag( void ) Returns: ------- TRUE if any ghost cells in the model FALSE if no ghost cells in the model Arguments: --------- Notes: ----- * This routine is new in the 2.01 API -------------------------------------------------------------------- USERD_get_model_extents Description: ----------- Gets the model bounding box extents. If this routine supplys them EnSight will not have to spend time doing so. If this routine returns Z_ERR, EnSight will have to take the time to touch all the nodes and gather the extent info. Specification: ------------- int USERD_get_model_extents(float extents[6]) Returns: ------- Z_OK if successful Z_ERR if not successful (whereupon EnSight will determine by reading all coords of all parts) Arguments: --------- (OUT) extents[0] = min x [1] = max x [2] = min y [3] = max y [4] = min z [5] = max z Notes: ----- * This will be based on Current_time_step -------------------------------------------------------------------- USERD_get_name_of_reader Description: ----------- Gets the name of your user defined reader. The user interface will ask for this and include it in the available reader list. Specification: ------------- int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME], int *two_fields) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (OUT) reader_name = the name of the your reader or data format. (max length is Z_MAX_USERD_NAME, which is 20) (OUT) *two_fields = FALSE if only one data field required in the data dialog of EnSight. TRUE if two data fields required. Notes: ----- * Always called. Please be sure to provide a name for your custom reader format. -------------------------------------------------------------------- USERD_get_node_label_status Description: ----------- Answers the question as to whether node labels will be provided. Specification: ------------- int USERD_get_node_label_status( void ) Returns: ------- TRUE if node labels will be provided FALSE if node labels will NOT be provided Arguments: --------- none Notes: ----- * Node ids are needed in order to do any node querying, or node labeling on-screen within EnSight. * Prior to API 2.01: ----------------- For unstructured parts, you can read them from your file if available, or can assign them, etc. They need to be unique per part, and are often unique per model. They must also be positive numbers greater than zero. USERD_get_part_node_ids is used to obtain the ids, if the status returned here is TRUE. (Unlike API 1.0, where the connectivity of elements had to be according to the node ids - API 2.0's element connectivities are not affected either way by the status here.) For structured parts, EnSight will assign ids if you return a status of TRUE here. You cannot assign them yourself!! * Starting at API 2.01: -------------------- For both unstructured and structured parts, you can read them from your file if available, or can assign them, etc. They need to be unique per part, and are often unique per model. They must also be positive numbers greater than zero. USERD_get_part_node_ids is used to obtain the ids, if the status returned here is TRUE. * Will call USERD_get_part_node_ids for each part if this routine returns TRUE. -------------------------------------------------------------------- USERD_get_num_of_time_steps Description: ----------- Gets the number of time steps of data available for desired timeset. Specification: ------------- int USERD_get_num_of_time_steps( int timeset_number ) Returns: ------- Number of time steps in timeset (>0 if okay, <=0 if problems). Arguments: --------- (IN) timeset number = the timeset number For example: If USERD_get_number_of_timesets returns 2, the valid timeset_number's would be 1 and 2 Notes: ----- * This should be >= 1 1 indicates a static model >1 indicates a transient model * Num_time_steps[timeset_number] would be set here -------------------------------------------------------------------- USERD_get_number_of_files_in_dataset Description: ----------- Get the total number of files in the dataset. Used for the dataset query option within EnSight. Specification: ------------- int USERD_get_number_of_files_in_dataset( void ) Returns: ------- The total number of files in the dataset. Arguments: --------- none Notes: ----- * You can be as complete as you want about this. If you don't care about the dataset query option, return a value of 0 If you only want certain files, you can just include them. But, you will need to supply the info in USERD_get_dataset_query_file_info for each file you include here. * Num_dataset_files would be set here -------------------------------------------------------------------- USERD_get_number_of_model_parts Description: ----------- Gets the total number of unstructured and structured parts in the model, for which you can supply information. Specification: ------------- int USERD_get_number_of_model_parts( void ) Returns: ------- Number of parts (>0 if okay, <=0 if problems). Arguments: --------- none Notes: ----- * If going to have to read down through the parts in order to know how many, you may want to build a table of pointers to the various parts, so you can easily get to particular parts in later processes. If you can simply read the number of parts at the head of the file, then you would probably not build the table at this time. * This routine would set Numparts_available, which is equal to Num_unstructured_parts + Num_structured_blocks. -------------------------------------------------------------------- USERD_get_number_of_timesets Description: ----------- Gets the number of timesets used in the model. Specification: ------------- int USERD_get_number_of_timesets( void ) Returns: ------- Number of timesets in the model Arguments: --------- none Notes: ----- * Num_timesets would be set here * If you have a static model, both geometry and variables, you should return a value of zero. * If you have a transient model, then you should return one or more. For example: Geometry Variables No. of timesets --------- ------------------------------ --------------- static static 0 static transient, all using same timeset 1 transient transient, all using same timeset as geom 1 static transient, using 3 different timesets 3 transient transient, using 3 different timesets and none of them the same as the geometry timeset 4 etc. NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide the timeset number to use for geometry in: USERD_get_geom_timeset_number Variables can use the same timeset as the geometry, or can use other timesets. More than one variable can use the same timeset. example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0 variable 1 provided at these same five steps variable 2 provided at 3 steps, 0.5, 1.25, 3.33 This routine should return a value of 2, because only two different timesets are needed. Timeset 1 would be for the geometry and variable 1 (they both use it). Timeset 2 would be for variable 2, which needs its own in this case. -------------------------------------------------------------------- USERD_get_number_of_variables Description: ----------- Get the number of variables for which you will be providing info. Specification: ------------- int USERD_get_number_of_variables( void ) Returns: ------- Number of variables (includes constant, scalar, vector and tensor types) (>=0 if okay, <0 if problem) Arguments: --------- none Notes: ----- ***************************************************************** * Variable numbers, by which references will be made, are implied here. If you say there are 3 variables, the variable numbers will be 1, 2, and 3. ***************************************************************** * Num_variables would be set here -------------------------------------------------------------------- USERD_get_part_coords Description: ----------- Gets the coordinates for an unstructured part. Specification: ------------- int USERD_get_part_coords(int part_number, float **coord_array) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) part_number = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (OUT) coord_array = 2D float array which contains, x,y,z coordinates of each node in the part. (IMPORTANT: The second dimension of this aray is 1-based!!!) (Array will have been allocated 3 by (number_of_nodes + 1) for the part long - see USERD_get_gold_part_build_info) ex) If number_of_nodes = 100 as obtained in: USERD_get_gold_part_build_info Then the allocated dimensions of the pointer sent to this routine will be: coord_array[3][101] Ignore the coord_array[0][0] coord_array[1][0] coord_array[2][0] locations and start the node coordinates at: coord_array[0][1] coord_array[1][1] coord_array[2][1] coord_array[0][2] coord_array[1][2] coord_array[2][2] etc. Notes: ----- * Not called unless Num_unstructured_parts is > 0 * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_part_element_ids_by_type Description: ----------- Gets the ids for the elements of a particular type for an unstructured or structured part. Specification: ------------- int USERD_get_part_element_ids_by_type(int part_number, int element_type, int *elemid_array) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) part_number = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (IN) element_type = One of the following (See global_extern.h) Z_POINT node point element Z_BAR02 2 node bar Z_BAR03 3 node bar Z_TRI03 3 node triangle Z_TRI06 6 node triangle Z_QUA04 4 node quad Z_QUA08 8 node quad Z_TET04 4 node tetrahedron Z_TET10 10 node tetrahedron Z_PYR05 5 node pyramid Z_PYR13 13 node pyramid Z_PEN06 6 node pentahedron Z_PEN15 15 node pentahedron Z_HEX08 8 node hexahedron Z_HEX20 20 node hexahedron Z_G_POINT ghost node point element Z_G_BAR02 2 node ghost bar Z_G_BAR03 3 node ghost bar Z_G_TRI03 3 node ghost triangle Z_G_TRI06 6 node ghost triangle Z_G_QUA04 4 node ghost quad Z_G_QUA08 8 node ghost quad Z_G_TET04 4 node ghost tetrahedron Z_G_TET10 10 node ghost tetrahedron Z_G_PYR05 5 node ghost pyramid Z_G_PYR13 13 node ghost pyramid Z_G_PEN06 6 node ghost pentahedron Z_G_PEN15 15 node ghost pentahedron Z_G_HEX08 8 node ghost hexahedron Z_G_HEX20 20 node ghost hexahedron (OUT) elemid_array = 1D array containing id of each element of the type. (Array will have been allocated number_of_elements of the type long) ex) If number_of_elements[Z_TRI03] = 25 number_of_elements[Z_QUA04] = 100 number_of_elements[Z_HEX08] = 30 as obtained in: USERD_get_gold_part_build_info Then the allocated dimensions available for this routine will be: conn_array[25] when called with Z_TRI03 conn_array[100] when called with Z_QUA04 conn_array[30] when called with Z_HEX08 Notes: ----- * Not called unless element label status is set to TRUE in USERD_get_element_label_status * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_part_elements_by_type Description: ----------- Gets the connectivities for the elements of a particular type in an unstructured part Specification: ------------- int USERD_get_part_elements_by_type(int part_number, int element_type, int **conn_array) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) part_number = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (IN) element_type = One of the following (See global_extern.h) Z_POINT node point element Z_BAR02 2 node bar Z_BAR03 3 node bar Z_TRI03 3 node triangle Z_TRI06 6 node triangle Z_QUA04 4 node quad Z_QUA08 8 node quad Z_TET04 4 node tetrahedron Z_TET10 10 node tetrahedron Z_PYR05 5 node pyramid Z_PYR13 13 node pyramid Z_PEN06 6 node pentahedron Z_PEN15 15 node pentahedron Z_HEX08 8 node hexahedron Z_HEX20 20 node hexahedron Z_G_POINT ghost node point element Z_G_BAR02 2 node ghost bar Z_G_BAR03 3 node ghost bar Z_G_TRI03 3 node ghost triangle Z_G_TRI06 6 node ghost triangle Z_G_QUA04 4 node ghost quad Z_G_QUA08 8 node ghost quad Z_G_TET04 4 node ghost tetrahedron Z_G_TET10 10 node ghost tetrahedron Z_G_PYR05 5 node ghost pyramid Z_G_PYR13 13 node ghost pyramid Z_G_PEN06 6 node ghost pentahedron Z_G_PEN15 15 node ghost pentahedron Z_G_HEX08 8 node ghost hexahedron Z_G_HEX20 20 node ghost hexahedron (OUT) conn_array = 2D array containing connectivity of each element of the type. (Array will have been allocated num_of_elements of the type by connectivity length of the type) ex) If number_of_elements[Z_TRI03] = 25 number_of_elements[Z_QUA04] = 100 number_of_elements[Z_HEX08] = 30 as obtained in: USERD_get_gold_part_build_info Then the allocated dimensions available for this routine will be: conn_array[25][3] when called with Z_TRI03 conn_array[100][4] when called with Z_QUA04 conn_array[30][8] when called with Z_HEX08 Notes: ----- * Not called unless Num_unstructured_parts is > 0 * Will be based on Current_time_step -------------------------------------------------------------------- USERD_get_part_node_ids Description: ----------- Gets the node ids of an unstructured or structured part. Specification: ------------- int USERD_get_part_node_ids(int part_number, int *nodeid_array) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) part_number = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) (OUT) nodeid_array = 1D array containing node ids of each node in the part. (IMPORTANT: This array is 1-based!!!) (Array will have been allocated (number_of_nodes + 1) for the part long see USERD_get_gold_part_build_info) ex) If number_of_nodes = 100 as obtained in: USERD_get_gold_part_build_info Then the allocated dimensions of the pointer sent to this routine will be: nodeid_array[101] Ignore the nodeid_array[0] location and start the node ids at: nodeid_array[1] nodeid_array[2] etc. Notes: ----- * Not called unless node label status is TRUE, as returned from USERD_get_node_label_status * Will be based on Current_time_step * The ids are purely labels, used when displaying or querying node ids. However, any node id < 0 will never be displayed -------------------------------------------------------------------- USERD_get_reader_descrip Description: ----------- Gets the description of the reader, so gui can give more info Specification: ------------- int USERD_get_reader_descrip(char descrip[Z_MAXFILENP]) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (OUT) descrip = the description of the reader (max length is MAXFILENP, which is 255) Notes: ----- * OPTIONAL ROUTINE! You can have it or not. -------------------------------------------------------------------- USERD_get_reader_version Description: ----------- Gets the version number of the user defined reader Specification: ------------- int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME]) Returns: ------- Z_OK if successful Z_ERR if not successful (and will assume is version 1.0) Arguments: --------- (OUT) version_number = the version number of the reader (max length is Z_MAX_USERD_NAME, which is 20) Notes: ----- * This needs to be "2.000" or greater. Otherwise EnSight will assume this reader is API 1.0 * should set it to "2.010" for this version of the API -------------------------------------------------------------------- USERD_get_sol_times Description: ----------- Get the solution times associated with each time step for desired timeset. Specification: ------------- int USERD_get_sol_times(int timeset_number, float *solution_times) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) timeset_number = the timeset number For example: If USERD_get_number_of_timesets returns 2, the valid timeset_number's would be 1 and 2 (OUT) solution_times = 1D array of solution times per time step (Array will have been allocated Num_time_steps[timeset_number] long) Notes: ----- * The solution times must be non-negative and increasing. -------------------------------------------------------------------- USERD_get_timeset_description - Description: ----------- Get the description to associate with the desired timeset. Specification: ------------- int USERD_get_timeset_description(int timeset_number, char timeset_description[Z_BUFL]) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) timeset_number = the timeset number For example: If USERD_get_number_of_timesets returns 2, the valid timeset_number's would be 1 and 2 (OUT) timeset_description = timeset description string Notes: ----- * A string of NULLs is valid for timeset_description -------------------------------------------------------------------- USERD_get_var_by_component Description: ----------- Gets the values of a variable component. Both unstructured and structured parts use this routine. if Z_PER_NODE: Get the component value at each node for a given variable in the part. or if Z_PER_ELEM: Get the component value at each element of a specific part and type for a given variable. Specification: ------------- int USERD_get_var_by_component(int which_variable, int which_part, int var_type, int which_type, int imag_data, int component, float *var_array) Returns: ------- Z_OK if successful Z_ERR if not successful or: Z_UNDEF, in which case you need not load any values into var_array Arguments: --------- (IN) which_variable = The variable number (IN) which_part Since EnSight Version 7.4 ------------------------- = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) Prior to EnSight Version 7.4 ---------------------------- = The part id This is the part_id label loaded in USERD_get_gold_part_build_info. It is NOT the part table index. (IN) var_type = Z_SCALAR Z_VECTOR Z_TENSOR (symmetric tensor) Z_TENSOR9 (asymmetric tensor) (IN) which_type if Z_PER_NODE: Not used if Z_PER_ELEM: = The element type Z_POINT node point element Z_BAR02 2 node bar Z_BAR03 3 node bar Z_TRI03 3 node triangle Z_TRI06 6 node triangle Z_QUA04 4 node quad Z_QUA08 8 node quad Z_TET04 4 node tetrahedron Z_TET10 10 node tetrahedron Z_PYR05 5 node pyramid Z_PYR13 13 node pyramid Z_PEN06 6 node pentahedron Z_PEN15 15 node pentahedron Z_HEX08 8 node hexahedron Z_HEX20 20 node hexahedron Z_G_POINT ghost node point element Z_G_BAR02 2 node ghost bar Z_G_BAR03 3 node ghost bar Z_G_TRI03 3 node ghost triangle Z_G_TRI06 6 node ghost triangle Z_G_QUA04 4 node ghost quad Z_G_QUA08 8 node ghost quad Z_G_TET04 4 node ghost tetrahedron Z_G_TET10 10 node ghost tetrahedron Z_G_PYR05 5 node ghost pyramid Z_G_PYR13 13 node ghost pyramid Z_G_PEN06 6 node ghost pentahedron Z_G_PEN15 15 node ghost pentahedron Z_G_HEX08 8 node ghost hexahedron Z_G_HEX20 20 node ghost hexahedron (IN) imag_data = TRUE if imag component FALSE if real component (IN) component = The component: (0 if Z_SCALAR) (0 - 2 if Z_VECTOR) (0 - 5 if Z_TENSOR) (0 - 8 if Z_TENSOR9) * 6 Symmetric Indicies, 0:5 * * ---------------------------- * * | 11 12 13 | | 0 3 4 | * * | | | | * * T = | 22 23 | = | 1 5 | * * | | | | * * | 33 | | 2 | * * 9 General Indicies, 0:8 * * ---------------------------- * * | 11 12 13 | | 0 3 4 | * * | | | | * * T = | 21 22 23 | = | 6 1 5 | * * | | | | * * | 31 32 33 | | 7 8 2 | * (OUT) var_array ----------------------------------------------------------------------- (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!) ----------------------------------------------------------------------- if Z_PER_NODE: = 1D array containing variable component value for each node. (Array will have been allocated (number_of_nodes + 1) long) Info stored in this fashion: var_array[0] = not used var_array[1] = var component for node 1 of part var_array[2] = var_component for node 2 of part var_array[3] = var_component for node 3 of part etc. if Z_PER_ELEM: = 1D array containing variable component value for each element of a particular part and type. (Array will have been allocated (number_of_elements[which_part][which_type] + 1) long. See USERD_get_gold_part_build_info) Info stored in this fashion: var_array[1] = var component for elem 1 (of part and type) var_array[2] = var component for elem 2 (of part and type) var_array[3] = var component for elem 3 (of part and type) etc. Notes: ----- * Not called unless Num_variables is > 0 * The per_node or per_elem classification must be obtainable from the variable number (a var_classify array needs to be retained) * Will be based on Current_time_step * If the variable is not defined for this part, simply return with a value of Z_UNDEF. EnSight will treat the variable as undefined for this part. -------------------------------------------------------------------- USERD_get_var_value_at_specific Description: ----------- if Z_PER_NODE: Get the value of a particular variable at a particular node in a particular part at a particular time. or if Z_PER_ELEM: Get the value of a particular variable at a particular element of a particular type in a particular part at a particular time. Specification: ------------- int USERD_get_var_value_at_specific(int which_var, int which_node_or_elem, int which_part, int which_elem_type, int time_step, float values[3], int imag_data) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) which_var = The variable number (IN) which_node_or_elem If Z_PER_NODE: = The node number. This is not the id, but is the index of the global node list (1 based), or the block's node list (1 based). Thus, coord_array[1] coord_array[2] coord_array[3] . | . |which_node_or_elem index . ---- If Z_PER_ELEM: = The element number. This is not the id, but is the element number index of the number_of_element array (see USERD_get_gold_part_build_info), or the block's element list (1 based). Thus, for which_part: conn_array[which_elem_type][0] conn_array[which_elem_type][1] conn_array[which_elem_type][2] . | . which_node_or_elem index . ---- (IN) which_part Since EnSight Version 7.4 ------------------------- = The part number (1-based index of part table, namely: 1 ... Numparts_available. It is NOT the part_id that is loaded in USERD_get_gold_part_build_info) Prior to EnSight Version 7.4 ---------------------------- = The part id This is the part_id label loaded in USERD_get_gold_part_build_info. It is NOT the part table index. (IN) which_elem_type If Z_PER_NODE, or block part: = Not used If Z_PER_ELEM: = The element type. This is the element type index of the number_of_element array (see USERD_get_gold_part_build_info) (IN) time_step = The time step (IN) imag_data = TRUE if want imaginary value. FALSE if want real value. (OUT) values = scalar or vector component value(s) values[0] = scalar or vector[0] values[1] = vector[1] values[2] = vector[2] Notes: ----- * This routine is used in node querys over time (or element querys over time for Z_PER_ELEM variables). If these operations are not critical to you, this can be a dummy routine. * The per_node or per_elem classification must be obtainable from the variable number (a var_classify array needs to be retained) * The time step given is for the proper variable timeset. -------------------------------------------------------------------- USERD_set_filenames Description: ----------- Receives the geometry and result filenames entered in the data dialog. The user written code will have to store and use these as needed. The user written code must manage its own files!! Specification: ------------- int USERD_set_filenames(char filename_1[], char filename_2[], char the_path[], int swapbytes) Returns: ------- Z_OK if successful Z_ERR if not successful Arguments: --------- (IN) filename_1 = the filename entered into the geometry field of the data dialog. (IN) filename_2 = the filename entered into the result field of the data dialog. (If the two_fields flag in USERD_get_name_of_reader is FALSE, this will be null string) (IN) the_path = the path info from the data dialog. Note: filename_1 and filename_2 have already had the path prepended to them. This is provided in case it is needed for filenames contained in one of the files (IN) swapbytes = TRUE if should swap bytes when reading data. = FALSE normally. Notes: ----- * Since you must manage everything from the input that is entered in these data dialog fields, this is an important routine! * It may be that you will need to have an executive type file that contains info and other filenames within it, like EnSight6's case file. -------------------------------------------------------------------- USERD_set_server_number Description: ----------- Receives the server number of how many total servers. Specification: ------------- int USERD_set_server_number(int cur_serv, int tot_servs) Returns: ------- nothing Arguments: --------- (IN) cur_serv = the current server. (IN) tot_servs = the total number of servers. Notes: ----- * Only useful if your user defined reader is being used with EnSight's Server-of-Server capability. And even then, it may or may not be something that you can take advantage of. If your data is already partitioned in some manner, such that you can access the proper portions using this information. For all non-SOS uses, this will simply be 1 of 1 -------------------------------------------------------------------- USERD_set_time_set_and_step Description: ----------- Set the current time step in the desired timeset. All functions that need time, and that do not explicitly pass it in, will use the timeset and step set by this routine, if needed. Specification: ------------- void USERD_set_time_set_and_step(int timeset_number, int time_step) Returns: ------- nothing Arguments: --------- (IN) timeset_number = the timeset number (1 based). For example: If USERD_get_number_of_timesets returns 2, the valid timeset_number's would be 1 and 2. (IN) time_step = The current time step to set Notes: ----- * Current_time_step and Current_timeset would be set here -------------------------------------------------------------------- USERD_stop_part_building Description: ----------- This routine called when the part building dialog is closed. It is provided in case you desire to release memory, etc. that was only needed during the part building process. Specification: ------------- void USERD_stop_part_building( void ) Returns: ------- nothing Arguments: --------- none Notes: ----- ---- end of doucment ----