Skip to content

Commit fd37b90

Browse files
baagaard-usgsbaagaard-usgs
committed
DOCS: Add discussion of Field::view() to developer guide,
1 parent 10499a7 commit fd37b90

File tree

1 file changed

+280
-77
lines changed

1 file changed

+280
-77
lines changed

‎docs/developer/implementation/petsc-fem.md‎

Lines changed: 280 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,12 @@ This means the "boundary" cells are at a height of 1 and a depth equal to the ma
4646
Conventional numbering (left) with vertices and cells numbered independently and `DMPlex` numbering (right) with cells, vertices, edges, (and faces), numbered sequentially.
4747
:::
4848

49-
(sec-developer-petsc-section)=
50-
## `PetscSection` and `PetscVec`
49+
(sec-developer-pylith-field)=
50+
## `pylith::topology::Field`, `PetscSection`, and `PetscVec`
51+
52+
A PyLith `Field` (`pylith::topology::Field`) is composed of a `PetscSection`, which associates the points (vertices, edges, faces, and cells) with the finite-element coefficients, and a `PetscVec`, which is a vector storing the finite-element coefficients.
53+
A `Field` may hold a single subfield, such as displacement, or it may hold several subfields, such as the density, shear modulus, and bulk modulus for an isotropic, linear elastic material.
5154

52-
We store a field over the mesh in a vector (PETSc `Vec` object, called `PetscVec` in PyLith).
53-
The `PetscSection` object describes the layout of the vector over the DMPlex object.
54-
The vector may hold multiple subfields, each with its own discretization.
5555
The chart of the `PetscSection` defines the range of points (minimum and maximum) over which the section is defined.
5656
For each point in the chart, the section holds the number of degrees of freedom a point has and the offset in the `PetscVec` for its first degree of freedom.
5757
The section also holds the number of degrees of freedom and offset for each individual subfield within the section for each point in the chart.
@@ -69,84 +69,287 @@ Constraints often arise from Dirichlet boundary conditions, which change the bas
6969
A local vector is used for assembly of the residual vector and Jacobian matrix, because we need the boundary values in order to compute those integrals.
7070
Global vectors are used for the algebraic solver because we do not want solution values fixed by constraints to participate in the solve.
7171

