File: index.html

package info (click to toggle)
petsc 3.23.1%2Bdfsg1-1exp1
  • links: PTS, VCS
  • area: main
  • in suites: experimental
  • size: 515,576 kB
  • sloc: ansic: 751,607; cpp: 51,542; python: 38,598; f90: 17,352; javascript: 3,493; makefile: 3,157; sh: 1,502; xml: 619; objc: 445; java: 13; csh: 1
file content (2817 lines) | stat: -rw-r--r-- 313,523 bytes parent folder | download
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

<!DOCTYPE html>


<html lang="en" data-content_root="../" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>FAQ &#8212; PETSc 3.23.1 documentation</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
  </script>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="../_static/styles/theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />

  
  <link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
  <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" />

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=8f2a1f02" />
    <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
    <link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=87e54e7c" />
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css" />
    <link rel="stylesheet" type="text/css" href="../_static/katex-math.css?v=91adb8b6" />
    <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=dbe1606d" />
  
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=bd9e20870c6007c4c509" />
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=bd9e20870c6007c4c509" />
  <script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=bd9e20870c6007c4c509"></script>

    <script src="../_static/documentation_options.js?v=34da53a5"></script>
    <script src="../_static/doctools.js?v=9a2dae69"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/clipboard.min.js?v=a7894cd8"></script>
    <script src="../_static/copybutton.js?v=a56c686a"></script>
    <script src="../_static/design-tabs.js?v=f930bc37"></script>
    <script src="../_static/katex.min.js?v=be8ff15f"></script>
    <script src="../_static/auto-render.min.js?v=ad136472"></script>
    <script src="../_static/katex_autorenderer.js?v=bebc588a"></script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'faq/index';</script>
    <link rel="icon" href="../_static/petsc_favicon.png"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Community" href="../community/index.html" />
    <link rel="prev" title="petsc4py API" href="../petsc4py/index.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
    <meta name="docbuild:last-update" content="2025-04-30T13:10:40-0500 (v3.23.1)"/>
  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  
  <a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a>
  
  <div id="pst-scroll-pixel-helper"></div>

  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>
    Back to top
  </button>

  
  <input type="checkbox"
          class="sidebar-toggle"
          name="__primary"
          id="__primary"/>
  <label class="overlay overlay-primary" for="__primary"></label>
  
  <input type="checkbox"
          class="sidebar-toggle"
          name="__secondary"
          id="__secondary"/>
  <label class="overlay overlay-secondary" for="__secondary"></label>
  
  <div class="search-button__wrapper">
    <div class="search-button__overlay"></div>
    <div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
      action="../search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         id="search-input"
         placeholder="Search the docs ..."
         aria-label="Search the docs ..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
  </div>

  <header>
  
    <div class="bd-header navbar navbar-expand-lg bd-navbar">
<div class="bd-header__inner bd-page-width">
  <label class="sidebar-toggle primary-toggle" for="__primary">
    <span class="fa-solid fa-bars"></span>
  </label>
  
  
  <div class="col-lg-3 navbar-header-items__start">
    
      <div class="navbar-item">

  

<a class="navbar-brand logo" href="../index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="../_static/PETSc-TAO_RGB.svg" class="logo__image only-light" alt="PETSc 3.23.1 documentation - Home"/>
    <script>document.write(`<img src="../_static/PETSc-TAO_RGB_white.svg" class="logo__image only-dark" alt="PETSc 3.23.1 documentation - Home"/>`);</script>
  
  
</a></div>
    
  </div>
  
  <div class="col-lg-9 navbar-header-items">
    
    <div class="me-auto navbar-header-items__center">
      
        <div class="navbar-item">
<nav class="navbar-nav">
  <ul class="bd-navbar-elements navbar-nav">
    
                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../overview/index.html">
                        Overview
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../install/index.html">
                        Install
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../tutorials/index.html">
                        Tutorials
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../manual/index.html">
                        User-Guide
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../manualpages/index.html">
                        C/Fortran API
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../petsc4py/index.html">
                        petsc4py API
                      </a>
                    </li>
                

                    <li class="nav-item current active">
                      <a class="nav-link nav-internal" href="#">
                        FAQ
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../community/index.html">
                        Community
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../developers/index.html">
                        Developers
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../miscellaneous/index.html">
                        Misc.
                      </a>
                    </li>
                
  </ul>
</nav></div>
      
    </div>
    
    
    <div class="navbar-header-items__end">
      
        <div class="navbar-item navbar-persistent--container">
          

 <script>
 document.write(`
   <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <i class="fa-solid fa-magnifying-glass"></i>
    <span class="search-button__default-text">Search</span>
    <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
   </button>
 `);
 </script>
        </div>
      
      
        <div class="navbar-item">

<script>
document.write(`
  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
  </button>
`);
</script></div>
      
        <div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
    aria-label="Icon Links">
        <li class="nav-item">
          
          
          
          
          
          
          
          
          <a href="https://gitlab.com/petsc/petsc" title="GitLab" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fab fa-gitlab fa-lg" aria-hidden="true"></i></span>
            <span class="sr-only">GitLab</span></a>
        </li>
</ul></div>
      
    </div>
    
  </div>
  
  
    <div class="navbar-persistent--mobile">

 <script>
 document.write(`
   <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <i class="fa-solid fa-magnifying-glass"></i>
    <span class="search-button__default-text">Search</span>
    <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
   </button>
 `);
 </script>
    </div>
  

  
    <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
      <span class="fa-solid fa-outdent"></span>
    </label>
  
</div>

    </div>
  
  </header>

  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      
      
        
      
      <div class="bd-sidebar-primary bd-sidebar hide-on-wide">
        

  
  <div class="sidebar-header-items sidebar-primary__section">
    
    
      <div class="sidebar-header-items__center">
        
          <div class="navbar-item">
<nav class="navbar-nav">
  <ul class="bd-navbar-elements navbar-nav">
    
                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../overview/index.html">
                        Overview
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../install/index.html">
                        Install
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../tutorials/index.html">
                        Tutorials
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../manual/index.html">
                        User-Guide
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../manualpages/index.html">
                        C/Fortran API
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../petsc4py/index.html">
                        petsc4py API
                      </a>
                    </li>
                

                    <li class="nav-item current active">
                      <a class="nav-link nav-internal" href="#">
                        FAQ
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../community/index.html">
                        Community
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../developers/index.html">
                        Developers
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../miscellaneous/index.html">
                        Misc.
                      </a>
                    </li>
                
  </ul>
</nav></div>
        
      </div>
    
    
    
      <div class="sidebar-header-items__end">
        
          <div class="navbar-item">

<script>
document.write(`
  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
  </button>
`);
</script></div>
        
          <div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
    aria-label="Icon Links">
        <li class="nav-item">
          
          
          
          
          
          
          
          
          <a href="https://gitlab.com/petsc/petsc" title="GitLab" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fab fa-gitlab fa-lg" aria-hidden="true"></i></span>
            <span class="sr-only">GitLab</span></a>
        </li>
</ul></div>
        
      </div>
    
  </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
  </div>
  
  <div id="rtd-footer-container"></div>


      </div>
      
      <main id="main-content" class="bd-main">
        
        
          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item">



<nav aria-label="Breadcrumb">
  <ul class="bd-breadcrumbs">
    
    <li class="breadcrumb-item breadcrumb-home">
      <a href="../index.html" class="nav-link" aria-label="Home">
        <i class="fa-solid fa-home"></i>
      </a>
    </li>
    <li class="breadcrumb-item active" aria-current="page">FAQ</li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="faq">
