Skip to content

Commit 3551495

Browse files
Merge pull request #739 from baagaard-usgs/docs-update-troubleshooting
Update troubleshooting-2d example
2 parents 5449cb4 + 0ca250f commit 3551495

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+1537
-872
lines changed

docs/Makefile.am

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -566,6 +566,7 @@ dist_noinst_DATA = \
566566
user/examples/troubleshooting-2d/step06-error07.md \
567567
user/examples/troubleshooting-2d/step06-error08.md \
568568
user/examples/troubleshooting-2d/step06-error09.md \
569+
user/examples/troubleshooting-2d/step06-error10.md \
569570
user/examples/troubleshooting-2d/figs/step01-diagram.pdf \
570571
user/examples/troubleshooting-2d/figs/step01-diagram.svg \
571572
user/examples/troubleshooting-2d/figs/step06-diagram.pdf \

docs/references.bib

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,24 @@ @Book{Timoshenko:Goodier:1987
325325
note = {567 pp.},
326326
}
327327

328+
329+
@Article{Nevitt:etal:2023,
330+
author = {Nevitt, J.M. and Brooks, B.A. and Hardebeck, J.L. and Aagaard, B.T.},
331+
title = {2019 {M7.1} {Ridgecrest} earthquake slip distribution controlled by fault geometry inherited from {Independence} dike swarm},
332+
year = {2023},
333+
journal = {Nature Communications},
334+
volume = {14},
335+
doi = {10.1038/s41467-023-36840-2},
336+
}
337+
338+
@Article{Uphoff:etal:2022,
339+
author = {Uphoff, C. and May, D.A. and Gabriel, A.-A.},
340+
title = {Electronic supplement to {A} discontinuous {Galerkin} method for sequences of earthquakes and aseismic slip on multiple faults using unstructured curvilinear grids},
341+
year = {2022},
342+
journal = {Geophysical Journal International},
343+
doi = {10.5281/zenodo.5796104},
344+
}
345+
328346
@InProceedings{Williams:2006,
329347
author = {Williams, C.~A.},
330348
title = {Development of a package for modeling stress in the lithosphere},

docs/user/examples/crustal-strikeslip-2d/index.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
New in v4.1.0
55
:::
66

7-
87
The files are in the directory `examples/crustal-strikeslip-2d`.
98
The files and directories for this set of examples includes:
109

@@ -22,7 +21,7 @@ The files and directories for this set of examples includes:
2221
## Overview
2322

2423
This suite of examples demonstrates using PyLith to model multiple intersecting faults embedded in a 2D georeferenced domain ({numref}`fig:example:crustal:strikeslip:2d:overview`).
25-
The geometry is based on the 2019 Ridgecrest earthquake sequence.
24+
The geometry is based on studies of the 2019 Ridgecrest earthquake sequence by {cite:t}`Uphoff:etal:2022` and {cite:t}`Nevitt:etal:2023`.
2625

2726
:Step 1: Static uniform coseismic slip with Dirichlet (displacement) boundary conditions.
2827
:Step 2: Static spatially varying coseismic slip with Dirichlet (displacement) boundary conditions.

docs/user/examples/crustal-strikeslip-3d/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The files and directories for this set of examples includes:
2121
## Overview
2222

2323
This suite of examples demonstrates using PyLith to model multiple intersecting faults embedded in a 3D georeferenced domain ({numref}`fig:example:crustal:strikeslip:3d:overview`).
24-
The geometry is based on the 2019 Ridgecrest earthquake sequence.
24+
The geometry is based on studies of the 2019 Ridgecrest earthquake sequence by {cite:t}`Uphoff:etal:2022` and {cite:t}`Nevitt:etal:2023`.
2525

2626
:Step 1: Static uniform coseismic slip with Dirichlet (displacement) boundary conditions.
2727
:Step 2: Static spatially varying coseismic slip with Dirichlet (displacement) boundary conditions.

docs/user/examples/troubleshooting-2d/error-messages.md

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,20 @@ Summary of error messages addressed in this set of examples.
88
---
99
caption: See [Step 1, Error 1](step01-error01.md).
1010
---
11-
ValueError: No constrained degrees of freedom found for time-dependent Dirichlet boundary condition 'bc_xpos'.
12-
'constrained_dof' must be a zero-based integer array (0=x, 1=y, 2=z).
11+
>> {default}::
12+
-- pyre.inventory(error)
13+
-- timedependent.problem_defaults.name <- ''
14+
-- Missing required property 'name' in default options for problem.
1315
```
1416

1517
```{code-block} bash
1618
---
1719
caption: See [Step 1, Error 2](step01-error02.md).
1820
---
19-
>> {default}::
20-
-- pyre.inventory(error)
21-
-- timedependent.problem_defaults.name <- ''
22-
-- Missing required property 'name' in default options for problem.
21+
>> {default}::
22+
-- pyre.inventory(error)
23+
-- timedependent.bc.dirichlettimedependent.label <- ''
24+
-- Label for boundary condition group/nodeset/pset in mesh not specified.
2325
```
2426

2527
```{code-block} bash
@@ -36,7 +38,7 @@ caption: See [Step 1, Error 3](step01-error03.md).
3638
---
3739
caption: See [Step 1, Error 4](step01-error04.md).
3840
---
39-
RuntimeError: Material label_value '3' for cell '3009' does not match the label_value of any materials or interfaces.
41+
RuntimeError: Material label_value '3' for cell '609' does not match the label_value of any materials or interfaces.
4042
```
4143

4244
```{code-block}
@@ -66,9 +68,6 @@ caption: See [Step 6, Error 3](step06-error03.md).
6668
RuntimeError: Cannot find 'lagrange_multiplier_fault' subfield in solution field for fault implementation in component 'splay'.
6769
```
6870

69-
70-
71-
7271
## Runtime Errors
7372

7473
```{code-block} bash
@@ -101,7 +100,7 @@ RuntimeError: Could not find value 'final_slip_opening' in spatial database 'Fau
101100
---
102101
caption: See [Step 6, Error 6](step06-error06.md).
103102
---
104-
[0]PETSC ERROR: Zero pivot in LU factorization: https://petsc.org/release/faq/#zeropivot
103+
Nonlinear solve did not converge due to DIVERGED_MAX_IT iterations 1
105104
```
106105

107106
```{code-block} bash
@@ -115,5 +114,5 @@ caption: See [Step 6, Error 7](step06-error07.md).
115114
---
116115
caption: See [Step 6, Error 9](step06-error09.md).
117116
---
118-
[0]PETSC ERROR: Could not find values for initiation_time at ( -24329 -29046.3) in spatial database 'Fault rupture for main fault'.
117+
[0]PETSC ERROR: Could not find values for initiation_time at ( -21860.3 -27621) in spatial database 'Fault rupture for main fault'.
119118
```

docs/user/examples/troubleshooting-2d/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
# Troubleshooting (2D)
33

44
This set of examples demonstrations how to troubleshoot PyLith simulations.
5-
We consider Steps 1 and 6 from `examples/reverse-2d` and introduce errors into the parameter files and spatial databases.
5+
We consider Steps 1a and 6 from `examples/reverse-2d` and introduce errors into the parameter files and spatial databases.
66
We illustrate how to dissect a variety of error messages, strategies for diagnosing errors, and the resolution.
77

88
The files are in the directory `examples/troubleshooting-2d`.
@@ -34,4 +34,5 @@ step06-error06.md
3434
step06-error07.md
3535
step06-error08.md
3636
step06-error09.md
37+
step06-error10.md
3738
:::

docs/user/examples/troubleshooting-2d/step01-error01.md

Lines changed: 76 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,44 +6,92 @@
66
---
77
caption: Error message 1 when running Step 1.
88
linenos: True
9-
emphasize-lines: 15,16
9+
emphasize-lines: 3-6
1010
---
11-
$ pylith step01_gravity.cfg
12-
13-
Traceback (most recent call last):
14-
File "/software/baagaard/py38-venv/pylith-debug/bin/pylith", line 28, in <module>
15-
start(applicationClass=PyLithApp)
16-
File "/software/baagaard/py38-venv/pylith-debug/lib/python3.8/site-packages/pythia/pyre/applications/__init__.py", line 42, in start
17-
shell.run(**kwds)
18-
19-
# -- many line omitted --
20-
21-
File "/software/baagaard/py38-venv/pylith-debug/lib/python3.8/site-packages/pythia/pyre/inventory/ConfigContext.py", line 68, in configureComponent
22-
component._validate(self)
23-
File "/software/baagaard/py38-venv/pylith-debug/lib/python3.8/site-packages/pylith/bc/DirichletTimeDependent.py", line 120, in _validate
24-
raise ValueError(f"No constrained degrees of freedom found for time-dependent Dirichlet boundary condition '{self.aliases[-1]}'. "
25-
ValueError: No constrained degrees of freedom found for time-dependent Dirichlet boundary condition 'bc_xpos'.
26-
'constrained_dof' must be a zero-based integer array (0=x, 1=y, 2=z).
11+
$ pylith step01a_gravity.cfg
12+
13+
>> {default}::
14+
-- pyre.inventory(error)
15+
-- timedependent.problem_defaults.name <- ''
16+
-- Missing required property 'name' in default options for problem.
17+
>> {default}::
18+
-- pyre.inventory(error)
19+
-- timedependent.bc.dirichlettimedependent.label <- ''
20+
-- Label for boundary condition group/nodeset/pset in mesh not specified.
21+
>> {default}::
22+
-- pyre.inventory(error)
23+
-- timedependent.bc.dirichlettimedependent.simpledb.description <- ''
24+
-- Description for spatial database not specified.
25+
>> {default}::
26+
-- pyre.inventory(error)
27+
-- timedependent.bc.dirichlettimedependent.simpledb.simpleioascii.filename <- ''
28+
-- Filename for spatial database not specified.
29+
>> {default}::
30+
-- pyre.inventory(error)
31+
-- timedependent.bc.dirichlettimedependent.constrained_dof <- '[]'
32+
-- No constrained degrees of freedom found for time-dependent Dirichlet boundary condition 'bc_xpos'. 'constrained_dof' must be a zero-based integer array (0=x, 1=y, 2=z).
33+
>> ./pylithapp.cfg:118:
34+
-- pyre.inventory(error)
35+
-- pylithapp.timedependent.materials.elasticity.auxiliary_subfields.bulk_modulus.basis_order <- '0'
36+
-- unknown component 'pylithapp.timedependent.materials.elasticity.auxiliary_subfields.bulk_modulus'
37+
>> ./pylithapp.cfg:119:
38+
-- pyre.inventory(error)
39+
-- pylithapp.timedependent.materials.elasticity.auxiliary_subfields.shear_modulus.basis_order <- '0'
40+
-- unknown component 'pylithapp.timedependent.materials.elasticity.auxiliary_subfields.shear_modulus'
41+
>> ./pylithapp.cfg:141:
42+
-- pyre.inventory(error)
43+
-- pylithapp.timedependent.bc.xpos.label <- 'boundary_xpos'
44+
-- unknown component 'pylithapp.timedependent.bc.xpos'
45+
>> ./pylithapp.cfg:142:
46+
-- pyre.inventory(error)
47+
-- pylithapp.timedependent.bc.xpos.label_value <- '11'
48+
-- unknown component 'pylithapp.timedependent.bc.xpos'
49+
>> ./pylithapp.cfg:143:
50+
-- pyre.inventory(error)
51+
-- pylithapp.timedependent.bc.xpos.constrained_dof <- '[0]'
52+
-- unknown component 'pylithapp.timedependent.bc.xpos'
53+
>> ./pylithapp.cfg:144:
54+
-- pyre.inventory(error)
55+
-- pylithapp.timedependent.bc.xpos.db_auxiliary_field <- 'pylith.bc.ZeroDB'
56+
-- unknown component 'pylithapp.timedependent.bc.xpos'
57+
>> ./pylithapp.cfg:145:
58+
-- pyre.inventory(error)
59+
-- pylithapp.timedependent.bc.xpos.db_auxiliary_field.description <- 'Dirichlet BC +x edge'
60+
-- unknown component 'pylithapp.timedependent.bc.xpos.db_auxiliary_field'
61+
>> ./pylithapp.cfg:147:
62+
-- pyre.inventory(error)
63+
-- pylithapp.timedependent.bc.xpos.auxiliary_subfields.initial_amplitude.basis_order <- '0'
64+
-- unknown component 'pylithapp.timedependent.bc.xpos.auxiliary_subfields.initial_amplitude'
65+
usage: pylith [--<property>=<value>] [--<facility>.<property>=<value>] [FILE.cfg] ...
66+
component 'pylithapp'
67+
properties: dump_parameters, help, help-components, help-persistence, help-properties, include-citations, initialize_only, job, launcher, mesh_generator, metadata, nodes, petsc, problem, scheduler, start_python_debugger, typos, weaver
68+
facilities: dump_parameters,job,launcher,mesh_generator,metadata,petsc,problem,scheduler,weaver
69+
For more information:
70+
--help-properties: prints details about user settable properties
71+
--help-components: prints details about user settable facilities and components
72+
pylithapp: configuration error(s)
2773
```
2874

2975
## Troubleshooting Strategy
3076

31-
The full error message includes a Python Traceback followed by the actual error message (lines 15-16) generated by the `ValueError` exception.
32-
The error message indicates there is a problem with the parameters for `pylithapp.problem.bc.bc_xpos`.
33-
We look for this section in the parameter files and find it in `pylithapp.cfg`.
77+
The full error message shows several errors associated with our parameter files.
78+
Because errors often cascade, the best place to start is to address the first error (lines 3-6).
79+
We see that the default name for `problem_defaults` is empty and PyLith requires one.
80+
This name will be used as the first part of the filename for output.
81+
We resolve this error by examining the parameters for `pylithapp.timedependent.problem_defaults` in `step01_gravity.cfg`.
82+
We see that we do not set any of the problem defaults.
3483

3584
## Resolution
3685

37-
There is a typo in the section heading for `pylithapp.problem.bc.bc_xpos`.
38-
Because the section heading has the wrong name, PyLith uses the defaults (no constrained degrees of freedom) and complains that no degrees of freedom are constrained by the Dirichlet boundary condition.
86+
We must set the simulation name in the problem defaults.
3987

4088
```{code-block} cfg
4189
---
42-
caption: Correct error in `pylithapp.cfg`.
90+
caption: Correct error in `step01a_gravity.cfg`.
4391
---
44-
# Error
45-
[pylithapp.timedependent.bc.xpos]
46-
47-
# Correct
48-
[pylithapp.timedependent.bc.bc_xpos]
92+
[pylithapp]
93+
...
94+
# Set the name of the problem that will be used to construct the
95+
# output filenames. The default directory for output is 'output'.
96+
problem.defaults.name = step01a_gravity
4997
```

docs/user/examples/troubleshooting-2d/step01-error02.md

Lines changed: 51 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,58 @@
66
---
77
caption: Error message 2 when running Step 1.
88
linenos: True
9-
emphasize-lines: 3-6
9+
emphasize-lines: 3-6,15-18
1010
---
11-
$ pylith step01_gravity.cfg
11+
$ pylith step01a_gravity.cfg
1212
1313
>> {default}::
1414
-- pyre.inventory(error)
15-
-- timedependent.problem_defaults.name <- ''
16-
-- Missing required property 'name' in default options for problem.
17-
>> ./pylithapp.cfg:133:
15+
-- timedependent.bc.dirichlettimedependent.label <- ''
16+
-- Label for boundary condition group/nodeset/pset in mesh not specified.
17+
>> {default}::
18+
-- pyre.inventory(error)
19+
-- timedependent.bc.dirichlettimedependent.simpledb.description <- ''
20+
-- Description for spatial database not specified.
21+
>> {default}::
22+
-- pyre.inventory(error)
23+
-- timedependent.bc.dirichlettimedependent.simpledb.simpleioascii.filename <- ''
24+
-- Filename for spatial database not specified.
25+
>> {default}::
26+
-- pyre.inventory(error)
27+
-- timedependent.bc.dirichlettimedependent.constrained_dof <- '[]'
28+
-- No constrained degrees of freedom found for time-dependent Dirichlet boundary condition 'bc_xpos'. 'constrained_dof' must be a zero-based integer array (0=x, 1=y, 2=z).
29+
>> ./pylithapp.cfg:118:
1830
-- pyre.inventory(error)
1931
-- pylithapp.timedependent.materials.elasticity.auxiliary_subfields.bulk_modulus.basis_order <- '0'
2032
-- unknown component 'pylithapp.timedependent.materials.elasticity.auxiliary_subfields.bulk_modulus'
21-
>> ./pylithapp.cfg:134:
33+
>> ./pylithapp.cfg:119:
2234
-- pyre.inventory(error)
2335
-- pylithapp.timedependent.materials.elasticity.auxiliary_subfields.shear_modulus.basis_order <- '0'
2436
-- unknown component 'pylithapp.timedependent.materials.elasticity.auxiliary_subfields.shear_modulus'
37+
>> ./pylithapp.cfg:141:
38+
-- pyre.inventory(error)
39+
-- pylithapp.timedependent.bc.xpos.label <- 'boundary_xpos'
40+
-- unknown component 'pylithapp.timedependent.bc.xpos'
41+
>> ./pylithapp.cfg:142:
42+
-- pyre.inventory(error)
43+
-- pylithapp.timedependent.bc.xpos.label_value <- '11'
44+
-- unknown component 'pylithapp.timedependent.bc.xpos'
45+
>> ./pylithapp.cfg:143:
46+
-- pyre.inventory(error)
47+
-- pylithapp.timedependent.bc.xpos.constrained_dof <- '[0]'
48+
-- unknown component 'pylithapp.timedependent.bc.xpos'
49+
>> ./pylithapp.cfg:144:
50+
-- pyre.inventory(error)
51+
-- pylithapp.timedependent.bc.xpos.db_auxiliary_field <- 'pylith.bc.ZeroDB'
52+
-- unknown component 'pylithapp.timedependent.bc.xpos'
53+
>> ./pylithapp.cfg:145:
54+
-- pyre.inventory(error)
55+
-- pylithapp.timedependent.bc.xpos.db_auxiliary_field.description <- 'Dirichlet BC +x edge'
56+
-- unknown component 'pylithapp.timedependent.bc.xpos.db_auxiliary_field'
57+
>> ./pylithapp.cfg:147:
58+
-- pyre.inventory(error)
59+
-- pylithapp.timedependent.bc.xpos.auxiliary_subfields.initial_amplitude.basis_order <- '0'
60+
-- unknown component 'pylithapp.timedependent.bc.xpos.auxiliary_subfields.initial_amplitude'
2561
usage: pylith [--<property>=<value>] [--<facility>.<property>=<value>] [FILE.cfg] ...
2662
component 'pylithapp'
2763
properties: dump_parameters, help, help-components, help-persistence, help-properties, include-citations, initialize_only, job, launcher, mesh_generator, metadata, nodes, petsc, problem, scheduler, start_python_debugger, typos, weaver
@@ -30,28 +66,26 @@ For more information:
3066
--help-properties: prints details about user settable properties
3167
--help-components: prints details about user settable facilities and components
3268
pylithapp: configuration error(s)
69+
3370
```
3471

3572
## Troubleshooting Strategy
3673

3774
The full error message shows several errors associated with our parameter files.
3875
Because errors often cascade, the best place to start is to address the first error (lines 3-6).
39-
We see that the default name for `problem_defaults` is empty and PyLith requires one.
40-
This name will be used as the first part of the filename for output.
41-
We resolve this error by examining the parameters for `pylithapp.timedependent.problem_defaults` in `step01_gravity.cfg`.
42-
We see that we do not set any of the problem defaults.
76+
This does not give us anything specific, so we look further down the output until we find an error for a specific component.
77+
At lines 15-18, we find that an error is associated with the `bc_xpos` boundary condition.
78+
We look for this section in the parameter files and find it in `pylithapp.cfg` and notice the name of the boundary condition is missing `bc_`.
4379

4480
## Resolution
4581

46-
We must set the simulation name in the problem defaults.
47-
4882
```{code-block} cfg
4983
---
5084
caption: Correct error in `pylithapp.cfg`.
5185
---
52-
[pylithapp]
53-
...
54-
# Set the name of the problem that will be used to construct the
55-
# output filenames. The default directory for output is 'output'.
56-
problem.defaults.name = step01_gravity
86+
# Error
87+
[pylithapp.timedependent.bc.xpos]
88+
89+
# Correct
90+
[pylithapp.timedependent.bc.bc_xpos]
5791
```

docs/user/examples/troubleshooting-2d/step01-error03.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ caption: Error message 3 when running Step 1.
88
linenos: True
99
emphasize-lines: 3-6
1010
---
11-
$ pylith step01_gravity.cfg
11+
$ pylith step01a_gravity.cfg
1212
13-
>> ./pylithapp.cfg:133:
13+
>> ./pylithapp.cfg:118:
1414
-- pyre.inventory(error)
1515
-- pylithapp.timedependent.materials.elasticity.auxiliary_subfields.bulk_modulus.basis_order <- '0'
1616
-- unknown component 'pylithapp.timedependent.materials.elasticity.auxiliary_subfields.bulk_modulus'
17-
>> ./pylithapp.cfg:134:
17+
>> ./pylithapp.cfg:119:
1818
-- pyre.inventory(error)
1919
-- pylithapp.timedependent.materials.elasticity.auxiliary_subfields.shear_modulus.basis_order <- '0'
2020
-- unknown component 'pylithapp.timedependent.materials.elasticity.auxiliary_subfields.shear_modulus'

0 commit comments

Comments
 (0)