Tutorial 2: Using Two Bilinear Quadrilaterals and PyLith Mesh ASCII Format

In this tutorial, we will walk through the steps necessary to construct, run, and view three problems that use the same mesh. In addition to this manual, each of the files for the example problem is heavily documented to aid users in understanding the basic file formats.

Mesh Description

The mesh consists of two square cells with edge lengths of one forming a regular region (Figure 5).

The mesh geometry and topology are described in the file twoquad4.mesh, which is in PyLith mesh ASCII format. This file format is described in Appendix B in the PyLith User Manual. This file describes the dimensionality of the problem (1D, 2D, or 3D), the coordinates of the vertices (nodes), the vertices composing each cell (element), the material ID to be associated with each cell, and then provides groups of vertices that may be used to define faults or surfaces to which boundary conditions may be applied.

Additional Common Information

In addition to the mesh, the three example problems share additional information. For problems of this type, it is generally useful to create a file named pylithapp.cfg in the run directory, since this file is read automatically every time PyLith is run. Settings specific to a particular problem may be placed in other .cfg files, as described later, and then those files are placed on the command line. The settings contained in pylithapp.cfg for this problem consist of:

pylithapp.journal.info

Settings that control the verbosity of the output for the different components.

pylithapp.mesh_generator

Settings that control mesh importing, such as the importer type, the filename, and the spatial dimension of the mesh.

pylithapp.timedependent

Settings that control the problem, such as the total time, time step size, and spatial dimension.

pylithapp.timedependent.materials

Settings that control the material type, specify which material IDs are to be associated with a particular material type, and give the name of the spatial database containing material parameters for the mesh. The quadrature information is also given.

pylithapp.petsc

PETSc settings to use for the problem, such as the preconditioner type.

All of the problems in this directory use the same material database, as specified under:

    pylithapp.timedependent.materials 

in pylithapp.cfg. This information is contained in the file matprops.spatialdb. Although the material model is specified in pylithapp.cfg, the parameters for the material model are given in matprops.spatialdb. For this example, values describing elastic plane strain material properties are given at a single point, resulting in uniform material properties.

Axial Displacement Example

The first example problem is extension of the mesh along the x axis. Parameter settings that override or augment those in pylithapp.cfg are contained in the file axialdisp.cfg. These settings are:

pylithapp.timedependent

Specifies an implicit formulation for the problem and specifies a container for boundary conditions (pylith.bc.BCFourSides) that allows them to be given along the edges of a rectangular domain.

pylithapp.timedependent.bc.x_neg