<span id="doc-faq"></span><h1>FAQ<a class="headerlink" href="#faq" title="Link to this heading">#</a></h1>
<nav class="contents local" id="table-of-contents">
<p class="topic-title">Table Of Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#general" id="id3949">General</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-subscribe-to-the-petsc-mailing-lists" id="id3950">How can I subscribe to the PETSc mailing lists?</a></p></li>
<li><p><a class="reference internal" href="#any-useful-books-on-numerical-computing" id="id3951">Any useful books on numerical computing?</a></p></li>
<li><p><a class="reference internal" href="#what-kind-of-parallel-computers-or-clusters-are-needed-to-use-petsc-or-why-do-i-get-little-speedup" id="id3952">What kind of parallel computers or clusters are needed to use PETSc? Or why do I get little speedup?</a></p></li>
<li><p><a class="reference internal" href="#what-kind-of-license-is-petsc-released-under" id="id3953">What kind of license is PETSc released under?</a></p></li>
<li><p><a class="reference internal" href="#why-is-petsc-written-in-c-instead-of-fortran-or-c" id="id3954">Why is PETSc written in C, instead of Fortran or C++?</a></p></li>
<li><p><a class="reference internal" href="#does-all-the-petsc-error-checking-and-logging-reduce-petsc-s-efficiency" id="id3955">Does all the PETSc error checking and logging reduce PETSc’s efficiency?</a></p></li>
<li><p><a class="reference internal" href="#how-do-such-a-small-group-of-people-manage-to-write-and-maintain-such-a-large-and-marvelous-package-as-petsc" id="id3956">How do such a small group of people manage to write and maintain such a large and marvelous package as PETSc?</a></p></li>
<li><p><a class="reference internal" href="#for-complex-numbers-will-i-get-better-performance-with-c" id="id3957">For complex numbers will I get better performance with C++?</a></p></li>
<li><p><a class="reference internal" href="#how-come-when-i-run-the-same-program-on-the-same-number-of-processes-i-get-a-different-answer" id="id3958">How come when I run the same program on the same number of processes I get a “different” answer?</a></p></li>
<li><p><a class="reference internal" href="#how-come-when-i-run-the-same-linear-solver-on-a-different-number-of-processes-it-takes-a-different-number-of-iterations" id="id3959">How come when I run the same linear solver on a different number of processes it takes a different number of iterations?</a></p></li>
<li><p><a class="reference internal" href="#can-petsc-use-gpus-to-speed-up-computations" id="id3960">Can PETSc use GPUs to speed up computations?</a></p></li>
<li><p><a class="reference internal" href="#can-i-run-petsc-with-extended-precision" id="id3961">Can I run PETSc with extended precision?</a></p></li>
<li><p><a class="reference internal" href="#why-doesn-t-petsc-use-qd-to-implement-support-for-extended-precision" id="id3962">Why doesn’t PETSc use Qd to implement support for extended precision?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-cite-petsc" id="id3963">How do I cite PETSc?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#installation" id="id3964">Installation</a></p>
<ul>
<li><p><a class="reference internal" href="#how-do-i-begin-using-petsc-if-the-software-has-already-been-completely-built-and-installed-by-someone-else" id="id3965">How do I begin using PETSc if the software has already been completely built and installed by someone else?</a></p></li>
<li><p><a class="reference internal" href="#the-petsc-distribution-is-so-large-how-can-i-reduce-my-disk-space-usage" id="id3966">The PETSc distribution is SO Large. How can I reduce my disk space usage?</a></p></li>
<li><p><a class="reference internal" href="#i-want-to-use-petsc-only-for-uniprocessor-programs-must-i-still-install-and-use-a-version-of-mpi" id="id3967">I want to use PETSc only for uniprocessor programs. Must I still install and use a version of MPI?</a></p></li>
<li><p><a class="reference internal" href="#can-i-install-petsc-to-not-use-x-windows-either-under-unix-or-microsoft-windows-with-gcc" id="id3968">Can I install PETSc to not use X windows (either under Unix or Microsoft Windows with GCC)?</a></p></li>
<li><p><a class="reference internal" href="#why-do-you-use-mpi" id="id3969">Why do you use MPI?</a></p></li>
<li><p><a class="reference internal" href="#what-do-i-do-if-my-mpi-compiler-wrappers-are-invalid" id="id3970">What do I do if my MPI compiler wrappers are invalid?</a></p></li>
<li><p><a class="reference internal" href="#when-should-can-i-use-the-configure-option-with-64-bit-indices" id="id3971">When should/can I use the <code class="docutils notranslate"><span class="pre">configure</span></code> option <code class="docutils notranslate"><span class="pre">--with-64-bit-indices</span></code>?</a></p></li>
<li><p><a class="reference internal" href="#what-if-i-get-an-internal-compiler-error" id="id3972">What if I get an internal compiler error?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-enable-python-bindings-petsc4py-with-petsc" id="id3973">How do I enable Python bindings (petsc4py) with PETSc?</a></p></li>
<li><p><a class="reference internal" href="#what-fortran-compiler-do-you-recommend-on-macos" id="id3974">What Fortran compiler do you recommend on macOS?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-find-the-url-locations-of-the-packages-you-install-using-download-package" id="id3975">How can I find the URL locations of the packages you install using <code class="docutils notranslate"><span class="pre">--download-PACKAGE</span></code>?</a></p></li>
<li><p><a class="reference internal" href="#how-to-fix-the-problem-petsc-was-configured-with-one-mpich-or-open-mpi-mpi-h-version-but-now-appears-to-be-compiling-using-a-different-mpich-or-open-mpi-mpi-h-version" id="id3976">How to fix the problem: PETSc was configured with one MPICH (or Open MPI) <code class="docutils notranslate"><span class="pre">mpi.h</span></code> version but now appears to be compiling using a different MPICH (or Open MPI) <code class="docutils notranslate"><span class="pre">mpi.h</span></code> version</a></p></li>
<li><p><a class="reference internal" href="#what-does-it-mean-when-make-check-hangs-or-errors-on-petscoptionsinsertfile" id="id3977">What does it mean when <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">check</span></code> hangs or errors on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsInsertFile.html">PetscOptionsInsertFile</a>()</span></code>?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#usage" id="id3978">Usage</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-redirect-petsc-s-stdout-and-stderr-when-programming-with-a-gui-interface-in-windows-developer-studio-or-to-c-streams" id="id3979">How can I redirect PETSc’s <code class="docutils notranslate"><span class="pre">stdout</span></code> and <code class="docutils notranslate"><span class="pre">stderr</span></code> when programming with a GUI interface in Windows Developer Studio or to C++ streams?</a></p></li>
<li><p><a class="reference internal" href="#i-want-to-use-hypre-boomeramg-without-gmres-but-when-i-run-pc-type-hypre-pc-hypre-type-boomeramg-ksp-type-preonly-i-don-t-get-a-very-accurate-answer" id="id3980">I want to use Hypre boomerAMG without GMRES but when I run <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">boomeramg</span> <span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> I don’t get a very accurate answer!</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-use-petsc-for-domain-decomposition" id="id3981">How do I use PETSc for Domain Decomposition?</a></p></li>
<li><p><a class="reference internal" href="#you-have-mataij-and-matbaij-matrix-formats-and-matsbaij-for-symmetric-storage-how-come-no-matsaij" id="id3982">You have <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> matrix formats, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSBAIJ.html">MATSBAIJ</a></span></code> for symmetric storage, how come no <code class="docutils notranslate"><span class="pre">MATSAIJ</span></code>?</a></p></li>
<li><p><a class="reference internal" href="#can-i-create-baij-matrices-with-different-size-blocks-for-different-block-rows" id="id3983">Can I Create BAIJ matrices with different size blocks for different block rows?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-access-the-values-of-a-remote-parallel-petsc-vec" id="id3984">How do I access the values of a remote parallel PETSc Vec?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-collect-to-a-single-processor-all-the-values-from-a-parallel-petsc-vec" id="id3985">How do I collect to a single processor all the values from a parallel PETSc Vec?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-collect-all-the-values-from-a-parallel-petsc-vec-on-the-0th-rank" id="id3986">How do I collect all the values from a parallel PETSc Vec on the 0th rank?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-read-in-or-write-out-a-sparse-matrix-in-matrix-market-harwell-boeing-slapc-or-other-ascii-format" id="id3987">How can I read in or write out a sparse matrix in Matrix Market, Harwell-Boeing, Slapc or other ASCII format?</a></p></li>
<li><p><a class="reference internal" href="#does-tssetfromoptions-snessetfromoptions-or-kspsetfromoptions-reset-all-the-parameters-i-previously-set-or-how-come-do-they-not-seem-to-work" id="id3988">Does TSSetFromOptions(), SNESSetFromOptions(), or KSPSetFromOptions() reset all the parameters I previously set or how come do they not seem to work?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-compile-and-link-my-own-petsc-application-codes-and-can-i-use-my-own-makefile-or-rules-for-compiling-code-rather-than-petsc-s" id="id3989">How do I compile and link my own PETSc application codes and can I use my own <code class="docutils notranslate"><span class="pre">makefile</span></code> or rules for compiling code, rather than PETSc’s?</a></p></li>
<li><p><a class="reference internal" href="#can-i-use-cmake-to-build-my-own-project-that-depends-on-petsc" id="id3990">Can I use CMake to build my own project that depends on PETSc?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-put-carriage-returns-in-petscprintf-statements-from-fortran" id="id3991">How can I put carriage returns in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a>()</span></code> statements from Fortran?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-implement-callbacks-using-c-class-methods" id="id3992">How can I implement callbacks using C++ class methods?</a></p></li>
<li><p><a class="reference internal" href="#everyone-knows-that-when-you-code-newton-s-method-you-should-compute-the-function-and-its-jacobian-at-the-same-time-how-can-one-do-this-in-petsc" id="id3993">Everyone knows that when you code Newton’s Method you should compute the function and its Jacobian at the same time. How can one do this in PETSc?</a></p></li>
<li><p><a class="reference internal" href="#computing-the-jacobian-or-preconditioner-is-time-consuming-is-there-any-way-to-compute-it-less-often" id="id3994">Computing the Jacobian or preconditioner is time consuming. Is there any way to compute it less often?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-newton-s-method-jacobian-free-can-i-difference-a-different-function-than-provided-with-snessetfunction" id="id3995">How can I use Newton’s Method Jacobian free? Can I difference a different function than provided with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a>()</span></code>?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-determine-the-condition-number-of-a-matrix" id="id3996">How can I determine the condition number of a matrix?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-compute-the-inverse-of-a-matrix-in-petsc" id="id3997">How can I compute the inverse of a matrix in PETSc?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-compute-the-schur-complement-in-petsc" id="id3998">How can I compute the Schur complement in PETSc?</a></p></li>
<li><p><a class="reference internal" href="#do-you-have-examples-of-doing-unstructured-grid-finite-element-method-fem-with-petsc" id="id3999">Do you have examples of doing unstructured grid Finite Element Method (FEM) with PETSc?</a></p></li>
<li><p><a class="reference internal" href="#dmda-decomposes-the-domain-differently-than-the-mpi-cart-create-command-how-can-one-use-them-together" id="id4000">DMDA decomposes the domain differently than the MPI_Cart_create() command. How can one use them together?</a></p></li>
<li><p><a class="reference internal" href="#when-solving-a-system-with-dirichlet-boundary-conditions-i-can-use-matzerorows-to-eliminate-the-dirichlet-rows-but-this-results-in-a-non-symmetric-system-how-can-i-apply-dirichlet-boundary-conditions-but-keep-the-matrix-symmetric" id="id4001">When solving a system with Dirichlet boundary conditions I can use MatZeroRows() to eliminate the Dirichlet rows but this results in a non-Symmetric system. How can I apply Dirichlet boundary conditions but keep the matrix symmetric?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-get-petsc-vectors-and-matrices-to-matlab-or-vice-versa" id="id4002">How can I get PETSc vectors and matrices to MATLAB or vice versa?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-get-started-with-cython-so-that-i-can-extend-petsc4py" id="id4003">How do I get started with Cython so that I can extend petsc4py?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-compute-a-custom-norm-for-ksp-to-use-as-a-convergence-test-or-for-monitoring" id="id4004">How do I compute a custom norm for KSP to use as a convergence test or for monitoring?</a></p></li>
<li><p><a class="reference internal" href="#if-i-have-a-sequential-program-can-i-use-a-petsc-parallel-solver" id="id4005">If I have a sequential program can I use a PETSc parallel solver?</a></p></li>
<li><p><a class="reference internal" href="#ts-or-snes-produces-infeasible-out-of-domain-solutions-or-states-how-can-i-prevent-this" id="id4006">TS or SNES produces infeasible (out of domain) solutions or states. How can I prevent this?</a></p></li>
<li><p><a class="reference internal" href="#can-petsc-work-with-hermitian-matrices" id="id4007">Can PETSc work with Hermitian matrices?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-assemble-a-bunch-of-similar-matrices" id="id4008">How can I assemble a bunch of similar matrices?</a></p></li>
<li><p><a class="reference internal" href="#can-one-resize-or-change-the-size-of-petsc-matrices-or-vectors" id="id4009">Can one resize or change the size of PETSc matrices or vectors?</a></p></li>
<li><p><a class="reference internal" href="#how-can-one-compute-the-nullspace-of-a-sparse-matrix-with-mumps" id="id4010">How can one compute the nullspace of a sparse matrix with MUMPS?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#execution" id="id4011">Execution</a></p>
<ul>
<li><p><a class="reference internal" href="#petsc-executables-are-so-big-and-take-so-long-to-link" id="id4012">PETSc executables are SO big and take SO long to link</a></p></li>
<li><p><a class="reference internal" href="#how-does-petsc-s-help-option-work-why-is-it-different-for-different-programs" id="id4013">How does PETSc’s <code class="docutils notranslate"><span class="pre">-help</span></code> option work? Why is it different for different programs?</a></p></li>
<li><p><a class="reference internal" href="#petsc-has-so-many-options-for-my-program-that-it-is-hard-to-keep-them-straight" id="id4014">PETSc has so many options for my program that it is hard to keep them straight</a></p></li>
<li><p><a class="reference internal" href="#petsc-automatically-handles-many-of-the-details-in-parallel-pde-solvers-how-can-i-understand-what-is-really-happening-within-my-program" id="id4015">PETSc automatically handles many of the details in parallel PDE solvers. How can I understand what is really happening within my program?</a></p></li>
<li><p><a class="reference internal" href="#assembling-large-sparse-matrices-takes-a-long-time-what-can-i-do-to-make-this-process-faster-or-matsetvalues-is-so-slow-what-can-i-do-to-speed-it-up" id="id4016">Assembling large sparse matrices takes a long time. What can I do to make this process faster? Or MatSetValues() is so slow; what can I do to speed it up?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-generate-performance-summaries-with-petsc" id="id4017">How can I generate performance summaries with PETSc?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-know-the-amount-of-time-spent-on-each-level-of-the-multigrid-solver-preconditioner" id="id4018">How do I know the amount of time spent on each level of the multigrid solver/preconditioner?</a></p></li>
<li><p><a class="reference internal" href="#where-do-i-get-the-input-matrices-for-the-examples" id="id4019">Where do I get the input matrices for the examples?</a></p></li>
<li><p><a class="reference internal" href="#when-i-dump-some-matrices-and-vectors-to-binary-i-seem-to-be-generating-some-empty-files-with-info-extensions-what-s-the-deal-with-these" id="id4020">When I dump some matrices and vectors to binary, I seem to be generating some empty files with <code class="docutils notranslate"><span class="pre">.info</span></code> extensions. What’s the deal with these?</a></p></li>
<li><p><a class="reference internal" href="#why-is-my-parallel-solver-slower-than-my-sequential-solver-or-i-have-poor-speed-up" id="id4021">Why is my parallel solver slower than my sequential solver, or I have poor speed-up?</a></p></li>
<li><p><a class="reference internal" href="#what-steps-are-necessary-to-make-the-pipelined-solvers-execute-efficiently" id="id4022">What steps are necessary to make the pipelined solvers execute efficiently?</a></p></li>
<li><p><a class="reference internal" href="#when-using-petsc-in-single-precision-mode-with-precision-single-when-running-configure-are-the-operations-done-in-single-or-double-precision" id="id4023">When using PETSc in single precision mode (<code class="docutils notranslate"><span class="pre">--with-precision=single</span></code> when running <code class="docutils notranslate"><span class="pre">configure</span></code>) are the operations done in single or double precision?</a></p></li>
<li><p><a class="reference internal" href="#why-is-newton-s-method-snes-not-converging-or-converges-slowly" id="id4024">Why is Newton’s method (SNES) not converging, or converges slowly?</a></p></li>
<li><p><a class="reference internal" href="#why-is-the-linear-solver-ksp-not-converging-or-converges-slowly" id="id4025">Why is the linear solver (KSP) not converging, or converges slowly?</a></p></li>
<li><p><a class="reference internal" href="#i-get-the-error-message-actual-argument-at-1-to-assumed-type-dummy-is-of-derived-type-with-type-bound-or-final-procedures" id="id4026">I get the error message: Actual argument at (1) to assumed-type dummy is of derived type with type-bound or FINAL procedures</a></p></li>
<li><p><a class="reference internal" href="#in-c-i-get-a-crash-on-vecdestroy-or-some-other-petsc-object-at-the-end-of-the-program" id="id4027">In C++ I get a crash on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a>()</span></code> (or some other PETSc object) at the end of the program</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#debugging" id="id4028">Debugging</a></p>
<ul>
<li><p><a class="reference internal" href="#what-does-the-message-hwloc-linux-ignoring-pci-device-with-non-16bit-domain-mean" id="id4029">What does the message hwloc/linux: Ignoring PCI device with non-16bit domain mean?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-turn-off-petsc-signal-handling-so-i-can-use-the-c-option-on-xlf" id="id4030">How do I turn off PETSc signal handling so I can use the <code class="docutils notranslate"><span class="pre">-C</span></code> Option On <code class="docutils notranslate"><span class="pre">xlf</span></code>?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-debug-if-start-in-debugger-does-not-work-on-my-machine" id="id4031">How do I debug if <code class="docutils notranslate"><span class="pre">-start_in_debugger</span></code> does not work on my machine?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-see-where-my-code-is-hanging" id="id4032">How do I see where my code is hanging?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-inspect-petsc-vector-and-matrix-values-when-in-the-debugger" id="id4033">How can I inspect PETSc vector and matrix values when in the debugger?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-find-the-cause-of-floating-point-exceptions-like-not-a-number-nan-or-infinity" id="id4034">How can I find the cause of floating point exceptions like not-a-number (NaN) or infinity?</a></p></li>
<li><p><a class="reference internal" href="#error-while-loading-shared-libraries-libimf-so-cannot-open-shared-object-file-no-such-file-or-directory" id="id4035">Error while loading shared libraries: libimf.so: cannot open shared object file: No such file or directory</a></p></li>
<li><p><a class="reference internal" href="#what-does-object-type-not-set-argument-n-mean" id="id4036">What does “Object Type Not Set: Argument # N” Mean?</a></p></li>
<li><p><a class="reference internal" href="#what-does-error-detected-in-petscsplitownership-about-sum-of-local-lengths-mean" id="id4037">What does error detected in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscSplitOwnership.html">PetscSplitOwnership</a>()</span></code> about “sum of local lengths …”: mean?</a></p></li>
<li><p><a class="reference internal" href="#what-does-corrupt-argument-or-caught-signal-or-segv-or-segmentation-violation-or-bus-error-mean-can-i-use-valgrind-or-cuda-memcheck-to-debug-memory-corruption-issues" id="id4038">What does “corrupt argument” or “caught signal” Or “SEGV” Or “segmentation violation” Or “bus error” mean? Can I use Valgrind or CUDA-Memcheck to debug memory corruption issues?</a></p></li>
<li><p><a class="reference internal" href="#what-does-detected-zero-pivot-in-lu-factorization-mean" id="id4039">What does “detected zero pivot in LU factorization” mean?</a></p></li>
<li><p><a class="reference internal" href="#you-create-draw-windows-or-petscviewerdraw-windows-or-use-options-ksp-monitor-draw-draw-lg-or-snes-monitor-draw-draw-lg-and-the-program-seems-to-run-ok-but-windows-never-open" id="id4040">You create draw windows or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSCVIEWERDRAW.html">PETSCVIEWERDRAW</a></span></code> windows or use options <code class="docutils notranslate"><span class="pre">-ksp_monitor</span> <span class="pre">draw::draw_lg</span></code> or <code class="docutils notranslate"><span class="pre">-snes_monitor</span> <span class="pre">draw::draw_lg</span></code> and the program seems to run OK but windows never open</a></p></li>
<li><p><a class="reference internal" href="#the-program-seems-to-use-more-and-more-memory-as-it-runs-even-though-you-don-t-think-you-are-allocating-more-memory" id="id4041">The program seems to use more and more memory as it runs, even though you don’t think you are allocating more memory</a></p></li>
<li><p><a class="reference internal" href="#when-calling-matpartitioningapply-you-get-a-message-error-key-16615-not-found" id="id4042">When calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatPartitioningApply.html">MatPartitioningApply</a>()</span></code> you get a message “Error! Key 16615 Not Found”</a></p></li>
<li><p><a class="reference internal" href="#with-gmres-at-restart-the-second-residual-norm-printed-does-not-match-the-first" id="id4043">With GMRES at restart the second residual norm printed does not match the first</a></p></li>
<li><p><a class="reference internal" href="#why-do-some-krylov-methods-seem-to-print-two-residual-norms-per-iteration" id="id4044">Why do some Krylov methods seem to print two residual norms per iteration?</a></p></li>
<li><p><a class="reference internal" href="#unable-to-locate-petsc-dynamic-library-libpetsc" id="id4045">Unable to locate PETSc dynamic library <code class="docutils notranslate"><span class="pre">libpetsc</span></code></a></p></li>
<li><p><a class="reference internal" href="#how-do-i-determine-what-update-to-petsc-broke-my-code" id="id4046">How do I determine what update to PETSc broke my code?</a></p></li>
<li><p><a class="reference internal" href="#how-to-fix-the-error-pmix-error-error-in-file-gds-ds12-lock-pthread-c" id="id4047">How to fix the error “PMIX Error: error in file gds_ds12_lock_pthread.c”?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#shared-libraries" id="id4048">Shared Libraries</a></p>
<ul>
<li><p><a class="reference internal" href="#can-i-install-petsc-libraries-as-shared-libraries" id="id4049">Can I install PETSc libraries as shared libraries?</a></p></li>
<li><p><a class="reference internal" href="#why-should-i-use-shared-libraries" id="id4050">Why should I use shared libraries?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-link-to-the-petsc-shared-libraries" id="id4051">How do I link to the PETSc shared libraries?</a></p></li>
<li><p><a class="reference internal" href="#what-if-i-want-to-link-to-the-regular-a-library-files" id="id4052">What if I want to link to the regular <code class="docutils notranslate"><span class="pre">.a</span></code> library files?</a></p></li>
<li><p><a class="reference internal" href="#what-do-i-do-if-i-want-to-move-my-executable-to-a-different-machine" id="id4053">What do I do if I want to move my executable to a different machine?</a></p></li>
</ul>
</li>
</ul>
</nav>
<hr class="docutils" />
<section id="general">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">General</a><a class="headerlink" href="#general" title="Link to this heading">#</a></h2>
<section id="how-can-i-subscribe-to-the-petsc-mailing-lists">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I subscribe to the PETSc mailing lists?</a><a class="headerlink" href="#how-can-i-subscribe-to-the-petsc-mailing-lists" title="Link to this heading">#</a></h3>
<p>See mailing list <a class="reference internal" href="../community/mailing.html#doc-mail"><span class="std std-ref">documentation</span></a></p>
</section>
<section id="any-useful-books-on-numerical-computing">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Any useful books on numerical computing?</a><a class="headerlink" href="#any-useful-books-on-numerical-computing" title="Link to this heading">#</a></h3>
<p><a class="reference external" href="https://my.siam.org/Store/Product/viewproduct/?ProductId=32850137">Bueler, PETSc for Partial Differential Equations: Numerical Solutions in C and Python</a></p>
<p><a class="reference external" href="https://www.cambridge.org/core/books/writing-scientific-software/23206704175AF868E43FE3FB399C2F53">Oliveira and Stewart, Writing Scientific Software: A Guide to Good Style</a></p>
</section>
<section id="what-kind-of-parallel-computers-or-clusters-are-needed-to-use-petsc-or-why-do-i-get-little-speedup">
<span id="doc-faq-general-parallel"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What kind of parallel computers or clusters are needed to use PETSc? Or why do I get little speedup?</a><a class="headerlink" href="#what-kind-of-parallel-computers-or-clusters-are-needed-to-use-petsc-or-why-do-i-get-little-speedup" title="Link to this heading">#</a></h3>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>PETSc can be used with any kind of parallel system that supports MPI BUT for any decent
performance one needs:</p>
<ul class="simple">
<li><p>Fast, <strong>low-latency</strong> interconnect; any ethernet (even 10 GigE) simply cannot provide
the needed performance.</p></li>
<li><p>High per-core <strong>memory</strong> performance. Each core needs to
have its <strong>own</strong> memory bandwidth of at least 2 or more gigabytes/second. Most modern
computers are not bottlenecked by how fast they can perform
calculations; rather, they are usually restricted by how quickly they can get their
data.</p></li>
</ul>
</div>
<p>To obtain good performance it is important that you know your machine! I.e. how many
compute nodes (generally, how many motherboards), how many memory sockets per node and how
many cores per memory socket and how much memory bandwidth for each.</p>
<p>If you do not know this and can run MPI programs with mpiexec (that is, you don’t have
batch system), run the following from <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>streams<span class="w"> </span><span class="o">[</span><span class="nv">NPMAX</span><span class="o">=</span>maximum_number_of_mpi_processes_you_plan_to_use<span class="o">]</span>
</pre></div>
</div>
<p>This will provide a summary of the bandwidth with different number of MPI
processes and potential speedups. See <a class="reference internal" href="../manual/streams.html#ch-streams"><span class="std std-ref">STREAMS: Example Study</span></a> for a detailed discussion.</p>
<p>If you have a batch system:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span><span class="nv">$PETSC_DIR</span>/src/benchmarks/streams
<span class="gp">$ </span>make<span class="w"> </span>MPIVersion
<span class="go">submit MPIVersion to the batch system a number of times with 1, 2, 3, etc. MPI processes</span>
<span class="go">collecting all of the output from the runs into the single file scaling.log. Copy</span>
<span class="go">scaling.log into the src/benchmarks/streams directory.</span>
<span class="gp">$ </span>./process.py<span class="w"> </span>createfile<span class="w"> </span><span class="p">;</span><span class="w"> </span>process.py
</pre></div>
</div>
<p>Even if you have enough memory bandwidth if the OS switches processes between cores
performance can degrade. Smart process to core/socket binding (this just means locking a
process to a particular core or memory socket) may help you. For example, consider using
fewer processes than cores and binding processes to separate sockets so that each process
uses a different memory bus:</p>
<ul>
<li><p>[MPICH2 binding with the Hydra process manager](https://github.com/pmodels/mpich/blob/main/doc/wiki/how_to/Using_the_Hydra_Process_Manager.md#process-core-binding]</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mpiexec.hydra<span class="w"> </span>-n<span class="w"> </span><span class="m">4</span><span class="w"> </span>--binding<span class="w"> </span>cpu:sockets
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://www.open-mpi.org/faq/?category=tuning#using-paffinity">Open MPI binding</a></p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mpiexec<span class="w"> </span>-n<span class="w"> </span><span class="m">4</span><span class="w"> </span>--map-by<span class="w"> </span>socket<span class="w"> </span>--bind-to<span class="w"> </span>socket<span class="w"> </span>--report-bindings
</pre></div>
</div>
</li>
<li><p><code class="docutils notranslate"><span class="pre">taskset</span></code>, part of the <a class="reference external" href="https://github.com/karelzak/util-linux">util-linux</a> package</p>
<p>Check <code class="docutils notranslate"><span class="pre">man</span> <span class="pre">taskset</span></code> for details. Make sure to set affinity for <strong>your</strong> program,
<strong>not</strong> for the <code class="docutils notranslate"><span class="pre">mpiexec</span></code> program.</p>
</li>
<li><p><code class="docutils notranslate"><span class="pre">numactl</span></code></p>
<p>In addition to task affinity, this tool also allows changing the default memory affinity
policy. On Linux, the default policy is to attempt to find memory on the same memory bus
that serves the core that a thread is running on when the memory is faulted
(not when <code class="docutils notranslate"><span class="pre">malloc()</span></code> is called). If local memory is not available, it is found
elsewhere, possibly leading to serious memory imbalances.</p>
<p>The option <code class="docutils notranslate"><span class="pre">--localalloc</span></code> allocates memory on the local NUMA node, similar to the
<code class="docutils notranslate"><span class="pre">numa_alloc_local()</span></code> function in the <code class="docutils notranslate"><span class="pre">libnuma</span></code> library. The option
<code class="docutils notranslate"><span class="pre">--cpunodebind=nodes</span></code> binds the process to a given NUMA node (note that this can be
larger or smaller than a CPU (socket); a NUMA node usually has multiple cores).</p>
<p>The option <code class="docutils notranslate"><span class="pre">--physcpubind=cpus</span></code> binds the process to a given processor core (numbered
according to <code class="docutils notranslate"><span class="pre">/proc/cpuinfo</span></code>, therefore including logical cores if Hyper-threading is
enabled).</p>
<p>With Open MPI, you can use knowledge of the NUMA hierarchy and core numbering on your
machine to calculate the correct NUMA node or processor number given the environment
variable <code class="docutils notranslate"><span class="pre">OMPI_COMM_WORLD_LOCAL_RANK</span></code>. In most cases, it is easier to make mpiexec or
a resource manager set affinities.</p>
</li>
</ul>
<p>The software <a class="reference external" href="http://open-mx.gforge.inria.fr">Open-MX</a> provides faster speed for
ethernet systems, we have not tried it but it claims it can dramatically reduce latency
and increase bandwidth on Linux system. You must first install this software and then
install MPICH or Open MPI to use it.</p>
</section>
<section id="what-kind-of-license-is-petsc-released-under">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What kind of license is PETSc released under?</a><a class="headerlink" href="#what-kind-of-license-is-petsc-released-under" title="Link to this heading">#</a></h3>
<p>See licensing <a class="reference internal" href="../install/license.html#doc-license"><span class="std std-ref">documentation</span></a></p>
</section>
<section id="why-is-petsc-written-in-c-instead-of-fortran-or-c">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why is PETSc written in C, instead of Fortran or C++?</a><a class="headerlink" href="#why-is-petsc-written-in-c-instead-of-fortran-or-c" title="Link to this heading">#</a></h3>
<p>When this decision was made, in the early 1990s, C enabled us to build data structures
for storing sparse matrices, solver information,
etc. in ways that Fortran simply did not allow. ANSI C was a complete standard that all
modern C compilers supported. The language was identical on all machines. C++ was still
evolving and compilers on different machines were not identical. Using C function pointers
to provide data encapsulation and polymorphism allowed us to get many of the advantages of
C++ without using such a large and more complicated language. It would have been natural and
reasonable to have coded PETSc in C++; we opted to use C instead.</p>
</section>
<section id="does-all-the-petsc-error-checking-and-logging-reduce-petsc-s-efficiency">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Does all the PETSc error checking and logging reduce PETSc’s efficiency?</a><a class="headerlink" href="#does-all-the-petsc-error-checking-and-logging-reduce-petsc-s-efficiency" title="Link to this heading">#</a></h3>
<p>No</p>
</section>
<section id="how-do-such-a-small-group-of-people-manage-to-write-and-maintain-such-a-large-and-marvelous-package-as-petsc">
<span id="doc-faq-maintenance-strats"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do such a small group of people manage to write and maintain such a large and marvelous package as PETSc?</a><a class="headerlink" href="#how-do-such-a-small-group-of-people-manage-to-write-and-maintain-such-a-large-and-marvelous-package-as-petsc" title="Link to this heading">#</a></h3>
<ol class="arabic simple">
<li><p><strong>We work very efficiently</strong>.</p>
<ul class="simple">
<li><p>We use powerful editors and programming environments.</p></li>
<li><p>Our manual pages are generated automatically from formatted comments in the code,
thus alleviating the need for creating and maintaining manual pages.</p></li>
<li><p>We employ continuous integration testing of the entire PETSc library on many different
machine architectures. This process <strong>significantly</strong> protects (no bug-catching
process is perfect) against inadvertently introducing bugs with new additions. Every
new feature <strong>must</strong> pass our suite of thousands of tests as well as formal code
review before it may be included.</p></li>
</ul>
</li>
<li><p><strong>We are very careful in our design (and are constantly revising our design)</strong></p>
<ul class="simple">
<li><p>PETSc as a package should be easy to use, write, and maintain. Our mantra is to write
code like everyone is using it.</p></li>
</ul>
</li>
<li><p><strong>We are willing to do the grunt work</strong></p>
<ul class="simple">
<li><p>PETSc is regularly checked to make sure that all code conforms to our interface
design. We will never keep in a bad design decision simply because changing it will
require a lot of editing; we do a lot of editing.</p></li>
</ul>
</li>
<li><p><strong>We constantly seek out and experiment with new design ideas</strong></p>
<ul class="simple">
<li><p>We retain the useful ones and discard the rest. All of these decisions are based not
just on performance, but also on <strong>practicality</strong>.</p></li>
</ul>
</li>
<li><p><strong>Function and variable names must adhere to strict guidelines</strong></p>
<ul class="simple">
<li><p>Even the rules about capitalization are designed to make it easy to figure out the
name of a particular object or routine. Our memories are terrible, so careful
consistent naming puts less stress on our limited human RAM.</p></li>
</ul>
</li>
<li><p><strong>The PETSc directory tree is designed to make it easy to move throughout the
entire package</strong></p></li>
<li><p><strong>We have a rich, robust, and fast bug reporting system</strong></p>
<ul class="simple">
<li><p><a class="reference external" href="mailto:petsc-maint&#37;&#52;&#48;mcs&#46;anl&#46;gov">mailto:petsc-maint<span>&#64;</span>mcs<span>&#46;</span>anl<span>&#46;</span>gov</a> is always checked, and we pride ourselves on responding
quickly and accurately. Email is very lightweight, and so bug reports system retains
an archive of all reported problems and fixes, so it is easy to re-find fixes to
previously discovered problems.</p></li>
</ul>
</li>
<li><p><strong>We contain the complexity of PETSc by using powerful object-oriented programming
techniques</strong></p>
<ul class="simple">
<li><p>Data encapsulation serves to abstract complex data formats or movement to
human-readable format. This is why your program cannot, for example, look directly
at what is inside the object <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>.</p></li>
<li><p>Polymorphism makes changing program behavior as easy as possible, and further
abstracts the <em>intent</em> of your program from what is <em>written</em> in code. You call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMult.html">MatMult</a>()</span></code> regardless of whether your matrix is dense, sparse, parallel or
sequential; you don’t call a different routine for each format.</p></li>
</ul>
</li>
<li><p><strong>We try to provide the functionality requested by our users</strong></p></li>
</ol>
</section>
<section id="for-complex-numbers-will-i-get-better-performance-with-c">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">For complex numbers will I get better performance with C++?</a><a class="headerlink" href="#for-complex-numbers-will-i-get-better-performance-with-c" title="Link to this heading">#</a></h3>
<p>To use PETSc with complex numbers you may use the following <code class="docutils notranslate"><span class="pre">configure</span></code> options;
<code class="docutils notranslate"><span class="pre">--with-scalar-type=complex</span></code> and either <code class="docutils notranslate"><span class="pre">--with-clanguage=c++</span></code> or (the default)
<code class="docutils notranslate"><span class="pre">--with-clanguage=c</span></code>. In our experience they will deliver very similar performance
(speed), but if one is concerned they should just try both and see if one is faster.</p>
</section>
<section id="how-come-when-i-run-the-same-program-on-the-same-number-of-processes-i-get-a-different-answer">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How come when I run the same program on the same number of processes I get a “different” answer?</a><a class="headerlink" href="#how-come-when-i-run-the-same-program-on-the-same-number-of-processes-i-get-a-different-answer" title="Link to this heading">#</a></h3>
<p>Inner products and norms in PETSc are computed using the <code class="docutils notranslate"><span class="pre"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Allreduce.html#MPI_Allreduce">MPI_Allreduce</a>()</span></code> command. For
different runs the order at which values arrive at a given process (via MPI) can be in a
different order, thus the order in which some floating point arithmetic operations are
performed will be different. Since floating point arithmetic is not
associative, the computed quantity may be slightly different.</p>
<p>Over a run the many slight differences in the inner products and norms will effect all the
computed results. It is important to realize that none of the computed answers are any
less right or wrong (in fact the sequential computation is no more right then the parallel
ones). All answers are equal, but some are more equal than others.</p>
<p>The discussion above assumes that the exact same algorithm is being used on the different
number of processes. When the algorithm is different for the different number of processes
(almost all preconditioner algorithms except Jacobi are different for different number of
processes) then one expects to see (and does) a greater difference in results for
different numbers of processes. In some cases (for example block Jacobi preconditioner) it
may be that the algorithm works for some number of processes and does not work for others.</p>
</section>
<section id="how-come-when-i-run-the-same-linear-solver-on-a-different-number-of-processes-it-takes-a-different-number-of-iterations">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How come when I run the same linear solver on a different number of processes it takes a different number of iterations?</a><a class="headerlink" href="#how-come-when-i-run-the-same-linear-solver-on-a-different-number-of-processes-it-takes-a-different-number-of-iterations" title="Link to this heading">#</a></h3>
<p>The convergence of many of the preconditioners in PETSc including the default parallel
preconditioner block Jacobi depends on the number of processes. The more processes the
(slightly) slower convergence it has. This is the nature of iterative solvers, the more
parallelism means the more “older” information is used in the solution process hence
slower convergence.</p>
</section>
<section id="can-petsc-use-gpus-to-speed-up-computations">
<span id="doc-faq-gpuhowto"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can PETSc use GPUs to speed up computations?</a><a class="headerlink" href="#can-petsc-use-gpus-to-speed-up-computations" title="Link to this heading">#</a></h3>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>See GPU development <a class="reference internal" href="../overview/gpu_roadmap.html#doc-gpu-roadmap"><span class="std std-ref">roadmap</span></a> for the latest information
regarding the state of PETSc GPU integration.</p>
<p>See GPU install <a class="reference internal" href="../install/install.html#doc-config-accel"><span class="std std-ref">documentation</span></a> for up-to-date information on
installing PETSc to use GPU’s.</p>
</div>
<p>Quick summary of usage with CUDA:</p>
<ul class="simple">
<li><p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecType.html">VecType</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VECSEQCUDA.html">VECSEQCUDA</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VECMPICUDA.html">VECMPICUDA</a></span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VECCUDA.html">VECCUDA</a></span></code> may be used with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetType.html">VecSetType</a>()</span></code> or <code class="docutils notranslate"><span class="pre">-vec_type</span> <span class="pre">seqcuda</span></code>, <code class="docutils notranslate"><span class="pre">mpicuda</span></code>, or <code class="docutils notranslate"><span class="pre">cuda</span></code> when
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetFromOptions.html">VecSetFromOptions</a>()</span></code> is used.</p></li>
<li><p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatType.html">MatType</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQAIJCUSPARSE.html">MATSEQAIJCUSPARSE</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMPIAIJCUSPARSE.html">MATMPIAIJCUSPARSE</a></span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJCUSPARSE.html">MATAIJCUSPARSE</a></span></code>
may be used with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetType.html">MatSetType</a>()</span></code> or <code class="docutils notranslate"><span class="pre">-mat_type</span> <span class="pre">seqaijcusparse</span></code>, <code class="docutils notranslate"><span class="pre">mpiaijcusparse</span></code>, or
<code class="docutils notranslate"><span class="pre">aijcusparse</span></code> when <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetFromOptions.html">MatSetFromOptions</a>()</span></code> is used.</p></li>
<li><p>If you are creating the vectors and matrices with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, you can use <code class="docutils notranslate"><span class="pre">-dm_vec_type</span> <span class="pre">cuda</span></code> and <code class="docutils notranslate"><span class="pre">-dm_mat_type</span> <span class="pre">aijcusparse</span></code>.</p></li>
</ul>
<p>Quick summary of usage with OpenCL (provided by the ViennaCL library):</p>
<ul class="simple">
<li><p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecType.html">VecType</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VECSEQVIENNACL.html">VECSEQVIENNACL</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VECMPIVIENNACL.html">VECMPIVIENNACL</a></span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VECVIENNACL.html">VECVIENNACL</a></span></code> may be used
with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetType.html">VecSetType</a>()</span></code> or <code class="docutils notranslate"><span class="pre">-vec_type</span> <span class="pre">seqviennacl</span></code>, <code class="docutils notranslate"><span class="pre">mpiviennacl</span></code>, or <code class="docutils notranslate"><span class="pre">viennacl</span></code>
when <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetFromOptions.html">VecSetFromOptions</a>()</span></code> is used.</p></li>
<li><p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatType.html">MatType</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQAIJVIENNACL.html">MATSEQAIJVIENNACL</a></span></code>, <code class="docutils notranslate"><span class="pre">MATMPIAIJVIENNACL</span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJVIENNACL.html">MATAIJVIENNACL</a></span></code>
may be used with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetType.html">MatSetType</a>()</span></code> or <code class="docutils notranslate"><span class="pre">-mat_type</span> <span class="pre">seqaijviennacl</span></code>, <code class="docutils notranslate"><span class="pre">mpiaijviennacl</span></code>, or
<code class="docutils notranslate"><span class="pre">aijviennacl</span></code> when <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetFromOptions.html">MatSetFromOptions</a>()</span></code> is used.</p></li>
<li><p>If you are creating the vectors and matrices with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, you can use <code class="docutils notranslate"><span class="pre">-dm_vec_type</span> <span class="pre">viennacl</span></code> and <code class="docutils notranslate"><span class="pre">-dm_mat_type</span> <span class="pre">aijviennacl</span></code>.</p></li>
</ul>
<p>General hints:</p>
<ul class="simple">
<li><p>It is useful to develop your code with the default vectors and then run production runs
with the command line options to use the GPU since debugging on GPUs is difficult.</p></li>
<li><p>All of the Krylov methods except <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPIBCGS.html">KSPIBCGS</a></span></code> run on the GPU.</p></li>
<li><p>Parts of most preconditioners run directly on the GPU. After setup, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> runs
fully on GPUs, without any memory copies between the CPU and GPU.</p></li>
</ul>
<p>Some GPU systems (for example many laptops) only run with single precision; thus, PETSc
must be built with the <code class="docutils notranslate"><span class="pre">configure</span></code> option <code class="docutils notranslate"><span class="pre">--with-precision=single</span></code>.</p>
</section>
<section id="can-i-run-petsc-with-extended-precision">
<span id="doc-faq-extendedprecision"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can I run PETSc with extended precision?</a><a class="headerlink" href="#can-i-run-petsc-with-extended-precision" title="Link to this heading">#</a></h3>
<p>Yes, with gcc and gfortran. <code class="docutils notranslate"><span class="pre">configure</span></code> PETSc using the
options <code class="docutils notranslate"><span class="pre">--with-precision=__float128</span></code> and <code class="docutils notranslate"><span class="pre">--download-f2cblaslapack</span></code>.</p>
<div class="yellow admonition">
<p class="admonition-title">Warning</p>
<p>External packages are not guaranteed to work in this mode!</p>
</div>
</section>
<section id="why-doesn-t-petsc-use-qd-to-implement-support-for-extended-precision">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why doesn’t PETSc use Qd to implement support for extended precision?</a><a class="headerlink" href="#why-doesn-t-petsc-use-qd-to-implement-support-for-extended-precision" title="Link to this heading">#</a></h3>
<p>We tried really hard but could not. The problem is that the QD c++ classes, though they
try to, implement the built-in data types of <code class="docutils notranslate"><span class="pre">double</span></code> are not native types and cannot
“just be used” in a general piece of numerical source code. Ratherm the code has to
rewritten to live within the limitations of QD classes. However PETSc can be built to use
quad precision, as detailed <a class="reference internal" href="#doc-faq-extendedprecision"><span class="std std-ref">here</span></a>.</p>
</section>
<section id="how-do-i-cite-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I cite PETSc?</a><a class="headerlink" href="#how-do-i-cite-petsc" title="Link to this heading">#</a></h3>
<p>Use <a class="reference internal" href="../index.html#doc-index-citing-petsc"><span class="std std-ref">these citations</span></a>.</p>
</section>
</section>
<hr class="docutils" />
<section id="installation">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Installation</a><a class="headerlink" href="#installation" title="Link to this heading">#</a></h2>
<section id="how-do-i-begin-using-petsc-if-the-software-has-already-been-completely-built-and-installed-by-someone-else">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I begin using PETSc if the software has already been completely built and installed by someone else?</a><a class="headerlink" href="#how-do-i-begin-using-petsc-if-the-software-has-already-been-completely-built-and-installed-by-someone-else" title="Link to this heading">#</a></h3>
<p>Assuming that the PETSc libraries have been successfully built for a particular
architecture and level of optimization, a new user must merely:</p>
<ol class="arabic simple">
<li><p>Set <code class="docutils notranslate"><span class="pre">PETSC_DIR</span></code> to the full path of the PETSc home
directory. This will be the location of the <code class="docutils notranslate"><span class="pre">configure</span></code> script, and usually called
“petsc” or some variation of that (for example, /home/username/petsc).</p></li>
<li><p>Set <code class="docutils notranslate"><span class="pre">PETSC_ARCH</span></code>, which indicates the configuration on which PETSc will be
used. Note that <code class="docutils notranslate"><span class="pre">$PETSC_ARCH</span></code> is simply a name the installer used when installing
the libraries. There will exist a directory within <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code> that is named after
its corresponding <code class="docutils notranslate"><span class="pre">$PETSC_ARCH</span></code>. There many be several on a single system, for
example “linux-c-debug” for the debug versions compiled by a C compiler or
“linux-c-opt” for the optimized version.</p></li>
</ol>
<div class="admonition-still-stuck admonition">
<p class="admonition-title">Still Stuck?</p>
<p>See the <a class="reference internal" href="../install/install_tutorial.html#tut-install"><span class="std std-ref">quick-start tutorial</span></a> for a step-by-step guide on
installing PETSc, in case you have missed a step.</p>
<p>See the users manual section on <a class="reference internal" href="../manual/getting_started.html#sec-getting-started"><span class="std std-ref">getting started</span></a>.</p>
</div>
</section>
<section id="the-petsc-distribution-is-so-large-how-can-i-reduce-my-disk-space-usage">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">The PETSc distribution is SO Large. How can I reduce my disk space usage?</a><a class="headerlink" href="#the-petsc-distribution-is-so-large-how-can-i-reduce-my-disk-space-usage" title="Link to this heading">#</a></h3>
<ol class="arabic simple">
<li><p>The PETSc users manual is provided in PDF format at <a class="reference external" href="https://petsc.org/release/manual/manual.pdf">
<span class="std std-ref">https://petsc.org/release/manual/manual.pdf</span></a>.</p></li>
<li><p>The PETSc test suite contains sample output for many of the examples. These are
contained in the PETSc directories <code class="docutils notranslate"><span class="pre">$PETSC_DIR/src/*/tutorials/output</span></code> and
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/src/*/tests/output</span></code>. Once you have run the test examples, you may remove
all of these directories to save some disk space. You can locate the largest with
e.g. <code class="docutils notranslate"><span class="pre">find</span> <span class="pre">.</span> <span class="pre">-name</span> <span class="pre">output</span> <span class="pre">-type</span> <span class="pre">d</span> <span class="pre">|</span> <span class="pre">xargs</span> <span class="pre">du</span> <span class="pre">-sh</span> <span class="pre">|</span> <span class="pre">sort</span> <span class="pre">-hr</span></code> on a Unix-based system.</p></li>
<li><p>The debugging versions of the libraries are larger than the optimized versions. In a
pinch you can work with the optimized version, although we bid you good luck in
finding bugs as it is much easier with the debug version.</p></li>
</ol>
</section>
<section id="i-want-to-use-petsc-only-for-uniprocessor-programs-must-i-still-install-and-use-a-version-of-mpi">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">I want to use PETSc only for uniprocessor programs. Must I still install and use a version of MPI?</a><a class="headerlink" href="#i-want-to-use-petsc-only-for-uniprocessor-programs-must-i-still-install-and-use-a-version-of-mpi" title="Link to this heading">#</a></h3>
<p>No, run <code class="docutils notranslate"><span class="pre">configure</span></code> with the option <code class="docutils notranslate"><span class="pre">--with-mpi=0</span></code></p>
</section>
<section id="can-i-install-petsc-to-not-use-x-windows-either-under-unix-or-microsoft-windows-with-gcc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can I install PETSc to not use X windows (either under Unix or Microsoft Windows with GCC)?</a><a class="headerlink" href="#can-i-install-petsc-to-not-use-x-windows-either-under-unix-or-microsoft-windows-with-gcc" title="Link to this heading">#</a></h3>
<p>Yes. Run <code class="docutils notranslate"><span class="pre">configure</span></code> with the additional flag <code class="docutils notranslate"><span class="pre">--with-x=0</span></code></p>
</section>
<section id="why-do-you-use-mpi">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why do you use MPI?</a><a class="headerlink" href="#why-do-you-use-mpi" title="Link to this heading">#</a></h3>
<p>MPI is the message-passing standard. Because it is a standard, it will not frequently change over
time; thus, we do not have to change PETSc every time the provider of the message-passing
system decides to make an interface change. MPI was carefully designed by experts from
industry, academia, and government labs to provide the highest quality performance and
capability.</p>
<p>For example, the careful design of communicators in MPI allows the easy nesting of
different libraries; no other message-passing system provides this support. All of the
major parallel computer vendors were involved in the design of MPI and have committed to
providing quality implementations.</p>
<p>In addition, since MPI is a standard, several different groups have already provided
complete free implementations. Thus, one does not have to rely on the technical skills of
one particular group to provide the message-passing libraries. Today, MPI is the only
practical, portable approach to writing efficient parallel numerical software.</p>
</section>
<section id="what-do-i-do-if-my-mpi-compiler-wrappers-are-invalid">
<span id="invalid-mpi-compilers"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What do I do if my MPI compiler wrappers are invalid?</a><a class="headerlink" href="#what-do-i-do-if-my-mpi-compiler-wrappers-are-invalid" title="Link to this heading">#</a></h3>
<p>Most MPI implementations provide compiler wrappers (such as <code class="docutils notranslate"><span class="pre">mpicc</span></code>) which give the
include and link options necessary to use that version of MPI to the underlying compilers
. Configuration will fail if these wrappers are either absent or broken in the MPI pointed to by
<code class="docutils notranslate"><span class="pre">--with-mpi-dir</span></code>. You can rerun the configure with the additional option
<code class="docutils notranslate"><span class="pre">--with-mpi-compilers=0</span></code>, which will try to auto-detect working compilers; however,
these compilers may be incompatible with the particular MPI build. If this fix does not
work, run with <code class="docutils notranslate"><span class="pre">--with-cc=[your_c_compiler]</span></code> where you know <code class="docutils notranslate"><span class="pre">your_c_compiler</span></code> works
with this particular MPI, and likewise for C++ (<code class="docutils notranslate"><span class="pre">--with-cxx=[your_cxx_compiler]</span></code>) and Fortran
(<code class="docutils notranslate"><span class="pre">--with-fc=[your_fortran_compiler]</span></code>).</p>
</section>
<section id="when-should-can-i-use-the-configure-option-with-64-bit-indices">
<span id="bit-indices"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">When should/can I use the <code class="docutils notranslate"><span class="pre">configure</span></code> option <code class="docutils notranslate"><span class="pre">--with-64-bit-indices</span></code>?</a><a class="headerlink" href="#when-should-can-i-use-the-configure-option-with-64-bit-indices" title="Link to this heading">#</a></h3>
<p>By default the type that PETSc uses to index into arrays and keep sizes of arrays is a
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span></code> defined to be a 32-bit <code class="docutils notranslate"><span class="pre">int</span></code>. If your problem:</p>
<ul class="simple">
<li><p>Involves more than 2^31 - 1 unknowns (around 2 billion).</p></li>
<li><p>Your matrix might contain more than 2^31 - 1 nonzeros on a single process.</p></li>
</ul>
<p>Then you need to use this option. Otherwise you will get strange crashes.</p>
<p>This option can be used when you are using either 32 or 64-bit pointers. You do not
need to use this option if you are using 64-bit pointers unless the two conditions above
hold.</p>
</section>
<section id="what-if-i-get-an-internal-compiler-error">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What if I get an internal compiler error?</a><a class="headerlink" href="#what-if-i-get-an-internal-compiler-error" title="Link to this heading">#</a></h3>
<p>You can rebuild the offending file individually with a lower optimization level. <strong>Then
make sure to complain to the compiler vendor and file a bug report</strong>. For example, if the
compiler chokes on <code class="docutils notranslate"><span class="pre">src/mat/impls/baij/seq/baijsolvtrannat.c</span></code> you can run the following
from <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>-f<span class="w"> </span>gmakefile<span class="w"> </span><span class="nv">PCC_FLAGS</span><span class="o">=</span><span class="s2">&quot;-O1&quot;</span><span class="w"> </span><span class="nv">$PETSC_ARCH</span>/obj/src/mat/impls/baij/seq/baijsolvtrannat.o
<span class="gp">$ </span>make<span class="w"> </span>all
</pre></div>
</div>
</section>
<section id="how-do-i-enable-python-bindings-petsc4py-with-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I enable Python bindings (petsc4py) with PETSc?</a><a class="headerlink" href="#how-do-i-enable-python-bindings-petsc4py-with-petsc" title="Link to this heading">#</a></h3>
<ol class="arabic simple">
<li><p>Install <a class="reference external" href="https://cython.org/">Cython</a>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">configure</span></code> PETSc with the <code class="docutils notranslate"><span class="pre">--with-petsc4py=1</span></code> option.</p></li>
<li><p>set <code class="docutils notranslate"><span class="pre">PYTHONPATH=$PETSC_DIR/$PETSC_ARCH/lib</span></code></p></li>
</ol>
</section>
<section id="what-fortran-compiler-do-you-recommend-on-macos">
<span id="macos-gfortran"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What Fortran compiler do you recommend on macOS?</a><a class="headerlink" href="#what-fortran-compiler-do-you-recommend-on-macos" title="Link to this heading">#</a></h3>
<p>We recommend using <a class="reference external" href="https://brew.sh/">homebrew</a> to install <a class="reference external" href="https://gcc.gnu.org/wiki/GFortran">gfortran</a>, see <a class="reference internal" href="../install/install.html#doc-macos-install"><span class="std std-ref">Installing On macOS</span></a></p>
</section>
<section id="how-can-i-find-the-url-locations-of-the-packages-you-install-using-download-package">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I find the URL locations of the packages you install using <code class="docutils notranslate"><span class="pre">--download-PACKAGE</span></code>?</a><a class="headerlink" href="#how-can-i-find-the-url-locations-of-the-packages-you-install-using-download-package" title="Link to this heading">#</a></h3>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>grep<span class="w"> </span><span class="s2">&quot;self.download &quot;</span><span class="w"> </span><span class="nv">$PETSC_DIR</span>/config/BuildSystem/config/packages/*.py
</pre></div>
</div>
</section>
<section id="how-to-fix-the-problem-petsc-was-configured-with-one-mpich-or-open-mpi-mpi-h-version-but-now-appears-to-be-compiling-using-a-different-mpich-or-open-mpi-mpi-h-version">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How to fix the problem: PETSc was configured with one MPICH (or Open MPI) <code class="docutils notranslate"><span class="pre">mpi.h</span></code> version but now appears to be compiling using a different MPICH (or Open MPI) <code class="docutils notranslate"><span class="pre">mpi.h</span></code> version</a><a class="headerlink" href="#how-to-fix-the-problem-petsc-was-configured-with-one-mpich-or-open-mpi-mpi-h-version-but-now-appears-to-be-compiling-using-a-different-mpich-or-open-mpi-mpi-h-version" title="Link to this heading">#</a></h3>
<p>This happens for generally one of two reasons:</p>
<ul>
<li><p>You previously ran <code class="docutils notranslate"><span class="pre">configure</span></code> with the option <code class="docutils notranslate"><span class="pre">--download-mpich</span></code> (or <code class="docutils notranslate"><span class="pre">--download-openmpi</span></code>)
but later ran <code class="docutils notranslate"><span class="pre">configure</span></code> to use a version of MPI already installed on the
machine. Solution:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>rm<span class="w"> </span>-rf<span class="w"> </span><span class="nv">$PETSC_DIR</span>/<span class="nv">$PETSC_ARCH</span>
<span class="gp">$ </span>./configure<span class="w"> </span>--your-args
</pre></div>
</div>
</li>
</ul>
</section>
<section id="what-does-it-mean-when-make-check-hangs-or-errors-on-petscoptionsinsertfile">
<span id="mpi-network-misconfigure"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What does it mean when <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">check</span></code> hangs or errors on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsInsertFile.html">PetscOptionsInsertFile</a>()</span></code>?</a><a class="headerlink" href="#what-does-it-mean-when-make-check-hangs-or-errors-on-petscoptionsinsertfile" title="Link to this heading">#</a></h3>
<p>For example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Possible error running C/C++ src/snes/tutorials/ex19 with 2 MPI processes
See https://petsc.org/release/faq/
[0]PETSC ERROR: #1 <a href="../manualpages/Sys/PetscOptionsInsertFile.html">PetscOptionsInsertFile</a>() line 563 in /Users/barrysmith/Src/PETSc/src/sys/objects/options.c
[0]PETSC ERROR: #2 <a href="../manualpages/Sys/PetscOptionsInsert.html">PetscOptionsInsert</a>() line 720 in /Users/barrysmith/Src/PETSc/src/sys/objects/options.c
[0]PETSC ERROR: #3 <a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>() line 828 in /Users/barrysmith/Src/PETSc/src/sys/objects/pinit.c
</pre></div>
</div>
<p>or</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make check
Running check examples to verify correct installation
Using PETSC_DIR=/Users/barrysmith/Src/petsc and PETSC_ARCH=arch-fix-mpiexec-hang-2-ranks
C/C++ example src/snes/tutorials/ex19 run successfully with 1 MPI process
PROGRAM SEEMS TO BE HANGING HERE
</pre></div>
</div>
<p>This usually occurs when network settings are misconfigured (perhaps due to VPN) resulting in a failure or hang in system call <code class="docutils notranslate"><span class="pre">gethostbyname()</span></code>.</p>
<ul>
<li><p>Verify you are using the correct <code class="docutils notranslate"><span class="pre">mpiexec</span></code> for the MPI you have linked PETSc with.</p></li>
<li><p>If you have a VPN enabled on your machine, try turning it off and then running <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">check</span></code> to
verify that it is not the VPN playing poorly with MPI.</p></li>
<li><p>If  <code class="docutils notranslate"><span class="pre">ping</span> <span class="pre">`hostname`</span> </code> (<code class="docutils notranslate"><span class="pre">/sbin/ping</span></code> on macOS) fails or hangs do:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>echo 127.0.0.1 `hostname` | sudo tee -a /etc/hosts
</pre></div>
</div>
<p>and try <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">check</span></code> again.</p>
</li>
<li><p>Try completely disconnecting your machine from the network and see if <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">check</span></code> then works</p></li>
<li><p>Try the PETSc <code class="docutils notranslate"><span class="pre">configure</span></code> option <code class="docutils notranslate"><span class="pre">--download-mpich-device=ch3:nemesis</span></code> with <code class="docutils notranslate"><span class="pre">--download-mpich</span></code>.</p></li>
</ul>
</section>
</section>
<hr class="docutils" />
<section id="usage">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Usage</a><a class="headerlink" href="#usage" title="Link to this heading">#</a></h2>
<section id="how-can-i-redirect-petsc-s-stdout-and-stderr-when-programming-with-a-gui-interface-in-windows-developer-studio-or-to-c-streams">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I redirect PETSc’s <code class="docutils notranslate"><span class="pre">stdout</span></code> and <code class="docutils notranslate"><span class="pre">stderr</span></code> when programming with a GUI interface in Windows Developer Studio or to C++ streams?</a><a class="headerlink" href="#how-can-i-redirect-petsc-s-stdout-and-stderr-when-programming-with-a-gui-interface-in-windows-developer-studio-or-to-c-streams" title="Link to this heading">#</a></h3>
<p>To overload just the error messages write your own <code class="docutils notranslate"><span class="pre">MyPrintError()</span></code> function that does
whatever you want (including pop up windows etc) and use it like below.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span><span class="w"> </span><span class="s">&quot;C&quot;</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="kt">int</span><span class="w"> </span><span class="n">PASCAL</span><span class="w"> </span><span class="nf">WinMain</span><span class="p">(</span><span class="n">HINSTANCE</span><span class="p">,</span><span class="n">HINSTANCE</span><span class="p">,</span><span class="n">LPSTR</span><span class="p">,</span><span class="kt">int</span><span class="p">);</span>
<span class="p">};</span>

