xref: /libCEED/examples/petsc/README.md (revision ba59ac12ef3579eea938de09e332a3a266c3cc08) ! 
1## libCEED + PETSc Examples
2
3PETSc v3.17 or a development version of PETSc at commit 0e95d842 or later is required.
4
5### CEED bakeoff problems with raw mesh management - bpsraw
6
7This code solves the CEED bakeoff problems on a structured grid generated and referenced using only low-level communication primitives.
8
9To build, run `make bpsraw`
10
11To run, `./bpsraw -ceed [ceed-resource] -problem bp[1-6] -degree [degree]`
12
13In addition to the common arguments, the following arguments may be set:
14
15- `-local`             - Target number of locally owned DoFs per process
16
17### CEED bakeoff problems with DMPlex - bps
18
19This code solves the CEED bakeoff problems on a unstructured grid using DMPlex.
20This example requires a PETSc version later than 3.11.3.
21
22To build, run `make bps`
23
24To run, `./bps -ceed [ceed-resource] -problem bp[1-6] -degree [degree]`
25
26In addition to the common arguments, the following arguments may be set:
27
28- `-mesh`              - Read mesh from file
29- `-cells`             - Number of cells per dimension
30
31#### Running a suite
32
33Some run-time arguments can be passed lists, which allows a single `mpiexec` invocation to run many experiments.
34For example
35
36    mpiexec -n 64 ./bps -problem bp1,bp2,bp3,bp4 -degree 2,3,5,7                \
37        -ceed /cpu/self/opt/serial,/cpu/self/xsmm/serial,/cpu/self/xsmm/blocked \
38        -local_nodes 600,20000 | tee bps.log
39
40which will sample from the `4*4*3=48` specified combinations, each of which will run a problem-size sweep of 600, 1200, 2400, 4800, 9600, 192000 FEM nodes per MPI rank.
41The resulting log file can be read by the Python plotting scripts in `benchmarks/`.
42
43### CEED bakeoff problems with DMPlex and PCMG - multigrid
44
45This code solves the CEED bakeoff problems on a unstructured grid using DMPlex with p-multigrid implemented in PCMG.
46This example requires a PETSc version later than 3.11.3.
47
48To build, run `make multigrid`
49
50To run, `./multigrid -ceed [ceed-resource] -problem bp[1-6] -degree [degree]`
51
52In addition to the common arguments, the following arguments may be set:
53
54- `-mesh`              - Read mesh from file
55- `-cells`             - Number of cells per dimension
56
57### Command line arguments
58
59The following arguments can be specified for all of the above examples:
60
61- `-ceed`              - CEED resource specifier
62- `-problem`           - CEED benchmark problem to solve
63- `-degree`            - Polynomial degree of tensor product basis
64- `-q_extra`           - Number of extra quadrature points
65- `-test`              - Testing mode (do not print unless error is large)
66- `-benchmark`         - Benchmarking mode (prints benchmark statistics)
67
68### libCEED example to compute surface area using DMPlex - area
69
70This example uses the mass matrix to compute the surface area of a cube or a discrete cubed-sphere, defined via DMPlex.
71
72To build, run `make area`
73
74To run, `./area -problem cube -ceed [ceed-resource] -petscspace_degree [degree]`
75
76or
77
78`./area -problem sphere -ceed [ceed-resource] -petscspace_degree [degree]`
79
80#### Command line arguments
81
82The following arguments can be specified for the area example:
83
84- `-ceed`              - CEED resource specifier
85- `-problem`           - Problem to solve, either 'cube' or 'sphere'
86- `-petscspace_degree` - Polynomial degree of tensor product basis
87- `-q_extra`           - Number of extra quadrature points
88- `-test`              - Testing mode (do not print unless error is large)
89- `-mesh`              - Read mesh from file
90
91