/
README
575 lines (419 loc) · 23 KB
/
README
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
We are pleased to announce release of PyLith version 1.5.1
Please submit bug reports via the World Wide Web at:
http://geodynamics.org/roundup
Please send all questions by electronic mail to:
cig-short@geodynamics.org
PyLith is free software. See the file COPYING for copying conditions.
This release allows the solution of both quasi-static and dynamic
problems in one, two, or three dimensions. The code runs in either
serial or parallel mode, and the design allows for relatively easy
scripting using the Python programming language. Material properties
and parameters for boundary and fault conditions are specified using a
spatial database, which permits easy prescription of complex spatial
variations of properties and parameters. Simulation parameters are
generally specified through the use of simple ASCII files or the
command line.
You can download the source code and binaries from
http://geodynamics.org/cig/software/packages/short/pylith
Installation instructions are in the bundled README and INSTALL
files, as well as in the User Manual on the web page.
PyLith is under active development and we expect a number of additions
and improvements in the near future. Likely enhancements will include
additional bulk and fault constitutive models and the generation of
Green's functions to be used in inversions.
======================================================================
TIPS
======================================================================
* For most crustal deformation problems, we recommend using the
Additive Schwartz preconditioner via the following PETSc
settings:
- Command line arguments
--petsc.pc_type=asm
--petsc.ksp_max_it=400
--petsc.ksp_gmres_restart=100
--petsc.ksp_rtol=1.0e-08
- pylithapp.cfg (or your other favorite .cfg file)
[pylithapp.petsc]
pc_type = asm
ksp_max_it = 400
ksp_gmres_restart = 100
ksp_rtol = 1.0e-08
* If the solve takes more than a few hundred iterations for a large
problem (use the --petsc.ksp_monitor=1 and --petsc.ksp_view=1 to
see diagnostic information for the solver), this is usually an
indication that something is wrong. Either the preconditioner is
inappropriate for the type of problem you are solving or there is
an error in the problem setup.
======================================================================
MIGRATING FROM VERSION 1.4 TO 1.5
======================================================================
Three changes to the code require updating old parameters settings for use
with version 1.5.
(1) Recent releases of CUBIT include nodeset names in the Exodus file
and PyLith now uses them to associate vertices with boundary
conditions and faults. Use the NetCDF utility ncdump to examine the
contents of the Exodus (.exo) file to see it it includes the variable
ns_names. If it does, then use nodeset names rather than nodeset ids
for boundary condition label properties. If your Exodus file does not
contain nodeset names, then set the MeshIOCubit property
use_nodeset_names to False to continue to use nodeset id values for
boundary condition labels.
(2) The power-law constitutive parameters have been changed so that the
parameter units are no longer dependent on the power-law exponent. This
is a more logical implementation and allows (among other things) users to
vary power-law parameters using a spatial database. Previously, it was not
possible to vary power-law parameters unless everything used the same
power-law exponent. The new implementation uses reference-strain-rate,
reference-stress, and power-law-exponent to describe the material. This is
described in the 'Material Models' section of the manual.
(3) The fault property 'normal_dir' is obsolete. Only the property
'up_dir' is required to enforce that positive slip is left-lateral,
reverse, and fault-opening for dipping faults in 2-D and horizontal
fault surfaces in 3-D. Previously, in 2-D positive slip was always
left-lateral, but now the up-direction is used to enforce positive
slip corresponds to reverse motion for dipping faults. For horizontal
fault surfaces in 3-D a normal of (0,0,1) is assumed in determining
the up-dip direction.
----------------------------------------------------------------------
Version 1.5.1
----------------------------------------------------------------------
* Bug fixes
- Fixed dimensioning of velocity and acceleration fields in
output. The scales were set to just the length scale rather than
the length scale divided by the time scale and length scale
divided by the time scale squared.
- Fixed partitioning of cohesive cells. Cohesive cells were
ignored during partitioning of the mesh, so they were randomly
distributed among processors.
----------------------------------------------------------------------
Version 1.5.0
----------------------------------------------------------------------
* Fault constitutive models
Added fault friction interface conditions with static friction,
linear slip-weakening friction, and rate- and state-friction with
the ageing law. The implementation can be used in static,
quasi-static, and dynamic problems.
* Drucker-Prager elastoplastic bulk rheology
Added a Drucker-Prager elastoplastic bulk rheology. This is a
perfect plasticity implementation (no hardening). This is a
nonlinear constitutive model, so the nonlinear solver is required
when this rheology is used. Refer to the 'Material Models' section
of the manual.
* Plane strain Maxwell viscoelastic bulk rheology
Linear Maxwell viscoelastic rheology for plane strain problems.
* Finite-deformation formulation
Added a finite-deformation (rigid body motion and small strains)
implementation of elasticity with stress calculated using the
Second Piola Kirchhoff stress tensor and strains calculated using
the Green-Lagrange strain tensor.
* Lumped Jacobian for explicit-time stepping
Added the option to lump cell Jacobian matrices to form a diagonal
system Jacobian matrix for explicit time stepping. This decouples
all degrees of freedom and permits use of a fast, trivial, direct
solver.
* Optimized elasticity objects
Added optimized elasticity objects for the most popular cell types
and basis functions (linear polynomials). For tri3 and tet4 cells
with one quadrature point, the optimized implementations do not
use reference (mapped) cells in order to reduce the number of
operations.
* Scientific notation for ASCII VTK files
Data values in ASCII data files are written in scientific notation
with user-specified precision.
* Nodeset names in CUBIT Exodus files
Use of nodeset names in CUBIT Exodus files for boundary conditions
and faults. Users can specify to use nodeset names (default
behavior) or ids.
* Velocity and slip rate as output fields
Velocity (domain and subdomain) and slip rate (fault) fields are
can be requested as output fields. The fields are computed using
the time-stepping algorithm and alleviates the need to compute
them via post-processing.
* Dimensionless values in spatial databases no longer need
artificial dimensions. Values without dimensions are understood by
the parser as dimensionless quantities.
* Bug fixes
- Updating state variables did not retrieve physical properties
for cell. Last physical properties retrieved were used. Physical
properties are now retrieved when updating state variables.
- Fixed incorrect dimensioning of physical properties and state
variables for the power-law rheology in output.
- Fixed memory bug for a fault in a 1-D mesh when constructing the
cohesive cells.
======================================================================
MIGRATING FROM VERSION 1.3 TO 1.4
======================================================================
A number of changes to the code require updating old parameter
settings for use with version 1.4.
(1) The mesh "importer" is now called "reader".
(2) The spatial database facility for a material, "db", is separated
into a "db_properties" and a "db_initial_state". The initial stress
and strain tensors are specified using the "db_initial_stress" and
"db_initial_strain" facilities. The names of some of the spatial
database values for physical properties for viscoelastic properties
have changed.
(3) The code is now intelligent enough to determine the dimensions of
the quadrature required (e.g., Quadrature2D and Quadrature2Din3D,
etc). Setting the quadrature to the object for a given spatial
dimension and cell dimension is no longer allowed because it is done
automatically.
(4) The names of the output filters have changed and include suffixes
Mesh or SubMesh to indicate that they operate on a mesh or submesh
(e.g., CellFilterAvg is now CellFilterAvgMesh or
CellFilterAvgSubMesh). This is related to the use of C++ templates.
(5) The DirichletPoints boundary condition has been renamed to
DirichletBC.
(6) The procedure for enabling certain features no longer involves
setting a "use" property to True. Instead, the features are enabled
when the user sets the component to a facility. This applies to
gravity, initial stresses, initial strains, and initial state
variables, and time-dependent boundary conditions (Dirichlet, Neumann,
and point force).
(7) Nondimensionalization of the problem eliminates the need to
condition the fault constraints. The "mat_db" facility was removed.
(8) The Dirichlet and Neumann boundary conditions now follow a more
general time dependence. The names of the facilities and the names of
the values in the spatial databases are, in most cases, different.
(9) The FixedDOFDB has been renamed to ZeroDispDB in order to better
reflect the type of spatial database.
======================================================================
MIGRATING FROM VERSION 1.2 TO 1.3
======================================================================
The implementation of different options for controlling the time step
requires adjusting input parameters from those used with PyLith
1.2. The time stepping is specified under the time-stepping
formulation rather than the problem (i.e., one level deeper).
----------------------------------------------------------------------
Version 1.3.1
----------------------------------------------------------------------
* Added stages to PETSc logging (--petsc.log_summary=1) to collect
event logging into groups.
* Bug fixes
- Fixed partitioning options. Partitioning options were ignored in
the 1.3.0 release.
- Fixed assembling of Jacobian, residual, and fault sections
across processors. This bug caused errors in the computation of
the change in tractions over the fault surface.
----------------------------------------------------------------------
Version 1.3.0
----------------------------------------------------------------------
* New time stepping options
In addition to a uniform, user-specified time step, which is the
default, there are two new time-stepping options. The user may
supply a file with nonuniform time steps or, for quasi-static
simulations, the user can request the code to compute the time
step automatically. For the current bulk constitutive models, the
automatically determined time step is independent of the
deformation rate, so it is uniform.
* Initial stresses
Users may optionally supply an initial stress state for each
material via a spatial database. The initial stress state can
balance the gravitational body forces so that the model is in
equilibrium without any deformation. This implementation of an
initial stress state is a prelude to specifying an initial state
for each material, which will be available in a future release.
* Bug fixes
- Fixed labeling of physical properties in output for the Maxwell
viscoelastic and generalized Maxwell viscoelastic materials (mu
and lambda were switched).
======================================================================
MIGRATING FROM VERSION 1.1 TO 1.2
======================================================================
There are two new features in PyLith version 1.2 that require users to
adjust input parameters from those used with PyLith 1.1. A dynamic
array of kinematic rupture replaces a single kinematic rupture on a
fault. Additionally, the default slip time function is now a
step-function. This eliminates the need to specify a peak slip rate
for quasi-static simulations. When using PyLith version 1.2 with a
problem previously setup for PyLith 1.1, look for warnings about
unknown components and settings in the screen output at the beginning
of a run.
----------------------------------------------------------------------
Version 1.2.0
----------------------------------------------------------------------
* New Sieve implementation
The previous implementation of Sieve provided a very generalized
implementation of data structures and operations for
finite-element meshes. Switching to a more rigid implementation in
the new implementation streamlined the data structures, resulting
in a significant reduction in the memory use for storing the
mesh. This leads to an overall reduction in memory use of 25-30%
in many cases.
* Multiple kinematic ruptures
A single kinematic rupture on a fault has been replaced by a
dynamic array of kinematic ruptures. This allows creation of an
arbitrary number of kinematic ruptures on each fault surface. By
using spatial databases to control the spatial and temporal extent
of slip in each rupture independently, slip from different
earthquake ruptures can overlap in space and/or
time. Additionally, the rupture time at each location is specified
with respect to the origin time of the corresponding earthquake
rupture.
* New slip time functions
- Step slip time function (now the default)
This slip time function simplifies specifying instantaneous slip
in a quasi-static simulation compared with using the Brune slip
time function.
- Constant slip rate slip time function
This slip time function permits prescribing a constant slip rate
on the fault surface.
* Gravitational body forces
Gravitational body forces are implemented (they are turned off by
default). The direction and acceleration of gravity may be specified.
* Fixed Makefile.am files to not delete source files during "make
clean" when building in the source tree.
======================================================================
MIGRATING FROM VERSION 1.0 TO 1.1
======================================================================
There are two new features in PyLith version 1.1 that require users to
adjust input parameters from those used with PyLith 1.0. The
elimination of containers in favor of the dynamic arrays of components
present in the latest version of Pyre requires switching from setting
the container to specifying the array of components on the command
line or .cfg file. Additionally, the new implementation of output
requires a completely new set of parameters. When using PyLith version
1.1 with a problem previously setup for PyLith 1.0, look for warnings
about unknown components and settings in the output at the beginning
of a run.
----------------------------------------------------------------------
Version 1.1.2
----------------------------------------------------------------------
* Fixed bug in output of solution over sub-domain boundary surfaces
in parallel.
* Fixed Makefile.am files to include documentation files in source
distribution.
----------------------------------------------------------------------
Version 1.1.1
----------------------------------------------------------------------
* Fixed Makefile.am files to include files missing from the source
distribution.
----------------------------------------------------------------------
Version 1.1.0
----------------------------------------------------------------------
* New boundary conditions
- Neumann (traction) boundary conditions
- Absorbing boundary conditions via simple, tuned dampers
- Dirichlet boundary conditions with displacement and/or velocity values
* New bulk constitutive models
- Generalized Maxwell viscoelastic model
* New output implementation
The output to VTK files has been completely rewritten. This new
implementation includes output of physical properties and state
variables associated with the bulk constitutive models, as well as
output of fault information (earthquake rupture parameters and
slip and traction time histories). Additionally, the VTK file with
the solution no longer includes fault related values- it contains
just the displacement field over the domain as one would expect. A
user can now also request output of the solution over an arbitrary
number of sub-domains of the domain boundary, e.g., the ground
surface. For each of these different kinds of output, the
frequency of output and the values included can be customized by
the user. The names of the VTK files and the variable names have
also been adjusted to permit animation of solutions within most
VTK visualization tools.
* New spatial database implementations
Spatialdata includes two new spatial database implementations. The
SCECCVMHDB provides a seamless interface to the SCEC CVM-H seismic
velocity model for elastic material properties. The UniformDB
permits creating a spatial database for uniform values using only
.cfg files or the command line; this eliminates the need to create
a SimpleDB database file with one location.
* Dynamic arrays of components in Pyre
Pyre now contains dynamic arrays of components, eliminating the
need for containers for materials, boundary conditions, and
faults.
* Better consistency checking of input parameters
- Uniqueness of material identifiers for materials and faults is
enforced.
- The material identifier of each cell in the mesh is checked to
make sure it matches a material model.
- Each boundary, interface condition, and output group is checked
to make sure it exists in the mesh.
* Bug fixes
- Fixed bug causing segmentation fault with multiple,
non-overlapping Dirichlet boundary conditions applied to vertices.
- Fixed numerous bugs related to explicit time integration for
dynamic problems.
- Eliminated several small memory errors.
- Fixed several bugs associated with writing VTK files in parallel.
* Known issues
- PyLith still uses much more memory that PyLith 0.8 due to the
current general Sieve implementation. A much more efficient,
albeit less general Sieve implementation is under
development. Additionally, distribution of the mesh will also be
improved in a future release.
- The preconditioner for explicit time stepping provides
relatively poor overall performance compared to a direct solve
with traditional mass lumping. An appropriate preconditioner and
traditional mass lumping will be supported in a future release.
----------------------------------------------------------------------
Version 1.0.2
----------------------------------------------------------------------
* Performance optimizations have significantly reduced runtime and
memory use relative to version 1.0.1. The default quadrature order
for tetrahedral cells is now 1, which is appropriate for the
default basis functions.
* Added checks to verify the compatibility of quadrature scheme for solid
and cohesive cells.
* Bug fixes
- In some cases, cohesive cells were not inserted into the
finite-element mesh properly. The cells mixed together vertices
from the different sides of the fault. A more efficient
procedure for creating cohesive cells fixed this problem.
- Cell adjacency graph was created incorrectly which resulted in
a poor quality of partitioning among processors.
- VTK output for meshes with N faults included cohesive cells
for N-1 faults. Since VTK output does not understand cohesive
cells, we now remove all cohesive cells from the VTK output.
- Using the SimpleDB in Spatialdata from Python limited
interpolation to the "linear" scheme instead of allowing use of
the "nearest" scheme. Setting the SimpleDB property to "nearest"
and "linear" now works as expected.
- The reader for Spatialdata coordinate systems information did not
correctly putback characters in the input stream, resulting in
reading errors. The putback routines were fixed.
- Fault "up" and "normal" directions remained as string arrays
when passed to the module, instead of being converted to float
arrays.
----------------------------------------------------------------------
Version 1.0.1
----------------------------------------------------------------------
* Bug fixes
- Cohesive cells lacked consistent orientation (inconsistent
normals) in cases where cells were not ordered one side of the
fault and then the other.
- Final slip of zero resulted in fault slip and slip increments
of Nan.
- Parallel importing of meshes from LaGrit and CUBIT lacked
guards against all processors reading the files.
----------------------------------------------------------------------
Version 1.0.0
----------------------------------------------------------------------
* Code now includes both dynamic and quasi-static solutions.
* Completely rewritten in Python and C++, with bindings provided by
Pyrex/Pyrexembed.
* Easier specification of simulations:
- Parameters are all set using .cfg files (or .pml/command-line).
- Mesh may be directly imported from CUBIT, LaGriT, or using
PyLith mesh ASCII format.
- Material properties, fault dislocations, and BC are all given
using spatial databases, which are independent of mesh
discretization.
* Faults are now implemented using cohesive elements:
- Easy specification of kinematic fault slip using a spatial
database.
- Cohesive elements generate offsets in the mesh corresponding
to fault slip, which increase the accuracy of displacement
fields near faults and facilitate visualization of fault slip.
- Usage of cohesive elements will facilitate the upcoming
addition of fault constitutive relations, where fault slip
occurs in response to prescribed physics.
* Improved implicit time-stepping eliminates need to perform more
than one iteration for linear rheologies.
* Code is now completely modular and object-oriented, which allows
much easier addition of new features. Modules may be added
without having to recompile the code.
* Features present in 0.8 that are not present in 1.0 that will be
added in the near future.
- Traction boundary conditions
- Generalized Maxwell and Power-law Maxwell viscoelastic models