[cig-commits] r7372 - in short/3D/PyLith/trunk/doc/userguide: .
boundaryconditions install materials runpylith
brad at geodynamics.org
brad at geodynamics.org
Fri Jun 22 06:27:51 PDT 2007
Author: brad
Date: 2007-06-22 06:27:51 -0700 (Fri, 22 Jun 2007)
New Revision: 7372
Added:
short/3D/PyLith/trunk/doc/userguide/glossary.lyx
Modified:
short/3D/PyLith/trunk/doc/userguide/TODO
short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx
short/3D/PyLith/trunk/doc/userguide/install/install.lyx
short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx
short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx
short/3D/PyLith/trunk/doc/userguide/userguide.lyx
Log:
Worked on several sections of the manual.
Modified: short/3D/PyLith/trunk/doc/userguide/TODO
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/TODO 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/TODO 2007-06-22 13:27:51 UTC (rev 7372)
@@ -19,58 +19,19 @@
7. Governing equations [MOSTLY DONE]
- Needs some checking. [Charles]
+ Needs some checking. [CHARLES]
-8. Installing binary PyLith [Charles with some input from Leif]
+8. Running PyLith (an overview) [PRETTY MUCH DONE?]
-9. Running PyLith (an overview) [Charles with some input from Brad]
+9. Installing binary PyLith
- a. Basic pieces needed to run problem
+ [CHARLES- NEED TO GET BINARY AND WRITE INSTRUCTIONS]
- b. Setting parameters for PyLith
+ Installation from source [Leif will write after CFEM]
- i. Command line
- ii. .cfg file
+11. Tutorials (all using ascii mesh format?) [CHARLES]
- iii. .pml file
-
- iv. Placement of .cfg files
-
- v. PETSc settings
-
- c. Mesh information
-
- d. Database information
-
- e. Implicit problems
-
- f. Explicit problems
-
-10. Installation from source [Leif will write after CFEM]
-
- C++, Python
-
- Numpy
-
- FIAT
-
- PETSc/MPI
-
- Pythia
-
- nemesis
-
- Pyrex/Pyrexembed
-
- spatialdata and proj
-
- optional
-
- netcdf
-
-11. Tutorials (all using ascii mesh format?) [Charles]
-
a. Two-triangle problem.
i. Dirichlet boundary conditions (shear)
@@ -92,33 +53,27 @@
12. Material models (should be able to copy from 0.8 with some editing) [Charles]
- a. Specifying .cfg and spatial database info.
+ a. Specifying .cfg and spatial database info.
- b. Existing material models.
+ [BRAD - needs to add a little more]
- * ElasticStrain1D [DONE]
-
- * ElasticStress1D [DONE]
-
- * ElasticPlaneStrain [Brad]
-
- * ElasticPlaneStress [Brad]
-
- * ElasticIsotropic3D [DONE]
-
* MaxwellIsotropic3D [Charles]
- Need to rewrite formulation in terms of mu and lambda.
+ [CHARLES - need to rewrite formulation in terms of mu and lambda]
+ [CHARLES - also list material modesl that will be added soon]
+
c. List material models in 0.8 that will be added soon.
-13. Boundary and interface conditions (includes faults) [Charles]
+13. Boundary and interface conditions (includes faults)
+ [BRAD]
+
a. Specifying .cfg and spatial database info.
b. Dirichlet conditions.
- c. Neumann conditions. [future]
+ c. Neumann conditions. [to be added in the future]
d. Fault
@@ -128,20 +83,8 @@
iii. Kinematic earthquake source
-14. Appendix [Charles]
+14. Appendix [BRAD]
- a. glossary
- sieve
- mesh
- cell (element)
- vertex (node)
- field
- section
- fiber dimension
- cohesive cell
- cone
- restrict
-
b. File formats (config, ascii mesh format, and spatial data).
Modified: short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx 2007-06-22 13:27:51 UTC (rev 7372)
@@ -30,23 +30,413 @@
\begin_body
\begin_layout Chapter
-Boundary and Interface Conditions
+\begin_inset LatexCommand \label{cha:boundary:interface:conditions}
+
+\end_inset
+
+Boundary and Interface Conditions
\end_layout
+\begin_layout Section
+Assigning Boundary Conditions
+\end_layout
+
\begin_layout Standard
-(includes faults)
+There are four basic steps in assigning a specific boundary condition to
+ a portion of the domain.
\end_layout
-\begin_layout Itemize
-a.
- Specifying .cfg and spatial database info.
+\begin_layout Enumerate
+Create sets of vertices in the mesh generation process for each boundary
+ condition.
\end_layout
-\begin_layout Itemize
-b.
- Dirichlet conditions.
- 82%
+\begin_layout Enumerate
+Create a container to hold the various boundary conditions unless a suitable
+ one already exists.
\end_layout
+\begin_layout Enumerate
+Set the parameters for each boundary condition in the boundary condition
+ container using .cfg or pml files and/or command line arguments.
+\end_layout
+
+\begin_layout Enumerate
+Specify the spatial variation in parameters for the boundary condition using
+ a spatial database file.
+\end_layout
+
+\begin_layout Subsection
+Creating Sets of Vertices
+\end_layout
+
+\begin_layout Standard
+The procedure for creating sets of vertices differs depending on the mesh
+ generator.
+ For meshes specified using the PyLith mesh ASCII format, the sets of vertices
+ are specified using groups (see Section
+\begin_inset LatexCommand \ref{sec:MeshIOAscii}
+
+\end_inset
+
+).
+ In CUBIT the groups of vertices are created using nodesets.
+ Similarly, in LaGriT psets are used.
+ Note that we chose to associated boundary conditions with groups of vertices
+ because nearly every mesh generation package supports associating a string
+ or integer with groups of vertices.
+ Note that we currently associate boundary conditions with string identifiers,
+ so even if the mesh generator uses integers, the name is specified as the
+ digits of the integer value.
+
+\end_layout
+
+\begin_layout Subsection
+Boundary Conditions Container
+\end_layout
+
+\begin_layout Standard
+The boundary condition container associates a type of boundary condition
+ with a string label.
+ Because the number of boundary conditions depends on the problem and Pyre
+ does not support dynamic arrays of components, a generic boundary condition
+ container is not yet available.
+ However, we supply containers for one, two, four, and six boundary conditions.
+ Table
+\begin_inset LatexCommand \ref{tab:bc:containers}
+
+\end_inset
+
+ gives the predefined boundary condition containers.
+ The default boundary condition for in each of the containers is the Dirichlet
+ boundary condition.
+ If no parameters are specified for the boundary condition, it is not used.
+ For problems with more than six boundary conditions, the user must create
+ the container using an an .odb file (a template is provided in the examples/temp
+lates directory of the PyLith distribution).
+ This .odb file should be placed in the directory with the other simulation
+ input files.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0.75in">
+<column alignment="center" valignment="top" leftline="true" width="1.3in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="2.47in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Container
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\series bold
+Number of Boundary Conditions
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Container Facilities
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+BCSingle
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+bc
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+BCTwoSides
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+neg, pos
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+BCFourSides
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+x_neg, x_pos, y_neg, y_pos
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+BCSixSides
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+6
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+x_neg, x_pos, y_neg, y_pos, z_neg, z_pos
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+\begin_inset LatexCommand \label{tab:bc:containers}
+
+\end_inset
+
+Predefined boundary condition containers.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+Dirichlet boundary conditions prescribe a fixed value of slip at vertices
+ of the finite-element mesh.
+ While Dirichlet boundary conditions can be applied to any vertex, usually
+ they are applied to vertices on the lateral and bottom boundaries of the
+ domain.
+ Currently, time dependent displacements are not supported.
+ Allowing time variation of the prescribed displacements on the boundaries
+ will likely be available in a future release.
+\end_layout
+
+\begin_layout Subsection
+Dirichlet Boundary Condition Parameters
+\end_layout
+
+\begin_layout Standard
+The principal parameters for the Dirichlet boundary condition are:
+\end_layout
+
+\begin_layout Description
+id This is an integer identifier for the boundary condition.
+ It is not used in the current implementation.
+\end_layout
+
+\begin_layout Description
+name Name or label for the boundary condition.
+ This associates sets of vertices with the boundary condition in addition
+ to being used in error and diagnostic reports.
+\end_layout
+
+\begin_layout Description
+db Spatial database specifying the spatial variation in the displacement
+ field.
+\end_layout
+
+\begin_layout Description
+fixed_dof Array of degrees of freedom to be fixed (first degree of freedom
+ is 0)
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a .cfg file for the homogeneous
+ material is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem]
+\end_layout
+
+\begin_layout LyX-Code
+bc = pylith.bc.BCTwoSides
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.bc.pos]
+\end_layout
+
+\begin_layout LyX-Code
+label = face A
+\end_layout
+
+\begin_layout LyX-Code
+db.iohandler.filename = disp_A.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db.query_type = nearest
+\end_layout
+
+\begin_layout LyX-Code
+fixed_dof = [2]
+\end_layout
+
+\begin_layout Standard
+where we have specified that we want to use the BCTwoSides boundary condition
+ container, the group of vertices has the label
+\begin_inset Quotes eld
+\end_inset
+
+face A
+\begin_inset Quotes erd
+\end_inset
+
+, the spatial database query should use the nearest point algorithm, and
+ motion in the z-direction is constrained.
+ See Chapter
+\begin_inset LatexCommand \ref{sec:Spatialdata:SimpleIOAscii}
+
+\end_inset
+
+ for a complete list of the spatial database settings.
+
+\end_layout
+
+\begin_layout Subsection
+Dirichlet Boundary Condition Spatial Database Files
+\end_layout
+
+\begin_layout Standard
+[ADD STUFF HERE]
+\end_layout
+
+\begin_layout Section
+Neumann Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+Neumann (traction) boundary conditions are not implemented in this release.
+ We hope to include these in the next release.
+\end_layout
+
+\begin_layout Section
+Fault Interface Conditions
+\end_layout
+
+\begin_layout Subsection
+Conventions
+\end_layout
+
+\begin_layout Subsection
+Fault Implementation
+\end_layout
+
+\begin_layout Subsection
+Kinematic Earthquake Source
+\end_layout
+
\end_body
\end_document
Added: short/3D/PyLith/trunk/doc/userguide/glossary.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/glossary.lyx 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/glossary.lyx 2007-06-22 13:27:51 UTC (rev 7372)
@@ -0,0 +1,98 @@
+#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 245
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\language english
+\inputencoding latin1
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\cite_engine basic
+\use_bibtopic false
+\paperorientation portrait
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+\begin_inset LatexCommand \label{cha:Glossary}
+
+\end_inset
+
+Glossary
+\end_layout
+
+\begin_layout Description
+sieve ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+mesh ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+cell ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+vertex ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+field ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+section ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+fiber\InsetSpace \space{}
+dimension ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+cohesive\InsetSpace \space{}
+cell ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+cone ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+restrict ADD DEFINITION
+\end_layout
+
+\begin_layout Description
+support ADD DEFINITION
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\end_body
+\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/install/install.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/install/install.lyx 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/install/install.lyx 2007-06-22 13:27:51 UTC (rev 7372)
@@ -44,113 +44,38 @@
Installation and Getting Help
\end_layout
-\begin_layout Section
-Installation of Binary Executable
-\end_layout
-
\begin_layout Standard
-[ADD STUFF HERE]
+Installation of PyLith on a desktop or laptop machine is, in most cases,
+ very easy.
+ Binary packages have been created for the most common platforms, including
+ Linux, Mac OS X, and Windows.
+ Installation on machines that are not compatible with any of these operating
+ systems requires building the software from the source code, which can
+ be difficult for inexperienced users.
+ Help is available from both a CIG mailing list and a roundup bug tracking
+ system.
\end_layout
\begin_layout Section
-Installation from Source
+Getting Help and Reporting Bugs
\end_layout
\begin_layout Standard
-PyLith 1.0 depends on a number of other packages.
- This complicates building the software from the source code.
- In many cases some of the packages required by PyLith are available as
- binary packages.
- On the one hand, using these packages removes the burden of configuring,
- building, and installing these packages, but it can come with its own host
- of complications if a consistent compiler and configuration settings are
- not used across all of the packages on which PyLith depends.
- This is usually not an issue with Linux distributions, such as Fedora,
- Ubuntu, and Debian that have good quality control; it can be an issue with
- Darwin package managers, such as Fink, where there is limited enforcement
- of consistency across pacakges.
- Nevertheless, PyLith can be built on most systems provided the instructions
- are followed carefully.
- PyLith is developed and tested on Linux and Mac OS X.
-\end_layout
-
-\begin_layout Subsection
-Introduction
-\end_layout
-
-\begin_layout Standard
-Installing PyLith is a three-stage process:
-\end_layout
-
-\begin_layout Enumerate
-Install the development version of PETSc (Section
-\begin_inset LatexCommand \vref{sec:Installing-PETSc}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Enumerate
-Install PyLith (Section
-\begin_inset LatexCommand \vref{sec:Installing-PyLith}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Enumerate
-Configure Pyre to launch parallel runs of PyLith (Section
-\begin_inset LatexCommand \vref{sec:Pyre-Configuration}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Standard
-Each stage is substantially faster and easier than the one before it.
- In fact, after successfully installing PETSc, you are close to being done.
- So review Section
-\begin_inset LatexCommand \ref{sec:System-Requirements}
-
-\end_inset
-
- to make sure you have the required tools at hand; and then proceed fearlessly,
- dear reader, to Section
-\begin_inset LatexCommand \ref{sec:Installing-PETSc}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-Advanced users and software developers may be interested in downloading
- the latest PyLith and PETSc source code directly from the source code repositor
-ies, instead of using the prepared source packages; see Section
-\begin_inset LatexCommand \ref{sec:Software-Repository}
-
-\end_inset
-
- later in this chapter.
-\end_layout
-
-\begin_layout Section
-Getting Help
-\end_layout
-
-\begin_layout Standard
Help is available via the CIG Short-Term Crustal Dynamics Mailing List and
CIG's issue tracking system.
- The mailing list
-\begin_inset LatexCommand \htmlurl[cig-short at geodynamics.org]{http://geodynamics.org/cig/lists/cig-short}
+ The
+\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
\end_inset
is dedicated to CIG issues associated with short-term crustal dynamics,
including the use of PyLith.
+ You can subscribe to the mailing list and view messages at
+\begin_inset LatexCommand \htmlurl[CIG Mailing Lists]{www.geodynamics.org/cig/lists/}
+
+\end_inset
+
+.
CIG uses
\family typewriter
Roundup
@@ -162,9 +87,9 @@
\end_inset
.
- You should first check to see if someone else already submitted a report
- related to the issue; one of the CIG developers may have posted a solution
- to the problem.
+ Of course, it is helpful to first check to see if someone else already
+ submitted a report related to the issue; one of the CIG developers may
+ have already posted a solution to the problem.
You can reply to a current issue by clicking on the issue title.
To submit a new issue, click
\family sans
@@ -178,2485 +103,44 @@
\end_layout
\begin_layout Section
-\begin_inset LatexCommand \label{sec:System-Requirements}
-
-\end_inset
-
-System Requirements
+Installation of Binary Executable
\end_layout
\begin_layout Standard
-Installation of PyLith requires the following:
+[ADD MORE DETAIL HERE AFTER LOOKING AT BINARY PACKAGE]
\end_layout
-\begin_layout Itemize
-A C++ compiler
-\end_layout
-
-\begin_layout Itemize
-Python 2.3 or greater (Python 2.4 or greater is required on 64-bit machines)
-\end_layout
-
-\begin_layout Itemize
-The development version of PETSc
-\end_layout
-
-\begin_layout Subsection
-C++ Compiler
-\end_layout
-
-\begin_layout Standard
-A C++ compiler is required for building PETSc's Sieve component and the
- PyLith components that interface with Sieve.
- The C++ compiler is also used to compile the layer which connects the high-leve
-l Python code with the low-level Fortran code.
-\end_layout
-
-\begin_layout Standard
-On Unix systems, there is a high likelihood that a usable C++ compiler is
- already installed.
- Check with your system administrator if you are unsure of the name of the
- C++ compiler command.
-\end_layout
-
-\begin_layout Standard
-On Linux, the standard C++ compiler is
-\family typewriter
-g++
-\family default
-.
- If the
-\family typewriter
-g++
-\family default
- command is not available, install GCC using the package manager for your
- distribution.
-\end_layout
-
-\begin_layout Standard
-The Mac OS X version of GCC is included in a software development suite
- called Xcode.
- Xcode is available as a free download at the
-\begin_inset LatexCommand \htmlurl[Apple Developer Connection]{developer.apple.com}
-
-\end_inset
-
-.
- (Note that Xcode does not include a Fortran compiler.)
-\end_layout
-
-\begin_layout Subsection
-Python
-\end_layout
-
-\begin_layout Standard
-PyLith's high-level user interface code is written in Python, utilizing
- the Pyre framework.
- Pyre is included in the Python package known as Pythia.
- PyLith requires Pythia v0.8.1.3 or later, but you need not install Pythia
- because PyLith's
-\family typewriter
-configure
-\family default
- script automatically downloads Pythia directly from CIG.
-\end_layout
-
-\begin_layout Standard
-Pythia (and therefore PyLith) requires Python 2.3 or later.
-\end_layout
-
-\begin_layout Quote
-
-\color red
-Warning:
-\color none
- On 64-bit machines, Python 2.4 or later is required.
- Python 2.3 contains a bug which prevents installation on 64-bit hardware.
-\end_layout
-
-\begin_layout Standard
-Your system may already have a suitable Python interpreter installed.
- To check, type the `
-\family typewriter
-python
-\family default
-' command:
-\end_layout
-
-\begin_layout LyX-Code
-$ python -V
-\end_layout
-
-\begin_layout LyX-Code
-Python 2.3.4
-\end_layout
-
-\begin_layout Standard
-Mac OS X 10.3 and later ships with a suitable version of Python preinstalled.
- If you're using an older version of Mac OS X, or for more information in
- general, see
-\begin_inset LatexCommand \htmlurl[Python on the Mac]{www.python.org/download/mac}
-
-\end_inset
-
- at the Python web site.
-\end_layout
-
-\begin_layout Standard
-On Linux, simply install the binary system package available for your distributi
-on.
- Be sure to select the Python development package (typically called
-\family typewriter
-python-dev
-\family default
-) in addition to the core Python package -- even if you don't plan on doing
- any Python software development.
- The development package contains the Python
-\family typewriter
-include
-\family default
- files, which are necessary for building PyLith.
-\end_layout
-
-\begin_layout Standard
-If you are working on a cluster and
-\family typewriter
-python
-\family default
- is too old, try poking around a little.
- Sometimes multiple versions of Python are installed on the same system:
-\end_layout
-
-\begin_layout LyX-Code
-$ python -V
-\end_layout
-
-\begin_layout LyX-Code
-Python 2.2.3
-\end_layout
-
-\begin_layout LyX-Code
-$ which python
-\end_layout
-
-\begin_layout LyX-Code
-/usr/bin/python
-\end_layout
-
-\begin_layout LyX-Code
-$ ls /usr/bin/python*
-\end_layout
-
-\begin_layout LyX-Code
-/usr/bin/python /usr/bin/python2 /usr/bin/python2.2
-\end_layout
-
-\begin_layout LyX-Code
-/usr/bin/python24 /usr/bin/python2.4
-\end_layout
-
-\begin_layout LyX-Code
-$
-\end_layout
-
-\begin_layout Standard
-In the above scenario, it is useful to create an alias to the newer Python:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd ~/bin
-\end_layout
-
-\begin_layout LyX-Code
-$ ln -s /usr/bin/python2.4 python
-\end_layout
-
-\begin_layout LyX-Code
-$ cd
-\end_layout
-
-\begin_layout LyX-Code
-$ hash -r
-\end_layout
-
-\begin_layout LyX-Code
-$ which python
-\end_layout
-
-\begin_layout LyX-Code
-~/bin/python
-\end_layout
-
-\begin_layout LyX-Code
-$ python -V
-\end_layout
-
-\begin_layout LyX-Code
-Python 2.4.1
-\end_layout
-
-\begin_layout LyX-Code
-$
-\end_layout
-
-\begin_layout Standard
-If absolutely necessary, one can easily build Python from source using a
- C compiler.
- You can download Python from the
-\begin_inset LatexCommand \htmlurl[Python website]{www.python.org}
-
-\end_inset
-
-.
-
-\end_layout
-
-\begin_layout Subsection
-PETSc
-\end_layout
-
-\begin_layout Standard
-PyLith requires PETSc -- including PETSc's new Sieve component.
- Sieve is still under development; as of this writing, Sieve is only available
- in the development version of PETSc.
-\end_layout
-
-\begin_layout Standard
-PETSc itself depends upon several other sofware packages.
- Fortunately, PETSc's configuration script can automatically download and
- build these software packages for you.
-\end_layout
-
-\begin_layout Standard
-For general information about the development version of PETSc, visit
-\begin_inset LatexCommand \htmlurl[the PETSc Developers Site]{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/}
-
-\end_inset
-
-.
-\end_layout
-
\begin_layout Section
-\begin_inset LatexCommand \label{sec:Installing-PETSc}
-
-\end_inset
-
-Installing PETSc
+Installation from Source
\end_layout
\begin_layout Standard
-To install PETSc, you will download and unpack the
-\family typewriter
-petsc-dev
-\family default
- tarball, run a Python configure script (
-\family typewriter
-config/configure.py
-\family default
-), set a pair of environment variables, and finally build PETSc from source
- by running
-\family typewriter
-make
-\family default
-.
+PyLith 1.0 depends on a number of other packages.
+ This complicates building the software from the source code.
+ In many cases some of the packages required by PyLith are available as
+ binary packages.
+ On the one hand, using these packages removes the burden of configuring,
+ building, and installing these packages, but it can come with its own host
+ of complications if a consistent compiler and configuration settings are
+ not used across all of the packages on which PyLith depends.
+ This is usually not an issue with Linux distributions, such as Fedora,
+ Ubuntu, and Debian that have good quality control; it can be an issue with
+ Darwin package managers, such as Fink, where there is limited enforcement
+ of consistency across pacakges.
+ Nevertheless, PyLith can be built on most systems provided the instructions
+ are followed carefully.
+ PyLith is developed and tested on Linux and Mac OS X.
\end_layout
-\begin_layout Quote
-
-\series bold
-TIP:
-\series default
-If you run into problems configuring or building PETSc, send
-\emph on
-both
-\family typewriter
-\emph default
- configure.log
-\family default
- and
-\family typewriter
-make_log_
-\emph on
-$PETSC_ARCH
-\family default
-\emph default
- to
-\begin_inset LatexCommand \url[PETSc Maintenance Mailing List]{petsc-maint at mcs.anl.gov}
-
-\end_inset
-
-.
-\end_layout
-
\begin_layout Standard
-For detailed information on installing PETSc, see
-\begin_inset LatexCommand \htmlurl[the PETSc Installation Docs]{http://www-unix.mcs.anl.gov/petsc/petsc-as/documentation/installation.html}
-
-\end_inset
-
-.
+Detailed instructions for building PyLith from source are not yet available.
+ We hope to provide detailed instructions in the very near future.
+ For now, please use the binary executables.
\end_layout
-\begin_layout Subsection
-Downloading and Unpacking
-\family typewriter
-petsc-dev
-\end_layout
-
-\begin_layout Standard
-The development version of PETSc is called
-\family typewriter
-petsc-dev
-\family default
-.
- Download the nightly tarball snapshot of
-\family typewriter
-petsc-dev
-\family default
- from the
-\begin_inset LatexCommand \htmlurl[the PETSc Developers Site]{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/}
-
-\end_inset
-
-.
- Unpack it using the
-\family typewriter
-tar
-\family default
- command:
-\end_layout
-
\begin_layout LyX-Code
-$ tar xzf petsc-dev.tar.gz
-\end_layout
-\begin_layout Standard
-If you don't have GNU Tar, try the following command instead:
\end_layout
-\begin_layout LyX-Code
-$ gunzip -c petsc-dev.tar.gz | tar xf -
-\end_layout
-
-\begin_layout Standard
-After unpacking, a directory called
-\family typewriter
-petsc-dev
-\family default
- will be visible in your working directory.
-\end_layout
-
-\begin_layout Subsection
-PETSc Configuration
-\end_layout
-
-\begin_layout Standard
-Navigate to the directory containing the PETSc source:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ cd petsc-dev
-\end_layout
-
-\begin_layout Standard
-To configure PETSc, run
-\family typewriter
-./config/configure.py
-\family default
- with the appropriate arguments to configure PETSc for your system.
- At a minimum, configuring PETSc for use with PyLith requires the following
- arguments:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---with-clanguage=c++
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---with-boost=1
-\end_layout
-
-\begin_layout LyX-Code
---with-chaco=1
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---with-sieve=1
-\end_layout
-
-\begin_layout Standard
-You will need to specify additional options; the specific set of options
- you will use depends upon the libraries and compilers you have available.
- See the examples below.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-TIP:
-\series default
- Run
-\family typewriter
-./config/configure.py --help
-\family default
- to see the long list of all possible options.
-\end_layout
-
-\begin_layout Standard
-Building PETSc with Sieve requires the following external libraries:
-\end_layout
-
-\begin_layout Itemize
-an MPI library
-\end_layout
-
-\begin_layout Itemize
-BLAS/LAPACK
-\end_layout
-
-\begin_layout Itemize
-Boost
-\end_layout
-
-\begin_layout Itemize
-Chaco
-\end_layout
-
-\begin_layout Standard
-You can instruct PETSc to download and install any or all of these libraries
- for you.
-\end_layout
-
-\begin_layout Standard
-If you have an MPI implementation installed on your workstation, you can
- use it, or let PETSc download and install one for you.
- If you are installing on a cluster, you should configure PETSc to use an
- existing MPI library installed by the system administrators.
-\end_layout
-
-\begin_layout Standard
-If you have an architecture-optimized version of BLAS/LAPACK, you should
- use those instead of asking PETSc to download and build one for you.
- In some cases, PETSc will find known optimized implementations of BLAS/LAPACK
- (e.g., vecLib on Mac OS X).
-\end_layout
-
-\begin_layout Standard
-Be sure to include flags indicating where MPI and BLAS/LAPACK are if you
- want to use a preinstalled implementation.
- If not, be sure to tell PETSc to download those packages.
- If you do not want to build PETSc using the GNU compilers, be sure to let
- PETSc know which compilers you want to use instead.
-\end_layout
-
-\begin_layout Subsubsection
-PETSc Configuration Examples
-\end_layout
-
-\begin_layout Standard
-In our first example, we configure PETSc on a Linux workstation.
- BLAS and LAPACK are preinstalled under
-\family typewriter
-/usr/lib
-\family default
-; PETSc finds these system libraries automatically.
- We happen to have MPICH already installed;
-\family typewriter
-mpicc
-\family default
- and other related MPI commands are accessible via our
-\family typewriter
-PATH
-\family default
-, so PETSc finds our MPICH installation automatically.
- However, we don't have Boost or Chaco installed, so we instruct PETSc to
- download these packages for us.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ ls -1 /usr/lib/libblas.so /usr/lib/liblapack.so
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-/usr/lib/libblas.so
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-/usr/lib/liblapack.so
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ which mpicc
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-/opt/mpich/bin/mpicc
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ ./config/configure.py
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-sieve=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-clanguage=C++
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-boost=1 --download-boost=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-chaco=1 --download-chaco=1
-\end_layout
-
-\begin_layout Standard
-In our next example, we configure PETSc on a Mac OS X machine.
- We have installed Apple's Xcode and the G95 Fortran compiler.
- However, we don't have anything else preinstalled, so we instruct PETSc
- to download almost everything else, including MPICH.
- Intentionally, we don't specify anything about BLAS/LAPACK: PETSc automatically
- finds vecLib, which is built-in to Mac OS X.
-\end_layout
-
-\begin_layout LyX-Code
-$ ./config/configure.py
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-sieve=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-clanguage=C++
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-fc=g95
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-boost=1 --download-boost=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-chaco=1 --download-chaco=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-mpi=1 --download-mpich=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-x=0
-\end_layout
-
-\begin_layout Standard
-In our final example, we configure PETSc on a 64-bit Linux cluster.
- We use an existing MPI implementation installed by the system administrators.
- BLAS/LAPACK is missing, so we instruct PETSc to download it, in addition
- to Boost and Chaco.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ ./config/configure.py
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-sieve=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-clanguage=C++
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-mpi-dir=/opt/mpich/myrinet_mx2g/intel
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --download-f-blas-lapack=1
-\family default
-
-\family typewriter
-
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-boost=1 --download-boost=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-chaco=1 --download-chaco=1
-\end_layout
-
-\begin_layout Subsubsection
-Running
-\family typewriter
-configure.py
-\end_layout
-
-\begin_layout Standard
-After several minutes, the configure script should finish and display the
- PETSc settings.
- Check to make sure these match your expectations before continuing.
-\end_layout
-
-\begin_layout Subsection
-Setting PETSC Environment Variables
-\end_layout
-
-\begin_layout Standard
-Before building PETSc, set the
-\family typewriter
-PETSC_DIR
-\family default
- and
-\family typewriter
-PETSC_ARCH
-\family default
- environment variables.
- Upon completion, the configure script displays instructions for setting
- these two variables:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** Before running "make" your PETSC_ARCH must be specified with:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** setenv PETSC_ARCH linux-gnu-cxx-debug (csh/tcsh)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** PETSC_ARCH=linux-gnu-cxx-debug; export PETSC_ARCH (sh/bash)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** Before running "make" your PETSC_DIR must be specified with:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** setenv PETSC_DIR /opt/petsc-dev (csh/tcsh)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** PETSC_DIR=/opt/petsc-dev; export PETSC_DIR (sh/bash)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-PETSC_ARCH
-\family default
- is a tag identifying this configuration of PETSc.
-
-\family typewriter
-PETSC_DIR
-\family default
- is set to the full path of the top-level directory in the PETSc source
- tree (the
-\family typewriter
-petsc-dev
-\family default
- directory).
- You will want to set these environment variables in your
-\family typewriter
-.bashrc
-\family default
-,
-\family typewriter
-.cshrc
-\family default
-, or similar file.
-\end_layout
-
-\begin_layout Subsection
-Building PETSc
-\end_layout
-
-\begin_layout Standard
-After setting
-\family typewriter
-PETSC_DIR
-\family default
- and
-\family typewriter
-PETSC_ARCH
-\family default
-, run
-\family typewriter
-make
-\family default
- to build PETSc:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ make
-\end_layout
-
-\begin_layout Subsection
-Testing the PETSc Installation
-\end_layout
-
-\begin_layout Standard
-Optionally, you may test your PETSc installation:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ make test
-\end_layout
-
-\begin_layout Standard
-One of the tests will attempt to display some X windows.
- If X windows is not available from the shell in which you run
-\family typewriter
-make test
-\family default
-, then that test will fail.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Installing-PyLith}
-
-\end_inset
-
-Installing PyLith
-\end_layout
-
-\begin_layout Standard
-To install PyLith, you follow the procedure that is commonly used with other
- open source software packages.
- First, download the source package available at the
-\begin_inset LatexCommand \htmlurl[Geodynamics Software Packages web page]{www.geodynamics.org/cig/software/packages}
-
-\end_inset
-
-.
- After unpacking the source, you run a prepackaged shell script to configure
- PyLith for your system.
- Finally, you use the
-\family typewriter
-make
-\family default
- utility to build and install PyLith from source.
-
-\end_layout
-
-\begin_layout Subsection
-Downloading and Unpacking the PyLith Source
-\end_layout
-
-\begin_layout Standard
-Download PyLith from the
-\begin_inset LatexCommand \htmlurl[Geodynamics website]{www.geodynamics.org}
-
-\end_inset
-
-.
- Click the
-\family sans
-software
-\family default
- tab at the top of the page.
- Then click
-\family sans
-Software Packages
-\family default
-, then
-\family sans
-Short-Term Crustal Dynamics
-\family default
-.
- Once you click the PyLith link, download the source archive and unpack
- it using the
-\family typewriter
-tar
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xzf pylith3d-0.8.2.tar.gz
-\end_layout
-
-\begin_layout Standard
-If you don't have GNU Tar, try the following command instead:
-\end_layout
-
-\begin_layout LyX-Code
-$ gunzip -c pylith3d-0.8.2.tar.gz | tar xf -
-\end_layout
-
-\begin_layout Subsection
-PyLith Installation Procedure
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-TIP:
-\series default
- If you run into problems configuring or building PyLith, send both the
-
-\family typewriter
-config.log
-\family default
- and
-\family typewriter
-make.log
-\family default
- files to the
-\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
-
-\end_inset
-
-.
- To create the
-\family typewriter
-make.log
-\family default
- file, redirect the output of
-\family typewriter
-make
-\family default
- to a file:
-\family typewriter
-make
-\begin_inset Formula $>$
-\end_inset
-
- make.log
-\family default
-.
-
-\end_layout
-
-\begin_layout Standard
-After unpacking the source, use the following procedure to install PyLith:
-\end_layout
-
-\begin_layout Enumerate
-Navigate (i.e.,
-\family typewriter
-cd
-\family default
-) to the directory containing the PyLith source
-\family typewriter
-.
-\newline
-
-\newline
-$ cd pylith3d-0.8.2
-\end_layout
-
-\begin_layout Enumerate
-Type .
-\family typewriter
-/configure
-\family default
- to configure the package for your system
-\family typewriter
-.
-\newline
-
-\newline
-$ ./configure
-\end_layout
-
-\begin_layout Enumerate
-Type
-\family typewriter
-make
-\family default
- to build the package.
-\family typewriter
-
-\newline
-
-\newline
-$ make
-\end_layout
-
-\begin_layout Standard
-If you are content to run PyLith from the build directory, then you are
- done.
- Upon successful completion, the
-\family typewriter
-make
-\family default
- command creates a script called
-\family typewriter
-pylith3dapp.py
-\family default
- in the
-\family typewriter
-pylith3d
-\family default
- subdirectory; this is the script you will use to run PyLith.
- You may wish to add the
-\family typewriter
-pylith3d
-\family default
- directory to your
-\family typewriter
-PATH
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-For more details about
-\family typewriter
-configure
-\family default
-, see Section
-\begin_inset LatexCommand \ref{sec:Configuration}
-
-\end_inset
-
- below.
-\end_layout
-
-\begin_layout Subsubsection
-Installing PyLith to a Secondary Location
-\end_layout
-
-\begin_layout Standard
-Optionally, after building PyLith, you can install it in a secondary location
- using the
-\family typewriter
-make install
-\family default
- command.
-\end_layout
-
-\begin_layout Quotation
-
-\series bold
-Note:
-\series default
- The following is not recommended if you plan on modifying the PyLith source.
-\end_layout
-
-\begin_layout Standard
-By default, PyLith is configured to install under
-\family typewriter
-/usr/local
-\family default
-, which requires that you become
-\family typewriter
-root
-\family default
- before issuing the
-\family typewriter
-make install
-\family default
- command.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ su
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-Password:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-# make install
-\end_layout
-
-\begin_layout Standard
-To install as an ordinary user instead of
-\family typewriter
-root
-\family default
-, give
-\family typewriter
-configure
-\family default
- the
-\family typewriter
---prefix
-\family default
- option, specifying a directory to which you have write access:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd
-\family typewriter
-pylith3d-0.8.2
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --prefix=$HOME/cig
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ make install
-\end_layout
-
-\begin_layout Standard
-The above commands will install PyLith under
-\family typewriter
-$HOME/cig
-\family default
-.
- Afterwards, you may wish to add
-\family typewriter
-PREFIX/bin
-\family default
- (
-\family typewriter
-$HOME/cig/bin
-\family default
-, in this example) to your
-\family typewriter
-PATH
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-After running
-\family typewriter
-make install
-\family default
-, you may (if desired) run
-\family typewriter
-make clean
-\family default
- in the build directory to save disk space.
- You are also free to delete the source/build directory altogether.
- (Note that
-\family typewriter
-make install
-\family default
- installs the examples under
-\family typewriter
-PREFIX/share/pylith3d/examples
-\family default
-.)
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:Configuration}
-
-\end_inset
-
-PyLith Configuration
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-configure
-\family default
- script checks for various system features.
- As it runs, it prints messages informing you of which features it is checking
- for.
- Upon successful completion, it generates a
-\family typewriter
-Makefile
-\family default
- in each source directory of the package.
- It also generates a
-\family typewriter
-config.h
-\family default
- header file, which contains system-dependent definitions.
-
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-configure
-\family default
- script will attempt to guess the correct values of various installation
- parameters.
- In the event that the default values used by
-\family typewriter
-configure
-\family default
- are incorrect for your system, or
-\family typewriter
-configure
-\family default
- is unable to guess the value of a certain parameter, you may have to specify
- the correct value by hand.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-Important:
-\series default
- If the
-\family typewriter
-configure
-\family default
- script fails, and you don't know what went wrong, examine the log file
-
-\family typewriter
-config.log
-\family default
-.
- This file contains a detailed transcript of all the checks
-\family typewriter
-configure
-\family default
- performed.
- Most importantly, it includes the error output (if any) from your compiler.
- When seeking help for
-\family typewriter
-configure
-\family default
- failures on the
-\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
-
-\end_inset
-
-, please send
-\family typewriter
-config.log
-\family default
- as an attachment.
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-configure
-\family default
- script will automatically check for needed Python dependencies, including
- the Pythia package (which includes the Pyre framework).
- If necessary,
-\family typewriter
-configure
-\family default
- will download missing Python packages from the Internet.
-\end_layout
-
-\begin_layout Standard
-PyLith v0.8.2 requires Pythia v0.8.1.3 or later, which
-\family typewriter
-configure
-\family default
- downloads directly from CIG.
- (Pythia v0.8.1.x is distinct from Pythia v0.8, which you may have installed
- previously.) Pythia v0.8.1.x is pure Python, and resides in a file or directory
- with the extension
-\family typewriter
-.egg
-\family default
- (e.g.,
-\family typewriter
-pythia-0.8.1.3.egg
-\family default
-).
- The
-\family typewriter
-configure
-\family default
- script may download other
-\family typewriter
-.egg
-\family default
- packages, in addition to Pythia.
- These are Python packages which are required (either directly or indirectly)
- by PyLith.
-\end_layout
-
-\begin_layout Subsubsection
-Configure Usage
-\end_layout
-
-\begin_layout Standard
-For a detailed list of
-\family typewriter
-configure
-\family default
- variables and options, give
-\family typewriter
-configure
-\family default
- the
-\family typewriter
---help
-\family default
- option:
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --help
-\end_layout
-
-\begin_layout Standard
-The following is a summary of the variables and options that are important
- when installing PyLith.
-
-\end_layout
-
-\begin_layout Subsubsection
-Environment Variables
-\end_layout
-
-\begin_layout Standard
-Environment variables may be specified as arguments to
-\family typewriter
-configure
-\family default
-, e.g.,
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure PYTHON=/usr/bin/python2.4
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="1in">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-
-\series bold
-Variable
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PYTHON
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-Python interpreter.
- This is useful if you have Python installed in a non-standard location,
- e.g.,
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-\InsetSpace ~
-\InsetSpace ~
-./configure
-\backslash
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-PYTHON=/opt/python2.3/bin/python
-\family default
-
-\end_layout
-
-\begin_layout Standard
-By default,
-\family typewriter
-configure
-\family default
- will search for a suitable Python interpreter using your
-\family typewriter
-PATH
-\family default
- environment variable.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PETSC_DIR
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PETSc installation/build directory.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PETSC_ARCH
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-(optional) PETSc configuration tag.
- If not specified,
-\family typewriter
-configure
-\family default
- will pick a default configuration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\align left
-The configure script will automatically select the appropriate C++ and Fortran
- compilers using information from the PETSc configuration.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- Manually specifying the C++ or Fortran compiler (using
-\family typewriter
-CXX
-\family default
- or
-\family typewriter
-FC
-\family default
-) is not recommended.
- Different Fortran compilers tend to be incompatible with one another.
- With C++, even different versions of the same compiler can be incompatible.
- Therefore, PyLith must be built using the same C++ and Fortran compilers
- used to configure and build PETSc.
- It is best to let PyLith's
-\family typewriter
-configure
-\family default
- script handle this automatically.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Pyre-Configuration}
-
-\end_inset
-
-Pyre Configuration
-\end_layout
-
-\begin_layout Standard
-Pyre is automatically downloaded by PyLith's configure script as a part
- of the Pythia package.
- Pythia is pure Python, so it requires no special configuration to build
- or install.
-\end_layout
-
-\begin_layout Standard
-However, Pyre manages the launching of parallel runs of PyLith under MPI,
- and the scheduling of PyLith jobs when used with a batch system.
- Therefore, before running PyLith, you must create a small configuration
- file which instructs Pyre how to launch and schedule PyLith runs on your
- system.
-\end_layout
-
-\begin_layout Subsection
-Pyre Configuration on a Personal Computer
-\end_layout
-
-\begin_layout Standard
-On a workstation or laptop, there is no job scheduler or communication network
- between compute nodes.
- In this scenario, Pyre is trivial to configure.
- Simply create the file
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
- with the following contents:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-command = mpiexec -np ${nodes}
-\end_layout
-
-\begin_layout Standard
-The only trick is to specify the right command for your MPI implementation.
- Specify the
-\family typewriter
-mpiexec
-\family default
- command if you are using MPICH2 (which will be the case if you instructed
- PETSc to download MPICH for you).
-\end_layout
-
-\begin_layout Standard
-If you are using MPICH1, enter the following instead:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-command = mpirun -np ${nodes}
-\end_layout
-
-\begin_layout Standard
-See the documentation for your MPI implementation if you are unsure of the
- command to specify.
-\end_layout
-
-\begin_layout Subsection
-Pyre Configuration on a Cluster
-\end_layout
-
-\begin_layout Standard
-If you are installing PyLith on a cluster with a batch system, you can configure
- Pyre such that the
-\family typewriter
-pylith3dapp.py
-\family default
- command automatically submits jobs to the batch queue.
- Pyre contains support for the LSF, PBS, and Globus batch systems.
-\end_layout
-
-\begin_layout Standard
-The command to submit a batch job depends upon the particular batch system
- used.
- Further, the command used in a batch script to launch an MPI program varies
- from one cluster to the next.
- This command can vary between two clusters, even if the clusters use the
- same batch system! On some systems,
-\family typewriter
-mpirun
-\family default
- is invoked directly from the batch script.
- On others, a special wrapper is used instead.
-\end_layout
-
-\begin_layout Standard
-Properly configured, Pyre can handle job submissions automatically, insulating
- users from the details of the batch system and the site configuration.
- This feature has the most value when the system administrator installs
- a global Pyre configuration file on the cluster (under
-\family typewriter
-/etc/pythia-0.8
-\family default
-), for the benefit of all users and all Pyre-based applications.
-\end_layout
-
-\begin_layout Subsubsection
-\begin_inset LatexCommand \label{sub:Launchers-and-Schedulers}
-
-\end_inset
-
-Launchers and Schedulers
-\end_layout
-
-\begin_layout Standard
-If you have used one of the batch systems, you will know that the batch
- system requires you to write a script to launch a job.
- Fortunately, launching a parallel PyLith job is simplified by Pyre's
-\family typewriter
-launcher
-\family default
- and
-\family typewriter
-scheduler
-\family default
- facilities.
- Many properties associated with
-\family typewriter
-launcher
-\family default
- and
-\family typewriter
-scheduler
-\family default
- are pertinent to the cluster you are on, and are best customized in a configura
-tion file.
- Your personal PyLith configuration file (
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
-) is suitable for this purpose.
- On a cluster, the ideal setup is to install a system-wide configuration
- file under
-\family typewriter
-/etc/pythia-0.8
-\family default
-, for the benefit of all users.
-\end_layout
-
-\begin_layout Standard
-Pyre's
-\family typewriter
-scheduler
-\family default
- facility is used to specify the type of batch system you are using (if
- any):
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d]
-\end_layout
-
-\begin_layout LyX-Code
-scheduler = lsf
-\end_layout
-
-\begin_layout Standard
-The valid values for
-\family typewriter
-scheduler
-\family default
- are
-\family typewriter
-lsf
-\family default
-,
-\family typewriter
-pbs
-\family default
-,
-\family typewriter
-globus
-\family default
-, and
-\family typewriter
-none
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Pyre's
-\family typewriter
-launcher
-\family default
- facility is used to specify which MPI implementation you are using:
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d]
-\end_layout
-
-\begin_layout LyX-Code
-launcher = mpich
-\end_layout
-
-\begin_layout Standard
-The valid values for
-\family typewriter
-launcher
-\family default
- include
-\family typewriter
-mpich
-\family default
- and
-\family typewriter
-lam-mpi
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-You may find the
-\family typewriter
-dry
-\family default
- option useful while debugging the
-\family typewriter
-launcher
-\family default
- and
-\family typewriter
-scheduler
-\family default
- configuration.
- To debug the scheduler configuration, use the
-\family typewriter
---scheduler.dry
-\family default
- option:
-\end_layout
-
-\begin_layout LyX-Code
-pylith3dapp.py --scheduler.dry
-\end_layout
-
-\begin_layout Standard
-This option will cause PyLith to perform a ``dry run,'' dumping the batch
- script to the console, instead of actually submitting it for execution
- (the output is only meaningful if you're using a batch system).
- Likewise, to debug the launcher configuration, use the
-\family typewriter
---launcher.dry
-\family default
- option:
-\end_layout
-
-\begin_layout LyX-Code
-pylith3dapp.py --launcher.dry
-\end_layout
-
-\begin_layout Standard
-This option will cause PyLith to print the
-\family typewriter
-mpirun
-\family default
- command, instead of actually executing it.
- (If you're using a batch system, a job will be submitted for execution;
- when it runs, PyLith will simply print the
-\family typewriter
-mpirun
-\family default
- command, and the job will immediately terminate.)
-\end_layout
-
-\begin_layout Subsubsection
-Running without a Batch System
-\end_layout
-
-\begin_layout Standard
-On a cluster without a batch system, you need to explicitly specify the
- machines on which the job will run.
- Supposing the machines on your cluster are named n001, n002, \SpecialChar \ldots{}
-, etc., but
- you want to run the job on machines n001, n003, n004, and n005 (maybe n002
- is down for the moment).
- To run an example, create a file named
-\family typewriter
-mymachines.cfg
-\family default
- which specifies the machines to use:
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-nodegen = n%03d
-\end_layout
-
-\begin_layout LyX-Code
-nodelist = [1,3-5]
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-nodegen
-\family default
- property is a printf-style format string, used in conjunction with
-\family typewriter
-nodelist
-\family default
- to generate the list of machine names.
- The
-\family typewriter
-nodelist
-\family default
- property is a comma-separated list of machine names in square brackets.
-\end_layout
-
-\begin_layout Standard
-Now, invoke the following:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith3dapp.py example.cfg mymachines.cfg
-\end_layout
-
-\begin_layout Standard
-This strategy gives you the flexibility to create an assortment of
-\family typewriter
-.cfg
-\family default
- files (with one
-\family typewriter
-.cfg
-\family default
- file for each machine list) which can be easily paired with different parameter
- files.
-\end_layout
-
-\begin_layout Standard
-If your machine list does not change often, you may find it more convenient
- to specify default values for
-\family typewriter
-nodegen
-\family default
- and
-\family typewriter
-nodelist
-\family default
- in
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
- (which is read automatically).
- Then, you can run any simulation with no additional arguments:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith3dapp.py example.cfg
-\end_layout
-
-\begin_layout Quote
-
-\color red
-Warning:
-\color none
-This assumes your machine list has enough nodes for the simulation in question.
-\end_layout
-
-\begin_layout Standard
-You will notice that a machine file
-\family typewriter
-mpirun.nodes
-\family default
- is generated.
- It will contain a list of the nodes where PyLith has run.
-\end_layout
-
-\begin_layout Subsubsection
-Using a Batch System
-\end_layout
-
-\begin_layout Standard
-The settings which are important when using a batch system are summarized
- in the sample configuration file which follows.
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d]
-\end_layout
-
-\begin_layout LyX-Code
-scheduler = lsf ; the type of the installed batch system
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.lsf]
-\end_layout
-
-\begin_layout LyX-Code
-bsub-options = [-a mpich_gm] ; special options for 'bsub'
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-command = mpirun.lsf ; 'mpirun' command to use on our cluster
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.job]
-\end_layout
-
-\begin_layout LyX-Code
-queue = normal ; default queue for jobs
-\end_layout
-
-\begin_layout Standard
-These settings are usually placed in
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
- or in a system-wide configuration file.
- They can be overridden on the command line, where one typically specifies
- the job name and the allotted time for the job:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith3dapp.py example1.cfg --job.queue=debug
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --job.name=example1 --job.walltime=5*minute
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --nodes=4
-\end_layout
-
-\begin_layout Standard
-The number of processors to allocate for the job is given using the
-\family typewriter
-nodes
-\family default
- parameter.
-\end_layout
-
-\begin_layout Standard
-For more information on configuring Pyre for your batch system, see CIG's
-
-\begin_inset LatexCommand \htmlurl[Pythia page]{www.geodynamics.org/cig/software/packages/cs/pythia}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Software-Repository}
-
-\end_inset
-
-Installing from the Software Repository
-\end_layout
-
-\begin_layout Standard
-The PyLith source code is available via the
-\begin_inset LatexCommand \htmlurl[Geodynamics Subversion Repository]{www.geodynamics.org/cig/software/Repository/}
-
-\end_inset
-
-.
- The PETSc source code is available via a Mercurial repository.
- This allows users to view the revision history of the code and check out
- the most recent development version of the software.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- Building PyLith using the source repositories is recommended only for expert
- users who are willing to work with a moving target and rebuild on a frequent
- basis.
- The installation instructions cover the basic steps and assume the user
- has experience building and installing software.
-\end_layout
-
-\begin_layout Quote
-If you are content with the prepared source packages, you may skip this
- section.
-\end_layout
-
-\begin_layout Subsection
-Additional Tools You Will Need
-\end_layout
-
-\begin_layout Standard
-In addition to the usual system requirements, you will need a handful of
- additional development tools installed in order to work with the source
- from the software repositories.
-\end_layout
-
-\begin_layout Itemize
-Subversion
-\end_layout
-
-\begin_layout Itemize
-Mercurial (0.9 or later)
-\end_layout
-
-\begin_layout Itemize
-GNU Autotools (Autoconf, Automake, and Libtool)
-\end_layout
-
-\begin_layout Itemize
-Pyrex (v0.9.5.1 or later)
-\end_layout
-
-\begin_layout Subsubsection
-Subversion
-\end_layout
-
-\begin_layout Standard
-To check out the PyLith source, you must have a Subversion client installed.
- To check, type
-\family typewriter
-svn
-\family default
-; it should return a usage message.
-\end_layout
-
-\begin_layout LyX-Code
-$ svn
-\end_layout
-
-\begin_layout LyX-Code
-Type 'svn help' for usage.
-\end_layout
-
-\begin_layout Standard
-Many flavors of Unix have Subversion packages.
- You do not need anything but the basic Subversion client package.
-\end_layout
-
-\begin_layout Standard
-For more information on Subversion, visit the
-\begin_inset LatexCommand \htmlurl[Subversion website]{subversion.tigris.org}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsubsection
-Mercurial
-\end_layout
-
-\begin_layout Standard
-To check out the PETSc source, you must have Mercurial 0.9 or later installed.
- You will likely have to build Mercurial from source, but this is a very
- easy task that takes only a couple of minutes.
- To learn how to download and install Mercurial, visit
-\begin_inset LatexCommand \htmlurl[the Mercurial web site]{http://www.selenic.com/mercurial/}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsubsection
-Pyrex
-\end_layout
-
-\begin_layout Standard
-The software layer which connects PyLith's high-level Python code with its
- low-level Fortran code is written in a language called
-\emph on
-Pyrex
-\emph default
-.
- Pyrex is a Python-like language for writing native Python extension modules.
- To download Pyrex, visit
-\begin_inset LatexCommand \htmlurl[the Pyrex web site]{http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/}
-
-\end_inset
-
-.
- After installing Pyrex, make sure the
-\family typewriter
-pyrexc
-\family default
- command is accessible via your
-\family typewriter
-PATH
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The Pyrex compiler generates C code as its output.
- Due to PETSc-related C/C++ linkage issues, the PyLith build system compiles
- this generated C code using the C++ compiler.
- For this reason and others, PyLith requires Pyrex v0.9.5.1 or later.
-\end_layout
-
-\begin_layout Subsubsection
-Autotools
-\end_layout
-
-\begin_layout Standard
-To generate the build system for PyLith, you must have the GNU tools Autoconf,
- Automake, and Libtool installed.
- To check, enter the following commands:
-\end_layout
-
-\begin_layout LyX-Code
-$ autoconf --version
-\end_layout
-
-\begin_layout LyX-Code
-$ automake --version
-\end_layout
-
-\begin_layout LyX-Code
-$ libtoolize --version
-\end_layout
-
-\begin_layout Standard
-For more information about these GNU tools, see the
-\begin_inset LatexCommand \htmlurl[GNU website]{www.gnu.org/software}
-
-\end_inset
-
-.
- The PyLith source package was created with Autoconf 2.61, Automake 1.9.6,
- and Libtool 1.5.22.
-\end_layout
-
-\begin_layout Subsection
-Downloading the PETSc Source using Mercurial
-\end_layout
-
-\begin_layout Standard
-Pull the source code from Argonne National Laboratory (ANL) and place the
- source tree in a suitable location.
- The steps below will create a
-\family typewriter
-petsc-dev
-\family default
- sub-directory in the current directory.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg clone http://mercurial.mcs.anl.gov/petsc/petsc-dev
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ cd petsc-dev/python
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg clone http://mercurial.mcs.anl.gov/petsc/BuildSystem BuildSystem
-\end_layout
-
-\begin_layout Standard
-In the future, you will likely want to update the PETSc source tree to include
- bug fixes, new features, etc.
- To update PETSc, perform the following commands:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ cd petsc-dev
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg pull
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg update
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ cd python/BuildSystem
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg pull
-\end_layout
-
-\begin_layout LyX-Code
-$ hg update
-\end_layout
-
-\begin_layout Subsection
-Downloading the PyLith Source using Subversion
-\end_layout
-
-\begin_layout Standard
-To check out the latest version of PyLith, use the
-\family typewriter
-svn checkout
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ svn checkout
-\family typewriter
-http://geodynamics.org/svn/cig/short/3D/PyLith/branches/pylith-0.8
-\end_layout
-
-\begin_layout Standard
-This will create the local directory
-\family typewriter
-pylith-0.8
-\family default
- (if it doesn't already exist) and fill it with the latest PyLith source
- from the CIG software repository.
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-pylith-0.8
-\family default
- directory thus created is called a
-\emph on
-working copy
-\emph default
-.
- To merge the latest changes into an existing working copy, use the
-\family typewriter
-svn update
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd pylith-0.8
-\end_layout
-
-\begin_layout LyX-Code
-$ svn update
-\end_layout
-
-\begin_layout Standard
-This will preserve any local changes you have made to your working copy.
-\end_layout
-
-\begin_layout Subsection
-Generating the GNU Build System
-\end_layout
-
-\begin_layout Standard
-Your working directory should now contain a fresh checkout of PyLith and
- PETSc:
-\end_layout
-
-\begin_layout LyX-Code
-$ ls
-\end_layout
-
-\begin_layout LyX-Code
-petsc-dev
-\end_layout
-
-\begin_layout LyX-Code
-pylith-0.8
-\end_layout
-
-\begin_layout LyX-Code
-$
-\end_layout
-
-\begin_layout Standard
-You are now ready to install PETSc as described in Section
-\begin_inset LatexCommand \ref{sec:Installing-PETSc}
-
-\end_inset
-
- earlier in this chapter.
-\end_layout
-
-\begin_layout Standard
-However, before you can run
-\family typewriter
-configure
-\family default
- or
-\family typewriter
-make
-\family default
- in the
-\family typewriter
-pylith-0.8
-\family default
- directory, you must generate the necessary files using the GNU tools.
- The easiest way to do this is to run
-\family typewriter
-autoreconf -if
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd pylith-0.8
-\end_layout
-
-\begin_layout LyX-Code
-$ autoreconf -if
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-autoreconf
-\family default
- tool runs Autoconf to generate the
-\family typewriter
-configure
-\family default
- script from
-\family typewriter
-configure.ac
-\family default
-.
- It also runs Automake to generate
-\family typewriter
-Makefile.in
-\family default
- from
-\family typewriter
-Makefile.am
-\family default
- in each source directory.
- After running
-\family typewriter
-autoreconf
-\family default
-, install PyLith as described in Section
-\begin_inset LatexCommand \ref{sec:Installing-PyLith}
-
-\end_inset
-
- earlier in this chapter.
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
\end_body
\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx 2007-06-22 13:27:51 UTC (rev 7372)
@@ -37,6 +37,10 @@
\begin_body
\begin_layout Chapter
+\begin_inset LatexCommand \label{cha:material:models}
+
+\end_inset
+
Material Models
\end_layout
@@ -57,6 +61,168 @@
\end_layout
\begin_layout Section
+Specifying Material Properties
+\end_layout
+
+\begin_layout Standard
+Associating material properties with each a given cell involves several
+ steps.
+
+\end_layout
+
+\begin_layout Enumerate
+In the mesh generation process, a material identifier must be assigned to
+ each cell.
+\end_layout
+
+\begin_layout Enumerate
+A material container must be created unless a suitable one already exists.
+\end_layout
+
+\begin_layout Enumerate
+Set the parameters for each material in the materials container using .cfg
+ or pml files and/or command line arguments.
+\end_layout
+
+\begin_layout Enumerate
+Specify the spatial variation in material property parameters using a spatial
+ database file.
+\end_layout
+
+\begin_layout Subsection
+Setting the Material Identifier
+\end_layout
+
+\begin_layout Standard
+Each cell in the finite-element mesh must have a material identifier.
+ This integer value is associated with a bulk material model.
+ The parameters of the material model need not be uniform for cells with
+ the same material identifier.
+ The bulk constitutive model and numerical integration (quadrature) scheme
+ will however, be the same for all cells with the same material identifier
+ value.
+ The material identifier is set during the mesh generation process.
+ The procedure for assigning this integer value to a cell depends on the
+ mesh generator.
+ For example, in the PyLith mesh ASCII format, the identifiers are listed
+ in the cells group using the material-id data; in CUBIT materials are defined
+ using blocks; in LaGriT materials are defined by the attribute imt and
+ the mregion command.
+\end_layout
+
+\begin_layout Subsection
+Creating a Material Container
+\end_layout
+
+\begin_layout Standard
+The material container associates a material model (label for the material,
+ a bulk constitutive model, and parameters for the constitutive model) with
+ a material identifier.
+ Because the number of materials depends on the problem and Pyre does not
+ support dynamic arrays of components, a generic materials container is
+ not yet available.
+ The default material container is a homogeneous material, i.e., a single
+ material model for the entire problem.
+ A two-material container (pylith.materials.BiMaterial) is also supplied.
+ For more problems with more than two materials, the user must create the
+ material container using an an .odb file (a template is provided in the
+ examples/templates directory of the PyLith distribution).
+ Example XX discusses creating a material container using this template.
+ This .odb file should be placed in the directory with the other simulation
+ input files.
+\end_layout
+
+\begin_layout Subsection
+Material Parameters
+\end_layout
+
+\begin_layout Standard
+The principal parameters for a material are:
+\end_layout
+
+\begin_layout Description
+id This is the material identifier that matches the integer value assigned
+ to each cell in the mesh generation process.
+\end_layout
+
+\begin_layout Description
+name Name or label for the material.
+ This is used in error and diagnostic reports.
+\end_layout
+
+\begin_layout Description
+db Spatial database specifying the spatial variation in the parameters of
+ the bulk constitutive model.
+\end_layout
+
+\begin_layout Description
+quadrature Numerical integration scheme used in integrating fields over
+ each cell.
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a .cfg file for the homogeneous
+ material is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.materials.homogeneous]
+\end_layout
+
+\begin_layout LyX-Code
+material = pylith.materials.ElasticIsotropic3D
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.materials.material]
+\end_layout
+
+\begin_layout LyX-Code
+id = 1
+\end_layout
+
+\begin_layout LyX-Code
+name = Elastic material
+\end_layout
+
+\begin_layout LyX-Code
+db.iohandler.filename = elastic.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db.query_type = linear
+\end_layout
+
+\begin_layout LyX-Code
+quadrature = pylith.feassemble.Quadrature3D
+\end_layout
+
+\begin_layout Standard
+where we have specified that the bulk constitutive model is the 3-D linear
+ elastic model and we use linear interpolation for computing the spatial
+ variation of the parameters within the spatial database.
+ See Chapter
+\begin_inset LatexCommand \ref{sec:Spatialdata:SimpleIOAscii}
+
+\end_inset
+
+ for a complete list of the spatial database settings.
+
+\end_layout
+
+\begin_layout Subsection
+Material Spatial Database Files
+\end_layout
+
+\begin_layout Standard
+[ADD STUFF HERE]
+\end_layout
+
+\begin_layout Section
Elastic Material Models
\end_layout
Modified: short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx 2007-06-22 13:27:51 UTC (rev 7372)
@@ -1,4 +1,4 @@
-#LyX 1.4.4 created this file. For more info see http://www.lyx.org/
+#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
@@ -434,7 +434,7 @@
\begin_layout Standard
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="7" columns="3">
+<lyxtabular version="3" rows="6" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="0.9in">
<column alignment="center" valignment="middle" leftline="true" width="0.8in">
@@ -492,7 +492,7 @@
\begin_layout Standard
\shape italic
-true
+false
\end_layout
\end_inset
@@ -523,9 +523,7 @@
\begin_inset Text
\begin_layout Standard
-
-\shape italic
-true
+false
\end_layout
\end_inset
@@ -556,9 +554,7 @@
\begin_inset Text
\begin_layout Standard
-
-\shape italic
-true
+false
\end_layout
\end_inset
@@ -592,7 +588,7 @@
\begin_layout Standard
\shape italic
-1.0e-09
+1.0e-05
\end_layout
\end_inset
@@ -625,7 +621,7 @@
\begin_layout Standard
\shape italic
-bjacobi
+jacobi
\end_layout
\end_inset
@@ -642,40 +638,6 @@
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-
-\family typewriter
-sub_pc_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-
-\shape italic
-ilu
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-Set preconditioner to incomplete factorization for each block.
- See PETSc documentation for a list of all preconditioners.
-\end_layout
-
-\end_inset
-</cell>
-</row>
</lyxtabular>
\end_inset
@@ -714,7 +676,7 @@
\end_layout
\begin_layout Standard
-PyLith supports linear elements in 1D (
+PyLith supports linear cells in 1D (
\begin_inset LatexCommand \ref{fig:1D-linear-elements}
\end_inset
@@ -730,28 +692,28 @@
\end_inset
).
- The node ordering must follow the convention shown in the figures.
- Quadratic elements are also supported, but at present the only method for
- using these elements in PyLith is using PyLith ASCII format.
+ The vertex ordering must follow the convention shown in the figures.
+ Quadratic cells are also supported, but at present the only method for
+ using these cells in PyLith is using PyLith ASCII format.
PyLith does not yet support automatic generation of a quadratic mesh from
the linear meshes created by CUBIT or LaGriT.
\end_layout
\begin_layout Standard
The mesh information defines the nodal coordinates as well as specifying
- the nodes composing each element in the mesh.
- The mesh information must also define at least one set of nodes for which
- displacement (Dirichlet) boundary conditions will be provided.
- In most realistic problems, there will be several node groups, each with
+ the vertices composing each cell in the mesh.
+ The mesh information must also define at least one set of vertices for
+ which displacement (Dirichlet) boundary conditions will be provided.
+ In most realistic problems, there will be several vertex groups, each with
a unique identifying label.
For example, one group might define a surface of the mesh where displacement
(Dirichlet) boundary conditions will be applied, another might define a
surface where traction (Neumann) boundary conditions will be applied, while
a third might specify a surface that will define a fault.
- Similarly, the mesh information contains element labels that define the
- material type for each element in the mesh.
+ Similarly, the mesh information contains cell labels that define the material
+ type for each cell in the mesh.
For a mesh with a single material type, there will only be a single label
- for every element in the mesh.
+ for every cell in the mesh.
***Put in references for all of this***
\end_layout
@@ -776,7 +738,7 @@
\end_layout
\begin_layout Caption
-Linear bar element available for 1-D problems.
+Linear bar cell available for 1-D problems.
\end_layout
\begin_layout Standard
@@ -825,7 +787,7 @@
\end_layout
\begin_layout Caption
-Linear elements available for 2-D problems are the triangle (left) and the
+Linear cells available for 2-D problems are the triangle (left) and the
quadrilateral (right).
\end_layout
@@ -875,8 +837,8 @@
\end_layout
\begin_layout Caption
-Linear elements available for 3D problems are the tetrahedron (left) and
- the hexahedron (right).
+Linear cells available for 3D problems are the tetrahedron (left) and the
+ hexahedron (right).
\begin_inset LatexCommand \label{fig:3D-linear-elements}
\end_inset
@@ -897,24 +859,34 @@
Once the problem has been defined with PyLith parameters, and the mesh informati
on has been provided, the final step is to specify the boundary conditions
and material properties to be used.
- The mesh information provides labels defining sets of nodes to which boundary
- conditions or fault conditions will be applied, as well as element labels
- that will be used to define the material type of each element.
+ The mesh information provides labels defining sets of vertices to which
+ boundary conditions or fault conditions will be applied, as well as cell
+ labels that will be used to define the material type of each cell.
For boundary conditions, the .cfg file is used to associate boundary condition
- types and spatial databases with each node group (***reference***).
+ types and spatial databases with each vertex group (see Chapter
+\begin_inset LatexCommand \ref{cha:boundary:interface:conditions}
+
+\end_inset
+
+).
For materials, the
\family typewriter
.cfg
\family default
- file is used to associate material types and spatial databases with each
- element group.
+ file is used to associate material types and spatial databases with cells
+ identified by the material identifier (see Chapter
+\begin_inset LatexCommand \ref{fig:Material-models}
+
+\end_inset
+
+).
\end_layout
\begin_layout Standard
The spatial databases define how the boundary conditions or material property
values vary spatially, and they can be arbitrarily complex.
The simplest example for a material database would be a mesh where all
- the elements of a given type have uniform properties (
+ the cells of a given type have uniform properties (
\begin_inset Quotes eld
\end_inset
@@ -922,8 +894,8 @@
\begin_inset Quotes erd
\end_inset
-, or 0-D variation).
- A slightly more complex case would be a mesh where the elements of a given
+ or 0-D variation).
+ A slightly more complex case would be a mesh where the cells of a given
type have properties that vary linearly along a given direction (
\begin_inset Quotes eld
\end_inset
@@ -932,7 +904,7 @@
\begin_inset Quotes erd
\end_inset
-, or 1-D variation).
+ or 1-D variation).
In more complex models, the material properties might have different values
at each point in the mesh (
\begin_inset Quotes eld
@@ -942,15 +914,17 @@
\begin_inset Quotes erd
\end_inset
-, or 3-D variation).
+ or 3-D variation).
This might be the case, for example, if the material properties are provided
by a database of seismic velocities and densities.
- ***Provide references***
-\end_layout
+ See Section
+\begin_inset LatexCommand \ref{sec:Spatialdata:SimpleIOAscii}
-\begin_layout Standard
-For boundary conditions, the simplest case would be where all nodes in a
- given group have the same boundary conditions (
+\end_inset
+
+ for the specification of the file format for the default spatial database.
+ For boundary conditions the simplest case would be where all vertices in
+ a given group have the same boundary condition parameters (
\begin_inset Quotes eld
\end_inset
@@ -968,10 +942,16 @@
\begin_inset Quotes erd
\end_inset
-, or 2-D variation).
+ or 2-D variation).
This sort of condition might be used, for example, to specify the variation
of slip on a fault plane.
- ***Provide references***
+ The examples discussed in Chapter
+\begin_inset LatexCommand \ref{cha:Tutorials}
+
+\end_inset
+
+ also contain more information regarding the specification and use of the
+ spatial database files.
\end_layout
\begin_layout Standard
Modified: short/3D/PyLith/trunk/doc/userguide/userguide.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/userguide.lyx 2007-06-22 04:36:08 UTC (rev 7371)
+++ short/3D/PyLith/trunk/doc/userguide/userguide.lyx 2007-06-22 13:27:51 UTC (rev 7372)
@@ -1,4 +1,4 @@
-#LyX 1.4.4 created this file. For more info see http://www.lyx.org/
+#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
@@ -202,7 +202,7 @@
\begin_layout Standard
\start_of_appendix
\begin_inset ERT
-status collapsed
+status open
\begin_layout Standard
@@ -217,6 +217,12 @@
\end_inset
+\begin_inset Include \input{glossary.lyx}
+preview false
+
+\end_inset
+
+
\begin_inset Include \input{fileformats/fileformats.lyx}
preview false
More information about the cig-commits
mailing list