<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscsys.h&gt;</span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;mpi.h&gt;</span>

<span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">help</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Set up from main&quot;</span><span class="p">;</span>

<span class="kt">int</span><span class="w"> </span><span class="nf">MyPrintError</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">error</span><span class="p">[],</span><span class="w"> </span><span class="p">...)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;%s&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">error</span><span class="p">);</span>
<span class="w">  </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>

<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">ac</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">av</span><span class="p">[])</span>
<span class="p">{</span>
<span class="w">  </span><span class="kt">char</span><span class="w">           </span><span class="n">buf</span><span class="p">[</span><span class="mi">256</span><span class="p">];</span>
<span class="w">  </span><span class="n">HINSTANCE</span><span class="w">      </span><span class="n">inst</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="n">ierr</span><span class="p">;</span>

<span class="w">  </span><span class="n">inst</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">HINSTANCE</span><span class="p">)</span><span class="n">GetModuleHandle</span><span class="p">(</span><span class="nb">NULL</span><span class="p">);</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscErrorPrintf.html">PetscErrorPrintf</a></span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">MyPrintError</span><span class="p">;</span>

<span class="w">  </span><span class="n">buf</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="w">  </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">ac</span><span class="p">;</span><span class="w"> </span><span class="o">++</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n">strcat</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">av</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
<span class="w">    </span><span class="n">strcat</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; &quot;</span><span class="p">);</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">ac</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">av</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">help</span><span class="p">));</span>

<span class="w">  </span><span class="k">return</span><span class="w"> </span><span class="n">WinMain</span><span class="p">(</span><span class="n">inst</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">SW_SHOWNORMAL</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Place this file in the project and compile with this preprocessor definitions:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">WIN32</span>
<span class="n">_DEBUG</span>
<span class="n">_CONSOLE</span>
<span class="n">_MBCS</span>
<span class="n">USE_PETSC_LOG</span>
<span class="n">USE_PETSC_BOPT_g</span>
<span class="n">USE_PETSC_STACK</span>
<span class="n">_AFXDLL</span>
</pre></div>
</div>
<p>And these link options:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">nologo</span>
<span class="o">/</span><span class="n">subsystem</span><span class="o">:</span><span class="n">console</span>
<span class="o">/</span><span class="n">incremental</span><span class="o">:</span><span class="n">yes</span>
<span class="o">/</span><span class="n">debug</span>
<span class="o">/</span><span class="n">machine</span><span class="o">:</span><span class="n">I386</span>
<span class="o">/</span><span class="n">nodefaultlib</span><span class="o">:</span><span class="s">&quot;libcmtd.lib&quot;</span>
<span class="o">/</span><span class="n">nodefaultlib</span><span class="o">:</span><span class="s">&quot;libcd.lib&quot;</span>
<span class="o">/</span><span class="n">nodefaultlib</span><span class="o">:</span><span class="s">&quot;mvcrt.lib&quot;</span>
<span class="o">/</span><span class="n">pdbtype</span><span class="o">:</span><span class="n">sept</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The above is compiled and linked as if it was a console program. The linker will search
for a main, and then from it the <code class="docutils notranslate"><span class="pre">WinMain</span></code> will start. This works with MFC templates and
derived classes too.</p>
<p>When writing a Window’s console application you do not need to do anything, the <code class="docutils notranslate"><span class="pre">stdout</span></code>
and <code class="docutils notranslate"><span class="pre">stderr</span></code> is automatically output to the console window.</p>
</div>
<p>To change where all PETSc <code class="docutils notranslate"><span class="pre">stdout</span></code> and <code class="docutils notranslate"><span class="pre">stderr</span></code> go, (you can also reassign
<code class="docutils notranslate"><span class="pre">PetscVFPrintf()</span></code> to handle <code class="docutils notranslate"><span class="pre">stdout</span></code> and <code class="docutils notranslate"><span class="pre">stderr</span></code> any way you like) write the
following function:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">mypetscvfprintf</span><span class="p">(</span><span class="kt">FILE</span><span class="w"> </span><span class="o">*</span><span class="n">fd</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">format</span><span class="p">[],</span><span class="w"> </span><span class="kt">va_list</span><span class="w"> </span><span class="n">Argp</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">fd</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">stdout</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="n">fd</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">stderr</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* handle regular files */</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscVFPrintfDefault.html">PetscVFPrintfDefault</a></span><span class="p">(</span><span class="n">fd</span><span class="p">,</span><span class="w"> </span><span class="n">format</span><span class="p">,</span><span class="w"> </span><span class="n">Argp</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="kt">char</span><span class="w"> </span><span class="n">buff</span><span class="p">[</span><span class="mi">1024</span><span class="p">];</span><span class="w"> </span><span class="cm">/* Make sure to assign a large enough buffer */</span>
<span class="w">    </span><span class="kt">int</span><span class="w">  </span><span class="n">length</span><span class="p">;</span>

<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscVSNPrintf.html">PetscVSNPrintf</a></span><span class="p">(</span><span class="n">buff</span><span class="p">,</span><span class="w"> </span><span class="mi">1024</span><span class="p">,</span><span class="w"> </span><span class="n">format</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">length</span><span class="p">,</span><span class="w"> </span><span class="n">Argp</span><span class="p">));</span>

<span class="w">    </span><span class="cm">/* now send buff to whatever stream or whatever you want */</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then assign <code class="docutils notranslate"><span class="pre">PetscVFPrintf</span> <span class="pre">=</span> <span class="pre">mypetscprintf</span></code> before <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code> in your main
program.</p>
</section>
<section id="i-want-to-use-hypre-boomeramg-without-gmres-but-when-i-run-pc-type-hypre-pc-hypre-type-boomeramg-ksp-type-preonly-i-don-t-get-a-very-accurate-answer">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">I want to use Hypre boomerAMG without GMRES but when I run <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">boomeramg</span> <span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> I don’t get a very accurate answer!</a><a class="headerlink" href="#i-want-to-use-hypre-boomeramg-without-gmres-but-when-i-run-pc-type-hypre-pc-hypre-type-boomeramg-ksp-type-preonly-i-don-t-get-a-very-accurate-answer" title="Link to this heading">#</a></h3>
<p>You should run with <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">richardson</span></code> to have PETSc run several V or W
cycles. <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> causes boomerAMG to use only one V/W cycle. You can control
how many cycles are used in a single application of the boomerAMG preconditioner with
<code class="docutils notranslate"><span class="pre">-pc_hypre_boomeramg_max_iter</span> <span class="pre">&lt;it&gt;</span></code> (the default is 1). You can also control the
tolerance boomerAMG uses to decide if to stop before <code class="docutils notranslate"><span class="pre">max_iter</span></code> with
<code class="docutils notranslate"><span class="pre">-pc_hypre_boomeramg_tol</span> <span class="pre">&lt;tol&gt;</span></code> (the default is 1.e-7). Run with <code class="docutils notranslate"><span class="pre">-ksp_view</span></code> to see
all the hypre options used and <code class="docutils notranslate"><span class="pre">-help</span> <span class="pre">|</span> <span class="pre">grep</span> <span class="pre">boomeramg</span></code> to see all the command line
options.</p>
</section>
<section id="how-do-i-use-petsc-for-domain-decomposition">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I use PETSc for Domain Decomposition?</a><a class="headerlink" href="#how-do-i-use-petsc-for-domain-decomposition" title="Link to this heading">#</a></h3>
<p>PETSc includes Additive Schwarz methods in the suite of preconditioners under the umbrella
of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>. These may be activated with the runtime option <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">asm</span></code>. Various
other options may be set, including the degree of overlap <code class="docutils notranslate"><span class="pre">-pc_asm_overlap</span> <span class="pre">&lt;number&gt;</span></code> the
type of restriction/extension <code class="docutils notranslate"><span class="pre">-pc_asm_type</span> <span class="pre">[basic,restrict,interpolate,none]</span></code> sets ASM
type and several others. You may see the available ASM options by using <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">asm</span> <span class="pre">-help</span></code>. See the procedural interfaces in the manual pages, for example <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PCASMType</a>()</span></code>
and check the index of the users manual for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMCreateSubdomains.html">PCASMCreateSubdomains</a>()</span></code>.</p>
<p>PETSc also contains a domain decomposition inspired wirebasket or face based two level
method where the coarse mesh to fine mesh interpolation is defined by solving specific
local subdomain problems. It currently only works for 3D scalar problems on structured
grids created with PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>. See the manual page for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCEXOTIC.html">PCEXOTIC</a></span></code> and
<code class="docutils notranslate"><span class="pre">src/ksp/ksp/tutorials/ex45.c</span></code> for an example.</p>
<p>PETSc also contains a balancing Neumann-Neumann type preconditioner, see the manual page
for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>. This requires matrices be constructed with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateIS.html">MatCreateIS</a>()</span></code> via the finite
element method. See <code class="docutils notranslate"><span class="pre">src/ksp/ksp/tests/ex59.c</span></code> for an example.</p>
</section>
<section id="you-have-mataij-and-matbaij-matrix-formats-and-matsbaij-for-symmetric-storage-how-come-no-matsaij">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">You have <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> matrix formats, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSBAIJ.html">MATSBAIJ</a></span></code> for symmetric storage, how come no <code class="docutils notranslate"><span class="pre">MATSAIJ</span></code>?</a><a class="headerlink" href="#you-have-mataij-and-matbaij-matrix-formats-and-matsbaij-for-symmetric-storage-how-come-no-matsaij" title="Link to this heading">#</a></h3>
<p>Just for historical reasons; the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSBAIJ.html">MATSBAIJ</a></span></code> format with blocksize one is just as efficient as
a <code class="docutils notranslate"><span class="pre">MATSAIJ</span></code> would be.</p>
</section>
<section id="can-i-create-baij-matrices-with-different-size-blocks-for-different-block-rows">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can I Create BAIJ matrices with different size blocks for different block rows?</a><a class="headerlink" href="#can-i-create-baij-matrices-with-different-size-blocks-for-different-block-rows" title="Link to this heading">#</a></h3>
<p>No. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> format only supports a single fixed block size on the entire
matrix. But the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> format automatically searches for matching rows and thus still
takes advantage of the natural blocks in your matrix to obtain good performance.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> you cannot use the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValuesBlocked.html">MatSetValuesBlocked</a>()</span></code>.</p>
</div>
</section>
<section id="how-do-i-access-the-values-of-a-remote-parallel-petsc-vec">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I access the values of a remote parallel PETSc Vec?</a><a class="headerlink" href="#how-do-i-access-the-values-of-a-remote-parallel-petsc-vec" title="Link to this heading">#</a></h3>
<ol class="arabic simple">
<li><p>On each process create a local <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> large enough to hold all the values it wishes to
access.</p></li>
<li><p>Create a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span></code> that scatters from the parallel <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> into the local <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code>.</p></li>
<li><p>Use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a>()</span></code> to access the values in the local <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code>.</p></li>
</ol>
<p>For example, assuming we have distributed a vector <code class="docutils notranslate"><span class="pre">vecGlobal</span></code> of size <span class="math">\(N\)</span> to
<span class="math">\(R\)</span> ranks and each remote rank holds <span class="math">\(N/R = m\)</span> values (similarly assume that
<span class="math">\(N\)</span> is cleanly divisible by <span class="math">\(R\)</span>). We want each rank <span class="math">\(r\)</span> to gather the
first <span class="math">\(n\)</span> (also assume <span class="math">\(n \leq m\)</span>) values from its immediately superior neighbor
<span class="math">\(r+1\)</span> (final rank will retrieve from rank 0).</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">            </span><span class="n">vecLocal</span><span class="p">;</span>
<span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w">             </span><span class="n">isLocal</span><span class="p">,</span><span class="w"> </span><span class="n">isGlobal</span><span class="p">;</span>
<span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w">     </span><span class="n">ctx</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">    </span><span class="o">*</span><span class="n">arr</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w">       </span><span class="n">N</span><span class="p">,</span><span class="w"> </span><span class="n">firstGlobalIndex</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w">       </span><span class="n">comm</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/PetscMPIInt.html">PetscMPIInt</a></span><span class="w">    </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n">R</span><span class="p">;</span>

