1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
|
README_USERD_1.0
================
--------------------------------------
EnSight User Defined Reader Capability ===> (API 1.0)
--------------------------------------
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.
Two versions of this API are available starting with EnSight Version 7.2. The
1.0 API (which was designed to be friendly to those producing it, but requires
more manipulation internally by EnSight) may be a little easier to
produce, but requires more memory and processing time. The 2.0 API is
considerably more efficient, and was designed more with that in mind. It
requires that all data be provided on a part basis.
If you already have a working 1.0 API reader and are happy with it - there is
probably no reason to modify it to the 2.0 API unless:
- you deal with large models and the memory use and load times are a
problem or
- you need tensor variable support or
- you need complex variable support or
- you need multiple timeset capability or
_ you want to provide your own "border" elements (as opposed to EnSight's
computation of them).
If you are producing a new reader, you should consider which will work best
for your needs.
API 1.0 (defined in this README_USERD_1.0 document)
=======
The original user defined reader API (used with EnSight Versions 6 through
7.1) will continue to be supported. (Note that there was a change in the way
that the libraries were made at version 7.1 of EnSight, but underlying code
was kept the same.) Thus, any readers that work with EnSight 7.1, should still
function with EnSight 7.2.
API 2.0 (defined in README_USERD_2.0 document)
=======
This new API has been defined to be more efficient and includes access to new
capabilities of EnSight 7.2. 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.
* If your data format already provides boundary shell information, you can
use it instead of the "border" representation that EnSight would compute.
Further discussion on the philosophical differences between the two API's and
an efficiency comparison example can be found in the README_1.0_to_2.0 file.
This file also contains guidance on necessary changes to modify an existing
1.0 API to the new 2.0 API.
****************************************************************************
Note: Several (1.0 API) user defined readers have been included with your
EnSight release and are configured by default. There are site- and
user-configurable options outlined in step 3 below. Please be aware
that these are "unsupported" readers, but many of them are being used
successfully.
****************************************************************************
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 library and for various other working or
sample libraries is copied from the installation CD during
installation. These will be located in directories under:
$ENSIGHT7_HOME/user_defined_src/readers
examples of API 1.0:
-------------------
Basic dummy routines provide skeleton for a new reader
$ENSIGHT7_HOME/user_defined_src/readers/dummy
Sample library which reads unstructured binary EnSight6 data
$ENSIGHT7_HOME/user_defined_src/readers/ensight6
Sample library which reads binary static plot3d data
$ENSIGHT7_HOME/user_defined_src/readers/plot3d
Reads binary LS-DYNA3D state database
$ENSIGHT7_HOME/user_defined_src/readers/ls-dyna3d
Reads FORTRAN binary Unstructured dytran data base
$ENSIGHT7_HOME/user_defined_src/readers/dytran
Reads FlowScience "flsgrf" flow3d data
$ENSIGHT7_HOME/user_defined_src/readers/flow3d
Reads Tecplot "plt" files
$ENSIGHT7_HOME/user_defined_src/readers/tecplot
Reads Common File Format data
$ENSIGHT7_HOME/user_defined_src/readers/cff
Reads Cobalt grid and picture/restart file data
$ENSIGHT7_HOME/user_defined_src/readers/cobalt
Reads binary Nastran OP2 data base
$ENSIGHT7_HOME/user_defined_src/readers/nastran
Reads binary and ascii cfx data
$ENSIGHT7_HOME/user_defined_src/readers/cfx4
Reads Exodus II data base
$ENSIGHT7_HOME/user_defined_src/readers/exodus
Reads Parallel Exodus data base
$ENSIGHT7_HOME/user_defined_src/readers/pxi
Reads FORTRAN binary SCRYU data
$ENSIGHT7_HOME/user_defined_src/readers/scryu
Reads binary and ascii STL data
$ENSIGHT7_HOME/user_defined_src/readers/stl
Reads Vectis data
$ENSIGHT7_HOME/user_defined_src/readers/vectis
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:
$ENSIGHT7_HOME/machines/$ENSIGHT7_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:
$ENSIGHT7_HOME/machines/$ENSIGHT7_ARCH/lib_readers/libuserd-mydata.so
3. By default EnSight will load all readers found in the directory:
$ENSIGHT7_HOME/machines/$ENSIGHT7_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 <librarypath> ~/lib:$<librarypath>
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_number_of_global_nodes number of global nodes
USERD_get_global_coords global node coordinates
USERD_get_global_node_ids global node ids
USERD_get_element_connectivities_for_part part's element connectivites
USERD_get_element_ids_for_part part's element ids
USERD_get_scalar_values global scalar variables
USERD_get_vector_values global vector variables
Generally Needed for BLOCK data
-----------------------------------------
USERD_get_block_coords_by_component block coordinates
USERD_get_block_iblanking block iblanking values
USERD_get_block_scalar_values block scalar variables
USERD_get_block_vector_values_by_component block vector variables
Generally needed for either or both kinds of data
-------------------------------------------------
USERD_set_filenames filenames entered in GUI
USERD_set_time_step current time step
USERD_get_name_of_reader name of reader for GUI
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_changing_geometry_status changing geometry?
USERD_get_node_label_status node labels?
USERD_get_element_label_status element labels?
USERD_get_number_of_time_steps number of time steps
USERD_get_solution_times solution time values
USERD_get_description_lines file associated descrip lines
USERD_get_number_of_variables number of variables
USERD_get_variable_info variable type/descrip etc.
USERD_get_constant_value constant variable's value
USERD_get_number_of_model_parts number of model parts
USERD_get_part_build_info part type/descrip etc.
USERD_get_variable_value_at_specific node's or element's variable
value over time
USERD_stop_part_building cleanup routine
USERD_bkup archive 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
2. Setting filenames and getting time info
USERD_set_filenames
USERD_get_number_of_time_steps
USERD_get_solution_times
USERD_set_time_step
3. Gathering info for part builder
USERD_set_time_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_description_lines (for geometry)
USERD_get_number_of_model_parts
USERD_get_part_build_info
USERD_get_number_global_nodes
USERD_get_global_coords (for model extents)
USERD_get_block_coords_by_component (for model extents)
4. Gathering Variable info
USERD_get_number_of_variables
USERD_get_variable_info
5. Part building (per part created)
USERD_set_time_step
USERD_get_global_coords
USERD_get_global_node_ids
USERD_get_element_connectivities_for_part
USERD_get_element_ids_for_part
USERD_get_block_iblanking
USERD_get_block_coords_by_component
USERD_stop_part_building (only once when part builder
dialog is closed)
6. Loading Variables
constants:
---------
USERD_set_time_step
USERD_get_constant_value
scalars:
-------
USERD_get_description_lines
USERD_set_time_step
USERD_get_scalar_values
USERD_get_block_scalar_values
vectors:
-------
USERD_get_description_lines
USERD_set_time_step
USERD_get_vector_values
USERD_get_block_vector_values_by_component
7. Changing geometry
changing coords only:
--------------------
USERD_set_time_step
USERD_get_global_coords
USERD_get_block_coords_by_component
changing connectivity:
---------------------
USERD_set_time_step
USERD_get_number_of_model_parts
USERD_get_part_build_info
USERD_get_number_global_nodes
USERD_get_global_coords
USERD_get_global_node_ids
USERD_get_element_connectivities_for_part
USERD_get_element_ids_for_part
USERD_get_block_iblanking
USERD_get_block_coords_by_component
8. Node or Element queries over time
USERD_get_variable_value_at_specific
-----------------------
Detailed Specifications
-----------------------
Include files:
--------------
The following header file is required in any file containing these library
routines.
#include "global_extern.h"
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_time_steps = 1;
static int Num_global_nodes = 0;
static int Num_variables = 0;
static int Num_dataset_files = 0;
static int Current_time_step = 0;
_________________________________________
-----------------------------------------
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_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
(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
(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_scalar_values
Description:
-----------
if Z_PER_NODE:
Get the values at each node of a block, for a given scalar variable
or if Z_PER_ELEM:
Get the values at each element of a block, for a given scalar variable
Specification:
-------------
int USERD_get_block_scalar_values(int block_number,
int which_scalar,
float *scalar_array)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(IN) block_number = The block part number
(IN) which_scalar = The variable number
(OUT) scalar_array = 1D array containing scalar values
for each node or element.
Array will have been allocated:
if Z_PER_NODE:
i*j*k for the block long
if Z_PER_ELEM:
(i-1)*(i-1)*(k-1) for the block long
Notes:
-----
* Not called unless Num_structured_blocks is > 0,
Num_variables is > 0, and there are some scalar type variables
* 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
--------------------------------------------------------------------
USERD_get_block_vector_values_by_component
Description:
-----------
if Z_PER_NODE:
Get the values at each node of a block, for a given vector
variable, one component at a time.
or if Z_PER_ELEM:
Get the values at each element of a block, for a given vector
variable, one component at a time.
Specification:
-------------
int USERD_get_block_vector_values_by_component(int block_number,
int which_vector,
int which_component,
float *vector_array)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(IN) block_number = The block part number
(IN) which_vector = The variable number
(IN) which_component = Z_COMPX if x component wanted
= Z_COMPY if y component wanted
= Z_COMPZ if z component wanted
(OUT) vector_array = 1D array containing vector
component value for each node or element.
Array will have been allocated:
if Z_PER_NODE:
i*j*k for the block long
if Z_PER_ELEM:
(i-1)*(i-1)*(k-1) for the block long
Notes:
-----
* Not called unless Num_structured_blocks is > 0,
Num_variables is > 0, and there are some vector type variables
* 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
--------------------------------------------------------------------
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.
--------------------------------------------------------------------
USERD_get_constant_value
Description:
-----------
Get the value of a constant at a time step
Specification:
-------------
float USERD_get_constant_value(int which_var)
Returns:
-------
Value of the requested constant variable
Arguments:
---------
(IN) which_var = The variable number
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.
--------------------------------------------------------------------
USERD_get_description_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_description_lines(int which_type,
int which_var,
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.
(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_connectivities_for_part
Description:
-----------
Gets the connectivities for the elements of an unstructured part
Specification:
-------------
int USERD_get_element_connectivities_for_part(int part_number,
int **conn_array[Z_MAXTYPE])
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(IN) part_number = The part number
(OUT) conn_array = 3D array containing connectivity
of each element of each type.
(Array will have been allocated
Z_MAXTYPE by num_of_elements of
each type by connectivity length
of each type)
ex) If num_of_elements[Z_TRI03] = 25
num_of_elements[Z_QUA04] = 100
num_of_elements[Z_HEX08] = 30
as obtained in:
USERD_get_part_build_info
Then the allocated dimensions available
for this routine will be:
conn_array[Z_TRI03][25][3]
conn_array[Z_QUA04][100][4]
conn_array[Z_HEX08][30][8]
Notes:
-----
* Not called unless Num_unstructured_parts is > 0
* Will be based on Current_time_step
* The coord_array loaded in USERD_get_global_coords is zero-based,
but within EnSight it will become a one-based array.
Thus, coord_array[0] will be accessed by node 1 from the conn_array,
coord_array[1] will be accessed by node 2 from the conn_array, etc.
ex) Given a model of two triangles, you should load coord_array in
USERD_get_global_coords as follows:
node coordinates
---- -----------
4 --------- 3 1 coord_array[0].xyz[0] = 0.0
|\ | coord_array[0].xyz[1] = 0.0
| \ T2 | coord_array[0].xyz[2] = 0.0
| \ |
| \ | 2 coord_array[1].xyz[0] = 1.0
| \ | coord_array[1].xyz[1] = 0.0
| \ | coord_array[1].xyz[2] = 0.0
| \ |
| T1 \ | 3 coord_array[2].xyz[0] = 1.0
| \| coord_array[2].xyz[1] = 1.6
1 --------- 2 coord_array[2].xyz[2] = 0.0
4 coord_array[3].xyz[0] = 0.0
coord_array[3].xyz[1] = 1.6
coord_array[3].xyz[2] = 0.0
And conn_array here as follows:
Triangle Connectivity
-------- ------------
T1 conn_array[Z_TRI03][0][0] = 1
conn_array[Z_TRI03][0][1] = 2
conn_array[Z_TRI03][0][2] = 4
T2 conn_array[Z_TRI03][1][0] = 2
conn_array[Z_TRI03][1][1] = 3
conn_array[Z_TRI03][1][2] = 4
--------------------------------------------------------------------
USERD_get_element_ids_for_part
Description:
-----------
Gets the ids for the elements of an unstructured part.
Specification:
-------------
int USERD_get_element_ids_for_part(int part_number,
int *elemid_array[Z_MAXTYPE])
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(IN) part_number = The part number
(OUT) elemid_array = 2D array containing id of each
element of each type.
(Array will have been allocated
Z_MAXTYPE by num_of_elements of
each type)
ex) If num_of_elements[Z_TRI03] = 25
num_of_elements[Z_QUA04] = 100
num_of_elements[Z_HEX08] = 30
as obtained in:
USERD_get_part_build_info
Then the allocated dimensions available
for this routine will be:
conn_array[Z_TRI03][25]
conn_array[Z_QUA04][100]
conn_array[Z_HEX08][30]
Notes:
-----
* Not called unless Num_unstructured_parts is > 0 and element
label status is TRUE
* Will be based on Current_time_step
--------------------------------------------------------------------
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.
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.
USERD_get_element_ids_for_part is used to obtain the ids,
on a part by part 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!!
--------------------------------------------------------------------
USERD_get_global_coords
Description:
-----------
Gets the coordinates for the global nodes.
Specification:
-------------
int USERD_get_global_coords(CRD *coord_array)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(OUT) coord_array = 1D array of CRD structures,
which contains x,y,z coordinates
of each node.
(Array will have been allocated
Num_global_nodes long)
For reference, CRD structure (which is in global_extern) is:
typedef struct {
float xyz[3];
}CRD;
Notes:
-----
* Not called unless Num_unstructured_parts is > 0
* Will be based on Current_time_step
* The coord_array is zero-based, but within EnSight it will become
a one-based array.
Thus, coord_array[0] will be accessed by node 1 from the conn_array,
coord_array[1] will be accessed by node 2 from the conn_array, etc.
ex) Given a model of two triangles, you should load coord_array as
follows:
node coordinates
---- -----------
4 --------- 3 1 coord_array[0].xyz[0] = 0.0
|\ | coord_array[0].xyz[1] = 0.0
| \ T2 | coord_array[0].xyz[2] = 0.0
| \ |
| \ | 2 coord_array[1].xyz[0] = 1.0
| \ | coord_array[1].xyz[1] = 0.0
| \ | coord_array[1].xyz[2] = 0.0
| \ |
| T1 \ | 3 coord_array[2].xyz[0] = 1.0
| \| coord_array[2].xyz[1] = 1.6
1 --------- 2 coord_array[2].xyz[2] = 0.0
4 coord_array[3].xyz[0] = 0.0
coord_array[3].xyz[1] = 1.6
coord_array[3].xyz[2] = 0.0
And conn_array in USERD_get_element_connectivities_for_part
as follows:
Triangle Connectivity
-------- ------------
T1 conn_array[Z_TRI03][0][0] = 1
conn_array[Z_TRI03][0][1] = 2
conn_array[Z_TRI03][0][2] = 4
T2 conn_array[Z_TRI03][1][0] = 2
conn_array[Z_TRI03][1][1] = 3
conn_array[Z_TRI03][1][2] = 4
--------------------------------------------------------------------
USERD_get_global_node_ids
Description:
-----------
Gets the node ids assigned to each of the global nodes.
Specification:
-------------
int USERD_get_global_node_ids(int *nodeid_array)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(OUT) nodeid_array = 1D array containing node ids of
each node. The ids must be > 0
(Array will have been allocated
Num_global_nodes long)
Notes:
-----
* Not called unless Num_unstructured_parts is > 0 and node label
status is TRUE
* 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. Provide a name for your custom reader format.
* If you don't want a custom reader to show up in the data dialog
choices, return a name of "No_Custom"
--------------------------------------------------------------------
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.
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. The must also be
positive numbers greater than zero.
USERD_get_global_node_ids is used to obtain the ids, if the
status returned here is TRUE.
Also be aware that if you say node labels are available,
the connectivity of elements must be according to these
node ids.
For structured parts, EnSight will assign ids if you return a
status of TRUE here. You cannot assign them yourself!!
--------------------------------------------------------------------
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_global_nodes
Description:
-----------
Gets the number of global nodes, used for unstructured parts.
Specification:
-------------
int USERD_get_number_of_global_nodes()
Returns:
-------
Number of global nodes (>=0 if okay, <0 if problems)
Arguments:
---------
none
Notes:
-----
* Not called unless Num_unstructured_parts is > 0
* Will be based on Current_time_step
* For unstructured data:
EnSight wants 1. A global array of nodes
2. Element connectivities by part, which
reference the node numbers of the global
node array.
IMPORTANT:
---------
If you provide node ids, then element connectivities
must be in terms of the node ids. If you do not
provide node ids, then element connectivities must be
in terms of the index into the node array, but shifted
to start at 1
* Num_global_nodes 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 probs).
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_time_steps
Description:
-----------
Gets the number of time steps of data available.
Specification:
-------------
int USERD_get_number_of_time_steps( void )
Returns:
-------
Number of time steps (>0 if okay, <=0 if problems).
Arguments:
---------
none
Notes:
-----
* This should be >= 1 1 indicates a static model
>1 indicates a transient model
* Num_time_steps would be set here
--------------------------------------------------------------------
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, and vector 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_build_info
Description:
-----------
Gets the info needed for the part building process.
Specification:
-------------
int USERD_get_part_build_info(int *part_numbers,
int *part_types,
char *part_description[Z_BUFL],
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_numbers = Array containing part numbers for
each of the model parts.
IMPORTANT:
Parts numbers must be >= 1
********************************************
The numbers provided here are the ones by
which the parts will be referred to in any
of the other routines which receive a part
number or block number as an argument!!
********************************************
(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_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
(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_scalar_values
Description:
-----------
if Z_PER_NODE:
Get the values at each global node for a given scalar variable.
or if Z_PER_ELEM:
Get the values at each element of a specific part and type for a
given scalar variable.
Specification:
-------------
int USERD_get_scalar_values(int which_scalar,
int which_part,
int which_type,
float *scalar_array)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(IN) which_scalar = The variable number (of scalar type)
(IN) which_part
if Z_PER_NODE: Not used
if Z_PER_ELEM: = The part number
(IN) which_type
if Z_PER_NODE: Not used
if Z_PER_ELEM: = The element type
(OUT) scalar_array
if Z_PER_NODE: = 1D array containing scalar values
for each node.
(Array will have been allocated
Num_global_nodes long)
if Z_PER_ELEM: = 1d array containing scalar values for
each element of a particular part and type.
(Array will have been allocated
number_of_elements[which_part][which_type]
long. See USERD_get_part_build_info)
Notes:
-----
* Not called unless Num_unstructured_parts is > 0,
Num_variables is > 0, and you have some scalar type variables.
* 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
--------------------------------------------------------------------
USERD_get_solution_times
Description:
-----------
Get the solution times associated with each time step.
Specification:
-------------
int USERD_get_solution_times(float *solution_times)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(OUT) solution_times = 1D array of solution times/time step
(Array will have been allocated
Num_time_steps long)
Notes:
-----
* The solution times must be non-negative and increasing.
--------------------------------------------------------------------
USERD_get_variable_info
Description:
-----------
Get the variable descriptions, types and filenames
Specification:
-------------
int USERD_get_variable_info(char **var_description,
char **var_filename,
int *var_type,
int *var_classify)
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)
(OUT) var_filename = Variable 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
(OUT) var_classify = Variable classification
(Array will have been allocated
Num_variables long)
types are: Z_PER_NODE
Z_PER_ELEM
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]
for variable 2, will need to provide var_description[1]
var_filename[1]
var_type[1]
var_classify[1]
etc.
--------------------------------------------------------------------
USERD_get_variable_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_variable_value_at_specific(int which_var,
int which_node_or_elem,
int which_part,
int which_elem_type,
int time_step,
float values[3])
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_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
If Z_PER_NODE, or block part:
= Not used
If Z_PER_ELEM:
= The part number
(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_part_build_info)
(IN) time_step = The time step
(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)
--------------------------------------------------------------------
USERD_get_vector_values
Description:
-----------
if Z_PER_NODE:
Get the values at each global node for a given vector variable.
or if Z_PER_ELEM:
Get the values at each element of a specific part and type for a
given vector variable.
Specification:
-------------
int USERD_get_vector_values(int which_vector,
int which_part,
int which_type,
float *vector_array)
Returns:
-------
Z_OK if successful
Z_ERR if not successful
Arguments:
---------
(IN) which_vector = The variable number
(IN) which_part
if Z_PER_NODE: Not used
if Z_PER_ELEM: = The part number
(IN) which_type
if Z_PER_NODE: Not used
if Z_PER_ELEM: = The element type
(OUT) vector_array
if Z_PER_NODE: = 1D array containing vector values
for each node.
(Array will have been allocated
3 by Num_global_nodes long)
Info stored in this fashion:
vector_array[0] = xcomp of node 1
vector_array[1] = ycomp of node 1
vector_array[2] = zcomp of node 1
vector_array[3] = xcomp of node 2
vector_array[4] = ycomp of node 2
vector_array[5] = zcomp of node 2
vector_array[6] = xcomp of node 3
vector_array[7] = ycomp of node 3
vector_array[8] = zcomp of node 3
etc.
if Z_PER_ELEM: = 1D array containing vector values for
each element of a particular part and type.
(Array will have been allocated
3 by number_of_elements[which_part][which_type]
long. See USERD_get_part_build_info)
Info stored in this fashion:
vector_array[0] = xcomp of elem 1 (of part and type)
vector_array[1] = ycomp of elem 1 "
vector_array[2] = zcomp of elem 1 "
vector_array[3] = xcomp of elem 2 "
vector_array[4] = ycomp of elem 2 "
vector_array[5] = zcomp of elem 2 "
vector_array[6] = xcomp of elem 3 "
vector_array[7] = ycomp of elem 3 "
vector_array[8] = zcomp of elem 3 "
etc.
Notes:
-----
* Not called unless Num_unstructured_parts is > 0,
Num_variables is > 0, and you have some vector type variables
* 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
--------------------------------------------------------------------
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.
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.
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_time_step
Description:
-----------
Set the current time step. All functions that need time, and
that do not explicitly pass it in, will use the time step set by
this routine.
Specification:
-------------
void USERD_set_time_step(int time_step)
Returns:
-------
nothing
Arguments:
---------
(IN) time_step - The current time step to set
Notes:
-----
* Current_time_step 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 ----
|