Specifies the boundary conditions for the left side of the mesh, defining which degrees of freedom are being constrained (x), giving the label (defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (axialdisp.spatialdb).

pylithapp.timedependent.bc.x_pos

Specifies the boundary conditions for the right side of the mesh, defining which degrees of freedom are being constrained (x), giving the label (defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (axialdisp.spatialdb).

pylithapp.timedependent.bc.y_neg

Specifies the boundary conditions for the bottom two corners of the mesh, defining which degrees of freedom are being constrained (y), giving the label (defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (axialdisp.spatialdb).

pylithapp.problem.formulation.output.output

Gives the base filename for VTK output (axialdisp.vtk).

The boundary conditions are described in the file axialdisp.spatialdb, as specified in axialdisp.cfg. In this case, the desired displacement values is given at two points. Since data is being specified at points (rather than being uniform over the mesh, for example), the data dimension is one.

The files containing common information (twoquad4.mesh, pylithapp.cfg, matprops.spatialdb) along with the problem-specific files (axialdisp.cfg, axialdisp.spatialdb) provide a complete description of the problem, and we can then run this example by typing:

    pylith axialdisp.cfg

Once the problem has run, a file called axialdisp_t0.vtk is produced which may be used with a number of visualization packages. If the problem ran correctly, you should be able to generate a figure such as the one below, which was generated using ParaView.

Shear Displacement Example

The next example problem is shearing of the mesh in the y direction using displacements applied along the positive and negative x boundaries. Parameter settings that override or augment those in pylithapp.cfg are contained in the file sheardisp.cfg. These settings are:

pylithapp.timedependent

Specifies an implicit formulation for the problem and specifies a container for boundary conditions (pylith.bc.BCFourSides) that allows them to be given on four sides of a rectangular domain.

pylithapp.timedependent.bc.x_neg

Specifies the boundary conditions for the left side of the mesh, defining which degrees of freedom are being constrained (x and y), giving the label (x_neg, defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (sheardisp.spatialdb).

pylithapp.timedependent.bc.x_pos

Specifies the boundary conditions for the left side of the mesh, defining which degrees of freedom are being constrained (y only), giving the label (x_pos, defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (sheardisp.spatialdb).

pylithapp.problem.formulation.output.output

Gives the base filename for VTK output (sheardisp.vtk).

The boundary conditions are described in the file sheardisp.spatialdb, as specified in sheardisp.cfg. In this case, the desired displacement values are given at two points, corresponding to the two edges we want to constrain. Since data is being specified at points (rather than being uniform over the mesh, for example), the data dimension is one.

The files containing common information (twoquad4.mesh, pylithapp.cfg, matprops.spatialdb) along with the problem-specific files (sheardisp.cfg, sheardisp.spatialdb) provide a complete description of the problem, and we can then run this example by typing:

    pylith sheardisp.cfg

Once the problem has run, a file called sheardisp_t0.vtk, is produced which may be used with a number of visualization packages. If the problem ran correctly, you should be able to generate a figure such as the one below, which was generated using ParaView.

Kinematic Fault Slip Example

The next example problem is left lateral fault slip applied between the two square cells using kinematic cohesive cells. The left and right boundaries are held fixed in the x and y directions. Parameter settings that override or augment those in pylithapp.cfg are contained in the file dislocation.cfg. These settings are:

pylithapp.journal.info

Turns on journaling for 1D quadrature (used for 2D faults) and for cohesive kinematic faults.

pylithapp.timedependent

Specifies an implicit formulation for the problem, specifies a container for boundary conditions (pylith.bc.BCFourSides) that allows them to be given along the edges of a rectangular domain, and specifies a container for a single fault (pylith.faults.SingleFault).

pylithapp.timedependent.bc.x_neg

Specifies the boundary conditions for the left side of the mesh, defining which degrees of freedom are being constrained (x and y), giving the label (x_neg, defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (dislocation_disp.spatialdb).

pylithapp.timedependent.bc.x_pos

Specifies the boundary conditions for the left side of the mesh, defining which degrees of freedom are being constrained (x and y), giving the label (x_pos, defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial database defining the boundary conditions (dislocation_disp.spatialdb).

pylithapp.timedependent.interfaces

Gives the label (defined in twoquad4.mesh) defining the points on the fault, provides quadrature information, and then gives database names for material properties (needed for conditioning), fault slip, fault slip rate, and fault slip time.

pylithapp.problem.formulation.output.output

Gives the base filename for VTK output (dislocation.vtk).

The boundary conditions are described in the file dislocation_disp.spatialdb, as specified in dislocation.cfg. In this case, the desired displacement values are given for two points. Since data is being specified at points, the data dimension is one.

The fault example requires three additional database files that were not needed for the simple displacement examples. The first file (dislocation_slip.spatialdb) specifies 0.01 m of left-lateral fault slip for the entire fault. The data dimension is zero since the same data is applied to all points in the set. It is also necessary to specify the slip rate, which is done in the file dislocation_sliprate.spatialdb. The slip rate of 1.0e6 m/s is essentially instantaneous. Finally, we must provide the time at which slip begins. The elastic solution begins at t=-dt, so this is the value given (t=-1\sec ) in dislocation_sliptime.spatialdb.

The files containing common information (twoquad4.mesh, pylithapp.cfg, matprops.spatialdb) along with the problem-specific files (dislocation.cfg, dislocation_disp.spatialdb, dislocation_slip.spatialdb, dislocation_sliprate.spatialdb, dislocation_sliptime.spatialdb) provide a complete description of the problem, and we can then run this example by typing:

    pylith dislocation.cfg

Once the problem has run, a file called dislocation_t0.vtk is produced which may be used with a number of visualization packages. If the problem ran correctly, you should be able to generate a figure such as the one below, which was generated using ParaView.