72+
The `Field::view()` method will print the `Field` metadata and the `PetscSection` in a more useful format compared to the corresponding PETSc viewer functions.
73+
74+
% ./mmstest_linearelasticity_faults2d OneFaultShearNoSlip::QuadQ1::testResidual --journal.debug=timedependent
75+
```{code-block} bash
76+
---
77+
caption: Output from `pylith::topology::Field::view()` for a solution field with two subfields showing only the sections (layout of the field). The displacement subfield has degrees of freedom on the vertices of the bulk cells. The lagrange_multiplier_fault subfield has degrees of freedom on the edges of the cohesive cells. The order of the values (offsets in the PetscVec) follows the ordering of the points (cells, vertices, edges, and faces). The local section includes the constrained degrees of freedom, whereas the global section does not. The sections list the point and then the degree of freedom associated with the components of the fields.
78+
---
79+
Viewing field 'DM_0x84000000_1 solution' Solution field.
80+
Subfields:
81+
Subfield displacement, index: 0, components: displacement_x displacement_y, scale: 1000, basisOrder: 1, quadOrder: 1, dimension: -1, cellBasis: tensor
82+
Subfield lagrange_multiplier_fault, index: 1, components: lagrange_multiplier_fault_x lagrange_multiplier_fault_y, scale: 2.25e+10, basisOrder: 1, quadOrder: 1, dimension: 1, cellBasis: tensor
83+
displacement lagrange_multiplier_fault
84+
Local Section
85+
Processor 0
86+
0 -- -- -- -- # cells
87+
1 -- -- -- --
88+
2 -- -- -- --
89+
3 -- -- -- --
90+
4 -- -- -- --
91+
5 -- -- -- --
92+
6 -- -- -- --
93+
7 -- -- -- --
94+
8 -- -- -- --
95+
9 -- -- -- --
96+
10 -- -- -- --
97+
11 -- -- -- --
98+
12 24 25 -- -- (constrained: 24 25) # vertices
99+
13 26 27 -- -- (constrained: 26 27)
100+
14 28 29 -- -- (constrained: 28 29)
101+
15 30 31 -- -- (constrained: 30 31)
102+
16 32 33 -- --
103+
17 34 35 -- --
104+
18 36 37 -- --
105+
19 38 39 -- --
106+
20 40 41 -- -- (constrained: 40 41)
107+
21 42 43 -- -- (constrained: 42 43)
108+
22 44 45 -- -- (constrained: 44 45)
109+
23 46 47 -- -- (constrained: 46 47)
110+
24 0 1 -- --
111+
25 2 3 -- --
112+
26 6 7 -- --
113+
27 8 9 -- --
114+
28 12 13 -- --
115+
29 14 15 -- --
116+
30 18 19 -- --
117+
31 20 21 -- --
118+
32 -- -- -- -- # edges
119+
33 -- -- -- --
120+
34 -- -- -- --
121+
35 -- -- -- --
122+
36 -- -- -- --
123+
37 -- -- -- --
124+
38 -- -- -- --
125+
39 -- -- -- --
126+
40 -- -- -- --
127+
41 -- -- -- --
128+
42 -- -- -- --
129+
43 -- -- -- --
130+
44 -- -- -- --
131+
45 -- -- -- --
132+
46 -- -- -- --
133+
47 -- -- -- --
134+
48 -- -- -- --
135+
49 -- -- -- --
136+
50 -- -- -- --
137+
51 -- -- -- --
138+
52 -- -- -- --
139+
53 -- -- -- --
140+
54 -- -- -- --
141+
55 -- -- -- --
142+
56 -- -- -- --
143+
57 -- -- -- --
144+
58 -- -- -- --
145+
59 -- -- 4 5 # cohesive edges
146+
60 -- -- 10 11
147+
61 -- -- 16 17
148+
62 -- -- 22 23
149+
Global Section
150+
Processor 0
151+
0 -- -- -- -- # cells
152+
1 -- -- -- --
153+
2 -- -- -- --
154+
3 -- -- -- --
155+
4 -- -- -- --
156+
5 -- -- -- --
157+
6 -- -- -- --
158+
7 -- -- -- --
159+
8 -- -- -- --
160+
9 -- -- -- --
161+
10 -- -- -- --
162+
11 -- -- -- --
163+
12 -- -- -- -- # vertices
164+
13 -- -- -- --
165+
14 -- -- -- --
166+
15 -- -- -- --
167+
16 24 25 -- --
168+
17 26 27 -- --
169+
18 28 29 -- --
170+
19 30 31 -- --
171+
20 -- -- -- --
172+
21 -- -- -- --
173+
22 -- -- -- --
174+
23 -- -- -- --
175+
24 0 1 -- --
176+
25 2 3 -- --
177+
26 6 7 -- --
178+
27 8 9 -- --
179+
28 12 13 -- --
180+
29 14 15 -- --
181+
30 18 19 -- --
182+
31 20 21 -- --
183+
32 -- -- -- -- # edges
184+
33 -- -- -- --
185+
34 -- -- -- --
186+
35 -- -- -- --
187+
36 -- -- -- --
188+
37 -- -- -- --
189+
38 -- -- -- --
190+
39 -- -- -- --
191+
40 -- -- -- --
192+
41 -- -- -- --
193+
42 -- -- -- --
194+
43 -- -- -- --
195+
44 -- -- -- --
196+
45 -- -- -- --
197+
46 -- -- -- --
198+
47 -- -- -- --
199+
48 -- -- -- --
200+
49 -- -- -- --
201+
50 -- -- -- --
202+
51 -- -- -- --
203+
52 -- -- -- --
204+
53 -- -- -- --
205+
54 -- -- -- --
206+
55 -- -- -- --
207+
56 -- -- -- --
208+
57 -- -- -- --
209+
58 -- -- -- --
210+
59 -- -- 4 5 # cohesive edges
211+
60 -- -- 10 11
212+
61 -- -- 16 17
213+
62 -- -- 22 23
214+
```
215+
72216
```{code-block} bash
73217
---
74-
caption: PetscSection information for a solution field with three subfields.
218+
caption: Corresponding output of PetscSectionVew() for the local section of the solution field.
75219
---
76-
# This example solution field has three subfields:
77-
# * displacement (vector field, 2 components, basis order 1)
78-
# * velocity (vector field, 2 components, basis order 1)
79-
# * pressure (scalar field, 1 component, basis order 0)
80-
#
81-
# The displacement and velocity subfields have degrees of freedom on the vertices.
82-
# The pressure subfield has degrees of freedom on the cells.
83-
#
84-
# The order of the values (offsets in the PetscVec) follows the
85-
# ordering of the points (cells, vertices, edges, and faces).
86-
# In this example, the pressure subfield appears first (offsets 0-3),
87-
# followed by the two components of the displacement subfield and
88-
# velocity subfield for each point.
89-
PetscSection Object: 1 MPI processes
220+
PetscSection Object: 1 MPI process
90221
type not yet set
91-
3 fields
92-
field 0 with 2 components # displacement field
93-
Process 0:
94-
# (POINT) dim SUBFIELD_NUM_COMPONENTS offset OFFSET
95-
( 0) dim 0 offset 0 # Cells
96-
( 1) dim 0 offset 0
97-
( 2) dim 0 offset 0
98-
( 3) dim 0 offset 0
99-
( 4) dim 2 offset 4 # Vertices
100-
( 5) dim 2 offset 8
101-
( 6) dim 2 offset 12
102-
( 7) dim 2 offset 16
103-
( 8) dim 2 offset 20
104-
( 9) dim 0 offset 24 # Edges
105-
( 10) dim 0 offset 24
106-
( 11) dim 0 offset 24
107-
( 12) dim 0 offset 24
108-
( 13) dim 0 offset 24
109-
( 14) dim 0 offset 24
110-
( 15) dim 0 offset 24
111-
( 16) dim 0 offset 24
112-
field 1 with 2 components # velocity field
222+
2 fields
223+
field 0 "displacement" with 2 components
113224
Process 0:
114-
( 0) dim 0 offset 0 # Cells
115-
( 1) dim 0 offset 0
116-
( 2) dim 0 offset 0
117-
( 3) dim 0 offset 0
118-
( 4) dim 2 offset 6 # Vertices
119-
( 5) dim 2 offset 10
120-
( 6) dim 2 offset 14
121-
( 7) dim 2 offset 18
122-
( 8) dim 2 offset 22
123-
( 9) dim 0 offset 24 # Edges
124-
( 10) dim 0 offset 24
125-
( 11) dim 0 offset 24
126-
( 12) dim 0 offset 24
127-
( 13) dim 0 offset 24
128-
( 14) dim 0 offset 24
129-
( 15) dim 0 offset 24
130-
( 16) dim 0 offset 24
131-
field 2 with 1 components # pressure field
225+
( 0) dof 0 offset 24 # cells
226+
( 1) dof 0 offset 24
227+
( 2) dof 0 offset 24
228+
( 3) dof 0 offset 24
229+
( 4) dof 0 offset 24
230+
( 5) dof 0 offset 24
231+
( 6) dof 0 offset 24
232+
( 7) dof 0 offset 24
233+
( 8) dof 0 offset 24
234+
( 9) dof 0 offset 12
235+
( 10) dof 0 offset 18
236+
( 11) dof 0 offset 24
237+
( 12) dof 2 offset 24 constrained 0 1 # vertices
238+
( 13) dof 2 offset 26 constrained 0 1
239+
( 14) dof 2 offset 28 constrained 0 1
240+
( 15) dof 2 offset 30 constrained 0 1
241+
( 16) dof 2 offset 32
242+
( 17) dof 2 offset 34
243+
( 18) dof 2 offset 36
244+
( 19) dof 2 offset 38
245+
( 20) dof 2 offset 0
246+
( 21) dof 2 offset 6
247+
( 22) dof 2 offset 12
248+
( 23) dof 2 offset 18
249+
( 24) dof 2 offset 40 constrained 0 1
250+
( 25) dof 2 offset 42 constrained 0 1
251+
( 26) dof 2 offset 44 constrained 0 1
252+
( 27) dof 2 offset 46 constrained 0 1
253+
( 28) dof 2 offset 2
254+
( 29) dof 2 offset 8
255+
( 30) dof 2 offset 14
256+
( 31) dof 2 offset 20
257+
( 32) dof 0 offset 48 # edges
258+
( 33) dof 0 offset 48
259+
( 34) dof 0 offset 48
260+
( 35) dof 0 offset 48
261+
( 36) dof 0 offset 48
262+
( 37) dof 0 offset 48
263+
( 38) dof 0 offset 48
264+
( 39) dof 0 offset 48
265+
( 40) dof 0 offset 48
266+
( 41) dof 0 offset 48
267+
( 42) dof 0 offset 48
268+
( 43) dof 0 offset 0
269+
( 44) dof 0 offset 48
270+
( 45) dof 0 offset 12
271+
( 46) dof 0 offset 48
272+
( 47) dof 0 offset 18
273+
( 48) dof 0 offset 48
274+
( 49) dof 0 offset 48
275+
( 50) dof 0 offset 48
276+
( 51) dof 0 offset 48
277+
( 52) dof 0 offset 48
278+
( 53) dof 0 offset 48
279+
( 54) dof 0 offset 48
280+
( 55) dof 0 offset 48
281+
( 56) dof 0 offset 0
282+
( 57) dof 0 offset 12
283+
( 58) dof 0 offset 18
284+
( 59) dof 0 offset 4 # cohesive edges
285+
( 60) dof 0 offset 10
286+
( 61) dof 0 offset 16
287+
( 62) dof 0 offset 22
288+
field 1 "lagrange_multiplier_fault" with 2 components
132289
Process 0:
133-
( 0) dim 1 offset 0 # Cells
134-
( 1) dim 1 offset 1
135-
( 2) dim 1 offset 2
136-
( 3) dim 1 offset 3
137-
( 4) dim 0 offset 4 # Vertices
138-
( 5) dim 0 offset 4
139-
( 6) dim 0 offset 4
140-
( 7) dim 0 offset 4
141-
( 8) dim 0 offset 4
142-
( 9) dim 0 offset 4 # Edges
143-
( 10) dim 0 offset 4
144-
( 11) dim 0 offset 4
145-
( 12) dim 0 offset 4
146-
( 13) dim 0 offset 4
147-
( 14) dim 0 offset 4
148-
( 15) dim 0 offset 4
149-
( 16) dim 0 offset 4
290+
( 0) dof 0 offset 24 # cells
291+
( 1) dof 0 offset 24
292+
( 2) dof 0 offset 24
293+
( 3) dof 0 offset 24
294+
( 4) dof 0 offset 24
295+
( 5) dof 0 offset 24
296+
( 6) dof 0 offset 24
297+
( 7) dof 0 offset 24
298+
( 8) dof 0 offset 24
299+
( 9) dof 0 offset 12
300+
( 10) dof 0 offset 18
301+
( 11) dof 0 offset 24
302+
( 12) dof 0 offset 26 # vertices
303+
( 13) dof 0 offset 28
304+
( 14) dof 0 offset 30
305+
( 15) dof 0 offset 32
306+
( 16) dof 0 offset 34
307+
( 17) dof 0 offset 36
308+
( 18) dof 0 offset 38
309+
( 19) dof 0 offset 40
310+
( 20) dof 0 offset 2
311+
( 21) dof 0 offset 8
312+
( 22) dof 0 offset 14
313+
( 23) dof 0 offset 20
314+
( 24) dof 0 offset 42
315+
( 25) dof 0 offset 44
316+
( 26) dof 0 offset 46
317+
( 27) dof 0 offset 48
318+
( 28) dof 0 offset 4
319+
( 29) dof 0 offset 10
320+
( 30) dof 0 offset 16
321+
( 31) dof 0 offset 22
322+
( 32) dof 0 offset 48 # edges
323+
( 33) dof 0 offset 48
324+
( 34) dof 0 offset 48
325+
( 35) dof 0 offset 48
326+
( 36) dof 0 offset 48
327+
( 37) dof 0 offset 48
328+
( 38) dof 0 offset 48
329+
( 39) dof 0 offset 48
330+
( 40) dof 0 offset 48
331+
( 41) dof 0 offset 48
332+
( 42) dof 0 offset 48
333+
( 43) dof 0 offset 0
334+
( 44) dof 0 offset 48
335+
( 45) dof 0 offset 12
336+
( 46) dof 0 offset 48
337+
( 47) dof 0 offset 18
338+
( 48) dof 0 offset 48
339+
( 49) dof 0 offset 48
340+
( 50) dof 0 offset 48
341+
( 51) dof 0 offset 48
342+
( 52) dof 0 offset 48
343+
( 53) dof 0 offset 48
344+
( 54) dof 0 offset 48
345+
( 55) dof 0 offset 48
346+
( 56) dof 0 offset 0
347+
( 57) dof 0 offset 12
348+
( 58) dof 0 offset 18
349+
( 59) dof 2 offset 4 # cohesive edges
350+
( 60) dof 2 offset 10
351+
( 61) dof 2 offset 16
352+
( 62) dof 2 offset 22
150353
```
151354

152355
## Integration

0 commit comments

Comments
 (0)