<span class="cm">/* Create sequential local vector, big enough to hold local portion */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecCreateSeq.html">VecCreateSeq</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_SELF.html">PETSC_COMM_SELF</a></span><span class="p">,</span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">vecLocal</span><span class="p">));</span>

<span class="cm">/* Create <a href="../manualpages/IS/IS.html">IS</a> to describe where we want to scatter to */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISCreateStride.html">ISCreateStride</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_SELF.html">PETSC_COMM_SELF</a></span><span class="p">,</span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">isLocal</span><span class="p">));</span>

<span class="cm">/* Compute the global indices */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetSize.html">VecGetSize</a></span><span class="p">(</span><span class="n">vecGlobal</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">N</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectGetComm.html">PetscObjectGetComm</a></span><span class="p">((</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">)</span><span class="w"> </span><span class="n">vecGlobal</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">comm</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_rank.html#MPI_Comm_rank">MPI_Comm_rank</a></span><span class="p">(</span><span class="n">comm</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">r</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_size.html#MPI_Comm_size">MPI_Comm_size</a></span><span class="p">(</span><span class="n">comm</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">R</span><span class="p">));</span>
<span class="n">firstGlobalIndex</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">R</span><span class="mi">-1</span><span class="w"> </span><span class="o">?</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="p">(</span><span class="n">N</span><span class="o">/</span><span class="n">R</span><span class="p">)</span><span class="o">*</span><span class="p">(</span><span class="n">r</span><span class="o">+</span><span class="mi">1</span><span class="p">);</span>

<span class="cm">/* Create <a href="../manualpages/IS/IS.html">IS</a> that describes where we want to scatter from */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISCreateStride.html">ISCreateStride</a></span><span class="p">(</span><span class="n">comm</span><span class="p">,</span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="w"> </span><span class="n">firstGlobalIndex</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">isGlobal</span><span class="p">));</span>

