petsc-master 2020-11-28
Report Typos and Errors

## KSP

• solving a system of linear equations Solves a tridiagonal linear system with KSP.
• solving a system of linear equations Solves a linear system in parallel with KSP,
demonstrating how to register a new preconditioner (PC) type.
Input parameters include:
-m <mesh_x> : number of mesh points in x-direction
-n <mesh_y> : number of mesh points in y-direction
• solving a system of linear equations
Description: Solves a tridiagonal linear system with KSP.

• solving a system of linear equations Solves 2D inhomogeneous Laplacian using multigrid.
• solving a system of linear equations Solves 2D inhomogeneous Laplacian using multigrid.
• solving a system of linear equations Solves 3D Laplacian using multigrid.
• solving a system of linear equations
Description: Solve Ax=b. A comes from an anisotropic 2D thermal problem with Q1 FEM on domain (-1,1)^2.
Material conductivity given by tensor:

D = | 1 0 |
| 0 epsilon |

rotated by angle 'theta' (-theta <90> in degrees) with anisotropic parameter 'epsilon' (-epsilon <0.0>).
Blob right hand side centered at C (-blob_center C(1),C(2) <0,0>)
Dirichlet BCs on y=-1 face.

-out_matlab will generate binary files for A,x,b and a ex54f.m file that reads them and plots them in matlab.

User can change anisotropic shape with function ex54_psi(). Negative theta will switch to a circular anisotropy.

• solving a system of linear equations Solves 2D inhomogeneous Laplacian. Demonstates using PCTelescopeSetCoarseDM functionality of PCTelescope via a DMShell
• basic parallel example; single
single
single
single
• basic parallel example; Solves a linear system in parallel with KSP.
Input parameters include:
-view_exact_sol : write exact solution vector to stdout
-m <mesh_x> : number of mesh points in x-direction
-n <mesh_y> : number of mesh points in y-direction
• basic parallel example; Solves a tridiagonal linear system.
• basic parallel example; Solves a linear system in parallel with KSP and DM.
Compare this to ex2 which solves the same problem without a DM.
• Laplacian, 2d Solves a linear system in parallel with KSP,
demonstrating how to register a new preconditioner (PC) type.
Input parameters include:
-m <mesh_x> : number of mesh points in x-direction
-n <mesh_y> : number of mesh points in y-direction
• Laplacian, 2d Solves a variable Poisson problem with KSP.
• Laplacian, 2d

• Laplacian, 2d Solves a sequence of linear systems with different right-hand-side vectors.
Input parameters include:
-ntimes <ntimes> : number of linear systems to solve
-view_exact_sol : write exact solution vector to stdout
-m <mesh_x> : number of mesh points in x-direction
-n <mesh_y> : number of mesh points in y-direction
• Laplacian, 2d single
single
single
single
• Laplacian, 2d Solves a linear system in parallel with KSP.
Input parameters include:
-view_exact_sol : write exact solution vector to stdout
-m <mesh_x> : number of mesh points in x-direction
-n <mesh_y> : number of mesh points in y-direction
• Laplacian, 2d Solves 2D inhomogeneous Laplacian using multigrid.
• Laplacian, 2d Solves 2D inhomogeneous Laplacian using multigrid.
• Laplacian, 2d Solves a linear system in parallel with KSP and DM.
Compare this to ex2 which solves the same problem without a DM.
• Laplacian, 2d Solves 2D inhomogeneous Laplacian. Demonstates using PCTelescopeSetCoarseDM functionality of PCTelescope via a DMShell
• basic parallel example Solve a small system and a large system through preloading
Input arguments are:
-f0 <small_sys_binary> -f1 <large_sys_binary>
• basic parallel example Solves a linear system in parallel with KSP. Also
illustrates setting a user-defined shell preconditioner and using the
Input parameters include:
-user_defined_pc : Activate a user-defined preconditioner
• basic parallel example
Solves a linear system in parallel with KSP. Also indicates
use of a user-provided preconditioner. Input parameters include:
-user_defined_pc : Activate a user-defined preconditioner

• basic parallel example
Description: Solves a linear system in parallel with KSP (Fortran code).
Also shows how to set a user-defined monitoring routine.

• basic parallel example Bilinear elements on the unit square for Laplacian. To test the parallel
matrix assembly, the matrix is intentionally laid out across processors
differently from the way it is assembled. Input arguments are:
-m <size> : problem size
• basic parallel example Krylov methods to solve u'' = f in parallel with periodic boundary conditions,
with a singular, inconsistent system.
• repeatedly solving linear systems; Solves a sequence of linear systems with different right-hand-side vectors.
Input parameters include:
-ntimes <ntimes> : number of linear systems to solve
-view_exact_sol : write exact solution vector to stdout
-m <mesh_x> : number of mesh points in x-direction
-n <mesh_y> : number of mesh points in y-direction
• repeatedly solving linear systems; Solves two linear systems in parallel with KSP. The code
illustrates repeated solution of linear systems with the same preconditioner
method but different matrices (having the same nonzero structure). The code
also uses multiple profiling stages. Input arguments are
-m <size> : problem size
-mat_nonsym : use nonsymmetric matrix (default is symmetric)
• repeatedly solving linear systems; Solves two linear systems in parallel with KSP. The code
illustrates repeated solution of linear systems with the same preconditioner
method but different matrices (having the same nonzero structure). The code
also uses multiple profiling stages. Input arguments are
-m <size> : problem size
-mat_nonsym : use nonsymmetric matrix (default is symmetric)
• repeatedly solving linear systems;
Description: This example demonstrates repeated linear solves as
well as the use of different preconditioner and linear system
matrices. This example also illustrates how to save PETSc objects
in common blocks.

