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
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
|
<html><head><title>Acknowledgments</title></head>
<body>
<a name="541728"><CENTER><h1>Acknowledgments</h1></CENTER></a>
<hr><p><a name="541736">
As with all such things, PANACEA was not created in a vacuum and owes a debt of thanks to many people who contributed in many different ways to its evolution. There are many more than can be mentioned in this short space, and the ones who are singled out are not mentioned in any particular order.<p>
</a>
<a name="541737">
Bill Eme and Tom Kelleher used the code, looked at the code, and made many excellent suggestions about the functionality. Rex Evans worked on forerunners to PANACEA over the years and many of the ideas here had their origins in his efforts. Lee Taylor similarly has had lots of experience with simulation code systems and has had a large impact on the workings of PANACEA. John Ambrosiano pushed hard for PANACHE and has graciously tested it. David Hardin has helped greatly in clarifying certain user requirements and in verifying their implementation.<p>
</a>
<a name="541738">
Jan Moura and Jeff Long organized a group to look into the requirements for time history data management and their efforts are to be found here. Scott Futral and Al Miller contributed some code and examples.<p>
</a>
<a name="541739">
Thanks also go to Ron Mayle and Howard Scott who have put up with PANACEA from its conception as often frustrated users.<p>
</a>
<a name="541740">
<h1>1.0 </a>Introduction</h1>
</a>
<a name="541741">
A numerical simulation code is fundamentally a device to solve an initial value problem. Very often these programs are written starting with the routines that solve some system of equations. Unless care is taken to formulate these routines with regard to a host of issues (e.g., data flow), it can be very awkward to set up a problem or to look at the answers that the code returns. Furthermore, it can be nearly impossible to take advantage of some of the excellent work that various groups have done (e.g., equation solver packages) because the data flow and structuring issues have not been given sufficient attention in the program design stages.<p>
</a>
<a name="541742">
One way to avoid some of these difficulties is to write the data flow controls, the I/O mechanisms, and the database manager first. With these parts in place, there is a great deal of guidance for building the parts of a simulation code that deal with the specific set of equations to be solved; thus initial value data is fed in and the solution is written out clearly and conveniently. Furthermore, this approach provides a basis for defining some conventions to allow the sharing of simulation modules. It also helps isolate the machine dependencies of a code in a very few places, which greatly enhances the portability of the code.<p>
</a>
<a name="541743">
PANACEA is a library of routines built to address these issues. In essence, PANACEA attempts to embody all of the functionality of a numerical simulation code, which is generic to all simulation codes. It accomplishes this by implementing a model of the simulation as a system of services (routines), which are bound together with the simulation specific routines provided by the code developer. One useful result of this approach is that it effectively imposes a discipline for the development of simulation codes that promote shareability, portability, and inter-operability.<p>
</a>
<a name="541744">
Throughout this manual examples will be couched in terms of a sample PANACEA code system called ABC. Like most PANACEA codes, ABC consists of three executable codes: </a>A, the initial value problem generator; </a>B, the main simulation code; and </a>C, the post processor code for ABC. ABC is a simple 2d hydrodynamics code with three packages: a global package for mesh handling and various “global” facilities; a hydrodynamics package; and a materials package. Many of the code fragments given, although appearing complete, are edited down to draw attention to essential points and leave out details which are not pertinent to the discussion of PANACEA.<p>
</a>
<a name="541745">
<h1>2.0 The PANACEA Model</h1>
</a>
<a name="541746">
This section discusses the motivation for and offers an explanation of the </a>PANACEA model. It summarizes the services that PANACEA provides and examines some related code issues. <p>
</a>
<a name="541747">
<h2>2.1 Sequence of States</h2>
</a>
<a name="541748">
An</a> initial value problem can be viewed as a machine (some system of equations) and an initial state. The initial state is evolved to a final state by the machine. When the system of equations is solved numerically, the evolution of states by the machine is represented as a discrete sequence of states.<p>
</a>
<a name="541749">
In this view, there are three broad phases to a numerical simulation. First, the initial state must be generated. Second, the numerical machine must evolve each state into its successor state until this cycle is terminated according to some criterion. Last, some or all of the information that represents the states of the system must be organized for visualization. The last two phases often occur simultaneously. For example, in a time plot of some physical variable in the simulation, the information for the plot must be gathered up in the course of the entire simulation and viewed at the end.<p>
</a>
<a name="541750">
PANACEA formalizes these three phases by addressing entire sets of routines to supporting the processes involved: problem generation, simulation, and post-processing for visualization. These phases can be accomplished in three separate codes or can be integrated into a single code. PANACEA attempts to make a minimum number of assumptions about the simulation being carried out. The assumptions that are made pertain to the model of a simulation as outlined above.<p>
</a>
<a name="541751">
<h2>2.2 Simulation Packages</h2>
</a>
<a name="541752">
Many of the most complex simulation programs are broken down into parts that solve some subset of the system of equations in the simulation. For example, some codes have a thermal conduction package that is a separately callable module. The reasons are fourfold: ease of control (packages can be switched on and off); simplified design and maintenance; multiple packages solving the same subset of equations (algorithmic testing or problem domain differences); or code recycling.<p>
</a>
<a name="541753">
Ideally, packages built for one code could be loaded into another code with few or no changes. This shareability will require some standardization of interfaces, database access, and so forth. PANACEA provides a framework upon which to build such a standardization. It is especially well suited to this task in light of its attempt to make few assumptions about how a code is organized or what it does.<p>
</a>
<a name="541754">
PANACEA has the facilities to manage a collection of simulation packages. The code developer defines each package to PANACEA (according to the criteria of the PANACEA model of simulations), which amounts to providing a set of functions which carry out simulation specific operations. Figure 1 illustrates how some basic functions provided by the code developer are bound by PANACEA into a simulation code. With the packages defined, PANACEA can manipulate them as abstract entities and perform such generic operations as cycling through the packages to evolve the state of the simulation.<p>
</a>
<a name="541755">
<p>
</a>
<A NAME="541757"><B>Defining packages for a PANACEA simulation code
</B><HR><A NAME="541758"><PRE> def_system()
</PRE><A NAME="541759"><PRE> {PA_run_time_package(“global”, NULL, NULL, def_global,
</PRE><A NAME="541760"><PRE> cont_global, init_vars, global_entry,
</PRE><A NAME="541761"><PRE> B_build_pseudo_mapping, NULL, NULL);
</PRE><A NAME="541762"><PRE> PA_run_time_package(“hydrodynamics”, NULL, NULL,
</PRE><A NAME="541763"><PRE> def_hydro, cont_hydro, init_hydro,
</PRE><A NAME="541764"><PRE> hydro, B_build_pseudo_mapping,
</PRE><A NAME="541765"><PRE> NULL, NULL);
</PRE><A NAME="541766"><PRE> PA_run_time_package(“materials”, NULL, NULL,
</PRE><A NAME="541767"><PRE> def_mat, cont_mat, mat_init,
</PRE><A NAME="541768"><PRE> mat, B_build_pseudo_mapping,
</PRE><A NAME="541769"><PRE> NULL, NULL);
</PRE><A NAME="541770"><PRE> return;}
</PRE><a name="541771">
<p>
</a>
<a name="545673">
Many (but not all) simulation codes require one or more computational meshes. Every simulation code does require some controlling information (e.g., when to stop) to be managed. PANACEA acknowledges this problem by requiring at least one package be provided. It is given a special status and a special name, the global package. It is recommended (but not required) that the mesh generation and handling routines go in the global package.<p>
</a>
<a name="541772">
To help realize the goal of shareability, the PANACEA package is defined as containing all of the routines needed to use the package in each of the phases: generation, simulation, and post-processing. In that way, the recipient of a PANACEA package should not have to add or change as much coding. For example, an equation-of-state (EOS) package might have some special information, which the generator must process for the main simulation. A PANACEA version of such an EOS package would include the routines to process that information for the generator.<p>
</a>
<a name="541773">
In practice, PANACEA packages can be thought of and realized as libraries of routines that are loaded together with a very simple driver module to produce the entire simulation code system (see Figure 2). If the PANACEA ideal of shareability were perfect, one simulation code could add the invocation of a package from a second code and load the package library to add the new package to the original simulation code system.<p>
</a>
<A NAME="545510"><B>A simple driver for the code whose packages are defined in Figure 1.
</B><HR><A NAME="545511"><PRE> /* B.C - the main simulation code of the ABC system */
</PRE><A NAME="545512"><PRE>
</PRE><A NAME="545513"><PRE> #include “b.h”
</PRE><A NAME="545514"><PRE>
</PRE><A NAME="545515"><PRE> /* MAIN - read the restart dump and run the physics loop */
</PRE><A NAME="545516"><PRE>
</PRE><A NAME="545517"><PRE> main(c, v)
</PRE><A NAME="545518"><PRE> int c;
</PRE><A NAME="545519"><PRE> char **v;
</PRE><A NAME="545520"><PRE> {char *fname;
</PRE><A NAME="545521"><PRE>
</PRE><A NAME="545522"><PRE> /* define the code system by setting up the packages */
</PRE><A NAME="545523"><PRE> def_system();
</PRE><A NAME="545524"><PRE> PA_build_domain_hook = B_build_domain;
</PRE><A NAME="545525"><PRE> PA_build_mapping_hook = B_build_mapping;
</PRE><A NAME="545526"><PRE>
</PRE><A NAME="545527"><PRE> /* read the restart file */
</PRE><A NAME="545528"><PRE> if (fname != NULL)
</PRE><A NAME="545529"><PRE> {PA_rd_restart(fname, NONE);
</PRE><A NAME="545530"><PRE> name[2] = SC_strsave(fname);};
</PRE><A NAME="545531"><PRE>
</PRE><A NAME="545532"><PRE> /* perform initialization */
</PRE><A NAME="545533"><PRE> PA_init_system(param[1], (param[3] - param[2])*param[4],
</PRE><A NAME="545534"><PRE> swtch[3], name[3], name[4], name[5]);
</PRE><A NAME="545535"><PRE>
</PRE><A NAME="545536"><PRE> /* run the simulation */
</PRE><A NAME="545537"><PRE> PA_simulate(param[1], swtch[3], N_zones, param[2], param[3],
</PRE><A NAME="545538"><PRE> param[4], param[5], param[6], param[7],
</PRE><A NAME="545539"><PRE> name[2], name[3], name[4], name[5]);
</PRE><A NAME="545540"><PRE>
</PRE><A NAME="545541"><PRE> /* write a restart dump before ending */
</PRE><A NAME="545542"><PRE> PA_wr_restart(name[2]);
</PRE><A NAME="545543"><PRE>
</PRE><A NAME="545608"><PRE> exit(0);}
</PRE><A NAME="545613"><PRE>
</PRE><a name="545609">
<h2>2.3 Simulation Variables</h2>
</a>
<a name="545610">
The complement to the simulation package is the simulation variable. Each package has three categories of variables: input variables, which are provided to the package by other packages; internal variables, which are neither imported into the package nor exported from it; and output variables, which are provided by the package for use by other packages.<p>
</a>
<a name="545563">
PANACEA manages a database of variables to which each package may contribute. Each variable is “owned” by some package and each package can gain access to any variable in the database. Access control is especially useful to help prevent some of the more obscure problems that can arise with unregulated access to simulation variables.<p>
</a>
<a name="545555">
A very important aspect of the variables in the database is to have a generic mechanism for specifying output requests. PANACEA can handle “most” requests in a generic fashion, thus freeing the application developer from having to worry about “most” output requests (plots, edits, dumps, etc.).<p>
</a>
<a name="541778">
Variables in PANACEA are carefully defined, including such information as name, type, array dimensions, units, and various categories of scope. This imposes an important discipline on the developer and permits PANACEA to provide some additional services relating to unit conversion, and subset extraction for I/O (see Figure 3).<p>
</a>
<a name="541779">
The database manager is the main mechanism for regulating data flow through a PANACEA code system. There is a practical problem inherited from the C programming language, in which PANACEA is implemented, in that there are no separate name spaces and hence global variables can (and sometimes do) make variables available where not actually intended or desired. A solution to this problem will come in later versions of PANACEA.<p>
</a>
<a name="541780">
<h2>2.4 Physical Units</h2>
</a>
<a name="541781">
PANACEA maintains three systems of units: external, internal, and cgs. The end user specifies input quantities in external units and output quantities are given in external units. Internal units are those in which the simulation routines deal. This was done to give code developers the opportunity to debug in units that make sense to them while letting the end users deal in a system of units that is natural to the problems being run. A “complete” set of fundamental constants and many derived physical constants are maintained by PANACEA in cgs units originally. PANACEA handles all data conversions in an efficient and transparent way, though each variable must have its units defined so that conversions can be done. The conversions cannot work if there are any numerical constants that have physical units in a PANACEA code. For example, writing 2.99e10 for the speed of light in an expression is illegal (although PANACEA does nothing to enforce it). The PANACEA provided constant, c, must be used instead.<p>
</a>
<A NAME="541816"><B>Defining variable for a PANACEA database. Note that this is one of the functions installed
as part of the definition of the hydrodynamics package in Figure 1
</B><HR><A NAME="541818"><PRE> /* DEF_HYDRO - define the hydrodynamics package data base */
</PRE><A NAME="541819"><PRE>
</PRE><A NAME="541820"><PRE> def_hydro(pck)
</PRE><A NAME="541821"><PRE> PA_package *pck;
</PRE><A NAME="541822"><PRE> {int *P_zones;
</PRE><A NAME="541824"><PRE> P_zones = &swtch[4];
</PRE><A NAME="541825"><PRE>
</PRE><A NAME="541826"><PRE> /* RESTART VARIABLES */
</PRE><A NAME="541828"><PRE> PA_def_var(“n”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541829"><PRE> SCOPE, RESTART, CLASS, REQU, CENTER, Z_CENT, ATTRIBUTE
</PRE><A NAME="541830"><PRE> P_zones, DIMENSION, PER, CC, UNITS);
</PRE><A NAME="541831"><PRE> PA_def_var(“P”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541832"><PRE> SCOPE, RESTART, CLASS, REQU, CENTER, Z_CENT, ATTRIBUTE
</PRE><A NAME="541833"><PRE> P_zones, DIMENSION, ERG, PER, CC, UNITS);
</PRE><A NAME="541834"><PRE> PA_def_var(“rho”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541835"><PRE> SCOPE, RESTART, CLASS, REQU, CENTER, Z_CENT, ATTRIBUTE
</PRE><A NAME="541836"><PRE> P_zones, DIMENSION, G, PER, CC, UNITS);
</PRE><A NAME="541837"><PRE>
</PRE><A NAME="541838"><PRE> /* RUNTIME VARIABLES */
</PRE><A NAME="541840"><PRE> PA_def_var(“Rpdv”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541841"><PRE> CENTER, Z_CENT, ATTRIBUTE,
</PRE><A NAME="541842"><PRE> P_zones, DIMENSION, EV, PER, SEC, UNITS);
</PRE><A NAME="541843"><PRE> PA_def_var(“Rqdv”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541844"><PRE> CENTER, Z_CENT, ATTRIBUTE,
</PRE><A NAME="541845"><PRE> P_zones, DIMENSION, EV, PER, SEC, UNITS);
</PRE><A NAME="541846"><PRE> PA_def_var(“vol”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541847"><PRE> CENTER, Z_CENT, ATTRIBUTE,
</PRE><A NAME="541848"><PRE> P_zones, DIMENSION, CC, UNITS);
</PRE><A NAME="541849"><PRE> PA_def_var(“mass-z”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541850"><PRE> CENTER, Z_CENT, ATTRIBUTE,
</PRE><A NAME="541851"><PRE> P_zones, DIMENSION, G, UNITS);
</PRE><A NAME="541852"><PRE>
</PRE><A NAME="541853"><PRE> /* EDIT VARIABLES */
</PRE><A NAME="541854"><PRE> PA_def_var(“Q”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="541855"><PRE> SCOPE, EDIT, CLASS, REQU, CENTER, Z_CENT, ATTRIBUTE,
</PRE><A NAME="541856"><PRE> P_zones, DIMENSION, ERG, PER, CC, UNITS);
</PRE><A NAME="541858"><PRE>
</PRE><A NAME="545501"><PRE> return;}
</PRE><a name="541860">
This efficiency offers three benefits. First, by requiring constants to be expressed in terms of physical constants and dimensionless numbers, a code system avoids certain arithmetic errors and is more self-documenting. Second, an extra level of consistency is built into simulation codes. I have found bugs in simulation packages by running a problem in two different systems of internal units. Such simulations should produce the same result, but various inconsistencies between packages can easily result in different answers. The third benefit is that without such a mechanism simulation packages in general would not be sharable! By carrying their system of units around in physical terms, packages can be moved around among simulations codes without regard to the way the original developer thought about units.<p>
</a>
<a name="541861">
<h2>2.5 Data Flow</h2>
</a>
<a name="541862">
With the three phase model in mind, the PANACEA model manages the data flow throughout a simulation as follows: the generator reads in ASCII and binary information to define the initial state, which is written as a binary file; the simulation phase code reads state files and source files, communicates with itself by writing state files, and communicates with the post-processor by writing dumps targeted for it; and the post-processor reads only the post-processor dumps and writes out files for target visualization systems.<p>
</a>
<a name="541863">
To maintain portability, PANACEA uses PDBLib to read and write portable binary files. The choice of PDBLib is motivated by its efficiency and its ability to handle structured data including pointers. In fact, PANACEA uses parts of PDBLib directly to manage its database. In this way, the developer can work with relatively arbitrary data structures without having to worry about reading and writing them out to the state files. The fact that the same tool is used for all binary files coupled with the fact that PDB files are self-describing gives the code developer the opportunity to make the greatest use of the data in the various files.<p>
</a>
<a name="541864">
<h2>2.6 Generation of Initial State</h2>
</a>
<a name="541865">
The procedure for using PANACEA to build a program to generate initial states for a simulation is described in this section. For sake of example, the generator program will be referred to as A. As with all PANACEA codes the simulation packages are the focus of attention.<p>
</a>
<a name="541866">
PANACEA uses a very simple mechanism for processing user commands. Each line of input in the user written file that describes the simulation problem is read into a buffer; the first token is stripped off and used in a hash table to dispatch to a routine that the code developer has provided to process the remaining tokens in the input line and to take appropriate action. PANACEA provides several functions to get the tokens and, if necessary, to translate them to numerical data types.<p>
</a>
<a name="541867">
Given this model, it is clear that the developer must write a collection of routines to handle the various commands for A. Very often in non-PANACEA codes this is done by having a routine with a potentially enormous if...elseif...elseif...endif construct. The advantage of PANACEA’s hash driven scheme is that each command is processed separately and with equally quick access. This procedure is done on a package-by-package basis. In this way, the routines that generate information for a package are associated with the package.<p>
</a>
<a name="541868">
Since PANACEA manages a database of simulation variables, the variables for each package must be defined to the database. PANACEA provides a routine for this purpose. The code developer must completely define variables for each package. These definitions are put into a single routine, which is one of the defining routines of a PANACEA package. The information required about a variable is shown below:<p>
</a>
<ul><a name="541869">
<li>A name by which it is installed in the database (a hash table).
</a>
<a name="541870">
<li>A pointer to the number of elements in the variable.
</a>
<a name="541871">
<li>A list of pointers to dimensions defining the shape of variable (1-D array, 2-D array, etc.).
</a>
<a name="541872">
<li>A designation specifying the scope of the variable.
</a>
<a name="541873">
<li>Another designation for the class of the variable.
</a>
<a name="541874">
<li>One for the centering of the variable with respect to any coordinate mesh used in the simulation.
</a>
<a name="541875">
<li>A list of physical units (see Figure 3).
</a>
<a name="541876">
The scope of a variable addresses three issues: (1) If it is necessary to the definition of the simulation state, in which case it is written to the state file when such a dump is done; (2) If the variable can be computed from the state but should otherwise remain present for the entire simulation; or (3) If the variable should only exist long enough to be edited and then have its space reclaimed.<p>
</a>
<a name="541877">
The class of a variable refers to whether it is required to be in the state file, whether it is optional in the state file, or whether it should be read from the state file only when specifically requested. The first two classes are read in whenever a state file is read. The last one only brings in the data when specifically accessed with PA_CONNECT.<p>
</a>
<a name="541878">
Pointers to the size (number of elements and shape) information are necessary because, at the time the variables are defined, there is no problem definition to give values to these numbers. Therefore, PANACEA is given pointers to the locations where that information will be stored when a problem is generated or read in from a state file.<p>
</a>
<a name="541879">
PANACEA provides a routine to install the code developer’s generator routines in the command hash table. Thus, in addition to the routines to process the input, a function to install these routines in the command table must be provided. This routine is one of the defining routines for a PANACEA package (see Figure 4).<p>
</a>
<A NAME="541880"><B>Install commands for the global package. These form part of the initial value problem
generator, A.
</B><HR><A NAME="541882"><PRE> /* GLOBAL_CMMNDS - install the commands for the global package */
</PRE><A NAME="541883"><PRE>
</PRE><A NAME="541884"><PRE> global_cmmnds()
</PRE><A NAME="541885"><PRE> {N_parts = 0;
</PRE><A NAME="541886"><PRE>
</PRE><A NAME="541887"><PRE> PA_inst_c(“make”, NULL, FALSE, 0, make_mesh, PA_zargs, commands);
</PRE><A NAME="541888"><PRE> PA_inst_c(“clear”, NULL, FALSE, 0, clearh, PA_zargs, commands);
</PRE><A NAME="541889"><PRE> PA_inst_c(“part”, NULL, FALSE, 0, parth, PA_zargs, commands);
</PRE><A NAME="541890"><PRE> PA_inst_c(“side”, NULL, FALSE, 0, sideh, PA_zargs, commands);
</PRE><A NAME="541891"><PRE>
</PRE><A NAME="541892"><PRE> /* named switches, parameters, and names */
</PRE><A NAME="541893"><PRE> PA_inst_c(“start-time”, param, SC_DOUBLE_I, 2, PA_pshand,
</PRE><A NAME="541894"><PRE> PA_sargs, commands);
</PRE><A NAME="541895"><PRE> PA_inst_c(“stop-time”, param, SC_DOUBLE_I, 3, PA_pshand,
</PRE><A NAME="541896"><PRE> PA_sargs, commands);
</PRE><A NAME="541897"><PRE>
</PRE><A NAME="541898"><PRE> return;}
</PRE><A NAME="541899"><PRE>
</PRE><a name="541936">
A PANACEA package provides for three arrays: one array of integers called switches; one array of doubles called parameters; and one array of strings called names, which the developer may wish to use to control a package’s operation. For example, a number of sub-iterations or a multiplier on some process might be managed by PANACEA on behalf of the code developer (i.e., the database manager overhead can be reduced by managing arrays rather than large numbers of scalars). The code developer can use this facility by providing a routine that specifies how many switches, parameters, and names are required for a given package and specifies their default values. PANACEA itself provides routines to handle input commands to set values for these quantities (collectively referred to as controls). In fact, PANACEA even provides the developer with the option of referring to the controls by names (at least from the generator input see Figure 4). The routine that defines the controls is one of the package defining routines (see Figure 5).<p>
</a>
<a name="541937">
The normal execution sequence for a PANACEA generator follows:<p>
</a>
<a name="541938">
<li>The command table is built by installing each package’s commands.
</a>
<a name="541939">
<li>The controls for each package are defined.
</a>
<a name="541940">
<li>The variables for each package are defined.
</a>
<a name="541941">
<li>The input is read in and processed.
</a>
<a name="541942">
<li>The variables that are created are interned in the database managed by PANACEA.
</a>
<a name="541943">
<li>The database is dumped out into a state file.
</a>
<A NAME="545679"><B>Define and initialize the controls for a PANACEA package. Note that this is one of the
functions installed as part of the definition for the hydrodynamics package in Figure 1.
</B><HR><A NAME="545681"><PRE> /* CONT_HYDRO - set the hydrodynamics package controls */
</PRE><A NAME="545682"><PRE>
</PRE><A NAME="545683"><PRE> cont_hydro(pck)
</PRE><A NAME="545684"><PRE> PA_package *pck;
</PRE><A NAME="545685"><PRE> {static int n_names = 2, n_params = 15, n_swtches = 10;
</PRE><A NAME="545686"><PRE>
</PRE><A NAME="545687"><PRE> PA_mk_control(pck, “hydrodynamics”, n_names, n_params, n_swtches);
</PRE><A NAME="545688"><PRE>
</PRE><A NAME="545689"><PRE> swtch[1] = TRUE; /* hydro switch */
</PRE><A NAME="545690"><PRE> swtch[2] = 0;
</PRE><A NAME="545691"><PRE> swtch[3] = 0;
</PRE><A NAME="545692"><PRE> swtch[4] = global_swtch[12];
</PRE><A NAME="545693"><PRE> swtch[5] = 0;
</PRE><A NAME="545694"><PRE> swtch[6] = 1;
</PRE><A NAME="545695"><PRE> swtch[7] = 0;
</PRE><A NAME="545696"><PRE>
</PRE><A NAME="545697"><PRE> param[1] = 0.2;
</PRE><A NAME="545698"><PRE> param[2] = 2.0;
</PRE><A NAME="545699"><PRE> param[3] = 1.0;
</PRE><A NAME="545700"><PRE> param[4] = 1.5;
</PRE><A NAME="545701"><PRE> param[5] = 0.2;
</PRE><A NAME="545702"><PRE> param[6] = 0.2;
</PRE><A NAME="545703"><PRE> param[7] = 0.2;
</PRE><A NAME="545704"><PRE> param[8] = 1.0;
</PRE><A NAME="545705"><PRE> param[9] = 0.0;
</PRE><A NAME="545706"><PRE> param[10] = 1.0;
</PRE><A NAME="545707"><PRE> param[11] = 3.0/2.0;
</PRE><A NAME="545708"><PRE> param[12] = 1.0e-6;
</PRE><A NAME="545709"><PRE> param[13] = 0.1;
</PRE><A NAME="545710"><PRE> param[14] = 2.0;
</PRE><A NAME="545711"><PRE> param[15] = 1.0;
</PRE><A NAME="545712"><PRE>
</PRE><A NAME="545713"><PRE> return;}
</PRE><A NAME="545714"><PRE>
</PRE><A NAME="545715"><PRE>
</PRE><A NAME="545716"><PRE>
</PRE><A NAME="545783"><PRE>
</PRE><a name="541944">
The last step is carried out by PANACEA alone. The step in which the variables are interned in the database requires a routine supplied by the developer to make PANACEA calls that associate local or global variables with entries in the database. This is the final defining routine for a package in the generation phase (see Figure 6).<p>
</a>
<A NAME="545722"><B> Intern the variables for the hydrodynamics package. This is a function defined for the
initial value problem generator, A, by the hydrodynamics package.
</B><HR><A NAME="545724"><PRE> /* INTERN_HYDRO - INTERN the variables of the hydrodynamics package
</PRE><A NAME="545725"><PRE> * - prior to writing the initial restart dump
</PRE><A NAME="545726"><PRE> */
</PRE><A NAME="545727"><PRE>
</PRE><A NAME="545728"><PRE> intern_hydro()
</PRE><A NAME="545729"><PRE> {swtch[2] = global_swtch[1];
</PRE><A NAME="545730"><PRE> swtch[3] = global_swtch[2];
</PRE><A NAME="545731"><PRE> swtch[4] = global_swtch[12];
</PRE><A NAME="545732"><PRE>
</PRE><A NAME="545733"><PRE> param[12] *= (global_param[3] - global_param[2]);
</PRE><A NAME="545734"><PRE> param[13] *= (global_param[3] - global_param[2]);
</PRE><A NAME="545735"><PRE>
</PRE><A NAME="545736"><PRE> PA_INTERN(n, “n”, double);
</PRE><A NAME="545737"><PRE> PA_INTERN(p, “P”, double);
</PRE><A NAME="545738"><PRE> PA_INTERN(rho, “rho”, double);
</PRE><A NAME="545739"><PRE>
</PRE><A NAME="545740"><PRE> return;}
</PRE><A NAME="545741"><PRE>
</PRE><a name="541945">
Finally, to build a PANACEA generator, the code developer writes a driver module that issues calls to PANACEA to define the packages given the functions discussed above, to process command line arguments, and to hand control of the input reading process to PANACEA. All further action is controlled by PANACEA and the information in the input stream, i.e., reviewing information, writing the initial state file, and exiting. This driver is compiled and loaded with the package libraries, the PANACEA library, and some other lower level libraries such as PDBLib.<p>
</a>
<a name="541946">
In practice, the first place to start is the global package. If the simulation code has a computational mesh, the routines to translate a collection of user specifications into a representation appropriate for the simulation routines should reside here. Controls that specify how many cycles to run, that keep the names of file families, etc. go in the global package. In addition, routines for direct visualization of the initial state before writing a state file might be most logically included in the global package.<p>
</a>
<a name="541947">
This process would be repeated for each package of the simulation until a complete generator code was specified. It is important to remember that PANACEA attempts to make limited assumptions about what the code developer wants to do - a necessity to have some structure specifying a framework on which to hang simulation packages. It is best to keep in mind a picture of fundamental processes of data flow and management and computational flow control, i.e., to think about what has to be happening to get a generation code to work properly.<p>
</a>
</ul><a name="541969">
<h2>2.7 Simulation</h2>
</a>
<a name="541970">
The actual simulation phase of the PANACEA model is the simplest. Since PANACEA simulation codes only read state files that serve what PANACEA itself manages, the code developer only needs to provide the actual simulation routines. Actually, PANACEA allows for some additional routines to be supplied to increase the efficiency of data flow through the code and to handle simulation specific output requests.<p>
</a>
<a name="545755">
Once the database has been read in from the state file, PANACEA alone has access to the variables in the database. In order to gain access to the data, the code developer must issue calls to connect local or global code variables to the information in the database. Even though the database is hash driven and is therefore quite efficient, PANACEA overhead can be reduced by connecting to package variables once and leaving those connections intact for the entire simulation run. This is not required, but it is very convenient and efficient. The code developer can supply a routine in which all of these connections are made on a package-by-package basis, i.e., one routine per package. These routines are defining routines for the packages. PANACEA will execute each of these packages once per simulation run before the main simulation routines are called (see Figure 7).<p>
</a>
<a name="545756">
Most PANACEA packages have a main entry point which is where the real simulation work occurs. The main entry point is probably the routine which is most often the starting point when a code developer sets out to write a new simulation package. Typically, the main entry point it designed to be executed once per major computational cycle. From PANACEA’s point of view it is both an easy point to control and a natural point to monitor the performance and resource usage of a package. Figure 8 illustrates a main entry point routine.<p>
</a>
<a name="545762">
PANACEA packages also include slots for routines to handle special purpose I/O and routines to run after the main simulations routines have been called for the last time in a run. The code developer can provide them if necessary and supply them to the call which defines the package to the simulation code.<p>
</a>
<a name="545763">
PANACEA provides a service to sequentially execute the main simulation routines until a certain “time” has elapsed. Many variations on such a service are possible and the code developer does not have to use the ones PANACEA provides. Given the list of packages, the code developer can manipulate them in whatever fashion is appropriate to the problem at hand (see Figure 2).<p>
</a>
<a name="541971">
<p>
</a>
<A NAME="541972"><B>Initialize the hydrodynamics package. Note that this is one of the functions installed as
part of the definition of the hydrodynamics package in Figure 1.
</B><HR><A NAME="541973"><PRE>
</PRE><A NAME="541974"><PRE> /* INIT_HYDRO - initialize and allocate hydro variables once */
</PRE><A NAME="541975"><PRE>
</PRE><A NAME="541976"><PRE> init_hydro(pck)
</PRE><A NAME="541977"><PRE> PA_package *pck;
</PRE><A NAME="541978"><PRE> {int i, j;
</PRE><A NAME="541979"><PRE>
</PRE><A NAME="541980"><PRE> /* PA_CONNECT global zonal variables */
</PRE><A NAME="541981"><PRE> PA_CONNECT(rho, “rho”, double *, TRUE);
</PRE><A NAME="541982"><PRE> PA_CONNECT(n, “n”, double *, TRUE);
</PRE><A NAME="541983"><PRE> PA_CONNECT(p, “P”, double *, TRUE);
</PRE><A NAME="541984"><PRE> PA_CONNECT(massz, “mass-z”, double *, TRUE);
</PRE><A NAME="541985"><PRE> PA_CONNECT(t, “T”, double *, TRUE);
</PRE><A NAME="541986"><PRE> PA_CONNECT(ab, “A-bar”, double *, TRUE);
</PRE><A NAME="541987"><PRE> PA_CONNECT(zb, “Z-bar”, double *, TRUE);};
</PRE><A NAME="541988"><PRE>
</PRE><A NAME="541989"><PRE> /* allocate local zonal variables */
</PRE><A NAME="541990"><PRE> cs = MAKE_N(double, N_zones);
</PRE><A NAME="541991"><PRE> dtvg = MAKE_N(double, N_zones);
</PRE><A NAME="541992"><PRE> pdv = MAKE_N(double, N_zones);
</PRE><A NAME="541993"><PRE> qdv = MAKE_N(double, N_zones);
</PRE><A NAME="541994"><PRE> voln = MAKE_N(double, N_zones);
</PRE><A NAME="541995"><PRE> volo = MAKE_N(double, N_zones);
</PRE><A NAME="541996"><PRE>
</PRE><A NAME="541997"><PRE> /* set some scalars */
</PRE><A NAME="541998"><PRE> csmin = param[9];
</PRE><A NAME="541999"><PRE> hgamma = 1.0 + 1.0/(param[11] + SMALL);
</PRE><A NAME="542000"><PRE>
</PRE><A NAME="542001"><PRE> /* initialize some zonal arrays */
</PRE><A NAME="542002"><PRE> for (j = frz; j <= lrz; j++)
</PRE><A NAME="542003"><PRE> {volo[j] = vol[j];
</PRE><A NAME="542004"><PRE> massz[j] = rho[j]*vol[j];};
</PRE><A NAME="542005"><PRE>
</PRE><A NAME="542006"><PRE> return;}
</PRE><A NAME="542007"><B>The main entry point for a PANACEA package. Note that this is one of the functions
installed as part of the definition of the hydrodynamics package in Figure 1.
</B><HR><A NAME="542008"><PRE>
</PRE><A NAME="542009"><PRE> /* HYDRO - the main hydro entry point */
</PRE><A NAME="542010"><PRE>
</PRE><A NAME="542011"><PRE> hydro(pck)
</PRE><A NAME="542012"><PRE> PA_package *pck;
</PRE><A NAME="542013"><PRE> {int hyd_z;
</PRE><A NAME="542014"><PRE> double hyd_dt;
</PRE><A NAME="542015"><PRE> static int first = TRUE;
</PRE><A NAME="542016"><PRE>
</PRE><A NAME="542017"><PRE> /* check that this package was requested */
</PRE><A NAME="542018"><PRE> if (swtch[1] == FALSE)
</PRE><A NAME="542019"><PRE> return;
</PRE><A NAME="542020"><PRE>
</PRE><A NAME="542021"><PRE> if (first)
</PRE><A NAME="542022"><PRE> pck->space = (double) Ssp_alloc;
</PRE><A NAME="542023"><PRE>
</PRE><A NAME="542024"><PRE> PA_MARK_TIME;
</PRE><A NAME="542025"><PRE>
</PRE><A NAME="542026"><PRE> init_cycle();
</PRE><A NAME="542027"><PRE>
</PRE><A NAME="542028"><PRE> /* do the real hydro work */
</PRE><A NAME="542029"><PRE> hydro_wrk(&hyd_dt, &hyd_z);
</PRE><A NAME="542030"><PRE>
</PRE><A NAME="542031"><PRE> /* record the hydro timestep vote */
</PRE><A NAME="542032"><PRE> pck->dt = hyd_dt;
</PRE><A NAME="542033"><PRE> pck->dt_zone = hyd_z;
</PRE><A NAME="542034"><PRE>
</PRE><A NAME="542035"><PRE> PA_ACCM_TIME(pck->time);
</PRE><A NAME="542036"><PRE>
</PRE><A NAME="542037"><PRE> if (first)
</PRE><A NAME="542038"><PRE> {pck->space = (double) Ssp_alloc - pck->space;
</PRE><A NAME="542039"><PRE> first = FALSE;};
</PRE><A NAME="542040"><PRE>
</PRE><A NAME="542041"><PRE> return;}
</PRE><A NAME="542042"><PRE>
</PRE><a name="542043">
<p>
</a>
<a name="542047">
To help with the monitoring of performance, each package has slots to record the CPU time spent in the package and the total memory required by the package. The latter is most useful when memory is being managed dynamically. PANACEA will print out statistics for each of the packages at the end of a run. In practice, this tends to be very useful information when algorithmic optimization is being pursued or when obscure behavior is suggesting memory bugs. See Figure 8.<p>
</a>
<a name="542048">
<h2>2.8 Data Management for Visualization</h2>
</a>
<a name="542049">
Ultimately, a simulation code system is limited by its ability to produce information that can be presented in a meaningful way. The visualization problem is one of current intense interest and effort. From the point of view of PANACEA, the important task is to get numerical results out of the simulation code and into a form usable by a visualization system. Because of the variety of visualization systems and their input formats, PANACEA can provide active services for the first part, i.e., it gets data out of the simulation efficiently. It only passively supports the second part by accessing the data it puts out from the simulation. The code developer is left with the task of formatting the information for the visualization system of choice. <p>
</a>
<a name="542050">
There are two basic kinds of data flow out of the simulation code. First, at each cycle, the data that is completed in a cycle must be written out according to user requests. Second, information that is accumulated across more than one cycle must be addressed.<p>
</a>
<a name="542051">
The “snapshot” requests (complete in one cycle) can be put out either directly for the visualization system or into some intermediate form for subsequent processing. In the PANACEA model, output data are not kept in the state of the running code. In fact, PANACEA services are aimed at transferring the data from the code to data files as efficiently as possible. The main advantage of this scheme is that the task of visualization can be done on a different machine while the simulation progresses if data is put out every cycle. A second advantage is that the running code does not grow as a result of the stored output data.<p>
</a>
<a name="542052">
The output whose meaning comes from the results of several computational cycles (generically referred to as time plots) is handled differently. PANACEA dumps the information computed in each cycle out into an intermediate file family at the end of the cycle. After the simulation is complete a separate post-processing code transposes the information and writes it in the desired format. This process naturally involves the code developer to a greater extent than the generation process, given that input parsing is ASCII based whereas visualization systems have a variety of input mechanisms.<p>
</a>
<a name="542053">
The PACT tool, PDBView, has facilities to display the “snapshot” files generated by PANACEA. PANACEA has support for post processor codes to emit files for ULTRA II, the PACT utility for presentation, analysis, and manipulation of 1D data sets. Typically these are time plots since the snapshot mechanism covers most other cases.<p>
</a>
<a name="542054">
<p>
</a>
<A NAME="542055"><B>Sample PANACEA plot request specifications. All of the range and domain variables are
in the database.
</B><HR><a name="542057">
A velocity vector plot every 20.0 time units from 0 to 100.0 over the entire mesh.<p>
</a>
<A NAME="AUTOTAG;"><B>graph {vx,vy}(t=step(0.0;1.0e2;20.0),rx,ry)
</B><a name="542059">
A vector plot with components rho and n every 20.0 time units from 0 to 100.0 over the entire mesh.<p>
</a>
<A NAME="AUTOTAG;"><B>graph {rho,n}(t=step(0.0;1.0e2;20.0),rx,ry)
</B><a name="542061">
The radiation field at time 50.0 and frequency 1000.0 over the entire mesh. This could be rendered as a contour plot, a surface plot, a wire-frame plot, or an image plot.<p>
</a>
<A NAME="AUTOTAG;"><B>graph jnu(t=50.0,rx,ry,nu=1000.0)
</B><a name="542063">
The variable, p, at every time over the entire mesh.<p>
</a>
<A NAME="AUTOTAG;"><B>graph p(t,rx,ry)
</B><A NAME="AUTOTAG;"><B>
</B><a name="542066">
PANACEA has very powerful and general mechanisms for plotting data from the database. These mechanisms translate output requests into data for a visualization system (see Figure 9).<p>
</a>
<a name="542067">
<h2>2.9 Source Functions and Source Data</h2>
</a>
<a name="542068">
Many systems of equations that are simulated numerically involve source functions of one sort or another. Also, initial value and boundary value data must be gotten into the simulation. In general, the amount of information for these purposes is too large to include in an ASCII input file. In any case, it is straightforward enough to handle all of this type of information in complete generality.<p>
</a>
<a name="542069">
PANACEA provides a set of services to manage source or boundary value data. The characterization of the data is specified in the input phase. The characterization may include information as to where or when the source is to be applied, a file from which to read the data, etc. During the simulation phase, the source data is interpolated by PANACEA and handed to simulation routines upon request.<p>
</a>
<a name="542070">
To make this process as efficient as possible, when source data is so voluminous as to require data files to contain it reasonably, it is prepared in advance in the form of PDB files. The self-describing nature of these files and variable database of PANACEA make it easy to code and efficient at run time. PANACEA provides routines to facilitate the writing of a code to gather source information from whatever sources the code developer has and to produce the required PDB source files. The further advantage of this approach is that many simulation runs can be done (and typically are) with one set of source information that does not change. Having the PDB files separate makes this fast and convenient.<p>
</a>
<a name="542071">
The source variable notion is very natural from the data generation and specification point of view. However, from the point of view of the algorithms, additional issues concern initial or boundary value data. Often this data is not directly part of the variable database (perhaps because it is applied to the boundaries of one of the database variables). PANACEA distinguishes between initial or boundary value data and source data. It treats source data as a separate sub-class of initial value data. In particular, source data usually involves information coming in over many computational cycles, and it may require interpolation with respect to “time”. It also may involve large quantities of data that are most conveniently kept in files (PDB files actually). PANACEA services make as much of this transparent to the developer as possible.<p>
</a>
<a name="542072">
PANACEA services gather up specifications, doing some processing when appropriate, and hold that information for the simulation on demand. These services also interpolate “temporal” data to the correct “time” in a simulation. Even though PANACEA makes a distinction between sources and initial value data, it gathers them in the same fashion (see Figure 10).<p>
</a>
<a name="545775">
<p>
</a>
<A NAME="542075"><B>Some examples of source and initial value specifications in PANACEA.
</B><HR><a name="542077">
Set a boundary condition tagged as “boundary-pressure”. The hydrodynamics package will look for “boundary-pressure” specifications and interpolate appropriate values from the data in file, “press.dat”.<p>
</a>
<A NAME="AUTOTAG;"><B>specify bc boundary-pressure from press.dat
</B><a name="542079">
Set a boundary condition tagged as “constant-vx”. The hydrodynamics package will look for “constant-vx” specifications and take the given values as the place to apply it.<p>
</a>
<A NAME="AUTOTAG;"><B>specify bc constant-vx 1 1 1 5
</B><a name="542081">
Impose a profile on the source variable tagged as “temperature-floor”. The relevant package looks for a source variable tagged this way. It will interpret (with PANACEA’s help) and interpolate the “time”, “value” pairs.<p>
</a>
<A NAME="AUTOTAG;"><B>specify src temperature-floor
</B><A NAME="AUTOTAG;"><B>s 0.0 50.0
</B><A NAME="AUTOTAG;"><B>s 0.3 100.0
</B><A NAME="AUTOTAG;"><B>s 0.5 300.0
</B><A NAME="AUTOTAG;"><B>s 0.8 400.0
</B><A NAME="AUTOTAG;"><B>s 1.0 500.0
</B><a name="542088">
Variables defined in the PANACEA database can be directly controlled by source variables. In this case, the variable rho would be interpolated from the source file rho.dat instead of being computed by a hydrodynamics package.<p>
</a>
<A NAME="AUTOTAG;"><B>specify rho from rho.dat
</B><a name="542091">
Typically, a PANACEA simulation code system will have a program to build source files for simulation runs. PANACEA has the routines to do the generic work here. It helps to map ASCII (or other) data files that are derived from experiments or other simulations into the database of the simulation code system. The developer provides the routines with specific information about the input data; the PANACEA services package it in a form that is most efficient for the simulation code to use.<p>
</a>
<a name="542092">
<h2>2.10 Data Structures</h2>
</a>
<a name="542093">
As the above discussion indicates, PANACEA attempts to work with many abstract concepts to delineate the boundary between the generic and the specific. The key to working with an abstraction is to create a concrete representation. Briefly, PANACEA uses the C struct mechanism to define structured data types representing packages, variables, source variables, initial value specifications, plot requests, and generator commands. These structures and a collection of routines to create, release, and manipulate them are the key to realizing PANACEA’s goals.<p>
</a>
<a name="542094">
One additional set of structures (provided by an associated math library called PML, Portable Mathematics Library) is important for its ability to tie some key aspects of data flow together. In attempting to deal with data that are generated from a specification that is natural for the end user, computed within a form natural to numerical algorithms, stored in intermediate data files or transmitted over networks, and finally visualized in yet a different form, it was important to formulate a description of data that is self-consistent and mathematically precise. In this way, data sets could be assembled, passed among computational routines, stored, and visualized all in a relatively efficient and general way. This description had to be general enough to deal with multidimensional data with a variety of properties.<p>
</a>
<a name="542095">
The key concepts are those of sets and mappings. Mathematically, for the purposes of both computation and visualization, one is interested in working with mappings of domain sets to range sets. A set consists of a collection of data items along with information describing the type of elements, the dimensionality of the set, the dimensionality of the elements, the topology of the set, the metric information, etc. Ideally, the set structure contains sufficient information to allow routines to process them without additional specifications. For example, a set might be a collection of 3-vectors on a 2-sphere or a simple 1-D array.<p>
</a>
<a name="542096">
Sets can be related by mappings that describe how elements of two sets are related. The mapping structure contains a domain set, a range set, some information about extremes of both sets, and other descriptive information (e.g., relative centering). Ideally, a differentiation routine could be handed a mapping whose properties it understands and return a new mapping representing the gradient of the argument mapping. The goal is to objectify a complete collection of information for the purposes of storage and computation.<p>
</a>
<a name="542097">
A third layer of structure combines a mapping with rendering specifications that make it possible to visualize the data set embodied in the mapping. This structure is referred to as a graph, and it provides a means of associating mathematically complete data sets (i.e. mappings) with information describing how they are to be displayed. For example, a mapping with a two-dimensional domain and a one-dimensional range could be rendered as a contour plot, a wire frame mesh plot, a surface plot, or an image plot. These rendering techniques all take the same fundamental data, embodied in the mapping structure (see Figure 9).<p>
</a>
<a name="542098">
<h2>2.11 Summary and Further Directions</h2>
</a>
<a name="542099">
PANACEA provides a collection of services to facilitate the production of numerical simulation codes and to increase the reusability and shareability of simulation packages. By attempting to provide services to do everything that is generic to “all” simulation codes, PANACEA also provides some standards of data exchange, management, and visualization.<p>
</a>
<a name="542100">
Although coded in C, PANACEA is coded in an object-oriented style. The most important ramification of this is that abstract objects (e.g., packages, variables, and mappings) have a relatively faithful concrete representation. This puts PANACEA on a sound conceptual basis and helps to delineate the generic from the specific in simulation code systems.<p>
</a>
<a name="542101">
As an additional benefit, the modularization that follows from this style lends itself to natural coarse-grained parallelization of code systems. In practice, packages can also be organized so as to make fine grained parallelization possible because the controlling structures and the data objects of PANACEA do not really intrude into the detailed workings of the simulation algorithms. Therefore, while PANACEA helps modularize a code system so that packages or large parts of packages might be run in parallel, it does not interfere with parallelizing individual routines which permit it.<p>
</a>
<a name="542102">
The encapsulation of abstract objects in concrete representations facilitates the process of manipulating these objects symbolically. I have used PANACEA with the PACT SCHEME interpreter to give users of one PANACEA code the ability to manipulate the code in very broad and general ways.<p>
</a>
<a name="542103">
This technique allows the manipulation of the packages’ execution sequences, the examination of the state of the running code, and the changes in the state of the code. When carried to its logical conclusion, this method will also permit the prototyping of algorithms at the LISP level before investing the effort in writing more efficient code at a lower level.<p>
</a>
<a name="542104">
Finally, PANACEA can bind simulation packages generated by a tool, such as ALPAL, into entire code systems. PANACEA complements ALPAL very neatly by attending to large control and data flow issues, while ALPAL uses the PANACEA services rather than getting loaded down with these issues.<p>
</a>
<a name="542105">
<h1>3.0 PANACEA Objects</h1>
</a>
<a name="542106">
In this section, the objects of PANACEA and their properties are discussed in detail.<p>
</a>
<a name="542107">
<h2>3.1 Packages</h2>
</a>
<a name="542108">
A PANACEA package consists of a collection of controlling information which is defined by the application through function calls to PANACEA routines and a set of functions supplied by the application. These functions perform a well-defined set of operations and PANACEA invokes them in the proper sequence to carry out the desired simulation.<p>
</a>
<a name="542109">
The functions that an application supplies are:<p>
</a>
<A NAME="542110">gencmd() define the generator commands
<P><A NAME="542111">dfstrc(pdrs) define data structures used in package variables
<P><A NAME="542112">intrn() intern variables into the database at generation
<P><A NAME="542113">defun(pck) define new units
<P><A NAME="542114">defvar(pck) define the package variables
<P><A NAME="542115">defcnt(pck) define the package controls
<P><A NAME="542116">inizer(pck) initialize the package
<P><A NAME="542117">main(pck) the main entry into the package
<P><A NAME="542118">ppsor(pr, t) handle package specific output
<P><A NAME="542119">finzer(pck) close out the package
<P><a name="542120">
All of these functions except ppsor must return 1 if they complete successfully and 0 otherwise.<p>
</a>
<a name="542121">
<h2>3.2 Variables</h2>
</a>
<a name="542122">
A PANACEA variable consists of a collection of descriptive information and the actual data associated with a computational quantity used in a numerical simulation. PANACEA variables can be scalars or arrays. They correspond to what code developers traditionally think of as variables in systems of equations. In addition they include information which governs their use. This information is collectively referred to as the attributes of the variable.<p>
</a>
<a name="542123">
Each PANACEA variable has a name. Since PANACEA variables are owned by packages, each PANACEA variable knows which package owns it. PANACEA variables also contain dimension information. Since PANACEA variables are defined before the values of their dimensions are known, PANACEA variables keep track of the addresses of the application code variables (typically scalars) which will contain the correct values for the dimensions when the PANACEA variables are accessed. PANACEA variables also contain conversion factors between CGS, internal, and external unit systems. Because the data associated with a PANACEA variable may be stored on disk files, PANACEA variables keep track of information describing any relevant data files.<p>
</a>
<a name="542124">
Three key attributes of a PANACEA variable require special discussion. Typically the data associated with PANACEA variables is in the form of an array which can be extremely large depending on the problems with which the application code deals. To provide flexibility, efficiency, and control, the data arrays associated with PANACEA variables can be allocated and released under the control of these three attributes. The scope attribute, class attribute, and persistence attribute. The scope attribute pertains to the lifetime of a PANACEA variable or more precisely its data. The class attribute defines the behavior of PANACEA variables with regard to PA_CONNECT. The persistence attribute defines the behavior of PANACEA variables with respect to PA_DISCONNECT.<p>
</a>
<a name="542125">
<h3>3.2.1 </a>Variable Scopes</h3>
</a>
<a name="542126">
The scopes defined in PANACEA are:<p>
</a>
<A NAME="542127"><PRE> </a>DEFN
</PRE><A NAME="542128"><PRE> </a>RESTART
</PRE><A NAME="542129"><PRE> </a>DMND
</PRE><A NAME="542130"><PRE> </a>RUNTIME
</PRE><A NAME="542131"><PRE> </a>EDIT
</PRE><a name="542132">
<h4>3.2.1.1 </a>DEFN</h4>
</a>
<a name="542133">
PANACEA variables with the DEFN scope are considered to be a part of the state of the numerical simulation. These variables, in contrast to RESTART variables whose properties they share, must be read from a state file before the RESTART variables. This distinction permits variables which define certain problem parameters (hence the designation DEFiNition variables) to be read in first, before the other RESTART variables which may depend on the information these variables specify.<p>
</a>
<a name="542134">
<h4>3.2.1.2 </a>RESTART</h4>
</a>
<a name="542135">
PANACEA variables with the RESTART scope are considered to be a part of the state of the numerical simulation. These variables define the state of the numerical simulation and cannot be derived from other state information. The PANACEA model dictates that with a complete set of RESTART variables in a state file, the simulation can be restarted from the state defined by the contents of the state file. These variables are read into database memory at the time the state file is opened.<p>
</a>
<a name="542136">
<h4>3.2.1.3 </a>DMND</h4>
</a>
<a name="542137">
PANACEA variables with the DMND scope are considered to be a part of the state of the numerical simulation. Like RESTART variables they define the state of the simulation. It sometimes happens that for reasons of size or efficiency, some state variables should not be read into memory when the file is opened, but when access is specifically requested via </a>PA_CONNECT. The DeMaND scope provides for this contingency.<p>
</a>
<a name="542138">
<h4>3.2.1.4 </a>RUNTIME</h4>
</a>
<a name="542139">
PANACEA variables with RUNTIME scope can be derived from state information defined by the RESTART variables. As such it is not necessary to write them into state files or read them out of state files. This saves space in state files and the time it would take to read or write the variables.<p>
</a>
<a name="542140">
<h4>3.2.1.5 </a>EDIT</h4>
</a>
<a name="542141">
There are some variables in a system of equations to be simulated which are only temporary or auxiliary. It is often useful to look at these variables for purposes such as debugging. In every computational cycle, PANACEA variables with EDIT scope are allocated just before the packages which own them are entered, their contents are “edited” as soon as the package returns, and the space associated with them is released.<p>
</a>
<a name="542142">
<h3>3.2.2 </a>Variable Classes</h3>
</a>
<a name="542143">
Another attribute is class. The class attribute specifies the behavior of PANACEA regarding the handling of the various scopes especially in the </a>PA_CONNECT process. The classes defined in PANACEA are:<p>
</a>
<A NAME="542144"><PRE> </a>REQU
</PRE><A NAME="542145"><PRE> </a>OPTL
</PRE><A NAME="542146"><PRE> </a>PSEUDO
</PRE><a name="542147">
<h4>3.2.2.1 </a>REQU</h4>
</a>
<a name="542148">
PANACEA variables in this class are required. That is to say that when access to such a variable is requested via </a>PA_CONNECT, it is a fatal error if at least one of the following sources of data values does not provide data for the PANACEA variable: the state file (DEFN, RESTART, and DMND variables only check this source); source specification data (via </a>SPECIFY command); an initializer function (optionally provided with the variable definition); or a broadcast default value (optionally provided with the variable definition). These means of initialization are attempted in the order stated above.<p>
</a>
<a name="542149">
<h4>3.2.2.2 </a>OPTL</h4>
</a>
<a name="542150">
PANACEA variables with the OPTL class can be thought of as optional. In contrast to REQU variables, PANACEA returns a NULL pointer if the data cannot be found for the variable (by the same procedure as for the REQU variables) instead of terminating with a fatal error.<p>
</a>
<a name="542151">
Many variables which are part of the state of a simulation are nevertheless OPTL. The usual case is for a variable in a package which may be turned off. In such a case, the absence of the variable in the state file is not an impediment to the running of the simulation.<p>
</a>
<a name="542152">
<h4>3.2.2.3 PSEUDO</h4>
</a>
<a name="542153">
In some simulations auxiliary variables which can be thought of logically as arrays are implemented as scalars or subsets of other arrays. Ordinarily this is no concern of PANACEA. However, when it is desired to put such data out into post processor files, PANACEA attempts to assist. The generic descriptive information that PANACEA requires of all variables is insufficient to specify how to construct the logical array structure desired in the output files from the actual information as implemented in the simulation coding. The application package will have to supply routines to accomplish this mapping. The PSEUDO class tells PANACEA to handle such a variable in a special way which requires more coordination with the particular package. The PSEUDO class is currently only meaningful in connection with variables of EDIT scope.<p>
</a>
<a name="542154">
<h3>3.2.3 </a>Variable Persistence</h3>
</a>
<a name="542155">
Another attribute is that of variable persistence. This specifies the actions PANACEA is to take in the </a>PA_DISCONNECT process. The defined persistence categories are:<p>
</a>
<A NAME="542156"><PRE> </a>KEEP
</PRE><A NAME="542157"><PRE> </a>CACHE_F
</PRE><A NAME="542158"><PRE> </a>CACHE_R
</PRE><A NAME="542159"><PRE> </a>REL
</PRE><a name="542160">
<h4>3.2.3.1 </a>KEEP</h4>
</a>
<a name="542161">
In many situations the application developer wants to relinquish the applications access to a PANACEA variable’s data yet insure that PANACEA retains the data in memory. This allows for rapid re-connections later via </a>PA_CONNECT.<p>
</a>
<a name="542162">
<h4>3.2.3.2 </a>CACHE_F</h4>
</a>
<a name="542163">
For larger data arrays, the application may not wish to have access to the data for part of the simulation, not wish PANACEA to retain it in memory either, and still require the data at a later point in the simulation. The CACHE_F persistence tells PANACEA to write the data out to a temporary scratch file and release its own copy from memory. It also tells PANACEA that the variable will never have its size changed via </a>PA_change_dim or </a>PA_change_length.<p>
</a>
<a name="542164">
<h4>3.2.3.3 </a>CACHE_R</h4>
</a>
<a name="542165">
For larger data arrays, the application may not wish to have access to the data for part of the simulation, not wish PANACEA to retain it in memory either, and still require the data at a later point in the simulation. The CACHE_R persistence tells PANACEA to write the data out to a temporary scratch file and release its own copy from memory. Unlike CACHE_F, CACHE_R variables can be resized. The distinction is enforced for the sake of execution and disk space efficiency.<p>
</a>
<a name="542166">
<h4>3.2.3.4 </a>REL</h4>
</a>
<a name="542167">
Perhaps the most common situation for RUNTIME variables when the data is not going to be used and the application invokes </a>PA_DISCONNECT is for PANACEA to release the memory associated with the PANACEA variable data altogether. It is not retained in any way and would have to be recreated if a </a>PA_CONNECT call were to be made at a later point in the simulation.<p>
</a>
<a name="542168">
The following table summarizes the interaction between scope, class, and persistence:<p>
</a>
<A NAME="542169"><TT>
</TT><BR><A NAME="545815"><TT>SCOPE CLASS PERSISTENCE
</TT><BR><A NAME="545816"><TT> REQU OPTL PSEUDO KEEP CACHE _X REL
</TT><BR><A NAME="545817"><TT>DEFN + - - - - -
</TT><BR><A NAME="545807"><TT>RESTART + + - + + +
</TT><BR><A NAME="542174"><TT>DMND + + - + + +
</TT><BR><A NAME="542175"><TT>RUNTIME + + - + + +
</TT><BR><A NAME="542176"><TT>EDIT - - + NA NA NA
</TT><BR><a name="542177">
<p>
</a>
<a name="542178">
In this table “+” means that the behavior of the combination is defined, and “-” means that the behavior of the combination is undefined. The undefined combinations may be defined in later releases of PANACEA.<p>
</a>
<a name="542179">
<h3>3.2.4 </a>Variable Centering</h3>
</a>
<a name="542180">
PANACEA variables which are not scalar variables as defined by PA_inst_scalar also have an attribute specifying their centering relative to the “spatial” mesh. (NOTE: this concept will be properly generalized in future releases of PANACEA). <p>
</a>
<a name="542181">
The legal values for the </a>centering of variables with an underlying mesh are:<p>
</a>
<A NAME="542182"><PRE> </a>Z_CENT </a>zone centered
</PRE><A NAME="542183"><PRE> </a>N_CENT </a>node centered
</PRE><A NAME="542184"><PRE> </a>E_CENT </a>edge centered
</PRE><A NAME="542185"><PRE> </a>F_CENT </a>face centered
</PRE><A NAME="542186"><PRE> </a>U_CENT </a>uncentered
</PRE><a name="542187">
<h3>3.2.5 </a>Variable Allocation</h3>
</a>
<a name="542188">
PANACEA can handle either of two situations on a variable by variable basis. One, memory is to be dynamically allocated and managed by the PANACEA database services. Two, memory is statically allocated by a compiler and the PANACEA database services hand out pointers to such spaces.<p>
</a>
<a name="542189">
The legal values for the </a>allocation strategy of a variable are:<p>
</a>
<A NAME="542190"><PRE> </a>STATIC </a>static allocation (i.e. by compiler)
</PRE><A NAME="542191"><PRE> </a>DYNAMIC </a>dynamic allocation (i.e. by run time memory manager)
</PRE><a name="542192">
<p>
</a>
<a name="542193">
<h2>3.3 Source Variables</h2>
</a>
<a name="542194">
<h2>3.4 Initial Value Specifications</h2>
</a>
<a name="542195">
<h2>3.5 Plot Requests</h2>
</a>
<a name="542196">
<h2>3.6 Unit Specifications</h2>
</a>
<a name="542197">
<h1>4.0 The PANACEA C API</h1>
</a>
<a name="542198">
The following commands are broken down by service category. The PANACEA service categories are:<p>
</a>
<A NAME="AUTOTAG;"><B>Database Definition and Control
</B><A NAME="AUTOTAG;"><B>Variable Definition
</B><A NAME="AUTOTAG;"><B>Control Definition
</B><A NAME="AUTOTAG;"><B>Unit Definition and Control
</B><A NAME="AUTOTAG;"><B>Database Access
</B><A NAME="AUTOTAG;"><B>Simulation Control
</B><A NAME="AUTOTAG;"><B>Plot Request Handling
</B><A NAME="AUTOTAG;"><B>Initial Value Problem Generation Support
</B><A NAME="AUTOTAG;"><B>Source Variable/Initial Value Data Handling
</B><A NAME="AUTOTAG;"><B>Time History Data Management
</B><A NAME="AUTOTAG;"><B>Miscellaneous
</B><a name="542210">
Commands are also sorted into two categories: Basic, PANACEA applications must invoke these functions at some appropriate point; and optional, these are provided for the benefit of the application but are not required.<p>
</a>
<a name="542211">
<h2>4.1 Database Definition and Control Functionality</h2>
</a>
<a name="542212">
This group of functions governs the creation and management of the PANACEA database. They are relevant to both the generator and simulation codes.<p>
</a>
<a name="542213">
These functions let applications define packages to PANACEA and query PANACEA about packages in a PANACEA code.<p>
</a>
<a name="542214">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="542216"></a>PA_gen_package
<P><A NAME="542217"></a>PA_run_time_package
<P><A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="542220"></a>PA_current_package
<P><A NAME="542221"></a>PA_install_function
<P><A NAME="542222"></a>PA_install_identifier
<P><A NAME="545042"></a>PA_GET_MAX_NAME_SPACE
<P><A NAME="545047"></a>PA_SET_MAX_NAME_SPACE
<P><a name="542223">
<h3>4.1.1 </a>PA_CURRENT_PACKAGE</h3>
</a>
<a name="542224">
<p>
</a>
<A NAME="542225"><PRE> PA_current_package()
</PRE><a name="542226">
At any moment in a </a>generator or </a>simulation code, PANACEA has a notion of the </a>current package. It is the one whose controls are connected to the global variables, </a>swtch, </a>param, and </a>name. Applications may wish to query or access the current </a>package.<p>
</a>
<a name="542227">
This function returns a pointer to the PA_package structure which is PANACEA’s current package.<p>
</a>
<a name="542228">
<h3>4.1.2 </a>PA_DEF_PACKAGE</h3>
</a>
<A NAME="542229"><PRE>
</PRE><A NAME="542230"><PRE> PA_def_package(char *name,
</PRE><A NAME="542231"><PRE> PFInt gcmd,
</PRE><A NAME="542232"><PRE> PFInt dfs,
</PRE><A NAME="542233"><PRE> PFInt dfu,
</PRE><A NAME="542234"><PRE> PFInt dfr,
</PRE><A NAME="542235"><PRE> PFInt cnt,
</PRE><A NAME="542236"><PRE> PFInt izr,
</PRE><A NAME="542237"><PRE> PFInt inr,
</PRE><A NAME="542238"><PRE> PFInt mn,
</PRE><A NAME="542239"><PRE> PFPPM_mapping psr,
</PRE><A NAME="542240"><PRE> PFInt fzr,
</PRE><A NAME="542241"><PRE> PFInt pcmd,
</PRE><A NAME="542242"><PRE> char *fname),
</PRE><A NAME="542243"><PRE>
</PRE><a name="542244">
To define a </a>package in complete generality the following functions must be supplied:<p>
</a>
<A NAME="542245">gcmd installs the functions which handle generator </a>commands
<P><A NAME="542246">dfs defines </a>data structures used by package variables
<P><A NAME="542247">dfu defines the </a>units of the package
<P><A NAME="542248">dfr defines the </a>variables of the package
<P><A NAME="542249">cnt defines and sets initial or default values for the </a>controls of the package
<P><A NAME="542250">izr </a>initializes the package one time before the main entry point is called
<P><A NAME="542251">inr </a>interns package variables into the database prior to writing the state file
<P><A NAME="542252">mn the </a>main entry point for the package
<P><A NAME="542253">psr makes </a>PM_mappings (for </a>output purposes) of package specific quantities
which PANACEA’s generic capabilities cannot handle
<P><A NAME="542254">fzr </a>finalizes a package one time before exiting the simulation
<P><A NAME="542255">pcmd installs the functions which handle </a>post processor commands
<P><A NAME="542256">fname names a dictionary file to be processed at runtime by the dfr function
<P><a name="542257">
With the exception of the psr function which returns a pointer to a PM_mapping structure if successful and NULL otherwise, these functions must return TRUE if successful and FALSE otherwise. If any of these functions is irrelevant to the package being defined, NULL should be passed in in its place.<p>
</a>
<a name="542258">
The name of the package must also be supplied.<p>
</a>
<a name="542259">
If successful, the function returns a pointer to a PA_package. Since PANACEA keeps an internal list of packages, it is not necessary for the application to do anything with the return value of this function.<p>
</a>
<a name="542260">
<h3>4.1.3 </a>PA_GEN_PACKAGE</h3>
</a>
<a name="542261">
<p>
</a>
<A NAME="542262"><PRE> PA_gen_package(char *name,
</PRE><A NAME="542263"><PRE> PFInt cmd,
</PRE><A NAME="542264"><PRE> PFInt dfs,
</PRE><A NAME="542265"><PRE> PFInt dfu,
</PRE><A NAME="542266"><PRE> PFInt dfr,
</PRE><A NAME="542267"><PRE> PFInt cnt,
</PRE><A NAME="542268"><PRE> PFInt inr,
</PRE><A NAME="542269"><PRE> char *fname)
</PRE><a name="542270">
To define a </a>package to a </a>generator code the application must supply functions:<p>
</a>
<A NAME="542271">cmd installs the functions which handle generator </a>commands
<P><A NAME="542272">dfs defines </a>data structures used by package variables
<P><A NAME="542273">dfu defines the </a>units of the package
<P><A NAME="542274">dfr defines the </a>variables of the package
<P><A NAME="542275">cnt defines and sets initial or default values for the </a>controls of the package
<P><A NAME="542276">inr </a>interns package variables into the database prior to writing the state file
<P><A NAME="542277">fname names a dictionary file to be processed at runtime by the dfr function
<P><a name="542278">
These functions must return TRUE if successful and FALSE otherwise. If any of these functions is irrelevant to the package being defined, NULL should be passed in in its place.<p>
</a>
<a name="542279">
The name of the package must also be supplied.<p>
</a>
<a name="542280">
If successful, the function returns a pointer to a PA_package. Since PANACEA keeps an internal list of packages, it is not necessary for the application to do anything with the return value of this function.<p>
</a>
<a name="545038">
<h3>4.1.4 </a>PA_GET_MAX_NAME_SPACE</h3>
</a>
<A NAME="545039"><PRE>
</PRE><A NAME="545040"><PRE> PA_GET_MAX_NAME_SPACE(int flag)
</PRE><a name="545041">
Returns the value of the name space flag in the argument flag. See the </a>PA_SET_NAME_SPACE function for further information.<p>
</a>
<a name="542281">
<h3>4.1.5 </a>PA_INSTALL_FUNCTION</h3>
</a>
<a name="542282">
<p>
</a>
<A NAME="542283"><PRE> PA_install_function(char *name, PFByte fnc)
</PRE><a name="542284">
This function provides a means for applications to make arbitrary procedures known to the PANACEA database. This is critical for </a>interactive or</a> interpreted applications which may need to invoke a function given only its name. It associates an address to which control can be passed with an ASCII name.<p>
</a>
<a name="542285">
The arguments to this function are: name, an ASCII string naming the function; and fnc, a compiled function which may be invoked by PANACEA. Currently the function installed this way can take no arguments and returns no value.<p>
</a>
<a name="542286">
This function returns nothing.<p>
</a>
<a name="542287">
<h3>4.1.6 </a>PA_INSTALL_IDENTIFIER</h3>
</a>
<a name="542288">
<p>
</a>
<A NAME="542289"><PRE> PA_install_identifier(char *name, byte *vr)
</PRE><a name="542290">
This function provides a means for applications to make arbitrary compiled variables known to the PANACEA database. This is critical for </a>interactive or</a> interpreted applications which may need to refer to a variable given only its name. It associates an address with which a value can be accessed with an ASCII name.<p>
</a>
<a name="542291">
The arguments to this function are: name, an ASCII string naming the function; and vr, a compiled variable which may be referenced by PANACEA.<p>
</a>
<a name="542292">
This function returns nothing.<p>
</a>
<a name="542293">
<h3>4.1.7 </a>PA_RUN_TIME_PACKAGE</h3>
</a>
<a name="542294">
<p>
</a>
<A NAME="542295"><PRE> PA_run_time_package(char *name,
</PRE><A NAME="542296"><PRE> PFInt dfs,
</PRE><A NAME="542297"><PRE> PFInt dfu,
</PRE><A NAME="542298"><PRE> PFInt dfr,
</PRE><A NAME="542299"><PRE> PFInt cnt,
</PRE><A NAME="542300"><PRE> PFInt izr,
</PRE><A NAME="542301"><PRE> PFInt mn,
</PRE><A NAME="542302"><PRE> PFPPM_mapping psr,
</PRE><A NAME="542303"><PRE> PFInt fzr,
</PRE><A NAME="542304"><PRE> char *fname)
</PRE><a name="542305">
To define a </a>package to a </a>simulation code the application must supply functions:<p>
</a>
<A NAME="542306">dfs defines </a>data structures used by package variables
<P><A NAME="542307">dfu defines the </a>units of the package
<P><A NAME="542308">dfr defines the </a>variables of the package
<P><A NAME="542309">cnt defines and sets initial or default values for the </a>controls of the package
<P><A NAME="542310">izr initializes the package (executed once before any main entry point)
<P><A NAME="542311">mn the </a>main entry point of the package (executed once each major cycle)
<P><A NAME="542312">psr returns a PM_mapping pointer for PSEUDO EDIT variables (each cycle)
<P><A NAME="542313">fzr shuts down the package (executed once after the last call to any main entry)
<P><a name="542314">
All of the functions except psr must return TRUE if successful and FALSE otherwise. psr returns a pointer to a PM_mapping associated with a plot request of a </a>PSEUDO EDIT variable. If any of these functions is irrelevant to the package being defined, NULL should be passed in in its place.<p>
</a>
<a name="542315">
The information defined via dfu, dfr, and cnt can alternatively be specified in an </a>ASCII text file. This file can be specified by fname. If fname is not NULL, dfu and cnt are ignored and the file fname is read in and processed using a dfr to supply interpretation of the dictionary fields.<p>
</a>
<a name="542316">
The name of the package must also be supplied.<p>
</a>
<a name="542317">
If successful, the function returns a pointer to a PA_package. Since PANACEA keeps an internal list of packages, it is not necessary for the application to do anything with the return value of this function.<p>
</a>
<a name="545043">
<h3>4.1.8 </a>PA_SET_MAX_NAME_SPACE</h3>
</a>
<A NAME="545044"><PRE>
</PRE><A NAME="545045"><PRE> PA_SET_MAX_NAME_SPACE(int flag)
</PRE><a name="545046">
If flag is TRUE then the </a>name space of PANACEA variables is maximized in that variables are defined to the database under a name made up from the package name, a hyphen, and the variable name. In this scheme, there is less potential for name conflicts. If flag is FALSE then variable are defined to the database simply by the variable name.<p>
</a>
<a name="542318">
<h2>4.2 Variable Definers</h2>
</a>
<a name="542319">
Variables are one of the main objects in PANACEA and consequently their definition to the database is crucial. Both </a>scalar and </a>array variables can be defined in the </a>database and variables may have any data </a>type used in the </a>simulation code system.<p>
</a>
<a name="542320">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542323">
<li></a>PA_def_var
</a>
<A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><a name="542327">
<li></a>PA_definitions()
</a>
<a name="542328">
<li></a>PA_variables(int flag)
</a>
</ul><a name="542329">
<h3>4.2.1 </a>PA_DEF_VAR</h3>
</a>
<a name="542330">
<p>
</a>
<A NAME="542331"><PRE> PA_def_var(char *vname,
</PRE><A NAME="542332"><PRE> char *vtype,
</PRE><A NAME="542333"><PRE> byte *viv,
</PRE><A NAME="542334"><PRE> byte *vif,
</PRE><A NAME="542335"><PRE> ...)
</PRE><a name="542336">
To </a>define a </a>variable to the PANACEA </a>database certain descriptive information must be supplied.<p>
</a>
<A NAME="542337">vname defines the name of the variable
<P><A NAME="542338">vtype defines the </a>type of the variable (variables may be of any type including structures)
<P><A NAME="542339">viv a pointer to a </a>default initial value to be broadcast into the array
<P><A NAME="542340">vif a pointer to a function which can be called to </a>compute initial values for the
variable
<P><A NAME="542341">... defines the attributes, </a>dimensions, </a>physical units, and optionally the data of the
variable
<P><a name="542342">
The attributes of the variable are specified by attribute identifier, attribute value pairs. When all the attributes are specified the </a>ATTRIBUTE keyword terminates the processing of attribute specifications. By default, variables will be defined as RUNTIME, OPTL, REL, U_CENT, DYNAMIC. To set the scope, the </a>SCOPE keyword is used followed by one of the values:</a> DEFN; </a>RESTART; </a>DMND; </a>RUNTIME; </a>or EDIT. To set the class, the </a>CLASS keyword is used followed by one of the values: </a>REQU; </a>OPTL</a></a>; or </a>PSEUDO. To set the persistence, the </a>PERSIST keyword is used followed by one of the values: </a>KEEP; </a>CACHE_F, </a>CACHE_R; or </a>REL. To set the centering of the variable with respect to its spatial mesh use the </a>CENTER keyword followed by one of the values: </a>Z_CENT; </a>N_CENT; </a>E_CENT; </a>F_CENT; or </a>U_CENT.<p>
</a>
<a name="542343">
The dimensions specifications consist of a set of pointers to the integer variables which will contain the actual dimensional numbers. It is crucial to realize that at the time that the variable is being defined the sizes of the array dimensions is not known (in general). Therefore, pointers to the scalars which will contain that information must be provided! The list of dimensions is terminated with the PANACEA defined pointer, </a>DIMENSION.<p>
</a>
<a name="542344">
Another feature of dimension specification in PANACEA is that a dimension can be specified in three ways. First a single pointer indicates to PANACEA that the dimension scalar represents the number of elements in that dimension. Second, each time the PANACEA provided pointer, </a>PA_DON, occurs in the dimension list, the next two integer pointers in the argument list are interpreted to be a pointer to the value of the minimum index value of the dimension and a pointer to the value of the number of elements in the dimension of the variable, respectively (i.e. DON means Dimension, Offset, and Number). Third, each time the PANACEA provided pointer, </a>PA_DUL, occurs in the dimension list, the next two integer pointers in the argument list are interpreted to be a pointer to the value of the minimum index value of the dimension and a pointer to the value of the maximum index value of the dimension of the variable, respectively (i.e. DUL means Dimension, Upper, and Lower). The reason for this distinction between the second and third case is that although the arithmetic is simple, the meaning of the scalar variables describing the dimensions is different. Since PANACEA does not deal with the dimension range values but pointers to the values, it must respect the semantics of these dimensioning scalars. This in turn dictates the presence of at least the two cases here.<p>
</a>
<a name="542345">
The physical units of a PANACEA variable are described in terms of a collection of conversion factors from </a>CGS units. There are arrays of factors for both internal and external units. They are indexed the same way and so the effective specification of the physical units of a variable are in terms of the integer indices into these arrays. PA_def_var processes the arguments after the dimension specification terminator, </a>DIMENSION, and before the unit specification terminator, </a>UNITS. It takes the arguments from left to right and multiplies the values in the conversion factor arrays indexed by the values together. If it encounters the PANACEA provided argument, </a>PER, it collects the factors remaining until, UNITS, and divides the two terms to compute the correct conversion factors (internal and external units conversion). The arguments are handled this way so that the call to PA_def_var reads very much like English and the units are “clear” at a glance. PANACEA goes further by providing the following constants as the index values:<p>
</a>
<A NAME="542346"><PRE> Macro Variable Unit
</PRE><A NAME="542347"><PRE> </a>RAD </a>PA_radian </a>angle
</PRE><A NAME="542348"><PRE> </a>STER </a>PA_steradian </a>solid angle
</PRE><A NAME="542349"><PRE> </a>MOLE </a>PA_mole </a>number
</PRE><A NAME="542350"><PRE> </a>Q </a>PA_electric_charge </a>Coulomb
</PRE><A NAME="542351"><PRE> </a>CM </a>PA_cm </a>length
</PRE><A NAME="542352"><PRE> </a>SEC </a>PA_sec </a>time
</PRE><A NAME="542353"><PRE> </a>G </a>PA_gram </a>mass
</PRE><A NAME="542354"><PRE> </a>EV </a>PA_eV </a>energy
</PRE><A NAME="542355"><PRE> </a>K </a>PA_kelvin </a>temperature
</PRE><A NAME="542356"><PRE> </a>ERG </a>PA_erg </a>energy
</PRE><A NAME="542357"><PRE> </a>CC </a>PA_cc </a>volume
</PRE><a name="542358">
Application developers are encouraged to use this practice to make the units they define easy to read in this context of variable definition.<p>
</a>
<a name="542359">
Finally, if a variable is defined with </a>ALLOCATION equal to </a>STATIC, a </a>pointer to data for the variable must be supplied after the UNITS terminator.<p>
</a>
<a name="542360">
The syntax for </a>PA_def_var is:<p>
</a>
<a name="542361">
<p>
</a>
<A NAME="542362"><PRE> PA_def_var(name, type, init_val_ptr, init_func_ptr,
</PRE><A NAME="542363"><PRE> attribute_spec, ..., ATTRIBUTE,
</PRE><A NAME="542364"><PRE> dimension_spec, ..., DIMENSION,
</PRE><A NAME="542365"><PRE> unit_spec, ..., UNITS
</PRE><A NAME="542366"><PRE> [, data_ptr])
</PRE><A NAME="542367"><PRE>
</PRE><A NAME="542368"><PRE> attribute_spec := attribute_id, attribute_val
</PRE><A NAME="542369"><PRE> attribute_id := SCOPE | CLASS | PERSIST |
</PRE><A NAME="542370"><PRE> CENTER | ALLOCATION
</PRE><A NAME="542371"><PRE>
</PRE><A NAME="542372"><PRE> attribute_val(SCOPE) := DEFN | RESTART | DMND |
</PRE><A NAME="542373"><PRE> RUNTIME | EDIT
</PRE><A NAME="542374"><PRE> attribute_val(CLASS) := REQU | OPTL | PSEUDO
</PRE><A NAME="542375"><PRE> attribute_val(PERSIST) := REL | KEEP | CACHE_F | CACHE_R
</PRE><A NAME="542376"><PRE> attribute_val(ALLOCATION):= STATIC | DYNAMIC
</PRE><A NAME="542377"><PRE> attribute_val(CENTER) := Z_CENT | N_CENT | F_CENT |
</PRE><A NAME="542378"><PRE> E_CENT | U_CENT
</PRE><A NAME="542379"><PRE>
</PRE><A NAME="542380"><PRE> dimension_spec := n_elements_ptr |
</PRE><A NAME="542381"><PRE> PA_DUL, lower_bnd_ptr, upper_bnd_ptr |
</PRE><A NAME="542382"><PRE> PA_DON, offset_ptr, n_elements_ptr
</PRE><A NAME="542383"><PRE> unit_spec := unit_index | PER
</PRE><A NAME="542384"><PRE> unit_index := RAD | STER | MOLE | Q | CM | SEC |
</PRE><A NAME="542385"><PRE> G | EV | K | ERG | CC |
</PRE><A NAME="542386"><PRE> <user defined index>
</PRE><a name="542387">
<p>
</a>
<a name="542388">
No attributes are required to be set (</a>ATTRIBUTE must appear in the arg list) and the default values are:<p>
</a>
<a name="542389">
RUNTIME, OPTL, REL, U_CENT, DYNAMIC<p>
</a>
<a name="542390">
<h2>4.3 Control Accessors/Definers</h2>
</a>
<A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542394">
<li></a>PA_mk_control(PA_package *new, char *s, int n_a, int n_p, int n_s)
</a>
<a name="542395">
<li></a>PA_control_set(char *s)
</a>
</ul><a name="542396">
<h2>4.4 Unit Conversion/Definition Functionality</h2>
</a>
<a name="542397">
<h3>4.4.1 Unit/Conversion Definitions</h3>
</a>
<a name="542398">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542401">
<li></a>PA_def_units(int flag)
</a>
<a name="542402">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><a name="542404">
<p>
</a>
<a name="542405">
<li></a>PA_def_unit(double fac, ...)
</a>
<a name="542406">
<p>
</a>
</ul><a name="542407">
<h3>4.4.2 Unit/Conversion Setup</h3>
</a>
<a name="542408">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542411">
<li></a>PA_set_conversions(int flag)
</a>
<a name="542412">
<li></a>PA_physical_constants_ext()
</a>
<a name="542413">
<li></a>PA_physical_constants_cgs()
</a>
<a name="542414">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><a name="542417">
<li></a>PA_physical_constants_int()
</a>
<a name="542418">
<p>
</a>
<a name="542419">
<p>
</a>
<a name="542420">
<p>
</a>
</ul><a name="542421">
<h2>4.5 Database Access Functionality</h2>
</a>
<a name="542422">
<h3>4.5.1 Variable Access for Simulation</h3>
</a>
<a name="542423">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="542425"></a>PA_INTERN
<P><A NAME="542426"></a>PA_CONNECT
<P><A NAME="542427"></a>PA_DISCONNECT
<P><A NAME="542428"></a>PA_ACCESS
<P><A NAME="542429"></a>PA_RELEASE
<P><A NAME="542430"></a>PA_change_dim
<P><A NAME="AUTOTAG;"><B></a>PA_change_size
</B><a name="542432">
<h4>4.5.1.1 </a>PA_INTERN</h4>
</a>
<A NAME="542433"><PRE>
</PRE><A NAME="542434"><PRE> PA_INTERN(byte *var, char *name)
</PRE><a name="542435">
Intern a given array in the variable data base.<p>
</a>
<a name="542436">
<h4>4.5.1.2 </a>PA_CONNECT</h4>
</a>
<A NAME="542437"><PRE>
</PRE><A NAME="542438"><PRE> PA_CONNECT(byte *var, char *name, int flag)
</PRE><a name="542439">
In the PANACEA model the PANACEA </a>database is viewed as the </a>manager of dynamic memory. As such one of its key functions is to dispense pointers to the data associated with PANACEA variables. PA_CONNECT is the principal means of doing this.<p>
</a>
<a name="542440">
The call to this </a>macro takes the application pointer which is to be set, var; the name of the variable in the PANACEA database; and a flag that informs PANACEA that it must track this pointer so that its value may be reset it another database operation changes the space to which the pointer points (see </a>PA_change_dim). If the value of flag is TRUE then PANACEA will reset the application’s pointer if the space is reallocated or released by another PANACEA operation.<p>
</a>
<a name="542441">
The following steps are performed when a PA_CONNECT request is made:<p>
</a>
<A NAME="542442"><PRE> </PRE>The variable specified by name is looked up in the database hash table.
<BR><a name="542443">
If the variable is not found </a>PA_ERR is called and the application exits with the error message: VARIABLE name NOT IN DATA BASE - PA_GET_ACCESS.<p>
</a>
<A NAME="542444"><PRE> </PRE>The </a>class of the variable is checked. If the class is PSEUDO PA_ERR is called and the
application exits.
<BR><A NAME="542445"><PRE> </PRE>If the </a>scope of the variable is DMND and it has not already been read in (presumably
by another PA_CONNECT operation) the variable is read in from the state dump file.
<BR><A NAME="542446"><PRE> </PRE>Each PANACEA variable has two sets of </a>dimensions: 1) derived from the contents of
the addresses of integer scalars (necessary for correct dynamic behavior at run time);
and 2) derived from the dimensions as specified in the PDB file (necessary for correct
storage behavior). On PA_CONNECT, PANACEA reconciles these two sets of dimensions to obtain consistency and computes the actual current size in elements of the variable. The reconciliation of the two sets of dimensions is done via the following steps:
<BR><ul><a name="542447">
<li>Compute the total length implied by the file dimensions.
</a>
<a name="542448">
<li>Compute the total length implied by the PANACEA dimensions.
</a>
<a name="542449">
<li>If they agree assume that they are </a>consistent.
</a>
<a name="542450">
<li>If the file dimensions imply a zero length, assume they are inconsistent and change them to match the PANACEA dimensions.
</a>
<a name="542451">
<li>If the PANACEA dimensions imply a zero length, assume they are inconsistent and change them to match the file dimensions.
</a>
<a name="542452">
<li>Otherwise assume the PANACEA dimensions are correct and change the file dimensions to match.
</a>
<a name="542453">
<li>Set both the PANACEA variable size and the file size to the selected size.
</a>
<A NAME="542454"><PRE> </PRE>If the class of the variable is REQU the following actions are taken:
<BR><a name="542455">
<li>If the </a>PANACEA variable data pointer is not NULL return it.
</a>
<a name="542456">
<li>If the PANACEA variable data pointer is NULL; the size determined above is positive; and one of following initialization modes is available (in order): a default value; source variable, or initialization function, attempt to initialize a block of space.
</a>
<a name="542457">
<li>If the preceding step fails </a>PA_ERR is called and the application exits
</a>
<A NAME="542458"><PRE> </PRE>If the class of the variable is OPTL the following actions are taken:
<BR><a name="542459">
<li>If the PANACEA variable data pointer is not NULL return it.
</a>
<a name="542460">
<li>If the PANACEA variable data pointer is NULL; the size determined above is positive; and one of following initialization modes is available (in order): default value; source variable; or initialization function, attempt to initialize a block of space.
</a>
<a name="542461">
<li>If the preceding step fails NULL is returned.
</a>
<A NAME="542462"><PRE> </PRE>Set the PANACEA variable data pointer to the address of the space
<BR><A NAME="542463"><PRE> </PRE>Set the pointer var to the address of the space.
<BR><A NAME="542464"><PRE> </PRE>If track is TRUE, PANACEA is requested to keep </a>track of this reference by adding it to
the list of tracked pointers.
<BR><A NAME="542465"><PRE> </PRE>Return.
<BR></ul><a name="542466">
<h4>4.5.1.3 </a>PA_DISCONNECT</h4>
</a>
<A NAME="542467"><PRE>
</PRE><A NAME="542468"><PRE> PA_DISCONNECT(char *name, byte *ptr)
</PRE><a name="542469">
In the course of doing a numerical simulation, an application may wish to </a>relinquish access to the data associated with a PANACEA variable. Most likely this access was obtained via </a>PA_CONNECT. Since PANACEA is monitoring </a>database access, it is not a good idea to simply set the application pointer to NULL because the </a>database may be tracking that pointer and it could mysteriously be reappear later with a value.The correct procedure to invoke PA_DISCONNECT to inform PANACEA that this access is to be terminated.<p>
</a>
<a name="542470">
The arguments to this </a>macro are: name, the name of the PANACEA variable in the database; and ptr, the application pointer whose access to the data associated with the named PANACEA variable is to be relinquished.<p>
</a>
<a name="542471">
The following steps are carried out when a call to inform the PANACEA database that the application no longer requires a specified reference to the data associated with a PANACEA variable:<p>
</a>
<A NAME="542472"><PRE> </PRE>The variable specified by name is looked up in the database hash table. If the variable is
not found </a>PA_ERR is called and the application exits with the error message: VARIABLE name NOT IN DATA BASE - PA_REL_ACCESS
<BR><A NAME="542473"><PRE> </PRE>If the </a>scope of the variable is EDIT the following actions are taken:
<BR><ul><a name="542474">
<li>The space associated with the PANACEA variable is freed
</a>
<a name="542475">
<li>The PANACEA variable’s data pointer is set to NULL
</a>
<A NAME="542476"><PRE> </PRE>Remove the reference ptr from the </a>list of pointers pointing to this data
<BR><A NAME="542477"><PRE> </PRE>Set the reference ptr to NULL if the PANACEA variable is not a scalar variable as
defined by </a>PA_inst_scalar.
<BR><A NAME="542478"><PRE> </PRE>If there are no more references to the data associated with the PANACEA variable the
following actions are taken:
<BR><a name="542479">
<li>If the </a>persistence of the PANACEA variable is REL, the space associated with the PANACEA variable is freed and the PANACEA data pointer is set to NULL.
</a>
<a name="542480">
<li>If the persistence of the PANACEA variable is CACHE_F or CACHE_R, the space associated with the PANACEA variable is freed after writing it out to a disk file (this last part not implemented yet) and the PANACEA data pointer is set to NULL.
</a>
<a name="542481">
<li>If the persistence of the PANACEA variable is KEEP, the space associated with the PANACEA variable is retained by the PANACEA database.
</a>
<a name="542482">
<li>If the variable is a </a>scalar as defined by </a>PA_inst_scalar, the scalar’s value is set to an appropriate representation of 0.
</a>
<A NAME="542483"><PRE> </PRE>Return
<BR></ul><a name="542484">
<h4>4.5.1.4 </a>PA_ACCESS</h4>
</a>
<A NAME="542485"><PRE> PA_ACCESS(char * name, type, long offs, long ne)
</PRE><a name="542486">
Return a connection to a sub-space of an array.<p>
</a>
<a name="542487">
<h4>4.5.1.5 </a>PA_RELEASE</h4>
</a>
<A NAME="542488"><PRE> PA_RELEASE(char * name, byte * ptr, long offs, long ne)
</PRE><a name="542489">
Release the access to an array sub-space.<p>
</a>
<a name="542490">
<h4>4.5.1.6 </a>PA_CHANGE_DIM</h4>
</a>
<A NAME="542491"><PRE>
</PRE><A NAME="542492"><PRE> void PA_change_dim(int *pdm, int val)
</PRE><a name="542493">
Change the value of an integer quantity, pointed to by pdm, to which the PANACEA variable dimensions of one or more PANACEA variables point to the given value, val, and reallocate all of the PANACEA variables which have this quantity as a dimension. This rather elaborate and expensive operation is the most consistent way of handling PANACEA database variables whose sizes are changing as a result of dynamically recomputing the computational domain (e.g. a spatial or frequency mesh). The alternate method provided by </a>PA_change_size is not consistent and can produce extremely bizarre behavior which is difficult to debug.<p>
</a>
<a name="542494">
The arguments to this function are: pdm, a pointer to the integer value to be changed (this should match at least one of the quantities used in a </a>PA_def_var call used to define the database variables; and val, the new value to be assigned to the location pointed to by pdm.<p>
</a>
<a name="542495">
NOTE: the use of val here is trivial but is intended to help enforce the discipline of using </a>PA_change_dim correctly.<p>
</a>
<a name="542496">
<h4>4.5.1.7 </a>PA_CHANGE_SIZE</h4>
</a>
<A NAME="542497"><PRE>
</PRE><A NAME="542498"><PRE> void PA_change_size(char *name, int flag)
</PRE><a name="542499">
Reallocate the PANACEA variable specified by name using the current values implied by set of dimensions specified by flag. With this call it is assumed that the application has changed the value of a dimensioning integer and now wants PANACEA to handle the resizing of the space associated with a particular PANACEA variable. In general, this is an extremely risky thing to do. However, some code systems which have automatically generated code can enforce consistency via the code generator. In such a case, the performance overhead of </a>PA_change_dim is diminished to some extent.<p>
</a>
<a name="542500">
The arguments to this function are: name, a string containing the name of the PANACEA database variable to be reallocated; and flag, an integer having either of the two values </a>PA_FILE or </a>PA_DATABASE signifying which set of dimensions (file or database respectively) to use in enforcing consistency on this one variable.<p>
</a>
<a name="542501">
NOTE: use this function at your own risk!<p>
</a>
<a name="542502">
<h3>4.5.2 </a>Structured Data Support</h3>
</a>
<a name="542503">
To provide an additional dimension in data handling for FORTRAN packages and to support interactive runtime data structuring, PANACEA supplies services to define, create and release instances, and get or set members of data structure independent of any compiled in data structure such as a C struct or FORTRAN common block. This facility is completely </a>dynamic and </a>interpreted at runtime.<p>
</a>
<a name="542504">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="542506"></a>PA_mk_instance
<P><A NAME="542507"></a>PA_rl_instance
<P><A NAME="542508"></a>PA_get_member
<P><A NAME="542509"></a>PA_set_member
<P><a name="542510">
<h4>4.5.2.1 </a>PA_MK_INSTANCE</h4>
</a>
<A NAME="542511"><PRE>
</PRE><A NAME="542512"><PRE> void *PA_mk_instance(char *name,
</PRE><A NAME="542513"><PRE> char *type,
</PRE><A NAME="542514"><PRE> long n)
</PRE><A NAME="542515"><PRE>
</PRE><a name="542516">
Allocate and return a pointer to an array of</a> instances of a type (defined in the virtual internal file) which is n items long.The type must have been defined from a </a>dictionary file or from an explicit function call.<p>
</a>
<a name="542517">
The return value of this function is a pointer to the space allocated to hold n elements each of which is of sufficient byte size to hold one item of type type. The instance is also installed in an internal table under the name name so that PANACEA can track the variable.<p>
</a>
<a name="542518">
<h4>4.5.2.2 </a>PA_RL_INSTANCE</h4>
</a>
<A NAME="542519"><PRE>
</PRE><A NAME="542520"><PRE> void PA_rl_instance(char *name)
</PRE><A NAME="542521"><PRE>
</PRE><a name="542522">
Release the named </a>instance of an entry allocated with </a>PA_mk_instance.<p>
</a>
<a name="542523">
This function has no return value.<p>
</a>
<a name="542524">
<h4>4.5.2.3 </a>PA_GET_MEMBER</h4>
</a>
<A NAME="542525"><PRE>
</PRE><A NAME="542526"><PRE> void *PA_get_member(char *name,
</PRE><A NAME="542527"><PRE> char *member)
</PRE><A NAME="542528"><PRE>
</PRE><a name="542529">
Get the named member of the instance of a </a>structured variable allocated by </a>PA_mk_instance under the name name.<p>
</a>
<a name="542530">
A pointer to the </a>member is returned if successful and NULL is returned otherwise.<p>
</a>
<a name="542531">
<h4>4.5.2.4 </a>PA_SET_MEMBER</h4>
</a>
<A NAME="542532"><PRE>
</PRE><A NAME="542533"><PRE> void PA_set_member(char *name,
</PRE><A NAME="542534"><PRE> void *data,
</PRE><A NAME="542535"><PRE> char *member)
</PRE><A NAME="542536"><PRE>
</PRE><a name="542537">
Set the named member of an instance of a data structure return by </a>PA_mk_instance to point to the given data. The instance is identified by name.<p>
</a>
<a name="542538">
This function returns nothing.<p>
</a>
<a name="542539">
<h3>4.5.3 Variable Access for Output</h3>
</a>
<a name="542540">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542543">
<li></a>PA_sub_select(PA_variable *pp, C_array *arr, long *pitems, long *poffs, long *pstr)
</a>
<a name="542544">
<li></a>PA_general_select(PA_variable *pp, C_array *arr, unsigned long *pitems, unsigned long *pdims,
</a>
<a name="542545">
unsigned long *poffs, unsigned long *pstr, unsigned long *pmax)<p>
</a>
<a name="542546">
<p>
</a>
</ul><a name="542547">
<h2>4.6 </a>Simulation Control</h2>
</a>
<a name="542548">
The functions in the section describe the services PANACEA offers the simulation phase code. These are fairly high level functions which encapsulate much of the detailed inner workings of the PANACEA database and the PANACEA packages.<p>
</a>
<a name="542549">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="542551"></a>PA_rd_restart
<P><A NAME="542552"></a>PA_wr_restart
<P><A NAME="542553"></a>PA_init_system
<P><A NAME="542554"></a>PA_terminate
<P><a name="542555">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="542557"></a>PA_simulate
<P><A NAME="542558"></a>PA_run_packages
<P><A NAME="542559"></a>PA_fin_system
<P><A NAME="542560"></a>PA_advance_t
<P><a name="542561">
<h3>4.6.1 </a>PA_RD_RESTART</h3>
</a>
<A NAME="542562"><PRE>
</PRE><A NAME="542563"><PRE> void PA_rd_restart(char *rsname,
</PRE><A NAME="542564"><PRE> int convs)
</PRE><A NAME="542565"><PRE>
</PRE><a name="542566">
This function reads a </a>state file as a prelude to performing simulations starting from the state specified in the file. Statistics about the amount of data in the state file which is actually loaded into memory are printed<p>
</a>
<a name="542567">
The arguments are: rsname, the name of the state file; and convs, the type of conversions to do. The conversion options are:<p>
</a>
<A NAME="542568"><PRE> </a>NONE perform no conversions
</PRE><A NAME="542569"><PRE> </a>INT_CGS convert from </a>internal units to CGS units
</PRE><A NAME="542570"><PRE> </a>INT_EXT convert from internal units to external units
</PRE><A NAME="542571"><PRE> </a>EXT_CGS convert from </a>external units to CGS units
</PRE><A NAME="542572"><PRE> </a>EXT_INT convert from external units to internal units
</PRE><A NAME="542573"><PRE> </a>CGS_INT convert from </a>CGS units to internal units
</PRE><A NAME="542574"><PRE> </a>CGS_EXT convert from CGS units to external units
</PRE><a name="542575">
The internal system of units is defined by the </a>unit array. The external system of units is defined by the </a>convrsn array.<p>
</a>
<a name="542576">
The system of units of the data in the state file is under the control of the code developer, but it must be consistent.<p>
</a>
<a name="542577">
This function returns no value.<p>
</a>
<A NAME="542578"><B>SEE ALSO:</B>PA_wr_restart
<BR><a name="542579">
<h3>4.6.2 </a>PA_SIMULATE</h3>
</a>
<A NAME="542580"><PRE>
</PRE><A NAME="542581"><PRE> void PA_simulate(double tc,
</PRE><A NAME="542582"><PRE> int nc,
</PRE><A NAME="542583"><PRE> int nz,
</PRE><A NAME="542584"><PRE> double ti,
</PRE><A NAME="542585"><PRE> double tf,
</PRE><A NAME="542586"><PRE> double dtf_init,
</PRE><A NAME="542587"><PRE> double dtf_min,
</PRE><A NAME="542588"><PRE> double dtf_max,
</PRE><A NAME="542589"><PRE> double dtf_inc,
</PRE><A NAME="542590"><PRE> char *rsname,
</PRE><A NAME="542591"><PRE> char *edname,
</PRE><A NAME="542592"><PRE> char *ppname,
</PRE><A NAME="542593"><PRE> char *pvname)
</PRE><A NAME="542594"><PRE>
</PRE><a name="542595">
This function is provided as a template for </a>controlling and coordinating the </a>execution of the packages and other PANACEA services. It is clear that no one routine can satisfy all of the requirements of all simulation systems, and this routine does not really attempt to do so. It is provided as an example to be used in constructing the simulation control for any given application code and to be used by those applications for which it is sufficient.<p>
</a>
<a name="542596">
The arguments are: tc, the current problem time; nc, the current problem cycle; nz, the number of zones/cells/particles in the problem; ti, the starting time; tf, the stopping time; dtf_init, the initial fractional time step; dtf_min, the minimum fractional time step; dtf_max, the maximum, fractional time step; dtf_inc, the fractional increase in the time step each cycle; rsname, the name of the most recently read </a>state file; edname, the name of the </a>ASCII edit file; ppname, the name of the </a>time history file; and pvname, the name of the </a>PVA file. Each file name is a base name ending with two digits. Each time a new file in each of the respective families is closed, the next member of the family is given a name with the number indicated by the final digits advanced by one.<p>
</a>
<a name="542597">
</a>PA_simulate performs the following actions in a loop over time from ti to tf:<p>
</a>
<A NAME="542598"><PRE> </PRE>calls </a>PA_source_variable to update all source variables in the simulation for the current time and time step
<BR><A NAME="542599"><PRE> </PRE>calls </a>PA_run_package to execute each installed package in the order of installation
<BR><A NAME="542600"><PRE> </PRE>calls </a>PA_dump_pp to check all plot requests and write out any requested data in the
time history and PVA files for the current time and cycle
<BR><A NAME="542601"><PRE> </PRE>calls </a>PA_file_mon to determine whether the current edit, time history, or PVA file need
to be closed and the next member of the family created
<BR><A NAME="542602"><PRE> </PRE>calls </a>PA_advance_t to poll the packages for their time step votes and determine the
next time step
<BR><a name="542603">
At the conclusion of the loop over time, </a>PA_simulate, prints a message to the terminal announcing that the stop time has been reached, and then it calls </a>PA_fin_system to call the package </a>fzr routines and print the </a>simulation statistics to the terminal.<p>
</a>
<a name="542604">
This routine has no return value.<p>
</a>
<A NAME="542605"><B>SEE ALSO:</B></a>PA_source_variable, </a>PA_run_packages, </a>PA_dump_pp, </a>PA_file_mon,
</a>PA_advance_t, </a>PA_fin_system.
<BR><a name="542606">
<h3>4.6.3 </a>PA_RUN_PACKAGES</h3>
</a>
<A NAME="542607"><PRE>
</PRE><A NAME="542608"><PRE> void PA_run_packages(double t,
</PRE><A NAME="542609"><PRE> double dt,
</PRE><A NAME="542610"><PRE> int cycle)
</PRE><A NAME="542611"><PRE>
</PRE><a name="542612">
This routine executes the </a>main entry point of each installed </a>package and dumps any information corresponding to a plot request associated with the package.<p>
</a>
<a name="542613">
The arguments are: t, the current problem time; dt, the current problem time step; and cycle, the current problem cycle number. This information is passed to the package’s main entry point via the package structure.<p>
</a>
<a name="542614">
Prior to executing the package main, the memory for </a>PSEUDO EDIT variables is allocated. After the package main is finished, the PSEUDO EDIT variable data are dumped and the memory allocated to it is released.<p>
</a>
<a name="542615">
This function has no return value.<p>
</a>
<A NAME="542616"><B>SEE ALSO:</B></a>PA_simulate
<BR><a name="542617">
<h3>4.6.4 </a>PA_FIN_SYSTEM</h3>
</a>
<A NAME="542618"><PRE>
</PRE><A NAME="542619"><PRE> void PA_fin_system(int nz,
</PRE><A NAME="542620"><PRE> int nc)
</PRE><A NAME="542621"><PRE>
</PRE><a name="542622">
This function runs the finalizer routine for each installed package and prints </a>performance statistics on the packages for the simulation (or partial simulation) just concluded. The performance statistics are based on the </a>CPU time spent in the package as reported by the package and the </a>storage space used by the package in kBytes. Whether this information is gathered is up to the package developer. If no information is stored in a package, PANACEA does not print any statistics for that package. The macros </a>PA_MARK_TIME, </a>PA_ACCM_TIME, </a>PA_MARK_SPACE, and </a>PA_ACCM_SPACE can be used by the package developer to save the timing and memory usage information in the package structure.<p>
</a>
<a name="542623">
The arguments are: nz, the number of zones/cells/particles in the problem; and nc the number of cycles run.<p>
</a>
<a name="542624">
This function has no return value.<p>
</a>
<A NAME="542625"><B>SEE ALSO:</B></a>PA_simulate, </a>PA_MARK_TIME, </a>PA_ACCM_TIME, </a>PA_MARK_SPACE,
and </a>PA_ACCM_SPACE
<BR><a name="542626">
<h3>4.6.5 </a>PA_ADVANCE_T</h3>
</a>
<A NAME="542627"><PRE>
</PRE><A NAME="542628"><PRE> double PA_advance_t(double dtmn,
</PRE><A NAME="542629"><PRE> double dtn,
</PRE><A NAME="542630"><PRE> double dtmx)
</PRE><A NAME="542631"><PRE>
</PRE><a name="542632">
This function computes a </a>time step for the next </a>major computational cycle based on the time step “votes” returned in each package after the package </a>main entry point is executed. The algorithm is that the smallest time step from the packages is computed, the smaller of this time step, dtn, and dtmx is taken; and the larger of dtmn and the result of the previous step is returned.<p>
</a>
<a name="542633">
The arguments are: dtmn, the minimum allowed time step, dtn, the current time step; and dtmx, the maximum allowed time step.<p>
</a>
<a name="542634">
The computed new time step is returned by this function.<p>
</a>
<A NAME="542635"><B>SEE ALSO:</B></a>PA_simulate
<BR><a name="542636">
<h3>4.6.6 </a>PA_WR_RESTART</h3>
</a>
<A NAME="542637"><PRE>
</PRE><A NAME="542638"><PRE> void PA_wr_restart(char *rsname)
</PRE><A NAME="542639"><PRE>
</PRE><a name="542640">
This function causes a state file to be written out. The name of the file is specified by rsname and after the file is closed successfully, the name is incremented. By convention files which PANACEA writes have names ending with two digits. When PANACEA increments a file name it adds one to the number represented by the two digits and replaces them in the file name.<p>
</a>
<a name="542641">
All of the variables defined to PANACEA as RESTART or DEFN are written out to the state file. They should be the variables required to define the state so that a future run of the simulation code can start up with only the state file’s information.<p>
</a>
<a name="542642">
The argument is: rsname, the name to be used for the state file.<p>
</a>
<A NAME="542643"><B>SEE ALSO:</B>PA_rd_restart
<BR><a name="542644">
<h3>4.6.7 </a>PA_INIT_SYSTEM</h3>
</a>
<A NAME="542645"><PRE>
</PRE><A NAME="542646"><PRE> void PA_init_system(double t,
</PRE><A NAME="542647"><PRE> double dt,
</PRE><A NAME="542648"><PRE> int nc,
</PRE><A NAME="542649"><PRE> char *edname,
</PRE><A NAME="542650"><PRE> char *ppname,
</PRE><A NAME="542651"><PRE> char *pvname)
</PRE><A NAME="542652"><PRE>
</PRE><a name="542653">
This function </a>initializes a PANACEA </a>simulation phase code. It is not for </a>generation phase programs. It performs the following actions:<p>
</a>
<A NAME="542654"><PRE> </PRE>opens any specified </a>source files and initializes the appropriate </a>source variables
<BR><A NAME="542655"><PRE> </PRE>opens and initializes the specified </a>ASCII edit file, </a>time history file, and </a>PVA file
<BR><A NAME="542656"><PRE> </PRE>runs the </a>initializer function for each package
<BR><A NAME="542657"><PRE> </PRE>processes the </a>plot requests for run time efficiency
<BR><A NAME="542658"><PRE> </PRE>calls </a>PA_dump_pp to make an initial dump of the information specified by the plot
requests
<BR><a name="542659">
The arguments to this function are: t, the initial problem time; dt, the initial problem time step; nc, the initial problem major cycle number; edname, the name of the ASCII edit file; ppname, the name of the time history file; and pvname, the name of the PVA file.<p>
</a>
<a name="542660">
This function has no return value.<p>
</a>
<A NAME="542661"><B>SEE ALSO:</B>PA_dump_pp
<BR><a name="542662">
<h3>4.6.8 </a>PA_TERMINATE</h3>
</a>
<A NAME="542663"><PRE>
</PRE><A NAME="542664"><PRE> void PA_terminate(char *edname,
</PRE><A NAME="542665"><PRE> char *ppname,
</PRE><A NAME="542666"><PRE> char *pvname,
</PRE><A NAME="542667"><PRE> int cycle)
</PRE><A NAME="542668"><PRE>
</PRE><a name="542669">
This function gracefully shuts down a simulation run. It closes any open </a>ASCII edit files, </a>time history files, </a>PVA files, </a>cache files, or </a>state files. If this function is not called, these files may not be </a>valid data files!<p>
</a>
<a name="542670">
The arguments are: edname, the name of the ASCII edit file; ppname, the name of the time history file; pvname, the name of the PVA file; and cycle, the current problem cycle. These arguments are currently unused, however, that is subject to change.<p>
</a>
<a name="542671">
This function returns nothing.<p>
</a>
<a name="542672">
<h2>4.7 Plot Request Handling</h2>
</a>
<a name="542673">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542676">
<li></a>PA_time_plot(char *rname, void *vr)
</a>
<a name="542677">
<li></a>PA_dump_time(PA_set_spec *pi, double tc, double dtc, int cycle)
</a>
<a name="542678">
<li></a>PA_put_set(PDBfile *file, PM_set *s)
</a>
<a name="542679">
<li></a>PA_put_mapping(PG_device *dev, PDBfile *file, PM_mapping *f, int plot_type)
</a>
<a name="542680">
<li></a>PA_set_data(char *name, C_array *arr, int *pcent)
</a>
<a name="542681">
<li></a>PA_fill_component(double *data, int len, int *pist, int ne)
</a>
<a name="542682">
<li></a>PA_build_mapping(PA_plot_request *pr, PFPPM_set build_ran, double t)
</a>
<a name="542683">
<li></a>PA_non_time_domain(PA_plot_request *pr)
</a>
<a name="542684">
<p>
</a>
<a name="542685">
<li></a>PA_PR_RANGE_SIZE(PA_plot_request *pr, long n)
</a>
<a name="542686">
Reset the size of the plot request range.<p>
</a>
<a name="542687">
<li></a>PA_STASH_SP_SCALAR(char *name, long indx, double val)
</a>
<a name="542688">
Save a scalar value for a spatial pseudo variable plot request.<p>
</a>
<a name="542689">
<li></a>PA_STASH_TV_SCALAR(char *name, double val)
</a>
<a name="542690">
Save a scalar value for a time pseudo variable plot request.<p>
</a>
<a name="542691">
<li></a>PA_MESH_RANGE_SEARCH(PA_plot_request *pr, long off, char *fn)
</a>
<a name="542692">
Loop the range specification of the plot request to setup an invocation of PA_STASH_SP_SCALAR.<p>
</a>
<a name="542693">
<li></a>PA_TIME_RANGE_SEARCH(PA_plot_request *pr, char *fn)
</a>
<a name="542694">
Loop the range specification of the plot request to setup an invocation of PA_STASH_TV_SCALAR.<p>
</a>
<a name="542695">
<li></a>PA_END_MESH_SEARCH(PA_plot_request *pr, expr)
</a>
<a name="542696">
Gracefully terminate the loop started by PA_MESH_RANGE_SEARCH.<p>
</a>
<a name="542697">
<li></a>PA_END_TIME_SEARCH(PA_plot_request *pr)
</a>
<a name="542698">
Gracefully terminate the loop started by PA_TIME_RANGE_SEARCH.<p>
</a>
<a name="542699">
<li></a>PA_STORE_TV(PA_plot_request *pr, double val)
</a>
<a name="542700">
Save away the given time value data.<p>
</a>
</ul><a name="542701">
<h2>4.8 Generation Support</h2>
</a>
<a name="542702">
<p>
</a>
<a name="542703">
<h3>4.8.1 Generator Command Management</h3>
</a>
<a name="542704">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="AUTOTAG;"><B>
</B><A NAME="542707"></a> PA_inst_com
<P><A NAME="542708"></a>PA_inst_pck_gen_cmmnds()
<P><A NAME="542709"></a>PA_inst_c(char *cname, byte *cvar, int ctype, int cnum, PFVoid cproc, PFVoid chand)
<P><A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="542712"></a>PA_get_commands
<P><a name="542713">
<h4>4.8.1.1 </a>PA_INST_COM</h4>
</a>
<A NAME="542714"><PRE>
</PRE><A NAME="542715"><PRE> HASHTAB *PA_inst_com(void)
</PRE><A NAME="542716"><PRE>
</PRE><a name="542717">
Initialize and set up the table of commands needed to parse an ASCII input file and generate an initial state for a simulation. This function does the following thing:<p>
</a>
<A NAME="542718"><PRE> </PRE>Installs the generic commands
<BR><A NAME="542719"><PRE> </PRE>Installs the package generator commands (see the gencmd argument of the
</a>PA_gen_package function)
<BR><A NAME="542720"><PRE> </PRE>Calls </a>PA_definitions to define the </a>unit and </a>conv arrays for PANACEA.
<BR><A NAME="542721"><PRE> </PRE>Calls </a>PA_variables to complete the definition of the database variables (the units are not
completed with this call since the input deck may redefine the unit system).
<BR><a name="542722">
The generic PANACEA supplied generator commands are:<p>
</a>
<A NAME="542723"></a>end end the generation run
<P><A NAME="542724"></a>read read the named input file
<P><A NAME="542725"></a>dump dump a state file
<P><A NAME="542726"></a>specify specify an initial value condition
<P><A NAME="542727"></a>s continue an initial value condition specification
<P><A NAME="542728"></a>graph make a plot request
<P><A NAME="542729"></a>package set the current package
<P><A NAME="542730"></a>switch set the value of a switch in the current package
<P><A NAME="542731"></a>parameter set the value of a switch in the current package
<P><A NAME="542732"></a>name set the value of a name in the current package
<P><A NAME="542733"></a>unit set an internal conversion factor (sets the internal system of units)
<P><A NAME="542734"></a>conversion set an external conversion factor (sets the external system of units)
<P><a name="542735">
<h4>4.8.1.2 </a>PA_GET_COMMANDS</h4>
</a>
<A NAME="542736"><PRE>
</PRE><A NAME="542737"><PRE> PA_get_commands(FILE *fp, void (*errfnc)())
</PRE><A NAME="542738"><PRE>
</PRE><a name="542739">
This function reads from the specified </a>input stream, parses command lines, and dispatches to functions installed in the PANACEA command table via the </a>PA_inst_c function.<p>
</a>
<A NAME="542740"><PRE> </PRE>It executes the following steps in a loop:
<BR><A NAME="542741"><PRE> </PRE>Get a line of text
<BR><A NAME="542742"><PRE> </PRE>If no more text is available close the stream (if it is not stdin) and return.
<BR><A NAME="542743"><PRE> </PRE>If the line is a blank or comment line loop
<BR><A NAME="542744"><PRE> </PRE>Lookup up the first token in the PANACEA command table
<BR><A NAME="542745"><PRE> </PRE>If there is an associated function dispatch to it
<BR><A NAME="542746"><PRE> </PRE>If there is no associated function call the errfnc from the argument list.
<BR><a name="542747">
<h3>4.8.2 Generation Time Functions</h3>
</a>
<a name="542748">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><ul><a name="542750">
<li></a>PA_name_files(char *base_name, char **ped, char **prs, char **ppp, char **pgf)
</a>
<A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><a name="542754">
<li></a>PA_clear()
</a>
<a name="542755">
<p>
</a>
<a name="542756">
<p>
</a>
</ul><a name="542757">
<h2>4.9 Source Variable/Initial Value Data Handling</h2>
</a>
<a name="542758">
PANACEA provides functionality for handling data which is to be used as </a>boundary condition or </a>source information or to set values of database variables. One application of this capability is to use the results of one simulation to drive a second simulation whose intent is to simulate one phenomenon in an environment which itself is the result of a simulation. To emphasize the inherent unity of sources and to provide a simple mechanism for applications, PANACEA defines the concept of an initial value specification. Initial value specifications are made in the ASCII input defining a problem with the specify command. The data may be provided with the specify or s commands. It may also be provided from a source file which is produced by a utility which the simulation system designer must write. This utility uses PANACEA services to format data in such a way that PANACEA can access it quickly and efficiently at run time. This is also done because it is impossible for PANACEA to know about even the smallest fraction of potential sources for initial value data and their formats.<p>
</a>
<a name="542759">
An</a> initial value specification is the mathematical notion of initial value data which together with a set of differential equations defines an</a> initial value problem. PANACEA defines a structure called a </a>PA_iv_specification to represent an initial value specification. In particular, an initial value specification has:<p>
</a>
<A NAME="542760"><PRE> </PRE>a type: bc, for boundary condition which specifies information on the boundary of the
computational mesh; src, for source which specifies a set of values imposed in some
region of the interior of the computational mesh; or the name of a database variable
whose values throughout the simulation are interpolated from a set of predetermined
data
<BR><A NAME="542761"><PRE> </PRE>a name by which the initial value specification may be selected
<BR><A NAME="542762"><PRE> </PRE>a file name in which the actual initial value data may be found
<BR><A NAME="542763"><PRE> </PRE>a flag specifying whether the data is to be interpolated or treated as discrete sets that are
to be used as the exact specified times
<BR><A NAME="542764"><PRE> </PRE>the number of data points in one time slice of the data set
<BR><A NAME="542765"><PRE> </PRE>various representations of any data that exists in memory (PANACEA manages this
with the aim of handling this data as efficiently as possible with respect to both time
and space)
<BR><a name="542766">
To help manage initial value specifications whose data is to be imported from a source file, PANACEA defines the concept of a </a>source variable and a structure called a </a>PA_src_variable. The source variable contains information about the data in a source file and the data structures necessary to manage the interpolations which may be done by PANACEA. Source variables must have counterparts in the database. They fundamentally are devices to help load the appropriate initial value data into a database variable.<p>
</a>
<a name="542767">
The following functions are all optional in that an application can use PANACEA without using the initial value handling services of the library. If the application does use these services, the basic operations at the application level involve accessing initial value data and interpolating values from initial value data structures. There is also a more global operation which tells PANACEA to update all sourced variables.<p>
</a>
<a name="542768">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><A NAME="542771"></a>PA_get_iv_source
<P><A NAME="542772"></a>PA_get_source
<P><A NAME="542773"></a>PA_interp_src
<P><A NAME="542774"></a>PA_intr_spec
<P><A NAME="542775"></a>PA_source_variables
<P><a name="542776">
<h3>4.9.1 PA_GET_IV_SOURCE</h3>
</a>
<A NAME="542777"><PRE>
</PRE><A NAME="542778"><PRE> PA_iv_specification *PA_get_iv_source(char *name)
</PRE><A NAME="542779"><PRE>
</PRE><a name="542780">
This routine searches the list of initial value specifications and returns the named </a>PA_iv_specification. In order for this function to succeed, the given name must match the name used in at least one </a>specify command in the problem definition.<p>
</a>
<a name="542781">
Input to this function is: name, an ASCII string naming the initial value specification for which to search.<p>
</a>
<a name="542782">
Output from this function is a pointer to a </a>PA_iv_specification if successful and NULL otherwise.<p>
</a>
<a name="542783">
<h3>4.9.2 </a>PA_GET_SOURCE</h3>
</a>
<A NAME="542784"><PRE>
</PRE><A NAME="542785"><PRE> PA_src_variable *PA_get_source(char *s, int start_flag)
</PRE><A NAME="542786"><PRE>
</PRE><a name="542787">
This function returns a pointer to a source variable specified by the name, s. It is permissible to have many instances of a source variable in a source file or to have many source files with the same source variable. In such a case each call to </a>PA_get_source returns the next available instance of the source variable. If the start_flag is TRUE the first instance is found and returned.<p>
</a>
<a name="542788">
Input to this function is: s, an ASCII string naming the source variable; and start_flag, an integer signalling whether to start from the beginning of the source variable list or from the last position searched.<p>
</a>
<a name="542789">
Output from this function is a pointer to a </a>PA_src_variable if successful and NULL otherwise.<p>
</a>
<a name="542790">
<h3>4.9.3 </a>PA_INTERP_SRC</h3>
</a>
<A NAME="542791"><PRE>
</PRE><A NAME="542792"><PRE> void PA_interp_src(void *v,
</PRE><A NAME="542793"><PRE> PA_src_variable *svp,
</PRE><A NAME="542794"><PRE> int ni,
</PRE><A NAME="542795"><PRE> int nf,
</PRE><A NAME="542796"><PRE> double t,
</PRE><A NAME="542797"><PRE> double dt)
</PRE><A NAME="542798"><PRE>
</PRE><a name="542799">
This function interpolates the data from the given PA_src_variable into the space pointed to by v from v[ni] to v[nf]. The data is interpolated in time at time t with timestep dt. The interpolation is quadratic.<p>
</a>
<a name="542800">
The input to this function is: v, a pointer to the target array; svp, a pointer to a PA_src_variable containing the source data; ni, an integer starting index into v; nf, an integer ending index into v; t, a double value specifying the interpolation time; and dt, a double value specifying the time step.<p>
</a>
<a name="542801">
This function has no return value.<p>
</a>
<a name="542802">
<h3>4.9.4 </a>PA_INTR_SPEC</h3>
</a>
<A NAME="542803"><PRE>
</PRE><A NAME="542804"><PRE> double PA_intr_spec(PA_iv_specification *sp,
</PRE><A NAME="542805"><PRE> double t,
</PRE><A NAME="542806"><PRE> double val,
</PRE><A NAME="542807"><PRE> long off)
</PRE><A NAME="542808"><PRE>
</PRE><a name="542809">
This function finds the interpolated source value from the given initial value specification information. For efficiency sake when interpolating the initial value data, the index into the data set from each call is saved and used as the starting point for the next interpolation. This means that the initial value data is assumed to be stored in increasing time order.<p>
</a>
<a name="542810">
The input to this function is: sp, a pointer to a </a>PA_iv_specification containing the initial value data to be interpolated; t, a double containing the time value at which the interpolated value is required; val, a double containing a default value if there is no data in the initial value data set for the given time, t; and off, a long offset telling how much of the initial value data to skip past (the initial value data may be prefaced with parameters describing the data that follows).<p>
</a>
<a name="542811">
The return value of this function is the interpolated value of the initial value data set.<p>
</a>
<a name="542812">
<h3>4.9.5 </a>PA_SOURCE_VARIABLES</h3>
</a>
<A NAME="542813"><PRE>
</PRE><A NAME="542814"><PRE> void PA_source_variables(double t,
</PRE><A NAME="542815"><PRE> double dt)
</PRE><A NAME="542816"><PRE>
</PRE><a name="542817">
This function sets the values (by interpolation) of the database variables which have been identified with source variables. This function is called once per major time cycle in </a>PA_simulate. Those applications controlling their own time stepping must call this function if they wish to have PANACEA handle source data. In </a>PA_simulate, this function is called before the packages are executed.<p>
</a>
<a name="542818">
This function performs the following steps:<p>
</a>
<A NAME="542819"><PRE> </PRE>Loops over each source variable set up by </a>PA_init_system.
<BR><A NAME="542820"><PRE> </PRE>If the database variable corresponding to the source variable does not exist or has a
NULL data pointer no further action is performed.
<BR><A NAME="542821"><PRE> </PRE></a>PA_interp_src is called to interpolate the source variable data in time and fill the data
associated with the database variable.
<BR><a name="542822">
The input to this function is: t, a double containing the time at which the source variable are to be interpolated; and dt, a double containing the corresponding time step.<p>
</a>
<a name="542823">
This function returns no value.<p>
</a>
<a name="542824">
<h2>4.10 </a>Time History Data Management</h2>
</a>
<a name="542825">
The following functions define a service for the management of time history data.<p>
</a>
<a name="542826">
This facility implements a time history data management model designed with the following goals:<p>
</a>
<ul><a name="542827">
<li>Easy to use
</a>
<a name="542828">
<li>Flexible enough to accommodate virtually any code system requirements
</a>
<a name="542829">
<li>Support families of files
</a>
<a name="542830">
<li>Support restart from any cycle in a simulation (the instance index is the key to this)
</a>
<a name="542831">
<li>The raw time history data should also be comprehensible.
</a>
<a name="542832">
The model chosen centers on the definition of a time history data structure which is defined at run time. Each such structure has a single domain component and multiple range components. These correspond to a set of time plots for which data is written at a particular frequency as determined by the application. By defining however many such structures are required, code systems can manage many sets of time plots each at their own frequency. New sets can be added over the course of a simulation. These structures are set up via the </a>PA_th_def_rec call. Once defined, the application can buffer up any amount of time history data and then write it out with </a>PA_th_write. Thus applications determine how much data will be kept in the running code.<p>
</a>
<a name="542833">
The time history data is written out in families </a>PDB of files. A family of time history PDB files is started with a call to </a>PA_th_open. The function </a>PA_th_family is used to close out one member of the family and start the next if the current file’s size is above a user set threshold. Each file in a family maintains a link to the previous file in the family. This is very useful when applications restart a simulation from an earlier state and, potentially, follow a different branch of execution. Knowing the last time history file in any branch allows the unambiguous reconstruction of the time history data for that branch.<p>
</a>
<a name="544351">
In addition to the time history data, any sort of associated data may be defined via the attribute mechanism in </a>PDBLib. Additionally attributes may be assigned to particular instances of time history data structures via the </a>PA_th_wr_iattr call.<p>
</a>
<a name="542834">
Since PANACEA is a part of PACT, it supplies functions to transpose the time history data files into </a>ULTRA files (also a PACT tool). These functions are: </a>PA_th_trans_name; </a>PA_th_trans_link; and </a>PA_th_trans_family. In this way, applications may directly transpose their time history files if desired. The stand alone program </a>TOUL which transposes a family of time history files into a family of </a>ULTRA files simply calls these functions appropriately. NOTE: all files in the family must be closed before any transpose operation. Functions to merge an arbitrary list of ULTRA files or a family of ULTRA files are also provided. These functions are: </a>PA_merge_files and </a>PA_merge_family.<p>
</a>
<a name="542835">
This facility is substantially independent of the rest of PANACEA and can be used without any other parts of PANACEA.<p>
</a>
<a name="542836">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="542838">PA_th_open, </a>PA_th_def_rec, PA_th_write, PA_th_family
<P><A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="542841"></a>PA_merge_family, </a>PA_merge_files, </a>PA_th_trans_name, </a>PA_th_trans_link,
</a>PA_th_trans_family, </a>PA_th_wr_iattr
<P><a name="542842">
<p>
</a>
</ul><a name="544884">
<h3>4.10.1 PA_MERGE_FAMILY</h3>
</a>
<A NAME="544885"><PRE>
</PRE><A NAME="544886"><PRE> int </a>PA_merge_family(char *base,
</PRE><A NAME="544887"><PRE> char *family,
</PRE><A NAME="544888"><PRE> int nc)
</PRE><a name="544889">
Merge a family of ULTRA files into a single file or family of files. The ULTRA source files are specified here by family base name.<p>
</a>
<a name="544890">
ULTRA source files are assumed to follow the naming convention<p>
</a>
<A NAME="544891"><PRE> family.udd
</PRE><a name="544892">
where family is the base source file name supplied and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544893">
ULTRA target files produced by this function similarly follow the naming convention<p>
</a>
<A NAME="544894"><PRE> base.udd
</PRE><a name="544895">
where base is the base target file name supplied.<p>
</a>
<a name="544896">
Argument nc, determines how target files are familied by specifying the approximate number of curves per file. However, regardless of the value of nc, all curves from a given source file will reside in a single target file. If nc is zero, all curves will be merged into a single file.<p>
</a>
<a name="544897">
For efficiency this function currently assumes that all curves in a given source file share the domain of the first curve in that file. This is true for ULTRA files produced by the PANACEA time history transpose routines. Curves from arbitrary ULTRA files can be merged, albeit less efficiently, using the </a>save command in the </a>ULTRA utility.<p>
</a>
<a name="544898">
Input to this function is: base, an ASCII string containing the base target file name; family, an ASCII string containing the base source file name; and nc an integer approximate number of curves per ULTRA target file.<p>
</a>
<a name="544899">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="544900">
See also </a>PA_merge_files.<p>
</a>
<A NAME="544901"><PRE>
</PRE><A NAME="544902"><PRE> int </a>PA_merge_family(char *base,
</PRE><A NAME="544904"><PRE> char *family,
</PRE><A NAME="544905"><PRE> int nc)
</PRE><A NAME="544906"><B>
</B><HR><A NAME="544907"><PRE> #include “panace.h”
</PRE><A NAME="544908"><PRE>
</PRE><A NAME="544910"><PRE> .
</PRE><A NAME="544911"><PRE> .
</PRE><A NAME="544912"><PRE> .
</PRE><A NAME="544913"><PRE> /* merge files in family foo */
</PRE><A NAME="544918"><PRE> if (!</a>PA_merge_family(“bar”, “foo”, 0))
</PRE><A NAME="544919"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="544924"><PRE> .
</PRE><A NAME="544925"><PRE> .
</PRE><A NAME="544926"><PRE> .
</PRE><a name="544386">
<h3>4.10.2 PA_MERGE_FILES</h3>
</a>
<A NAME="544805"><PRE>
</PRE><A NAME="544814"><PRE> int </a>PA_merge_files(char *base,
</PRE><A NAME="544815"><PRE> int n,
</PRE><A NAME="544816"><PRE> char **names,
</PRE><A NAME="544817"><PRE> int nc)
</PRE><a name="544818">
</a>Merge a set of ULTRA files into a single file or family of files. The ULTRA source files are specified here explicitly by name.<p>
</a>
<a name="544819">
ULTRA target files produced by this function follow the naming convention<p>
</a>
<A NAME="544820"><PRE> base.udd
</PRE><a name="544821">
where base is the base target file name supplied and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544822">
Argument nc, determines how target files are familied by specifying the approximate number of curves per file. However, regardless of the value of nc, all curves from a given source file will reside in a single target file. If nc is zero, all curves will be merged into a single file.<p>
</a>
<a name="544823">
For efficiency this function currently assumes that all curves in a given source file share the domain of the first curve in that file. This is true for ULTRA files produced by the PANACEA time history transpose routines. Curves from arbitrary ULTRA files can be merged, albeit less efficiently, using the </a>save command in the </a>ULTRA utility.<p>
</a>
<a name="544824">
Input to this function is: base, an ASCII string containing the base file name; n, an integer number of file names supplied in names; names, an array of ASCII strings containing the full names of the ULTRA source files; and nc an integer approximate number of curves per ULTRA target file.<p>
</a>
<a name="544825">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="544826">
See also </a>PA_merge_family.<p>
</a>
<A NAME="544827"><PRE>
</PRE><A NAME="544828"><PRE> int </a>PA_merge_files(char *base,
</PRE><A NAME="544829"><PRE> int n,
</PRE><A NAME="544830"><PRE> char **names,
</PRE><A NAME="544831"><PRE> int nc)
</PRE><A NAME="544832"><B>
</B><HR><A NAME="544833"><PRE> #include “panace.h”
</PRE><A NAME="544834"><PRE>
</PRE><A NAME="544835"><PRE> char **names;
</PRE><A NAME="544836"><PRE> .
</PRE><A NAME="544837"><PRE> .
</PRE><A NAME="544838"><PRE> .
</PRE><A NAME="544870"><PRE> /* only merge foo.u09 through foo.u0b */
</PRE><A NAME="544871"><PRE> names = MAKE_N(char *, 3);
</PRE><A NAME="544872"><PRE> names[0] = SC_strsave(“foo.t09”);
</PRE><A NAME="544873"><PRE> names[1] = SC_strsave(“foo.t0a”);
</PRE><A NAME="544874"><PRE> names[2] = SC_strsave(“foo.t0b”);
</PRE><A NAME="544875"><PRE> if (!</a>PA_merge_files(“bar”, 3, names, 0))
</PRE><A NAME="544876"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="544877"><PRE> SFREE(names[0]);
</PRE><A NAME="544878"><PRE> SFREE(names[1]);
</PRE><A NAME="544879"><PRE> SFREE(names[2]);
</PRE><A NAME="544880"><PRE> SFREE(names);
</PRE><A NAME="544881"><PRE> .
</PRE><A NAME="544882"><PRE> .
</PRE><A NAME="544883"><PRE> .
</PRE><a name="542843">
<h3>4.10.3 PA_TH_DEF_REC</h3>
</a>
<A NAME="542844"><PRE>
</PRE><A NAME="542845"><PRE> defstr *</a>PA_th_def_rec(PDBfile *file,
</PRE><A NAME="542846"><PRE> char *name,
</PRE><A NAME="542847"><PRE> char *type,
</PRE><A NAME="542848"><PRE> int nmemb,
</PRE><A NAME="542849"><PRE> char **members,
</PRE><A NAME="542850"><PRE> char **labels)
</PRE><a name="542851">
Define a special type to be used for the purpose of gathering </a>time history data in such a fashion that a generic tool (e.g. TOUL) can be used to convert the data into arrays of time ordered data. This defines both a derived data type and an entry in the symbol table of the file to contain the data. PANACEA implicitly adds another entry which contains information that a transposer would use.<p>
</a>
<a name="544497">
The members must follow the rules for member specifications as described in the PDBLib User’s Manual with the exception that if no type is specified the type is taken to be “double”. Briefly, a member specification consists of a type, an identifier, and optional dimension specifications. Member identifiers must not contain white space characters or any of the following: ‘*’, ‘[‘, ‘]’, ‘(‘, ‘)’, or ‘.’. The first member is taken to be the domain data (x value) and the remaining members are taken to be ranges. Each data set of the specified type transposes into nmemb-1 curves, that is one x array and nmemb-1 y arrays.<p>
</a>
<a name="543176">
NOTE: A non-scalar member does not transpose into a set of curves. In such a case PDBView is used directly to manipulate the time history data since it has superior capabilities for allowing users to control the semantics of their data.<p>
</a>
<a name="542853">
Since a very common use for this capability is to generate curves for plotting purposes, the labels argument is provided for the application to supply curve labels. The labels argument may be NULL if the application wishes PANACEA to construct labels from the member.<p>
</a>
<a name="542854">
Input to </a>PA_th_def_rec is: file, a pointer to a PDBfile; name, an ASCII string containing the name of the data entry in the symbol table; type, an ASCII string containing the name of the new struct; nmemb, an integer specifying the number of members of the new type; members, an array of nmemb ASCII strings specifying the struct members; and labels, an array of nmemb-1 ASCII strings specifying labels for curves generated by the transposer.<p>
</a>
<a name="542855">
A pointer to the type’s defstr is returned if the call is successful; otherwise, NULL is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="542856">
See also </a>PA_th_wr_iattr, </a>PA_th_write, and </a>PA_th_trans_family.<p>
</a>
<A NAME="542857"><PRE>
</PRE><A NAME="542858"><PRE> defstr *</a>PA_th_def_rec(PDBfile *file,
</PRE><A NAME="542859"><PRE> char *name,
</PRE><A NAME="542860"><PRE> char *type,
</PRE><A NAME="542861"><PRE> int nmemb,
</PRE><A NAME="542862"><PRE> char **members,
</PRE><A NAME="542863"><PRE> char **labels)
</PRE><A NAME="542864"><B>
</B><HR><A NAME="542865"><PRE> #include “panace.h”
</PRE><A NAME="542866"><PRE>
</PRE><A NAME="542867"><PRE> PDBfile *file;
</PRE><A NAME="542868"><PRE> defstr *ptr;
</PRE><A NAME="542869"><PRE> char **members;
</PRE><A NAME="542870"><PRE> .
</PRE><A NAME="542871"><PRE> .
</PRE><A NAME="542872"><PRE> .
</PRE><A NAME="542873"><PRE> members = MAKE_N(char *, 3);
</PRE><A NAME="542874"><PRE> members[0] = SC_strsave(“time”);
</PRE><A NAME="542875"><PRE> members[1] = SC_strsave(“d[20]”);
</PRE><A NAME="542876"><PRE> members[2] = SC_strsave(“p at x,y”);
</PRE><A NAME="542877"><PRE> ptr = </a>PA_th_def_rec(file, “t-data”, “t-struct”, 3, members, NULL);
</PRE><A NAME="542878"><PRE>
</PRE><A NAME="542879"><PRE> SFREE(members[0]);
</PRE><A NAME="542880"><PRE> SFREE(members[1]);
</PRE><A NAME="542881"><PRE> SFREE(members[2]);
</PRE><A NAME="542882"><PRE> SFREE(members);
</PRE><A NAME="542883"><PRE> .
</PRE><A NAME="542884"><PRE> .
</PRE><A NAME="542885"><PRE> .
</PRE><a name="541731">
<h3>4.10.4 PA_TH_FAMILY</h3>
</a>
<A NAME="544207"><PRE>
</PRE><A NAME="544223"><PRE> PDBfile *</a>PA_th_family(PDBfile *file)
</PRE><A NAME="544213"><PRE>
</PRE><a name="544217">
Check the current file’s size against the maximum size as specified in the </a>PA_th_open call. If the file is larger than the maximum size, close the file, open the next member of the file family, and return a pointer to the new file.<p>
</a>
<a name="544208">
Input to this function is: file, a pointer to a PDBfile.<p>
</a>
<a name="544218">
A pointer to a PDBfile is returned if the call is successful; otherwise, NULL is returned. The PDBfile pointer that is returned should be checked against the one passed in to tell whether a new file has been opened.<p>
</a>
<a name="544219">
See also </a>PA_th_def_rec, </a>PA_th_write, and </a>PA_th_open.<p>
</a>
<A NAME="544220"><PRE>
</PRE><A NAME="544221"><PRE> PDBfile *</a>PA_th_family(PDBfile *file)
</PRE><A NAME="544227"><B>
</B><HR><A NAME="544228"><PRE> #include “panace.h”
</PRE><A NAME="544229"><PRE>
</PRE><A NAME="544230"><PRE> PDBfile *oldfile, *newfile;
</PRE><A NAME="544233"><PRE> .
</PRE><A NAME="544234"><PRE> .
</PRE><A NAME="544235"><PRE> .
</PRE><A NAME="544240"><PRE> newfile = </a>PA_th_family(oldfile);
</PRE><A NAME="544245"><PRE> if (newfile != oldfile)
</PRE><A NAME="544222"><PRE> printf(“Next member of family opened\n”);
</PRE><A NAME="544246"><PRE> .
</PRE><A NAME="544247"><PRE> .
</PRE><A NAME="544248"><PRE> .
</PRE><a name="544209">
<h3>4.10.5 PA_TH_OPEN</h3>
</a>
<A NAME="544210"><PRE>
</PRE><A NAME="544212"><PRE> PDBfile *</a>PA_th_open(char *name,
</PRE><A NAME="544214"><PRE> char *mode,
</PRE><A NAME="544215"><PRE> long size,
</PRE><A NAME="544276"><PRE> char *prev)
</PRE><a name="544216">
Open a new time history data file. This implicitly defines a family of files. The name should be of the form: base.tdd where d is a base 36 digit (i.e. 0-9a-z). This is only a convention, but there are certain consequences for not following it in as much as the familying mechanism assumes that the last two characters form a base 36 number and increments it accordingly. As an application writes data to a time history file, periodic calls to </a>PA_th_family should be made to monitor the file size and when necessary close the current family member and open the next.<p>
</a>
<a name="544277">
Since simulations may be restarted and each code may have a different strategy for continuing time history collection in the event of a restart, it is necessary to allow for name changes in the family. The consequence of this is that each member of a file family must contain the name of the previous file in the family. In that way, the transpose process may unambiguously and under the control of the user or simulation follow a chain of time history files from the end point back to the beginning. The prev argument is used to supply this information. The family of files that follows will be in sequence from the name supplied. Only across restarts, which implies calls to PA_th_open, may the sequence name be changed. A call to PA_th_open may have NULL for prev which indicates the absolute beginning of the sequence, i.e. the transpose will stop in its search for files at this point.<p>
</a>
<a name="544224">
Input to this function is: name, an ASCII string specifying the name of the first file in the family for the current application; mode, an ASCII string specifying the mode of the file (typically this will be “w”); size, a long integer value specifying the target maximum file size for members of the family; and prev, an ASCII string specfiying the name of the previous file in the family sequence.<p>
</a>
<a name="544225">
A pointer to a PDBfile is returned if the call is successful; otherwise, NULL is returned. <p>
</a>
<a name="544226">
See also </a>PA_th_def_rec, </a>PA_th_write, and </a>PA_th_family.<p>
</a>
<A NAME="544231"><PRE>
</PRE><A NAME="544282"><PRE> PDBfile *</a>PA_th_open(char *name,
</PRE><A NAME="544283"><PRE> char *mode,
</PRE><A NAME="544284"><PRE> long size,
</PRE><A NAME="544296"><PRE> char *prev)
</PRE><A NAME="544238"><B>
</B><HR><A NAME="544239"><PRE> #include “panace.h”
</PRE><A NAME="544241"><PRE>
</PRE><A NAME="544242"><PRE> PDBfile *newfile;
</PRE><A NAME="544243"><PRE> .
</PRE><A NAME="544244"><PRE> .
</PRE><A NAME="544249"><PRE> .
</PRE><A NAME="544250"><PRE> newfile = </a>PA_th_open(“foo.t00”, “w”, 1000000L, NULL);
</PRE><A NAME="544251"><PRE> if (newfile == NULL)
</PRE><A NAME="544252"><PRE> printf(“Can’t open time history file\n”);
</PRE><A NAME="544253"><PRE> .
</PRE><A NAME="544254"><PRE> .
</PRE><A NAME="544255"><PRE> .
</PRE><a name="544982">
<h3>4.10.6 PA_TH_TRANS_FAMILY</h3>
</a>
<A NAME="544983"><PRE>
</PRE><A NAME="544984"><PRE> int </a>PA_th_trans_family(char *name,
</PRE><A NAME="544986"><PRE> int ord,
</PRE><A NAME="544985"><PRE> int nc)
</PRE><a name="544987">
Write an ULTRA file by </a>transposing the </a>time history data from a given set of time history files.<p>
</a>
<a name="544988">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544989"><PRE> name.tdd
</PRE><a name="544990">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544996">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="545004"><PRE> name.udd
</PRE><a name="545022">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="545005">
Input to this function is: name, an ASCII string containing the base name of the time history file family; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="545006">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="545007">
See also </a>PA_th_trans_link, </a>PA_th_trans_name, </a>PA_th_def_rec, and </a>PA_th_write.<p>
</a>
<A NAME="545008"><PRE>
</PRE><A NAME="545009"><PRE> int </a>PA_th_trans_family(char *name,
</PRE><A NAME="545023"><PRE> int ord,
</PRE><A NAME="545010"><PRE> int nc)
</PRE><A NAME="545011"><B>
</B><HR><A NAME="545012"><PRE> #include “panace.h”
</PRE><A NAME="545013"><PRE>
</PRE><A NAME="545014"><PRE> .
</PRE><A NAME="545015"><PRE> .
</PRE><A NAME="545016"><PRE> .
</PRE><A NAME="545017"><PRE> if (!</a>PA_th_trans_family(“foo”, 1, 1000))
</PRE><A NAME="545018"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="545019"><PRE> .
</PRE><A NAME="545020"><PRE> .
</PRE><A NAME="545021"><PRE> .
</PRE><a name="544394">
<h3>4.10.7 PA_TH_TRANS_LINK</h3>
</a>
<A NAME="544395"><PRE>
</PRE><A NAME="544396"><PRE> int </a>PA_th_trans_link(int n,
</PRE><A NAME="544397"><PRE> char **names,
</PRE><A NAME="544398"><PRE> int ord,
</PRE><A NAME="544399"><PRE> int nc)
</PRE><a name="544400">
</a>Write an ULTRA file by </a>transposing the </a>time history data from a specified set of time history files. The time history files are specified here by giving the names of files at the end of file family chains.<p>
</a>
<a name="544401">
On occasion, files in a family are lost. This breaks the chain of files as well as leaving gaps in the data. Since this function can take many file names, it can be used to take into account missing files by supplying the files at the top of the gap(s) of missing files. In the accompanying example it is assumed that the files foo.t09 through foo.t11 are missing.<p>
</a>
<a name="544402">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="544403">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544404"><PRE> name.tdd
</PRE><a name="544405">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544406">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544407"><PRE> name.udd
</PRE><a name="544408">
Input to this function is: n, an integer number of file names supplied in names; names, an array of ASCII strings containing the full names of the time history files; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544409">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="544410">
See also </a>PA_th_trans_name, </a>PA_trans_family, </a>PA_th_def_rec, and </a>PA_th_write.<p>
</a>
<A NAME="544411"><PRE>
</PRE><A NAME="544412"><PRE> int </a>PA_th_trans_link(int n,
</PRE><A NAME="544413"><PRE> char **names,
</PRE><A NAME="544414"><PRE> int ord,
</PRE><A NAME="544415"><PRE> int nc)
</PRE><A NAME="544416"><B>
</B><HR><A NAME="544417"><PRE> #include “panace.h”
</PRE><A NAME="544418"><PRE>
</PRE><A NAME="544419"><PRE> char **names;
</PRE><A NAME="544420"><PRE> .
</PRE><A NAME="544421"><PRE> .
</PRE><A NAME="544422"><PRE> .
</PRE><A NAME="544423"><PRE> /* files foo.t09 through foo.t11 are missing */
</PRE><A NAME="544424"><PRE> names = MAKE_N(char *, 2);
</PRE><A NAME="544425"><PRE> names[0] = SC_strsave(“foo.t1f”);
</PRE><A NAME="544426"><PRE> names[1] = SC_strsave(“foo.t08”);
</PRE><A NAME="544427"><PRE> if (!</a>PA_th_trans_link(2, names, -1, 1000))
</PRE><A NAME="544428"><PRE> err_proc();
</PRE><A NAME="544429"><PRE> SFREE(names[0]);
</PRE><A NAME="544430"><PRE> SFREE(names[1]);
</PRE><A NAME="544431"><PRE> SFREE(names);
</PRE><A NAME="544432"><PRE> .
</PRE><A NAME="544433"><PRE> .
</PRE><A NAME="544434"><PRE> .
</PRE><a name="543123">
<h3>4.10.8 PA_TH_TRANS_NAME</h3>
</a>
<A NAME="543124"><PRE>
</PRE><A NAME="544389"><PRE> int </a>PA_th_trans_name(int n,
</PRE><A NAME="544390"><PRE> char **names,
</PRE><A NAME="544391"><PRE> int ord,
</PRE><A NAME="544392"><PRE> int nc)
</PRE><a name="544357">
</a>Write an ULTRA file by </a>transposing the </a>time history data from a specified set of time history files. The time history files are specified here explicitly by name.<p>
</a>
<a name="543125">
On occasion, it is desirable to transpose only selected files from a family. For example, a user may know that only certain times are of interest and doesn’t wish to see the entire data set. This function gives the finest level of control to the application about which files to transpose.<p>
</a>
<a name="544393">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="544358">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544359"><PRE> name.tdd
</PRE><a name="544360">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544361">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544362"><PRE> name.udd
</PRE><a name="544363">
Input to this function is: n, an integer number of file names supplied in names; names, an array of ASCII strings containing the full names of the time history files; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544364">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="544365">
See also </a>PA_th_trans_link, </a>PA_trans_family, </a>PA_th_def_rec, and </a>PA_th_write.<p>
</a>
<A NAME="544366"><PRE>
</PRE><A NAME="544435"><PRE> int </a>PA_th_trans_name(int n,
</PRE><A NAME="544436"><PRE> char **names,
</PRE><A NAME="544437"><PRE> int ord,
</PRE><A NAME="544438"><PRE> int nc)
</PRE><A NAME="544369"><B>
</B><HR><A NAME="544370"><PRE> #include “panace.h”
</PRE><A NAME="544371"><PRE>
</PRE><A NAME="544372"><PRE> char **names;
</PRE><A NAME="544380"><PRE> .
</PRE><A NAME="544373"><PRE> .
</PRE><A NAME="544356"><PRE> .
</PRE><A NAME="544374"><PRE> /* only transpose foo.t09 through foo.t0b */
</PRE><A NAME="544375"><PRE> names = MAKE_N(char *, 3);
</PRE><A NAME="544388"><PRE> names[0] = SC_strsave(“foo.t09”);
</PRE><A NAME="544384"><PRE> names[1] = SC_strsave(“foo.t0a”);
</PRE><A NAME="544367"><PRE> names[2] = SC_strsave(“foo.t0b”);
</PRE><A NAME="544383"><PRE> if (!</a>PA_th_trans_name(3, names, 1, 1000))
</PRE><A NAME="544376"><PRE> err_proc();
</PRE><A NAME="544385"><PRE> SFREE(names[0]);
</PRE><A NAME="544368"><PRE> SFREE(names[1]);
</PRE><A NAME="544381"><PRE> SFREE(names[2]);
</PRE><A NAME="544377"><PRE> SFREE(names);
</PRE><A NAME="544387"><PRE> .
</PRE><A NAME="544378"><PRE> .
</PRE><A NAME="544379"><PRE> .
</PRE><a name="542957">
<h3>4.10.9 PA_TH_TRANSPOSE</h3>
</a>
<A NAME="542958"><PRE>
</PRE><A NAME="542959"><PRE> int </a>PA_th_transpose(char *name,
</PRE><A NAME="542960"><PRE> int nc)
</PRE><a name="544981">
</a>WARNING: This is a deprecated function. Use </a>PA_th_trans_family instead.<p>
</a>
<a name="542961">
Write an ULTRA file by </a>transposing the </a>time history data from a given set of time history files.<p>
</a>
<a name="542962">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="542963"><PRE> name.tdd
</PRE><a name="542964">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="542965">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="542966"><PRE> name.udd
</PRE><a name="542967">
Input to this function is: name, an ASCII string containing the base name of the time history file family; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="542968">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="542969">
See also </a>PA_th_trans_link, </a>PA_th_trans_name, </a>PA_th_def_rec, and </a>PA_th_write.<p>
</a>
<A NAME="542970"><PRE>
</PRE><A NAME="542971"><PRE> int </a>PA_th_transpose(char *name,
</PRE><A NAME="542972"><PRE> int nc)
</PRE><A NAME="542973"><B>
</B><HR><A NAME="542974"><PRE> #include “panace.h”
</PRE><A NAME="542975"><PRE>
</PRE><A NAME="542976"><PRE> .
</PRE><A NAME="542977"><PRE> .
</PRE><A NAME="542978"><PRE> .
</PRE><A NAME="542979"><PRE> if (!</a>PA_th_transpose(“foo”, 1000))
</PRE><A NAME="542980"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="542981"><PRE> .
</PRE><A NAME="542982"><PRE> .
</PRE><A NAME="542983"><PRE> .
</PRE><a name="542886">
<h3>4.10.10 PA_TH_WR_IATTR</h3>
</a>
<A NAME="542887"><PRE>
</PRE><A NAME="542888"><PRE> int </a>PA_th_wr_iattr(PDBfile *file,
</PRE><A NAME="542889"><PRE> char *var,
</PRE><A NAME="542890"><PRE> int inst,
</PRE><A NAME="542891"><PRE> char *attr,
</PRE><A NAME="542892"><PRE> void *avl)
</PRE><a name="542893">
Assign an </a>attribute value to an instance of a </a>time history data record.<p>
</a>
<a name="542894">
Input to this function is: file, a pointer to a PDBfile; var, an ASCII string containing the name of the data entry in the symbol table; inst, an integer instance index; attr, an ASCII string containing the name of the attribute; and avl, a pointer to the attribute value.<p>
</a>
<a name="542895">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="542896">
See also </a>PA_th_def_rec, </a>PA_th_write, and </a>PA_th_trans_family.<p>
</a>
<A NAME="542897"><PRE>
</PRE><A NAME="542898"><PRE>
</PRE><A NAME="542899"><PRE> int </a>PA_th_wr_iattr(PDBfile *file,
</PRE><A NAME="542900"><PRE> char *var,
</PRE><A NAME="542901"><PRE> int inst,
</PRE><A NAME="542902"><PRE> char *attr,
</PRE><A NAME="542903"><PRE> void *avl)
</PRE><A NAME="542904"><B>
</B><HR><A NAME="542905"><PRE> #include “panace.h”
</PRE><A NAME="542906"><PRE>
</PRE><A NAME="542907"><PRE> PDBfile *file;
</PRE><A NAME="542908"><PRE> double *vr
</PRE><A NAME="542909"><PRE> .
</PRE><A NAME="542910"><PRE> .
</PRE><A NAME="542911"><PRE> .
</PRE><A NAME="542912"><PRE> vr = MAKE_N(double, 9);
</PRE><A NAME="542913"><PRE> .
</PRE><A NAME="542914"><PRE> .
</PRE><A NAME="542915"><PRE> .
</PRE><A NAME="542916"><PRE> if (!</a>PA_th_wr_iattr(file, “t-data”, 3, “date”, “today”))
</PRE><A NAME="542917"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="542918"><PRE> .
</PRE><A NAME="542919"><PRE> .
</PRE><A NAME="542920"><PRE> .
</PRE><a name="542921">
<h3>4.10.11 PA_TH_WRITE</h3>
</a>
<A NAME="542922"><PRE>
</PRE><A NAME="542923"><PRE> int </a>PA_th_write(PDBfile *file,
</PRE><A NAME="542924"><PRE> char *name,
</PRE><A NAME="542925"><PRE> char *type,
</PRE><A NAME="544211"><PRE> int inst,
</PRE><A NAME="542926"><PRE> int nr,
</PRE><A NAME="542927"><PRE> void *vr)
</PRE><a name="542928">
</a>Write out nr instances of </a>time history data whose structure has been defined by </a>PA_th_def_rec. This function writes out nr complete instances of a time history record! Using this function an application can manage multiple sets of time history data which are written at different frequencies.<p>
</a>
<a name="542929">
The name and type arguments should match those used in defining the structure with </a>PA_th_def_rec.<p>
</a>
<a name="542930">
Input to this function is: file, a pointer to a PDBfile; name, an ASCII string containing the name of the data entry in the symbol table; type, an ASCII string containing the name of the time history domain struct; inst, an integer specifying the instance index of the first record in this call; nr, an integer specifying the number of instances of the structure pointed to by vr; and vr, a pointer to the data.<p>
</a>
<a name="542931">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="542932">
See also </a>PA_th_wr_iattr, </a>PA_th_def_rec, and </a>PA_th_trans_family.<p>
</a>
<A NAME="542933"><PRE>
</PRE><A NAME="542934"><PRE> int </a>PA_th_write(PDBfile *file,
</PRE><A NAME="542935"><PRE> char *name,
</PRE><A NAME="542936"><PRE> char *type,
</PRE><A NAME="544257"><PRE> int inst,
</PRE><A NAME="542937"><PRE> int nr,
</PRE><A NAME="542938"><PRE> void *vr)
</PRE><A NAME="542939"><B>
</B><HR><A NAME="542940"><PRE> #include “panace.h”
</PRE><A NAME="542941"><PRE>
</PRE><A NAME="542942"><PRE> PDBfile *file;
</PRE><A NAME="542943"><PRE> double *vr
</PRE><A NAME="542944"><PRE> .
</PRE><A NAME="542945"><PRE> .
</PRE><A NAME="542946"><PRE> .
</PRE><A NAME="542947"><PRE> vr = MAKE_N(double, 9);
</PRE><A NAME="542948"><PRE> .
</PRE><A NAME="542949"><PRE> .
</PRE><A NAME="542950"><PRE> .
</PRE><A NAME="542951"><PRE> if (!</a>PA_th_write(file, “t-data”, “t-struct”, 0, 3, vr))
</PRE><A NAME="542952"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="544258"><PRE> .
</PRE><A NAME="544259"><PRE> .
</PRE><A NAME="544260"><PRE> .
</PRE><A NAME="544261"><PRE> if (!</a>PA_th_write(file, “t-data”, “t-struct”, 3, 2, vr))
</PRE><A NAME="544262"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="542953"><PRE> .
</PRE><A NAME="542954"><PRE> .
</PRE><A NAME="542955"><PRE> .
</PRE><A NAME="544266"><PRE> if (!</a>PA_th_write(file, “t-data”, “t-struct”, 5, 3, vr))
</PRE><A NAME="544267"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="542956"><PRE> .
</PRE><A NAME="544263"><PRE> .
</PRE><A NAME="544264"><PRE> .
</PRE><a name="544703">
<h3>4.10.12 PA_TH_WR_MEMBER</h3>
</a>
<A NAME="544704"><PRE>
</PRE><A NAME="544721"><PRE> int </a>PA_th_wr_member(PDBfile *file,
</PRE><A NAME="544740"><PRE> char *name,
</PRE><A NAME="544741"><PRE> char *member,
</PRE><A NAME="544742"><PRE> char *type,
</PRE><A NAME="544743"><PRE> int inst,
</PRE><A NAME="544744"><PRE> void *vr)
</PRE><A NAME="544710"><PRE>
</PRE><a name="544705">
</a>Write out one member of a </a>time history data record whose structure has been defined by </a>PA_th_def_rec. This function writes out one member of a time history record. Its utility is most apparent when the member is an array which could be large or is part of a very large record.<p>
</a>
<a name="544713">
Input to this function is: file, a pointer to a PDBfile; name, an ASCII string containing the name of the data entry in the symbol table; member, an ASCII string containing the name of the time history record member; type, an ASCII string containing the name of the time history domain struct; inst, an integer specifying the instance index of the first record in this call; and vr, a pointer to the data.<p>
</a>
<a name="544714">
TRUE is returned if the call is successful; otherwise, FALSE is returned and the ASCII string PD_err contains any error message that was generated.<p>
</a>
<a name="544715">
See also </a>PA_th_wr_iattr, </a>PA_th_def_rec, and </a>PA_th_trans_family.<p>
</a>
<A NAME="544716"><PRE>
</PRE><A NAME="544717"><PRE> int </a>PA_th_wr_member(PDBfile *file,
</PRE><A NAME="544718"><PRE> char *name,
</PRE><A NAME="544750"><PRE> char *member,
</PRE><A NAME="544719"><PRE> char *type,
</PRE><A NAME="544720"><PRE> int inst,
</PRE><A NAME="544722"><PRE> void *vr)
</PRE><A NAME="544723"><B>
</B><HR><A NAME="544724"><PRE> #include “panace.h”
</PRE><A NAME="544725"><PRE>
</PRE><A NAME="544726"><PRE> PDBfile *file;
</PRE><A NAME="544727"><PRE> double *vr
</PRE><A NAME="544728"><PRE> .
</PRE><A NAME="544729"><PRE> .
</PRE><A NAME="544730"><PRE> .
</PRE><A NAME="544731"><PRE> vr = MAKE_N(double, 10000);
</PRE><A NAME="544732"><PRE> .
</PRE><A NAME="544733"><PRE> .
</PRE><A NAME="544734"><PRE> .
</PRE><A NAME="544735"><PRE> if (!PA_th_wr_member(file, “t-data”, “v_1”, “t-struct”, 1, vr))
</PRE><A NAME="544736"><PRE> printf(stderr, “%s\n”, PD_err);
</PRE><A NAME="544737"><PRE> .
</PRE><A NAME="544738"><PRE> .
</PRE><A NAME="544739"><PRE> .
</PRE><a name="542984">
<h2>4.11 Miscellaneous</h2>
</a>
<a name="542985">
<p>
</a>
<a name="542986">
<h3>4.11.1 Parsing Support</h3>
</a>
<a name="542987">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542990">
<li></a>PA_get_field(char *s, char *t, int optp)
</a>
<a name="542991">
<li></a>PA_stof(char *s)
</a>
<a name="542992">
<li></a>PA_stoi(char *s)
</a>
<a name="542993">
<p>
</a>
</ul><a name="542994">
<h3>4.11.2 Array Operations</h3>
</a>
<a name="542995">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="542998">
<li></a>PA_scale_array(double *p, int n, double f)
</a>
<a name="542999">
<li></a>PA_set_value(double *p, int n, double f)
</a>
<a name="543000">
<li></a>PA_copy_array(double *s, double *t, int n)
</a>
<a name="543001">
<li></a>PA_index_min(double *p, int n)
</a>
<a name="543002">
<li></a>PA_find_index(double *p, double f, int n)
</a>
<a name="543003">
<li></a>PA_max_value(double *p, int imin, int n)
</a>
<a name="543004">
<p>
</a>
</ul><a name="543005">
<h3>4.11.3 Error Handling</h3>
</a>
<a name="543006">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="543009">
<li></a>PA_ERR(int test, char *fmt, ...)
</a>
<a name="543010">
<p>
</a>
</ul><a name="543011">
<h3>4.11.4 Timing Routines</h3>
</a>
<a name="543012">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="543015">
<li></a>PA_MARK_TIME
</a>
<a name="543016">
Mark the current cpu time.<p>
</a>
<a name="543017">
<li></a>PA_ACCM_TIME(double x)
</a>
<a name="543018">
Accumulate the time since the previous MARK_TIME.<p>
</a>
<a name="543019">
<p>
</a>
</ul><a name="543020">
<h3>4.11.5 Comparison Routines</h3>
</a>
<a name="543021">
<p>
</a>
<A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><ul><a name="543024">
<li></a>PA_SAME(double x1, double y1, double x2, double y2)
</a>
<a name="543025">
Return TRUE if the points are within TOLERANCE distance of each other.<p>
</a>
<a name="543026">
<li></a>PA_CLOSETO(double x1, double x2)
</a>
<a name="543027">
Return TRUE if the numbers are within TOLERANCE of each other.<p>
</a>
<a name="543028">
<p>
</a>
</ul><a name="543029">
<h1>5.0 The PANACEA FORTRAN API</h1>
</a>
<a name="543030">
The FORTRAN interface to PANACEA has some global conventions. First, the function names adhere strictly to the FORTRAN77 naming convention of six characters. The names all begin with “PA” to identify them with PANACEA.<p>
</a>
<a name="543031">
Most functions return the value 1 if they complete without error and 0 otherwise.<p>
</a>
<a name="543032">
As in the C interface, the descriptions of the functions are sorted into service categories as follows:<p>
</a>
<A NAME="AUTOTAG;"><B>Database Definition and Control
</B><A NAME="AUTOTAG;"><B>Variable Definition
</B><A NAME="AUTOTAG;"><B>Control Definition
</B><A NAME="AUTOTAG;"><B>Unit Definition and Control
</B><A NAME="AUTOTAG;"><B>Database Access
</B><A NAME="AUTOTAG;"><B>Simulation Control
</B><A NAME="AUTOTAG;"><B>Plot Request Handling
</B><A NAME="AUTOTAG;"><B>Initial Value Problem Generation Support
</B><A NAME="AUTOTAG;"><B>Source Variable/Initial Value Data Handling
</B><A NAME="AUTOTAG;"><B>Time History Data Management
</B><A NAME="AUTOTAG;"><B>Miscellaneous
</B><a name="543044">
Within service category commands are segregated into two groups: Basic, PANACEA applications must invoke these functions at some appropriate point; and optional, these are provided for the benefit of the application but are not required.<p>
</a>
<a name="543045">
<p>
</a>
<a name="543046">
<h2>5.1 Database Definition and Control Functionality</h2>
</a>
<a name="543047">
These functions provide for overall control of the PANACEA database and packages.<p>
</a>
<a name="543048">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="543050"></a>PASPCK
<P><A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="AUTOTAG;"><B>
</B><a name="545030">
<h3>5.1.1 </a>PAGNSP</h3>
</a>
<A NAME="545031"><PRE>
</PRE><A NAME="545032"><PRE> PAGNSP(integer flag)
</PRE><a name="545033">
Returns the value of the name space flag in the argument flag. See the </a>PASNSP function for further information.<p>
</a>
<a name="545034">
<h3>5.1.2 </a>PASNSP</h3>
</a>
<A NAME="545035"><PRE>
</PRE><A NAME="545036"><PRE> PASNSP(integer flag)
</PRE><a name="545037">
If flag is TRUE then the </a>name space of PANACEA variables is maximized in that variables are defined to the database under a name made up from the package name, a hyphen, and the variable name. In this scheme, there is less potential for name conflicts. If flag is FALSE then variable are defined to the database simply by the variable name.<p>
</a>
<a name="543054">
<h3>5.1.3 </a>PASPCK</h3>
</a>
<A NAME="543055"><PRE>
</PRE><A NAME="543056"><PRE> PASPCK(pnc, pname)
</PRE><a name="543057">
This function sets the current package to be the named one. PANACEA uses the concept of current package to set a context for operations such as variable access and control use. That is to say that such operations are only meaningful when a particular package is in effect to provide information and procedures necessary to their function.<p>
</a>
<a name="543058">
Input to this function is: pnc, the number of characters in the package name; and pname the name of the package.<p>
</a>
<a name="543059">
This function returns 1 if successful and 0 otherwise.<p>
</a>
<a name="543060">
<h2>5.2 Variable Definers</h2>
</a>
<a name="543061">
<h2>5.3 Control Accessors/Definers</h2>
</a>
<a name="543062">
<h2>5.4 Unit Conversion/Definition Functionality</h2>
</a>
<a name="543063">
<h2>5.5 Database Access Functionality</h2>
</a>
<a name="543064">
This group of functions gives application packages access to the database variables or to non-database managed memory.<p>
</a>
<a name="543065">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="543067"></a>PACONN
<P><A NAME="543068"></a>PADCON
<P><A NAME="543069"></a>PALOCA
<P><A NAME="543070"></a>PAMCON
<P><A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="543073"></a>PALLOC
<P><a name="543074">
<p>
</a>
<a name="543075">
<h3>5.5.1 </a>PACONN</h3>
</a>
<A NAME="543076"><PRE>
</PRE><A NAME="543077"><PRE> PACONN(pv, pnc, vname, pf)
</PRE><a name="543078">
Connect the given pointer to the data associated with the named variable. PANACEA will record the address of the pointer pv if the flag, pf, is 1. In that case, if another operation causes PANACEA to change the size of or move the block of memory associated with the database variable, PANACEA will update the pointer pv to point to the new space. <p>
</a>
<a name="543079">
Sometimes a connection is made to a local pointer which is on the stack or otherwise temporary. In such a case it could be disastrous for PANACEA to change the contents of memory there. The flag lets the application programmer control this behavior.<p>
</a>
<a name="543080">
The arguments to this function are: pv, the pointer to be connected to the database variable vname; pnc, the number of characters in vname; vname, the name of the variable in the database; and pf, a flag specifying whether or not PANACEA is to record the address of pv so that it can be updated if the space to which it points is moved.<p>
</a>
<a name="543081">
This function returns 1 if successful and 0 otherwise.<p>
</a>
<a name="543082">
<h3>5.5.2 </a>PADCON</h3>
</a>
<A NAME="543083"><PRE>
</PRE><A NAME="543084"><PRE> PADCON(pv, pnc, vname)
</PRE><a name="543085">
Disconnect the pointer, pv, from the database variable named by name. The pointer is set to NULL (0x0) and future references to it will induce a crash or some other possibly undesirable behavior. PANACEA simply guarantees that the pointer will no longer be pointing to the memory block associated with the database variable.<p>
</a>
<a name="543086">
In the case of DMND variables, when the number of pointers connected to the database variable storage falls to zero the variable is written back out to disk. It can be connected to at a later time with </a>PACONN.<p>
</a>
<a name="543087">
The arguments to this function are: pv, the pointer to be disconnected from the database variable vname; pnc, the number of characters in vname; and vname, the name of the variable in the database.<p>
</a>
<a name="543088">
This function returns 1 if successful and 0 otherwise.<p>
</a>
<a name="543089">
<h3>5.5.3 </a>PALLOC</h3>
</a>
<A NAME="543090"><PRE>
</PRE><A NAME="543091"><PRE> PALLOC(pv, pnc, vname, pf, dim1, ...)
</PRE><a name="543092">
Define the dimensions for the named variable, allocate it, and set pv to point to the new space. Each dimension is ignored unless the corresponding dimension was NULL when the variable was defined.<p>
</a>
<a name="543093">
In certain applications even the application variable which will hold the value of some dimensions is unknown at the start of a simulation run. PANACEA allows for this maximal delay by permitting the application variable which holds the dimension value to be supplied with the request to allocate space. In this call the dimensions which were specified when the variable was defined are ignored.<p>
</a>
<a name="543094">
The arguments to this function are: pv, the pointer to be allocated and associated with the database variable vname; pnc, the number of characters in vname; vname, the name of the variable in the database; pf, a flag specifying whether or not PANACEA is to record the address of pv so that it can be updated if the space to which it points is moved; and dimi are the dimensions of the variable. They must match in number the dimension specifications used in the definition of the variable.<p>
</a>
<a name="543095">
This function returns 1 if successful and 0 otherwise.<p>
</a>
<a name="543096">
<p>
</a>
<a name="543097">
<h3>5.5.4 </a>PALOCA</h3>
</a>
<A NAME="543098"><PRE>
</PRE><A NAME="543099"><PRE> PALOCA(pv, pbpi, pn, dim1, ...)
</PRE><a name="543100">
Allocate some local space and set the pv to point to the new space.<p>
</a>
<a name="543101">
The arguments to this function are: pv, the pointer to be connected to the allocated space; pbpi, the number of bytes required for a single element of the variable; pn, the number of dimension for the variable; and dimi, the dimensions for the variable.<p>
</a>
<a name="543102">
This function returns 1 if successful and 0 otherwise.<p>
</a>
<a name="543103">
<h3>5.5.5 </a>PAMCON</h3>
</a>
<A NAME="543104"><PRE>
</PRE><A NAME="543105"><PRE> PAMCON(pnc, vn, pp, pn)
</PRE><a name="543106">
Connect the pointers in pp to the variables named by the entries in vn. There must be pn pointers in pp and pn strings in vn.<p>
</a>
<a name="543107">
The purpose of this routine is to connect a number of pointers to their corresponding database variables in a single operation. It is assumed that PANACEA will track all of these variables and update the pointers if the memory associated them is reallocated. This is equivalent to having the flag in </a>PACONN set to 1.<p>
</a>
<a name="543108">
The arguments to this function are: pnc, an array containing the length of the variable names in vn; vn, an array of names of the variables in the database; pp, an array of pointers to be connected to the database variables named in vn; and pn, the number of variables to be connected. Each of the arrays pnc, vn, and pp must be pn long.<p>
</a>
<a name="543109">
This function returns 1 if successful and 0 otherwise.<p>
</a>
<a name="543110">
<h2>5.6 Simulation Control</h2>
</a>
<a name="543111">
<h2>5.7 Plot Request Handling</h2>
</a>
<a name="543112">
<h2>5.8 Generation Support</h2>
</a>
<a name="543113">
<h2>5.9 Source Variable/Initial Value Data Handling</h2>
</a>
<a name="543114">
<h2>5.10 Time History Data Management</h2>
</a>
<a name="543115">
The following functions define a service for the management of time history data.<p>
</a>
<a name="543116">
This facility implements a time history data management model designed with the following goals:<p>
</a>
<ul><a name="543117">
<li>Easy to use
</a>
<a name="543118">
<li>Flexible enough to accommodate virtually any code system requirements
</a>
<a name="543119">
<li>Support families of files
</a>
<a name="543120">
<li>Support restart from any cycle in a simulation (the instance index is the key to this)
</a>
<a name="543121">
<li>The raw time history data should also be comprehensible.
</a>
<a name="543122">
The model chosen centers on the definition of a time history data structure which is defined at run time. Each such structure has a single domain component and multiple range components. These correspond to a set of time plots for which data is written at a particular frequency as determined by the application. By defining however many such structures are required, code systems can manage many sets of time plots each at their own frequency. New sets can be added over the course of a simulation. These structures are set up via the </a>PAAREC, </a>PABREC, and </a>PAEREC calls. Once defined, the application can buffer up any amount of time history data and then write it out with </a>PAWREC. Thus applications determine how much data will be kept in the running code.<p>
</a>
<a name="544352">
The time history data is written out in families </a>PDB of files. A family of time history PDB files is started with a call to </a>PATHOP. The function </a>PATHFM is used to close out one member of the family and start the next if the current file’s size is above a user set threshold. Each file in a family maintains a link to the previous file in the family. This is very useful when applications restart a simulation from an earlier state and, potentially, follow a different branch of execution. Knowing the last time history file in any branch allows the unambiguous reconstruction of the time history data for that branch.<p>
</a>
<a name="544353">
In addition to the time history data, any sort of associated data may be defined via the attribute mechanism in </a>PDBLib. Additionally attributes may be assigned to particular instances of time history data structures via the </a>PAWRIA call.<p>
</a>
<a name="544977">
Since PANACEA is a part of PACT, it supplies functions to transpose the time history data files into </a>ULTRA files (also a PACT tool). These functions are: </a>PATRNN; </a>PATRNL; and </a>PATRNF. In this way, applications may directly transpose their time history files if desired. The stand alone program </a>TOUL which transposes a family of time history files into a family of </a>ULTRA files simply calls these functions appropriately. NOTE: all files in the family must be closed before any transpose operation. Functions to merge an arbitrary list of ULTRA files or a family of ULTRA files are also provided. These functions are: </a>PAMRGN and </a>PAMRGF.<p>
</a>
<a name="544354">
<p>
</a>
<a name="544355">
This facility is substantially independent of the rest of PANACEA and can be used without any other parts of PANACEA.<p>
</a>
<a name="543126">
<p>
</a>
<A NAME="AUTOTAG;"><B>Basic Functions
</B><A NAME="543128"></a>PAAREC, </a>PABREC, </a>PAEREC, </a>PAWREC
<P><A NAME="AUTOTAG;"><B>
</B><A NAME="AUTOTAG;"><B>Optional Functions
</B><A NAME="543131">PAMRGF, PAMRGN, </a>PATRNN, </a>PATRNL, </a>PATRNF, </a>PAWRIA
<P></ul><a name="543132">
<h3>5.10.1 PAAREC</h3>
</a>
<A NAME="543133"><PRE>
</PRE><A NAME="543134"><PRE> integer </a>PAAREC(integer fileid,
</PRE><A NAME="543135"><PRE> integer recid,
</PRE><A NAME="543136"><PRE> integer nm,
</PRE><A NAME="543137"><PRE> char *memb,
</PRE><A NAME="543138"><PRE> integer nl,
</PRE><A NAME="543139"><PRE> char *labl)
</PRE><a name="543140">
Add a member to the definition of the </a>time history data structure specified.<p>
</a>
<a name="543141">
This function is a part of the process which defines a special derived type to be used for gathering time history data that a generic tool (e.g. TOUL) can convert into arrays of time ordered data.<p>
</a>
<a name="544546">
The member, memb. must follow the rules for member specifications as described in the PDBLib User’s Manual with the exception that if no type is specified the type is taken to be “double” (real*8). Briefly, a member specification consists of a type, an identifier, and optional dimension specifications. Member identifiers must not contain white space characters or any of the following: ‘*’, ‘[‘, ‘]’, ‘(‘, ‘)’, or ‘.’.<p>
</a>
<a name="543175">
NOTE: A non-scalar member does not transpose into a set of curves. In such a case PDBView is used directly to manipulate the time history data since it has superior capabilities for allowing users to control the semantics of their data.<p>
</a>
<a name="543143">
Since a very common use for this capability is to generate curves for plotting purposes, the labl argument is provided for the application to supply curve labels. The nl argument may be 0 if the application wishes PANACEA to construct labels from the member.<p>
</a>
<a name="543144">
Input to </a>PAAREC is: fileid, an integer identifying a PDB file; recid, an integer identifying a derived type definition started by </a>PABREC; nm, an integer number of characters in the member; memb, an ASCII string containing the name of the member; nl, an integer number of characters in the labl string; and labl, an ASCII string containing a curve label for this member versus the domain member.<p>
</a>
<a name="543145">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="543146">
See also </a>PABREC, </a>PAEREC, and </a>PAWREC.<p>
</a>
<A NAME="543147"><PRE>
</PRE><A NAME="543148"><PRE> integer </a>PAAREC(integer fileid,
</PRE><A NAME="543149"><PRE> integer recid,
</PRE><A NAME="543150"><PRE> integer nm,
</PRE><A NAME="543151"><PRE> char *memb,
</PRE><A NAME="543152"><PRE> integer nl,
</PRE><A NAME="543153"><PRE> char *labl)
</PRE><A NAME="543154"><B>
</B><HR><A NAME="543155"><PRE> integer paarec
</PRE><A NAME="543156"><PRE> integer fileid, recid
</PRE><A NAME="543157"><PRE> .
</PRE><A NAME="543158"><PRE> .
</PRE><A NAME="543159"><PRE> .
</PRE><A NAME="543160"><PRE> if (paarec(fileid, recid, 5, ‘d[20]’, 0, ‘ ‘) .eq. 0)
</PRE><A NAME="543161"><PRE> $ call errproc
</PRE><A NAME="543162"><PRE> .
</PRE><A NAME="543163"><PRE> .
</PRE><A NAME="543164"><PRE> .
</PRE><a name="543165">
<h3>5.10.2 PABREC</h3>
</a>
<A NAME="543166"><PRE>
</PRE><A NAME="543167"><PRE> integer PABREC(integer fileid,
</PRE><A NAME="543168"><PRE> integer nf,
</PRE><A NAME="543169"><PRE> char *name,
</PRE><A NAME="543170"><PRE> integer nt,
</PRE><A NAME="543171"><PRE> char *type,
</PRE><A NAME="543172"><PRE> integer nd,
</PRE><A NAME="543173"><PRE> char *domain)
</PRE><a name="543174">
Begin the definition of a special type to be used for gathering </a>time history data that a generic tool (e.g. </a>TOUL) can convert into arrays of time ordered data. This begins a process which defines both a derived data type and an entry in the symbol table of the file to contain the data. PANACEA implicitly adds another entry which contains information that a transposer would use.<p>
</a>
<a name="543142">
The name of the domain member is supplied here since each time history struct has only one domain variable (x data).<p>
</a>
<a name="544670">
The domain must follow the rules for member specifications as described in the PDBLib User’s Manual with the exception that if no type is specified the type is taken to be “double”. Briefly, a member specification consists of a type, an identifier, and optional dimension specifications. Member identifiers must not contain white space characters or any of the following: ‘*’, ‘[‘, ‘]’, ‘(‘, ‘)’, or ‘.’. The first member is taken to be the domain data (x value) and the remaining members are taken to be ranges. Each data set of the specified type transposes into nmemb-1 curves, that is one x array and nmemb-1 y arrays.<p>
</a>
<a name="542852">
Input to </a>PABREC is: fileid, an integer identifying a PDB file; nf, an integer number of characters in name; name, an ASCII string containing the name of the data entry in the symbol table; nt, an integer number of characters in the type string; type, an ASCII string containing the name of the new derived type; nd, an integer number of characters in the domain string; and domain, an ASCII string labelling the domain member.<p>
</a>
<a name="543177">
A non-zero integer identifier for this time history record structure is returned if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="543178">
See also </a>PAAREC, </a>PAEREC, and </a>PAWREC.<p>
</a>
<A NAME="543179"><PRE>
</PRE><A NAME="543180"><PRE> integer PABREC(integer fileid,
</PRE><A NAME="543181"><PRE> integer nf,
</PRE><A NAME="543182"><PRE> char *name,
</PRE><A NAME="543183"><PRE> integer nt,
</PRE><A NAME="543184"><PRE> char *type,
</PRE><A NAME="543185"><PRE> integer nd,
</PRE><A NAME="543186"><PRE> char *domain)
</PRE><A NAME="543187"><B>
</B><HR><A NAME="543188"><PRE> integer pabrec
</PRE><A NAME="543189"><PRE> integer fileid, recid
</PRE><A NAME="543190"><PRE> .
</PRE><A NAME="543191"><PRE> .
</PRE><A NAME="543192"><PRE> .
</PRE><A NAME="543193"><PRE> recid = pabrec(fileid, 6, ‘t-data’, 8, ‘t-struct’, 4, ‘time’)
</PRE><A NAME="543194"><PRE> .
</PRE><A NAME="543195"><PRE> .
</PRE><A NAME="543196"><PRE> .
</PRE><a name="543197">
<h3>5.10.3 PAEREC</h3>
</a>
<A NAME="543198"><PRE>
</PRE><A NAME="543199"><PRE> integer </a>PAEREC(integer fileid,
</PRE><A NAME="543200"><PRE> integer recid)
</PRE><a name="543201">
Complete the definition of a </a>time history data structure and enter the definition in the PDB file.<p>
</a>
<a name="543202">
Input to </a>PAEREC is: fileid, an integer identifying a PDB file; and recid, an integer identifying a derived type definition started by </a>PABREC.<p>
</a>
<a name="543203">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="543204">
See also </a>PAAREC, </a>PABREC, and </a>PAWREC.<p>
</a>
<A NAME="543205"><PRE>
</PRE><A NAME="543206"><PRE> integer </a>PAEREC(integer fileid,
</PRE><A NAME="543207"><PRE> integer recid)
</PRE><A NAME="543208"><B>
</B><HR><A NAME="543209"><PRE> integer paerec
</PRE><A NAME="543210"><PRE> integer fileid, recid
</PRE><A NAME="543211"><PRE> .
</PRE><A NAME="543212"><PRE> .
</PRE><A NAME="543213"><PRE> .
</PRE><A NAME="543214"><PRE> if (</a>paerec(fileid, recid) .eq. 0)
</PRE><A NAME="543215"><PRE> $ call errproc
</PRE><A NAME="543216"><PRE> .
</PRE><A NAME="543217"><PRE> .
</PRE><A NAME="543218"><PRE> .
</PRE><a name="544903">
<h3>5.10.4 PAMRGF</h3>
</a>
<A NAME="544909"><PRE>
</PRE><A NAME="544914"><PRE> integer </a>PAMRGF(integer nb,
</PRE><A NAME="544991"><PRE> char *base,
</PRE><A NAME="544992"><PRE> integer nf,
</PRE><A NAME="544915"><PRE> char *family,
</PRE><A NAME="544916"><PRE> integer nc)
</PRE><a name="544917">
Merge a family of ULTRA files into a single file or family of files. The ULTRA source files are specified here by family base name.<p>
</a>
<a name="544920">
ULTRA source files are assumed to follow the naming convention<p>
</a>
<A NAME="544921"><PRE> family.udd
</PRE><a name="544922">
where family is the base source file name supplied and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544923">
ULTRA target files produced by this function similarly follow the naming convention<p>
</a>
<A NAME="544927"><PRE> base.udd
</PRE><a name="544928">
where base is the base target file name supplied.<p>
</a>
<a name="544929">
Argument nc, determines how target files are familied by specifying the approximate number of curves per file. However, regardless of the value of nc, all curves from a given source file will reside in a single target file. If nc is zero, all curves will be merged into a single file.<p>
</a>
<a name="544930">
For efficiency this function currently assumes that all curves in a given source file share the domain of the first curve in that file. This is true for ULTRA files produced by the PANACEA time history transpose routines. Curves from arbitrary ULTRA files can be merged, albeit less efficiently, using the </a>save command in the </a>ULTRA utility.<p>
</a>
<a name="544931">
Input to this function is: nb, an integer number of characters in base; base, an ASCII string containing the base target file name; nf, an integer number of characters in famly; family, an ASCII string containing the base source file name; and nc an integer approximate number of curves per ULTRA target file.<p>
</a>
<a name="544932">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544933">
See also </a>PAMRGN.<p>
</a>
<A NAME="544934"><PRE>
</PRE><A NAME="544935"><PRE> integer </a>PAMRGF(integer nb,
</PRE><A NAME="544993"><PRE> char *base,
</PRE><A NAME="544994"><PRE> integer nf,
</PRE><A NAME="544936"><PRE> char *family,
</PRE><A NAME="544937"><PRE> integer nc)
</PRE><A NAME="544938"><B>
</B><HR><A NAME="544995"><PRE> integer pamrgf
</PRE><A NAME="544997"><PRE> .
</PRE><A NAME="544998"><PRE> .
</PRE><A NAME="544999"><PRE> .
</PRE><A NAME="545000"><PRE> if (</a>pamrgf(3, ‘bar’, 3, ‘foo’, 1000) .eq. 0)
</PRE><A NAME="545001"><PRE> $ call errproc
</PRE><A NAME="545002"><PRE> .
</PRE><A NAME="545003"><PRE> .
</PRE><A NAME="544939"><PRE> .
</PRE><a name="544940">
<h3>5.10.5 PAMRGN</h3>
</a>
<A NAME="544941"><PRE>
</PRE><A NAME="544942"><PRE> integer </a>PAMRGN(integer nb,
</PRE><A NAME="544943"><PRE> char *base,
</PRE><A NAME="544944"><PRE> integer nn,
</PRE><A NAME="544945"><PRE> char *names,
</PRE><A NAME="544946"><PRE> integer nc)
</PRE><a name="544956">
</a>Merge a set of ULTRA files into a single file or family of files. The ULTRA source files are specified here explicitly by name.<p>
</a>
<a name="544957">
ULTRA target files produced by this function follow the naming convention<p>
</a>
<A NAME="544958"><PRE> base.udd
</PRE><a name="544959">
where base is the base target file name supplied and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544960">
Argument nc, determines how target files are familied by specifying the approximate number of curves per file. However, regardless of the value of nc, all curves from a given source file will reside in a single target file. If nc is zero, all curves will be merged into a single file.<p>
</a>
<a name="544961">
For efficiency this function currently assumes that all curves in a given source file share the domain of the first curve in that file. This is true for ULTRA files produced by the PANACEA time history transpose routines. Curves from arbitrary ULTRA files can be merged, albeit less efficiently, using the </a>save command in the </a>ULTRA utility.<p>
</a>
<a name="544962">
Input to this function is: nb, an integer number of characters in base; base, an ASCII string containing the base file name; nn, an integer number of characters in names; names, an ASCII string containing the space delimited full names of the ULTRA source files; and nc an integer approximate number of curves per ULTRA target file.<p>
</a>
<a name="544947">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544964">
See also </a>PAMRGF.<p>
</a>
<A NAME="544965"><PRE>
</PRE><A NAME="544966"><PRE> integer </a>PAMRGN(integer nb,
</PRE><A NAME="544948"><PRE> char *base,
</PRE><A NAME="544967"><PRE> integer nn,
</PRE><A NAME="544968"><PRE> char *names,
</PRE><A NAME="544969"><PRE> integer nc)
</PRE><A NAME="544970"><B>
</B><HR><A NAME="544949"><PRE> integer pamrgn
</PRE><A NAME="544950"><PRE> character*8 names(3)
</PRE><A NAME="544951"><PRE> .
</PRE><A NAME="544952"><PRE> .
</PRE><A NAME="544953"><PRE> .
</PRE><A NAME="544954"><PRE> c merge files foo.u09 through foo.u0b
</PRE><A NAME="544955"><PRE> names(1) = ‘foo.u09 ’
</PRE><A NAME="544963"><PRE> names(2) = ‘foo.u0a ’
</PRE><A NAME="544976"><PRE> names(3) = ‘foo.u0b ’
</PRE><A NAME="544971"><PRE> if (</a>pamrgn(3, ‘bar’, 24, names, 1000) .eq. 0)
</PRE><A NAME="544972"><PRE> $ call errproc
</PRE><A NAME="544973"><PRE> .
</PRE><A NAME="544974"><PRE> .
</PRE><A NAME="544975"><PRE> .
</PRE><a name="544256">
<h3>5.10.6 PATHFM</h3>
</a>
<A NAME="544273"><PRE>
</PRE><A NAME="544322"><PRE> integer </a>PATHFM(integer fileid)
</PRE><a name="544274">
Check the current file’s size against the maximum size as specified in the </a>PATHOP call. If the file is larger than the maximum size, close the file, open the next member of the file family, and return an id for the new file.<p>
</a>
<a name="544275">
Input to this function is: fileid, an integer file identifier.<p>
</a>
<a name="544303">
An integer PDBfile identifier is returned if the call is successful; otherwise, -1 is returned and an error message may be retrieved by invoking function </a>PFGERR. The return value should be checked against the original one to see whether or not a new file has been opened.<p>
</a>
<a name="544304">
See also </a>PABREC, </a>PAAREC, </a>PAEREC, </a>PAWREC, and </a>PATHOP.<p>
</a>
<A NAME="544305"><PRE>
</PRE><A NAME="544306"><PRE> integer </a>PATHFM(integer fileid)
</PRE><A NAME="544311"><B>
</B><HR><A NAME="544312"><PRE> integer pathfm
</PRE><A NAME="544313"><PRE> integer nfid, fid
</PRE><A NAME="544307"><PRE> .
</PRE><A NAME="544314"><PRE> .
</PRE><A NAME="544315"><PRE> .
</PRE><A NAME="544316"><PRE> nfid = </a>pathfm(fid)
</PRE><A NAME="544317"><PRE> if (nfid .eq. -1)
</PRE><A NAME="544309"><PRE> $ call errproc
</PRE><A NAME="544310"><PRE>
</PRE><A NAME="544308"><PRE> if (nfid .ne. fid)
</PRE><A NAME="544318"><PRE> $ fid = nfid
</PRE><A NAME="544319"><PRE> .
</PRE><A NAME="544320"><PRE> .
</PRE><A NAME="544321"><PRE> .
</PRE><a name="544265">
<h3>5.10.7 PATHOP</h3>
</a>
<A NAME="544268"><PRE>
</PRE><A NAME="544298"><PRE> integer </a>PATHOP(integer nf,
</PRE><A NAME="544299"><PRE> char *name,
</PRE><A NAME="544300"><PRE> integer nm,
</PRE><A NAME="544301"><PRE> char *mode,
</PRE><A NAME="544302"><PRE> integer sz,
</PRE><A NAME="544278"><PRE> integer np,
</PRE><A NAME="544279"><PRE> char *prev)
</PRE><a name="544269">
Open a new time history data file. This implicitly defines a family of files. The name should be of the form: base.tdd where d is a base 36 digit (i.e. 0-9a-z). This is only a convention, but there are certain consequences for not following it in as much as the familying mechanism assumes that the last two characters form a base 36 number and increments it accordingly. As an application writes data to a time history file, periodic calls to </a>PATHFM should be made to monitor the file size and when necessary close the current family member and open the next.<p>
</a>
<a name="544329">
Since simulations may be restarted and each code may have a different strategy for continuing time history collection in the event of a restart, it is necessary to allow for name changes in the family. The consequence of this is that each member of a file family must contain the name of the previous file in the family. In that way, the transpose process may unambiguously and under the control of the user or simulation follow a chain of time history files from the end point back to the beginning. The prev argument is used to supply this information. The family of files that follows will be in sequence from the name supplied. Only across restarts, which implies calls to PATHOP, may the sequence name be changed. A call to PATHOP may have 0 for np which indicates the absolute beginning of the sequence, i.e. the transpose will stop in its search for files at this point.<p>
</a>
<a name="544270">
Input to this function is: nf, an integer number of characters in name; name, an ASCII string specifying the name of the first file in the family for the current application; nm, an integer number of characters in mode; mode, an ASCII string specifying the mode of the file (typically this will be “w”); and sz, an integer value specifying the target maximum file size for members of the family.<p>
</a>
<a name="544271">
An integer PDBfile identifier is returned if the call is successful; otherwise, -1 is returned and an error message may be retrieved by invoking function </a>PFGERR. <p>
</a>
<a name="544272">
See also </a>PABREC, </a>PAAREC, </a>PAEREC, </a>PAWREC, and </a>PATHFM.<p>
</a>
<A NAME="544281"><PRE>
</PRE><A NAME="544280"><PRE> integer </a>PATHOP(integer nf,
</PRE><A NAME="544323"><PRE> char *name,
</PRE><A NAME="544324"><PRE> integer nm,
</PRE><A NAME="544325"><PRE> char *mode,
</PRE><A NAME="544326"><PRE> integer sz,
</PRE><A NAME="544327"><PRE> integer np,
</PRE><A NAME="544328"><PRE> char *prev)
</PRE><A NAME="544285"><B>
</B><HR><A NAME="544286"><PRE> integer pathop
</PRE><A NAME="544287"><PRE> .
</PRE><A NAME="544288"><PRE> .
</PRE><A NAME="544289"><PRE> .
</PRE><A NAME="544290"><PRE> fid = </a>pathop(3, ‘foo’, 1, ‘w’, 1000000, 4, ‘blat’)
</PRE><A NAME="544295"><PRE> if (fid .eq. -1)
</PRE><A NAME="544291"><PRE> $ call errproc
</PRE><A NAME="544292"><PRE> .
</PRE><A NAME="544293"><PRE> .
</PRE><A NAME="544294"><PRE> .
</PRE><a name="543219">
<h3>5.10.8 PATHTL</h3>
</a>
<A NAME="543220"><PRE>
</PRE><A NAME="543221"><PRE> integer </a>PATHTL(char *names,
</PRE><A NAME="543222"><PRE> integer ord,
</PRE><A NAME="543223"><PRE> int nc)
</PRE><a name="543224">
</a>WARNING: This is a deprecated function. Use </a>PATRNL instead.<p>
</a>
<a name="544840">
Write an ULTRA file by </a>transposing the </a>time history data from a specified set of time history files. The time history files are specified here by giving the names of files at the end of file family chains.<p>
</a>
<a name="543225">
On occasion, files in a family are lost. This breaks the chain of files as well as leaving gaps in the data. Since this function can take many file names, it can be used to take into account missing files by supplying the files at the top of the gap(s) of missing files. In the accompanying example it is assumed that the files foo.t09 through foo.t11 are missing.<p>
</a>
<a name="543226">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="543227">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="543228"><PRE> name.tdd
</PRE><a name="543229">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="543230">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="543231"><PRE> name.udd
</PRE><a name="543232">
Input to this function is: names, an ASCII string containing the space delimited full names of the time history files; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="543233">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="543234">
See also </a>PATRNN and </a>PATRNF.<p>
</a>
<A NAME="543235"><PRE>
</PRE><A NAME="543236"><PRE> integer </a>PATHTL(char *names,
</PRE><A NAME="543237"><PRE> integer ord,
</PRE><A NAME="543238"><PRE> int nc)
</PRE><A NAME="543239"><B>
</B><HR><A NAME="543240"><PRE> integer pathtl
</PRE><A NAME="543241"><PRE> character*8 names(2)
</PRE><A NAME="543242"><PRE> .
</PRE><A NAME="543243"><PRE> .
</PRE><A NAME="543244"><PRE> .
</PRE><A NAME="543245"><PRE> c files foo.t09 through foo.t11 are missing
</PRE><A NAME="543246"><PRE> names(1) = ‘foo.t1f ’
</PRE><A NAME="544382"><PRE> names(2) = ‘foo.t08 ’
</PRE><A NAME="544439"><PRE> if (</a>pathtl(names, -1, 1000) .eq. 0)
</PRE><A NAME="544440"><PRE> $ call errproc
</PRE><A NAME="544441"><PRE> .
</PRE><A NAME="544442"><PRE> .
</PRE><A NAME="544443"><PRE> .
</PRE><a name="544444">
<h3>5.10.9 PATHTN</h3>
</a>
<A NAME="544445"><PRE>
</PRE><A NAME="544446"><PRE> integer </a>PATHTN(char *names,
</PRE><A NAME="544447"><PRE> integer ord,
</PRE><A NAME="544448"><PRE> int nc)
</PRE><a name="544839">
WARNING: This is a deprecated function. Use </a>PATRNN instead.<p>
</a>
<a name="544449">
</a>Write an ULTRA file by </a>transposing the </a>time history data from a specified set of time history files. The time history files are specified here explicitly by name.<p>
</a>
<a name="544450">
On occasion, it is desirable to transpose only selected files from a family. For example, a user may know that only certain times are of interest and doesn’t wish to see the entire data set. This function gives the finest level of control to the application about which files to transpose.<p>
</a>
<a name="544451">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="544453">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544454"><PRE> name.tdd
</PRE><a name="544455">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544456">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544457"><PRE> name.udd
</PRE><a name="544458">
Input to this function is: names, an ASCII string containing the space delimited full names of the time history files; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544459">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544460">
See also </a>PATRNL and </a>PATRNF.<p>
</a>
<A NAME="544461"><PRE>
</PRE><A NAME="544462"><PRE> integer </a>PATHTN(char *names,
</PRE><A NAME="544463"><PRE> integer ord,
</PRE><A NAME="544464"><PRE> int nc)
</PRE><A NAME="544465"><B>
</B><HR><A NAME="544466"><PRE> integer pathtn
</PRE><A NAME="544467"><PRE> character*16 names(4)
</PRE><A NAME="544468"><PRE> .
</PRE><A NAME="544469"><PRE> .
</PRE><A NAME="544470"><PRE> .
</PRE><A NAME="544471"><PRE> c only transpose foo.t09 through foo.t0b
</PRE><A NAME="544472"><PRE> names(1) = ‘foo.t09 ’
</PRE><A NAME="544473"><PRE> names(2) = ‘foo.t0a ’
</PRE><A NAME="544474"><PRE> names(3) = ‘foo.t0b ’
</PRE><A NAME="544475"><PRE> names(4) = ‘ ’
</PRE><A NAME="544476"><PRE> if (</a>pathtn(names, 1, 1000) .eq. 0)
</PRE><A NAME="544477"><PRE> $ call errproc
</PRE><A NAME="544478"><PRE> .
</PRE><A NAME="544479"><PRE> .
</PRE><A NAME="544480"><PRE> .
</PRE><a name="544481">
<h3>5.10.10 PATHTR</h3>
</a>
<A NAME="544482"><PRE>
</PRE><A NAME="544483"><PRE> integer </a>PATHTR(integer nf,
</PRE><A NAME="544484"><PRE> char *name,
</PRE><A NAME="544485"><PRE> integer nc)
</PRE><a name="544841">
</a>WARNING This is a deprecated function. Use </a>PATRNF instead.<p>
</a>
<a name="544486">
Write an </a>ULTRA file by </a>transposing the </a>time history data from a given set of time history files.<p>
</a>
<a name="544487">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544488"><PRE> name.tdd
</PRE><a name="544489">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544490">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544491"><PRE> name.udd
</PRE><a name="544492">
Input to this function is: nf, an integer number of characters in name; name, an ASCII string containing the base name of the time history file family; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544494">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544495">
See also </a>PATRNL and </a>PATRNN.<p>
</a>
<A NAME="544496"><PRE>
</PRE><A NAME="544520"><PRE> integer </a>PATHTR(integer nf,
</PRE><A NAME="544521"><PRE> char *name,
</PRE><A NAME="544522"><PRE> integer nc)
</PRE><A NAME="544523"><B>
</B><HR><A NAME="544524"><PRE> integer pathtr
</PRE><A NAME="544525"><PRE> .
</PRE><A NAME="544526"><PRE> .
</PRE><A NAME="544527"><PRE> .
</PRE><A NAME="544528"><PRE> if (</a>pathtr(3, ‘foo’, 1000) .eq. 0)
</PRE><A NAME="544529"><PRE> $ call errproc
</PRE><A NAME="544530"><PRE> .
</PRE><A NAME="544531"><PRE> .
</PRE><A NAME="544532"><PRE> .
</PRE><a name="544842">
<h3>5.10.11 PATRNF</h3>
</a>
<A NAME="544843"><PRE>
</PRE><A NAME="544844"><PRE> integer </a>PATRNF(integer nf,
</PRE><A NAME="544845"><PRE> char *name,
</PRE><A NAME="544978"><PRE> integer ord,
</PRE><A NAME="544846"><PRE> integer nc)
</PRE><a name="544847">
</a>Write an </a>ULTRA file by </a>transposing the </a>time history data from a given set of time history files.<p>
</a>
<a name="544848">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544849"><PRE> name.tdd
</PRE><a name="544850">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544851">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544852"><PRE> name.udd
</PRE><a name="544979">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="544853">
Input to this function is: nf, an integer number of characters in name; name, an ASCII string containing the base name of the time history file family; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544854">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544855">
See also </a>PATRNL and </a>PATRNN.<p>
</a>
<A NAME="544856"><PRE>
</PRE><A NAME="544857"><PRE> integer </a>PATRNF(integer nf,
</PRE><A NAME="544858"><PRE> char *name,
</PRE><A NAME="544980"><PRE> integer ord,
</PRE><A NAME="544859"><PRE> integer nc)
</PRE><A NAME="544860"><B>
</B><HR><A NAME="544861"><PRE> integer patrnf
</PRE><A NAME="544862"><PRE> .
</PRE><A NAME="544863"><PRE> .
</PRE><A NAME="544864"><PRE> .
</PRE><A NAME="544865"><PRE> if (</a>patrnf(3, ‘foo’, 1, 1000) .eq. 0)
</PRE><A NAME="544866"><PRE> $ call errproc
</PRE><A NAME="544867"><PRE> .
</PRE><A NAME="544868"><PRE> .
</PRE><A NAME="544869"><PRE> .
</PRE><a name="544706">
<h3>5.10.12 PATRNL</h3>
</a>
<A NAME="544707"><PRE>
</PRE><A NAME="544708"><PRE> integer </a>PATRNL(int nn,
</PRE><A NAME="544811"><PRE> char *names,
</PRE><A NAME="544709"><PRE> integer ord,
</PRE><A NAME="544711"><PRE> int nc)
</PRE><a name="544712">
</a>Write an ULTRA file by </a>transposing the </a>time history data from a specified set of time history files. The time history files are specified here by giving the names of files at the end of file family chains.<p>
</a>
<a name="544745">
On occasion, files in a family are lost. This breaks the chain of files as well as leaving gaps in the data. Since this function can take many file names, it can be used to take into account missing files by supplying the files at the top of the gap(s) of missing files. In the accompanying example it is assumed that the files foo.t09 through foo.t11 are missing.<p>
</a>
<a name="544746">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="544747">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544748"><PRE> name.tdd
</PRE><a name="544749">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544751">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544752"><PRE> name.udd
</PRE><a name="544753">
Input to this function is: nn, an integer number of characters in names; names, an ASCII string containing the space delimited full names of the time history files; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544754">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544755">
See also </a>PATRNN and </a>PATRNF.<p>
</a>
<A NAME="544756"><PRE>
</PRE><A NAME="544757"><PRE> integer </a>PATRNL(int nn,
</PRE><A NAME="544769"><PRE> char *names,
</PRE><A NAME="544758"><PRE> integer ord,
</PRE><A NAME="544759"><PRE> int nc)
</PRE><A NAME="544760"><B>
</B><HR><A NAME="544761"><PRE> integer patrnl
</PRE><A NAME="544762"><PRE> character*8 names(2)
</PRE><A NAME="544763"><PRE> .
</PRE><A NAME="544764"><PRE> .
</PRE><A NAME="544765"><PRE> .
</PRE><A NAME="544766"><PRE> c files foo.t09 through foo.t11 are missing
</PRE><A NAME="544767"><PRE> names(1) = ‘foo.t1f ’
</PRE><A NAME="544768"><PRE> names(2) = ‘foo.t08 ’
</PRE><A NAME="544770"><PRE> if (</a>patrnl(16, names, -1, 1000) .eq. 0)
</PRE><A NAME="544771"><PRE> $ call errproc
</PRE><A NAME="544772"><PRE> .
</PRE><A NAME="544773"><PRE> .
</PRE><A NAME="544774"><PRE> .
</PRE><a name="544775">
<h3>5.10.13 PATRNN</h3>
</a>
<A NAME="544776"><PRE>
</PRE><A NAME="544777"><PRE> integer </a>PATRNN(int nn,
</PRE><A NAME="544812"><PRE> char *names,
</PRE><A NAME="544778"><PRE> integer ord,
</PRE><A NAME="544779"><PRE> int nc)
</PRE><a name="544780">
</a>Write an ULTRA file by </a>transposing the </a>time history data from a specified set of time history files. The time history files are specified here explicitly by name.<p>
</a>
<a name="544781">
On occasion, it is desirable to transpose only selected files from a family. For example, a user may know that only certain times are of interest and doesn’t wish to see the entire data set. This function gives the finest level of control to the application about which files to transpose.<p>
</a>
<a name="544782">
There is the possibility inherent in this model of handling file families that two or more files to be processed will have data for some regions in time. Because of the underlying PDB machinery, the data from the last file processed will predominate. Also, since the files are linked together from latest to earliest, it is sometimes necessary to require that the files be processed in the opposite order in which they are specified. The ord argument is used for this purpose. A value of 1 causes the files to be processed in the order in which they are specified while a value of -1 causes them to be processed in reverse order.<p>
</a>
<a name="544783">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544784"><PRE> name.tdd
</PRE><a name="544785">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544786">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544787"><PRE> name.udd
</PRE><a name="544788">
Input to this function is: nn, an integer number of characters in names; names, an ASCII string containing the space delimited full names of the time history files; ord, an integer flag specifying the order of processing; and nc a maximum number of curves per file in the ULTRA file family.<p>
</a>
<a name="544789">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544790">
See also </a>PATRNL and </a>PATRNF.<p>
</a>
<A NAME="544791"><PRE>
</PRE><A NAME="544792"><PRE> integer </a>PATRNN(int nn,
</PRE><A NAME="544813"><PRE> char *names,
</PRE><A NAME="544793"><PRE> integer ord,
</PRE><A NAME="544794"><PRE> int nc)
</PRE><A NAME="544795"><B>
</B><HR><A NAME="544796"><PRE> integer patrnn
</PRE><A NAME="544797"><PRE> character*8 names(3)
</PRE><A NAME="544798"><PRE> .
</PRE><A NAME="544799"><PRE> .
</PRE><A NAME="544800"><PRE> .
</PRE><A NAME="544801"><PRE> c only transpose foo.t09 through foo.t0b
</PRE><A NAME="544802"><PRE> names(1) = ‘foo.t09 ’
</PRE><A NAME="544803"><PRE> names(2) = ‘foo.t0a ’
</PRE><A NAME="544804"><PRE> names(3) = ‘foo.t0b ’
</PRE><A NAME="544806"><PRE> if (</a>patrnn(24, names, 1, 1000) .eq. 0)
</PRE><A NAME="544807"><PRE> $ call errproc
</PRE><A NAME="544808"><PRE> .
</PRE><A NAME="544809"><PRE> .
</PRE><A NAME="544810"><PRE> .
</PRE><a name="543247">
<h3>5.10.14 PAWREC</h3>
</a>
<A NAME="543248"><PRE>
</PRE><A NAME="543249"><PRE> integer </a>PAWREC(integer fileid,
</PRE><A NAME="543250"><PRE> integer recid,
</PRE><A NAME="543251"><PRE> integer inst,
</PRE><A NAME="543252"><PRE> integer nr,
</PRE><A NAME="543253"><PRE> vr)
</PRE><a name="543254">
</a>Write out nr instances of </a>time history data whose structure has been defined by </a>PABREC, </a>PAAREC, and </a>PAEREC. This function writes out nr complete instances of a time history record! Using this function an application can manage multiple sets of time history data which are written at different frequencies.<p>
</a>
<a name="543255">
Input to this function is: fileid, an integer identifying a PDB file; recid, an integer identifier specifying a time history record type; inst, an integer specifying the instance index of the records to be written; nr, an integer specifying the number of instances of the structure pointed to by vr; and vr, the data to be written.<p>
</a>
<a name="543256">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="543257">
See also </a>PAAREC, </a>PABREC, </a>PAEREC, and </a>PAWRIA.<p>
</a>
<A NAME="543258"><PRE>
</PRE><A NAME="543259"><PRE> integer </a>PAWREC(integer fileid,
</PRE><A NAME="543260"><PRE> integer recid,
</PRE><A NAME="543261"><PRE> integer inst,
</PRE><A NAME="543262"><PRE> integer nr,
</PRE><A NAME="543263"><PRE> vr)
</PRE><A NAME="543264"><B>
</B><HR><A NAME="543265"><PRE> integer pawrec
</PRE><A NAME="543266"><PRE> integer fileid, recid
</PRE><A NAME="543267"><PRE> real*8 vr(9)
</PRE><A NAME="543268"><PRE> .
</PRE><A NAME="543269"><PRE> .
</PRE><A NAME="543270"><PRE> .
</PRE><A NAME="543271"><PRE> if (</a>pawrec(fileid, recid, 14, 3, vr) .eq. 0)
</PRE><A NAME="543272"><PRE> $ call errproc
</PRE><A NAME="543273"><PRE> .
</PRE><A NAME="543274"><PRE> .
</PRE><A NAME="543275"><PRE> .
</PRE><a name="544668">
<h3>5.10.15 PAWMEM</h3>
</a>
<A NAME="544674"><PRE>
</PRE><A NAME="544683"><PRE> integer </a>PAWMEM(integer fileid,
</PRE><A NAME="544675"><PRE> integer recid,
</PRE><A NAME="544684"><PRE> integer nc,
</PRE><A NAME="544685"><PRE> char *name,
</PRE><A NAME="544676"><PRE> integer inst,
</PRE><A NAME="544682"><PRE> vr)
</PRE><A NAME="544671"><PRE>
</PRE><a name="544677">
Write out one member of a </a>time history data record whose structure has been defined by </a>PABREC, </a>PAAREC, and </a>PAEREC. This function writes out one member of a time history record. Its utility is most apparent when the member is an array which could be large or is part of a very large record.<p>
</a>
<a name="544678">
Input to this function is: fileid, an integer identifying a PDB file; recid, an integer identifier specifying a time history record type; nc, an integer number of characters in the member string; member, an ASCII string naming the member desired; inst, an integer specifying the instance number; and vr, the data to be written.<p>
</a>
<a name="544679">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="544680">
See also </a>PAAREC, </a>PABREC, </a>PAEREC, and </a>PAWRIA.<p>
</a>
<A NAME="544672"><PRE>
</PRE><A NAME="544681"><PRE> integer </a>PAWMEM(integer fileid,
</PRE><A NAME="544686"><PRE> integer recid,
</PRE><A NAME="544687"><PRE> integer nc,
</PRE><A NAME="544700"><PRE> char *name,
</PRE><A NAME="544701"><PRE> integer inst,
</PRE><A NAME="544702"><PRE> vr)
</PRE><A NAME="544673"><PRE>
</PRE><A NAME="544688"><B>
</B><HR><A NAME="544689"><PRE> integer pawmem
</PRE><A NAME="544690"><PRE> integer fileid, recid
</PRE><A NAME="544691"><PRE> real*8 vr(100,100)
</PRE><A NAME="544692"><PRE> .
</PRE><A NAME="544693"><PRE> .
</PRE><A NAME="544694"><PRE> .
</PRE><A NAME="544695"><PRE> if (</a>pawmem(fileid, recid, 3, ‘v_1’, 14, vr) .eq. 0)
</PRE><A NAME="544696"><PRE> $ call errproc
</PRE><A NAME="544697"><PRE> .
</PRE><A NAME="544698"><PRE> .
</PRE><A NAME="544699"><PRE> .
</PRE><a name="543276">
<h3>5.10.16 PAWRIA</h3>
</a>
<A NAME="543277"><PRE>
</PRE><A NAME="543278"><PRE> integer </a>PAWRIA(integer fileid,
</PRE><A NAME="543279"><PRE> integer nv,
</PRE><A NAME="543280"><PRE> char *var
</PRE><A NAME="543281"><PRE> integer inst,
</PRE><A NAME="543282"><PRE> integer na,
</PRE><A NAME="543283"><PRE> char *attr,
</PRE><A NAME="543284"><PRE> value)
</PRE><a name="543285">
</a>Assign an attribute value to the indicated</a> time history data instance.<p>
</a>
<a name="543286">
Input to this function is: fileid, an integer identifying a PDB file; nv, an integer number of characters in the string var; var, an ASCII string naming the time history data entry; inst, an integer specifying the instance index of the records to be written; na, an integer specifying the number of characters in the attribute name; attr, an ASCII string containing the name of an attribute; and; and value, the attribute value.<p>
</a>
<a name="543287">
The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function </a>PFGERR.<p>
</a>
<a name="543288">
See also </a>PAAREC, </a>PABREC, </a>PAEREC, and </a>PAWREC.<p>
</a>
<A NAME="543289"><PRE>
</PRE><A NAME="543290"><PRE> integer </a>PAWRIA(integer fileid,
</PRE><A NAME="543291"><PRE> integer nv,
</PRE><A NAME="543292"><PRE> char *var
</PRE><A NAME="543293"><PRE> integer inst,
</PRE><A NAME="543294"><PRE> integer na,
</PRE><A NAME="543295"><PRE> char *attr,
</PRE><A NAME="543296"><PRE> value)
</PRE><A NAME="543297"><B>
</B><HR><A NAME="543298"><PRE> integer pawria
</PRE><A NAME="543299"><PRE> integer fileid
</PRE><A NAME="543300"><PRE> character*8 datestr
</PRE><A NAME="543301"><PRE>
</PRE><A NAME="543302"><PRE> .
</PRE><A NAME="543303"><PRE> .
</PRE><A NAME="543304"><PRE> .
</PRE><A NAME="543305"><PRE> if (</a>pawria(fileid, 6, ‘t-data’, 3, 4, ‘date’, datestr)
</PRE><A NAME="543306"><PRE> $ .eq. 0) call errproc
</PRE><A NAME="543307"><PRE> .
</PRE><A NAME="543308"><PRE> .
</PRE><A NAME="543309"><PRE> .
</PRE><a name="544498">
<h3>5.10.17 FORTRAN API </a>Time History Example</h3>
</a>
<a name="544504">
Here is an example of using the time history functionality of PANACEA.<p>
</a>
<A NAME="544499"><CODE></CODE><A NAME="544500"><CODE></CODE><A NAME="544501"><CODE></CODE><A NAME="544502"><CODE></CODE><A NAME="544503"><CODE></CODE><A NAME="544669"><CODE></CODE><A NAME="544505"><CODE></CODE><A NAME="544506"><CODE></CODE><A NAME="544507"><CODE></CODE><A NAME="544508"><CODE></CODE><A NAME="544509"><CODE></CODE><A NAME="544510"><CODE></CODE><A NAME="544511"><CODE></CODE><A NAME="544512"><CODE></CODE><A NAME="544513"><CODE></CODE><A NAME="544514"><CODE></CODE><A NAME="544515"><CODE></CODE><A NAME="544516"><CODE></CODE><A NAME="544517"><CODE></CODE><A NAME="544518"><CODE></CODE><A NAME="544519"><CODE></CODE><A NAME="544533"><CODE></CODE><A NAME="544534"><CODE></CODE><A NAME="544535"><CODE></CODE><A NAME="544536"><CODE></CODE><A NAME="544537"><CODE></CODE><A NAME="544538"><CODE></CODE><A NAME="544539"><CODE></CODE><A NAME="544540"><CODE></CODE><A NAME="544541"><CODE></CODE><A NAME="544542"><CODE></CODE><A NAME="544543"><CODE></CODE><A NAME="544544"><CODE></CODE><A NAME="544493"><CODE></CODE><A NAME="544545"><CODE></CODE><A NAME="544547"><CODE></CODE><A NAME="544548"><CODE></CODE><A NAME="544549"><CODE></CODE><A NAME="544550"><CODE></CODE><A NAME="544551"><CODE></CODE><A NAME="544552"><CODE></CODE><A NAME="544553"><CODE></CODE><A NAME="544554"><CODE></CODE><A NAME="544555"><CODE></CODE><A NAME="544556"><CODE></CODE><A NAME="544557"><CODE></CODE><A NAME="544558"><CODE></CODE><A NAME="544559"><CODE></CODE><A NAME="544560"><CODE></CODE><A NAME="544561"><CODE></CODE><A NAME="544562"><CODE></CODE><A NAME="544563"><CODE></CODE><A NAME="544564"><CODE></CODE><A NAME="544565"><CODE></CODE><A NAME="544566"><CODE></CODE><A NAME="544567"><CODE></CODE><A NAME="544568"><CODE></CODE><A NAME="544569"><CODE></CODE><A NAME="544570"><CODE></CODE><A NAME="544571"><CODE></CODE><A NAME="544572"><CODE></CODE><A NAME="544573"><CODE></CODE><A NAME="544574"><CODE></CODE><A NAME="544575"><CODE></CODE><A NAME="544576"><CODE></CODE><A NAME="544577"><CODE></CODE><A NAME="544578"><CODE></CODE><A NAME="544579"><CODE></CODE><A NAME="544580"><CODE></CODE><A NAME="544581"><CODE></CODE><A NAME="544582"><CODE></CODE><A NAME="544583"><CODE></CODE><A NAME="544584"><CODE></CODE><A NAME="544585"><CODE></CODE><A NAME="544586"><CODE></CODE><A NAME="544587"><CODE></CODE><A NAME="544588"><CODE></CODE><A NAME="544589"><CODE></CODE><A NAME="544590"><CODE></CODE><A NAME="544591"><CODE></CODE><A NAME="544592"><CODE></CODE><A NAME="544593"><CODE></CODE><A NAME="544594"><CODE></CODE><A NAME="544595"><CODE></CODE><A NAME="544596"><CODE></CODE><A NAME="544597"><CODE></CODE><A NAME="544598"><CODE></CODE><A NAME="544599"><CODE></CODE><A NAME="544600"><CODE></CODE><A NAME="544601"><CODE></CODE><A NAME="544602"><CODE></CODE><A NAME="544603"><CODE></CODE><A NAME="544604"><CODE></CODE><A NAME="544605"><CODE></CODE><A NAME="544606"><CODE></CODE><A NAME="544607"><CODE></CODE><A NAME="544608"><CODE></CODE><A NAME="544609"><CODE></CODE><A NAME="544610"><CODE></CODE><A NAME="544611"><CODE></CODE><A NAME="544612"><CODE></CODE><A NAME="544613"><CODE></CODE><A NAME="544614"><CODE></CODE><A NAME="544615"><CODE></CODE><A NAME="544616"><CODE></CODE><A NAME="544617"><CODE></CODE><A NAME="544618"><CODE></CODE><A NAME="544619"><CODE></CODE><A NAME="544620"><CODE></CODE><A NAME="544621"><CODE></CODE><A NAME="544622"><CODE></CODE><A NAME="544623"><CODE></CODE><A NAME="544624"><CODE></CODE><A NAME="544625"><CODE></CODE><A NAME="544626"><CODE></CODE><A NAME="544627"><CODE></CODE><A NAME="544628"><CODE></CODE><A NAME="544629"><CODE></CODE><A NAME="544630"><CODE></CODE><A NAME="544631"><CODE></CODE><A NAME="544632"><CODE></CODE><A NAME="544633"><CODE></CODE><A NAME="544634"><CODE></CODE><A NAME="544635"><CODE></CODE><A NAME="544636"><CODE></CODE><A NAME="544637"><CODE></CODE><A NAME="544638"><CODE></CODE><A NAME="544639"><CODE></CODE><A NAME="544640"><CODE></CODE><A NAME="544641"><CODE></CODE><A NAME="544642"><CODE></CODE><A NAME="544643"><CODE></CODE><A NAME="544644"><CODE></CODE><A NAME="544645"><CODE></CODE><A NAME="544646"><CODE></CODE><A NAME="544647"><CODE></CODE><A NAME="544648"><CODE></CODE><A NAME="544649"><CODE></CODE><A NAME="544650"><CODE></CODE><A NAME="544651"><CODE></CODE><A NAME="544652"><CODE></CODE><A NAME="544653"><CODE></CODE><A NAME="544654"><CODE></CODE><A NAME="544655"><CODE></CODE><A NAME="544656"><CODE></CODE><A NAME="544657"><CODE></CODE><A NAME="544658"><CODE></CODE><A NAME="544659"><CODE></CODE><A NAME="544660"><CODE></CODE><A NAME="544661"><CODE></CODE><A NAME="544662"><CODE></CODE><A NAME="544663"><CODE></CODE><A NAME="544664"><CODE></CODE><A NAME="544665"><CODE></CODE><A NAME="544666"><CODE></CODE><A NAME="544667"><CODE></CODE><a name="543310">
<h2>5.11 Miscellaneous</h2>
</a>
<a name="543311">
<h1>6.0 PANACEA Initial Value Problem Generators</h1>
</a>
<a name="543312">
<p>
</a>
<a name="543313">
<h2>6.1 Generic Commands Supplied by PANACEA</h2>
</a>
<a name="543314">
<p>
</a>
<A NAME="543315"><BR><B></a>dump
</B><BR><a name="543316">
Build the database and write a restart dump.<p>
</a>
<A NAME="543317"><BR><B></a>end
</B><BR><a name="543318">
Shutdown the generator.<p>
</a>
<A NAME="543319"><BR><B></a>graph
</B><BR><a name="543320">
Specify a plot request.<p>
</a>
<A NAME="543321"><BR><B></a>name
</B><BR><a name="543322">
Set the value of a name for the current package.<p>
</a>
<A NAME="543323"><BR><B></a>package
</B><BR><a name="543324">
Specify the package to which subsequent SWITCH, PARAMETER, and NAME commands apply.<p>
</a>
<A NAME="543325"><BR><B></a>parameter
</B><BR><a name="543326">
Set the value of a parameter for the current package.<p>
</a>
<A NAME="543327"><BR><B></a>read
</B><BR><a name="543328">
Read a file of generator commands.<p>
</a>
<A NAME="543329"><BR><B></a>s
</B><BR><a name="543330">
Continuation of last specify command.<p>
</a>
<A NAME="543331"><BR><B></a>specify
</B><BR><a name="543332">
Specify an initial value constraint (BC, SRC, or <variable>). The precise syntax for this command is:<p>
</a>
<A NAME="543333">specify <</a>bc name | </a>src name | name> spec-list
<P><A NAME="543334">
<P><A NAME="543335">spec-list := spec-list spec | spec
<P><A NAME="543336">spec := </a>from file |
<P><A NAME="543337"> </a>interpolate |
<P><A NAME="543338"> </a>discrete |
<P><A NAME="543339"> </a>in name |
<P><A NAME="543340"> </a>at value |
<P><A NAME="543341"> </a>along value |
<P><A NAME="543342"> value
<P><a name="543343">
The specifications at and along are simply put their associated value into the array of floating point numbers which the specify command constructs. In short, they are for the clarity of the input command. The in specification invokes the </a>PA_reg_hook to map a name to a number which goes in the array which specify builds. The intention again is to provide an additional level of clarity by allowing users of a PANACEA code to be able to specify at least some information by name. Any value can be denoted by an alias which is defined by a call to </a>PA_alias.<p>
</a>
<a name="543344">
The array of number which this command builds up can be handed back to those part of the packages which query the initial value specifications.<p>
</a>
<A NAME="543345"><BR><B></a>switch
</B><BR><a name="543346">
Set the value of a switch for the current package.<p>
</a>
<a name="544232">
<h1>7.0 PANACEA Supplied Physical Constants</h1>
</a>
<a name="543348">
PANACEA provides a service for handling physical units in simulation packages. It is geared toward solving problems associated with importing and exporting packages between PANACEA codes and toward letting the code developer and code users have control over the systems of units in which problems are run and debugged.<p>
</a>
<a name="543349">
Part of this service hinges on providing fundamental physical constants which the code developer can use in expressions appearing in the set of equations which their packages solve. Coupled with a complete definition of the set of units (see the next section) PANACEA is able to change the values of its physical constants to reflect the system of units in which the user or code developer wishes to work.<p>
</a>
<a name="543350">
At the beginning of a code run, these constants are initialized with their CGS values as indicated below. Once the system of units is defined (either by the input deck for the initial value problem generator or from the restart dump for the main simulation code) all of these constants are converted into the defined system of units.<p>
</a>
<a name="543351">
The constants given below are divided into three categories: ones with no units (pure numbers); those with physical units that cannot be expressed in terms of more fundamental physical constants; and those which can be expressed in terms of more fundamental constants.<p>
</a>
<a name="543352">
<p>
</a>
<a name="543353">
<h3>7.0.1 Pure Numbers</h3>
</a>
<a name="543354">
<p>
</a>
<A NAME="543355"><BR><B></a> alpha
</B><BR><a name="543356">
Fine structure constant = 7.297353080e-3<p>
</a>
<A NAME="543357"><BR><B></a> Coulomb
</B><BR><a name="543358">
Coulomb in fundamental charges = 6.241506363e18<p>
</a>
<A NAME="543359"><BR><B></a> N0
</B><BR><a name="543360">
Avogadro’s number = 6.02213665e23<p>
</a>
<a name="543361">
<p>
</a>
<a name="543362">
<p>
</a>
<a name="543363">
<h3>7.0.2 Fundamental Physical Constants</h3>
</a>
<a name="543364">
<p>
</a>
<A NAME="543365"><BR><B></a> c
</B><BR><a name="543366">
Speed of light (cm/sec) = 2.99792458e10<p>
</a>
<A NAME="543367"><BR><B></a> Gn
</B><BR><a name="543368">
Newtonian gravitational constant (cm3/g-sec2) = 6.673231e-8<p>
</a>
<A NAME="543369"><BR><B></a> Hbar
</B><BR><a name="543370">
Planck’s constant divided by 2Pi (erg-sec) = 1.05457267e-27<p>
</a>
<A NAME="543371"><BR><B> </a>kBoltz
</B><BR><a name="543372">
Boltzman constant (erg/K) = 1.380658e-16<p>
</a>
<A NAME="543373"><BR><B></a> M_e
</B><BR><a name="543374">
electron mass (g) = 9.109389754e-28<p>
</a>
<a name="543375">
<p>
</a>
<a name="543376">
<h3>7.0.3 Derived Physical Constants</h3>
</a>
<a name="543377">
<p>
</a>
<A NAME="543378"><BR><B></a> e
</B><BR><a name="543379">
Electron charge, sqrt(alpha*Hbar*c) (esu) = 4.80320680e-10<p>
</a>
<A NAME="543380"><BR><B></a> eV_erg
</B><BR><a name="543381">
eV to erg, 1.0e7/Coulomb (erg/eV) = 1.60217733e-12<p>
</a>
<A NAME="543382"><BR><B></a> HbarC
</B><BR><a name="543383">
Hbar*c (eV-cm) = 1.97327054e-5<p>
</a>
<A NAME="543384"><BR><B></a> M_a
</B><BR><a name="543385">
Atomic mass unit, 1/N0 (g) = 1.660540210e-24<p>
</a>
<A NAME="543386"><BR><B></a> M_e_eV
</B><BR><a name="543387">
Electron mass, Me*c*c/eV_erg (eV) = 5.10999065e5<p>
</a>
<A NAME="543388"><BR><B></a> Ryd
</B><BR><a name="543389">
Rydberg, (M_e*c2*alpha2)/2 (eV) = 13.605698140<p>
</a>
<a name="543390">
<p>
</a>
<a name="543391">
In addition to theses constants, the constants #define’d by PML are available to PANACEA packages. These are:<p>
</a>
<a name="543392">
<p>
</a>
<A NAME="543393"><BR><B></a>DEG_RAD
</B><BR><a name="543394">
Conversion from degrees to radians = 0.017453292519943295<p>
</a>
<A NAME="543395"><BR><B></a>PI
</B><BR><a name="543396">
<img src="chars/pi.gif"> = 3.1415926535897931<p>
</a>
<A NAME="543397"><BR><B></a>RAD_DEG
</B><BR><a name="543398">
Conversion from radians to degrees = 57.295779513082323<p>
</a>
<a name="543399">
<p>
</a>
<a name="543400">
<h1>8.0 </a>Physical Units in PANACEA</h1>
</a>
<a name="543401">
In PANACEA the view is taken that all expressions involving fundamental physical constants should be expressed in terms of scalar variables representing those constants, NOT as numerical constants. There are two main reasons for this: PANACEA can offer the code developer many options for converting between systems of units; and the expressions involving such constants are self-documenting.<p>
</a>
<a name="543402">
A critical part of PANACEA’s ability to perform these services is its ability to specify and manipulate the physical units which a simulation package requires. PANACEA starts with a reasonable set of physical units:<p>
</a>
<A NAME="543403"><PRE> Type Macro Variable
</PRE><A NAME="543404"><PRE> </a>angle </a>RAD </a>PA_radian
</PRE><A NAME="543405"><PRE> </a>STER </a>PA_steradian
</PRE><A NAME="543406"><PRE> </a>charge </a>Q </a>PA_electric_charge
</PRE><A NAME="543407"><PRE> </a>energy </a>EV </a>PA_eV
</PRE><A NAME="543408"><PRE> </a>ERG </a>PA_erg
</PRE><A NAME="543409"><PRE> </a>length </a>CM </a>PA_cm
</PRE><A NAME="543410"><PRE> </a>mass </a>G </a>PA_gram
</PRE><A NAME="543411"><PRE> </a>number </a>MOLE </a>PA_mole
</PRE><A NAME="543412"><PRE> </a>temperature </a>K </a>PA_kelvin
</PRE><A NAME="543413"><PRE> </a>time </a>SEC </a>PA_sec
</PRE><A NAME="543414"><PRE> </a>volume </a>CC </a>PA_cc
</PRE><a name="543415">
The code developer can define new units with a call to </a>PA_def_unit. PA_def_unit takes a numerical value and a list of previously defined units and returns the index of a newly defined unit. For example, the units CM, SEC, ERG and CC are defined as: <p>
</a>
<A NAME="543416"><PRE> PA_cm = PA_def_unit(1.0, UNITS);
</PRE><A NAME="543417"><PRE> PA_sec = PA_def_unit(1.0, UNITS);
</PRE><A NAME="543418"><PRE> PA_erg = PA_def_unit(1.0, G, CM, CM, PER, SEC, SEC, UNITS);
</PRE><A NAME="543419"><PRE> PA_cc = PA_def_unit(1.0, CM, CM, CM, UNITS);
</PRE><a name="543420">
In this way both primitive units, i.e. units which don’t depend on any previously defined unit, and compound units may be defined and used by PANACEA code systems.<p>
</a>
<a name="543421">
In the table above, the macro designation means that the name refers to a #define’d constant and the variable designation means that the name refers to a global scalar variable. In C it turns out to be useful to have both the macro and variable forms. So codes which are going to define units should have a set of #define’s corresponding to their PA_def_unit calls. In the case of the above example:<p>
</a>
<A NAME="543422"><PRE> #define CM PA_cm
</PRE><A NAME="543423"><PRE> #define SEC PA_sec
</PRE><A NAME="543424"><PRE> #define ERG PA_erg
</PRE><A NAME="543425"><PRE> #define CC PA_cc
</PRE><a name="543426">
would be the appropriate sort of association.<p>
</a>
<a name="543427">
In the PANACEA model there are three systems of units: CGS; internal; and external. The physical constants are initialized in CGS units. The user of a PANACEA code specifies input and receives output in the external unit system. In the simulation routines quantities are expressed in the internal system of units.<p>
</a>
<a name="543428">
There are two arrays of double precision floating point numbers which keep the conversion factors for each of the defined units. The array unit keeps the conversion factors between CGS and internal units. The array convrsn keeps the conversion factors between CGS and external units. For example, suppose a code function needs a length in the three systems of units and these are held in the variables: length_internal, length_cgs, and length_external. The values of length_internal and length_external can be obtained from length_cgs as follows:<p>
</a>
<A NAME="543429"><PRE> length_internal = length_cgs*unit[CM]
</PRE><A NAME="543430"><PRE> length_external = length_cgs*convrsn[CM]
</PRE><a name="543431">
The two situations in which this is most useful is during initial value problem generation when the data which has been read in has not yet been used to create the data structures and arrays to be used in the simulation itself and during the simulation when data from source files is brought in.<p>
</a>
<a name="543432">
PANACEA applies conversions automatically when putting out data for post processing purposes. It also lets the code developer specify what the units of the state files (restart dumps) is to be and handles any necessary conversions.<p>
</a>
<a name="543433">
An example of setting up unit systems is given below. This routine is invoked by the initial value problem generator. Depending on the value of the argument the internal system of units is defined to be “natural units” with Hbar and c both 1 or a modified CGS system with temperatures in eV.<p>
</a>
<a name="543434">
<p>
</a>
<A NAME="543435"><PRE> /* INIT_CONT - initialize the controls */
</PRE><A NAME="543436"><PRE>
</PRE><A NAME="543437"><PRE> init_cont(def_unit_flag)
</PRE><A NAME="543438"><PRE> int def_unit_flag;
</PRE><A NAME="543439"><PRE> {PA_def_units(FALSE);
</PRE><A NAME="543440"><PRE>
</PRE><A NAME="543441"><PRE> /* set up the physical constants in CGS units */
</PRE><A NAME="543442"><PRE> PA_physical_constants_cgs();
</PRE><A NAME="543443"><PRE>
</PRE><A NAME="543444"><PRE> /* define the internal system of units
</PRE><A NAME="543445"><PRE> * if def_unit_flag it TRUE, “natural units” with Hbar = c = 1
</PRE><A NAME="543446"><PRE> * are defined
</PRE><A NAME="543447"><PRE> */
</PRE><A NAME="543448"><PRE> if (def_unit_flag)
</PRE><A NAME="543449"><PRE> {unit[G] = g_icm;
</PRE><A NAME="543450"><PRE> unit[SEC] = c;
</PRE><A NAME="543451"><PRE> unit[K] = eV_icm*(kBoltz/eV_erg);
</PRE><A NAME="543452"><PRE> unit[EV] = eV_icm*unit[Q]*unit[Q]/unit[CM];}
</PRE><A NAME="543453"><PRE>
</PRE><A NAME="543454"><PRE> /* the alternate internal system of units is the modified CGS system
</PRE><A NAME="543455"><PRE> * with temperatures in eV
</PRE><A NAME="543456"><PRE> */
</PRE><A NAME="543457"><PRE> else
</PRE><A NAME="543458"><PRE> unit[K] = kBoltz/eV_erg;
</PRE><A NAME="543459"><PRE>
</PRE><A NAME="543460"><PRE> /* define the external units to be modified CGS with
</PRE><A NAME="543461"><PRE> * temperatures in eV
</PRE><A NAME="543462"><PRE> */
</PRE><A NAME="543463"><PRE> convrsn[K] = kBoltz/eV_erg;
</PRE><A NAME="543464"><PRE>
</PRE><A NAME="543465"><PRE> /* make the conversion factors consistent with these changes */
</PRE><A NAME="543466"><PRE> PA_set_conversions(TRUE);
</PRE><A NAME="543467"><PRE>
</PRE><A NAME="543468"><PRE> /* set up the physical constants in the external system of units */
</PRE><A NAME="543469"><PRE> PA_physical_constants_ext();
</PRE><A NAME="543470"><PRE>
</PRE><A NAME="543471"><PRE> return;}
</PRE><a name="543472">
<p>
</a>
<a name="543473">
In the above example, pay special attention to the calls to </a>PA_def_units, </a>PA_physical_constants_cgs, </a>PA_set_conversions, and </a>PA_physical_constants_ext. The call to </a>PA_def_units causes PANACEA to define all of its units and initialize the unit and convrsn arrays. The call to PA_physical_constants_cgs initializes the physical constants in CGS units. The call to PA_set_conversions passes over </a>unit and </a>convrsn and makes the entire set of units consistent with the changes made between the PA_def_units call and the </a>PA_set_conversions call. Lastly, the call to </a>PA_physical_constants_ext converts the physical constants to the external system of units.<p>
</a>
<a name="543474">
At this point the initial value problem generator has as consistent set of units and physical constants. If the user changes the systems of units in the input deck, the calls to PA_set_conversions and PA_physical_constants_ext should be repeated to keep every thing consistent.<p>
</a>
<a name="543475">
In the main simulation code everything is taken care of by PANACEA. In the process of reading the state file (restart dump), calls to </a>PA_def_units, PA_set_conversions, and </a>PA_physical_constants_cgs are made by PANACEA. The only difference is that at the end of the process of reading the restart dump, PANACEA calls </a>PA_physical_constants_int to convert the physical constants to the internal system of units.<p>
</a>
<a name="543476">
<h1>9.0 Source Data Handling in PANACEA</h1>
</a>
<a name="543477">
<h1>10.0 The PANACEA Cookbook</h1>
</a>
<a name="543478">
The purpose of this section is to provide some concrete guidance to users who want to get started with PANACEA. The first two subsections describe how to analyze a simulation code with a view to building a new code from scratch or to converting an existing code to use PANACEA services. The last subsection gives extracts of the source code to the PANACEA code system, ABC. The extracts were taken to exemplify the PANACEA interface and to give complete (i.e. with full detail) functions which define PANACEA packages.<p>
</a>
<a name="543479">
<h2>10.1 Building a PANACEA Code System</h2>
</a>
<a name="543480">
The first place to start when building a PANACEA code is at the top. Since PANACEA is a model of a simulation code, the new code should be conceptualized in terms of the PANACEA model.<p>
</a>
<a name="543481">
Break down the simulation into conceptual packages. That is, decide how to best modularize your code system at the level of systems of equations to be simulated. Try to think in terms of giving a package to another code developer so that he or she has everything that is needed to generate, run, and post process data for the package.<p>
</a>
<a name="543482">
Define each variable in terms of type, attributes (RESTART, REQU, etc.), and the package which will own it. PANACEA can perform its services only for variables in the database. Other variables which are temporary, local, or for some other reason do not belong in the database should be identified and allotted to the packages which will handle them.<p>
</a>
<a name="543483">
Decide how to handle issues associated with computational meshes. If feasible plan on putting mesh handling routines (routines that deal only with meshes - no physics) into one global package. Remember that mesh handling includes mesh generation or the facility to link to a mesh generator in the initial value problem generator.<p>
</a>
<a name="543484">
For each identified package do the following steps:<p>
</a>
<A NAME="543485"><B>Eliminate dimensional numeric constants
</B><BR><a name="543486">
Replace dimensional numeric constants with variables whose values are constructed from the fundamental physical constants supplied by PANACEA (or plan on defining additional constants - see the section on Physical Units in PANACEA).<p>
</a>
<a name="543487">
For example, replace an expression such as<p>
</a>
<A NAME="543488"><PRE> x = 2.99e10*t;
</PRE><a name="543489">
with<p>
</a>
<A NAME="543490"><PRE> x = c*t;
</PRE><a name="543491">
When this process is complete, the only numeric constants in the code should be pure numbers, i.e. dimensionless.<p>
</a>
<A NAME="543492"><B>Build a function to define the package variables
</B><BR><a name="543493">
With each package there will be a set of variables which the package owns. A helpful way to identify these is to ask what would be required to hand this package to another code system. Variables will fall into three main classes: RESTART, RUNTIME, and EDIT. The variable dimensions are typically stored in the swtch array for the package for efficiency in handling the state file.<p>
</a>
<a name="543494">
<p>
</a>
<A NAME="543495"><PRE> def_foo(pck)
</PRE><A NAME="543496"><PRE> PA_package *pck;
</PRE><A NAME="543497"><PRE> {P_dim_1 = &swtch[4];
</PRE><A NAME="543498"><PRE> P_dim_2 = &swtch[5];
</PRE><A NAME="543499"><PRE> P_dim_3 = &Two_I;
</PRE><A NAME="543500"><PRE> P_dim_4 = &Three_I;
</PRE><A NAME="543501"><PRE>
</PRE><A NAME="543502"><PRE> /* RESTART VARIABLES */
</PRE><A NAME="543503"><PRE> PA_def_var(“foo_var_1”, SC_INTEGER_S, NULL, NULL,
</PRE><A NAME="543504"><PRE> SCOPE, RESTART, CLASS, OPTL, ATTRIBUTE,
</PRE><A NAME="543505"><PRE> P_dim_1, DIMENSION, UNITS);
</PRE><A NAME="543506"><PRE>
</PRE><A NAME="543507"><PRE> /* RUNTIME VARIABLES */
</PRE><A NAME="543508"><PRE> PA_def_var(“foo_var_2”, SC_DOUBLE_S, NULL, NULL,
</PRE><A NAME="543509"><PRE> ATTRIBUTE,
</PRE><A NAME="543510"><PRE> P_dim_2, P_dim_3, DIMENSION, UNITS);
</PRE><A NAME="543511"><PRE>
</PRE><A NAME="543512"><PRE> /* EDIT VARIABLES */
</PRE><A NAME="543513"><PRE> PA_def_var(“foo_var_3”, SC_INTEGER_S, NULL, NULL,
</PRE><A NAME="543514"><PRE> SCOPE, EDIT, CLASS, PSEUDO, ATTRIBUTE,
</PRE><A NAME="543515"><PRE> P_dim_4, DIMENSION, UNITS);
</PRE><A NAME="543516"><PRE>
</PRE><A NAME="543517"><PRE> return(TRUE);}
</PRE><a name="543518">
<p>
</a>
<a name="543519">
Note: 1) the use of PA_def_var; 2) the way dimensions are handled.<p>
</a>
<A NAME="543520"><B>Build a function to define the controls
</B><BR><a name="543521">
With each package there will be a set of controlling parameters. PANACEA provides for an array of integer parameters, double precision parameters, and ASCII strings associated with each package. This permits efficient handling of these controls and does not hamper the code developer in associating them with named scalar variables.<p>
</a>
<a name="543522">
Define the controls for the package and write the function to allocate them and initialize them.<p>
</a>
<A NAME="543523"><PRE>
</PRE><A NAME="543524"><PRE> cont_foo(pck)
</PRE><A NAME="543525"><PRE> PA_package *pck;
</PRE><A NAME="543526"><PRE> {static int n_names = 2, n_params = 2, n_swtches = 5;
</PRE><A NAME="543527"><PRE>
</PRE><A NAME="543528"><PRE> PA_mk_control(pck, “foo”, n_names, n_params, n_swtches);
</PRE><A NAME="543529"><PRE>
</PRE><A NAME="543530"><PRE> swtch[1] = TRUE; /* main switch - use this package if TRUE */
</PRE><A NAME="543531"><PRE> swtch[2] = 1; /* option #1 */
</PRE><A NAME="543532"><PRE> swtch[3] = 0; /* option #2 */
</PRE><A NAME="543533"><PRE> swtch[4] = 0; /* number of bar_1 values */
</PRE><A NAME="543534"><PRE> swtch[5] = 0; /* number of bar_2 values */
</PRE><A NAME="543535"><PRE>
</PRE><A NAME="543536"><PRE> param[1] = 1.0; /* multiplier 1 */
</PRE><A NAME="543537"><PRE> param[2] = 1.0; /* multiplier 2 */
</PRE><A NAME="543538"><PRE>
</PRE><A NAME="543539"><PRE> return(TRUE);}
</PRE><A NAME="543540"><PRE>
</PRE><a name="543541">
Note: 1) the use of PA_mk_control; and 2) the static integers n_names, n_params and n_swtches which define the length of the swtch, name, and param arrays respectively.<p>
</a>
<A NAME="543542"><B>Build the package initializer function
</B><BR><a name="543543">
This function will be executed once at start up and should connect database variables with local pointers as well as allocating local variables which will endure for the entire simulation run.<p>
</a>
<A NAME="543544"><PRE>
</PRE><A NAME="543545"><PRE> int *loc_var_1;
</PRE><A NAME="543546"><PRE> double *loc_var_2;
</PRE><A NAME="543547"><PRE>
</PRE><A NAME="543548"><PRE> foo_init(pck)
</PRE><A NAME="543549"><PRE> PA_package *pck;
</PRE><A NAME="543550"><PRE> {N_foo_1 = swtch[2];
</PRE><A NAME="543551"><PRE> N_foo_2 = swtch[3];
</PRE><A NAME="543552"><PRE>
</PRE><A NAME="543553"><PRE> /* PA_CONNECT for database variables */
</PRE><A NAME="543554"><PRE> PA_CONNECT(foo_var_1, “variable_1”, int *, TRUE);
</PRE><A NAME="543555"><PRE>
</PRE><A NAME="543556"><PRE> /* MAKE_N for non-database local variables */
</PRE><A NAME="543557"><PRE> loc_var_1 = MAKE_N(int, N_foo_1);
</PRE><A NAME="543558"><PRE> loc_var_2 = MAKE_N(double, N_foo_1*N_foo_2);
</PRE><A NAME="543559"><PRE>
</PRE><A NAME="543560"><PRE> return(TRUE);}
</PRE><A NAME="543561"><PRE>
</PRE><a name="543562">
Note: 1) the use of PA_CONNECT and MAKE_N; and 2) the dimension constants extracted from the swtch array.<p>
</a>
<A NAME="543563"><B>Build a wrapper for the main entry point
</B><BR><a name="543564">
Since many packages will want to vote on the timestep for the next major computational cycle and since it will be useful for most packages to monitor their performance, it will be a good idea to build a wrapper function around the package main entry point. It is also a good place to invoke initializations which occur every time the main entry point is invoked as well as clean up after it has been executed.<p>
</a>
<A NAME="543565"><PRE>
</PRE><A NAME="543566"><PRE> main_foo(pck)
</PRE><A NAME="543567"><PRE> PA_package *pck;
</PRE><A NAME="543568"><PRE> {int foo_z;
</PRE><A NAME="543569"><PRE> double foo_dt;
</PRE><A NAME="543570"><PRE> static int first = TRUE;
</PRE><A NAME="543571"><PRE>
</PRE><A NAME="543572"><PRE> /* check that this package was requested */
</PRE><A NAME="543573"><PRE> if (swtch[1] == FALSE)
</PRE><A NAME="543574"><PRE> return;
</PRE><A NAME="543575"><PRE>
</PRE><A NAME="543576"><PRE> if (first)
</PRE><A NAME="543577"><PRE> pck->space = (double) Ssp_alloc;
</PRE><A NAME="543578"><PRE>
</PRE><A NAME="543579"><PRE> PA_MARK_TIME;
</PRE><A NAME="543580"><PRE>
</PRE><A NAME="543581"><PRE> init_cycle();
</PRE><A NAME="543582"><PRE>
</PRE><A NAME="543583"><PRE> /* do the real work of foo*/
</PRE><A NAME="543584"><PRE> foo_work(&foo_dt, &foo_z);
</PRE><A NAME="543585"><PRE>
</PRE><A NAME="543586"><PRE> /* record the hydro timestep vote */
</PRE><A NAME="543587"><PRE> pck->dt = foo_dt;
</PRE><A NAME="543588"><PRE> pck->dt_zone = foo_z;
</PRE><A NAME="543589"><PRE>
</PRE><A NAME="543590"><PRE> PA_ACCM_TIME(pck->time);
</PRE><A NAME="543591"><PRE>
</PRE><A NAME="543592"><PRE> if (first)
</PRE><A NAME="543593"><PRE> {pck->space = (double) Ssp_alloc - pck->space;
</PRE><A NAME="543594"><PRE> first = FALSE;};
</PRE><A NAME="543595"><PRE>
</PRE><A NAME="543596"><PRE> return;}
</PRE><A NAME="543597"><PRE>
</PRE><a name="543598">
Note: the use of PA_MARK_TIME and PA_ACCM_TIME.<p>
</a>
<a name="543599">
The above list covers the main simulation code. Most simulation codes will need to have some means of building initial state files (restart dumps). This means writing the following additional routines for the initial value problem generator code:<p>
</a>
<a name="543600">
<p>
</a>
<A NAME="543601"><B>Build functions to handle each command
</B><BR><a name="543602">
Each input command that the initial value problem generator will have to parse requires a function which does the actual parsing and takes the appropriate actions. One function may handle many different commands, but it is best to keep the functions simple and that usually makes the correspondence between commands and functions one to one. For an existing code, the coding for these routines probably already exists but may have to be reorganized.<p>
</a>
<A NAME="543603"><PRE>
</PRE><A NAME="543604"><PRE> void command_1h()
</PRE><A NAME="543605"><PRE> {char *token_1, *token_2;
</PRE><A NAME="543606"><PRE> int i1, i2;
</PRE><A NAME="543607"><PRE>
</PRE><A NAME="543608"><PRE> token_1 = PA_get_field(“TOKEN_1”, “COMMAND_1”, REQU);
</PRE><A NAME="543609"><PRE> token_2 = PA_get_field(“TOKEN_2”, “COMMAND_1”, REQU);
</PRE><A NAME="543610"><PRE>
</PRE><A NAME="543611"><PRE> i1 = PA_stoi(PA_get_field(“INTEGER_1”, “COMMAND_1”, REQU));
</PRE><A NAME="543612"><PRE> i2 = PA_stoi(PA_get_field(“INTEGER_2”, “COMMAND_1”, REQU));
</PRE><A NAME="543613"><PRE>
</PRE><A NAME="543614"><PRE> N_foo_1 = i1;
</PRE><A NAME="543615"><PRE> N_foo_2 = i1*i2;
</PRE><A NAME="543616"><PRE>
</PRE><A NAME="543617"><PRE> return;}
</PRE><A NAME="543618"><PRE>
</PRE><a name="543619">
Note: the use of PA_get_field and PA_stoi.<p>
</a>
<A NAME="543620"><B>Build a function which installs the commands
</B><BR><a name="543621">
Not all packages require specific generator commands. The generic commands supplied by PANACEA may be sufficient. However, if commands have been defined in the previous step they must be made known to PANACEA. All commands are installed in a hash table which is used by PANACEA to process ASCII input files or interactive commands.<p>
</a>
<a name="543622">
<p>
</a>
<A NAME="543623"><PRE> foo_cmmnds()
</PRE><A NAME="543624"><PRE> {PA_inst_c(“command_1”, NULL, FALSE, 0, command_1h,
</PRE><A NAME="543625"><PRE> PA_zargs, commands);
</PRE><A NAME="543626"><PRE>
</PRE><A NAME="543627"><PRE> /* optionally initialize some constants */
</PRE><A NAME="543628"><PRE> N_foo_1 = 0;
</PRE><A NAME="543629"><PRE> N_foo_2 = 0;
</PRE><A NAME="543630"><PRE>
</PRE><A NAME="543631"><PRE> return;}
</PRE><A NAME="543632"><PRE>
</PRE><a name="543633">
Note: the use of PA_inst_c and the reference to the function command_1h.<p>
</a>
<A NAME="543634"><B>Build a function to intern the package variable in the database
</B><BR><a name="543635">
Before a state (restart) dump can be made two things must happen. First, the data read in from the input deck must be transformed into data structures usable by the simulation routines. Second, those data structures must be made available to the database, a process called interning. A function is supplied by the code developer whose responsibility is to ensure that the package’s contribution to the database is complete and ready to be dumped.<p>
</a>
<a name="543636">
<p>
</a>
<A NAME="543637"><PRE> intern_foo()
</PRE><A NAME="543638"><PRE> {
</PRE><A NAME="543639"><PRE> swtch[4] = N_foo_1;
</PRE><A NAME="543640"><PRE> swtch[5] = N_foo_2;
</PRE><A NAME="543641"><PRE>
</PRE><A NAME="543642"><PRE> PA_INTERN(foo_var_1, “variable_1”, int);
</PRE><A NAME="543643"><PRE>
</PRE><A NAME="543644"><PRE> return;}
</PRE><a name="543645">
Note: 1) the use of PA_INTERN; and 2) the setting of the control array values (here swtch).<p>
</a>
<a name="543646">
<p>
</a>
<a name="543647">
With this done the only remaining task is to produce the counterparts to A.C, the source file which contains the main entry point for the initial value generator program, and B.C, the source file which contains the main entry point for the run time simulation program. Whether they are written in C or FORTRAN is immaterial. Fundamentally, they define the packages for the code system, initialize everything (or have PANACEA do it), read the input, pass control to whatever routines coordinate the main activity of the code, and do the appropriate clean up at the end.<p>
</a>
<a name="543648">
<p>
</a>
<A NAME="543649"><B>Install the package in the generator code
</B><BR><a name="543650">
Make the foo package known to the PANACEA initial value problem generator code, A.<p>
</a>
<A NAME="543651"><PRE>
</PRE><A NAME="543652"><PRE> PA_gen_package(“foo”, foo_cmmnds, NULL, NULL, def_foo,
</PRE><A NAME="543653"><PRE> cont_foo, intern_foo);
</PRE><a name="543654">
<p>
</a>
<A NAME="543655"><B>Install the foo package in the simulation code
</B><BR><a name="543656">
Make the foo package known to the PANACEA main simulation code, B.<p>
</a>
<A NAME="543657"><PRE>
</PRE><A NAME="543658"><PRE> PA_run_time_package(“foo”, NULL, NULL, def_foo, cont_foo,
</PRE><A NAME="543659"><PRE> init_foo, main_foo, NULL, NULL);
</PRE><a name="543660">
This may seem like quite a lot of work. For an existing code, in some sense it is akin to starting over and building a new code, but the big advantage is that most of the coding already exists, has been tested, and has a base of test input problems. On the other hand, the payoff can be quite large rather quickly. The output data for the code will be completely portable. There is at least one existing system for visualizing the data produced which is very flexible and available on all sorts of computer platforms. Furthermore, for code systems which share the same computational meshes, there may be readily available routines that will provide interim or permanent capabilities (mesh generators, common packages, etc.).<p>
</a>
<a name="543661">
<h2>10.2 The Monolithic Approach</h2>
</a>
<a name="543662">
One way to approach converting an existing code system into a PANACEA code system is to start by viewing the entire simulation code as a single, global package. The advantage is that a few relatively simple pieces of interface coding will get the conversion going fairly quickly. Since there will be small amounts of interface coding, the connections to PANACEA services can be written one by one and tested before proceeding. The entire process becomes more of an evolutionary one than a major code rewrite exercise.<p>
</a>
<a name="543663">
The basic steps are the same as outlined in the previous section. The advantage is that each of those steps only has to be done once (to start with).<p>
</a>
<a name="543664">
Once the monolithic code is running reliably, the smaller more modular packages can be extracted from the original global package. This process amounts to splitting the monolithic interface apart into a series of smaller interfaces. Once all of the identifiable packages have been extracted from the original monolithic package, the remainder should be a fairly natural PANACEA style global package.<p>
</a>
<a name="543665">
<h2>10.3 ABC: A PANACEA Code</h2>
</a>
<a name="543666">
ABC is a simple 2d hydrodynamics code which shows how a PANACEA code system is structured. The A code is an initial value problem generator, the B code is the main simulation code, and the C code is a post processing code which transforms PANACEA output files for a particular visualization system.<p>
</a>
<a name="543667">
Although ABC was constructed solely as a test of PANACEA, it still illustrates some of the important points that must be addressed when building a PANACEA code. The construction of a PANACEA package is logically the same whether the entire package is being built from scratch or whether an existing package is being turned into a PANACEA package.<p>
</a>
<a name="543668">
The parts of the source to ABC which should provide helpful examples of the material documented in this manual are given here. The actual code for ABC is available and interested readers can contact the author for copies of it.<p>
</a>
<a name="543347">
<h1>11.0 TOUL</h1>
</a>
<a name="544236">
TOUL is a stand alone utility to transpose time history files written by PANACEA into a family of ULTRA files. <p>
</a>
<a name="544237">
A </a>family of time history files is conventionally named<p>
</a>
<A NAME="544297"><PRE> name.tdd
</PRE><a name="544330">
where name is the base file name and dd are base 36 digits (0-9a-z).<p>
</a>
<a name="544331">
The resulting </a>family of ULTRA files will be named<p>
</a>
<A NAME="544332"><PRE> name.udd
</PRE><a name="544333">
Its usage is:<p>
</a>
<A NAME="544334">toul [-d] [-h] [+/-o] [-f files | -l files | base]
<P><A NAME="544335"> -d Turn on debug mode for memory info
<P><A NAME="544336"> -f Use explicitly specified TH files
<P><A NAME="544337"> -h Print this help message and exit
<P><A NAME="544338"> -l Use internal links in TH files
<P><A NAME="544339"> +o Process TH files in the order specified (default)
<P><A NAME="544340"> -o Process TH files in reverse order
<P><a name="544341">
See the discussions of </a>PA_th_trans_link, </a>PA_th_trans_name, </a>PATRNL, and </a>PATRNN for additional information regarding the -f, -l, -o, and +o options.<p>
</a>
<a name="544342">
There are a few distinct modes of using TOUL.<p>
</a>
<a name="544343">
First, if you have a complete set of time history files with a single base name, you can supply the base name to TOUL. For example, suppose you have a set of time history files foo.t00 through foo.t1s. You can type:<p>
</a>
<A NAME="544344">toul foo
<P><a name="544345">
This will result in a family of ULTRA files beginning with foo.u00.<p>
</a>
<a name="544346">
Second, you may have a family of files from which some are missing or because of a restart you may have a different base name for some files in the family. You can use the -l option in such cases. For example, suppose that files foo.t09 through foo.t12 are missing in the previous example. You can type:<p>
</a>
<A NAME="544347">toul -l foo.t1s foo.t08
<P><a name="544348">
The curves in the resulting ULTRA files will have a gap corresponding to the missing data from foo.t09 through foo.t12.<p>
</a>
<a name="544349">
Third, you may wish to transpose an explicit set of file. You can use the -f option to accomplish this. For example, suppose that you just want to see the data from foo.t1e through foo.t1g in the ongoing example. You can type:<p>
</a>
<A NAME="544350">toul -f foo.t1e foo.t1f foo.t1g
<P><a name="544452">
Because this is the most general level on which you can approach the transposition process, the resulting curves in the ULTRA files can look a little strange. You may have to get used to the gaps that might result from pieces of data widely spaced in time.<p>
</a>
<a name="543669">
<h1>12.0 PANACHE</h1>
</a>
<a name="543670">
PANACHE is a tool to automate the process of building interface coding between numerical simulation code packages and PANACEA. PANACHE does this by processing a dictionary which contains compact and concise descriptions of variables, functions, commands, and actions.<p>
</a>
<a name="543671">
A dictionary contains three basic kinds of information: global code system declarations; one or more package descriptions; and directives for generating and possibly compiling the code system.<p>
</a>
<a name="543672">
When the dictionary has been read in and processed, PANACHE will generate: for each package defined, the interface between the package and PANACEA; and the module(s) which contain the main routine(s) and some related high level control functions.<p>
</a>
<a name="543673">
The code generated this way can be compiled and linked with the simulation packages into the component parts of a simulation code system (generator and simulation codes or a combined code).<p>
</a>
<a name="543674">
Certain conventions are used for sake of clarity.<p>
</a>
<A NAME="543675"><PRE> [...]* means zero or more of the items in the brackets
</PRE><A NAME="543676"><PRE> [...]+ means one or more of the items in the brackets
</PRE><A NAME="543677"><PRE> The following variables are pre-defined in PANACHE:
</PRE><A NAME="543678"><PRE> </a>NULL - used to indicate a null pointer (ala NULL in C).
</PRE><a name="543679">
<h2>12.1 </a>Commands</h2>
</a>
<a name="543680">
This section describes the commands which PANACHE understands. It uses these commands to build up an internal view of the simulation code system as well as the package interfaces. A set of such commands defining a code system and its interface is called a </a>dictionary.<p>
</a>
<a name="543681">
<h3>12.1.1 </a>Global Definition Commands</h3>
</a>
<a name="543682">
These commands define information that is not particular to a single package but is global to the entire simulation system.<p>
</a>
<a name="543683">
PANACEA contains various routines which can control a simulation. These routines do NOT purport to be completely general. They are however fairly general and in any case can be used as templates for code systems which need to do something different. PANACHE will let you use these generic routines if you supply certain information.<p>
</a>
<a name="543684">
The system scalars define the time step controls used by the high level PANACEA simulation managers. The system files define the naming of state files, post-processor files, edit files, and PVA files. <p>
</a>
<a name="543685">
The system variables are REQUIRED if you do not specify your own simulation manager routines. If you want to use your own routines, you must specify one of the following two sets of system functions:<p>
</a>
<A NAME="543686"><PRE> “generator-init-problem”
</PRE><A NAME="543687"><PRE> “simulation-init-problem”
</PRE><A NAME="543688"><PRE> “simulation-run-problem”
</PRE><A NAME="543689"><PRE> “simulation-fin-problem”
</PRE><a name="543690">
or<p>
</a>
<A NAME="543691"><PRE> “combined-init-problem”
</PRE><A NAME="543692"><PRE> “combined-run-problem”
</PRE><A NAME="543693"><PRE> “combined-fin-problem”
</PRE><a name="543694">
<p>
</a>
<A NAME="543695"><BR><B></a>system-scalars
</B><BR><a name="543696">
Specify scalar variables which contain global information required by PANACEA.<p>
</a>
<A NAME="543697"><I>Usage: </I>(system-scalars
<P><A NAME="543698"> t ; system time
<P><A NAME="543699"> tstart ; system start time
<P><A NAME="543700"> tstop ; system stop time
<P><A NAME="543701"> dtf ; system time step fraction
<P><A NAME="543702"> dtfmin ; minimum time step fraction
<P><A NAME="543703"> dtfmax ; maximum time step fraction
<P><A NAME="543704"> dtfinc ; maximum time step fractional increase
<P><A NAME="543705"> cycle ; system time cycle number
<P><A NAME="543706"> nzones) ; number of computational units (zones)
<P><A NAME="543707"><BR><B></a>system-files
</B><BR><a name="543708">
Specify ASCII variables which contain the names of files used by PANACEA.<p>
</a>
<A NAME="543709"><I>Usage: </I>(system-files
<P><A NAME="543710"> sfname ; state file name
<P><A NAME="543711"> edname ; edit file name
<P><A NAME="543712"> ppname ; pp file name
<P><A NAME="543713"> pvname) ; PVA file name
<P><A NAME="543714"><BR><B></a>system-functions
</B><BR><a name="543715">
Specify functions which PANACEA will call under certain conditions. Each function is paired with a name. All pairs are optional, but functions must be paired with the names. The current meaningful names for PANACEA are:<p>
</a>
<A NAME="543716">“</a>generator-init-problem”
<P><A NAME="543717">“</a>simulation-init-problem”
<P><A NAME="543718">“</a>simulation-run-problem”
<P><A NAME="543719">“</a>simulation-fin-problem”
<P><A NAME="543720">“</a>combined-init-problem”
<P><A NAME="543721">“</a>combined-run-problem”
<P><A NAME="543722">“</a>combined-fin-problem”
<P><A NAME="543723">“</a>generator-termination”
<P><A NAME="543724">“</a>simulation-termination”
<P><A NAME="543725">“</a>interrupt-handler”
<P><A NAME="543726">“</a>generator-error-handler”
<P><A NAME="543727">“</a>region-name-to-index”
<P><A NAME="543728">“</a>pre-intern”
<P><A NAME="543729">“</a>domain-builder”
<P><A NAME="543730">“</a>mapping-builder”
<P><a name="543731">
Only specified functions can be called. PANACEA doesn’t attempt to call it if you don’t define it. Any functions used here that are not PANACEA functions (PANACEA functions all begin with ‘PA_’ or ‘_PA_’) must be declared in a </a>declare-function statement.<p>
</a>
<A NAME="543732"><I>Usage: </I>(system-functions [name function]+)
<P><A NAME="543733"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543734"> “generator-termination” global_end_graphics
<P><A NAME="543735"> “simulation-termination” B_term
<P><A NAME="543736"> “interrupt-handler” PA_interrupt_handler
<P><A NAME="543737"> “generator-error-handler” A_gen_err
<P><A NAME="543738"> “region-name-to-index” part_reg
<P><A NAME="543739"> “pre-intern” load_reg
<P><A NAME="543740"> “domain-builder” LR_build_domain
<P><A NAME="543741"> “mapping-builder” LR_build_mapping)
<P><a name="543742">
<h3>12.1.2 </a>Package Definition Commands</h3>
</a>
<a name="543743">
These commands are used for specifying package level details of the interface between PANACEA and the simulation package.<p>
</a>
<A NAME="543744"><BR><B></a>command
</B><BR><a name="543745">
Defines generator commands.<p>
</a>
<A NAME="543746"><I>Usage: </I>(command [name spec]+)
<P><A NAME="543747"> spec := function handler |
<P><A NAME="543748"> type array index
<P><A NAME="543749"> type := integer | real | string
<P><a name="543750">
The second form of spec allows an application to name an element of an array as a command which sets the value of the element.<p>
</a>
<A NAME="543751"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543752"> side sideh PA_zargs
<P><A NAME="543753"> dimension integer swtch 1)
<P><A NAME="543754"><BR><B></a>control
</B><BR><a name="543755">
Defines PANACEA control items.<p>
</a>
<A NAME="543756"><I>Usage: </I>(control [type index val comment]+)
<P><A NAME="543757"> type := ascii | integer | real
<P><A NAME="543758"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543759"> real 1 0.0 “current problem time (internal units)”
<P><A NAME="543760"> ascii 8 </a>NULL “input deck name (ASCII)”
<P><A NAME="543761"> integer 14 0 “generation time mesh dumps if TRUE”)
<P><A NAME="543762"><BR><B></a>declare-function
</B><BR><a name="543763">
Declare one or more functions pertaining to the package. These functions may be ones that are defined in hand coded routines but need to be referenced in generated code. They may also be given so that a complete package header can be generated. At this writing declarations involving pointers must be enclosed in quotes.<p>
</a>
<A NAME="543764"><I>Usage: </I>(declare-function [function-spec]+)
<P><A NAME="543765"> function-spec := type name arg-list
<P><A NAME="543766"> arg-list := (arg*)
<P><A NAME="543767"> arg := “type [‘*‘]*name”
<P><A NAME="543768"> type := any defined type (e.g. double)
<P><A NAME="543769">
<P><A NAME="543770"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543771"> void load_reg ()
<P><A NAME="543772"> “char *” foo (“int s” “double t”)
<P><A NAME="543773"><BR><B></a>declare-variable
</B><BR><a name="543774">
Declare one or more variables pertaining to the package. These variables may be ones that are referenced in hand coded routines but need to be referenced and or defined in generate code. They may also be given so that a complete package header can be generated. At this writing declarations involving pointers must be enclosed in quotes.<p>
</a>
<a name="543775">
NOTE: these are NOT database variable definitions, see </a>def-var for that purpose. These are variables which the compiler must be able to correctly understand. Database variables are created at run time and are mainly irrelevant to the compiler.<p>
</a>
<A NAME="543776"><I>Usage: </I>(declare-variable [variable-spec]+)
<P><A NAME="543777"> variable-spec := [class] type name dims initial-value
<P><A NAME="543778"> class := static | extern | const
<P><A NAME="543779"> type := any defined type (e.g. double)
<P><A NAME="543780"> dims := ()
<P><A NAME="543781"> initial-value := number
<P><A NAME="543782">
<P><A NAME="543783"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543784"> double bar ()
<P><A NAME="543785"> static int foo 3)
<P><A NAME="543786"><BR><B></a>def-var
</B><BR><a name="543787">
Define one or more database variables.<p>
</a>
<A NAME="543788"><I>Usage: </I>(def-var variable-spec type
<P><A NAME="543789"> mesh-spec
<P><A NAME="543790"> [attribute-list
<P><A NAME="543791"> [unit-list
<P><A NAME="543792"> [init-val
<P><A NAME="543793"> [init-fnc
<P><A NAME="543794"> [data-pointer]]]]])
<P><A NAME="543795">
<P><A NAME="543796"> variable-spec := variable | ([variable]+)
<P><A NAME="543797"> type := any defined type (e.g. double)
<P><A NAME="543798"> mesh-spec := mesh | ([mesh]+)
<P><A NAME="543799"> attribute-list := [attribute]*
<P><A NAME="543800"> attribute := scope | class | persist |
<P><A NAME="543801"> allocation | center
<P><A NAME="543802"> scope := restart | runtime | demand | edit | defn
<P><A NAME="543803"> class := requ | optl | pseudo
<P><A NAME="543804"> persist := keep | cache-f | cache-r | rel
<P><A NAME="543805"> allocation := static | dynamic
<P><A NAME="543806"> center := zone | node | edge | face | un-centered
<P><A NAME="543807">
<P><A NAME="543808"> unit-list := (unit*)
<P><A NAME="543809"> unit := user-defined-unit | per |
<P><A NAME="543810"> rad | ster | mole | Q | cm | sec | g |
<P><A NAME="543811"> eV | K | erg | cc
<P><A NAME="543812"> init-val := a declare-variable’d name
<P><A NAME="543813"> init-fnc := a declare-function’d name
<P><A NAME="543814"> data-pointer := a declare-variable’d name
<P><A NAME="543815">
<P><A NAME="543816"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543817"> (def-var lindex long spatial (restart))
<P><A NAME="543818"> (def-var knob-a integer ()
<P><A NAME="543819"> (restart static)
<P><A NAME="543820"> ()
<P><A NAME="543821"> kav () knoba)
<P><A NAME="543822"> (def-var cache-f-4 double spatial
<P><A NAME="543823"> (restart cache-r zone)
<P><A NAME="543824"> (K)
<P><A NAME="543825"> pi)
<P><A NAME="543826"><BR><B></a>generate
</B><BR><a name="543827">
Causes PANACHE to generate compilable code from the currently defined dictionary.<p>
</a>
<A NAME="543828"><I>Usage: </I>(generate language type name1 [name2])
<P><A NAME="545024"> language := C | C++ | F77
<P><A NAME="545025"> type := + | -
<P><a name="543830">
The language argument allows the user to specify the target language of the generated code. At this time only C and C++ are support. Plans are for future versions to produce Fortran77 code. If type is ‘+’ use SX extensions; and if ‘-’ use PANACEA only. The argument name1 is the name of the generator code if name2 is also given; otherwise it is the name of the combined code. name2 is the name of the simulation code if given. Two names implies two codes and one name implies a combined code.<p>
</a>
<A NAME="543831"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543832"> (generate C - fubar)
<P><A NAME="543833"> (generate C++ + a b)
<P><A NAME="543834"> (generate C++ - a b)
<P><A NAME="543835"><BR><B></a>include
</B><BR><a name="545026">
Specify one or more header files to be included by the header for the current package.<p>
</a>
<A NAME="545027"><I>Usage: </I>(include [file]*)
<P><a name="545028">
The files are the literal names of header files which the preprocessor must be able to find as specified.<p>
</a>
<A NAME="545029"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543829"><BR><B></a>mesh
</B><BR><a name="543836">
Define a mesh for the package. A mesh here corresponds to an array dimension.<p>
</a>
<A NAME="543837"><I>Usage: </I>(mesh [mesh-spec]+)
<P><A NAME="543838"> mesh-spec := name variable
<P><A NAME="543839">
<P><A NAME="543840"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543841"><BR><B></a>package
</B><BR><a name="543842">
Begins the definition of the named package. The definition continues until the next package command or until a generate command. The package name must be a legal C or Fortran identifier since it will be used to generate function and variable names.<p>
</a>
<A NAME="543843"><I>Usage: </I>(package name)
<P><A NAME="543844"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543845"><BR><B></a>package-functions
</B><BR><a name="543846">
Defines the package functions that will be called by PANACEA. The following list shows all of the package functions available in PANACEA:<p>
</a>
<a name="543847">
“</a>install-generator-commands”<p>
</a>
<a name="543848">
“</a>install-type-definitions”<p>
</a>
<a name="543849">
“</a>intern-variables”<p>
</a>
<a name="543850">
“</a>define-units”<p>
</a>
<a name="543851">
“</a>define-variables”<p>
</a>
<a name="543852">
“</a>define-controls”<p>
</a>
<a name="543853">
“</a>initialize”<p>
</a>
<a name="543854">
“</a>main-entry”<p>
</a>
<a name="543855">
“</a>post-process-output”<p>
</a>
<a name="543856">
“</a>finish”<p>
</a>
<a name="543857">
“</a>install-pp-commands”<p>
</a>
<a name="543858">
As with the </a>system-function command, package functions must be paired with the name by which PANACHE knows them. Functions which PANACHE will generate need not be defined this way since PANACHE will implicitly define them.<p>
</a>
<A NAME="543859"><I>Usage: </I>(package-functions [name function ... ])
<P><A NAME="543860"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543861"> “intern-variables” global_intern
<P><A NAME="543862"> “initialize” global_init
<P><A NAME="543863"> “main-entry” global_main)
<P><A NAME="543864"><BR><B></a>typedef
</B><BR><a name="543865">
Define a </a>structured data type. Database variables may be declared to be of any type (or any depth of </a>pointers) which is either </a>primitive or typedef’d. The primitive types are: </a>char, </a>short, </a>int, </a>long, </a>float, </a>double. Pointers are denoted with *’s as in C.<p>
</a>
<A NAME="543866"><I>Usage: </I>(typedef name [member]+)
<P><A NAME="543867"> member := “type [*]*member_name”
<P><A NAME="543868"> type := any defined type (e.g. double)
<P><A NAME="543869"><I>EXAMPLE: </I><PRE></PRE><BR><A NAME="543870"> “int *a”
<P><A NAME="543871"> “double b”)
<P><a name="543872">
<h2>12.2 Example: ABC Dictionary</h2>
</a>
<a name="543873">
In this section we present a sample dictionary. This dictionary generates the interface coding for the ABC PANACEA test code. The actual listing is broken down into sections to allow for discussion.<p>
</a>
<a name="543874">
<h3>12.2.1 The ABC System Information</h3>
</a>
<a name="543875">
In many PANACEA codes there is some information about the entire code system which does not belong to any one package. Global time information is one example. The system of file families managed by PANACEA is another. At this point, this information is required to generate coding for the main routines where the A and B (or the combined AB code) start up.<p>
</a>
<a name="543876">
<p>
</a>
<A NAME="543877"><CODE></CODE><A NAME="543878"><CODE></CODE><A NAME="543879"><CODE></CODE><A NAME="543880"><CODE></CODE><A NAME="543881"><CODE></CODE><A NAME="543882"><CODE></CODE><A NAME="543883"><CODE></CODE><A NAME="543884"><CODE></CODE><A NAME="543885"><CODE></CODE><A NAME="543886"><CODE></CODE><A NAME="543887"><CODE></CODE><A NAME="543888"><CODE></CODE><A NAME="543889"><CODE></CODE><A NAME="543890"><CODE></CODE><A NAME="543891"><CODE></CODE><A NAME="543892"><CODE></CODE><A NAME="543893"><CODE></CODE><A NAME="543894"><CODE></CODE><A NAME="543895"><CODE></CODE><A NAME="543896"><CODE></CODE><A NAME="543897"><CODE></CODE><A NAME="543898"><CODE></CODE><A NAME="543899"><CODE></CODE><A NAME="543900"><CODE></CODE><A NAME="543901"><CODE></CODE><A NAME="543902"><CODE></CODE><A NAME="543903"><CODE></CODE><A NAME="543904"><CODE></CODE><A NAME="543905"><CODE></CODE><A NAME="543906"><CODE></CODE><A NAME="543907"><CODE></CODE><A NAME="543908"><CODE></CODE><A NAME="543909"><CODE></CODE><A NAME="543910"><CODE></CODE><A NAME="543911"><CODE></CODE><A NAME="543912"><CODE></CODE><A NAME="543913"><CODE></CODE><A NAME="543914"><CODE></CODE><A NAME="543915"><CODE></CODE><A NAME="543916"><CODE></CODE><A NAME="543917"><CODE></CODE><A NAME="543918"><CODE></CODE><a name="543919">
<h3>12.2.2 The ABC Global Package</h3>
</a>
<a name="543920">
The global package in the PANACEA model has a special place in that it may provide for a computational mesh or some other central activity. This package provides a 2d mesh generator for the 2d hydrodynamics package in the next section.<p>
</a>
<a name="543921">
<p>
</a>
<A NAME="543922"><CODE></CODE><A NAME="543923"><CODE></CODE><A NAME="543924"><CODE></CODE><A NAME="543925"><CODE></CODE><A NAME="543926"><CODE></CODE><A NAME="543927"><CODE></CODE><A NAME="543928"><CODE></CODE><A NAME="543929"><CODE></CODE><A NAME="543930"><CODE></CODE><A NAME="543931"><CODE></CODE><A NAME="543932"><CODE></CODE><A NAME="543933"><CODE></CODE><A NAME="543934"><CODE></CODE><A NAME="543935"><CODE></CODE><A NAME="543936"><CODE></CODE><A NAME="543937"><CODE></CODE><A NAME="543938"><CODE></CODE><A NAME="543939"><CODE></CODE><A NAME="543940"><CODE></CODE><A NAME="543941"><CODE></CODE><A NAME="543942"><CODE></CODE><A NAME="543943"><CODE></CODE><A NAME="543944"><CODE></CODE><A NAME="543945"><CODE></CODE><A NAME="543946"><CODE></CODE><A NAME="543947"><CODE></CODE><A NAME="543948"><CODE></CODE><A NAME="543949"><CODE></CODE><A NAME="543950"><CODE></CODE><A NAME="543951"><CODE></CODE><A NAME="543952"><CODE></CODE><A NAME="543953"><CODE></CODE><A NAME="543954"><CODE></CODE><A NAME="543955"><CODE></CODE><A NAME="543956"><CODE></CODE><A NAME="543957"><CODE></CODE><A NAME="543958"><CODE></CODE><A NAME="543959"><CODE></CODE><A NAME="543960"><CODE></CODE><A NAME="543961"><CODE></CODE><A NAME="543962"><CODE></CODE><A NAME="543963"><CODE></CODE><A NAME="543964"><CODE></CODE><A NAME="543965"><CODE></CODE><A NAME="543966"><CODE></CODE><A NAME="543967"><CODE></CODE><A NAME="543968"><CODE></CODE><A NAME="543969"><CODE></CODE><A NAME="543970"><CODE></CODE><A NAME="543971"><CODE></CODE><A NAME="543972"><CODE></CODE><A NAME="543973"><CODE></CODE><A NAME="543974"><CODE></CODE><A NAME="543975"><CODE></CODE><A NAME="543976"><CODE></CODE><A NAME="543977"><CODE></CODE><A NAME="543978"><CODE></CODE><A NAME="543979"><CODE></CODE><A NAME="543980"><CODE></CODE><A NAME="543981"><CODE></CODE><A NAME="543982"><CODE></CODE><A NAME="543983"><CODE></CODE><A NAME="543984"><CODE></CODE><A NAME="543985"><CODE></CODE><A NAME="543986"><CODE></CODE><A NAME="543987"><CODE></CODE><A NAME="543988"><CODE></CODE><A NAME="543989"><CODE></CODE><A NAME="543990"><CODE></CODE><A NAME="543991"><CODE></CODE><A NAME="543992"><CODE></CODE><A NAME="543993"><CODE></CODE><A NAME="543994"><CODE></CODE><A NAME="543995"><CODE></CODE><A NAME="543996"><CODE></CODE><A NAME="543997"><CODE></CODE><A NAME="543998"><CODE></CODE><A NAME="543999"><CODE></CODE><A NAME="544000"><CODE></CODE><A NAME="544001"><CODE></CODE><A NAME="544002"><CODE></CODE><A NAME="544003"><CODE></CODE><A NAME="544004"><CODE></CODE><A NAME="544005"><CODE></CODE><A NAME="544006"><CODE></CODE><A NAME="544007"><CODE></CODE><A NAME="544008"><CODE></CODE><A NAME="544009"><CODE></CODE><A NAME="544010"><CODE></CODE><A NAME="544011"><CODE></CODE><A NAME="544012"><CODE></CODE><A NAME="544013"><CODE></CODE><A NAME="544014"><CODE></CODE><A NAME="544015"><CODE></CODE><A NAME="544016"><CODE></CODE><A NAME="544017"><CODE></CODE><A NAME="544018"><CODE></CODE><A NAME="544019"><CODE></CODE><A NAME="544020"><CODE></CODE><A NAME="544021"><CODE></CODE><A NAME="544022"><CODE></CODE><A NAME="544023"><CODE></CODE><a name="544024">
<h3>12.2.3 The ABC Hydro Package</h3>
</a>
<a name="544025">
The ABC hydro package is a simple 2d hydro package which does actual hydrodynamics so that certain meaningful tests of PANACEA can be carried out (especially regarding post processing and package control functions).<p>
</a>
<a name="544026">
<p>
</a>
<A NAME="544027"><CODE></CODE><A NAME="544028"><CODE></CODE><A NAME="544029"><CODE></CODE><A NAME="544030"><CODE></CODE><A NAME="544031"><CODE></CODE><A NAME="544032"><CODE></CODE><A NAME="544033"><CODE></CODE><A NAME="544034"><CODE></CODE><A NAME="544035"><CODE></CODE><A NAME="544036"><CODE></CODE><A NAME="544037"><CODE></CODE><A NAME="544038"><CODE></CODE><A NAME="544039"><CODE></CODE><A NAME="544040"><CODE></CODE><A NAME="544041"><CODE></CODE><A NAME="544042"><CODE></CODE><A NAME="544043"><CODE></CODE><A NAME="544044"><CODE></CODE><A NAME="544045"><CODE></CODE><A NAME="544046"><CODE></CODE><A NAME="544047"><CODE></CODE><A NAME="544048"><CODE></CODE><A NAME="544049"><CODE></CODE><A NAME="544050"><CODE></CODE><A NAME="544051"><CODE></CODE><A NAME="544052"><CODE></CODE><A NAME="544053"><CODE></CODE><A NAME="544054"><CODE></CODE><A NAME="544055"><CODE></CODE><A NAME="544056"><CODE></CODE><A NAME="544057"><CODE></CODE><A NAME="544058"><CODE></CODE><A NAME="544059"><CODE></CODE><A NAME="544060"><CODE></CODE><A NAME="544061"><CODE></CODE><A NAME="544062"><CODE></CODE><A NAME="544063"><CODE></CODE><A NAME="544064"><CODE></CODE><A NAME="544065"><CODE></CODE><A NAME="544066"><CODE></CODE><A NAME="544067"><CODE></CODE><A NAME="544068"><CODE></CODE><A NAME="544069"><CODE></CODE><A NAME="544070"><CODE></CODE><A NAME="544071"><CODE></CODE><A NAME="544072"><CODE></CODE><A NAME="544073"><CODE></CODE><A NAME="544074"><CODE></CODE><a name="544075">
<h3>12.2.4 The ABC Miscellaneous Package</h3>
</a>
<a name="544076">
This package is used to test various facets of PANACEA functionality. It has almost no significance as far as a simulation goes. It demonstrates more of the ways in which the dictionary defining function of PANACHE can be used.<p>
</a>
<a name="544077">
<p>
</a>
<A NAME="544078"><CODE></CODE><A NAME="544079"><CODE></CODE><A NAME="544080"><CODE></CODE><A NAME="544081"><CODE></CODE><A NAME="544082"><CODE></CODE><A NAME="544083"><CODE></CODE><A NAME="544084"><CODE></CODE><A NAME="544085"><CODE></CODE><A NAME="544086"><CODE></CODE><A NAME="544087"><CODE></CODE><A NAME="544088"><CODE></CODE><A NAME="544089"><CODE></CODE><A NAME="544090"><CODE></CODE><A NAME="544091"><CODE></CODE><A NAME="544092"><CODE></CODE><A NAME="544093"><CODE></CODE><A NAME="544094"><CODE></CODE><A NAME="544095"><CODE></CODE><A NAME="544096"><CODE></CODE><A NAME="544097"><CODE></CODE><A NAME="544098"><CODE></CODE><A NAME="544099"><CODE></CODE><A NAME="544100"><CODE></CODE><A NAME="544101"><CODE></CODE><A NAME="544102"><CODE></CODE><A NAME="544103"><CODE></CODE><A NAME="544104"><CODE></CODE><A NAME="544105"><CODE></CODE><A NAME="544106"><CODE></CODE><A NAME="544107"><CODE></CODE><A NAME="544108"><CODE></CODE><A NAME="544109"><CODE></CODE><A NAME="544110"><CODE></CODE><A NAME="544111"><CODE></CODE><A NAME="544112"><CODE></CODE><A NAME="544113"><CODE></CODE><A NAME="544114"><CODE></CODE><A NAME="544115"><CODE></CODE><A NAME="544116"><CODE></CODE><A NAME="544117"><CODE></CODE><A NAME="544118"><CODE></CODE><A NAME="544119"><CODE></CODE><A NAME="544120"><CODE></CODE><A NAME="544121"><CODE></CODE><A NAME="544122"><CODE></CODE><A NAME="544123"><CODE></CODE><A NAME="544124"><CODE></CODE><A NAME="544125"><CODE></CODE><A NAME="544126"><CODE></CODE><A NAME="544127"><CODE></CODE><A NAME="544128"><CODE></CODE><A NAME="544129"><CODE></CODE><A NAME="544130"><CODE></CODE><A NAME="544131"><CODE></CODE><A NAME="544132"><CODE></CODE><A NAME="544133"><CODE></CODE><A NAME="544134"><CODE></CODE><A NAME="544135"><CODE></CODE><A NAME="544136"><CODE></CODE><A NAME="544137"><CODE></CODE><A NAME="544138"><CODE></CODE><A NAME="544139"><CODE></CODE><A NAME="544140"><CODE></CODE><A NAME="544141"><CODE></CODE><A NAME="544142"><CODE></CODE><A NAME="544143"><CODE></CODE><A NAME="544144"><CODE></CODE><A NAME="544145"><CODE></CODE><A NAME="544146"><CODE></CODE><A NAME="544147"><CODE></CODE><A NAME="544148"><CODE></CODE><A NAME="544149"><CODE></CODE><A NAME="544150"><CODE></CODE><A NAME="544151"><CODE></CODE><A NAME="544152"><CODE></CODE><A NAME="544153"><CODE></CODE><A NAME="544154"><CODE></CODE><A NAME="544155"><CODE></CODE><A NAME="544156"><CODE></CODE><A NAME="544157"><CODE></CODE><A NAME="544158"><CODE></CODE><A NAME="544159"><CODE></CODE><A NAME="544160"><CODE></CODE><A NAME="544161"><CODE></CODE><A NAME="544162"><CODE></CODE><A NAME="544163"><CODE></CODE><a name="544164">
<h3>12.2.5 Completing ABC</h3>
</a>
<a name="544165">
Once the system level information and the packages have been defined, PANACHE can be directed to generate the source code for a variety of configurations and in this case the compilation executed.<p>
</a>
<a name="544166">
<p>
</a>
<A NAME="544167"><CODE></CODE><A NAME="544168"><CODE></CODE><A NAME="544169"><CODE></CODE><A NAME="544170"><CODE></CODE><A NAME="544171"><CODE></CODE><A NAME="544172"><CODE></CODE><A NAME="544173"><CODE></CODE><A NAME="544174"><CODE></CODE><A NAME="544175"><CODE></CODE><A NAME="544176"><CODE></CODE><A NAME="544177"><CODE></CODE><A NAME="544178"><CODE></CODE><A NAME="544179"><CODE></CODE><a name="544180">
<p>
</a>
<a name="544181">
<h1>13.0 Other Documentation</h1>
</a>
<a name="544182">
PANACEA is a part of the PACT portable code development and visualization tool set. It depends on most of PACT. Readers may find useful material in the other PACT documents.<p>
</a>
<a name="544183">
The list of PACT Documents is:<p>
</a>
<A NAME="544184"><PRE> PACT User’s Guide, UCRL-MA-112087
</PRE><A NAME="544185"><PRE> SCORE User’s Manual, UCRL-MA-108976 Rev.1
</PRE><A NAME="544186"><PRE> PPC User’s Manual UCRL-MA-108964 Rev.1
</PRE><A NAME="544187"><PRE> PML User’s Manual, UCRL-MA-108965 Rev.1
</PRE><A NAME="544188"><PRE> PDBLib User’s Manual, M-270 Rev.2
</PRE><A NAME="544189"><PRE> PGS User’s Manual, UCRL-MA-108966 Rev.1
</PRE><A NAME="544190"><PRE> PANACEA User’s Manual, M-276 Rev.2 (this document)
</PRE><A NAME="544191"><PRE> ULTRA II User’s Manual, UCRL-MA-108967 Rev.1
</PRE><A NAME="544192"><PRE> PDBDiff User’s Manual, UCRL-MA-108975 Rev.1
</PRE><A NAME="544193"><PRE> PDBView User’s Manual, UCRL-MA-108968 Rev.1
</PRE><A NAME="544194"><PRE> SX User’s Manual, UCRL-MA-112315
</PRE><a name="544195">
Some additional references to work that readers may find interesting and useful are:<p>
</a>
<a name="544196">
1. Harold Ableson, and Gerald Jay Sussman, Structure and Interpretation of Computer Programs, MIT Press, Cambridge, Mass. (1986).<p>
</a>
<a name="544197">
2. G. O. Cook, Jr., “ALPAL, A Program to Generate Physics Simulation Codes from Natural Descriptions”, Int. J. Mod. Phys. C 1, 1990.<p>
</a>
<a name="544198">
<p>
</a>
<p><hr>
</body></html>
|