<span class="cm">/* Create the <a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a> context */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a></span><span class="p">(</span><span class="n">vecGlobal</span><span class="p">,</span><span class="w"> </span><span class="n">isGlobal</span><span class="p">,</span><span class="w"> </span><span class="n">vecLocal</span><span class="p">,</span><span class="w"> </span><span class="n">isLocal</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">));</span>

<span class="cm">/* Gather the values */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n">vecGlobal</span><span class="p">,</span><span class="w"> </span><span class="n">vecLocal</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n">vecGlobal</span><span class="p">,</span><span class="w"> </span><span class="n">vecLocal</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">));</span>

<span class="cm">/* Retrieve and do work */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a></span><span class="p">(</span><span class="n">vecLocal</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">arr</span><span class="p">));</span>
<span class="cm">/* Work */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a></span><span class="p">(</span><span class="n">vecLocal</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">arr</span><span class="p">));</span>

<span class="cm">/* Don&#39;t forget to clean up */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISDestroy.html">ISDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">isLocal</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISDestroy.html">ISDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">isGlobal</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterDestroy.html">VecScatterDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">vecLocal</span><span class="p">));</span>
</pre></div>
</div>
</section>
<section id="how-do-i-collect-to-a-single-processor-all-the-values-from-a-parallel-petsc-vec">
<span id="doc-faq-usage-alltoone"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I collect to a single processor all the values from a parallel PETSc Vec?</a><a class="headerlink" href="#how-do-i-collect-to-a-single-processor-all-the-values-from-a-parallel-petsc-vec" title="Link to this heading">#</a></h3>
<ol class="arabic">
<li><p>Create the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span></code> context that will do the communication:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">        </span><span class="n">in_par</span><span class="p">,</span><span class="n">out_seq</span><span class="p">;</span>
<span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">;</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterCreateToAll.html">VecScatterCreateToAll</a></span><span class="p">(</span><span class="n">in_par</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">out_seq</span><span class="p">));</span>
</pre></div>
</div>
</li>
<li><p>Initiate the communication (this may be repeated if you wish):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n">in_par</span><span class="p">,</span><span class="w"> </span><span class="n">out_seq</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n">in_par</span><span class="p">,</span><span class="w"> </span><span class="n">out_seq</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">));</span>
<span class="cm">/* May destroy context now if no additional scatters are needed, otherwise reuse it */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterDestroy.html">VecScatterDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">));</span>
</pre></div>
</div>
</li>
</ol>
<p>Note that this simply concatenates in the parallel ordering of the vector (computed by the
<code class="docutils notranslate"><span class="pre"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_rank.html#MPI_Comm_rank">MPI_Comm_rank</a></span></code> of the owning process). If you are using a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> from
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a>()</span></code> you likely want to first call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAGlobalToNaturalBegin.html">DMDAGlobalToNaturalBegin</a>()</span></code>
followed by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAGlobalToNaturalEnd.html">DMDAGlobalToNaturalEnd</a>()</span></code> to scatter the original <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> into the natural
ordering in a new global <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> before calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a>()</span></code>/<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a>()</span></code>
to scatter the natural <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> onto all processes.</p>
</section>
<section id="how-do-i-collect-all-the-values-from-a-parallel-petsc-vec-on-the-0th-rank">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I collect all the values from a parallel PETSc Vec on the 0th rank?</a><a class="headerlink" href="#how-do-i-collect-all-the-values-from-a-parallel-petsc-vec-on-the-0th-rank" title="Link to this heading">#</a></h3>
<p>See FAQ entry on collecting to <a class="reference internal" href="#doc-faq-usage-alltoone"><span class="std std-ref">an arbitrary processor</span></a>, but
replace</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterCreateToAll.html">VecScatterCreateToAll</a></span><span class="p">(</span><span class="n">in_par</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">out_seq</span><span class="p">));</span>
</pre></div>
</div>
<p>with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecScatterCreateToZero.html">VecScatterCreateToZero</a></span><span class="p">(</span><span class="n">in_par</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">out_seq</span><span class="p">));</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The same ordering considerations as discussed in the aforementioned entry also apply
here.</p>
</div>
</section>
<section id="how-can-i-read-in-or-write-out-a-sparse-matrix-in-matrix-market-harwell-boeing-slapc-or-other-ascii-format">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I read in or write out a sparse matrix in Matrix Market, Harwell-Boeing, Slapc or other ASCII format?</a><a class="headerlink" href="#how-can-i-read-in-or-write-out-a-sparse-matrix-in-matrix-market-harwell-boeing-slapc-or-other-ascii-format" title="Link to this heading">#</a></h3>
<p>If you can read or write your matrix using Python or MATLAB/Octave, <code class="docutils notranslate"><span class="pre">PetscBinaryIO</span></code>
modules are provided at <code class="docutils notranslate"><span class="pre">$PETSC_DIR/lib/petsc/bin</span></code> for each language that can assist
with reading and writing. If you just want to convert <code class="docutils notranslate"><span class="pre">MatrixMarket</span></code>, you can use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span><span class="nv">$PETSC_DIR</span>/lib/petsc/bin/PetscBinaryIO<span class="w"> </span>convert<span class="w"> </span>matrix.mtx
</pre></div>
</div>
<p>To produce <code class="docutils notranslate"><span class="pre">matrix.petsc</span></code>.</p>
<p>You can also call the script directly or import it from your Python code. There is also a
<code class="docutils notranslate"><span class="pre">PETScBinaryIO.jl</span></code> Julia package.</p>
<p>For other formats, either adapt one of the above libraries or see the examples in
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/src/mat/tests</span></code>, specifically <code class="docutils notranslate"><span class="pre">ex72.c</span></code> or <code class="docutils notranslate"><span class="pre">ex78.c</span></code>. You will likely need
to modify the code slightly to match your required ASCII format.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Never read or write in parallel an ASCII matrix file.</p>
<p>Instead read in sequentially with a standalone code based on <code class="docutils notranslate"><span class="pre">ex72.c</span></code> or <code class="docutils notranslate"><span class="pre">ex78.c</span></code>
then save the matrix with the binary viewer <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinaryOpen.html">PetscViewerBinaryOpen</a>()</span></code> and load the
matrix in parallel in your “real” PETSc program with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLoad.html">MatLoad</a>()</span></code>.</p>
<p>For writing save with the binary viewer and then load with the sequential code to store
it as ASCII.</p>
</div>
</section>
<section id="does-tssetfromoptions-snessetfromoptions-or-kspsetfromoptions-reset-all-the-parameters-i-previously-set-or-how-come-do-they-not-seem-to-work">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Does TSSetFromOptions(), SNESSetFromOptions(), or KSPSetFromOptions() reset all the parameters I previously set or how come do they not seem to work?</a><a class="headerlink" href="#does-tssetfromoptions-snessetfromoptions-or-kspsetfromoptions-reset-all-the-parameters-i-previously-set-or-how-come-do-they-not-seem-to-work" title="Link to this heading">#</a></h3>
<p>If <code class="docutils notranslate"><span class="pre">XXSetFromOptions()</span></code> is used (with <code class="docutils notranslate"><span class="pre">-xxx_type</span> <span class="pre">aaaa</span></code>) to change the type of the
object then all parameters associated with the previous type are removed. Otherwise it
does not reset parameters.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a>/<a href="../manualpages/SNES/SNES.html">SNES</a>/KSPSetXXX()</span></code> commands that set properties for a particular type of object (such
as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRESSetRestart.html">KSPGMRESSetRestart</a>()</span></code>) ONLY work if the object is ALREADY of that type. For example,
with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">;</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSPCreate.html">KSPCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSPGMRESSetRestart.html">KSPGMRESSetRestart</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">));</span>
</pre></div>
</div>
<p>the restart will be ignored since the type has not yet been set to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRES.html">KSPGMRES</a></span></code>. To have
those values take effect you should do one of the following:</p>
<ul class="simple">
<li><p>Allow setting the type from the command line, if it is not on the command line then the
default type is automatically set.</p></li>
</ul>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Create generic object */</span>
<span class="n">XXXCreate</span><span class="p">(..,</span><span class="o">&amp;</span><span class="n">obj</span><span class="p">);</span>
<span class="cm">/* Must set all settings here, or default */</span>
<span class="n">XXXSetFromOptions</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Hardwire the type in the code, but allow the user to override it via a subsequent
<code class="docutils notranslate"><span class="pre">XXXSetFromOptions()</span></code> call. This essentially allows the user to customize what the
“default” type to of the object.</p></li>
</ul>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Create generic object */</span>
<span class="n">XXXCreate</span><span class="p">(..,</span><span class="o">&amp;</span><span class="n">obj</span><span class="p">);</span>
<span class="cm">/* Set type directly */</span>
<span class="n">XXXSetYYYYY</span><span class="p">(</span><span class="n">obj</span><span class="p">,...);</span>
<span class="cm">/* Can always change to different type */</span>
<span class="n">XXXSetFromOptions</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="how-do-i-compile-and-link-my-own-petsc-application-codes-and-can-i-use-my-own-makefile-or-rules-for-compiling-code-rather-than-petsc-s">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I compile and link my own PETSc application codes and can I use my own <code class="docutils notranslate"><span class="pre">makefile</span></code> or rules for compiling code, rather than PETSc’s?</a><a class="headerlink" href="#how-do-i-compile-and-link-my-own-petsc-application-codes-and-can-i-use-my-own-makefile-or-rules-for-compiling-code-rather-than-petsc-s" title="Link to this heading">#</a></h3>
<p>See the <a class="reference internal" href="../manual/getting_started.html#sec-writing-application-codes"><span class="std std-ref">section</span></a> of the users manual on writing
application codes with PETSc.</p>
</section>
<section id="can-i-use-cmake-to-build-my-own-project-that-depends-on-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can I use CMake to build my own project that depends on PETSc?</a><a class="headerlink" href="#can-i-use-cmake-to-build-my-own-project-that-depends-on-petsc" title="Link to this heading">#</a></h3>
<p>See the <a class="reference internal" href="../manual/getting_started.html#sec-writing-application-codes"><span class="std std-ref">section</span></a> of the users manual on writing
application codes with PETSc.</p>
</section>
<section id="how-can-i-put-carriage-returns-in-petscprintf-statements-from-fortran">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I put carriage returns in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a>()</span></code> statements from Fortran?</a><a class="headerlink" href="#how-can-i-put-carriage-returns-in-petscprintf-statements-from-fortran" title="Link to this heading">#</a></h3>
<p>You can use the same notation as in C, just put a <code class="docutils notranslate"><span class="pre">\n</span></code> in the string. Note that no other C
format instruction is supported.</p>
<p>Or you can use the Fortran concatenation <code class="docutils notranslate"><span class="pre">//</span></code> and <code class="docutils notranslate"><span class="pre">char(10)</span></code>; for example <code class="docutils notranslate"><span class="pre">'some</span> <span class="pre">string'//char(10)//'another</span> <span class="pre">string</span></code> on the next line.</p>
</section>
<section id="how-can-i-implement-callbacks-using-c-class-methods">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I implement callbacks using C++ class methods?</a><a class="headerlink" href="#how-can-i-implement-callbacks-using-c-class-methods" title="Link to this heading">#</a></h3>
<p>Declare the class method static. Static methods do not have a <code class="docutils notranslate"><span class="pre">this</span></code> pointer, but the
<code class="docutils notranslate"><span class="pre">void*</span></code> context parameter will usually be cast to a pointer to the class where it can
serve the same function.</p>
<div class="admonition-remember admonition">
<p class="admonition-title">Remember</p>
<p>All PETSc callbacks return <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span></code>.</p>
</div>
</section>
<section id="everyone-knows-that-when-you-code-newton-s-method-you-should-compute-the-function-and-its-jacobian-at-the-same-time-how-can-one-do-this-in-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Everyone knows that when you code Newton’s Method you should compute the function and its Jacobian at the same time. How can one do this in PETSc?</a><a class="headerlink" href="#everyone-knows-that-when-you-code-newton-s-method-you-should-compute-the-function-and-its-jacobian-at-the-same-time-how-can-one-do-this-in-petsc" title="Link to this heading">#</a></h3>
<p>The update in Newton’s method is computed as</p>
<div class="math">
\[
u^{n+1} = u^n - \lambda * \left[J(u^n)] * F(u^n) \right]^{\dagger}
\]</div>
<p>The reason PETSc doesn’t default to computing both the function and Jacobian at the same
time is:</p>
<ul class="simple">
<li><p>In order to do the line search <span class="math">\(F \left(u^n - \lambda * \text{step} \right)\)</span> may
need to be computed for several <span class="math">\(\lambda\)</span>. The Jacobian is not needed for each of
those and one does not know in advance which will be the final <span class="math">\(\lambda\)</span> until
after the function value is computed, so many extra Jacobians may be computed.</p></li>
<li><p>In the final step if <span class="math">\(|| F(u^p)||\)</span> satisfies the convergence criteria then a
Jacobian need not be computed.</p></li>
</ul>
<p>You are free to have your <code class="docutils notranslate"><span class="pre">FormFunction()</span></code> compute as much of the Jacobian at that point
as you like, keep the information in the user context (the final argument to
<code class="docutils notranslate"><span class="pre">FormFunction()</span></code> and <code class="docutils notranslate"><span class="pre">FormJacobian()</span></code>) and then retrieve the information in your
<code class="docutils notranslate"><span class="pre">FormJacobian()</span></code> function.</p>
</section>
<section id="computing-the-jacobian-or-preconditioner-is-time-consuming-is-there-any-way-to-compute-it-less-often">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Computing the Jacobian or preconditioner is time consuming. Is there any way to compute it less often?</a><a class="headerlink" href="#computing-the-jacobian-or-preconditioner-is-time-consuming-is-there-any-way-to-compute-it-less-often" title="Link to this heading">#</a></h3>
<p>PETSc has a variety of ways of lagging the computation of the Jacobian or the
preconditioner. They are documented in the manual page for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESComputeJacobian.html">SNESComputeJacobian</a>()</span></code>
and in the <a class="reference internal" href="../manual/snes.html#ch-snes"><span class="std std-ref">users manual</span></a>:</p>
<p>-s</p>
<p>nes_lag_jacobian</p>
<p>(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetLagJacobian.html">SNESSetLagJacobian</a>()</span></code>) How often Jacobian is rebuilt (use -1 to
never rebuild, use -2 to rebuild the next time requested and then
never again).</p>
<p>-s</p>
<p>nes_lag_jacobian_persists</p>
<p>(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetLagJacobianPersists.html">SNESSetLagJacobianPersists</a>()</span></code>) Forces lagging of Jacobian
through multiple <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> solves , same as passing -2 to
<code class="docutils notranslate"><span class="pre">-snes_lag_jacobian</span></code>. By default, each new <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> solve
normally triggers a recomputation of the Jacobian.</p>
<p>-s</p>
<p>nes_lag_preconditioner</p>
<p>(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetLagPreconditioner.html">SNESSetLagPreconditioner</a>()</span></code>) how often the preconditioner is
rebuilt. Note: if you are lagging the Jacobian the system will
know that the matrix has not changed and will not recompute the
(same) preconditioner.</p>
<p>-s</p>
<p>nes_lag_preconditioner_persists</p>
<p>(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetLagPreconditionerPersists.html">SNESSetLagPreconditionerPersists</a>()</span></code>) Preconditioner
lags through multiple <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> solves</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>These are often (but does not need to be) used in combination with
<code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code> which applies the fresh Jacobian matrix-free for every
matrix-vector product. Otherwise the out-of-date matrix vector product, computed with
the lagged Jacobian will be used.</p>
</div>
<p>By using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPMonitorSet.html">KSPMonitorSet</a>()</span></code> and/or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESMonitorSet.html">SNESMonitorSet</a>()</span></code> one can provide code that monitors the
convergence rate and automatically triggers an update of the Jacobian or preconditioner
based on decreasing convergence of the iterative method. For example if the number of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>
iterations doubles one might trigger a new computation of the Jacobian. Experimentation is
the only general purpose way to determine which approach is best for your problem.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>It is also vital to experiment on your true problem at the scale you will be solving
the problem since the performance benefits depend on the exact problem and the problem
size!</p>
</div>
</section>
<section id="how-can-i-use-newton-s-method-jacobian-free-can-i-difference-a-different-function-than-provided-with-snessetfunction">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I use Newton’s Method Jacobian free? Can I difference a different function than provided with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a>()</span></code>?</a><a class="headerlink" href="#how-can-i-use-newton-s-method-jacobian-free-can-i-difference-a-different-function-than-provided-with-snessetfunction" title="Link to this heading">#</a></h3>
<p>The simplest way is with the option <code class="docutils notranslate"><span class="pre">-snes_mf</span></code>, this will use finite differencing of the
function provided to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESComputeFunction.html">SNESComputeFunction</a>()</span></code> to approximate the action of Jacobian.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Since no matrix-representation of the Jacobian is provided the <code class="docutils notranslate"><span class="pre">-pc_type</span></code> used with
this option must be <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">none</span></code>. You may provide a custom preconditioner with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESGetKSP.html">SNESGetKSP</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGetPC.html">KSPGetPC</a>()</span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSetType.html">PCSetType</a>()</span></code> and use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSHELL.html">PCSHELL</a></span></code>.</p>
</div>
<p>The option <code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code> will use Jacobian free to apply the Jacobian (in the
Krylov solvers) but will use whatever matrix you provided with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code>
(assuming you set one) to compute the preconditioner.</p>
<p>To write the code (rather than use the options above) use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/MatCreateSNESMF.html">MatCreateSNESMF</a>()</span></code> and pass
the resulting matrix object to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code>.</p>
<p>For purely matrix-free (like <code class="docutils notranslate"><span class="pre">-snes_mf</span></code>) pass the matrix object for both matrix
arguments and pass the function <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/MatMFFDComputeJacobian.html">MatMFFDComputeJacobian</a>()</span></code>.</p>
<p>To provide your own approximate Jacobian matrix to compute the preconditioner (like
<code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code>), pass this other matrix as the second matrix argument to
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code>. Make sure your provided <code class="docutils notranslate"><span class="pre">computejacobian()</span></code> function calls
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a>()</span></code> separately on <strong>BOTH</strong> matrix arguments
to this function. See <code class="docutils notranslate"><span class="pre">src/snes/tests/ex7.c</span></code>.</p>
<p>To difference a different function than that passed to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code> to compute the
matrix-free Jacobian multiply call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMFFDSetFunction.html">MatMFFDSetFunction</a>()</span></code> to set that other function. See
<code class="docutils notranslate"><span class="pre">src/snes/tests/ex7.c.h</span></code>.</p>
</section>
<section id="how-can-i-determine-the-condition-number-of-a-matrix">
<span id="doc-faq-usage-condnum"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I determine the condition number of a matrix?</a><a class="headerlink" href="#how-can-i-determine-the-condition-number-of-a-matrix" title="Link to this heading">#</a></h3>
<p>For small matrices, the condition number can be reliably computed using</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-pc_type svd -pc_svd_monitor
</pre></div>
</div>
<p>For larger matrices, you can run with</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-pc_type none -ksp_type gmres -ksp_monitor_singular_value -ksp_gmres_restart 1000
</pre></div>
</div>
<p>to get approximations to the condition number of the operator. This will generally be
accurate for the largest singular values, but may overestimate the smallest singular value
unless the method has converged. Make sure to avoid restarts. To estimate the condition
number of the preconditioned operator, use <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">somepc</span></code> in the last command.</p>
<p>You can use <a class="reference external" href="https://slepc.upv.es">SLEPc</a> for highly scalable, efficient, and quality eigenvalue computations.</p>
</section>
<section id="how-can-i-compute-the-inverse-of-a-matrix-in-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I compute the inverse of a matrix in PETSc?</a><a class="headerlink" href="#how-can-i-compute-the-inverse-of-a-matrix-in-petsc" title="Link to this heading">#</a></h3>
<div class="yellow admonition">
<p class="admonition-title">Are you sure?</p>
<p>It is very expensive to compute the inverse of a matrix and very rarely needed in
practice. We highly recommend avoiding algorithms that need it.</p>
</div>
<p>The inverse of a matrix (dense or sparse) is essentially always dense, so begin by
creating a dense matrix B and fill it with the identity matrix (ones along the diagonal),
also create a dense matrix X of the same size that will hold the solution. Then factor the
matrix you wish to invert with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLUFactor.html">MatLUFactor</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCholeskyFactor.html">MatCholeskyFactor</a>()</span></code>, call the
result A. Then call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMatSolve.html">MatMatSolve</a>(A,B,X)</span></code> to compute the inverse into X. See also section
on <a class="reference internal" href="#how-can-i-compute-the-schur-complement"><span class="std std-ref">Schur's complement</span></a>.</p>
</section>
<section id="how-can-i-compute-the-schur-complement-in-petsc">
<span id="how-can-i-compute-the-schur-complement"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I compute the Schur complement in PETSc?</a><a class="headerlink" href="#how-can-i-compute-the-schur-complement-in-petsc" title="Link to this heading">#</a></h3>
<div class="yellow admonition">
<p class="admonition-title">Are you sure?</p>
<p>It is very expensive to compute the Schur complement of a matrix and very rarely needed
in practice. We highly recommend avoiding algorithms that need it.</p>
</div>
<p>The Schur complement of the matrix <span class="math">\(M \in \mathbb{R}^{\left(p+q \right) \times
\left(p + q \right)}\)</span></p>
<div class="math">
\[
M = \begin{bmatrix}
A & B \\
C & D
\end{bmatrix}
\]</div>
<p>where</p>
<div class="math">
\[
A \in \mathbb{R}^{p \times p}, \quad B \in \mathbb{R}^{p \times q}, \quad C \in \mathbb{R}^{q \times p}, \quad D \in \mathbb{R}^{q \times q}
\]</div>
<p>is given by</p>
<div class="math">
\[
S_D := A - BD^{-1}C \\
S_A := D - CA^{-1}B
\]</div>
<p>Like the inverse, the Schur complement of a matrix (dense or sparse) is essentially always
dense, so assuming you wish to calculate <span class="math">\(S_A = D - C \underbrace{
\overbrace{(A^{-1})}^{U} B}_{V}\)</span> begin by:</p>
<ol class="arabic simple">
<li><p>Forming a dense matrix <span class="math">\(B\)</span></p></li>
<li><p>Also create another dense matrix <span class="math">\(V\)</span> of the same size.</p></li>
<li><p>Then either factor the matrix <span class="math">\(A\)</span> directly with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLUFactor.html">MatLUFactor</a>()</span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCholeskyFactor.html">MatCholeskyFactor</a>()</span></code>, or use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatGetFactor.html">MatGetFactor</a>()</span></code> followed by
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLUFactorSymbolic.html">MatLUFactorSymbolic</a>()</span></code> followed by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLUFactorNumeric.html">MatLUFactorNumeric</a>()</span></code> if you wish to use and
external solver package like SuperLU_Dist. Call the result <span class="math">\(U\)</span>.</p></li>
<li><p>Then call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMatSolve.html">MatMatSolve</a>(U,B,V)</span></code>.</p></li>
<li><p>Then call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMatMult.html">MatMatMult</a>(C,V,<a href="../manualpages/Mat/MatReuse.html">MAT_INITIAL_MATRIX</a>,1.0,&amp;S)</span></code>.</p></li>
<li><p>Now call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatAXPY.html">MatAXPY</a>(S,-1.0,D,MAT_SUBSET_NONZERO)</span></code>.</p></li>
<li><p>Followed by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatScale.html">MatScale</a>(S,-1.0)</span></code>.</p></li>
</ol>
<p>For computing Schur complements like this it does not make sense to use the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>
iterative solvers since for solving many moderate size problems using a direct
factorization is much faster than iterative solvers. As you can see, this requires a great
deal of work space and computation so is best avoided.</p>
<p>However, it is not necessary to assemble the Schur complement <span class="math">\(S\)</span> in order to solve
systems with it. Use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/MatCreateSchurComplement.html">MatCreateSchurComplement</a>(A,A_pre,B,C,D,&amp;S)</span></code> to create a
matrix that applies the action of <span class="math">\(S\)</span> (using <code class="docutils notranslate"><span class="pre">A_pre</span></code> to solve with <code class="docutils notranslate"><span class="pre">A</span></code>), but
does not assemble.</p>
<p>Alternatively, if you already have a block matrix <code class="docutils notranslate"><span class="pre">M</span> <span class="pre">=</span> <span class="pre">[A,</span> <span class="pre">B;</span> <span class="pre">C,</span> <span class="pre">D]</span></code> (in some
ordering), then you can create index sets (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code>) <code class="docutils notranslate"><span class="pre">isa</span></code> and <code class="docutils notranslate"><span class="pre">isb</span></code> to address each
block, then use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/MatGetSchurComplement.html">MatGetSchurComplement</a>()</span></code> to create the Schur complement and/or an
approximation suitable for preconditioning.</p>
<p>Since <span class="math">\(S\)</span> is generally dense, standard preconditioning methods cannot typically be
applied directly to Schur complements. There are many approaches to preconditioning Schur
complements including using the <code class="docutils notranslate"><span class="pre">SIMPLE</span></code> approximation</p>
<div class="math">
\[
D - C \text{diag}(A)^{-1} B
\]</div>
<p>to create a sparse matrix that approximates the Schur complement (this is returned by
default for the optional “preconditioning” matrix in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/MatGetSchurComplement.html">MatGetSchurComplement</a>()</span></code>).</p>
<p>An alternative is to interpret the matrices as differential operators and apply
approximate commutator arguments to find a spectrally equivalent operation that can be
applied efficiently (see the “PCD” preconditioners <span id="id1">[<a class="reference internal" href="#id2256" title="Howard C. Elman, David J. Silvester, and Andrew J. Wathen. Finite elements and fast iterative solvers: with applications in incompressible fluid dynamics. Oxford University Press, 2014. URL: https://global.oup.com/academic/product/finite-elements-and-fast-iterative-solvers-9780199678792?cc=us&amp;lang=en&amp;.">ESW14</a>]</span>). A
variant of this is the least squares commutator, which is closely related to the
Moore-Penrose pseudoinverse, and is available in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLSC.html">PCLSC</a></span></code> which operates on matrices of
type <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/MATSCHURCOMPLEMENT.html">MATSCHURCOMPLEMENT</a></span></code>.</p>
</section>
<section id="do-you-have-examples-of-doing-unstructured-grid-finite-element-method-fem-with-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Do you have examples of doing unstructured grid Finite Element Method (FEM) with PETSc?</a><a class="headerlink" href="#do-you-have-examples-of-doing-unstructured-grid-finite-element-method-fem-with-petsc" title="Link to this heading">#</a></h3>
<p>There are at least three ways to write finite element codes using PETSc:</p>
<ol class="arabic simple">
<li><p>Use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMPlex/DMPLEX.html">DMPLEX</a></span></code>, which is a high level approach to manage your mesh and
discretization. See the <a class="reference internal" href="../tutorials/physics/guide_to_stokes.html#tut-stokes"><span class="std std-ref">tutorials sections</span></a> for further information,
or see <code class="docutils notranslate"><span class="pre">src/snes/tutorial/ex62.c</span></code>.</p></li>
<li><p>Use packages such as <a class="reference external" href="https://www.dealii.org">deal.ii</a>, <a class="reference external" href="https://libmesh.github.io">libMesh</a>, or
<a class="reference external" href="https://www.firedrakeproject.org">Firedrake</a>, which use PETSc for the solvers.</p></li>
<li><p>Manage the grid data structure yourself and use PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span></code> to
communicate the required ghost point communication. See
<code class="docutils notranslate"><span class="pre">src/snes/tutorials/ex10d/ex10.c</span></code>.</p></li>
</ol>
</section>
<section id="dmda-decomposes-the-domain-differently-than-the-mpi-cart-create-command-how-can-one-use-them-together">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">DMDA decomposes the domain differently than the MPI_Cart_create() command. How can one use them together?</a><a class="headerlink" href="#dmda-decomposes-the-domain-differently-than-the-mpi-cart-create-command-how-can-one-use-them-together" title="Link to this heading">#</a></h3>
<p>The <code class="docutils notranslate"><span class="pre"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Cart_create.html#MPI_Cart_create">MPI_Cart_create</a>()</span></code> first divides the mesh along the z direction, then the y, then
the x. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> divides along the x, then y, then z. Thus, for example, rank 1 of the
processes will be in a different part of the mesh for the two schemes. To resolve this you
can create a new MPI communicator that you pass to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDACreate.html">DMDACreate</a>()</span></code> that renumbers the
process ranks so that each physical process shares the same part of the mesh with both the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> and the <code class="docutils notranslate"><span class="pre"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Cart_create.html#MPI_Cart_create">MPI_Cart_create</a>()</span></code>. The code to determine the new numbering was
provided by Rolf Kuiper:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// the numbers of processors per direction are (int) x_procs, y_procs, z_procs respectively</span>
<span class="c1">// (no parallelization in direction &#39;dir&#39; means dir_procs = 1)</span>

<span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w">    </span><span class="n">NewComm</span><span class="p">;</span>
<span class="kt">int</span><span class="w">         </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="w"> </span><span class="n">z</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/PetscMPIInt.html">PetscMPIInt</a></span><span class="w"> </span><span class="n">MPI_Rank</span><span class="p">,</span><span class="w"> </span><span class="n">NewRank</span><span class="p">;</span>

<span class="c1">// get rank from MPI ordering:</span>
<span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_rank.html#MPI_Comm_rank">MPI_Comm_rank</a></span><span class="p">(</span><span class="n">MPI_COMM_WORLD</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">MPI_Rank</span><span class="p">));</span>

<span class="c1">// calculate coordinates of cpus in MPI ordering:</span>
<span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">MPI_rank</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">(</span><span class="n">z_procs</span><span class="o">*</span><span class="n">y_procs</span><span class="p">);</span>
<span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">MPI_rank</span><span class="w"> </span><span class="o">%</span><span class="w"> </span><span class="p">(</span><span class="n">z_procs</span><span class="o">*</span><span class="n">y_procs</span><span class="p">))</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">z_procs</span><span class="p">;</span>
<span class="n">z</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">MPI_rank</span><span class="w"> </span><span class="o">%</span><span class="w"> </span><span class="p">(</span><span class="n">z_procs</span><span class="o">*</span><span class="n">y_procs</span><span class="p">))</span><span class="w"> </span><span class="o">%</span><span class="w"> </span><span class="n">z_procs</span><span class="p">;</span>

<span class="c1">// set new rank according to PETSc ordering:</span>
<span class="n">NewRank</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">z</span><span class="o">*</span><span class="n">y_procs</span><span class="o">*</span><span class="n">x_procs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="o">*</span><span class="n">x_procs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">x</span><span class="p">;</span>

<span class="c1">// create communicator with new ranks according to PETSc ordering</span>
<span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_split.html#MPI_Comm_split">MPI_Comm_split</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="n">NewRank</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">NewComm</span><span class="p">));</span>

<span class="c1">// override the default communicator (was MPI_COMM_WORLD as default)</span>
<span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">NewComm</span><span class="p">;</span>
</pre></div>
</div>
</section>
<section id="when-solving-a-system-with-dirichlet-boundary-conditions-i-can-use-matzerorows-to-eliminate-the-dirichlet-rows-but-this-results-in-a-non-symmetric-system-how-can-i-apply-dirichlet-boundary-conditions-but-keep-the-matrix-symmetric">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">When solving a system with Dirichlet boundary conditions I can use MatZeroRows() to eliminate the Dirichlet rows but this results in a non-Symmetric system. How can I apply Dirichlet boundary conditions but keep the matrix symmetric?</a><a class="headerlink" href="#when-solving-a-system-with-dirichlet-boundary-conditions-i-can-use-matzerorows-to-eliminate-the-dirichlet-rows-but-this-results-in-a-non-symmetric-system-how-can-i-apply-dirichlet-boundary-conditions-but-keep-the-matrix-symmetric" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>For nonsymmetric systems put the appropriate boundary solutions in the x vector and use
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatZeroRows.html">MatZeroRows</a>()</span></code> followed by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a>()</span></code>.</p></li>
<li><p>For symmetric problems use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatZeroRowsColumns.html">MatZeroRowsColumns</a>()</span></code>.</p></li>
<li><p>If you have many Dirichlet locations you can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatZeroRows.html">MatZeroRows</a>()</span></code> (<strong>not</strong>
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatZeroRowsColumns.html">MatZeroRowsColumns</a>()</span></code>) and <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span> <span class="pre">-pc_type</span> <span class="pre">redistribute</span></code> (see
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCREDISTRIBUTE.html">PCREDISTRIBUTE</a></span></code>) and PETSc will repartition the parallel matrix for load
balancing. In this case the new matrix solved remains symmetric even though
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatZeroRows.html">MatZeroRows</a>()</span></code> is used.</p></li>
</ul>
<p>An alternative approach is, when assembling the matrix (generating values and passing
them to the matrix), never to include locations for the Dirichlet grid points in the
vector and matrix, instead taking them into account as you put the other values into the
load.</p>
</section>
<section id="how-can-i-get-petsc-vectors-and-matrices-to-matlab-or-vice-versa">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I get PETSc vectors and matrices to MATLAB or vice versa?</a><a class="headerlink" href="#how-can-i-get-petsc-vectors-and-matrices-to-matlab-or-vice-versa" title="Link to this heading">#</a></h3>
<p>There are numerous ways to work with PETSc and MATLAB. All but the first approach
require PETSc to be configured with –with-matlab.</p>
<ol class="arabic simple">
<li><p>To save PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> to files that can be read from MATLAB use
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinaryOpen.html">PetscViewerBinaryOpen</a>()</span></code> viewer and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecView.html">VecView</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatView.html">MatView</a>()</span></code> to save objects
for MATLAB and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecLoad.html">VecLoad</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLoad.html">MatLoad</a>()</span></code> to get the objects that MATLAB has
saved. See <code class="docutils notranslate"><span class="pre">share/petsc/matlab/<a href="../manualpages/Sys/PetscBinaryRead.html">PetscBinaryRead</a>.m</span></code> and
<code class="docutils notranslate"><span class="pre">share/petsc/matlab/<a href="../manualpages/Sys/PetscBinaryWrite.html">PetscBinaryWrite</a>.m</span></code> for loading and saving the objects in MATLAB.</p></li>
<li><p>Using the <a class="reference external" href="https://www.mathworks.com/help/matlab/calling-matlab-engine-from-c-programs-1.html">MATLAB Engine</a>,
allows PETSc to automatically call MATLAB to perform some specific computations. This
does not allow MATLAB to be used interactively by the user. See the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Matlab/PetscMatlabEngine.html">PetscMatlabEngine</a></span></code>.</p></li>
<li><p>You can open a socket connection between MATLAB and PETSc to allow sending objects back
and forth between an interactive MATLAB session and a running PETSc program. See
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerSocketOpen.html">PetscViewerSocketOpen</a>()</span></code> for access from the PETSc side and
<code class="docutils notranslate"><span class="pre">share/petsc/matlab/PetscReadBinary.m</span></code> for access from the MATLAB side.</p></li>
<li><p>You can save PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> (<strong>not</strong> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>) with the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerMatlabOpen.html">PetscViewerMatlabOpen</a>()</span></code>
viewer that saves <code class="docutils notranslate"><span class="pre">.mat</span></code> files can then be loaded into MATLAB using the <code class="docutils notranslate"><span class="pre">load()</span></code> command</p></li>
</ol>
</section>
<section id="how-do-i-get-started-with-cython-so-that-i-can-extend-petsc4py">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I get started with Cython so that I can extend petsc4py?</a><a class="headerlink" href="#how-do-i-get-started-with-cython-so-that-i-can-extend-petsc4py" title="Link to this heading">#</a></h3>
<ol class="arabic simple">
<li><p>Learn how to <a class="reference external" href="http://docs.cython.org/src/quickstart/build.html">build a Cython module</a>.</p></li>
<li><p>Go through the simple <a class="reference external" href="https://stackoverflow.com/questions/3046305/simple-wrapping-of-c-code-with-cython">example</a>. Note
also the next comment that shows how to create numpy arrays in the Cython and pass them
back.</p></li>
<li><p>Check out <a class="reference external" href="http://docs.cython.org/src/tutorial/numpy.html">this page</a> which tells
you how to get fast indexing.</p></li>
<li><p>Have a look at the petsc4py <a class="reference external" href="http://code.google.com/p/petsc4py/source/browse/src/PETSc/arraynpy.pxi">array source</a>.</p></li>
</ol>
</section>
<section id="how-do-i-compute-a-custom-norm-for-ksp-to-use-as-a-convergence-test-or-for-monitoring">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I compute a custom norm for KSP to use as a convergence test or for monitoring?</a><a class="headerlink" href="#how-do-i-compute-a-custom-norm-for-ksp-to-use-as-a-convergence-test-or-for-monitoring" title="Link to this heading">#</a></h3>
<p>You need to call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBuildResidual.html">KSPBuildResidual</a>()</span></code> on your <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> object and then compute the
appropriate norm on the resulting residual. Note that depending on the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetNormType.html">KSPSetNormType</a>()</span></code> of the method you may not return the same norm as provided by the
method. See also <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetPCSide.html">KSPSetPCSide</a>()</span></code>.</p>
</section>
<section id="if-i-have-a-sequential-program-can-i-use-a-petsc-parallel-solver">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">If I have a sequential program can I use a PETSc parallel solver?</a><a class="headerlink" href="#if-i-have-a-sequential-program-can-i-use-a-petsc-parallel-solver" title="Link to this heading">#</a></h3>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Do not expect to get great speedups! Much of the speedup gained by using parallel
solvers comes from building the underlying matrices and vectors in parallel to begin
with. You should see some reduction in the time for the linear solvers.</p>
</div>
<p>Yes, you must set up PETSc with MPI (even though you will not use MPI) with at least the
following options:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./configure<span class="w"> </span>--download-superlu_dist<span class="w"> </span>--download-parmetis<span class="w"> </span>--download-metis<span class="w"> </span>--with-openmp
</pre></div>
</div>
<p>Your compiler must support OpenMP. To have the linear solver run in parallel run your
program with</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">OMP_NUM_THREADS</span><span class="o">=</span>n<span class="w"> </span>./myprog<span class="w"> </span>-pc_type<span class="w"> </span>lu<span class="w"> </span>-pc_factor_mat_solver<span class="w"> </span>superlu_dist
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">n</span></code> is the number of threads and should be less than or equal to the number of cores
available.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If your code is MPI parallel you can also use these same options to have SuperLU_dist
utilize multiple threads per MPI process for the direct solver. Make sure that the
<code class="docutils notranslate"><span class="pre">$OMP_NUM_THREADS</span></code> you use per MPI process is less than or equal to the number of
cores available for each MPI process. For example if your compute nodes have 6 cores
and you use 2 MPI processes per node then set <code class="docutils notranslate"><span class="pre">$OMP_NUM_THREADS</span></code> to 2 or 3.</p>
</div>
<p>Another approach that allows using a PETSc parallel solver is to use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMPI.html">PCMPI</a></span></code>.</p>
</section>
<section id="ts-or-snes-produces-infeasible-out-of-domain-solutions-or-states-how-can-i-prevent-this">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">TS or SNES produces infeasible (out of domain) solutions or states. How can I prevent this?</a><a class="headerlink" href="#ts-or-snes-produces-infeasible-out-of-domain-solutions-or-states-how-can-i-prevent-this" title="Link to this heading">#</a></h3>
<p>For <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetFunctionDomainError.html">TSSetFunctionDomainError</a>()</span></code>. For both <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunctionDomainError.html">SNESSetFunctionDomainError</a>()</span></code> when the solver passes an infeasible (out of domain)
solution or state to your routines.</p>
<p>If it occurs for DAEs, it is important to insure the algebraic constraints are well
satisfied, which can prevent “breakdown” later. Thus, one can try using a tight tolerance
for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>, using a direct linear solver (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCType.html">PCType</a></span></code> of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLU.html">PCLU</a></span></code>) when possible, and reducing the timestep (or
tightening <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> tolerances for adaptive time stepping).</p>
</section>
<section id="can-petsc-work-with-hermitian-matrices">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can PETSc work with Hermitian matrices?</a><a class="headerlink" href="#can-petsc-work-with-hermitian-matrices" title="Link to this heading">#</a></h3>
<p>PETSc’s support of Hermitian matrices is limited. Many operations and solvers work
for symmetric (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSBAIJ.html">MATSBAIJ</a></span></code>) matrices and operations on transpose matrices but there is
little direct support for Hermitian matrices and Hermitian transpose (complex conjugate
transpose) operations. There is <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolveTranspose.html">KSPSolveTranspose</a>()</span></code> for solving the transpose of a
linear system but no <code class="docutils notranslate"><span class="pre">KSPSolveHermitian()</span></code>.</p>
<p>For creating known Hermitian matrices:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateNormalHermitian.html">MatCreateNormalHermitian</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateHermitianTranspose.html">MatCreateHermitianTranspose</a>()</span></code></p></li>
</ul>
<p>For determining or setting Hermitian status on existing matrices:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatIsHermitian.html">MatIsHermitian</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatIsHermitianKnown.html">MatIsHermitianKnown</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatIsStructurallySymmetric.html">MatIsStructurallySymmetric</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatIsSymmetricKnown.html">MatIsSymmetricKnown</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatIsSymmetric.html">MatIsSymmetric</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetOption.html">MatSetOption</a>()</span></code> (use with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatOption.html">MAT_SYMMETRIC</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatOption.html">MAT_HERMITIAN</a></span></code> to assert to PETSc
that either is the case).</p></li>
</ul>
<p>For performing matrix operations on known Hermitian matrices (note that regular <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>
functions such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMult.html">MatMult</a>()</span></code> will of course also work on Hermitian matrices):</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMultHermitianTranspose.html">MatMultHermitianTranspose</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMultHermitianTransposeAdd.html">MatMultHermitianTransposeAdd</a>()</span></code> (very limited support)</p></li>
</ul>
</section>
<section id="how-can-i-assemble-a-bunch-of-similar-matrices">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I assemble a bunch of similar matrices?</a><a class="headerlink" href="#how-can-i-assemble-a-bunch-of-similar-matrices" title="Link to this heading">#</a></h3>
<p>You can first add the values common to all the matrices, then use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatStoreValues.html">MatStoreValues</a>()</span></code> to
stash the common values. Each iteration you call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatRetrieveValues.html">MatRetrieveValues</a>()</span></code>, then set the
unique values in a matrix and assemble.</p>
</section>
<section id="can-one-resize-or-change-the-size-of-petsc-matrices-or-vectors">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can one resize or change the size of PETSc matrices or vectors?</a><a class="headerlink" href="#can-one-resize-or-change-the-size-of-petsc-matrices-or-vectors" title="Link to this heading">#</a></h3>
<p>No, once the vector or matrices sizes have been set and the matrices or vectors are fully
usable one cannot change the size of the matrices or vectors or number of processors they
live on. One may create new vectors and copy, for example using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a>()</span></code>,
the old values from the previous vector.</p>
</section>
<section id="how-can-one-compute-the-nullspace-of-a-sparse-matrix-with-mumps">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can one compute the nullspace of a sparse matrix with MUMPS?</a><a class="headerlink" href="#how-can-one-compute-the-nullspace-of-a-sparse-matrix-with-mumps" title="Link to this heading">#</a></h3>
<p>Assuming you have an existing matrix <span class="math">\(A\)</span> whose nullspace <span class="math">\(V\)</span> you want to find:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w">      </span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="n">work</span><span class="p">,</span><span class="w"> </span><span class="n">V</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="w"> </span><span class="n">rows</span><span class="p">;</span>

<span class="cm">/* Determine factorability */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatGetFactor.html">MatGetFactor</a></span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MATSOLVERMUMPS.html">MATSOLVERMUMPS</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatFactorType.html">MAT_FACTOR_LU</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">F</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatGetLocalSize.html">MatGetLocalSize</a></span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">rows</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="cm">/* Set MUMPS options, see MUMPS documentation for more information */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatMumpsSetIcntl.html">MatMumpsSetIcntl</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="mi">24</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatMumpsSetIcntl.html">MatMumpsSetIcntl</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="mi">25</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">));</span>

<span class="cm">/* Perform factorization */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatLUFactorSymbolic.html">MatLUFactorSymbolic</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatLUFactorNumeric.html">MatLUFactorNumeric</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="cm">/* This is the dimension of the null space */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatMumpsGetInfog.html">MatMumpsGetInfog</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="mi">28</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">N</span><span class="p">));</span>

<span class="cm">/* This will contain the null space in the columns */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatCreateDense.html">MatCreateDense</a></span><span class="p">(</span><span class="n">comm</span><span class="p">,</span><span class="w"> </span><span class="n">rows</span><span class="p">,</span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DETERMINE.html">PETSC_DETERMINE</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DETERMINE.html">PETSC_DETERMINE</a></span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">V</span><span class="p">));</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatDuplicate.html">MatDuplicate</a></span><span class="p">(</span><span class="n">V</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatDuplicateOption.html">MAT_DO_NOT_COPY_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">work</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatMatSolve.html">MatMatSolve</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="n">work</span><span class="p">,</span><span class="w"> </span><span class="n">V</span><span class="p">));</span>
</pre></div>
</div>
</section>
</section>
<hr class="docutils" />
<section id="execution">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Execution</a><a class="headerlink" href="#execution" title="Link to this heading">#</a></h2>
<section id="petsc-executables-are-so-big-and-take-so-long-to-link">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">PETSc executables are SO big and take SO long to link</a><a class="headerlink" href="#petsc-executables-are-so-big-and-take-so-long-to-link" title="Link to this heading">#</a></h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>See <a class="reference internal" href="#doc-faq-sharedlibs"><span class="std std-ref">shared libraries section</span></a> for more information.</p>
</div>
<p>We find this annoying as well. On most machines PETSc can use shared libraries, so
executables should be much smaller, run <code class="docutils notranslate"><span class="pre">configure</span></code> with the additional option
<code class="docutils notranslate"><span class="pre">--with-shared-libraries</span></code> (this is the default). Also, if you have room, compiling and
linking PETSc on your machine’s <code class="docutils notranslate"><span class="pre">/tmp</span></code> disk or similar local disk, rather than over the
network will be much faster.</p>
</section>
<section id="how-does-petsc-s-help-option-work-why-is-it-different-for-different-programs">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How does PETSc’s <code class="docutils notranslate"><span class="pre">-help</span></code> option work? Why is it different for different programs?</a><a class="headerlink" href="#how-does-petsc-s-help-option-work-why-is-it-different-for-different-programs" title="Link to this heading">#</a></h3>
<p>There are 2 ways in which one interacts with the options database:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">PetscOptionsGetXXX()</span></code> where <code class="docutils notranslate"><span class="pre">XXX</span></code> is some type or data structure (for example
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsGetBool.html">PetscOptionsGetBool</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsGetScalarArray.html">PetscOptionsGetScalarArray</a>()</span></code>). This is a classic
“getter” function, which queries the command line options for a matching option name,
and returns the specified value.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">PetscOptionsXXX()</span></code> where <code class="docutils notranslate"><span class="pre">XXX</span></code> is some type or data structure (for example
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsBool.html">PetscOptionsBool</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsScalarArray.html">PetscOptionsScalarArray</a>()</span></code>). This is a so-called “provider”
function. It first records the option name in an internal list of previously encountered
options before calling <code class="docutils notranslate"><span class="pre">PetscOptionsGetXXX()</span></code> to query the status of said option.</p></li>
</ul>
<p>While users generally use the first option, developers will <em>always</em> use the second
(provider) variant of functions. Thus, as the program runs, it will build up a list of
encountered option names which are then printed <strong>in the order of their appearance on the
root rank</strong>. Different programs may take different paths through PETSc source code, so
they will encounter different providers, and therefore have different <code class="docutils notranslate"><span class="pre">-help</span></code> output.</p>
</section>
<section id="petsc-has-so-many-options-for-my-program-that-it-is-hard-to-keep-them-straight">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">PETSc has so many options for my program that it is hard to keep them straight</a><a class="headerlink" href="#petsc-has-so-many-options-for-my-program-that-it-is-hard-to-keep-them-straight" title="Link to this heading">#</a></h3>
<p>Running the PETSc program with the option <code class="docutils notranslate"><span class="pre">-help</span></code> will print out many of the options. To
print the options that have been specified within a program, employ <code class="docutils notranslate"><span class="pre">-options_left</span></code> to
print any options that the user specified but were not actually used by the program and
all options used; this is helpful for detecting typo errors. The PETSc website has a search option,
in the upper right hand corner, that quickly finds answers to most PETSc questions.</p>
</section>
<section id="petsc-automatically-handles-many-of-the-details-in-parallel-pde-solvers-how-can-i-understand-what-is-really-happening-within-my-program">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">PETSc automatically handles many of the details in parallel PDE solvers. How can I understand what is really happening within my program?</a><a class="headerlink" href="#petsc-automatically-handles-many-of-the-details-in-parallel-pde-solvers-how-can-i-understand-what-is-really-happening-within-my-program" title="Link to this heading">#</a></h3>
<p>You can use the option <code class="docutils notranslate"><span class="pre">-info</span></code> to get more details about the solution process. The
option <code class="docutils notranslate"><span class="pre">-log_view</span></code> provides details about the distribution of time spent in the various
phases of the solution process. You can run with <code class="docutils notranslate"><span class="pre">-ts_view</span></code> or <code class="docutils notranslate"><span class="pre">-snes_view</span></code> or
<code class="docutils notranslate"><span class="pre">-ksp_view</span></code> to see what solver options are being used. Run with <code class="docutils notranslate"><span class="pre">-ts_monitor</span></code>,
<code class="docutils notranslate"><span class="pre">-snes_monitor</span></code>, or <code class="docutils notranslate"><span class="pre">-ksp_monitor</span></code> to watch convergence of the
methods. <code class="docutils notranslate"><span class="pre">-snes_converged_reason</span></code> and <code class="docutils notranslate"><span class="pre">-ksp_converged_reason</span></code> will indicate why and if
the solvers have converged.</p>
</section>
<section id="assembling-large-sparse-matrices-takes-a-long-time-what-can-i-do-to-make-this-process-faster-or-matsetvalues-is-so-slow-what-can-i-do-to-speed-it-up">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Assembling large sparse matrices takes a long time. What can I do to make this process faster? Or MatSetValues() is so slow; what can I do to speed it up?</a><a class="headerlink" href="#assembling-large-sparse-matrices-takes-a-long-time-what-can-i-do-to-make-this-process-faster-or-matsetvalues-is-so-slow-what-can-i-do-to-speed-it-up" title="Link to this heading">#</a></h3>
<p>You probably need to do preallocation, as explained in <a class="reference internal" href="../manual/mat.html#sec-matsparse"><span class="std std-ref">Sparse Matrices</span></a>.
See also the <a class="reference internal" href="../manual/performance.html#ch-performance"><span class="std std-ref">performance chapter</span></a> of the users manual.</p>
<p>For GPUs (and even CPUs) you can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetPreallocationCOO.html">MatSetPreallocationCOO</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValuesCOO.html">MatSetValuesCOO</a>()</span></code> for more rapid assembly.</p>
</section>
<section id="how-can-i-generate-performance-summaries-with-petsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I generate performance summaries with PETSc?</a><a class="headerlink" href="#how-can-i-generate-performance-summaries-with-petsc" title="Link to this heading">#</a></h3>
<p>Use this option at runtime:</p>
<p>-l</p>
<p>og_view</p>
<p>Outputs a comprehensive timing, memory consumption, and communications digest
for your program. See the <a class="reference internal" href="../manual/profiling.html#ch-profiling"><span class="std std-ref">profiling chapter</span></a> of the users
manual for information on interpreting the summary data.</p>
</section>
<section id="how-do-i-know-the-amount-of-time-spent-on-each-level-of-the-multigrid-solver-preconditioner">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I know the amount of time spent on each level of the multigrid solver/preconditioner?</a><a class="headerlink" href="#how-do-i-know-the-amount-of-time-spent-on-each-level-of-the-multigrid-solver-preconditioner" title="Link to this heading">#</a></h3>
<p>Run with <code class="docutils notranslate"><span class="pre">-log_view</span></code> and <code class="docutils notranslate"><span class="pre">-pc_mg_log</span></code></p>
</section>
<section id="where-do-i-get-the-input-matrices-for-the-examples">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Where do I get the input matrices for the examples?</a><a class="headerlink" href="#where-do-i-get-the-input-matrices-for-the-examples" title="Link to this heading">#</a></h3>
<p>Some examples use <code class="docutils notranslate"><span class="pre">$DATAFILESPATH/matrices/medium</span></code> and other files. These test matrices
in PETSc binary format can be found in the <a class="reference external" href="https://gitlab.com/petsc/datafiles">datafiles repository</a>.</p>
</section>
<section id="when-i-dump-some-matrices-and-vectors-to-binary-i-seem-to-be-generating-some-empty-files-with-info-extensions-what-s-the-deal-with-these">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">When I dump some matrices and vectors to binary, I seem to be generating some empty files with <code class="docutils notranslate"><span class="pre">.info</span></code> extensions. What’s the deal with these?</a><a class="headerlink" href="#when-i-dump-some-matrices-and-vectors-to-binary-i-seem-to-be-generating-some-empty-files-with-info-extensions-what-s-the-deal-with-these" title="Link to this heading">#</a></h3>
<p>PETSc binary viewers put some additional information into <code class="docutils notranslate"><span class="pre">.info</span></code> files like matrix
block size. It is harmless but if you <em>really</em> don’t like it you can use
<code class="docutils notranslate"><span class="pre">-viewer_binary_skip_info</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinarySkipInfo.html">PetscViewerBinarySkipInfo</a>()</span></code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You need to call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinarySkipInfo.html">PetscViewerBinarySkipInfo</a>()</span></code> before
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFileSetName.html">PetscViewerFileSetName</a>()</span></code>. In other words you <strong>cannot</strong> use
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinaryOpen.html">PetscViewerBinaryOpen</a>()</span></code> directly.</p>
</div>
</section>
<section id="why-is-my-parallel-solver-slower-than-my-sequential-solver-or-i-have-poor-speed-up">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why is my parallel solver slower than my sequential solver, or I have poor speed-up?</a><a class="headerlink" href="#why-is-my-parallel-solver-slower-than-my-sequential-solver-or-i-have-poor-speed-up" title="Link to this heading">#</a></h3>
<p>This can happen for many reasons:</p>
<ol class="arabic simple">
<li><p>Make sure it is truly the time in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code> that is slower (by running the code
with <code class="docutils notranslate"><span class="pre">-log_view</span></code>). Often the slower time is in generating the matrix or some other
operation.</p></li>
<li><p>There must be enough work for each process to outweigh the communication time. We
recommend an absolute minimum of about 10,000 unknowns per process, better is 20,000 or
more. This is even more true when using multiple GPUs, where you need to have millions
of unknowns per GPU.</p></li>
<li><p>Make sure the <a class="reference internal" href="#doc-faq-general-parallel"><span class="std std-ref">communication speed of the parallel computer</span></a> is good enough for parallel solvers.</p></li>
<li><p>Check the number of solver iterates with the parallel solver against the sequential
solver. Most preconditioners require more iterations when used on more processes, this
is particularly true for block Jacobi (the default parallel preconditioner). You can
try <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">asm</span></code> (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>) its iterations scale a bit better for more
processes. You may also consider multigrid preconditioners like <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code> or BoomerAMG
in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCHYPRE.html">PCHYPRE</a></span></code>.</p></li>
</ol>
</section>
<section id="what-steps-are-necessary-to-make-the-pipelined-solvers-execute-efficiently">
<span id="doc-faq-pipelined"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What steps are necessary to make the pipelined solvers execute efficiently?</a><a class="headerlink" href="#what-steps-are-necessary-to-make-the-pipelined-solvers-execute-efficiently" title="Link to this heading">#</a></h3>
<p>Pipelined solvers like <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPGMRES.html">KSPPGMRES</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPECG.html">KSPPIPECG</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPECR.html">KSPPIPECR</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGROPPCG.html">KSPGROPPCG</a></span></code> may
require special MPI configuration to effectively overlap reductions with computation. In
general, this requires an MPI-3 implementation, an implementation that supports multiple
threads, and use of a “progress thread”. Consult the documentation from your vendor or
computing facility for more details.</p>
<ul>
<li><p>Cray MPI MPT-5.6 MPI-3, by setting <code class="docutils notranslate"><span class="pre">$MPICH_MAX_THREAD_SAFETY</span></code> to “multiple”
for threads, plus either <code class="docutils notranslate"><span class="pre">$MPICH_ASYNC_PROGRESS</span></code> or
<code class="docutils notranslate"><span class="pre">$MPICH_NEMESIS_ASYNC_PROGRESS</span></code>. E.g.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">MPICH_MAX_THREAD_SAFETY</span><span class="o">=</span>multiple
<span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">MPICH_ASYNC_PROGRESS</span><span class="o">=</span><span class="m">1</span>
<span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">MPICH_NEMESIS_ASYNC_PROGRESS</span><span class="o">=</span><span class="m">1</span>
</pre></div>
</div>
</li>
<li><p>MPICH version 3.0 and later implements the MPI-3 standard and the default
configuration supports use of threads. Use of a progress thread is configured by
setting the environment variable <code class="docutils notranslate"><span class="pre">$MPICH_ASYNC_PROGRESS</span></code>. E.g.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">MPICH_ASYNC_PROGRESS</span><span class="o">=</span><span class="m">1</span>
</pre></div>
</div>
</li>
</ul>
</section>
<section id="when-using-petsc-in-single-precision-mode-with-precision-single-when-running-configure-are-the-operations-done-in-single-or-double-precision">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">When using PETSc in single precision mode (<code class="docutils notranslate"><span class="pre">--with-precision=single</span></code> when running <code class="docutils notranslate"><span class="pre">configure</span></code>) are the operations done in single or double precision?</a><a class="headerlink" href="#when-using-petsc-in-single-precision-mode-with-precision-single-when-running-configure-are-the-operations-done-in-single-or-double-precision" title="Link to this heading">#</a></h3>
<p>PETSc does <strong>NOT</strong> do any explicit conversion of single precision to double before
performing computations; it depends on the hardware and compiler for what happens. For
example, the compiler could choose to put the single precision numbers into the usual
double precision registers and then use the usual double precision floating point unit. Or
it could use SSE2 instructions that work directly on the single precision numbers. It is a
bit of a mystery what decisions get made sometimes. There may be compiler flags in some
circumstances that can affect this.</p>
</section>
<section id="why-is-newton-s-method-snes-not-converging-or-converges-slowly">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why is Newton’s method (SNES) not converging, or converges slowly?</a><a class="headerlink" href="#why-is-newton-s-method-snes-not-converging-or-converges-slowly" title="Link to this heading">#</a></h3>
<p>Newton’s method may not converge for many reasons, here are some of the most common:</p>
<ul class="simple">
<li><p>The Jacobian is wrong (or correct in sequential but not in parallel).</p></li>
<li><p>The linear system is <a class="reference internal" href="#doc-faq-execution-kspconv"><span class="std std-ref">not solved</span></a> or is not solved
accurately enough.</p></li>
<li><p>The Jacobian system has a singularity that the linear solver is not handling.</p></li>
<li><p>There is a bug in the function evaluation routine.</p></li>
<li><p>The function is not continuous or does not have continuous first derivatives (e.g. phase
change or TVD limiters).</p></li>
<li><p>The equations may not have a solution (e.g. limit cycle instead of a steady state) or
there may be a “hill” between the initial guess and the steady state (e.g. reactants
must ignite and burn before reaching a steady state, but the steady-state residual will
be larger during combustion).</p></li>
</ul>
<p>Here are some of the ways to help debug lack of convergence of Newton:</p>
<ul>
<li><p>Run on one processor to see if the problem is only in parallel.</p></li>
<li><p>Run with <code class="docutils notranslate"><span class="pre">-info</span></code> to get more detailed information on the solution process.</p></li>
<li><p>Run with the options</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-snes_monitor -ksp_monitor_true_residual -snes_converged_reason -ksp_converged_reason
</pre></div>
</div>
<ul class="simple">
<li><p>If the linear solve does not converge, check if the Jacobian is correct, then see
<a class="reference internal" href="#doc-faq-execution-kspconv"><span class="std std-ref">this question</span></a>.</p></li>
<li><p>If the preconditioned residual converges, but the true residual does not, the
preconditioner may be singular.</p></li>
<li><p>If the linear solve converges well, but the line search fails, the Jacobian may be
incorrect.</p></li>
</ul>
</li>
<li><p>Run with <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">lu</span></code> or <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">svd</span></code> to see if the problem is a poor linear
solver.</p></li>
<li><p>Run with <code class="docutils notranslate"><span class="pre">-mat_view</span></code> or <code class="docutils notranslate"><span class="pre">-mat_view</span> <span class="pre">draw</span></code> to see if the Jacobian looks reasonable.</p></li>
<li><p>Run with <code class="docutils notranslate"><span class="pre">-snes_test_jacobian</span> <span class="pre">-snes_test_jacobian_view</span></code> to see if the Jacobian you are
using is wrong. Compare the output when you add <code class="docutils notranslate"><span class="pre">-mat_fd_type</span> <span class="pre">ds</span></code> to see if the result
is sensitive to the choice of differencing parameter.</p></li>
<li><p>Run with <code class="docutils notranslate"><span class="pre">-snes_mf_operator</span> <span class="pre">-pc_type</span> <span class="pre">lu</span></code> to see if the Jacobian you are using is
wrong. If the problem is too large for a direct solve, try</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-snes_mf_operator -pc_type ksp -ksp_ksp_rtol 1e-12.
</pre></div>
</div>
<p>Compare the output when you add <code class="docutils notranslate"><span class="pre">-mat_mffd_type</span> <span class="pre">ds</span></code> to see if the result is sensitive
to choice of differencing parameter.</p>
</li>
<li><p>Run with <code class="docutils notranslate"><span class="pre">-snes_linesearch_monitor</span></code> to see if the line search is failing (this is
usually a sign of a bad Jacobian). Use <code class="docutils notranslate"><span class="pre">-info</span></code> in PETSc 3.1 and older versions,
<code class="docutils notranslate"><span class="pre">-snes_ls_monitor</span></code> in PETSc 3.2 and <code class="docutils notranslate"><span class="pre">-snes_linesearch_monitor</span></code> in PETSc 3.3 and
later.</p></li>
</ul>
<p>Here are some ways to help the Newton process if everything above checks out:</p>
<ul>
<li><p>Run with grid sequencing (<code class="docutils notranslate"><span class="pre">-snes_grid_sequence</span></code> if working with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> is all you
need) to generate better initial guess on your finer mesh.</p></li>
<li><p>Run with quad precision, i.e.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./configure<span class="w"> </span>--with-precision<span class="o">=</span>__float128<span class="w"> </span>--download-f2cblaslapack
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>quad precision requires PETSc 3.2 and later and recent versions of the GNU compilers.</p>
</div>
</li>
<li><p>Change the units (nondimensionalization), boundary condition scaling, or formulation so
that the Jacobian is better conditioned. See <a class="reference external" href="https://en.wikipedia.org/wiki/Buckingham_%CF%80_theorem">Buckingham pi theorem</a> and <a class="reference external" href="https://epubs.siam.org/doi/pdf/10.1137/16M1107127">Dimensional and
Scaling Analysis</a>.</p></li>
<li><p>Mollify features in the function that do not have continuous first derivatives (often
occurs when there are “if” statements in the residual evaluation, e.g. phase change or
TVD limiters). Use a variational inequality solver (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESVINEWTONRSLS.html">SNESVINEWTONRSLS</a></span></code>) if the
discontinuities are of fundamental importance.</p></li>
<li><p>Try a trust region method (<code class="docutils notranslate"><span class="pre">-ts_type</span> <span class="pre">tr</span></code>, may have to adjust parameters).</p></li>
<li><p>Run with some continuation parameter from a point where you know the solution, see
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSPSEUDO.html">TSPSEUDO</a></span></code> for steady-states.</p></li>
<li><p>There are homotopy solver packages like PHCpack that can get you all possible solutions
(and tell you that it has found them all) but those are not scalable and cannot solve
anything but small problems.</p></li>
</ul>
</section>
<section id="why-is-the-linear-solver-ksp-not-converging-or-converges-slowly">
<span id="doc-faq-execution-kspconv"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why is the linear solver (KSP) not converging, or converges slowly?</a><a class="headerlink" href="#why-is-the-linear-solver-ksp-not-converging-or-converges-slowly" title="Link to this heading">#</a></h3>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>Always run with <code class="docutils notranslate"><span class="pre">-ksp_converged_reason</span> <span class="pre">-ksp_monitor_true_residual</span></code> when trying to
learn why a method is not converging!</p>
</div>
<p>Common reasons for KSP not converging are:</p>
<ul>
<li><p>A symmetric method is being used for a non-symmetric problem.</p></li>
<li><p>The equations are singular by accident (e.g. forgot to impose boundary
conditions). Check this for a small problem using <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">svd</span> <span class="pre">-pc_svd_monitor</span></code>.</p></li>
<li><p>The equations are intentionally singular (e.g. constant null space), but the Krylov
method was not informed, see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNullSpace.html">MatSetNullSpace</a>()</span></code>. Always inform your local Krylov
subspace solver of any change of singularity. Failure to do so will result in the
immediate revocation of your computing and keyboard operator licenses, as well as
a stern talking-to by the nearest Krylov Subspace Method representative.</p></li>
<li><p>The equations are intentionally singular and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNullSpace.html">MatSetNullSpace</a>()</span></code> was used, but the
right-hand side is not consistent. You may have to call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpaceRemove.html">MatNullSpaceRemove</a>()</span></code> on the
right-hand side before calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetTransposeNullSpace.html">MatSetTransposeNullSpace</a>()</span></code>.</p></li>
<li><p>The equations are indefinite so that standard preconditioners don’t work. Usually you
will know this from the physics, but you can check with</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-ksp_compute_eigenvalues -ksp_gmres_restart 1000 -pc_type none
</pre></div>
</div>
<p>For simple saddle point problems, try</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-pc_type fieldsplit -pc_fieldsplit_type schur -pc_fieldsplit_detect_saddle_point
</pre></div>
</div>
<p>For more difficult problems, read the literature to find robust methods and ask
<a class="reference external" href="mailto:petsc-users&#37;&#52;&#48;mcs&#46;anl&#46;gov">mailto:petsc-users<span>&#64;</span>mcs<span>&#46;</span>anl<span>&#46;</span>gov</a> or <a class="reference external" href="mailto:petsc-maint&#37;&#52;&#48;mcs&#46;anl&#46;gov">mailto:petsc-maint<span>&#64;</span>mcs<span>&#46;</span>anl<span>&#46;</span>gov</a> if you want advice about how to
implement them.</p>
</li>
<li><p>If the method converges in preconditioned residual, but not in true residual, the
preconditioner is likely singular or nearly so. This is common for saddle point problems
(e.g. incompressible flow) or strongly nonsymmetric operators (e.g. low-Mach hyperbolic
problems with large time steps).</p></li>
<li><p>The preconditioner is too weak or is unstable. See if <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">asm</span> <span class="pre">-sub_pc_type</span> <span class="pre">lu</span></code>
improves the convergence rate. If GMRES is losing too much progress in the restart, see
if longer restarts help <code class="docutils notranslate"><span class="pre">-ksp_gmres_restart</span> <span class="pre">300</span></code>. If a transpose is available, try
<code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">bcgs</span></code> or other methods that do not require a restart.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Unfortunately convergence with these methods is frequently erratic.</p>
</div>
</li>
<li><p>The preconditioner is nonlinear (e.g. a nested iterative solve), try <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">fgmres</span></code> or <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">gcr</span></code>.</p></li>
<li><p>You are using geometric multigrid, but some equations (often boundary conditions) are
not scaled compatibly between levels. Try <code class="docutils notranslate"><span class="pre">-pc_mg_galerkin</span></code> both to algebraically
construct a correctly scaled coarse operator or make sure that all the equations are
scaled in the same way if you want to use rediscretized coarse levels.</p></li>
<li><p>The matrix is very ill-conditioned. Check the <a class="reference internal" href="#doc-faq-usage-condnum"><span class="std std-ref">condition number</span></a>.</p>
<ul class="simple">
<li><p>Try to improve it by choosing the relative scaling of components/boundary conditions.</p></li>
<li><p>Try <code class="docutils notranslate"><span class="pre">-ksp_diagonal_scale</span> <span class="pre">-ksp_diagonal_scale_fix</span></code>.</p></li>
<li><p>Perhaps change the formulation of the problem to produce more friendly algebraic
equations.</p></li>
</ul>
</li>
<li><p>Change the units (nondimensionalization), boundary condition scaling, or formulation so
that the Jacobian is better conditioned. See <a class="reference external" href="https://en.wikipedia.org/wiki/Buckingham_%CF%80_theorem">Buckingham pi theorem</a> and <a class="reference external" href="https://epubs.siam.org/doi/pdf/10.1137/16M1107127">Dimensional and
Scaling Analysis</a>.</p></li>
<li><p>Classical Gram-Schmidt is becoming unstable, try <code class="docutils notranslate"><span class="pre">-ksp_gmres_modifiedgramschmidt</span></code> or
use a method that orthogonalizes differently, e.g. <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">gcr</span></code>.</p></li>
</ul>
</section>
<section id="i-get-the-error-message-actual-argument-at-1-to-assumed-type-dummy-is-of-derived-type-with-type-bound-or-final-procedures">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">I get the error message: Actual argument at (1) to assumed-type dummy is of derived type with type-bound or FINAL procedures</a><a class="headerlink" href="#i-get-the-error-message-actual-argument-at-1-to-assumed-type-dummy-is-of-derived-type-with-type-bound-or-final-procedures" title="Link to this heading">#</a></h3>
<p>Use the following code-snippet:</p>
<div class="highlight-fortran notranslate"><div class="highlight"><pre><span></span><span class="k">module </span><span class="n">context_module</span>
<span class="cp">#include petsc/finclude/petsc.h</span>
<span class="k">use </span><span class="n">petsc</span>
<span class="k">implicit none</span>
<span class="k">private</span>
<span class="k">type</span><span class="p">,</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="kd">::</span><span class="w">  </span><span class="n">context_type</span>
<span class="w">  </span><span class="k">private</span>
<span class="k">  </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">foo</span>
<span class="k">contains</span>
<span class="k">  procedure</span><span class="p">,</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">init</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">context_init</span>
<span class="k">end type </span><span class="n">context_type</span>
<span class="k">contains</span>
<span class="k">subroutine </span><span class="n">context_init</span><span class="p">(</span><span class="n">self</span><span class="p">,</span><span class="w"> </span><span class="n">foo</span><span class="p">)</span>
<span class="w">  </span><span class="k">class</span><span class="p">(</span><span class="n">context_type</span><span class="p">),</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">in</span><span class="w"> </span><span class="n">out</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">self</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">in</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">foo</span>
<span class="w">  </span><span class="n">self</span><span class="p">%</span><span class="n">foo</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">foo</span>
<span class="k">end subroutine </span><span class="n">context_init</span>
<span class="k">end module </span><span class="n">context_module</span>

<span class="c">!------------------------------------------------------------------------</span>

<span class="k">program </span><span class="n">test_snes</span>
<span class="k">use</span><span class="p">,</span><span class="k">intrinsic</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="nb">iso_c_binding</span>
<span class="k">use </span><span class="n">petsc</span>
<span class="k">use </span><span class="n">context_module</span>
<span class="k">implicit none</span>

<span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">snes</span>
<span class="k">type</span><span class="p">(</span><span class="n">context_type</span><span class="p">),</span><span class="k">target</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">context</span>
<span class="k">type</span><span class="p">(</span><span class="kt">c_ptr</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">contextOut</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">ierr</span>

<span class="k">call </span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">(</span><span class="n">PETSC_NULL_CHARACTER</span><span class="p">,</span><span class="w"> </span><span class="n">ierr</span><span class="p">)</span>
<span class="k">call </span><span class="n"><a href="../manualpages/SNES/SNESCreate.html">SNESCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">ierr</span><span class="p">)</span>
<span class="k">call </span><span class="n">context</span><span class="p">%</span><span class="n">init</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

<span class="n">contextOut</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">c_loc</span><span class="p">(</span><span class="n">context</span><span class="p">)</span><span class="w"> </span><span class="c">! contextOut is a C pointer on context</span>

<span class="k">call </span><span class="n"><a href="../manualpages/SNES/SNESSetConvergenceTest.html">SNESSetConvergenceTest</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">convergence</span><span class="p">,</span><span class="w"> </span><span class="n">contextOut</span><span class="p">,</span><span class="w"> </span><span class="n">PETSC_NULL_FUNCTION</span><span class="p">,</span><span class="w"> </span><span class="n">ierr</span><span class="p">)</span>

<span class="k">call </span><span class="n"><a href="../manualpages/SNES/SNESDestroy.html">SNESDestroy</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">ierr</span><span class="p">)</span>
<span class="k">call </span><span class="n"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a></span><span class="p">(</span><span class="n">ierr</span><span class="p">)</span>

<span class="k">contains</span>

<span class="k">subroutine </span><span class="n">convergence</span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">num_iterations</span><span class="p">,</span><span class="w"> </span><span class="n">xnorm</span><span class="p">,</span><span class="w"> </span><span class="n">pnorm</span><span class="p">,</span><span class="n">fnorm</span><span class="p">,</span><span class="w"> </span><span class="n">reason</span><span class="p">,</span><span class="w"> </span><span class="n">contextIn</span><span class="p">,</span><span class="w"> </span><span class="n">ierr</span><span class="p">)</span>
<span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">in</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">snes</span>

<span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">in</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">num_iterations</span>
<span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">in</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">xnorm</span><span class="p">,</span><span class="w"> </span><span class="n">pnorm</span><span class="p">,</span><span class="w"> </span><span class="n">fnorm</span>
<span class="n"><a href="../manualpages/SNES/SNESConvergedReason.html">SNESConvergedReason</a></span><span class="p">,</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">out</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">reason</span>
<span class="k">type</span><span class="p">(</span><span class="kt">c_ptr</span><span class="p">),</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">in</span><span class="w"> </span><span class="n">out</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">contextIn</span>
<span class="k">type</span><span class="p">(</span><span class="n">context_type</span><span class="p">),</span><span class="w"> </span><span class="k">pointer</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">context</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="p">,</span><span class="w"> </span><span class="k">intent</span><span class="p">(</span><span class="n">out</span><span class="p">)</span><span class="w"> </span><span class="kd">::</span><span class="w"> </span><span class="n">ierr</span>

<span class="k">call </span><span class="nb">c_f_pointer</span><span class="p">(</span><span class="n">contextIn</span><span class="p">,</span><span class="n">context</span><span class="p">)</span><span class="w">  </span><span class="c">! convert the C pointer to a Fortran pointer to use context as in the main program</span>
<span class="n">reason</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span>
<span class="n">ierr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span>
<span class="k">end subroutine </span><span class="n">convergence</span>
<span class="k">end program </span><span class="n">test_snes</span>
</pre></div>
</div>
</section>
<section id="in-c-i-get-a-crash-on-vecdestroy-or-some-other-petsc-object-at-the-end-of-the-program">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">In C++ I get a crash on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a>()</span></code> (or some other PETSc object) at the end of the program</a><a class="headerlink" href="#in-c-i-get-a-crash-on-vecdestroy-or-some-other-petsc-object-at-the-end-of-the-program" title="Link to this heading">#</a></h3>
<p>This can happen when the destructor for a C++ class is automatically called at the end of
the program after <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a>()</span></code>. Use the following code-snippet:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">());</span>
<span class="w">  </span><span class="p">{</span>
<span class="w">    </span><span class="n">your</span><span class="w"> </span><span class="n">variables</span>
<span class="w">    </span><span class="n">your</span><span class="w"> </span><span class="n">code</span>

<span class="w">    </span><span class="p">...</span><span class="w">   </span><span class="cm">/* all your destructors are called here automatically by C++ so they work correctly */</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a></span><span class="p">());</span>
<span class="w">  </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
</section>
<hr class="docutils" />
<section id="debugging">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Debugging</a><a class="headerlink" href="#debugging" title="Link to this heading">#</a></h2>
<section id="what-does-the-message-hwloc-linux-ignoring-pci-device-with-non-16bit-domain-mean">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What does the message hwloc/linux: Ignoring PCI device with non-16bit domain mean?</a><a class="headerlink" href="#what-does-the-message-hwloc-linux-ignoring-pci-device-with-non-16bit-domain-mean" title="Link to this heading">#</a></h3>
<p>This is printed by the hwloc library that is used by some MPI implementations. It can be ignored.
To prevent the message from always being printed set the environmental variable <code class="docutils notranslate"><span class="pre">HWLOC_HIDE_ERRORS</span></code> to 2.
For example</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">export</span><span class="w"> </span><span class="n">HWLOC_HIDE_ERRORS</span><span class="o">=</span><span class="mi">2</span>
</pre></div>
</div>
<p>which can be added to your login profile file such as <code class="docutils notranslate"><span class="pre">~/.bashrc</span></code>.</p>
</section>
<section id="how-do-i-turn-off-petsc-signal-handling-so-i-can-use-the-c-option-on-xlf">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I turn off PETSc signal handling so I can use the <code class="docutils notranslate"><span class="pre">-C</span></code> Option On <code class="docutils notranslate"><span class="pre">xlf</span></code>?</a><a class="headerlink" href="#how-do-i-turn-off-petsc-signal-handling-so-i-can-use-the-c-option-on-xlf" title="Link to this heading">#</a></h3>
<p>Immediately after calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code> call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscPopSignalHandler.html">PetscPopSignalHandler</a>()</span></code>.</p>
<p>Some Fortran compilers including the IBM xlf, xlF etc compilers have a compile option
(<code class="docutils notranslate"><span class="pre">-C</span></code> for IBM’s) that causes all array access in Fortran to be checked that they are
in-bounds. This is a great feature but does require that the array dimensions be set
explicitly, not with a *.</p>
</section>
<section id="how-do-i-debug-if-start-in-debugger-does-not-work-on-my-machine">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I debug if <code class="docutils notranslate"><span class="pre">-start_in_debugger</span></code> does not work on my machine?</a><a class="headerlink" href="#how-do-i-debug-if-start-in-debugger-does-not-work-on-my-machine" title="Link to this heading">#</a></h3>
<p>The script <a class="github reference external" href="https://github.com/Azrael3000/tmpi">Azrael3000/tmpi</a> can be used to run multiple MPI
ranks in the debugger using tmux.</p>
<p>On newer macOS machines - one has to be in admin group to be able to use debugger.</p>
<p>On newer Ubuntu linux machines - one has to disable <code class="docutils notranslate"><span class="pre">ptrace_scope</span></code> with</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="m">0</span><span class="w"> </span>&gt;<span class="w"> </span>/proc/sys/kernel/yama/ptrace_scope
</pre></div>
</div>
<p>to get start in debugger working.</p>
<p>If <code class="docutils notranslate"><span class="pre">-start_in_debugger</span></code> does not work on your OS, for a uniprocessor job, just
try the debugger directly, for example: <code class="docutils notranslate"><span class="pre">gdb</span> <span class="pre">ex1</span></code>. You can also use <a class="reference external" href="https://totalview.io/products/totalview">TotalView</a> which is a good graphical parallel debugger.</p>
</section>
<section id="how-do-i-see-where-my-code-is-hanging">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I see where my code is hanging?</a><a class="headerlink" href="#how-do-i-see-where-my-code-is-hanging" title="Link to this heading">#</a></h3>
<p>You can use the <code class="docutils notranslate"><span class="pre">-start_in_debugger</span></code> option to start all processes in the debugger (each
will come up in its own xterm) or run in <a class="reference external" href="https://totalview.io/products/totalview">TotalView</a>. Then use <code class="docutils notranslate"><span class="pre">cont</span></code> (for continue) in each
xterm. Once you are sure that the program is hanging, hit control-c in each xterm and then
use ‘where’ to print a stack trace for each process.</p>
</section>
<section id="how-can-i-inspect-petsc-vector-and-matrix-values-when-in-the-debugger">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I inspect PETSc vector and matrix values when in the debugger?</a><a class="headerlink" href="#how-can-i-inspect-petsc-vector-and-matrix-values-when-in-the-debugger" title="Link to this heading">#</a></h3>
<p>I will illustrate this with <code class="docutils notranslate"><span class="pre">gdb</span></code>, but it should be similar on other debuggers. You can
look at local <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> values directly by obtaining the array. For a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> v, we can
print all local values using:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp gp-VirtualEnv">(gdb)</span> <span class="go">p ((Vec_Seq*) v-&gt;data)-&gt;array[0]@v-&gt;map.n</span>
</pre></div>
</div>
<p>However, this becomes much more complicated for a matrix. Therefore, it is advisable to use the default viewer to look at the object. For a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> v and a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code> m, this would be:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp gp-VirtualEnv">(gdb)</span> <span class="go">call <a href="../manualpages/Vec/VecView.html">VecView</a>(v, 0)</span>
<span class="gp gp-VirtualEnv">(gdb)</span> <span class="go">call <a href="../manualpages/Mat/MatView.html">MatView</a>(m, 0)</span>
</pre></div>
</div>
<p>or with a communicator other than <code class="docutils notranslate"><span class="pre">MPI_COMM_WORLD</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp gp-VirtualEnv">(gdb)</span> <span class="go">call <a href="../manualpages/Mat/MatView.html">MatView</a>(m, <a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_.html">PETSC_VIEWER_STDOUT_</a>(m-&gt;comm))</span>
</pre></div>
</div>
<p>Totalview 8.8.0+ has a new feature that allows libraries to provide their own code to
display objects in the debugger. Thus in theory each PETSc object, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code> etc
could have custom code to print values in the object. We have only done this for the most
elementary display of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>. See the routine <code class="docutils notranslate"><span class="pre">TV_display_type()</span></code> in
<code class="docutils notranslate"><span class="pre">src/vec/vec/interface/vector.c</span></code> for an example of how these may be written. Contact us
if you would like to add more.</p>
</section>
<section id="how-can-i-find-the-cause-of-floating-point-exceptions-like-not-a-number-nan-or-infinity">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How can I find the cause of floating point exceptions like not-a-number (NaN) or infinity?</a><a class="headerlink" href="#how-can-i-find-the-cause-of-floating-point-exceptions-like-not-a-number-nan-or-infinity" title="Link to this heading">#</a></h3>
<p>The best way to locate floating point exceptions is to use a debugger. On supported
architectures (including Linux and glibc-based systems), just run in a debugger and pass
<code class="docutils notranslate"><span class="pre">-fp_trap</span></code> to the PETSc application. This will activate signaling exceptions and the
debugger will break on the line that first divides by zero or otherwise generates an
exceptions.</p>
<p>Without a debugger, running with <code class="docutils notranslate"><span class="pre">-fp_trap</span></code> in debug mode will only identify the
function in which the error occurred, but not the line or the type of exception. If
<code class="docutils notranslate"><span class="pre">-fp_trap</span></code> is not supported on your architecture, consult the documentation for your
debugger since there is likely a way to have it catch exceptions.</p>
</section>
<section id="error-while-loading-shared-libraries-libimf-so-cannot-open-shared-object-file-no-such-file-or-directory">
<span id="error-libimf"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Error while loading shared libraries: libimf.so: cannot open shared object file: No such file or directory</a><a class="headerlink" href="#error-while-loading-shared-libraries-libimf-so-cannot-open-shared-object-file-no-such-file-or-directory" title="Link to this heading">#</a></h3>
<p>The Intel compilers use shared libraries (like libimf) that cannot be found, by default, at run
time. When using the Intel compilers (and running the resulting code) you must make sure
that the proper Intel initialization scripts are run. This is usually done by adding some
code into your <code class="docutils notranslate"><span class="pre">.cshrc</span></code>, <code class="docutils notranslate"><span class="pre">.bashrc</span></code>, <code class="docutils notranslate"><span class="pre">.profile</span></code> etc file. Sometimes on batch file
systems that do now access your initialization files (like .cshrc) you must include the
initialization calls in your batch file submission.</p>
<p>For example, on my Mac using <code class="docutils notranslate"><span class="pre">csh</span></code> I have the following in my <code class="docutils notranslate"><span class="pre">.cshrc</span></code> file:</p>
<div class="highlight-csh notranslate"><div class="highlight"><pre><span></span><span class="nb">source</span> /opt/intel/cc/10.1.012/bin/iccvars.csh
<span class="nb">source</span> /opt/intel/fc/10.1.012/bin/ifortvars.csh
<span class="nb">source</span> /opt/intel/idb/10.1.012/bin/idbvars.csh
</pre></div>
</div>
<p>And in my <code class="docutils notranslate"><span class="pre">.profile</span></code> I have</p>
<div class="highlight-csh notranslate"><div class="highlight"><pre><span></span><span class="nb">source</span> /opt/intel/cc/10.1.012/bin/iccvars.sh
<span class="nb">source</span> /opt/intel/fc/10.1.012/bin/ifortvars.sh
<span class="nb">source</span> /opt/intel/idb/10.1.012/bin/idbvars.sh
</pre></div>
</div>
</section>
<section id="what-does-object-type-not-set-argument-n-mean">
<span id="object-type-not-set"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What does “Object Type Not Set: Argument # N” Mean?</a><a class="headerlink" href="#what-does-object-type-not-set-argument-n-mean" title="Link to this heading">#</a></h3>
<p>Many operations on PETSc objects require that the specific type of the object be set before the operations is performed. You must call <code class="docutils notranslate"><span class="pre">XXXSetType()</span></code> or <code class="docutils notranslate"><span class="pre">XXXSetFromOptions()</span></code> before you make the offending call. For example</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">A</span><span class="p">;</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">A</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">A</span><span class="p">,....));</span>
</pre></div>
</div>
<p>will not work. You must add <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetType.html">MatSetType</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetFromOptions.html">MatSetFromOptions</a>()</span></code> before the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a>()</span></code>. I.e.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">A</span><span class="p">;</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">A</span><span class="p">));</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetType.html">MatSetType</a></span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span><span class="p">));</span>
<span class="cm">/* Will override <a href="../manualpages/Mat/MatSetType.html">MatSetType</a>() */</span>
<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetFromOptions.html">MatSetFromOptions</a></span><span class="p">());</span>