• repeatedly solving linear systems; The solution of 2 different linear systems with different linear solvers.
Also, this example illustrates the repeated
solution of linear systems, while reusing matrix, vector, and solver data
structures throughout the process. Note the various stages of event logging.
• customizing the block Jacobi preconditioner Block Jacobi preconditioner for solving a linear system in parallel with KSP.
The code indicates the
procedures for setting the particular block sizes and for using different
linear solvers on the individual blocks.
• customizing the block Jacobi preconditioner Block Jacobi preconditioner for solving a linear system in parallel with KSP
The code indicates the procedures for setting the particular block sizes and
for using different linear solvers on the individual blocks
This example focuses on ways to customize the block Jacobi preconditioner.
See ex1.c and ex2.c for more detailed comments on the basic usage of KSP
(including working with matrices and vectors)
Recall: The block Jacobi method is equivalent to the ASM preconditioner with zero overlap.
• Additive Schwarz Method (ASM) with user-defined subdomains Illustrates use of the preconditioner ASM.
The Additive Schwarz Method for solving a linear system in parallel with KSP. The
code indicates the procedure for setting user-defined subdomains. Input
parameters include:
-user_set_subdomain_solvers: User explicitly sets subdomain solvers
-user_set_subdomains: Activate user-defined subdomains
• solving a Helmholtz equation Solves a linear system in parallel with KSP.
• solving a Helmholtz equation
Description: Solves a complex linear system in parallel with KSP (Fortran code).

• basic sequential example Solves a variable Poisson problem with KSP.
• basic sequential example

• solving a linear system Reads a PETSc matrix and vector from a file and solves the normal equations.
• solving a linear system Reads a PETSc matrix and vector from a socket connection, solves a linear system and sends the result back.
• solving a linear system Reads a PETSc matrix and vector from a file and solves a linear system.
another (larger) system and solves it as well. This example illustrates
performance monitoring can be done with the larger one (that actually
is the system of interest). See the 'Performance Hints' chapter of the
-f0 <input_file> : first file to load (small system)
-f1 <input_file> : second file to load (larger system)
-nearnulldim <0> : number of vectors in the near-null space immediately following matrix
-trans : solve transpose system instead
• Laplacian, 3d Solves 3D Laplacian using multigrid.
• Additive Schwarz Method (GASM) with user-defined subdomains Illustrates use of PCGASM.
The Generalized Additive Schwarz Method for solving a linear system in parallel with KSP. The
code indicates the procedure for setting user-defined subdomains.
See section 'ex62' below for command-line options.
Without -user_set_subdomains, the general PCGASM options are meaningful:
-pc_gasm_total_subdomains
-pc_gasm_print_subdomains

• Additive Schwarz Method (GASM) with user-defined subdomains Illustrates use of the preconditioner GASM.
using hierarchical partitioning and MatIncreaseOverlapSplit -pc_gasm_total_subdomains
-pc_gasm_print_subdomains
• ex74.c Solves the constant-coefficient 1D heat equation
with an Implicit Runge-Kutta method using MatKAIJ.

du d^2 u
-- = a ----- ; 0 <= x <= 1;
dt dx^2

with periodic boundary conditions

2nd order central discretization in space:

[ d^2 u ] u_{i+1} - 2u_i + u_{i-1}
[ ----- ] = ------------------------
[ dx^2 ]i h^2

i = grid index; h = x_{i+1}-x_i (Uniform)
0 <= i < n h = 1.0/n

Thus,

du
-- = Ju; J = (a/h^2) tridiagonal(1,-2,1)_n
dt

Implicit Runge-Kutta method:

U^(k) = u^n + dt \\sum_i a_{ki} JU^{i}
u^{n+1} = u^n + dt \\sum_i b_i JU^{i}

i = 1,...,s (s -> number of stages)

At each time step, we solve

[ 1 ] 1
[ -- I \\otimes A^{-1} - J \\otimes I ] U = -- u^n \\otimes A^{-1}
[ dt ] dt

where A is the Butcher tableaux of the implicit
Runge-Kutta method,

with MATKAIJ and KSP.

Available IRK Methods:
gauss n-stage Gauss method

• setting a user-defined monitoring routine
Description: Solves a linear system in parallel with KSP (Fortran code).
Also shows how to set a user-defined monitoring routine.

• different matrices for linear system and preconditioner;
Description: This example demonstrates repeated linear solves as
well as the use of different preconditioner and linear system
matrices. This example also illustrates how to save PETSc objects
in common blocks.

• writing a user-defined nonlinear solver

Solves a nonlinear system in parallel with a user-defined
Newton method that uses KSP to solve the linearized Newton sytems. This solver
is a very simplistic inexact Newton method. The intent of this code is to
demonstrate the repeated solution of linear sytems with the same nonzero pattern.

This is NOT the recommended approach for solving nonlinear problems with PETSc!
We urge users to employ the SNES component for solving nonlinear problems whenever
possible, as it offers many advantages over coding nonlinear solvers independently.

We solve the Bratu (SFI - solid fuel ignition) problem in a 2D rectangular
domain, using distributed arrays (DMDAs) to partition the parallel grid.