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
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/sphinx_docs/html/manual/ksp.html" />
<meta charset="utf-8" />
<title>KSP: Linear System Solvers — PETSc 3.14.5 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" />
<link rel="stylesheet" type="text/css" href="../_static/katex-math.css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js"></script>
<script src="../_static/katex_autorenderer.js"></script>
<link rel="shortcut icon" href="../_static/PETSc_RGB-logo.png"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="SNES: Nonlinear Solvers" href="snes.html" />
<link rel="prev" title="Matrices" href="mat.html" />
</head><body>
<div id="version" align=right><b>petsc-3.14.5 2021-03-03</b></div>
<div id="bugreport" align=right><a href="mailto:petsc-maint@mcs.anl.gov?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: petsc-3.14.5 v3.14.5 docs/sphinx_docs/html/manual/ksp.html "><small>Report Typos and Errors</small></a></div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="snes.html" title="SNES: Nonlinear Solvers"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="mat.html" title="Matrices"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">PETSc 3.14.5 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >PETSc Users Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="programming.html" accesskey="U">Programming with PETSc</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/PETSc-TAO_RGB.svg" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">KSP: Linear System Solvers</a><ul>
<li><a class="reference internal" href="#using-ksp">Using KSP</a></li>
<li><a class="reference internal" href="#solving-successive-linear-systems">Solving Successive Linear Systems</a></li>
<li><a class="reference internal" href="#krylov-methods">Krylov Methods</a><ul>
<li><a class="reference internal" href="#preconditioning-within-ksp">Preconditioning within KSP</a></li>
<li><a class="reference internal" href="#convergence-tests">Convergence Tests</a></li>
<li><a class="reference internal" href="#convergence-monitoring">Convergence Monitoring</a></li>
<li><a class="reference internal" href="#understanding-the-operators-spectrum">Understanding the Operator’s Spectrum</a></li>
<li><a class="reference internal" href="#other-ksp-options">Other KSP Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#preconditioners">Preconditioners</a><ul>
<li><a class="reference internal" href="#ilu-and-icc-preconditioners">ILU and ICC Preconditioners</a></li>
<li><a class="reference internal" href="#sor-and-ssor-preconditioners">SOR and SSOR Preconditioners</a></li>
<li><a class="reference internal" href="#lu-factorization">LU Factorization</a></li>
<li><a class="reference internal" href="#block-jacobi-and-overlapping-additive-schwarz-preconditioners">Block Jacobi and Overlapping Additive Schwarz Preconditioners</a></li>
<li><a class="reference internal" href="#algebraic-multigrid-amg-preconditioners">Algebraic Multigrid (AMG) Preconditioners</a></li>
<li><a class="reference internal" href="#balancing-domain-decomposition-by-constraints">Balancing Domain Decomposition by Constraints</a></li>
<li><a class="reference internal" href="#shell-preconditioners">Shell Preconditioners</a></li>
<li><a class="reference internal" href="#combining-preconditioners">Combining Preconditioners</a></li>
<li><a class="reference internal" href="#multigrid-preconditioners">Multigrid Preconditioners</a></li>
</ul>
</li>
<li><a class="reference internal" href="#solving-block-matrices">Solving Block Matrices</a></li>
<li><a class="reference internal" href="#solving-singular-systems">Solving Singular Systems</a></li>
<li><a class="reference internal" href="#using-external-linear-solvers">Using External Linear Solvers</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="mat.html"
title="previous chapter">Matrices</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="snes.html"
title="next chapter">SNES: Nonlinear Solvers</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/manual/ksp.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="ksp-linear-system-solvers">
<span id="chapter-ksp"></span><h1>KSP: Linear System Solvers<a class="headerlink" href="#ksp-linear-system-solvers" title="Permalink to this headline">¶</a></h1>
<p>The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> object is the heart of PETSc, because it provides uniform
and efficient access to all of the package’s linear system solvers,
including parallel and sequential, direct and iterative. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> is
intended for solving systems of the form</p>
<div class="math" id="equation-eq-axeqb">
<span class="eqno">(1)<a class="headerlink" href="#equation-eq-axeqb" title="Permalink to this equation">¶</a></span>\[ A x = b,\]</div>
<p>where <span class="math">\(A\)</span> denotes the matrix representation of a linear operator,
<span class="math">\(b\)</span> is the right-hand-side vector, and <span class="math">\(x\)</span> is the solution
vector. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> uses the same calling sequence for both direct and
iterative solution of a linear system. In addition, particular solution
techniques and their associated options can be selected at runtime.</p>
<p>The combination of a Krylov subspace method and a preconditioner is at
the center of most modern numerical codes for the iterative solution of
linear systems. Many textbooks (e.g. <span id="id1">[<a class="reference internal" href="#id273"><span>FGN92</span></a>]</span> <span id="id2">[<a class="reference internal" href="#id1274"><span>vdV03</span></a>]</span>, or <span id="id3">[<a class="reference internal" href="#id389"><span>Saa03</span></a>]</span>) provide an
overview of the theory of such methods.
The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> package, discussed in
<a class="reference internal" href="#sec-ksp"><span class="std std-ref">Krylov Methods</span></a>, provides many popular Krylov subspace
iterative methods; the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> module, described in
<a class="reference internal" href="#sec-pc"><span class="std std-ref">Preconditioners</span></a>, includes a variety of preconditioners.</p>
<div class="section" id="using-ksp">
<span id="sec-usingksp"></span><h2>Using KSP<a class="headerlink" href="#using-ksp" title="Permalink to this headline">¶</a></h2>
<p>To solve a linear system with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code>, one must first create a solver
context with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCreate.html#KSPCreate">KSPCreate</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span> <span class="n">comm</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>Here <code class="docutils literal notranslate"><span class="pre">comm</span></code> is the MPI communicator and <code class="docutils literal notranslate"><span class="pre">ksp</span></code> is the newly formed
solver context. Before actually solving a linear system with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code>,
the user must call the following routine to set the matrices associated
with the linear system:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">Amat</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">Pmat</span><span class="p">);</span>
</pre></div>
</div>
<p>The argument <code class="docutils literal notranslate"><span class="pre">Amat</span></code>, representing the matrix that defines the linear
system, is a symbolic placeholder for any kind of matrix or operator. In
particular, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> <em>does</em> support matrix-free methods. The routine
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateShell.html#MatCreateShell">MatCreateShell</a>()</span></code> in <a class="reference internal" href="mat.html#sec-matrixfree"><span class="std std-ref">Matrix-Free Matrices</span></a>
provides further information regarding matrix-free methods. Typically,
the matrix from which the preconditioner is to be constructed, <code class="docutils literal notranslate"><span class="pre">Pmat</span></code>,
is the same as the matrix that defines the linear system, <code class="docutils literal notranslate"><span class="pre">Amat</span></code>;
however, occasionally these matrices differ (for instance, when a
preconditioning matrix is obtained from a lower order method than that
employed to form the linear system matrix).</p>
<p>Much of the power of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> can be accessed through the single routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetFromOptions.html#KSPSetFromOptions">KSPSetFromOptions</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>This routine accepts the option <code class="docutils literal notranslate"><span class="pre">-help</span></code> as well as any of
the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> options discussed below. To solve a linear
system, one sets the rhs and solution vectors using and executes the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">b</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">b</span></code> and <code class="docutils literal notranslate"><span class="pre">x</span></code> respectively denote the right-hand-side and
solution vectors. On return, the iteration number at which the iterative
process stopped can be obtained using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetIterationNumber.html#KSPGetIterationNumber">KSPGetIterationNumber</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">its</span><span class="p">);</span>
</pre></div>
</div>
<p>Note that this does not state that the method converged at this
iteration: it can also have reached the maximum number of iterations, or
have diverged.</p>
<p><a class="reference internal" href="#sec-convergencetests"><span class="std std-ref">Convergence Tests</span></a> gives more details
regarding convergence testing. Note that multiple linear solves can be
performed by the same <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> context. Once the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> context is no
longer needed, it should be destroyed with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPDestroy.html#KSPDestroy">KSPDestroy</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>The above procedure is sufficient for general use of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code>
package. One additional step is required for users who wish to customize
certain preconditioners (e.g., see <a class="reference internal" href="#sec-bjacobi"><span class="std std-ref">Block Jacobi and Overlapping Additive Schwarz Preconditioners</span></a>) or
to log certain performance data using the PETSc profiling facilities (as
discussed in <a class="reference internal" href="profiling.html#ch-profiling"><span class="std std-ref">Profiling</span></a>). In this case, the user can
optionally explicitly call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetUp.html#KSPSetUp">KSPSetUp</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>before calling <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a>()</span></code> to perform any setup required for the
linear solvers. The explicit call of this routine enables the separate
monitoring of any computations performed during the set up phase, such
as incomplete factorization for the ILU preconditioner.</p>
<p>The default solver within <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> is restarted GMRES, preconditioned for
the uniprocess case with ILU(0), and for the multiprocess case with the
block Jacobi method (with one block per process, each of which is solved
with ILU(0)). A variety of other solvers and options are also available.
To allow application programmers to set any of the preconditioner or
Krylov subspace options directly within the code, we provide routines
that extract the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> contexts,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetPC.html#KSPGetPC">KSPGetPC</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="o">*</span><span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The application programmer can then directly call any of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> routines to modify the corresponding default options.</p>
<p>To solve a linear system with a direct solver (currently supported by
PETSc for sequential matrices, and by several external solvers through
PETSc interfaces (see <a class="reference internal" href="#sec-externalsol"><span class="std std-ref">Using External Linear Solvers</span></a>)) one may use
the options <code class="docutils literal notranslate"><span class="pre">-ksp_type</span></code> <code class="docutils literal notranslate"><span class="pre">preonly</span></code> <code class="docutils literal notranslate"><span class="pre">-pc_type</span></code> <code class="docutils literal notranslate"><span class="pre">lu</span></code> (see below).</p>
<p>By default, if a direct solver is used, the factorization is <em>not</em> done
in-place. This approach prevents the user from the unexpected surprise
of having a corrupted matrix after a linear solve. The routine
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetUseInPlace.html#PCFactorSetUseInPlace">PCFactorSetUseInPlace</a>()</span></code>, discussed below, causes factorization to be
done in-place.</p>
</div>
<div class="section" id="solving-successive-linear-systems">
<h2>Solving Successive Linear Systems<a class="headerlink" href="#solving-successive-linear-systems" title="Permalink to this headline">¶</a></h2>
<p>When solving multiple linear systems of the same size with the same
method, several options are available. To solve successive linear
systems having the <em>same</em> preconditioner matrix (i.e., the same data
structure with exactly the same matrix elements) but different
right-hand-side vectors, the user should simply call <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a>()</span></code>,
multiple times. The preconditioner setup operations (e.g., factorization
for ILU) will be done during the first call to <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a>()</span></code> only; such
operations will <em>not</em> be repeated for successive solves.</p>
<p>To solve successive linear systems that have <em>different</em> preconditioner
matrices (i.e., the matrix elements and/or the matrix data structure
change), the user <em>must</em> call <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</a>()</span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a>()</span></code>
for each solve. See <a class="reference internal" href="#sec-usingksp"><span class="std std-ref">Using KSP</span></a> for a description
of various flags for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</a>()</span></code> that can save work for such
cases.</p>
</div>
<div class="section" id="krylov-methods">
<span id="sec-ksp"></span><h2>Krylov Methods<a class="headerlink" href="#krylov-methods" title="Permalink to this headline">¶</a></h2>
<p>The Krylov subspace methods accept a number of options, many of which
are discussed below. First, to set the Krylov subspace method that is to
be used, one calls the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetType.html#KSPSetType">KSPSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPType.html#KSPType">KSPType</a></span> <span class="n">method</span><span class="p">);</span>
</pre></div>
</div>
<p>The type can be one of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPRICHARDSON.html#KSPRICHARDSON">KSPRICHARDSON</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCHEBYSHEV.html#KSPCHEBYSHEV">KSPCHEBYSHEV</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCG.html#KSPCG">KSPCG</a></span></code>,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRES.html#KSPGMRES">KSPGMRES</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPTCQMR.html#KSPTCQMR">KSPTCQMR</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBCGS.html#KSPBCGS">KSPBCGS</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGS.html#KSPCGS">KSPCGS</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPTFQMR.html#KSPTFQMR">KSPTFQMR</a></span></code>,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCR.html#KSPCR">KSPCR</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPLSQR.html#KSPLSQR">KSPLSQR</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBICG.html#KSPBICG">KSPBICG</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPREONLY.html#KSPPREONLY">KSPPREONLY</a></span></code>. or others; see
<a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a> or the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPType.html#KSPType">KSPType</a></span></code> man page for more.
The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> method can also be set with the options database command
<code class="docutils literal notranslate"><span class="pre">-ksp_type</span></code>, followed by one of the options <code class="docutils literal notranslate"><span class="pre">richardson</span></code>,
<code class="docutils literal notranslate"><span class="pre">chebyshev</span></code>, <code class="docutils literal notranslate"><span class="pre">cg</span></code>, <code class="docutils literal notranslate"><span class="pre">gmres</span></code>, <code class="docutils literal notranslate"><span class="pre">tcqmr</span></code>, <code class="docutils literal notranslate"><span class="pre">bcgs</span></code>, <code class="docutils literal notranslate"><span class="pre">cgs</span></code>,
<code class="docutils literal notranslate"><span class="pre">tfqmr</span></code>, <code class="docutils literal notranslate"><span class="pre">cr</span></code>, <code class="docutils literal notranslate"><span class="pre">lsqr</span></code>, <code class="docutils literal notranslate"><span class="pre">bicg</span></code>, <code class="docutils literal notranslate"><span class="pre">preonly.</span></code>, or others (see
<a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a> or the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPType.html#KSPType">KSPType</a></span></code> man page) There are
method-specific options. For instance, for the Richardson, Chebyshev, and
GMRES methods:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPRichardsonSetScale.html#KSPRichardsonSetScale">KSPRichardsonSetScale</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">scale</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPChebyshevSetEigenvalues.html#KSPChebyshevSetEigenvalues">KSPChebyshevSetEigenvalues</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">emax</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">emin</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESSetRestart.html#KSPGMRESSetRestart">KSPGMRESSetRestart</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">max_steps</span><span class="p">);</span>
</pre></div>
</div>
<p>The default parameter values are
<code class="docutils literal notranslate"><span class="pre">damping_factor=1.0,</span> <span class="pre">emax=0.01,</span> <span class="pre">emin=100.0</span></code>, and <code class="docutils literal notranslate"><span class="pre">max_steps=30</span></code>. The
GMRES restart and Richardson damping factor can also be set with the
options <code class="docutils literal notranslate"><span class="pre">-ksp_gmres_restart</span> <span class="pre"><n></span></code> and
<code class="docutils literal notranslate"><span class="pre">-ksp_richardson_scale</span> <span class="pre"><factor></span></code>.</p>
<p>The default technique for orthogonalization of the Hessenberg matrix in
GMRES is the unmodified (classical) Gram-Schmidt method, which can be
set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESSetOrthogonalization.html#KSPGMRESSetOrthogonalization">KSPGMRESSetOrthogonalization</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESClassicalGramSchmidtOrthogonalization.html#KSPGMRESClassicalGramSchmidtOrthogonalization">KSPGMRESClassicalGramSchmidtOrthogonalization</a></span><span class="p">);</span>
</pre></div>
</div>
<p>or the options database command <code class="docutils literal notranslate"><span class="pre">-ksp_gmres_classicalgramschmidt</span></code>. By
default this will <em>not</em> use iterative refinement to improve the
stability of the orthogonalization. This can be changed with the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESSetCGSRefinementType.html#KSPGMRESSetCGSRefinementType">KSPGMRESSetCGSRefinementType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESCGSRefinementType.html#KSPGMRESCGSRefinementType">KSPGMRESCGSRefinementType</a></span> <span class="n">type</span><span class="p">)</span>
</pre></div>
</div>
<p>or via the options database with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">ksp_gmres_cgs_refinement_type</span> <span class="n">none</span><span class="p">,</span><span class="n">ifneeded</span><span class="p">,</span><span class="n">always</span>
</pre></div>
</div>
<p>The values for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESCGSRefinementType.html#KSPGMRESCGSRefinementType">KSPGMRESCGSRefinementType</a>()</span></code> are
<code class="docutils literal notranslate"><span class="pre">KSP_GMRES_CGS_REFINEMENT_NONE</span></code>, <code class="docutils literal notranslate"><span class="pre">KSP_GMRES_CGS_REFINEMENT_IFNEEDED</span></code>
and <code class="docutils literal notranslate"><span class="pre">KSP_GMRES_CGS_REFINEMENT_ALWAYS</span></code>.</p>
<p>One can also use modified Gram-Schmidt, by using the orthogonalization
routine <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESModifiedGramSchmidtOrthogonalization.html#KSPGMRESModifiedGramSchmidtOrthogonalization">KSPGMRESModifiedGramSchmidtOrthogonalization</a>()</span></code> or by using
the command line option <code class="docutils literal notranslate"><span class="pre">-ksp_gmres_modifiedgramschmidt</span></code>.</p>
<p>For the conjugate gradient method with complex numbers, there are two
slightly different algorithms depending on whether the matrix is
Hermitian symmetric or truly symmetric (the default is to assume that it
is Hermitian symmetric). To indicate that it is symmetric, one uses the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGSetType.html#KSPCGSetType">KSPCGSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGType.html#KSPCGType">KSPCGType</a></span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGType.html#KSPCGType">KSP_CG_SYMMETRIC</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Note that this option is not valid for all matrices.</p>
<p>The LSQR algorithm does not involve a preconditioner; any preconditioner
set to work with the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> object is ignored if <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPLSQR.html#KSPLSQR">KSPLSQR</a></span></code> was
selected.</p>
<p>By default, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> assumes an initial guess of zero by zeroing the
initial value for the solution vector that is given; this zeroing is
done at the call to <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a>()</span></code>. To use a nonzero initial guess, the
user <em>must</em> call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetInitialGuessNonzero.html#KSPSetInitialGuessNonzero">KSPSetInitialGuessNonzero</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">flg</span><span class="p">);</span>
</pre></div>
</div>
<div class="section" id="preconditioning-within-ksp">
<span id="sec-ksppc"></span><h3>Preconditioning within KSP<a class="headerlink" href="#preconditioning-within-ksp" title="Permalink to this headline">¶</a></h3>
<p>Since the rate of convergence of Krylov projection methods for a
particular linear system is strongly dependent on its spectrum,
preconditioning is typically used to alter the spectrum and hence
accelerate the convergence rate of iterative techniques. Preconditioning
can be applied to the system <a class="reference internal" href="#equation-eq-axeqb">(1)</a> by</p>
<div class="math" id="equation-eq-prec">
<span class="eqno">(2)<a class="headerlink" href="#equation-eq-prec" title="Permalink to this equation">¶</a></span>\[ (M_L^{-1} A M_R^{-1}) \, (M_R x) = M_L^{-1} b,\]</div>
<p>where <span class="math">\(M_L\)</span> and <span class="math">\(M_R\)</span> indicate preconditioning matrices (or,
matrices from which the preconditioner is to be constructed). If
<span class="math">\(M_L = I\)</span> in <a class="reference internal" href="#equation-eq-prec">(2)</a>, right preconditioning
results, and the residual of <a class="reference internal" href="#equation-eq-axeqb">(1)</a>,</p>
<div class="math">
\[r \equiv b - Ax = b - A M_R^{-1} \, M_R x,
\]</div>
<p>is preserved. In contrast, the residual is altered for left
(<span class="math">\(M_R = I\)</span>) and symmetric preconditioning, as given by</p>
<div class="math">
\[r_L \equiv M_L^{-1} b - M_L^{-1} A x = M_L^{-1} r.
\]</div>
<p>By default, most KSP implementations use left preconditioning. Some more
naturally use other options, though. For instance, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPQCG.html#KSPQCG">KSPQCG</a></span></code> defaults
to use symmetric preconditioning and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFGMRES.html#KSPFGMRES">KSPFGMRES</a></span></code> uses right
preconditioning by default. Right preconditioning can be activated for
some methods by using the options database command
<code class="docutils literal notranslate"><span class="pre">-ksp_pc_side</span> <span class="pre">right</span></code> or calling the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetPCSide.html#KSPSetPCSide">KSPSetPCSide</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSide.html#PCSide">PCSide</a></span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSide.html#PCSide">PC_RIGHT</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Attempting to use right preconditioning for a method that does not
currently support it results in an error message of the form</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>KSPSetUp_Richardson:No right preconditioning for <a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPRICHARDSON.html#KSPRICHARDSON">KSPRICHARDSON</a>
</pre></div>
</div>
<p>We summarize the defaults for the residuals used in KSP convergence
monitoring within <a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a>. Details regarding
specific convergence tests and monitoring routines are presented in the
following sections. The preconditioned residual is used by default for
convergence testing of all left-preconditioned <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> methods. For the
conjugate gradient, Richardson, and Chebyshev methods the true residual
can be used by the options database command
<code class="docutils literal notranslate"><span class="pre">ksp_norm_type</span> <span class="pre">unpreconditioned</span></code> or by calling the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetNormType.html#KSPSetNormType">KSPSetNormType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP_NORM_UNPRECONDITIONED.html#KSP_NORM_UNPRECONDITIONED">KSP_NORM_UNPRECONDITIONED</a></span><span class="p">);</span>
</pre></div>
</div>
<table class="docutils align-default" id="tab-kspdefaults">
<caption><span class="caption-number">Table 4 </span><span class="caption-text">KSP Objects</span><a class="headerlink" href="#tab-kspdefaults" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Method</p></th>
<th class="head"><p>KSPType</p></th>
<th class="head"><p>Options Database Name</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Richardson</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPRICHARDSON.html#KSPRICHARDSON">KSPRICHARDSON</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">richardson</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Chebyshev</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCHEBYSHEV.html#KSPCHEBYSHEV">KSPCHEBYSHEV</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">chebyshev</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradient <span id="id4">[<a class="reference internal" href="#id318"><span>HS52</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCG.html#KSPCG">KSPCG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined Conjugate Gradients <span id="id5">[<a class="reference internal" href="#id839"><span>GV14</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPIPECG.html#KSPPIPECG">KSPPIPECG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pipecg</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Pipelined Conjugate Gradients (Gropp)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGROPPCG.html#KSPGROPPCG">KSPGROPPCG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">groppcg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined Conjugate Gradients with Residual Replacement</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPIPECGRR.html#KSPPIPECGRR">KSPPIPECGRR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pipecgrr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradients for the Normal Equations</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGNE.html#KSPCGNE">KSPCGNE</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cgne</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Flexible Conjugate Gradients <span id="id6">[<a class="reference internal" href="#id918"><span>Not00</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFCG.html#KSPFCG">KSPFCG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">fcg</span></code></p></td>
</tr>
<tr class="row-even"><td><p> Pipelined, Flexible Conjugate Gradients <span id="id7">[<a class="reference internal" href="#id2112"><span>SSM16</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPIPEFCG.html#KSPPIPEFCG">KSPPIPEFCG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pipefcg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradients for Least Squares</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGLS.html#KSPCGLS">KSPCGLS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cgls</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradients with Constraint (1)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPNASH.html#KSPNASH">KSPNASH</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">nash</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradients with Constraint (2)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSTCG.html#KSPSTCG">KSPSTCG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">stcg</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradients with Constraint (3)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGLTR.html#KSPGLTR">KSPGLTR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">gltr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradients with Constraint (4)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPQCG.html#KSPQCG">KSPQCG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">qcg</span></code></p></td>
</tr>
<tr class="row-even"><td><p>BiConjugate Gradient</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBICG.html#KSPBICG">KSPBICG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bicg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>BiCGSTAB <span id="id8">[<a class="reference internal" href="#id321"><span>vandVorst92</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBCGS.html#KSPBCGS">KSPBCGS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bcgs</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Improved BiCGSTAB</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPIBCGS.html#KSPIBCGS">KSPIBCGS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ibcgs</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Flexible BiCGSTAB</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFBCGS.html#KSPFBCGS">KSPFBCGS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">fbcgs</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Flexible BiCGSTAB (variant)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFBCGSR.html#KSPFBCGSR">KSPFBCGSR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">fbcgsr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Enhanced BiCGSTAB(L)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBCGSL.html#KSPBCGSL">KSPBCGSL</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bcgsl</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Minimal Residual Method <span id="id9">[<a class="reference internal" href="#id1126"><span>PS75</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMINRES.html#KSPMINRES">KSPMINRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">minres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Generalized Minimal Residual <span id="id10">[<a class="reference internal" href="#id319"><span>SS86</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRES.html#KSPGMRES">KSPGMRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">gmres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Flexible Generalized Minimal Residual <span id="id11">[<a class="reference internal" href="#id713"><span>Saa93</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFGMRES.html#KSPFGMRES">KSPFGMRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">fgmres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Deflated Generalized Minimal Residual</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPDGMRES.html#KSPDGMRES">KSPDGMRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">dgmres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Pipelined Generalized Minimal Residual <span id="id12">[<a class="reference internal" href="#id838"><span>GAMV13</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPGMRES.html#KSPPGMRES">KSPPGMRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pgmres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined, Flexible Generalized Minimal Residual <span id="id13">[<a class="reference internal" href="#id2112"><span>SSM16</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPIPEFGMRES.html#KSPPIPEFGMRES">KSPPIPEFGMRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pipefgmres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Generalized Minimal Residual with Accelerated Restart</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPLGMRES.html#KSPLGMRES">KSPLGMRES</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lgmres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Residual <span id="id14">[<a class="reference internal" href="#id726"><span>EES83</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCR.html#KSPCR">KSPCR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Generalized Conjugate Residual</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGCR.html#KSPGCR">KSPGCR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">gcr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined Conjugate Residual</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPIPECR.html#KSPPIPECR">KSPPIPECR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pipecr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Pipelined, Flexible Conjugate Residual <span id="id15">[<a class="reference internal" href="#id2112"><span>SSM16</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPIPEGCR.html#KSPPIPEGCR">KSPPIPEGCR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pipegcr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>FETI-DP</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFETIDP.html#KSPFETIDP">KSPFETIDP</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">fetidp</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradient Squared <span id="id16">[<a class="reference internal" href="#id320"><span>Son89</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCGS.html#KSPCGS">KSPCGS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cgs</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Transpose-Free Quasi-Minimal Residual (1) <span id="id17">[<a class="reference internal" href="#id322"><span>Fre93</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPTFQMR.html#KSPTFQMR">KSPTFQMR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tfqmr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Transpose-Free Quasi-Minimal Residual (2)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPTCQMR.html#KSPTCQMR">KSPTCQMR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tcqmr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Least Squares Method</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPLSQR.html#KSPLSQR">KSPLSQR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lsqr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Symmetric LQ Method <span id="id18">[<a class="reference internal" href="#id1126"><span>PS75</span></a>]</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSYMMLQ.html#KSPSYMMLQ">KSPSYMMLQ</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">symmlq</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>TSIRM</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPTSIRM.html#KSPTSIRM">KSPTSIRM</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tsirm</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Python Shell</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">KSPPYTHON</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">python</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Shell for no <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> method</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPREONLY.html#KSPPREONLY">KSPPREONLY</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">preonly</span></code></p></td>
</tr>
</tbody>
</table>
<p>Note: the bi-conjugate gradient method requires application of both the
matrix and its transpose plus the preconditioner and its transpose.
Currently not all matrices and preconditioners provide this support and
thus the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBICG.html#KSPBICG">KSPBICG</a></span></code> cannot always be used.</p>
<p>Note: PETSc implements the FETI-DP (Finite Element Tearing and
Interconnecting Dual-Primal) method as an implementation of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> since it recasts the
original problem into a contstrained minimization one with Lagrange
multipliers. The only matrix type supported is <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATIS.html#MATIS">MATIS</a></span></code>. Support for
saddle point problems is provided. See the man page for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPFETIDP.html#KSPFETIDP">KSPFETIDP</a></span></code> for
further details.</p>
</div>
<div class="section" id="convergence-tests">
<span id="sec-convergencetests"></span><h3>Convergence Tests<a class="headerlink" href="#convergence-tests" title="Permalink to this headline">¶</a></h3>
<p>The default convergence test, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPConvergedDefault.html#KSPConvergedDefault">KSPConvergedDefault</a>()</span></code>, is based on the
<span class="math">\(l_2\)</span>-norm of the residual. Convergence (or divergence) is decided
by three quantities: the decrease of the residual norm relative to the
norm of the right hand side, <code class="docutils literal notranslate"><span class="pre">rtol</span></code>, the absolute size of the residual
norm, <code class="docutils literal notranslate"><span class="pre">atol</span></code>, and the relative increase in the residual, <code class="docutils literal notranslate"><span class="pre">dtol</span></code>.
Convergence is detected at iteration <span class="math">\(k\)</span> if</p>
<div class="math">
\[\| r_k \|_2 < {\rm max} ( \text{rtol} * \| b \|_2, \text{atol}),
\]</div>
<p>where <span class="math">\(r_k = b - A x_k\)</span>. Divergence is detected if</p>
<div class="math">
\[\| r_k \|_2 > \text{dtol} * \| b \|_2.
\]</div>
<p>These parameters, as well as the maximum number of allowable iterations,
can be set with the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetTolerances.html#KSPSetTolerances">KSPSetTolerances</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">rtol</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">atol</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">dtol</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">maxits</span><span class="p">);</span>
</pre></div>
</div>
<p>The user can retain the default value of any of these parameters by
specifying <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_DEFAULT.html#PETSC_DEFAULT">PETSC_DEFAULT</a></span></code> as the corresponding tolerance; the
defaults are <code class="docutils literal notranslate"><span class="pre">rtol=1e-5</span></code>, <code class="docutils literal notranslate"><span class="pre">atol=1e-50</span></code>, <code class="docutils literal notranslate"><span class="pre">dtol=1e5</span></code>, and
<code class="docutils literal notranslate"><span class="pre">maxits=1e4</span></code>. These parameters can also be set from the options
database with the commands <code class="docutils literal notranslate"><span class="pre">-ksp_rtol</span></code> <code class="docutils literal notranslate"><span class="pre"><rtol></span></code>, <code class="docutils literal notranslate"><span class="pre">-ksp_atol</span></code>
<code class="docutils literal notranslate"><span class="pre"><atol></span></code>, <code class="docutils literal notranslate"><span class="pre">-ksp_divtol</span></code> <code class="docutils literal notranslate"><span class="pre"><dtol></span></code>, and <code class="docutils literal notranslate"><span class="pre">-ksp_max_it</span></code> <code class="docutils literal notranslate"><span class="pre"><its></span></code>.</p>
<p>In addition to providing an interface to a simple convergence test,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> allows the application programmer the flexibility to provide
customized convergence-testing routines. The user can specify a
customized routine with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetConvergenceTest.html#KSPSetConvergenceTest">KSPSetConvergenceTest</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">test</span><span class="p">)(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">it</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">rnorm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPConvergedReason.html#KSPConvergedReason">KSPConvergedReason</a></span> <span class="o">*</span><span class="n">reason</span><span class="p">,</span><span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">),</span><span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">destroy</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">));</span>
</pre></div>
</div>
<p>The final routine argument, <code class="docutils literal notranslate"><span class="pre">ctx</span></code>, is an optional context for private
data for the user-defined convergence routine, <code class="docutils literal notranslate"><span class="pre">test</span></code>. Other <code class="docutils literal notranslate"><span class="pre">test</span></code>
routine arguments are the iteration number, <code class="docutils literal notranslate"><span class="pre">it</span></code>, and the residual’s
<span class="math">\(l_2\)</span> norm, <code class="docutils literal notranslate"><span class="pre">rnorm</span></code>. The routine for detecting convergence,
<code class="docutils literal notranslate"><span class="pre">test</span></code>, should set <code class="docutils literal notranslate"><span class="pre">reason</span></code> to positive for convergence, 0 for no
convergence, and negative for failure to converge. A full list of
possible values for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPConvergedReason.html#KSPConvergedReason">KSPConvergedReason</a></span></code> is given in
<code class="docutils literal notranslate"><span class="pre">include/petscksp.h</span></code>. You can use <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetConvergedReason.html#KSPGetConvergedReason">KSPGetConvergedReason</a>()</span></code> after
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a>()</span></code> to see why convergence/divergence was detected.</p>
</div>
<div class="section" id="convergence-monitoring">
<span id="sec-kspmonitor"></span><h3>Convergence Monitoring<a class="headerlink" href="#convergence-monitoring" title="Permalink to this headline">¶</a></h3>
<p>By default, the Krylov solvers run silently without displaying
information about the iterations. The user can indicate that the norms
of the residuals should be displayed by using <code class="docutils literal notranslate"><span class="pre">-ksp_monitor</span></code> within
the options database. To display the residual norms in a graphical
window (running under X Windows), one should use
<code class="docutils literal notranslate"><span class="pre">-ksp_monitor_lg_residualnorm</span></code> <code class="docutils literal notranslate"><span class="pre">[x,y,w,h]</span></code>, where either all or none
of the options must be specified. Application programmers can also
provide their own routines to perform the monitoring by using the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorSet.html#KSPMonitorSet">KSPMonitorSet</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">mon</span><span class="p">)(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">it</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">rnorm</span><span class="p">,</span><span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">),</span><span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">mondestroy</span><span class="p">)(</span><span class="kt">void</span><span class="o">**</span><span class="p">));</span>
</pre></div>
</div>
<p>The final routine argument, <code class="docutils literal notranslate"><span class="pre">ctx</span></code>, is an optional context for private
data for the user-defined monitoring routine, <code class="docutils literal notranslate"><span class="pre">mon</span></code>. Other <code class="docutils literal notranslate"><span class="pre">mon</span></code>
routine arguments are the iteration number (<code class="docutils literal notranslate"><span class="pre">it</span></code>) and the residual’s
<span class="math">\(l_2\)</span> norm (<code class="docutils literal notranslate"><span class="pre">rnorm</span></code>). A helpful routine within user-defined
monitors is <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObjectGetComm.html#PetscObjectGetComm">PetscObjectGetComm</a>((<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObject.html#PetscObject">PetscObject</a>)ksp,<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span> <span class="pre">*comm)</span></code>,
which returns in <code class="docutils literal notranslate"><span class="pre">comm</span></code> the MPI communicator for the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> context.
See <a class="reference internal" href="getting_started.html#sec-writing"><span class="std std-ref">Writing PETSc Programs</span></a> for more discussion of the use of
MPI communicators within PETSc.</p>
<p>Several monitoring routines are supplied with PETSc, including</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorDefault.html#KSPMonitorDefault">KSPMonitorDefault</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorSingularValue.html#KSPMonitorSingularValue">KSPMonitorSingularValue</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span><span class="p">,</span><span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorTrueResidualNorm.html#KSPMonitorTrueResidualNorm">KSPMonitorTrueResidualNorm</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<p>The default monitor simply prints an estimate of the <span class="math">\(l_2\)</span>-norm of
the residual at each iteration. The routine
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorSingularValue.html#KSPMonitorSingularValue">KSPMonitorSingularValue</a>()</span></code> is appropriate only for use with the
conjugate gradient method or GMRES, since it prints estimates of the
extreme singular values of the preconditioned operator at each
iteration. Since <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorTrueResidualNorm.html#KSPMonitorTrueResidualNorm">KSPMonitorTrueResidualNorm</a>()</span></code> prints the true
residual at each iteration by actually computing the residual using the
formula <span class="math">\(r = b - Ax\)</span>, the routine is slow and should be used only
for testing or convergence studies, not for timing. These monitors may
be accessed with the command line options <code class="docutils literal notranslate"><span class="pre">-ksp_monitor</span></code>,
<code class="docutils literal notranslate"><span class="pre">-ksp_monitor_singular_value</span></code>, and <code class="docutils literal notranslate"><span class="pre">-ksp_monitor_true_residual</span></code>.</p>
<p>To employ the default graphical monitor, one should use the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawLG.html#PetscDrawLG">PetscDrawLG</a></span> <span class="n">lg</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorLGResidualNormCreate.html#KSPMonitorLGResidualNormCreate">KSPMonitorLGResidualNormCreate</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span> <span class="n">comm</span><span class="p">,</span><span class="kt">char</span> <span class="o">*</span><span class="n">display</span><span class="p">,</span><span class="kt">char</span> <span class="o">*</span><span class="n">title</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">x</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">y</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">w</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">h</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawLG.html#PetscDrawLG">PetscDrawLG</a></span> <span class="o">*</span><span class="n">lg</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPMonitorSet.html#KSPMonitorSet">KSPMonitorSet</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n">KSPMonitorLGResidualNorm</span><span class="p">,</span><span class="n">lg</span><span class="p">,</span><span class="mi">0</span><span class="p">);</span>
</pre></div>
</div>
<p>When no longer needed, the line graph should be destroyed with the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawLGDestroy.html#PetscDrawLGDestroy">PetscDrawLGDestroy</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawLG.html#PetscDrawLG">PetscDrawLG</a></span> <span class="o">*</span><span class="n">lg</span><span class="p">);</span>
</pre></div>
</div>
<p>The user can change aspects of the graphs with the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawLG.html#PetscDrawLG">PetscDrawLG</a>*()</span></code>
and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawAxis.html#PetscDrawAxis">PetscDrawAxis</a>*()</span></code> routines. One can also access this
functionality from the options database with the command
<code class="docutils literal notranslate"><span class="pre">-ksp_monitor_lg_residualnorm</span></code> <code class="docutils literal notranslate"><span class="pre">[x,y,w,h]</span></code>. , where <code class="docutils literal notranslate"><span class="pre">x,</span> <span class="pre">y,</span> <span class="pre">w,</span> <span class="pre">h</span></code>
are the optional location and size of the window.</p>
<p>One can cancel hardwired monitoring routines for KSP at runtime with
<code class="docutils literal notranslate"><span class="pre">-ksp_monitor_cancel</span></code>.</p>
<p>Unless the Krylov method converges so that the residual norm is small,
say <span class="math">\(10^{-10}\)</span>, many of the final digits printed with the
<code class="docutils literal notranslate"><span class="pre">-ksp_monitor</span></code> option are meaningless. Worse, they are different on
different machines; due to different round-off rules used by, say, the
IBM RS6000 and the Sun SPARC. This makes testing between different
machines difficult. The option <code class="docutils literal notranslate"><span class="pre">-ksp_monitor_short</span></code> causes PETSc to
print fewer of the digits of the residual norm as it gets smaller; thus
on most of the machines it will always print the same numbers making
cross system testing easier.</p>
</div>
<div class="section" id="understanding-the-operators-spectrum">
<h3>Understanding the Operator’s Spectrum<a class="headerlink" href="#understanding-the-operators-spectrum" title="Permalink to this headline">¶</a></h3>
<p>Since the convergence of Krylov subspace methods depends strongly on the
spectrum (eigenvalues) of the preconditioned operator, PETSc has
specific routines for eigenvalue approximation via the Arnoldi or
Lanczos iteration. First, before the linear solve one must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetComputeEigenvalues.html#KSPSetComputeEigenvalues">KSPSetComputeEigenvalues</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Then after the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> solve one calls</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPComputeEigenvalues.html#KSPComputeEigenvalues">KSPComputeEigenvalues</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">n</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="o">*</span><span class="n">realpart</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="o">*</span><span class="n">complexpart</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">neig</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">n</span></code> is the size of the two arrays and the eigenvalues are
inserted into those two arrays. <code class="docutils literal notranslate"><span class="pre">neig</span></code> is the number of eigenvalues
computed; this number depends on the size of the Krylov space generated
during the linear system solution, for GMRES it is never larger than the
restart parameter. There is an additional routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPComputeEigenvaluesExplicitly.html#KSPComputeEigenvaluesExplicitly">KSPComputeEigenvaluesExplicitly</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">n</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="o">*</span><span class="n">realpart</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="o">*</span><span class="n">complexpart</span><span class="p">);</span>
</pre></div>
</div>
<p>that is useful only for very small problems. It explicitly computes the
full representation of the preconditioned operator and calls LAPACK to
compute its eigenvalues. It should be only used for matrices of size up
to a couple hundred. The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Draw/PetscDrawSP.html#PetscDrawSP">PetscDrawSP</a>*()</span></code> routines are very useful for
drawing scatter plots of the eigenvalues.</p>
<p>The eigenvalues may also be computed and displayed graphically with the
options data base commands <code class="docutils literal notranslate"><span class="pre">-ksp_view_eigenvalues</span> <span class="pre">draw</span></code> and
<code class="docutils literal notranslate"><span class="pre">-ksp_view_eigenvalues_explicitly</span> <span class="pre">draw</span></code>. Or they can be dumped to the
screen in ASCII text via <code class="docutils literal notranslate"><span class="pre">-ksp_view_eigenvalues</span></code> and
<code class="docutils literal notranslate"><span class="pre">-ksp_view_eigenvalues_explicitly</span></code>.</p>
</div>
<div class="section" id="other-ksp-options">
<h3>Other KSP Options<a class="headerlink" href="#other-ksp-options" title="Permalink to this headline">¶</a></h3>
<p>To obtain the solution vector and right hand side from a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code>
context, one uses</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetSolution.html#KSPGetSolution">KSPGetSolution</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="o">*</span><span class="n">x</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetRhs.html#KSPGetRhs">KSPGetRhs</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="o">*</span><span class="n">rhs</span><span class="p">);</span>
</pre></div>
</div>
<p>During the iterative process the solution may not yet have been
calculated or it may be stored in a different location. To access the
approximate solution during the iterative process, one uses the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBuildSolution.html#KSPBuildSolution">KSPBuildSolution</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">w</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="o">*</span><span class="n">v</span><span class="p">);</span>
</pre></div>
</div>
<p>where the solution is returned in <code class="docutils literal notranslate"><span class="pre">v</span></code>. The user can optionally provide
a vector in <code class="docutils literal notranslate"><span class="pre">w</span></code> as the location to store the vector; however, if <code class="docutils literal notranslate"><span class="pre">w</span></code>
is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, space allocated by PETSc in the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> context is used.
One should not destroy this vector. For certain <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> methods, (e.g.,
GMRES), the construction of the solution is expensive, while for many
others it doesn’t evenrequire a vector copy.</p>
<p>Access to the residual is done in a similar way with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPBuildResidual.html#KSPBuildResidual">KSPBuildResidual</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">t</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">w</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="o">*</span><span class="n">v</span><span class="p">);</span>
</pre></div>
</div>
<p>Again, for GMRES and certain other methods this is an expensive
operation.</p>
</div>
</div>
<div class="section" id="preconditioners">
<span id="sec-pc"></span><h2>Preconditioners<a class="headerlink" href="#preconditioners" title="Permalink to this headline">¶</a></h2>
<p>As discussed in <a class="reference internal" href="#sec-ksppc"><span class="std std-ref">Preconditioning within KSP</span></a>, Krylov subspace methods
are typically used in conjunction with a preconditioner. To employ a
particular preconditioning method, the user can either select it from
the options database using input of the form <code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre"><methodname></span></code>
or set the method with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCType.html#PCType">PCType</a></span> <span class="n">method</span><span class="p">);</span>
</pre></div>
</div>
<p>In <a class="reference internal" href="#tab-pcdefaults"><span class="std std-ref">PETSc Preconditioners (partial list)</span></a> we summarize the basic
preconditioning methods supported in PETSc. See the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCType.html#PCType">PCType</a></span></code> manual
page for a complete list. The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSHELL.html#PCSHELL">PCSHELL</a></span></code> preconditioner uses a
specific, application-provided preconditioner. The direct
preconditioner, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCLU.html#PCLU">PCLU</a></span></code> , is, in fact, a direct solver for the linear
system that uses LU factorization. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCLU.html#PCLU">PCLU</a></span></code> is included as a
preconditioner so that PETSc has a consistent interface among direct and
iterative linear solvers.</p>
<table class="docutils align-default" id="tab-pcdefaults">
<caption><span class="caption-number">Table 5 </span><span class="caption-text">PETSc Preconditioners (partial list)</span><a class="headerlink" href="#tab-pcdefaults" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Method</p></th>
<th class="head"><p>PCType</p></th>
<th class="head"><p>Options Database Name</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Jacobi</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCJACOBI.html#PCJACOBI">PCJACOBI</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">jacobi</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Block Jacobi</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBJACOBI.html#PCBJACOBI">PCBJACOBI</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bjacobi</span></code></p></td>
</tr>
<tr class="row-even"><td><p>SOR (and SSOR)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSOR.html#PCSOR">PCSOR</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">sor</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>SOR with Eisenstat trick</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCEISENSTAT.html#PCEISENSTAT">PCEISENSTAT</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">eisenstat</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Incomplete Cholesky</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCICC.html#PCICC">PCICC</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">icc</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Incomplete LU</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCILU.html#PCILU">PCILU</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ilu</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Additive Schwarz</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">asm</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Generalized Additive Schwarz</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">gasm</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Algebraic Multigrid</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGAMG.html#PCGAMG">PCGAMG</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">gamg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Balancing Domain Decomposition by Constraints</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bddc</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Linear solver</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCKSP.html#PCKSP">PCKSP</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ksp</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Combination of preconditioners</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCOMPOSITE.html#PCCOMPOSITE">PCCOMPOSITE</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">composite</span></code></p></td>
</tr>
<tr class="row-even"><td><p>LU</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCLU.html#PCLU">PCLU</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Cholesky</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCHOLESKY.html#PCCHOLESKY">PCCHOLESKY</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
</tr>
<tr class="row-even"><td><p>No preconditioning</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCNONE.html#PCNONE">PCNONE</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">none</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Shell for user-defined <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSHELL.html#PCSHELL">PCSHELL</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">shell</span></code></p></td>
</tr>
</tbody>
</table>
<p>Each preconditioner may have associated with it a set of options, which
can be set with routines and options database commands provided for this
purpose. Such routine names and commands are all of the form
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a><TYPE><Option></span></code> and <code class="docutils literal notranslate"><span class="pre">-pc_<type>_<option></span> <span class="pre">[value]</span></code>. A complete
list can be found by consulting the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCType.html#PCType">PCType</a></span></code> manual page; we discuss
just a few in the sections below.</p>
<div class="section" id="ilu-and-icc-preconditioners">
<span id="sec-ilu-icc"></span><h3>ILU and ICC Preconditioners<a class="headerlink" href="#ilu-and-icc-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>Some of the options for ILU preconditioner are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetLevels.html#PCFactorSetLevels">PCFactorSetLevels</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">levels</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetReuseOrdering.html#PCFactorSetReuseOrdering">PCFactorSetReuseOrdering</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">flag</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetDropTolerance.html#PCFactorSetDropTolerance">PCFactorSetDropTolerance</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">dt</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">dtcol</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">dtcount</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetReuseFill.html#PCFactorSetReuseFill">PCFactorSetReuseFill</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">flag</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetUseInPlace.html#PCFactorSetUseInPlace">PCFactorSetUseInPlace</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">flg</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetAllowDiagonalFill.html#PCFactorSetAllowDiagonalFill">PCFactorSetAllowDiagonalFill</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">flg</span><span class="p">);</span>
</pre></div>
</div>
<p>When repeatedly solving linear systems with the same <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> context,
one can reuse some information computed during the first linear solve.
In particular, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetReuseOrdering.html#PCFactorSetReuseOrdering">PCFactorSetReuseOrdering</a>()</span></code> causes the ordering (for
example, set with <code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_ordering_type</span></code> <code class="docutils literal notranslate"><span class="pre">order</span></code>) computed
in the first factorization to be reused for later factorizations.
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetUseInPlace.html#PCFactorSetUseInPlace">PCFactorSetUseInPlace</a>()</span></code> is often used with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code> or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBJACOBI.html#PCBJACOBI">PCBJACOBI</a></span></code> when zero fill is used, since it reuses the matrix space
to store the incomplete factorization it saves memory and copying time.
Note that in-place factorization is not appropriate with any ordering
besides natural and cannot be used with the drop tolerance
factorization. These options may be set in the database with</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">-pc_factor_levels</span> <span class="pre"><levels></span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-pc_factor_reuse_ordering</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-pc_factor_reuse_fill</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-pc_factor_in_place</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-pc_factor_nonzeros_along_diagonal</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-pc_factor_diagonal_fill</span></code></p></li>
</ul>
<p>See <a class="reference internal" href="performance.html#sec-symbolfactor"><span class="std std-ref">Memory Allocation for Sparse Matrix Factorization</span></a> for information on
preallocation of memory for anticipated fill during factorization. By
alleviating the considerable overhead for dynamic memory allocation,
such tuning can significantly enhance performance.</p>
<p>PETSc supports incomplete factorization preconditioners
for several matrix types for sequential matrices (for example
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSEQAIJ.html#MATSEQAIJ">MATSEQAIJ</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSEQBAIJ.html#MATSEQBAIJ">MATSEQBAIJ</a></span></code>, and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSEQSBAIJ.html#MATSEQSBAIJ">MATSEQSBAIJ</a></span></code>).</p>
</div>
<div class="section" id="sor-and-ssor-preconditioners">
<h3>SOR and SSOR Preconditioners<a class="headerlink" href="#sor-and-ssor-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>PETSc only provides only a sequential SOR preconditioner; it can only be
used with sequential matrices or as the subblock preconditioner when
using block Jacobi or ASM preconditioning (see below).</p>
<p>The options for SOR preconditioning with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSOR.html#PCSOR">PCSOR</a></span></code> are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSORSetOmega.html#PCSORSetOmega">PCSORSetOmega</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="n">omega</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSORSetIterations.html#PCSORSetIterations">PCSORSetIterations</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">its</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">lits</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSORSetSymmetric.html#PCSORSetSymmetric">PCSORSetSymmetric</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">MatSORType</a></span> <span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>The first of these commands sets the relaxation factor for successive
over (under) relaxation. The second command sets the number of inner
iterations <code class="docutils literal notranslate"><span class="pre">its</span></code> and local iterations <code class="docutils literal notranslate"><span class="pre">lits</span></code> (the number of
smoothing sweeps on a process before doing a ghost point update from the
other processes) to use between steps of the Krylov space method. The
total number of SOR sweeps is given by <code class="docutils literal notranslate"><span class="pre">its*lits</span></code>. The third command
sets the kind of SOR sweep, where the argument <code class="docutils literal notranslate"><span class="pre">type</span></code> can be one of
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_FORWARD_SWEEP</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_BACKWARD_SWEEP</a></span></code> or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_SYMMETRIC_SWEEP</a></span></code>, the default being <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_FORWARD_SWEEP</a></span></code>.
Setting the type to be <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_SYMMETRIC_SWEEP</a></span></code> produces the SSOR method.
In addition, each process can locally and independently perform the
specified variant of SOR with the types <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_LOCAL_FORWARD_SWEEP</a></span></code>,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_LOCAL_BACKWARD_SWEEP</a></span></code>, and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSORType.html#MatSORType">SOR_LOCAL_SYMMETRIC_SWEEP</a></span></code>. These
variants can also be set with the options <code class="docutils literal notranslate"><span class="pre">-pc_sor_omega</span> <span class="pre"><omega></span></code>,
<code class="docutils literal notranslate"><span class="pre">-pc_sor_its</span> <span class="pre"><its></span></code>, <code class="docutils literal notranslate"><span class="pre">-pc_sor_lits</span> <span class="pre"><lits></span></code>, <code class="docutils literal notranslate"><span class="pre">-pc_sor_backward</span></code>,
<code class="docutils literal notranslate"><span class="pre">-pc_sor_symmetric</span></code>, <code class="docutils literal notranslate"><span class="pre">-pc_sor_local_forward</span></code>,
<code class="docutils literal notranslate"><span class="pre">-pc_sor_local_backward</span></code>, and <code class="docutils literal notranslate"><span class="pre">-pc_sor_local_symmetric</span></code>.</p>
<p>The Eisenstat trick <span id="id19">[<a class="reference internal" href="#id278"><span>Eis81</span></a>]</span> for SSOR
preconditioning can be employed with the method <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCEISENSTAT.html#PCEISENSTAT">PCEISENSTAT</a></span></code>
(<code class="docutils literal notranslate"><span class="pre">-pc_type</span></code> <code class="docutils literal notranslate"><span class="pre">eisenstat</span></code>). By using both left and right
preconditioning of the linear system, this variant of SSOR requires
about half of the floating-point operations for conventional SSOR. The
option <code class="docutils literal notranslate"><span class="pre">-pc_eisenstat_no_diagonal_scaling</span></code>) (or the routine
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCEisenstatSetNoDiagonalScaling.html#PCEisenstatSetNoDiagonalScaling">PCEisenstatSetNoDiagonalScaling</a>()</span></code>) turns off diagonal scaling in
conjunction with Eisenstat SSOR method, while the option
<code class="docutils literal notranslate"><span class="pre">-pc_eisenstat_omega</span> <span class="pre"><omega></span></code> (or the routine
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCEisenstatSetOmega.html#PCEisenstatSetOmega">PCEisenstatSetOmega</a>(<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="pre">pc,<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</a></span> <span class="pre">omega)</span></code>) sets the SSOR relaxation
coefficient, <code class="docutils literal notranslate"><span class="pre">omega</span></code>, as discussed above.</p>
</div>
<div class="section" id="lu-factorization">
<span id="sec-factorization"></span><h3>LU Factorization<a class="headerlink" href="#lu-factorization" title="Permalink to this headline">¶</a></h3>
<p>The LU preconditioner provides several options. The first, given by the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetUseInPlace.html#PCFactorSetUseInPlace">PCFactorSetUseInPlace</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">flg</span><span class="p">);</span>
</pre></div>
</div>
<p>causes the factorization to be performed in-place and hence destroys the
original matrix. The options database variant of this command is
<code class="docutils literal notranslate"><span class="pre">-pc_factor_in_place</span></code>. Another direct preconditioner option is
selecting the ordering of equations with the command
<code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_ordering_type</span> <span class="pre"><ordering></span></code>. The possible orderings are</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">MATORDERINGNATURAL</span></code> - Natural</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATORDERINGND</span></code> - Nested Dissection</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATORDERING1WD</span></code> - One-way Dissection</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATORDERINGRCM</span></code> - Reverse Cuthill-McKee</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATORDERINGQMD</span></code> - Quotient Minimum Degree</p></li>
</ul>
<p>These orderings can also be set through the options database by
specifying one of the following: <code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_ordering_type</span></code>
<code class="docutils literal notranslate"><span class="pre">natural</span></code>, or <code class="docutils literal notranslate"><span class="pre">nd</span></code>, or <code class="docutils literal notranslate"><span class="pre">1wd</span></code>, or <code class="docutils literal notranslate"><span class="pre">rcm</span></code>, or <code class="docutils literal notranslate"><span class="pre">qmd</span></code>. In addition,
see <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/MatOrderings/MatGetOrdering.html#MatGetOrdering">MatGetOrdering</a>()</span></code>, discussed in <a class="reference internal" href="advanced.html#sec-matfactor"><span class="std std-ref">Matrix Factorization</span></a>.</p>
<p>The sparse LU factorization provided in PETSc does not perform pivoting
for numerical stability (since they are designed to preserve nonzero
structure), and thus occasionally a LU factorization will fail with a
zero pivot when, in fact, the matrix is non-singular. The option
<code class="docutils literal notranslate"><span class="pre">-pc_factor_nonzeros_along_diagonal</span> <span class="pre"><tol></span></code> will often help eliminate
the zero pivot, by preprocessing the column ordering to remove small
values from the diagonal. Here, <code class="docutils literal notranslate"><span class="pre">tol</span></code> is an optional tolerance to
decide if a value is nonzero; by default it is <code class="docutils literal notranslate"><span class="pre">1.e-10</span></code>.</p>
<p>In addition, <a class="reference internal" href="performance.html#sec-symbolfactor"><span class="std std-ref">Memory Allocation for Sparse Matrix Factorization</span></a> provides information
on preallocation of memory for anticipated fill during factorization.
Such tuning can significantly enhance performance, since it eliminates
the considerable overhead for dynamic memory allocation.</p>
</div>
<div class="section" id="block-jacobi-and-overlapping-additive-schwarz-preconditioners">
<span id="sec-bjacobi"></span><h3>Block Jacobi and Overlapping Additive Schwarz Preconditioners<a class="headerlink" href="#block-jacobi-and-overlapping-additive-schwarz-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>The block Jacobi and overlapping additive Schwarz methods in PETSc are
supported in parallel; however, only the uniprocess version of the block
Gauss-Seidel method is currently in place. By default, the PETSc
implementations of these methods employ ILU(0) factorization on each
individual block (that is, the default solver on each subblock is
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCType.html#PCType">PCType</a>=<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCILU.html#PCILU">PCILU</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPType.html#KSPType">KSPType</a>=<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPREONLY.html#KSPPREONLY">KSPPREONLY</a></span></code>); the user can set alternative
linear solvers via the options <code class="docutils literal notranslate"><span class="pre">-sub_ksp_type</span></code> and <code class="docutils literal notranslate"><span class="pre">-sub_pc_type</span></code>.
In fact, all of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> options can be applied to the
subproblems by inserting the prefix <code class="docutils literal notranslate"><span class="pre">-sub_</span></code> at the beginning of the
option name. These options database commands set the particular options
for <em>all</em> of the blocks within the global problem. In addition, the
routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBJacobiGetSubKSP.html#PCBJacobiGetSubKSP">PCBJacobiGetSubKSP</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">n_local</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">first_local</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">**</span><span class="n">subksp</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMGetSubKSP.html#PCASMGetSubKSP">PCASMGetSubKSP</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">n_local</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">first_local</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">**</span><span class="n">subksp</span><span class="p">);</span>
</pre></div>
</div>
<p>extract the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> context for each local block. The argument
<code class="docutils literal notranslate"><span class="pre">n_local</span></code> is the number of blocks on the calling process, and
<code class="docutils literal notranslate"><span class="pre">first_local</span></code> indicates the global number of the first block on the
process. The blocks are numbered successively by processes from zero
through <span class="math">\(b_g-1\)</span>, where <span class="math">\(b_g\)</span> is the number of global blocks.
The array of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> contexts for the local blocks is given by
<code class="docutils literal notranslate"><span class="pre">subksp</span></code>. This mechanism enables the user to set different solvers for
the various blocks. To set the appropriate data structures, the user
<em>must</em> explicitly call <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetUp.html#KSPSetUp">KSPSetUp</a>()</span></code> before calling
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBJacobiGetSubKSP.html#PCBJacobiGetSubKSP">PCBJacobiGetSubKSP</a>()</span></code> or <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMGetSubKSP.html#PCASMGetSubKSP">PCASMGetSubKSP</a>(</span></code>). For further details,
see
<a class="reference external" href="https://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/tutorials/ex7.c.html">KSP Tutorial ex7</a>
or
<a class="reference external" href="https://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/tutorials/ex8.c.html">KSP Tutorial ex8</a>.</p>
<p>The block Jacobi, block Gauss-Seidel, and additive Schwarz
preconditioners allow the user to set the number of blocks into which
the problem is divided. The options database commands to set this value
are <code class="docutils literal notranslate"><span class="pre">-pc_bjacobi_blocks</span></code> <code class="docutils literal notranslate"><span class="pre">n</span></code> and <code class="docutils literal notranslate"><span class="pre">-pc_bgs_blocks</span></code> <code class="docutils literal notranslate"><span class="pre">n</span></code>, and,
within a program, the corresponding routines are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBJacobiSetTotalBlocks.html#PCBJacobiSetTotalBlocks">PCBJacobiSetTotalBlocks</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">blocks</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">size</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetTotalSubdomains.html#PCASMSetTotalSubdomains">PCASMSetTotalSubdomains</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">n</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span> <span class="o">*</span><span class="n">is</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span> <span class="o">*</span><span class="n">islocal</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetType.html#PCASMSetType">PCASMSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PCASMType</a></span> <span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>The optional argument <code class="docutils literal notranslate"><span class="pre">size</span></code> is an array indicating the size of each
block. Currently, for certain parallel matrix formats, only a single
block per process is supported. However, the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATMPIAIJ.html#MATMPIAIJ">MATMPIAIJ</a></span></code> and
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATMPIBAIJ.html#MATMPIBAIJ">MATMPIBAIJ</a></span></code> formats support the use of general blocks as long as no
blocks are shared among processes. The <code class="docutils literal notranslate"><span class="pre">is</span></code> argument contains the
index sets that define the subdomains.</p>
<p>The object <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PCASMType</a></span></code> is one of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_BASIC</a></span></code>,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_INTERPOLATE</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_RESTRICT</a></span></code>, or<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_NONE</a></span></code> and may
also be set with the options database <code class="docutils literal notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils literal notranslate"><span class="pre">[basic</span></code>,
<code class="docutils literal notranslate"><span class="pre">interpolate</span></code>, <code class="docutils literal notranslate"><span class="pre">restrict</span></code>, <code class="docutils literal notranslate"><span class="pre">none]</span></code>. The type <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_BASIC</a></span></code> (or
<code class="docutils literal notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils literal notranslate"><span class="pre">basic</span></code>) corresponds to the standard additive Schwarz
method that uses the full restriction and interpolation operators. The
type <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_RESTRICT</a></span></code> (or <code class="docutils literal notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils literal notranslate"><span class="pre">restrict</span></code>) uses a full
restriction operator, but during the interpolation process ignores the
off-process values. Similarly, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_INTERPOLATE</a></span></code> (or
<code class="docutils literal notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils literal notranslate"><span class="pre">interpolate</span></code>) uses a limited restriction process in
conjunction with a full interpolation, while <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_NONE</a></span></code> (or
<code class="docutils literal notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils literal notranslate"><span class="pre">none</span></code>) ignores off-process values for both
restriction and interpolation. The ASM types with limited restriction or
interpolation were suggested by Xiao-Chuan Cai and Marcus Sarkis
<span id="id20">[<a class="reference internal" href="#id218"><span>CS97</span></a>]</span>. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMType.html#PCASMType">PC_ASM_RESTRICT</a></span></code> is the PETSc default, as
it saves substantial communication and for many problems has the added
benefit of requiring fewer iterations for convergence than the standard
additive Schwarz method.</p>
<p>The user can also set the number of blocks and sizes on a per-process
basis with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBJacobiSetLocalBlocks.html#PCBJacobiSetLocalBlocks">PCBJacobiSetLocalBlocks</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">blocks</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">size</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetLocalSubdomains.html#PCASMSetLocalSubdomains">PCASMSetLocalSubdomains</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">N</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span> <span class="o">*</span><span class="n">is</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span> <span class="o">*</span><span class="n">islocal</span><span class="p">);</span>
</pre></div>
</div>
<p>For the ASM preconditioner one can use the following command to set the
overlap to compute in constructing the subdomains.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetOverlap.html#PCASMSetOverlap">PCASMSetOverlap</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">overlap</span><span class="p">);</span>
</pre></div>
</div>
<p>The overlap defaults to 1, so if one desires that no additional overlap
be computed beyond what may have been set with a call to
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetTotalSubdomains.html#PCASMSetTotalSubdomains">PCASMSetTotalSubdomains</a>()</span></code> or <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetLocalSubdomains.html#PCASMSetLocalSubdomains">PCASMSetLocalSubdomains</a>()</span></code>, then
<code class="docutils literal notranslate"><span class="pre">overlap</span></code> must be set to be 0. In particular, if one does <em>not</em>
explicitly set the subdomains in an application code, then all overlap
would be computed internally by PETSc, and using an overlap of 0 would
result in an ASM variant that is equivalent to the block Jacobi
preconditioner. Note that one can define initial index sets <code class="docutils literal notranslate"><span class="pre">is</span></code> with
<em>any</em> overlap via <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetTotalSubdomains.html#PCASMSetTotalSubdomains">PCASMSetTotalSubdomains</a>()</span></code> or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetLocalSubdomains.html#PCASMSetLocalSubdomains">PCASMSetLocalSubdomains</a>()</span></code>; the routine <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASMSetOverlap.html#PCASMSetOverlap">PCASMSetOverlap</a>()</span></code> merely
allows PETSc to extend that overlap further if desired.</p>
<p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> is an experimental generalization of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code> that allows
the user to specify subdomains that span multiple MPI ranks. This can be
useful for problems where small subdomains result in poor convergence.
To be effective, the multirank subproblems must be solved using a
sufficient strong subsolver, such as LU, for which <code class="docutils literal notranslate"><span class="pre">SuperLU_DIST</span></code> or a
similar parallel direct solver could be used; other choices may include
a multigrid solver on the subdomains.</p>
<p>The interface for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> is similar to that of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code>. In
particular, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMType.html#PCGASMType">PCGASMType</a></span></code> is one of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMType.html#PCGASMType">PC_GASM_BASIC</a></span></code>,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMType.html#PCGASMType">PC_GASM_INTERPOLATE</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMType.html#PCGASMType">PC_GASM_RESTRICT</a></span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMType.html#PCGASMType">PC_GASM_NONE</a></span></code>. These
options have the same meaning as with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code> and may also be set with
the options database <code class="docutils literal notranslate"><span class="pre">-pc_gasm_type</span></code> <code class="docutils literal notranslate"><span class="pre">[basic</span></code>, <code class="docutils literal notranslate"><span class="pre">interpolate</span></code>,
<code class="docutils literal notranslate"><span class="pre">restrict</span></code>, <code class="docutils literal notranslate"><span class="pre">none]</span></code>.</p>
<p>Unlike <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code>, however, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> allows the user to define
subdomains that span multiple MPI ranks. The simplest way to do this is
using a call to <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMSetTotalSubdomains.html#PCGASMSetTotalSubdomains">PCGASMSetTotalSubdomains</a>(<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="pre">pc,PetscPetscInt</span> <span class="pre">N)</span></code> with
the total number of subdomains <code class="docutils literal notranslate"><span class="pre">N</span></code> that is smaller than the MPI
communicator <code class="docutils literal notranslate"><span class="pre">size</span></code>. In this case <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> will coalesce <code class="docutils literal notranslate"><span class="pre">size/N</span></code>
concecutive single-rank subdomains into a single multi-rank subdomain.
The single-rank subdomains contain the degrees of freedom corresponding
to the locally-owned rows of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> preconditioning matrix –
these are the subdomains <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> use by default.</p>
<p>Each of the multirank subdomain subproblems is defined on the
subcommunicator that contains the coalesced <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> ranks. In general
this might not result in a very good subproblem if the single-rank
problems corresponding to the coalesced ranks are not very strongly
connected. In the future this will be addressed with a hierarchical
partitioner that generates well-connected coarse subdomains first before
subpartitioning them into the single-rank subdomains.</p>
<p>In the meantime the user can provide his or her own multi-rank
subdomains by calling<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMSetSubdomains.html#PCGASMSetSubdomains">PCGASMSetSubdomains</a>(<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a>,<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a>[],<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a>[])</span></code> where each
of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span></code> objects on the list defines the inner (without the
overlap) or the outer (including the overlap) subdomain on the
subcommunicator of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span></code> object. A helper subroutine
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMCreateSubdomains2D.html#PCGASMCreateSubdomains2D">PCGASMCreateSubdomains2D</a>()</span></code> is similar to PCASM’s but is capable of
constructing multi-rank subdomains that can be then used with
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMSetSubdomains.html#PCGASMSetSubdomains">PCGASMSetSubdomains</a>()</span></code>. An alternative way of creating multi-rank
subdomains is by using the underlying DM object, if it is capable of
generating such decompositions via <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMCreateDomainDecomposition.html#DMCreateDomainDecomposition">DMCreateDomainDecomposition</a>()</span></code>.
Ordinarily the decomposition specified by the user via
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMSetSubdomains.html#PCGASMSetSubdomains">PCGASMSetSubdomains</a>()</span></code> takes precedence, unless
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMSetUseDMSubdomains.html#PCGASMSetUseDMSubdomains">PCGASMSetUseDMSubdomains</a>()</span></code> instructs <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASM.html#PCGASM">PCGASM</a></span></code> to prefer
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span></code>-created decompositions.</p>
<p>Currently there is no support for increasing the overlap of multi-rank
subdomains via<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMSetOverlap.html#PCGASMSetOverlap">PCGASMSetOverlap</a>()</span></code> – this functionality works only
for subdomains that fit within a single MPI rank, exactly as in
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCASM.html#PCASM">PCASM</a></span></code>.</p>
<p>Examples of the described PCGASM usage can be found in
<a class="reference external" href="https://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/tutorials/ex62.c.html">KSP Tutorial ex62</a>.
In particular, <code class="docutils literal notranslate"><span class="pre">runex62_superlu_dist</span></code> illustrates the use of
<code class="docutils literal notranslate"><span class="pre">SuperLU_DIST</span></code> as the subdomain solver on coalesced multi-rank
subdomains. The <code class="docutils literal notranslate"><span class="pre">runex62_2D_*</span></code> examples illustrate the use of
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGASMCreateSubdomains2D.html#PCGASMCreateSubdomains2D">PCGASMCreateSubdomains2D</a>()</span></code>.</p>
</div>
<div class="section" id="algebraic-multigrid-amg-preconditioners">
<span id="sec-amg"></span><h3>Algebraic Multigrid (AMG) Preconditioners<a class="headerlink" href="#algebraic-multigrid-amg-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>PETSc has a native algebraic multigrid preconditioner <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGAMG.html#PCGAMG">PCGAMG</a></span></code> –
<em>gamg</em> – and interfaces to two external AMG packages: <em>hypre</em> and <em>ML</em>.
<em>Hypre</em> is relatively monolithic in that a PETSc matrix is into a hypre
matrix and then <em>hypre</em> is called to do the entire solve. <em>ML</em> is more
modular in that PETSc only has <em>ML</em> generate the coarse grid spaces
(columns of the prolongation operator), which is core of an AMG method,
and then constructs a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMG.html#PCMG">PCMG</a></span></code> with Galerkin coarse grid operator
construction. GAMG is designed from the beginning to be modular, to
allow for new components to be added easily and also populates a
multigrid preconditioner <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMG.html#PCMG">PCMG</a></span></code> so generic multigrid parameters are
used. PETSc provides a fully supported (smoothed) aggregation AMG,
(<code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">gamg</span> <span class="pre">-pc_gamg_type</span> <span class="pre">agg</span></code> or <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a>(pc,<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGAMG.html#PCGAMG">PCGAMG</a>)</span></code> and
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGAMGSetType.html#PCGAMGSetType">PCGAMGSetType</a>(pc,PCGAMGAGG)</span></code>, as well as reference implementations of
a classical AMG method (<code class="docutils literal notranslate"><span class="pre">-pc_gamg_type</span> <span class="pre">classical</span></code>), a hybrid geometric
AMG method (<code class="docutils literal notranslate"><span class="pre">-pc_gamg_type</span> <span class="pre">geo</span></code>), and a 2.5D AMG method DofColumns
<span id="id21">[<a class="reference internal" href="#id1060"><span>ISG15</span></a>]</span>. GAMG does require the use
of (MPI)AIJ matrices. For instance, BAIJ matrices are not supported. One
can use AIJ instead of BAIJ without changing any code other than the
constructor (or the <code class="docutils literal notranslate"><span class="pre">-mat_type</span></code> from the command line). For instance,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetValuesBlocked.html#MatSetValuesBlocked">MatSetValuesBlocked</a></span></code> works with AIJ matrices.</p>
<p>GAMG provides unsmoothed aggregation (<code class="docutils literal notranslate"><span class="pre">-pc_gamg_agg_nsmooths</span> <span class="pre">0</span></code>) and
smoothed aggregation (<code class="docutils literal notranslate"><span class="pre">-pc_gamg_agg_nsmooths</span> <span class="pre">1</span></code> or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGAMGSetNSmooths.html#PCGAMGSetNSmooths">PCGAMGSetNSmooths</a>(pc,1)</span></code>). Smoothed aggregation (SA) is recommended
for symmetric positive definite systems. Unsmoothed aggregation can be
useful for asymmetric problems and problems where highest eigen
estimates are problematic. If poor convergence rates are observed using
the smoothed version one can test unsmoothed aggregation.</p>
<p><strong>Eigenvalue estimates:</strong> The parameters for the KSP eigen estimator,
use for SA, can be set with <code class="docutils literal notranslate"><span class="pre">-pc_gamg_esteig_ksp_max_it</span></code> and
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_esteig_ksp_type</span></code>. For example CG generally converges to the
highest eigenvalue fast than GMRES (the default for KSP) if your problem
is symmetric positive definite. One can specify CG with
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_esteig_ksp_type</span> <span class="pre">cg</span></code>. The default for
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_esteig_ksp_max_it</span></code> is 10, which we have found is pretty safe
with a (default) safety factor of 1.1. One can specify the range of real
eigenvalues, in the same way that one can for Chebyshev KSP solvers
(smoothers), with <code class="docutils literal notranslate"><span class="pre">-pc_gamg_eigenvalues</span> <span class="pre"><emin,emax></span></code>. GAMG sets the MG
smoother type to chebyshev by default. By default, GAMG uses its eigen
estimate, if it has one, for Chebyshev smoothers if the smoother uses
Jacobi preconditioning. This can be overridden with
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_use_sa_esteig</span>  <span class="pre"><true,false></span></code>.</p>
<p>AMG methods requires knowledge of the number of degrees of freedom per
vertex, the default is one (a scalar problem). Vector problems like
elasticity should set the block size of the matrix appropriately with
<code class="docutils literal notranslate"><span class="pre">-mat_block_size</span> <span class="pre">bs</span></code> or <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetBlockSize.html#MatSetBlockSize">MatSetBlockSize</a>(mat,bs)</span></code>. Equations must be
ordered in “vertex-major” ordering (e.g.,
<span class="math">\(x_1,y_1,z_1,x_2,y_2,...\)</span>).</p>
<p><strong>Near null space:</strong> Smoothed aggregation requires an explicit
representation of the (near) null space of the operator for optimal
performance. One can provide an orthonormal set of null space vectors
with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetNearNullSpace.html#MatSetNearNullSpace">MatSetNearNullSpace</a>()</span></code>. The vector of all ones is the default,
for each variable given by the block size (e.g., the translational rigid
body modes). For elasticity, where rotational rigid body modes are
required to complete the near null space you can use
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpaceCreateRigidBody.html#MatNullSpaceCreateRigidBody">MatNullSpaceCreateRigidBody</a>()</span></code> to create the null space vectors and
then <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetNearNullSpace.html#MatSetNearNullSpace">MatSetNearNullSpace</a>()</span></code>.</p>
<p><strong>Coarse grid data model:</strong> The GAMG framework provides for reducing the
number of active processes on coarse grids to reduce communication costs
when there is not enough parallelism to keep relative communication
costs down. Most AMG solver reduce to just one active process on the
coarsest grid (the PETSc MG framework also supports redundantly solving
the coarse grid on all processes to potentially reduce communication
costs), although this forcing to one process can be overridden if one
wishes to use a parallel coarse grid solver. GAMG generalizes this by
reducing the active number of processes on other coarse grids as well.
GAMG will select the number of active processors by fitting the desired
number of equation per process (set with
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_process_eq_limit</span> <span class="pre"><50>,</span></code>) at each level given that size of
each level. If <span class="math">\(P_i < P\)</span> processors are desired on a level
<span class="math">\(i\)</span> then the first <span class="math">\(P_i\)</span> ranks are populated with the grid
and the remaining are empty on that grid. One can, and probably should,
repartition the coarse grids with <code class="docutils literal notranslate"><span class="pre">-pc_gamg_repartition</span> <span class="pre"><true>,</span></code>,
otherwise an integer process reduction factor (<span class="math">\(q\)</span>) is selected
and the equations on the first <span class="math">\(q\)</span> processes are move to process
0, and so on. As mentioned multigrid generally coarsens the problem
until it is small enough to be solved with an exact solver (eg, LU or
SVD) in a relatively small time. GAMG will stop coarsening when the
number of equation on a grid falls below at threshold give by
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_coarse_eq_limit</span> <span class="pre"><50>,</span></code>.</p>
<p><strong>Coarse grid parameters:</strong> There are several options to provide
parameters to the coarsening algorithm and parallel data layout. Run a
code that uses GAMG with <code class="docutils literal notranslate"><span class="pre">-help</span></code> to get full listing of GAMG
parameters with short parameter descriptions. The rate of coarsening is
critical in AMG performance – too slow of coarsening will result in an
overly expensive solver per iteration and too fast coarsening will
result in decrease in the convergence rate. <code class="docutils literal notranslate"><span class="pre">-pc_gamg_threshold</span> <span class="pre"><0></span></code>
and <code class="docutils literal notranslate"><span class="pre">-pc_gamg_square_graph</span> <span class="pre"><1>,</span></code> are the primary parameters that
control coarsening rates, which is very important for AMG performance. A
greedy maximal independent set (MIS) algorithm is used in coarsening.
Squaring the graph implements so called MIS-2, the root vertex in an
aggregate is more than two edges away from another root vertex, instead
of more than one in MIS. The threshold parameter sets a normalized
threshold for which edges are removed from the MIS graph, thereby
coarsening slower. Zero will keep all non-zero edges, a negative number
will keep zero edges, a positive number will drop small edges. Typical
finite threshold values are in the range of <span class="math">\(0.01 - 0.05\)</span>. There
are additional parameters for changing the weights on coarse grids.
Note, the parallel algorithm requires symmetric weights/matrix. You must
use <code class="docutils literal notranslate"><span class="pre">-pc_gamg_sym_graph</span> <span class="pre"><true></span></code> to symmetrize the graph if your
problem is not symmetric.</p>
<p><strong>Trouble shooting algebraic multigrid methods:</strong> If <em>GAMG</em>, <em>ML</em>, or
<em>hypre</em> does not perform well the first thing to try is one of the other
methods. Often the default parameters or just the strengths of different
algorithms can fix performance problems or provide useful information to
guide further debugging. There are several sources of poor performance
of AMG solvers and often special purpose methods must be developed to
achieve the full potential of multigrid. To name just a few sources of
performance degradation that may not be fixed with parameters in PETSc
currently: non-elliptic operators, curl/curl operators, highly stretched
grids or highly anisotropic problems, large jumps in material
coefficients with complex geometry (AMG is particularly well suited to
jumps in coefficients but it is not a perfect solution), highly
incompressible elasticity, not to mention ill-posed problems, and many
others. For Grad-Div and Curl-Curl operators, you may want to try the
Auxiliary-space Maxwell Solver (AMS,
<code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">ams</span></code>) or the Auxiliary-space Divergence
Solver (ADS, <code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">ads</span></code>) solvers. These
solvers need some additional information on the underlying mesh;
specifically, AMS needs the discrete gradient operator, which can be
specified via <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCHYPRESetDiscreteGradient.html#PCHYPRESetDiscreteGradient">PCHYPRESetDiscreteGradient</a>()</span></code>. In addition to the
discrete gradient, ADS also needs the specification of the discrete curl
operator, which can be set using <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCHYPRESetDiscreteCurl.html#PCHYPRESetDiscreteCurl">PCHYPRESetDiscreteCurl</a>()</span></code>.</p>
<p><strong>I am converging slowly, what do I do?</strong> AMG methods are sensitive to
coarsening rates and methods; for GAMG use <code class="docutils literal notranslate"><span class="pre">-pc_gamg_threshold</span> <span class="pre"><x></span></code> to
regulate coarsening rates and PCGAMGSetThreshold, higher values decrease
coarsening rate. Squaring the graph is the second mechanism for
increasing coarsening rate. Use <code class="docutils literal notranslate"><span class="pre">-pc_gamg_square_graph</span> <span class="pre"><N>,</span></code>, or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGAMGSetSquareGraph.html#PCGAMGSetSquareGraph">PCGAMGSetSquareGraph</a>(pc,N)</span></code>, to square the graph on the finest N
levels. A high threshold (e.g., <span class="math">\(x=0.08\)</span>) will result in an
expensive but potentially powerful preconditioner, and a low threshold
(e.g., <span class="math">\(x=0.0\)</span>) will result in faster coarsening, fewer levels,
cheaper solves, and generally worse convergence rates.</p>
<p>One can run with <code class="docutils literal notranslate"><span class="pre">-info</span></code> and grep for “GAMG” to get some statistics on
each level, which can be used to see if you are coarsening at an
appropriate rate. With smoothed aggregation you generally want to coarse
at about a rate of 3:1 in each dimension. Coarsening too slow will
result in large numbers of non-zeros per row on coarse grids (this is
reported). The number of non-zeros can go up very high, say about 300
(times the degrees-of-freedom per vertex) on a 3D hex mesh. One can also
look at the grid complexity, which is also reported (the ration of the
total number of matrix entries for all levels to the number of matrix
entries on the fine level). Grid complexity should be well under 2.0 and
preferably around <span class="math">\(1.3\)</span> or lower. If convergence is poor and the
Galerkin coarse grid construction is much smaller than the time for each
solve then one can safely decrease the coarsening rate.
<code class="docutils literal notranslate"><span class="pre">-pc_gamg_threshold</span></code> <span class="math">\(0.0\)</span> is the simplest and most robust
option, and is recommended if poor convergence rates are observed, at
least until the source of the problem is discovered. In conclusion, if
convergence is slow then decreasing the coarsening rate (increasing the
threshold) should be tried.</p>
<p><strong>A note on Chebyshev smoothers.</strong> Chebyshev solvers are attractive as
multigrid smoothers because they can target a specific interval of the
spectrum which is the purpose of a smoother. The spectral bounds for
Chebyshev solvers are simple to compute because they rely on the highest
eigenvalue of your (diagonally preconditioned) operator, which is
conceptually simple to compute. However, if this highest eigenvalue
estimate is not accurate (too low) then the solvers can fail with and
indefinite preconditioner message. One can run with <code class="docutils literal notranslate"><span class="pre">-info</span></code> and grep
for “GAMG” to get these estimates or use <code class="docutils literal notranslate"><span class="pre">-ksp_view</span></code>. These highest
eigenvalues are generally between 1.5-3.0. For symmetric positive
definite systems CG is a better eigenvalue estimator
<code class="docutils literal notranslate"><span class="pre">-mg_levels_esteig_ksp_type</span> <span class="pre">cg</span></code>. Indefinite matrix messages are often
caused by bad Eigen estimates. Explicitly damped Jacobi or Krylov
smoothers can provide an alternative to Chebyshev and <em>hypre</em> has
alternative smoothers.</p>
<p><strong>Now am I solving alright, can I expect better?</strong> If you find that you
are getting nearly on digit in reduction of the residual per iteration
and are using a modest number of point smoothing steps (e.g., 1-4
iterations of SOR), then you may be fairly close to textbook multigrid
efficiency. Although you also need to check the setup costs. This can be
determined by running with <code class="docutils literal notranslate"><span class="pre">-log_view</span></code> and check that the time for the
Galerkin coarse grid construction (<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatPtAP.html#MatPtAP">MatPtAP</a></span></code>) is not (much) more than
the time spent in each solve (<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSolve.html#KSPSolve">KSPSolve</a></span></code>). If the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatPtAP.html#MatPtAP">MatPtAP</a></span></code> time is
too large then one can increase the coarsening rate by decreasing the
threshold and squaring the coarsening graph
(<code class="docutils literal notranslate"><span class="pre">-pc_gamg_square_graph</span> <span class="pre"><N></span></code>, squares the graph on the finest N
levels). Likewise if your <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatPtAP.html#MatPtAP">MatPtAP</a></span></code> time is small and your convergence
rate is not ideal then you could decrease the coarsening rate.</p>
<p>PETSc’s AMG solver is constructed as a framework for developers to
easily add AMG capabilities, like a new AMG methods or an AMG component
like a matrix triple product. Contact us directly if you are interested
in contributing.</p>
</div>
<div class="section" id="balancing-domain-decomposition-by-constraints">
<h3>Balancing Domain Decomposition by Constraints<a class="headerlink" href="#balancing-domain-decomposition-by-constraints" title="Permalink to this headline">¶</a></h3>
<p>PETSc provides the Balancing Domain Decomposition by Constraints (BDDC)
method for preconditioning parallel finite element problems stored in
unassembled format (see <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATIS.html#MATIS">MATIS</a></span></code>). BDDC is a 2-level non-overlapping
domain decomposition method which can be easily adapted to different
problems and discretizations by means of few user customizations. The
application of the preconditioner to a vector consists in the static
condensation of the residual at the interior of the subdomains by means
of local Dirichet solves, followed by an additive combination of Neumann
local corrections and the solution of a global coupled coarse problem.
Command line options for the underlying <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> objects are prefixed by
<code class="docutils literal notranslate"><span class="pre">-pc_bddc_dirichlet</span></code>, <code class="docutils literal notranslate"><span class="pre">-pc_bddc_neumann</span></code>, and <code class="docutils literal notranslate"><span class="pre">-pc_bddc_coarse</span></code>
respectively.</p>
<p>The current implementation supports any kind of linear system, and
assumes a one-to-one mapping between subdomains and MPI processes.
Complex numbers are supported as well. For non-symmetric problems, use
the runtime option <code class="docutils literal notranslate"><span class="pre">-pc_bddc_symmetric</span> <span class="pre">0</span></code>.</p>
<p>Unlike conventional non-overlapping methods that iterates just on the
degrees of freedom at the interface between subdomain, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code>
iterates on the whole set of degrees of freedom, allowing the use of
approximate subdomain solvers. When using approximate solvers, the
command line switches <code class="docutils literal notranslate"><span class="pre">-pc_bddc_dirichlet_approximate</span></code> and/or
<code class="docutils literal notranslate"><span class="pre">-pc_bddc_neumann_approximate</span></code> should be used to inform <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code>. If
any of the local problems is singular, the nullspace of the local
operator should be attached to the local matrix via
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetNullSpace.html#MatSetNullSpace">MatSetNullSpace</a>()</span></code>.</p>
<p>At the basis of the method there’s the analysis of the connected
components of the interface for the detection of vertices, edges and
faces equivalence classes. Additional information on the degrees of
freedom can be supplied to <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code> by using the following functions:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetDofsSplitting.html#PCBDDCSetDofsSplitting">PCBDDCSetDofsSplitting</a>()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetLocalAdjacencyGraph.html#PCBDDCSetLocalAdjacencyGraph">PCBDDCSetLocalAdjacencyGraph</a>()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetPrimalVerticesLocalIS.html#PCBDDCSetPrimalVerticesLocalIS">PCBDDCSetPrimalVerticesLocalIS</a>()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetNeumannBoundaries.html#PCBDDCSetNeumannBoundaries">PCBDDCSetNeumannBoundaries</a>()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetDirichletBoundaries.html#PCBDDCSetDirichletBoundaries">PCBDDCSetDirichletBoundaries</a>()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetNeumannBoundariesLocal.html#PCBDDCSetNeumannBoundariesLocal">PCBDDCSetNeumannBoundariesLocal</a>()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetDirichletBoundariesLocal.html#PCBDDCSetDirichletBoundariesLocal">PCBDDCSetDirichletBoundariesLocal</a>()</span></code></p></li>
</ul>
<p>Crucial for the convergence of the iterative process is the
specification of the primal constraints to be imposed at the interface
between subdomains. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code> uses by default vertex continuities and
edge arithmetic averages, which are enough for the three-dimensional
Poisson problem with constant coefficients. The user can switch on and
off the usage of vertices, edges or face constraints by using the
command line switches <code class="docutils literal notranslate"><span class="pre">-pc_bddc_use_vertices</span></code>, <code class="docutils literal notranslate"><span class="pre">-pc_bddc_use_edges</span></code>,
<code class="docutils literal notranslate"><span class="pre">-pc_bddc_use_faces</span></code>. A customization of the constraints is available
by attaching a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span></code> object to the preconditioning matrix via
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetNearNullSpace.html#MatSetNearNullSpace">MatSetNearNullSpace</a>()</span></code>. The vectors of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span></code> object
should represent the constraints in the form of quadrature rules;
quadrature rules for different classes of the interface can be listed in
the same vector. The number of vectors of the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span></code> object
corresponds to the maximum number of constraints that can be imposed for
each class. Once all the quadrature rules for a given interface class
have been extracted, an SVD operation is performed to retain the
non-singular modes. As an example, the rigid body modes represent an
effective choice for elasticity, even in the almost incompressible case.
For particular problems, e.g. edge-based discretization with Nedelec
elements, a user defined change of basis of the degrees of freedom can
be beneficial for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code>; use <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetChangeOfBasisMat.html#PCBDDCSetChangeOfBasisMat">PCBDDCSetChangeOfBasisMat</a>()</span></code> to
customize the change of basis.</p>
<p>The BDDC method is usually robust with respect to jumps in the material
parameters aligned with the interface; for PDEs with more than one
material parameter you may also consider to use the so-called deluxe
scaling, available via the command line switch
<code class="docutils literal notranslate"><span class="pre">-pc_bddc_use_deluxe_scaling</span></code>. Other scalings are available, see
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCISSetSubdomainScalingFactor.html#PCISSetSubdomainScalingFactor">PCISSetSubdomainScalingFactor</a>()</span></code>,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCISSetSubdomainDiagonalScaling.html#PCISSetSubdomainDiagonalScaling">PCISSetSubdomainDiagonalScaling</a>()</span></code> or
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCISSetUseStiffnessScaling.html#PCISSetUseStiffnessScaling">PCISSetUseStiffnessScaling</a>()</span></code>. However, the convergence properties of
the BDDC method degrades in presence of large jumps in the material
coefficients not aligned with the interface; for such cases, PETSc has
the capability of adaptively computing the primal constraints. Adaptive
selection of constraints could be requested by specifying a threshold
value at command line by using <code class="docutils literal notranslate"><span class="pre">-pc_bddc_adaptive_threshold</span> <span class="pre">x</span></code>. Valid
values for the threshold <code class="docutils literal notranslate"><span class="pre">x</span></code> ranges from 1 to infinity, with smaller
values corresponding to more robust preconditioners. For SPD problems in
2D, or in 3D with only face degrees of freedom (like in the case of
Raviart-Thomas or Brezzi-Douglas-Marini elements), such a threshold is a
very accurate estimator of the condition number of the resulting
preconditioned operator. Since the adaptive selection of constraints for
BDDC methods is still an active topic of research, its implementation is
currently limited to SPD problems; moreover, because the technique
requires the explicit knowledge of the local Schur complements, it needs
the external package MUMPS.</p>
<p>When solving problems decomposed in thousands of subdomains or more, the
solution of the BDDC coarse problem could become a bottleneck; in order
to overcome this issue, the user could either consider to solve the
parallel coarse problem on a subset of the communicator associated with
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code> by using the command line switch
<code class="docutils literal notranslate"><span class="pre">-pc_bddc_coarse_redistribute</span></code>, or instead use a multilevel approach.
The latter can be requested by specifying the number of requested level
at command line (<code class="docutils literal notranslate"><span class="pre">-pc_bddc_levels</span></code>) or by using <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetLevels.html#PCBDDCSetLevels">PCBDDCSetLevels</a>()</span></code>.
An additional parameter (see <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDCSetCoarseningRatio.html#PCBDDCSetCoarseningRatio">PCBDDCSetCoarseningRatio</a>()</span></code>) controls
the number of subdomains that will be generated at the next level; the
larger the coarsening ratio, the lower the number of coarser subdomains.</p>
<p>For further details, see the example
<a class="reference external" href="https://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/tutorials/ex59.c">KSP Tutorial ex59</a>
and the online documentation for <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCBDDC.html#PCBDDC">PCBDDC</a></span></code>.</p>
</div>
<div class="section" id="shell-preconditioners">
<h3>Shell Preconditioners<a class="headerlink" href="#shell-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>The shell preconditioner simply uses an application-provided routine to
implement the preconditioner. To set this routine, one uses the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCShellSetApply.html#PCShellSetApply">PCShellSetApply</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">apply</span><span class="p">)(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span><span class="p">));</span>
</pre></div>
</div>
<p>Often a preconditioner needs access to an application-provided data
structured. For this, one should use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCShellSetContext.html#PCShellSetContext">PCShellSetContext</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>to set this data structure and</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCShellGetContext.html#PCShellGetContext">PCShellGetContext</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="kt">void</span> <span class="o">**</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>to retrieve it in <code class="docutils literal notranslate"><span class="pre">apply</span></code>. The three routine arguments of <code class="docutils literal notranslate"><span class="pre">apply()</span></code>
are the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code>, the input vector, and the output vector, respectively.</p>
<p>For a preconditioner that requires some sort of “setup” before being
used, that requires a new setup every time the operator is changed, one
can provide a routine that is called every time the operator is changed
(usually via <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</a>()</span></code>).</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCShellSetSetUp.html#PCShellSetSetUp">PCShellSetSetUp</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">setup</span><span class="p">)(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span><span class="p">));</span>
</pre></div>
</div>
<p>The argument to the <code class="docutils literal notranslate"><span class="pre">setup</span></code> routine is the same <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> object which
can be used to obtain the operators with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCGetOperators.html#PCGetOperators">PCGetOperators</a>()</span></code> and the
application-provided data structure that was set with
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCShellSetContext.html#PCShellSetContext">PCShellSetContext</a>()</span></code>.</p>
</div>
<div class="section" id="combining-preconditioners">
<span id="sec-combining-pcs"></span><h3>Combining Preconditioners<a class="headerlink" href="#combining-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> type <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCOMPOSITE.html#PCCOMPOSITE">PCCOMPOSITE</a></span></code> allows one to form new preconditioners
by combining already-defined preconditioners and solvers. Combining
preconditioners usually requires some experimentation to find a
combination of preconditioners that works better than any single method.
It is a tricky business and is not recommended until your application
code is complete and running and you are trying to improve performance.
In many cases using a single preconditioner is better than a
combination; an exception is the multigrid/multilevel preconditioners
(solvers) that are always combinations of some sort, see <a class="reference internal" href="#sec-mg"><span class="std std-ref">Multigrid Preconditioners</span></a>.</p>
<p>Let <span class="math">\(B_1\)</span> and <span class="math">\(B_2\)</span> represent the application of two
preconditioners of type <code class="docutils literal notranslate"><span class="pre">type1</span></code> and <code class="docutils literal notranslate"><span class="pre">type2</span></code>. The preconditioner
<span class="math">\(B = B_1 + B_2\)</span> can be obtained with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCOMPOSITE.html#PCCOMPOSITE">PCCOMPOSITE</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeAddPC.html#PCCompositeAddPC">PCCompositeAddPC</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n">type1</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeAddPC.html#PCCompositeAddPC">PCCompositeAddPC</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n">type2</span><span class="p">);</span>
</pre></div>
</div>
<p>Any number of preconditioners may added in this way.</p>
<p>This way of combining preconditioners is called additive, since the
actions of the preconditioners are added together. This is the default
behavior. An alternative can be set with the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeSetType.html#PCCompositeSetType">PCCompositeSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeType.html#PCCompositeType">PCCompositeType</a></span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeType.html#PCCompositeType">PC_COMPOSITE_MULTIPLICATIVE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>In this form the new residual is updated after the application of each
preconditioner and the next preconditioner applied to the next residual.
For example, with two composed preconditioners: <span class="math">\(B_1\)</span> and
<span class="math">\(B_2\)</span>; <span class="math">\(y = B x\)</span> is obtained from</p>
<div class="math">
\[\begin{aligned}
y = B_1 x \\
w_1 = x - A y \\
y = y + B_2 w_1\end{aligned}\]</div>
<p>Loosely, this corresponds to a Gauss-Seidel iteration, while additive
corresponds to a Jacobi iteration.</p>
<p>Under most circumstances, the multiplicative form requires one-half the
number of iterations as the additive form; however, the multiplicative
form does require the application of <span class="math">\(A\)</span> inside the
preconditioner.</p>
<p>In the multiplicative version, the calculation of the residual inside
the preconditioner can be done in two ways: using the original linear
system matrix or using the matrix used to build the preconditioners
<span class="math">\(B_1\)</span>, <span class="math">\(B_2\)</span>, etc. By default it uses the “preconditioner
matrix”, to use the <code class="docutils literal notranslate"><span class="pre">Amat</span></code> matrix use the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetUseAmat.html#PCSetUseAmat">PCSetUseAmat</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The individual preconditioners can be accessed (in order to set options)
via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeGetPC.html#PCCompositeGetPC">PCCompositeGetPC</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">count</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="o">*</span><span class="n">subpc</span><span class="p">);</span>
</pre></div>
</div>
<p>For example, to set the first sub preconditioners to use ILU(1)</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">subpc</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCCompositeGetPC.html#PCCompositeGetPC">PCCompositeGetPC</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="o">&</span><span class="n">subpc</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetFill.html#PCFactorSetFill">PCFactorSetFill</a></span><span class="p">(</span><span class="n">subpc</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</div>
<p>One can also change the operator that is used to construct a particular
PC in the composite PC call PCSetOperators() on the obtained PC.</p>
<p>These various options can also be set via the options database. For
example, <code class="docutils literal notranslate"><span class="pre">-pc_type</span></code> <code class="docutils literal notranslate"><span class="pre">composite</span></code> <code class="docutils literal notranslate"><span class="pre">-pc_composite_pcs</span></code> <code class="docutils literal notranslate"><span class="pre">jacobi,ilu</span></code>
causes the composite preconditioner to be used with two preconditioners:
Jacobi and ILU. The option <code class="docutils literal notranslate"><span class="pre">-pc_composite_type</span></code> <code class="docutils literal notranslate"><span class="pre">multiplicative</span></code>
initiates the multiplicative version of the algorithm, while
<code class="docutils literal notranslate"><span class="pre">-pc_composite_type</span></code> <code class="docutils literal notranslate"><span class="pre">additive</span></code> the additive version. Using the
<code class="docutils literal notranslate"><span class="pre">Amat</span></code> matrix is obtained with the option <code class="docutils literal notranslate"><span class="pre">-pc_use_amat</span></code>. One sets
options for the sub-preconditioners with the extra prefix <code class="docutils literal notranslate"><span class="pre">-sub_N_</span></code>
where <code class="docutils literal notranslate"><span class="pre">N</span></code> is the number of the sub-preconditioner. For example,
<code class="docutils literal notranslate"><span class="pre">-sub_0_pc_ifactor_fill</span></code> <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
<p>PETSc also allows a preconditioner to be a complete linear solver. This
is achieved with the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCKSP.html#PCKSP">PCKSP</a></span></code> type.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCKSP.html#PCKSP">PCKSP</a></span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCKSP.html#PCKSP">PCKSP</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCKSPGetKSP.html#PCKSPGetKSP">PCKSPGetKSP</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="o">&</span><span class="n">ksp</span><span class="p">);</span>
<span class="cm">/* set any <a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a>/<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a> options */</span>
</pre></div>
</div>
<p>From the command line one can use 5 iterations of biCG-stab with ILU(0)
preconditioning as the preconditioner with
<code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">ksp</span> <span class="pre">-ksp_pc_type</span> <span class="pre">ilu</span> <span class="pre">-ksp_ksp_max_it</span> <span class="pre">5</span> <span class="pre">-ksp_ksp_type</span> <span class="pre">bcgs</span></code>.</p>
<p>By default the inner <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> solver uses the outer preconditioner
matrix, <code class="docutils literal notranslate"><span class="pre">Pmat</span></code>, as the matrix to be solved in the linear system; to
use the matrix that defines the linear system, <code class="docutils literal notranslate"><span class="pre">Amat</span></code> use the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetUseAmat.html#PCSetUseAmat">PCSetUseAmat</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>or at the command line with <code class="docutils literal notranslate"><span class="pre">-pc_use_amat</span></code>.</p>
<p>Naturally, one can use a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCKSP.html#PCKSP">PCKSP</a></span></code> preconditioner inside a composite
preconditioner. For example,
<code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">composite</span> <span class="pre">-pc_composite_pcs</span> <span class="pre">ilu,ksp</span> <span class="pre">-sub_1_pc_type</span> <span class="pre">jacobi</span> <span class="pre">-sub_1_ksp_max_it</span> <span class="pre">10</span></code>
uses two preconditioners: ILU(0) and 10 iterations of GMRES with Jacobi
preconditioning. However, it is not clear whether one would ever wish to
do such a thing.</p>
</div>
<div class="section" id="multigrid-preconditioners">
<span id="sec-mg"></span><h3>Multigrid Preconditioners<a class="headerlink" href="#multigrid-preconditioners" title="Permalink to this headline">¶</a></h3>
<p>A large suite of routines is available for using geometric multigrid as
a preconditioner <a class="footnote-reference brackets" href="#id25" id="id22">2</a>. In the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> framework, the user is required to
provide the coarse grid solver, smoothers, restriction and interpolation
operators, and code to calculate residuals. The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> package allows
these components to be encapuslated within a PETSc-compliant
preconditioner. We fully support both matrix-free and matrix-based
multigrid solvers.</p>
<p>A multigrid preconditioner is created with the four commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPCreate.html#KSPCreate">KSPCreate</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span> <span class="n">comm</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetPC.html#KSPGetPC">KSPGetPC</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="o">*</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMG.html#PCMG">PCMG</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetLevels.html#PCMGSetLevels">PCMGSetLevels</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">levels</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span> <span class="o">*</span><span class="n">comms</span><span class="p">);</span>
</pre></div>
</div>
<p>A large number of parameters affect the multigrid behavior. The command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetType.html#PCMGSetType">PCMGSetType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGType.html#PCMGType">PCMGType</a></span> <span class="n">mode</span><span class="p">);</span>
</pre></div>
</div>
<p>indicates which form of multigrid to apply <span id="id23">[<a class="reference internal" href="#id2058"><span>SBjorstadG96</span></a>]</span>.</p>
<p>For standard V or W-cycle multigrids, one sets the <code class="docutils literal notranslate"><span class="pre">mode</span></code> to be
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGType.html#PCMGType">PC_MG_MULTIPLICATIVE</a></span></code>; for the additive form (which in certain cases
reduces to the BPX method, or additive multilevel Schwarz, or multilevel
diagonal scaling), one uses <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGType.html#PCMGType">PC_MG_ADDITIVE</a></span></code> as the <code class="docutils literal notranslate"><span class="pre">mode</span></code>. For a
variant of full multigrid, one can use <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGType.html#PCMGType">PC_MG_FULL</a></span></code>, and for the
Kaskade algorithm <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGType.html#PCMGType">PC_MG_KASKADE</a></span></code>. For the multiplicative and full
multigrid options, one can use a W-cycle by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetCycleType.html#PCMGSetCycleType">PCMGSetCycleType</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGCycleType.html#PCMGCycleType">PCMGCycleType</a></span> <span class="n">ctype</span><span class="p">);</span>
</pre></div>
</div>
<p>with a value of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGCycleType.html#PCMGCycleType">PC_MG_CYCLE_W</a></span></code> for <code class="docutils literal notranslate"><span class="pre">ctype</span></code>. The commands above can
also be set from the options database. The option names are
<code class="docutils literal notranslate"><span class="pre">-pc_mg_type</span> <span class="pre">[multiplicative,</span> <span class="pre">additive,</span> <span class="pre">full,</span> <span class="pre">kaskade]</span></code>, and
<code class="docutils literal notranslate"><span class="pre">-pc_mg_cycle_type</span></code> <code class="docutils literal notranslate"><span class="pre"><ctype></span></code>.</p>
<p>The user can control the amount of smoothing by configuring the solvers
on the levels. By default, the up and down smoothers are identical. If
separate configuration of up and down smooths is required, it can be
requested with the option <code class="docutils literal notranslate"><span class="pre">-pc_mg_distinct_smoothup</span></code> or the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetDistinctSmoothUp.html#PCMGSetDistinctSmoothUp">PCMGSetDistinctSmoothUp</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The multigrid routines, which determine the solvers and
interpolation/restriction operators that are used, are mandatory. To set
the coarse grid solver, one must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGGetCoarseSolve.html#PCMGGetCoarseSolve">PCMGGetCoarseSolve</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>and set the appropriate options in <code class="docutils literal notranslate"><span class="pre">ksp</span></code>. Similarly, the smoothers are
controlled by first calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGGetSmoother.html#PCMGGetSmoother">PCMGGetSmoother</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>and then setting the various options in the <code class="docutils literal notranslate"><span class="pre">ksp.</span></code> For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGGetSmoother.html#PCMGGetSmoother">PCMGGetSmoother</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="o">&</span><span class="n">ksp</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n">A1</span><span class="p">,</span><span class="n">A1</span><span class="p">);</span>
</pre></div>
</div>
<p>sets the matrix that defines the smoother on level 1 of the multigrid.
While</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGGetSmoother.html#PCMGGetSmoother">PCMGGetSmoother</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="o">&</span><span class="n">ksp</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetPC.html#KSPGetPC">KSPGetPC</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="o">&</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSOR.html#PCSOR">PCSOR</a></span><span class="p">);</span>
</pre></div>
</div>
<p>sets SOR as the smoother to use on level 1.</p>
<p>To use a different pre- or postsmoother, one should call the following
routines instead.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGGetSmootherUp.html#PCMGGetSmootherUp">PCMGGetSmootherUp</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">upksp</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGGetSmootherDown.html#PCMGGetSmootherDown">PCMGGetSmootherDown</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="o">*</span><span class="n">downksp</span><span class="p">);</span>
</pre></div>
</div>
<p>Use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetInterpolation.html#PCMGSetInterpolation">PCMGSetInterpolation</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">P</span><span class="p">);</span>
</pre></div>
</div>
<p>and</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetRestriction.html#PCMGSetRestriction">PCMGSetRestriction</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">R</span><span class="p">);</span>
</pre></div>
</div>
<p>to define the intergrid transfer operations. If only one of these is
set, its transpose will be used for the other.</p>
<p>It is possible for these interpolation operations to be matrix free (see
<a class="reference internal" href="mat.html#sec-matrixfree"><span class="std std-ref">Matrix-Free Matrices</span></a>); One should then make
sure that these operations are defined for the (matrix-free) matrices
passed in. Note that this system is arranged so that if the
interpolation is the transpose of the restriction, you can pass the same
<code class="docutils literal notranslate"><span class="pre">mat</span></code> argument to both <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetRestriction.html#PCMGSetRestriction">PCMGSetRestriction</a>()</span></code> and
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetInterpolation.html#PCMGSetInterpolation">PCMGSetInterpolation</a>()</span></code>.</p>
<p>On each level except the coarsest, one must also set the routine to
compute the residual. The following command suffices:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetResidual.html#PCMGSetResidual">PCMGSetResidual</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a></span> <span class="p">(</span><span class="o">*</span><span class="n">residual</span><span class="p">)(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span><span class="p">),</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">mat</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">residual()</span></code> function normally does not need to be set if one’s
operator is stored in <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span></code> format. In certain circumstances, where it
is much cheaper to calculate the residual directly, rather than through
the usual formula <span class="math">\(b - Ax\)</span>, the user may wish to provide an
alternative.</p>
<p>Finally, the user may provide three work vectors for each level (except
on the finest, where only the residual work vector is required). The
work vectors are set with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetRhs.html#PCMGSetRhs">PCMGSetRhs</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">b</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetX.html#PCMGSetX">PCMGSetX</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">x</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCMGSetR.html#PCMGSetR">PCMGSetR</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span> <span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">level</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="n">r</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> references these vectors, so you should call <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecDestroy.html#VecDestroy">VecDestroy</a>()</span></code>
when you are finished with them. If any of these vectors are not
provided, the preconditioner will allocate them.</p>
<p>One can control the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PC.html#PC">PC</a></span></code> options used on the various
levels (as well as the coarse grid) using the prefix <code class="docutils literal notranslate"><span class="pre">mg_levels_</span></code>
(<code class="docutils literal notranslate"><span class="pre">mg_coarse_</span></code> for the coarse grid). For example,
<code class="docutils literal notranslate"><span class="pre">-mg_levels_ksp_type</span> <span class="pre">cg</span></code> will cause the CG method to be used as the
Krylov method for each level. Or
<code class="docutils literal notranslate"><span class="pre">-mg_levels_pc_type</span> <span class="pre">ilu</span> <span class="pre">-mg_levels_pc_factor_levels</span> <span class="pre">2</span></code> will cause the
ILU preconditioner to be used on each level with two levels of fill in
the incomplete factorization.</p>
</div>
</div>
<div class="section" id="solving-block-matrices">
<span id="sec-block-matrices"></span><h2>Solving Block Matrices<a class="headerlink" href="#solving-block-matrices" title="Permalink to this headline">¶</a></h2>
<p>Block matrices represent an important class of problems in numerical
linear algebra and offer the possibility of far more efficient iterative
solvers than just treating the entire matrix as black box. In this
section we use the common linear algebra definition of block matrices
where matrices are divided in a small, problem-size independent (two,
three or so) number of very large blocks. These blocks arise naturally
from the underlying physics or discretization of the problem, for
example, the velocity and pressure. Under a certain numbering of
unknowns the matrix can be written as</p>
<div class="math">
\[\left( \begin{array}{cccc}
A_{00} & A_{01} & A_{02} & A_{03} \\
A_{10} & A_{11} & A_{12} & A_{13} \\
A_{20} & A_{21} & A_{22} & A_{23} \\
A_{30} & A_{31} & A_{32} & A_{33} \\
\end{array} \right),\]</div>
<p>where each <span class="math">\(A_{ij}\)</span> is an entire block. On a parallel computer the
matrices are not explicitly stored this way. Instead, each process will
own some of the rows of <span class="math">\(A_{0*}\)</span>, <span class="math">\(A_{1*}\)</span> etc. On a
process, the blocks may be stored one block followed by another</p>
<div class="math">
\[\left( \begin{array}{ccccccc}
A_{{00}_{00}} & A_{{00}_{01}} & A_{{00}_{02}} & ... & A_{{01}_{00}} & A_{{01}_{02}} & ... \\
A_{{00}_{10}} & A_{{00}_{11}} & A_{{00}_{12}} & ... & A_{{01}_{10}} & A_{{01}_{12}} & ... \\
A_{{00}_{20}} & A_{{00}_{21}} & A_{{00}_{22}} & ... & A_{{01}_{20}} & A_{{01}_{22}} & ...\\
... \\
A_{{10}_{00}} & A_{{10}_{01}} & A_{{10}_{02}} & ... & A_{{11}_{00}} & A_{{11}_{02}} & ... \\
A_{{10}_{10}} & A_{{10}_{11}} & A_{{10}_{12}} & ... & A_{{11}_{10}} & A_{{11}_{12}} & ... \\
... \\
\end{array} \right)\]</div>
<p>or interlaced, for example with two blocks</p>
<div class="math">
\[\left( \begin{array}{ccccc}
A_{{00}_{00}} & A_{{01}_{00}} & A_{{00}_{01}} & A_{{01}_{01}} & ... \\
A_{{10}_{00}} & A_{{11}_{00}} & A_{{10}_{01}} & A_{{11}_{01}} & ... \\
... \\
A_{{00}_{10}} & A_{{01}_{10}} & A_{{00}_{11}} & A_{{01}_{11}} & ...\\
A_{{10}_{10}} & A_{{11}_{10}} & A_{{10}_{11}} & A_{{11}_{11}} & ...\\
...
\end{array} \right).\]</div>
<p>Note that for interlaced storage the number of rows/columns of each
block must be the same size. Matrices obtained with <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMCreateMatrix.html#DMCreateMatrix">DMCreateMatrix</a>()</span></code>
where the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span></code> is a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMDA/DMDA.html#DMDA">DMDA</a></span></code> are always stored interlaced. Block
matrices can also be stored using the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATNEST.html#MATNEST">MATNEST</a></span></code> format which holds
separate assembled blocks. Each of these nested matrices is itself
distributed in parallel. It is more efficient to use <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATNEST.html#MATNEST">MATNEST</a></span></code> with
the methods described in this section because there are fewer copies and
better formats (e.g. <code class="docutils literal notranslate"><span class="pre">BAIJ</span></code> or <code class="docutils literal notranslate"><span class="pre">SBAIJ</span></code>) can be used for the
components, but it is not possible to use many other methods with
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATNEST.html#MATNEST">MATNEST</a></span></code>. See <a class="reference internal" href="mat.html#sec-matnest"><span class="std std-ref">Block Matrices</span></a> for more on assembling
block matrices without depending on a specific matrix format.</p>
<p>The PETSc <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFIELDSPLIT.html#PCFIELDSPLIT">PCFIELDSPLIT</a></span></code> preconditioner is used to implement the
“block” solvers in PETSc. There are three ways to provide the
information that defines the blocks. If the matrices are stored as
interlaced then <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSetFields.html#PCFieldSplitSetFields">PCFieldSplitSetFields</a>()</span></code> can be called repeatedly to
indicate which fields belong to each block. More generally
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSetIS.html#PCFieldSplitSetIS">PCFieldSplitSetIS</a>()</span></code> can be used to indicate exactly which
rows/columns of the matrix belong to a particular block. You can provide
names for each block with these routines, if you do not provide names
they are numbered from 0. With these two approaches the blocks may
overlap (though generally they will not). If only one block is defined
then the complement of the matrices is used to define the other block.
Finally the option <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_detect_saddle_point</span></code> causes two
diagonal blocks to be found, one associated with all rows/columns that
have zeros on the diagonals and the rest.</p>
<p>For simplicity in the rest of the section we restrict our matrices to
two by two blocks. So the matrix is</p>
<div class="math">
\[\left( \begin{array}{cc}
A_{00} & A_{01} \\
A_{10} & A_{11} \\
\end{array} \right).\]</div>
<p>On occasion the user may provide another matrix that is used to
construct parts of the preconditioner</p>
<div class="math">
\[\left( \begin{array}{cc}
Ap_{00} & Ap_{01} \\
Ap_{10} & Ap_{11} \\
\end{array} \right).\]</div>
<p>For notational simplicity define <span class="math">\(\text{ksp}(A,Ap)\)</span> to mean
approximately solving a linear system using <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> with operator
<span class="math">\(A\)</span> and preconditioner built from matrix <span class="math">\(Ap\)</span>.</p>
<p>For matrices defined with any number of blocks there are three “block”
algorithms available: block Jacobi,</p>
<div class="math">
\[\left( \begin{array}{cc}
\text{ksp}(A_{00},Ap_{00}) & 0 \\
0 & \text{ksp}(A_{11},Ap_{11}) \\
\end{array} \right)\]</div>
<p>block Gauss-Seidel,</p>
<div class="math">
\[\left( \begin{array}{cc}
I & 0 \\
0 & A^{-1}_{11} \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
-A_{10} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A^{-1}_{00} & 0 \\
0 & I \\
\end{array} \right)\]</div>
<p>which is implemented <a class="footnote-reference brackets" href="#id26" id="id24">3</a> as</p>
<div class="math">
\[\left( \begin{array}{cc}
I & 0 \\
0 & \text{ksp}(A_{11},Ap_{11}) \\
\end{array} \right)
\left[
\left( \begin{array}{cc}
0 & 0 \\
0 & I \\
\end{array} \right)
+
\left( \begin{array}{cc}
I & 0 \\
-A_{10} & -A_{11} \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
0 & 0 \\
\end{array} \right)
\right]
\left( \begin{array}{cc}
\text{ksp}(A_{00},Ap_{00}) & 0 \\
0 & I \\
\end{array} \right)\]</div>
<p>and symmetric block Gauss-Seidel</p>
<div class="math">
\[\left( \begin{array}{cc}
A_{00}^{-1} & 0 \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I & -A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00} & 0 \\
0 & A_{11}^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
-A_{10} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1} & 0 \\
0 & I \\
\end{array} \right).\]</div>
<p>These can be accessed with
<code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_type<additive,multiplicative,</span></code><code class="docutils literal notranslate"><span class="pre">symmetric_multiplicative></span></code>
or the function <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSetType.html#PCFieldSplitSetType">PCFieldSplitSetType</a>()</span></code>. The option prefixes for the
internal KSPs are given by <code class="docutils literal notranslate"><span class="pre">-fieldsplit_name_</span></code>.</p>
<p>By default blocks <span class="math">\(A_{00}, A_{01}\)</span> and so on are extracted out of
<code class="docutils literal notranslate"><span class="pre">Pmat</span></code>, the matrix that the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> uses to build the preconditioner,
and not out of <code class="docutils literal notranslate"><span class="pre">Amat</span></code> (i.e., <span class="math">\(A\)</span> itself). As discussed above in
<a class="reference internal" href="#sec-combining-pcs"><span class="std std-ref">Combining Preconditioners</span></a>, however, it is
possible to use <code class="docutils literal notranslate"><span class="pre">Amat</span></code> instead of <code class="docutils literal notranslate"><span class="pre">Pmat</span></code> by calling
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetUseAmat.html#PCSetUseAmat">PCSetUseAmat</a>(pc)</span></code> or using <code class="docutils literal notranslate"><span class="pre">-pc_use_amat</span></code> on the command line.
Alternatively, you can have <code class="docutils literal notranslate"><span class="pre">PCFieldSplit</span></code> extract the diagonal blocks
<span class="math">\(A_{00}, A_{11}\)</span> etc. out of <code class="docutils literal notranslate"><span class="pre">Amat</span></code> by calling
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSetDiagUseAmat.html#PCFieldSplitSetDiagUseAmat">PCFieldSplitSetDiagUseAmat</a>(pc,<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a>)</span></code> or supplying command-line
argument <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_diag_use_amat</span></code>. Similarly,
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSetOffDiagUseAmat.html#PCFieldSplitSetOffDiagUseAmat">PCFieldSplitSetOffDiagUseAmat</a>(pc,{<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span></code>) or
<code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_off_diag_use_amat</span></code> will cause the off-diagonal blocks
<span class="math">\(A_{01},A_{10}\)</span> etc. to be extracted out of <code class="docutils literal notranslate"><span class="pre">Amat</span></code>.</p>
<p>For two by two blocks only there are another family of solvers, based on
Schur complements. The inverse of the Schur complement factorization is</p>
<div class="math">
\[\left[
\left( \begin{array}{cc}
I & 0 \\
A_{10}A_{00}^{-1} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00} & 0 \\
0 & S \\
\end{array} \right)
\left( \begin{array}{cc}
I & A_{00}^{-1} A_{01} \\
0 & I \\
\end{array} \right)
\right]^{-1}\]</div>
<div class="math">
\[\left( \begin{array}{cc}
I & A_{00}^{-1} A_{01} \\
0 & I \\
\end{array} \right)^{-1}
\left( \begin{array}{cc}
A_{00}^{-1} & 0 \\
0 & S^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
A_{10}A_{00}^{-1} & I \\
\end{array} \right)^{-1}\]</div>
<div class="math">
\[\left( \begin{array}{cc}
I & -A_{00}^{-1} A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1} & 0 \\
0 & S^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
-A_{10}A_{00}^{-1} & I \\
\end{array} \right)\]</div>
<div class="math">
\[\left( \begin{array}{cc}
A_{00}^{-1} & 0 \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I & -A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00} & 0 \\
0 & S^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
-A_{10} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1} & 0 \\
0 & I \\
\end{array} \right).\]</div>
<p>The preconditioner is accessed with <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_type</span> <span class="pre">schur</span></code> and is
implemented as</p>
<div class="math">
\[\left( \begin{array}{cc}
\text{ksp}(A_{00},Ap_{00}) & 0 \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I & -A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
0 & \text{ksp}(\hat{S},\hat{S}p) \\
\end{array} \right)
\left( \begin{array}{cc}
I & 0 \\
-A_{10} \text{ksp}(A_{00},Ap_{00}) & I \\
\end{array} \right).\]</div>
<p>Where
<span class="math">\(\hat{S} = A_{11} - A_{10} \text{ksp}(A_{00},Ap_{00}) A_{01}\)</span> is
the approximate Schur complement.</p>
<p>There are several variants of the Schur complement preconditioner
obtained by dropping some of the terms, these can be obtained with
<code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_schur_fact_type</span> <span class="pre"><diag,lower,upper,full></span></code> or the
function <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSetSchurFactType.html#PCFieldSplitSetSchurFactType">PCFieldSplitSetSchurFactType</a>()</span></code>. Note that the <code class="docutils literal notranslate"><span class="pre">diag</span></code> form
uses the preconditioner</p>
<div class="math">
\[\left( \begin{array}{cc}
\text{ksp}(A_{00},Ap_{00}) & 0 \\
0 & -\text{ksp}(\hat{S},\hat{S}p) \\
\end{array} \right).\]</div>
<p>This is done to ensure the preconditioner is positive definite for a
common class of problems, saddle points with a positive definite
<span class="math">\(A_{00}\)</span>: for these the Schur complement is negative definite.</p>
<p>The effectiveness of the Schur complement preconditioner depends on the
availability of a good preconditioner <span class="math">\(\hat Sp\)</span> for the Schur
complement matrix. In general, you are responsible for supplying
<span class="math">\(\hat Sp\)</span> via
<code class="docutils literal notranslate"><span class="pre">PCFieldSplitSchurPrecondition(pc,<a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFieldSplitSchurPreType.html#PCFieldSplitSchurPreType">PC_FIELDSPLIT_SCHUR_PRE_USER</a>,Sp)</span></code>.
In the absence of a good problem-specific <span class="math">\(\hat Sp\)</span>, you can use
some of the built-in options.</p>
<p>Using <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">user</span></code> on the command line
activates the matrix supplied programmatically as explained above.</p>
<p>With <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">a11</span></code> (default)
<span class="math">\(\hat Sp = A_{11}\)</span> is used to build a preconditioner for
<span class="math">\(\hat S\)</span>.</p>
<p>Otherwise, <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">self</span></code> will set
<span class="math">\(\hat Sp = \hat S\)</span> and use the Schur complement matrix itself to
build the preconditioner.</p>
<p>The problem with the last approach is that <span class="math">\(\hat S\)</span> is used in
unassembled, matrix-free form, and many preconditioners (e.g., ILU)
cannot be built out of such matrices. Instead, you can <em>assemble</em> an
approximation to <span class="math">\(\hat S\)</span> by inverting <span class="math">\(A_{00}\)</span>, but only
approximately, so as to ensure the sparsity of <span class="math">\(\hat Sp\)</span> as much
as possible. Specifically, using
<code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">selfp</span></code> will assemble
<span class="math">\(\hat Sp = A_{11} - A_{10} \text{inv}(A_{00}) A_{01}\)</span>.</p>
<p>By default <span class="math">\(\text{inv}(A_{00})\)</span> is the inverse of the diagonal of
<span class="math">\(A_{00}\)</span>, but using
<code class="docutils literal notranslate"><span class="pre">-fieldsplit_1_mat_schur_complement_ainv_type</span> <span class="pre">lump</span></code> will lump
<span class="math">\(A_{00}\)</span> first. Using
<code class="docutils literal notranslate"><span class="pre">-fieldsplit_1_mat_schur_complement_ainv_type</span> <span class="pre">blockdiag</span></code> will use the
inverse of the block diagonal of <span class="math">\(A_{00}\)</span>. Option
<code class="docutils literal notranslate"><span class="pre">-mat_schur_complement_ainv_type</span></code> applies to any matrix of
<code class="docutils literal notranslate"><span class="pre">MatSchurComplement</span></code> type and here it is used with the prefix
<code class="docutils literal notranslate"><span class="pre">-fieldsplit_1</span></code> of the linear system in the second split.</p>
<p>Finally, you can use the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCLSC.html#PCLSC">PCLSC</a></span></code> preconditioner for the Schur
complement with <code class="docutils literal notranslate"><span class="pre">-pc_fieldsplit_type</span> <span class="pre">schur</span> <span class="pre">-fieldsplit_1_pc_type</span> <span class="pre">lsc</span></code>.
This uses for the preconditioner to <span class="math">\(\hat{S}\)</span> the operator</p>
<div class="math">
\[\text{ksp}(A_{10} A_{01},A_{10} A_{01}) A_{10} A_{00} A_{01} \text{ksp}(A_{10} A_{01},A_{10} A_{01})
\]</div>
<p>which, of course, introduces two additional inner solves for each
application of the Schur complement. The options prefix for this inner
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> is <code class="docutils literal notranslate"><span class="pre">-fieldsplit_1_lsc_</span></code>. Instead of constructing the matrix
<span class="math">\(A_{10} A_{01}\)</span> the user can provide their own matrix. This is
done by attaching the matrix/matrices to the <span class="math">\(Sp\)</span> matrix they
provide with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObjectCompose.html#PetscObjectCompose">PetscObjectCompose</a></span><span class="p">((</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObject.html#PetscObject">PetscObject</a></span><span class="p">)</span><span class="n">Sp</span><span class="p">,</span><span class="s">"LSC_L"</span><span class="p">,(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObject.html#PetscObject">PetscObject</a></span><span class="p">)</span><span class="n">L</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObjectCompose.html#PetscObjectCompose">PetscObjectCompose</a></span><span class="p">((</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObject.html#PetscObject">PetscObject</a></span><span class="p">)</span><span class="n">Sp</span><span class="p">,</span><span class="s">"LSC_Lp"</span><span class="p">,(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscObject.html#PetscObject">PetscObject</a></span><span class="p">)</span><span class="n">Lp</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="solving-singular-systems">
<span id="sec-singular"></span><h2>Solving Singular Systems<a class="headerlink" href="#solving-singular-systems" title="Permalink to this headline">¶</a></h2>
<p>Sometimes one is required to solver singular linear systems. In this
case, the system matrix has a nontrivial null space. For example, the
discretization of the Laplacian operator with Neumann boundary
conditions has a null space of the constant functions. PETSc has tools
to help solve these systems.</p>
<p>First, one must know what the null space is and store it using an
orthonormal basis in an array of PETSc Vecs. The constant functions can
be handled separately, since they are such a common case). Create a
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span></code> object with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpaceCreate.html#MatNullSpaceCreate">MatNullSpaceCreate</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="n">hasconstants</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">dim</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span> <span class="o">*</span><span class="n">basis</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span> <span class="o">*</span><span class="n">nsp</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">dim</span></code> is the number of vectors in <code class="docutils literal notranslate"><span class="pre">basis</span></code> and <code class="docutils literal notranslate"><span class="pre">hasconstants</span></code>
indicates if the null space contains the constant functions. If the null
space contains the constant functions you do not need to include it in
the <code class="docutils literal notranslate"><span class="pre">basis</span></code> vectors you provide, nor in the count <code class="docutils literal notranslate"><span class="pre">dim</span></code>.</p>
<p>One then tells the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span></code> object you are using what the null space is
with the call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetNullSpace.html#MatSetNullSpace">MatSetNullSpace</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">Amat</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span> <span class="n">nsp</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetTransposeNullSpace.html#MatSetTransposeNullSpace">MatSetTransposeNullSpace</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/Mat.html#Mat">Mat</a></span> <span class="n">Amat</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatNullSpace.html#MatNullSpace">MatNullSpace</a></span> <span class="n">nsp</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">Amat</span></code> should be the <em>first</em> matrix argument used with
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</a>()</span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/SNES/SNESSetJacobian.html#SNESSetJacobian">SNESSetJacobian</a>()</span></code>, or <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/TS/TSSetIJacobian.html#TSSetIJacobian">TSSetIJacobian</a>()</span></code>.
You can also use <code class="docutils literal notranslate"><span class="pre">KSPSetNullspace()</span></code>. The PETSc solvers will now
handle the null space during the solution process.</p>
<p>If one chooses a direct solver (or an incomplete factorization) it may
still detect a zero pivot. You can run with the additional options or
<code class="docutils literal notranslate"><span class="pre">-pc_factor_shift_type</span> <span class="pre">NONZERO</span></code>
<code class="docutils literal notranslate"><span class="pre">-pc_factor_shift_amount</span>  <span class="pre"><dampingfactor></span></code> to prevent the zero pivot.
A good choice for the <code class="docutils literal notranslate"><span class="pre">dampingfactor</span></code> is 1.e-10.</p>
</div>
<div class="section" id="using-external-linear-solvers">
<span id="sec-externalsol"></span><h2>Using External Linear Solvers<a class="headerlink" href="#using-external-linear-solvers" title="Permalink to this headline">¶</a></h2>
<p>PETSc interfaces to several external linear solvers (also see <a class="reference internal" href="acknowledgements.html#chapter-acknowledgements"><span class="std std-ref">Acknowledgments</span></a>)
at the beginning of this manual). To use these solvers, one may:</p>
<ol class="arabic simple">
<li><p>Run <code class="docutils literal notranslate"><span class="pre">./configure</span></code> with the additional options
<code class="docutils literal notranslate"><span class="pre">--download-packagename</span></code> e.g. <code class="docutils literal notranslate"><span class="pre">--download-superlu_dist</span></code>
<code class="docutils literal notranslate"><span class="pre">--download-parmetis</span></code> (SuperLU_DIST needs ParMetis) or
<code class="docutils literal notranslate"><span class="pre">--download-mumps</span></code> <code class="docutils literal notranslate"><span class="pre">--download-scalapack</span></code> (MUMPS requires
ScaLAPACK).</p></li>
<li><p>Build the PETSc libraries.</p></li>
<li><p>Use the runtime option: <code class="docutils literal notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> <code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre"><pctype></span></code>
<code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_solver_type</span> <span class="pre"><packagename></span></code>. For eg:
<code class="docutils literal notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> <code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">lu</span></code>
<code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_solver_type</span> <span class="pre">superlu_dist</span></code>.</p></li>
</ol>
<table class="docutils align-default" id="tab-externaloptions">
<caption><span class="caption-number">Table 6 </span><span class="caption-text">Options for External Solvers</span><a class="headerlink" href="#tab-externaloptions" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 25%" />
<col style="width: 25%" />
<col style="width: 25%" />
<col style="width: 25%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>MatType</p></th>
<th class="head"><p>PCType</p></th>
<th class="head"><p>MatSolverType</p></th>
<th class="head"><p>Package (<code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_solver_type</span></code>)</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERESSL.html#MATSOLVERESSL">MATSOLVERESSL</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">essl</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERLUSOL.html#MATSOLVERLUSOL">MATSOLVERLUSOL</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lusol</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMATLAB.html#MATSOLVERMATLAB">MATSOLVERMATLAB</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">matlab</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMUMPS.html#MATSOLVERMUMPS">MATSOLVERMUMPS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">mumps</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">sbaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERSUPERLU.html#MATSOLVERSUPERLU">MATSOLVERSUPERLU</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">superlu</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERSUPERLU_DIST.html#MATSOLVERSUPERLU_DIST">MATSOLVERSUPERLU_DIST</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">superlu_dist</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERUMFPACK.html#MATSOLVERUMFPACK">MATSOLVERUMFPACK</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">umfpack</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERCHOLMOD.html#MATSOLVERCHOLMOD">MATSOLVERCHOLMOD</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholmod</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">MATSOLVERCLIQUE</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">clique</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERKLU.html#MATSOLVERKLU">MATSOLVERKLU</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">klu</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">dense</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">MATSOLVERELEMENTAL</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">elemental</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">dense</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMKL_PARDISO.html#MATSOLVERMKL_PARDISO">MATSOLVERMKL_PARDISO</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">mkl_pardiso</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">MATSOLVERMKL_CPARDISO</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">mkl_cpardiso</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERPASTIX.html#MATSOLVERPASTIX">MATSOLVERPASTIX</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pastix</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERBAS.html#MATSOLVERBAS">MATSOLVERBAS</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bas</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aijcusparse</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERCUSPARSE.html#MATSOLVERCUSPARSE">MATSOLVERCUSPARSE</a></span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cusparse</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aijcusparse</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">lu</span></code>, <code class="docutils literal notranslate"><span class="pre">cholesky</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">MATSOLVERPETSC</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">petsc</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">baij</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aijcrl</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aijperm</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">seqdense</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aij</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">baij</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">aijcrl</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aijperm</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">seqdense</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>The default and available input options for each external software can
be found by specifying <code class="docutils literal notranslate"><span class="pre">-help</span></code> at runtime.</p>
<p>As an alternative to using runtime flags to employ these external
packages, procedural calls are provided for some packages. For example,
the following procedural calls are equivalent to runtime options
<code class="docutils literal notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> <code class="docutils literal notranslate"><span class="pre">-pc_type</span> <span class="pre">lu</span></code>
<code class="docutils literal notranslate"><span class="pre">-pc_factor_mat_solver_type</span> <span class="pre">mumps</span></code> <code class="docutils literal notranslate"><span class="pre">-mat_mumps_icntl_7</span> <span class="pre">2</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetType.html#KSPSetType">KSPSetType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPPREONLY.html#KSPPREONLY">KSPPREONLY</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGetPC.html#KSPGetPC">KSPGetPC</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="o">&</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetType.html#PCSetType">PCSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCLU.html#PCLU">PCLU</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetMatSolverType.html#PCFactorSetMatSolverType">PCFactorSetMatSolverType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMUMPS.html#MATSOLVERMUMPS">MATSOLVERMUMPS</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorGetMatrix.html#PCFactorGetMatrix">PCFactorGetMatrix</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="o">&</span><span class="n">F</span><span class="p">);</span>
<span class="n">icntl</span><span class="o">=</span><span class="mi">7</span><span class="p">;</span> <span class="n">ival</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatMumpsSetIcntl.html#MatMumpsSetIcntl">MatMumpsSetIcntl</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="n">icntl</span><span class="p">,</span><span class="n">ival</span><span class="p">);</span>
</pre></div>
</div>
<p>One can also create matrices with the appropriate capabilities by
calling <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreate.html#MatCreate">MatCreate</a>()</span></code> followed by <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetType.html#MatSetType">MatSetType</a>()</span></code> specifying the
desired matrix type from <a class="reference internal" href="#tab-externaloptions"><span class="std std-ref">Options for External Solvers</span></a>. These
matrix types inherit capabilities from their PETSc matrix parents:
<code class="docutils literal notranslate"><span class="pre">seqaij</span></code>, <code class="docutils literal notranslate"><span class="pre">mpiaij</span></code>, etc. As a result, the preallocation routines
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSeqAIJSetPreallocation.html#MatSeqAIJSetPreallocation">MatSeqAIJSetPreallocation</a>()</span></code>, <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatMPIAIJSetPreallocation.html#MatMPIAIJSetPreallocation">MatMPIAIJSetPreallocation</a>()</span></code>, etc.
and any other type specific routines of the base class are supported.
One can also call <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatConvert.html#MatConvert">MatConvert</a>()</span></code> inplace to convert the matrix to and
from its base class without performing an expensive data copy.
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatConvert.html#MatConvert">MatConvert</a>()</span></code> cannot be called on matrices that have already been
factored.</p>
<p>In <a class="reference internal" href="#tab-externaloptions"><span class="std std-ref">Options for External Solvers</span></a>, the base class <code class="docutils literal notranslate"><span class="pre">aij</span></code> refers
to the fact that inheritance is based on <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSEQAIJ.html#MATSEQAIJ">MATSEQAIJ</a></span></code> when constructed
with a single process communicator, and from <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATMPIAIJ.html#MATMPIAIJ">MATMPIAIJ</a></span></code> otherwise.
The same holds for <code class="docutils literal notranslate"><span class="pre">baij</span></code> and <code class="docutils literal notranslate"><span class="pre">sbaij</span></code>. For codes that are intended
to be run as both a single process or with multiple processes, depending
on the <code class="docutils literal notranslate"><span class="pre">mpiexec</span></code> command, it is recommended that both sets of
preallocation routines are called for these communicator morphing types.
The call for the incorrect type will simply be ignored without any harm
or message.</p>
<hr><dl class="footnote brackets">
<dt class="label" id="id25"><span class="brackets"><a class="fn-backref" href="#id22">2</a></span></dt>
<dd><p>See <a class="reference internal" href="#sec-amg"><span class="std std-ref">Algebraic Multigrid (AMG) Preconditioners</span></a> for information on using algebraic multigrid.</p>
</dd>
<dt class="label" id="id26"><span class="brackets"><a class="fn-backref" href="#id24">3</a></span></dt>
<dd><p>This may seem an odd way to implement since it involves the “extra”
multiply by <span class="math">\(-A_{11}\)</span>. The reason is this is implemented this
way is that this approach works for any number of blocks that may
overlap.</p>
</dd>
</dl>
<hr><p id="id27"><dl class="citation">
<dt class="label" id="id218"><span class="brackets"><a class="fn-backref" href="#id20">CS97</a></span></dt>
<dd><p>X.-C. Cai and M. Sarkis. A restricted additive Schwarz preconditioner for general sparse linear systems. Technical Report CU-CS 843-97, Computer Science Department, University of Colorado-Boulder, 1997. (accepted by SIAM J. of Scientific Computing).</p>
</dd>
<dt class="label" id="id278"><span class="brackets"><a class="fn-backref" href="#id19">Eis81</a></span></dt>
<dd><p>S. Eisenstat. Efficient implementation of a class of CG methods. <em>SIAM J. Sci. Stat. Comput.</em>, 2:1–4, 1981.</p>
</dd>
<dt class="label" id="id726"><span class="brackets"><a class="fn-backref" href="#id14">EES83</a></span></dt>
<dd><p>S.C. Eisenstat, H.C. Elman, and M.H. Schultz. Variational iterative methods for nonsymmetric systems of linear equations. <em>SIAM Journal on Numerical Analysis</em>, 20(2):345–357, 1983.</p>
</dd>
<dt class="label" id="id273"><span class="brackets"><a class="fn-backref" href="#id1">FGN92</a></span></dt>
<dd><p>R. Freund, G. H. Golub, and N. Nachtigal. <em>Iterative Solution of Linear Systems</em>, pages 57–100. Acta Numerica. Cambridge University Press, 1992.</p>
</dd>
<dt class="label" id="id322"><span class="brackets"><a class="fn-backref" href="#id17">Fre93</a></span></dt>
<dd><p>Roland W. Freund. A transpose-free quasi-minimal residual algorithm for non-Hermitian linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 14:470–482, 1993.</p>
</dd>
<dt class="label" id="id838"><span class="brackets"><a class="fn-backref" href="#id12">GAMV13</a></span></dt>
<dd><p>P. Ghysels, T.J. Ashby, K. Meerbergen, and W. Vanroose. Hiding global communication latency in the GMRES algorithm on massively parallel machines. <em>SIAM Journal on Scientific Computing</em>, 35(1):C48–C71, 2013.</p>
</dd>
<dt class="label" id="id839"><span class="brackets"><a class="fn-backref" href="#id5">GV14</a></span></dt>
<dd><p>P. Ghysels and W. Vanroose. Hiding global synchronization latency in the preconditioned conjugate gradient algorithm. <em>Parallel Computing</em>, 40(7):224–238, 2014. 7th Workshop on Parallel Matrix Algorithms and Applications. <a class="reference external" href="https://doi.org/10.1016/j.parco.2013.06.001">doi:10.1016/j.parco.2013.06.001</a>.</p>
</dd>
<dt class="label" id="id318"><span class="brackets"><a class="fn-backref" href="#id4">HS52</a></span></dt>
<dd><p>Magnus R. Hestenes and Eduard Steifel. Methods of conjugate gradients for solving linear systems. <em>J. Research of the National Bureau of Standards</em>, 49:409–436, 1952.</p>
</dd>
<dt class="label" id="id1060"><span class="brackets"><a class="fn-backref" href="#id21">ISG15</a></span></dt>
<dd><p>Tobin Isaac, Georg Stadler, and Omar Ghattas. Solution of nonlinear Stokes equations discretized by high-order finite elements on nonconforming and anisotropic meshes, with application to ice sheet dynamics. <em>SIAM J. Sci. Comput.</em>, 37(6):804–833, 2015.</p>
</dd>
<dt class="label" id="id918"><span class="brackets"><a class="fn-backref" href="#id6">Not00</a></span></dt>
<dd><p>Yvan Notay. Flexible Conjugate Gradients. <em>SIAM Journal on Scientific Computing</em>, 22(4):1444–1460, 2000.</p>
</dd>
<dt class="label" id="id1126"><span class="brackets">PS75</span><span class="fn-backref">(<a href="#id9">1</a>,<a href="#id18">2</a>)</span></dt>
<dd><p>C. C. Paige and M. A. Saunders. Solution of sparse indefinite systems of linear equations. <em>SIAM Journal on Numerical Analysis</em>, 12:617–629, 1975.</p>
</dd>
<dt class="label" id="id713"><span class="brackets"><a class="fn-backref" href="#id11">Saa93</a></span></dt>
<dd><p>Youcef Saad. A flexible inner-outer preconditioned GMRES algorithm. <em>SIAM Journal on Scientific Computing</em>, 14(2):461–469, 1993. <a class="reference external" href="https://doi.org/10.1137/0914028">doi:10.1137/0914028</a>.</p>
</dd>
<dt class="label" id="id319"><span class="brackets"><a class="fn-backref" href="#id10">SS86</a></span></dt>
<dd><p>Youcef Saad and Martin H. Schultz. GMRES: a generalized minimal residual algorithm for solving nonsymmetric linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 7:856–869, 1986.</p>
</dd>
<dt class="label" id="id389"><span class="brackets"><a class="fn-backref" href="#id3">Saa03</a></span></dt>
<dd><p>Yousef Saad. <em>Iterative Methods for Sparse Linear Systems</em>. SIAM, 2nd edition, 2003. <a class="reference external" href="https://doi.org/10.1016/S1570-579X(01)80025-2">doi:10.1016/S1570-579X(01)80025-2</a>.</p>
</dd>
<dt class="label" id="id320"><span class="brackets"><a class="fn-backref" href="#id16">Son89</a></span></dt>
<dd><p>Peter Sonneveld. CGS, a fast Lanczos-type solver for nonsymmetric linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 10:36–52, 1989.</p>
</dd>
<dt class="label" id="id1274"><span class="brackets"><a class="fn-backref" href="#id2">vdV03</a></span></dt>
<dd><p>H. van der Vorst. <em>Iterative Krylov Methods for Large Linear Systems</em>. Cambridge University Press, 2003. ISBN 9780521818285.</p>
</dd>
<dt class="label" id="id321"><span class="brackets"><a class="fn-backref" href="#id8">vandVorst92</a></span></dt>
<dd><p>H. A. van der Vorst. BiCGSTAB: a fast and smoothly converging variant of BiCG for the solution of nonsymmetric linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 13:631–644, 1992.</p>
</dd>
</dl>
</p>
<p id="id1277"><dl class="citation">
<dt class="label" id="id2112"><span class="brackets">SSM16</span><span class="fn-backref">(<a href="#id7">1</a>,<a href="#id13">2</a>,<a href="#id15">3</a>)</span></dt>
<dd><p>P. Sanan, S. M. Schnepp, and D. A. May. Pipelined, flexible Krylov subspace methods. <em>SIAM Journal on Scientific Computing</em>, 38(5):C441–C470, 2016. <a class="reference external" href="https://doi.org/10.1137/15M1049130">doi:10.1137/15M1049130</a>.</p>
</dd>
<dt class="label" id="id2058"><span class="brackets"><a class="fn-backref" href="#id23">SBjorstadG96</a></span></dt>
<dd><p>Barry F. Smith, Petter Bjørstad, and William D. Gropp. <em>Domain Decomposition: Parallel Multilevel Methods for Elliptic Partial Differential Equations</em>. Cambridge University Press, 1996. URL: <a class="reference external" href="http://www.mcs.anl.gov/~bsmith/ddbook.html">http://www.mcs.anl.gov/~bsmith/ddbook.html</a>.</p>
</dd>
</dl>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="snes.html" title="SNES: Nonlinear Solvers"
>next</a> |</li>
<li class="right" >
<a href="mat.html" title="Matrices"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">PETSc 3.14.5 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >PETSc Users Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="programming.html" >Programming with PETSc</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 1991-2021, UChicago Argonne, LLC and the PETSc Development Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>
|