<span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">A</span><span class="p">,....));</span>
</pre></div>
</div>
</section>
<section id="what-does-error-detected-in-petscsplitownership-about-sum-of-local-lengths-mean">
<span id="split-ownership"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What does error detected in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscSplitOwnership.html">PetscSplitOwnership</a>()</span></code> about “sum of local lengths …”: mean?</a><a class="headerlink" href="#what-does-error-detected-in-petscsplitownership-about-sum-of-local-lengths-mean" title="Link to this heading">#</a></h3>
<p>In a previous call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetSizes.html">VecSetSizes</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetSizes.html">MatSetSizes</a>()</span></code>, <code class="docutils notranslate"><span class="pre">VecCreateXXX()</span></code> or
<code class="docutils notranslate"><span class="pre">MatCreateXXX()</span></code> you passed in local and global sizes that do not make sense for the
correct number of processors. For example if you pass in a local size of 2 and a global
size of 100 and run on two processors, this cannot work since the sum of the local sizes
is 4, not 100.</p>
</section>
<section id="what-does-corrupt-argument-or-caught-signal-or-segv-or-segmentation-violation-or-bus-error-mean-can-i-use-valgrind-or-cuda-memcheck-to-debug-memory-corruption-issues">
<span id="valgrind"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What does “corrupt argument” or “caught signal” Or “SEGV” Or “segmentation violation” Or “bus error” mean? Can I use Valgrind or CUDA-Memcheck to debug memory corruption issues?</a><a class="headerlink" href="#what-does-corrupt-argument-or-caught-signal-or-segv-or-segmentation-violation-or-bus-error-mean-can-i-use-valgrind-or-cuda-memcheck-to-debug-memory-corruption-issues" title="Link to this heading">#</a></h3>
<p>Sometimes it can mean an argument to a function is invalid. In Fortran this may be caused
by forgetting to list an argument in the call, especially the final <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span></code>.</p>
<p>Otherwise it is usually caused by memory corruption; that is somewhere the code is writing
out of array bounds. To track this down rerun the debug version of the code with the
option <code class="docutils notranslate"><span class="pre">-malloc_debug</span></code>. Occasionally the code may crash only with the optimized version,
in that case run the optimized version with <code class="docutils notranslate"><span class="pre">-malloc_debug</span></code>. If you determine the
problem is from memory corruption you can put the macro CHKMEMQ in the code near the crash
to determine exactly what line is causing the problem.</p>
<p>If <code class="docutils notranslate"><span class="pre">-malloc_debug</span></code> does not help: on NVIDIA CUDA systems you can use <a class="reference external" href="https://docs.nvidia.com/cuda/cuda-memcheck/index.html">https://docs.nvidia.com/cuda/cuda-memcheck/index.html</a></p>
<p>If <code class="docutils notranslate"><span class="pre">-malloc_debug</span></code> does not help: on GNU/Linux (not macOS machines) - you can
use <a class="reference external" href="http://valgrind.org">valgrind</a>. Follow the below instructions:</p>
<ol class="arabic">
<li><p><code class="docutils notranslate"><span class="pre">configure</span></code> PETSc with <code class="docutils notranslate"><span class="pre">--download-mpich</span> <span class="pre">--with-debugging</span></code> (you can use other MPI implementations but most produce spurious Valgrind messages)</p></li>
<li><p>Compile your application code with this build of PETSc.</p></li>
<li><p>Run with Valgrind.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">$PETSC_DIR</span>/lib/petsc/bin/petscmpiexec<span class="w"> </span>-valgrind<span class="w"> </span>-n<span class="w"> </span>NPROC<span class="w"> </span>PETSCPROGRAMNAME<span class="w"> </span>PROGRAMOPTIONS
</pre></div>
</div>
<p>or</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mpiexec<span class="w"> </span>-n<span class="w"> </span>NPROC<span class="w"> </span>valgrind<span class="w"> </span>--tool<span class="o">=</span>memcheck<span class="w"> </span>-q<span class="w"> </span>--num-callers<span class="o">=</span><span class="m">20</span><span class="w"> </span><span class="se">\</span>
--suppressions<span class="o">=</span><span class="nv">$PETSC_DIR</span>/share/petsc/suppressions/valgrind<span class="w"> </span><span class="se">\</span>
--log-file<span class="o">=</span>valgrind.log.%p<span class="w"> </span>PETSCPROGRAMNAME<span class="w"> </span>-malloc<span class="w"> </span>off<span class="w"> </span>PROGRAMOPTIONS
</pre></div>
</div>
</li>
</ol>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p>option <code class="docutils notranslate"><span class="pre">--with-debugging</span></code> enables valgrind to give stack trace with additional
source-file:line-number info.</p></li>
<li><p>option <code class="docutils notranslate"><span class="pre">--download-mpich</span></code> is valgrind clean, other MPI builds are not valgrind clean.</p></li>
<li><p>when <code class="docutils notranslate"><span class="pre">--download-mpich</span></code> is used - mpiexec will be in <code class="docutils notranslate"><span class="pre">$PETSC_ARCH/bin</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">--log-file=valgrind.log.%p</span></code> option tells valgrind to store the output from each
process in a different file [as %p i.e PID, is different for each MPI process.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">memcheck</span></code> will not find certain array access that violate static array
declarations so if memcheck runs clean you can try the <code class="docutils notranslate"><span class="pre">--tool=exp-ptrcheck</span></code>
instead.</p></li>
</ul>
</div>
<p>You might also consider using <a class="reference external" href="http://drmemory.org">http://drmemory.org</a> which has support for GNU/Linux, Apple
Mac OS and Microsoft Windows machines. (Note we haven’t tried this ourselves).</p>
</section>
<section id="what-does-detected-zero-pivot-in-lu-factorization-mean">
<span id="zeropivot"></span><h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What does “detected zero pivot in LU factorization” mean?</a><a class="headerlink" href="#what-does-detected-zero-pivot-in-lu-factorization-mean" title="Link to this heading">#</a></h3>
<p>A zero pivot in LU, ILU, Cholesky, or ICC sparse factorization does not always mean that
the matrix is singular. You can use</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-pc_factor_shift_type nonzero -pc_factor_shift_amount [amount]
</pre></div>
</div>
<p>or</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-pc_factor_shift_type positive_definite -[level]_pc_factor_shift_type nonzero
 -pc_factor_shift_amount [amount]
</pre></div>
</div>
<p>or</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-[level]_pc_factor_shift_type positive_definite
</pre></div>
</div>
<p>to prevent the zero pivot. [level] is “sub” when lu, ilu, cholesky, or icc are employed in
each individual block of the bjacobi or ASM preconditioner. [level] is “mg_levels” or
“mg_coarse” when lu, ilu, cholesky, or icc are used inside multigrid smoothers or to the
coarse grid solver. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFactorSetShiftType.html">PCFactorSetShiftType</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFactorSetShiftAmount.html">PCFactorSetShiftAmount</a>()</span></code>.</p>
<p>This error can also happen if your matrix is singular, see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNullSpace.html">MatSetNullSpace</a>()</span></code> for how
to handle this. If this error occurs in the zeroth row of the matrix, it is likely you
have an error in the code that generates the matrix.</p>
</section>
<section id="you-create-draw-windows-or-petscviewerdraw-windows-or-use-options-ksp-monitor-draw-draw-lg-or-snes-monitor-draw-draw-lg-and-the-program-seems-to-run-ok-but-windows-never-open">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">You create draw windows or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSCVIEWERDRAW.html">PETSCVIEWERDRAW</a></span></code> windows or use options <code class="docutils notranslate"><span class="pre">-ksp_monitor</span> <span class="pre">draw::draw_lg</span></code> or <code class="docutils notranslate"><span class="pre">-snes_monitor</span> <span class="pre">draw::draw_lg</span></code> and the program seems to run OK but windows never open</a><a class="headerlink" href="#you-create-draw-windows-or-petscviewerdraw-windows-or-use-options-ksp-monitor-draw-draw-lg-or-snes-monitor-draw-draw-lg-and-the-program-seems-to-run-ok-but-windows-never-open" title="Link to this heading">#</a></h3>
<p>The libraries were compiled without support for X windows. Make sure that <code class="docutils notranslate"><span class="pre">configure</span></code>
was run with the option <code class="docutils notranslate"><span class="pre">--with-x</span></code>.</p>
</section>
<section id="the-program-seems-to-use-more-and-more-memory-as-it-runs-even-though-you-don-t-think-you-are-allocating-more-memory">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">The program seems to use more and more memory as it runs, even though you don’t think you are allocating more memory</a><a class="headerlink" href="#the-program-seems-to-use-more-and-more-memory-as-it-runs-even-though-you-don-t-think-you-are-allocating-more-memory" title="Link to this heading">#</a></h3>
<p>Some of the following may be occurring:</p>
<ul class="simple">
<li><p>You are creating new PETSc objects but never freeing them.</p></li>
<li><p>There is a memory leak in PETSc or your code.</p></li>
<li><p>Something much more subtle: (if you are using Fortran). When you declare a large array
in Fortran, the operating system does not allocate all the memory pages for that array
until you start using the different locations in the array. Thus, in a code, if at each
step you start using later values in the array your virtual memory usage will “continue”
to increase as measured by <code class="docutils notranslate"><span class="pre">ps</span></code> or <code class="docutils notranslate"><span class="pre">top</span></code>.</p></li>
<li><p>You are running with the <code class="docutils notranslate"><span class="pre">-log</span></code>, <code class="docutils notranslate"><span class="pre">-log_mpe</span></code>, or <code class="docutils notranslate"><span class="pre">-log_all</span></code> option. With these
options, a great deal of logging information is stored in memory until the conclusion of
the run.</p></li>
<li><p>You are linking with the MPI profiling libraries; these cause logging of all MPI
activities. Another symptom is at the conclusion of the run it may print some message
about writing log files.</p></li>
</ul>
<p>The following may help:</p>
<ul class="simple">
<li><p>Run with the <code class="docutils notranslate"><span class="pre">-malloc_debug</span></code> option and <code class="docutils notranslate"><span class="pre">-malloc_view</span></code>. Or use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscMallocDump.html">PetscMallocDump</a>()</span></code>
and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscMallocView.html">PetscMallocView</a>()</span></code> sprinkled about your code to track memory that is allocated
and not later freed. Use the commands <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscMallocGetCurrentUsage.html">PetscMallocGetCurrentUsage</a>()</span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscMemoryGetCurrentUsage.html">PetscMemoryGetCurrentUsage</a>()</span></code> to monitor memory allocated and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscMallocGetMaximumUsage.html">PetscMallocGetMaximumUsage</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscMemoryGetMaximumUsage.html">PetscMemoryGetMaximumUsage</a>()</span></code> for total memory
used as the code progresses.</p></li>
<li><p>This is just the way Unix works and is harmless.</p></li>
<li><p>Do not use the <code class="docutils notranslate"><span class="pre">-log</span></code>, <code class="docutils notranslate"><span class="pre">-log_mpe</span></code>, or <code class="docutils notranslate"><span class="pre">-log_all</span></code> option, or use
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Log/PetscLogEventDeactivate.html">PetscLogEventDeactivate</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Log/PetscLogEventDeactivateClass.html">PetscLogEventDeactivateClass</a>()</span></code> to turn off logging of
specific events.</p></li>
<li><p>Make sure you do not link with the MPI profiling libraries.</p></li>
</ul>
</section>
<section id="when-calling-matpartitioningapply-you-get-a-message-error-key-16615-not-found">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">When calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatPartitioningApply.html">MatPartitioningApply</a>()</span></code> you get a message “Error! Key 16615 Not Found”</a><a class="headerlink" href="#when-calling-matpartitioningapply-you-get-a-message-error-key-16615-not-found" title="Link to this heading">#</a></h3>
<p>The graph of the matrix you are using is not symmetric. You must use symmetric matrices
for partitioning.</p>
</section>
<section id="with-gmres-at-restart-the-second-residual-norm-printed-does-not-match-the-first">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">With GMRES at restart the second residual norm printed does not match the first</a><a class="headerlink" href="#with-gmres-at-restart-the-second-residual-norm-printed-does-not-match-the-first" title="Link to this heading">#</a></h3>
<p>I.e.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>26 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 3.421544615851e-04
27 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 2.973675659493e-04
28 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 2.588642948270e-04
29 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 2.268190747349e-04
30 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 1.977245964368e-04
30 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 1.994426291979e-04 &lt;----- At restart the residual norm is printed a second time
</pre></div>
</div>
<p>This is actually not surprising! GMRES computes the norm of the residual at each iteration
via a recurrence relation between the norms of the residuals at the previous iterations
and quantities computed at the current iteration. It does not compute it via directly
<span class="math">\(|| b - A x^{n} ||\)</span>.</p>
<p>Sometimes, especially with an ill-conditioned matrix, or computation of the matrix-vector
product via differencing, the residual norms computed by GMRES start to “drift” from the
correct values. At the restart, we compute the residual norm directly, hence the “strange
stuff,” the difference printed. The drifting, if it remains small, is harmless (doesn’t
affect the accuracy of the solution that GMRES computes).</p>
<p>If you use a more powerful preconditioner the drift will often be smaller and less
noticeable. Of if you are running matrix-free you may need to tune the matrix-free
parameters.</p>
</section>
<section id="why-do-some-krylov-methods-seem-to-print-two-residual-norms-per-iteration">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why do some Krylov methods seem to print two residual norms per iteration?</a><a class="headerlink" href="#why-do-some-krylov-methods-seem-to-print-two-residual-norms-per-iteration" title="Link to this heading">#</a></h3>
<p>I.e.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1198 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 1.366052062216e-04
1198 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 1.931875025549e-04
1199 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 1.366026406067e-04
1199 <a href="../manualpages/KSP/KSP.html">KSP</a> Residual norm 1.931819426344e-04
</pre></div>
</div>
<p>Some Krylov methods, for example <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPTFQMR.html">KSPTFQMR</a></span></code>, actually have a “sub-iteration” of size 2
inside the loop. Each of the two substeps has its own matrix vector product and
application of the preconditioner and updates the residual approximations. This is why you
get this “funny” output where it looks like there are two residual norms per
iteration. You can also think of it as twice as many iterations.</p>
</section>
<section id="unable-to-locate-petsc-dynamic-library-libpetsc">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Unable to locate PETSc dynamic library <code class="docutils notranslate"><span class="pre">libpetsc</span></code></a><a class="headerlink" href="#unable-to-locate-petsc-dynamic-library-libpetsc" title="Link to this heading">#</a></h3>
<p>When using DYNAMIC libraries - the libraries cannot be moved after they are
installed. This could also happen on clusters - where the paths are different on the (run)
nodes - than on the (compile) front-end. <strong>Do not use dynamic libraries &amp; shared
libraries</strong>. Run <code class="docutils notranslate"><span class="pre">configure</span></code> with
<code class="docutils notranslate"><span class="pre">--with-shared-libraries=0</span> <span class="pre">--with-dynamic-loading=0</span></code>.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>This option has been removed in PETSc v3.5</p>
</div>
</section>
<section id="how-do-i-determine-what-update-to-petsc-broke-my-code">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I determine what update to PETSc broke my code?</a><a class="headerlink" href="#how-do-i-determine-what-update-to-petsc-broke-my-code" title="Link to this heading">#</a></h3>
<p>If at some point (in PETSc code history) you had a working code - but the latest PETSc
code broke it, its possible to determine the PETSc code change that might have caused this
behavior. This is achieved by:</p>
<ul class="simple">
<li><p>Using Git to access PETSc sources</p></li>
<li><p>Knowing the Git commit for the known working version of PETSc</p></li>
<li><p>Knowing the Git commit for the known broken version of PETSc</p></li>
<li><p>Using the <a class="reference external" href="https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-bisect.html">bisect</a>
functionality of Git</p></li>
</ul>
<p>Git bisect can be done as follows:</p>
<ol class="arabic">
<li><p>Get PETSc development (main branch in git) sources</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>clone<span class="w"> </span>https://gitlab.com/petsc/petsc.git
</pre></div>
</div>
</li>
<li><p>Find the good and bad markers to start the bisection process. This can be done either
by checking <code class="docutils notranslate"><span class="pre">git</span> <span class="pre">log</span></code> or <code class="docutils notranslate"><span class="pre">gitk</span></code> or <a class="gitlab reference external" href="https://gitlab.com/petsc/petsc">petsc/petsc</a> or the web
history of petsc-release clones. Lets say the known bad commit is 21af4baa815c and
known good commit is 5ae5ab319844.</p></li>
<li><p>Start the bisection process with these known revisions. Build PETSc, and test your code
to confirm known good/bad behavior:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>bisect<span class="w"> </span>start<span class="w"> </span>21af4baa815c<span class="w"> </span>5ae5ab319844
</pre></div>
</div>
<p>build/test, perhaps discover that this new state is bad</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>bisect<span class="w"> </span>bad
</pre></div>
</div>
<p>build/test, perhaps discover that this state is good</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>bisect<span class="w"> </span>good
</pre></div>
</div>
<p>Now until done - keep bisecting, building PETSc, and testing your code with it and
determine if the code is working or not. After something like 5-15 iterations, <code class="docutils notranslate"><span class="pre">git</span> <span class="pre">bisect</span></code> will pin-point the exact code change that resulted in the difference in
application behavior.</p>
</li>
</ol>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>See <a class="reference external" href="https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-bisect.html">git-bisect(1)</a> and the
<a class="reference external" href="https://git-scm.com/book/en/Git-Tools-Debugging-with-Git">debugging section of the Git Book</a> for more debugging tips.</p>
</div>
</section>
<section id="how-to-fix-the-error-pmix-error-error-in-file-gds-ds12-lock-pthread-c">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How to fix the error “PMIX Error: error in file gds_ds12_lock_pthread.c”?</a><a class="headerlink" href="#how-to-fix-the-error-pmix-error-error-in-file-gds-ds12-lock-pthread-c" title="Link to this heading">#</a></h3>
<p>This seems to be an error when using Open MPI and OpenBLAS with threads (or perhaps other
packages that use threads).</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">PMIX_MCA_gds</span><span class="o">=</span><span class="nb">hash</span>
</pre></div>
</div>
<p>Should resolve the problem.</p>
<hr class="docutils" />
</section>
</section>
<section id="shared-libraries">
<span id="doc-faq-sharedlibs"></span><h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Shared Libraries</a><a class="headerlink" href="#shared-libraries" title="Link to this heading">#</a></h2>
<section id="can-i-install-petsc-libraries-as-shared-libraries">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Can I install PETSc libraries as shared libraries?</a><a class="headerlink" href="#can-i-install-petsc-libraries-as-shared-libraries" title="Link to this heading">#</a></h3>
<p>Yes. Use</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./configure<span class="w"> </span>--with-shared-libraries
</pre></div>
</div>
</section>
<section id="why-should-i-use-shared-libraries">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Why should I use shared libraries?</a><a class="headerlink" href="#why-should-i-use-shared-libraries" title="Link to this heading">#</a></h3>
<p>When you link to shared libraries, the function symbols from the shared libraries are not
copied in the executable. This way the size of the executable is considerably smaller than
when using regular libraries. This helps in a couple of ways:</p>
<ul class="simple">
<li><p>Saves disk space when more than one executable is created</p></li>
<li><p>Improves the compile time immensely, because the compiler has to write a much smaller
file (executable) to the disk.</p></li>
</ul>
</section>
<section id="how-do-i-link-to-the-petsc-shared-libraries">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">How do I link to the PETSc shared libraries?</a><a class="headerlink" href="#how-do-i-link-to-the-petsc-shared-libraries" title="Link to this heading">#</a></h3>
<p>By default, the compiler should pick up the shared libraries instead of the regular
ones. Nothing special should be done for this.</p>
</section>
<section id="what-if-i-want-to-link-to-the-regular-a-library-files">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What if I want to link to the regular <code class="docutils notranslate"><span class="pre">.a</span></code> library files?</a><a class="headerlink" href="#what-if-i-want-to-link-to-the-regular-a-library-files" title="Link to this heading">#</a></h3>
<p>You must run <code class="docutils notranslate"><span class="pre">configure</span></code> with the option <code class="docutils notranslate"><span class="pre">--with-shared-libraries=0</span></code> (you can use a
different <code class="docutils notranslate"><span class="pre">$PETSC_ARCH</span></code> for this build so you can easily switch between the two).</p>
</section>
<section id="what-do-i-do-if-i-want-to-move-my-executable-to-a-different-machine">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">What do I do if I want to move my executable to a different machine?</a><a class="headerlink" href="#what-do-i-do-if-i-want-to-move-my-executable-to-a-different-machine" title="Link to this heading">#</a></h3>
<p>You would also need to have access to the shared libraries on this new machine. The other
alternative is to build the executable without shared libraries by first deleting the
shared libraries, and then creating the executable.</p>
<div class="docutils container" id="id2">
<div role="list" class="citation-list">
<div class="citation" id="id2256" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">ESW14</a><span class="fn-bracket">]</span></span>
<p>Howard C. Elman, David J. Silvester, and Andrew J. Wathen. <em>Finite elements and fast iterative solvers: with applications in incompressible fluid dynamics</em>. Oxford University Press, 2014. URL: <a class="reference external" href="https://global.oup.com/academic/product/finite-elements-and-fast-iterative-solvers-9780199678792?cc=us&amp;lang=en&amp;">https://global.oup.com/academic/product/finite-elements-and-fast-iterative-solvers-9780199678792?cc=us&amp;lang=en&amp;</a>.</p>
</div>
</div>
</div>
</section>
</section>
</section>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="../petsc4py/index.html"
       title="previous page">
      <i class="fa-solid fa-angle-left"></i>
      <div class="prev-next-info">
        <p class="prev-next-subtitle">previous</p>
        <p class="prev-next-title">petsc4py API</p>
      </div>
    </a>
    <a class="right-next"
       href="../community/index.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Community</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            
              
                <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#general">General</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-subscribe-to-the-petsc-mailing-lists">How can I subscribe to the PETSc mailing lists?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#any-useful-books-on-numerical-computing">Any useful books on numerical computing?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-kind-of-parallel-computers-or-clusters-are-needed-to-use-petsc-or-why-do-i-get-little-speedup">What kind of parallel computers or clusters are needed to use PETSc? Or why do I get little speedup?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-kind-of-license-is-petsc-released-under">What kind of license is PETSc released under?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-is-petsc-written-in-c-instead-of-fortran-or-c">Why is PETSc written in C, instead of Fortran or C++?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#does-all-the-petsc-error-checking-and-logging-reduce-petsc-s-efficiency">Does all the PETSc error checking and logging reduce PETSc’s efficiency?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-such-a-small-group-of-people-manage-to-write-and-maintain-such-a-large-and-marvelous-package-as-petsc">How do such a small group of people manage to write and maintain such a large and marvelous package as PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#for-complex-numbers-will-i-get-better-performance-with-c">For complex numbers will I get better performance with C++?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-come-when-i-run-the-same-program-on-the-same-number-of-processes-i-get-a-different-answer">How come when I run the same program on the same number of processes I get a “different” answer?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-come-when-i-run-the-same-linear-solver-on-a-different-number-of-processes-it-takes-a-different-number-of-iterations">How come when I run the same linear solver on a different number of processes it takes a different number of iterations?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-petsc-use-gpus-to-speed-up-computations">Can PETSc use GPUs to speed up computations?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-i-run-petsc-with-extended-precision">Can I run PETSc with extended precision?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-doesn-t-petsc-use-qd-to-implement-support-for-extended-precision">Why doesn’t PETSc use Qd to implement support for extended precision?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-cite-petsc">How do I cite PETSc?</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#installation">Installation</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-begin-using-petsc-if-the-software-has-already-been-completely-built-and-installed-by-someone-else">How do I begin using PETSc if the software has already been completely built and installed by someone else?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#the-petsc-distribution-is-so-large-how-can-i-reduce-my-disk-space-usage">The PETSc distribution is SO Large. How can I reduce my disk space usage?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#i-want-to-use-petsc-only-for-uniprocessor-programs-must-i-still-install-and-use-a-version-of-mpi">I want to use PETSc only for uniprocessor programs. Must I still install and use a version of MPI?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-i-install-petsc-to-not-use-x-windows-either-under-unix-or-microsoft-windows-with-gcc">Can I install PETSc to not use X windows (either under Unix or Microsoft Windows with GCC)?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-do-you-use-mpi">Why do you use MPI?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-do-i-do-if-my-mpi-compiler-wrappers-are-invalid">What do I do if my MPI compiler wrappers are invalid?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#when-should-can-i-use-the-configure-option-with-64-bit-indices">When should/can I use the <code class="docutils notranslate"><span class="pre">configure</span></code> option <code class="docutils notranslate"><span class="pre">--with-64-bit-indices</span></code>?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-if-i-get-an-internal-compiler-error">What if I get an internal compiler error?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-enable-python-bindings-petsc4py-with-petsc">How do I enable Python bindings (petsc4py) with PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-fortran-compiler-do-you-recommend-on-macos">What Fortran compiler do you recommend on macOS?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-find-the-url-locations-of-the-packages-you-install-using-download-package">How can I find the URL locations of the packages you install using <code class="docutils notranslate"><span class="pre">--download-PACKAGE</span></code>?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-to-fix-the-problem-petsc-was-configured-with-one-mpich-or-open-mpi-mpi-h-version-but-now-appears-to-be-compiling-using-a-different-mpich-or-open-mpi-mpi-h-version">How to fix the problem: PETSc was configured with one MPICH (or Open MPI) <code class="docutils notranslate"><span class="pre">mpi.h</span></code> version but now appears to be compiling using a different MPICH (or Open MPI) <code class="docutils notranslate"><span class="pre">mpi.h</span></code> version</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-does-it-mean-when-make-check-hangs-or-errors-on-petscoptionsinsertfile">What does it mean when <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">check</span></code> hangs or errors on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsInsertFile.html">PetscOptionsInsertFile</a>()</span></code>?</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#usage">Usage</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-redirect-petsc-s-stdout-and-stderr-when-programming-with-a-gui-interface-in-windows-developer-studio-or-to-c-streams">How can I redirect PETSc’s <code class="docutils notranslate"><span class="pre">stdout</span></code> and <code class="docutils notranslate"><span class="pre">stderr</span></code> when programming with a GUI interface in Windows Developer Studio or to C++ streams?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#i-want-to-use-hypre-boomeramg-without-gmres-but-when-i-run-pc-type-hypre-pc-hypre-type-boomeramg-ksp-type-preonly-i-don-t-get-a-very-accurate-answer">I want to use Hypre boomerAMG without GMRES but when I run <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">boomeramg</span> <span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> I don’t get a very accurate answer!</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-use-petsc-for-domain-decomposition">How do I use PETSc for Domain Decomposition?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#you-have-mataij-and-matbaij-matrix-formats-and-matsbaij-for-symmetric-storage-how-come-no-matsaij">You have <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> matrix formats, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSBAIJ.html">MATSBAIJ</a></span></code> for symmetric storage, how come no <code class="docutils notranslate"><span class="pre">MATSAIJ</span></code>?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-i-create-baij-matrices-with-different-size-blocks-for-different-block-rows">Can I Create BAIJ matrices with different size blocks for different block rows?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-access-the-values-of-a-remote-parallel-petsc-vec">How do I access the values of a remote parallel PETSc Vec?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-collect-to-a-single-processor-all-the-values-from-a-parallel-petsc-vec">How do I collect to a single processor all the values from a parallel PETSc Vec?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-collect-all-the-values-from-a-parallel-petsc-vec-on-the-0th-rank">How do I collect all the values from a parallel PETSc Vec on the 0th rank?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-read-in-or-write-out-a-sparse-matrix-in-matrix-market-harwell-boeing-slapc-or-other-ascii-format">How can I read in or write out a sparse matrix in Matrix Market, Harwell-Boeing, Slapc or other ASCII format?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#does-tssetfromoptions-snessetfromoptions-or-kspsetfromoptions-reset-all-the-parameters-i-previously-set-or-how-come-do-they-not-seem-to-work">Does TSSetFromOptions(), SNESSetFromOptions(), or KSPSetFromOptions() reset all the parameters I previously set or how come do they not seem to work?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-compile-and-link-my-own-petsc-application-codes-and-can-i-use-my-own-makefile-or-rules-for-compiling-code-rather-than-petsc-s">How do I compile and link my own PETSc application codes and can I use my own <code class="docutils notranslate"><span class="pre">makefile</span></code> or rules for compiling code, rather than PETSc’s?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-i-use-cmake-to-build-my-own-project-that-depends-on-petsc">Can I use CMake to build my own project that depends on PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-put-carriage-returns-in-petscprintf-statements-from-fortran">How can I put carriage returns in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a>()</span></code> statements from Fortran?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-implement-callbacks-using-c-class-methods">How can I implement callbacks using C++ class methods?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#everyone-knows-that-when-you-code-newton-s-method-you-should-compute-the-function-and-its-jacobian-at-the-same-time-how-can-one-do-this-in-petsc">Everyone knows that when you code Newton’s Method you should compute the function and its Jacobian at the same time. How can one do this in PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#computing-the-jacobian-or-preconditioner-is-time-consuming-is-there-any-way-to-compute-it-less-often">Computing the Jacobian or preconditioner is time consuming. Is there any way to compute it less often?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-use-newton-s-method-jacobian-free-can-i-difference-a-different-function-than-provided-with-snessetfunction">How can I use Newton’s Method Jacobian free? Can I difference a different function than provided with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a>()</span></code>?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-determine-the-condition-number-of-a-matrix">How can I determine the condition number of a matrix?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-compute-the-inverse-of-a-matrix-in-petsc">How can I compute the inverse of a matrix in PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-compute-the-schur-complement-in-petsc">How can I compute the Schur complement in PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#do-you-have-examples-of-doing-unstructured-grid-finite-element-method-fem-with-petsc">Do you have examples of doing unstructured grid Finite Element Method (FEM) with PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmda-decomposes-the-domain-differently-than-the-mpi-cart-create-command-how-can-one-use-them-together">DMDA decomposes the domain differently than the MPI_Cart_create() command. How can one use them together?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#when-solving-a-system-with-dirichlet-boundary-conditions-i-can-use-matzerorows-to-eliminate-the-dirichlet-rows-but-this-results-in-a-non-symmetric-system-how-can-i-apply-dirichlet-boundary-conditions-but-keep-the-matrix-symmetric">When solving a system with Dirichlet boundary conditions I can use MatZeroRows() to eliminate the Dirichlet rows but this results in a non-Symmetric system. How can I apply Dirichlet boundary conditions but keep the matrix symmetric?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-get-petsc-vectors-and-matrices-to-matlab-or-vice-versa">How can I get PETSc vectors and matrices to MATLAB or vice versa?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-get-started-with-cython-so-that-i-can-extend-petsc4py">How do I get started with Cython so that I can extend petsc4py?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-compute-a-custom-norm-for-ksp-to-use-as-a-convergence-test-or-for-monitoring">How do I compute a custom norm for KSP to use as a convergence test or for monitoring?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#if-i-have-a-sequential-program-can-i-use-a-petsc-parallel-solver">If I have a sequential program can I use a PETSc parallel solver?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ts-or-snes-produces-infeasible-out-of-domain-solutions-or-states-how-can-i-prevent-this">TS or SNES produces infeasible (out of domain) solutions or states. How can I prevent this?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-petsc-work-with-hermitian-matrices">Can PETSc work with Hermitian matrices?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-assemble-a-bunch-of-similar-matrices">How can I assemble a bunch of similar matrices?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-one-resize-or-change-the-size-of-petsc-matrices-or-vectors">Can one resize or change the size of PETSc matrices or vectors?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-one-compute-the-nullspace-of-a-sparse-matrix-with-mumps">How can one compute the nullspace of a sparse matrix with MUMPS?</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#execution">Execution</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#petsc-executables-are-so-big-and-take-so-long-to-link">PETSc executables are SO big and take SO long to link</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-does-petsc-s-help-option-work-why-is-it-different-for-different-programs">How does PETSc’s <code class="docutils notranslate"><span class="pre">-help</span></code> option work? Why is it different for different programs?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#petsc-has-so-many-options-for-my-program-that-it-is-hard-to-keep-them-straight">PETSc has so many options for my program that it is hard to keep them straight</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#petsc-automatically-handles-many-of-the-details-in-parallel-pde-solvers-how-can-i-understand-what-is-really-happening-within-my-program">PETSc automatically handles many of the details in parallel PDE solvers. How can I understand what is really happening within my program?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#assembling-large-sparse-matrices-takes-a-long-time-what-can-i-do-to-make-this-process-faster-or-matsetvalues-is-so-slow-what-can-i-do-to-speed-it-up">Assembling large sparse matrices takes a long time. What can I do to make this process faster? Or MatSetValues() is so slow; what can I do to speed it up?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-generate-performance-summaries-with-petsc">How can I generate performance summaries with PETSc?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-know-the-amount-of-time-spent-on-each-level-of-the-multigrid-solver-preconditioner">How do I know the amount of time spent on each level of the multigrid solver/preconditioner?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#where-do-i-get-the-input-matrices-for-the-examples">Where do I get the input matrices for the examples?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#when-i-dump-some-matrices-and-vectors-to-binary-i-seem-to-be-generating-some-empty-files-with-info-extensions-what-s-the-deal-with-these">When I dump some matrices and vectors to binary, I seem to be generating some empty files with <code class="docutils notranslate"><span class="pre">.info</span></code> extensions. What’s the deal with these?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-is-my-parallel-solver-slower-than-my-sequential-solver-or-i-have-poor-speed-up">Why is my parallel solver slower than my sequential solver, or I have poor speed-up?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-steps-are-necessary-to-make-the-pipelined-solvers-execute-efficiently">What steps are necessary to make the pipelined solvers execute efficiently?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#when-using-petsc-in-single-precision-mode-with-precision-single-when-running-configure-are-the-operations-done-in-single-or-double-precision">When using PETSc in single precision mode (<code class="docutils notranslate"><span class="pre">--with-precision=single</span></code> when running <code class="docutils notranslate"><span class="pre">configure</span></code>) are the operations done in single or double precision?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-is-newton-s-method-snes-not-converging-or-converges-slowly">Why is Newton’s method (SNES) not converging, or converges slowly?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-is-the-linear-solver-ksp-not-converging-or-converges-slowly">Why is the linear solver (KSP) not converging, or converges slowly?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#i-get-the-error-message-actual-argument-at-1-to-assumed-type-dummy-is-of-derived-type-with-type-bound-or-final-procedures">I get the error message: Actual argument at (1) to assumed-type dummy is of derived type with type-bound or FINAL procedures</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#in-c-i-get-a-crash-on-vecdestroy-or-some-other-petsc-object-at-the-end-of-the-program">In C++ I get a crash on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a>()</span></code> (or some other PETSc object) at the end of the program</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#debugging">Debugging</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-does-the-message-hwloc-linux-ignoring-pci-device-with-non-16bit-domain-mean">What does the message hwloc/linux: Ignoring PCI device with non-16bit domain mean?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-turn-off-petsc-signal-handling-so-i-can-use-the-c-option-on-xlf">How do I turn off PETSc signal handling so I can use the <code class="docutils notranslate"><span class="pre">-C</span></code> Option On <code class="docutils notranslate"><span class="pre">xlf</span></code>?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-debug-if-start-in-debugger-does-not-work-on-my-machine">How do I debug if <code class="docutils notranslate"><span class="pre">-start_in_debugger</span></code> does not work on my machine?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-see-where-my-code-is-hanging">How do I see where my code is hanging?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-inspect-petsc-vector-and-matrix-values-when-in-the-debugger">How can I inspect PETSc vector and matrix values when in the debugger?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-can-i-find-the-cause-of-floating-point-exceptions-like-not-a-number-nan-or-infinity">How can I find the cause of floating point exceptions like not-a-number (NaN) or infinity?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#error-while-loading-shared-libraries-libimf-so-cannot-open-shared-object-file-no-such-file-or-directory">Error while loading shared libraries: libimf.so: cannot open shared object file: No such file or directory</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-does-object-type-not-set-argument-n-mean">What does “Object Type Not Set: Argument # N” Mean?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-does-error-detected-in-petscsplitownership-about-sum-of-local-lengths-mean">What does error detected in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscSplitOwnership.html">PetscSplitOwnership</a>()</span></code> about “sum of local lengths …”: mean?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-does-corrupt-argument-or-caught-signal-or-segv-or-segmentation-violation-or-bus-error-mean-can-i-use-valgrind-or-cuda-memcheck-to-debug-memory-corruption-issues">What does “corrupt argument” or “caught signal” Or “SEGV” Or “segmentation violation” Or “bus error” mean? Can I use Valgrind or CUDA-Memcheck to debug memory corruption issues?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-does-detected-zero-pivot-in-lu-factorization-mean">What does “detected zero pivot in LU factorization” mean?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#you-create-draw-windows-or-petscviewerdraw-windows-or-use-options-ksp-monitor-draw-draw-lg-or-snes-monitor-draw-draw-lg-and-the-program-seems-to-run-ok-but-windows-never-open">You create draw windows or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSCVIEWERDRAW.html">PETSCVIEWERDRAW</a></span></code> windows or use options <code class="docutils notranslate"><span class="pre">-ksp_monitor</span> <span class="pre">draw::draw_lg</span></code> or <code class="docutils notranslate"><span class="pre">-snes_monitor</span> <span class="pre">draw::draw_lg</span></code> and the program seems to run OK but windows never open</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#the-program-seems-to-use-more-and-more-memory-as-it-runs-even-though-you-don-t-think-you-are-allocating-more-memory">The program seems to use more and more memory as it runs, even though you don’t think you are allocating more memory</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#when-calling-matpartitioningapply-you-get-a-message-error-key-16615-not-found">When calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatPartitioningApply.html">MatPartitioningApply</a>()</span></code> you get a message “Error! Key 16615 Not Found”</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#with-gmres-at-restart-the-second-residual-norm-printed-does-not-match-the-first">With GMRES at restart the second residual norm printed does not match the first</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-do-some-krylov-methods-seem-to-print-two-residual-norms-per-iteration">Why do some Krylov methods seem to print two residual norms per iteration?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#unable-to-locate-petsc-dynamic-library-libpetsc">Unable to locate PETSc dynamic library <code class="docutils notranslate"><span class="pre">libpetsc</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-determine-what-update-to-petsc-broke-my-code">How do I determine what update to PETSc broke my code?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-to-fix-the-error-pmix-error-error-in-file-gds-ds12-lock-pthread-c">How to fix the error “PMIX Error: error in file gds_ds12_lock_pthread.c”?</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#shared-libraries">Shared Libraries</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#can-i-install-petsc-libraries-as-shared-libraries">Can I install PETSc libraries as shared libraries?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#why-should-i-use-shared-libraries">Why should I use shared libraries?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-i-link-to-the-petsc-shared-libraries">How do I link to the PETSc shared libraries?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-if-i-want-to-link-to-the-regular-a-library-files">What if I want to link to the regular <code class="docutils notranslate"><span class="pre">.a</span></code> library files?</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#what-do-i-do-if-i-want-to-move-my-executable-to-a-different-machine">What do I do if I want to move my executable to a different machine?</a></li>
</ul>
</li>
</ul>
  </nav></div>

  <div class="sidebar-secondary-item">

  
  <div class="tocsection editthispage">
    <a href="https://gitlab.com/petsc/petsc/-/edit/release/doc/faq/index.md">
      <i class="fa-solid fa-pencil"></i>
      
      
        
          Edit on GitLab
        
      
    </a>
  </div>
</div>

  <div class="sidebar-secondary-item">

  <div class="tocsection sourcelink">
    <a href="../_sources/faq/index.md.txt">
      <i class="fa-solid fa-file-lines"></i> Show Source
    </a>
  </div>
</div>

</div></div>
              
            
          </div>
          <footer class="bd-footer-content">
            
          </footer>
        
      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script src="../_static/scripts/bootstrap.js?digest=bd9e20870c6007c4c509"></script>
<script src="../_static/scripts/pydata-sphinx-theme.js?digest=bd9e20870c6007c4c509"></script>

  <footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
  
    <div class="footer-items__start">
      
        <div class="footer-item">

  <p class="copyright">
    
      © Copyright 1991-2025, UChicago Argonne, LLC and the PETSc Development Team.
      <br/>
    
  </p>
</div>
      
        <div class="footer-item">

  <p class="sphinx-version">
    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
    <br/>
  </p>
</div>
      
    </div>
  
  
  
    <div class="footer-items__end">
      
        <div class="footer-item">
<p class="theme-version">
  Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.1.
</p></div>
      
        <div class="footer-item"><p class="last-updated">
  Last updated on 2025-04-30T13:10:40-0500 (v3.23.1).
  <br/>
</p></div>
      
    </div>
  
</div>

  </footer>
  </body>
</html>