[cig-commits] r6741 - short/3D/PyLith/branches/pylith-0.8/doc/userguide/install

[sue at geodynamics.org]

Author: sue
Date: 2007-05-01 13:27:04 -0700 (Tue, 01 May 2007)
New Revision: 6741

Modified:
   short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.lyx
Log:
a few edits; more tomorrow

Modified: short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.lyx
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.lyx	2007-05-01 19:25:30 UTC (rev 6740)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.lyx	2007-05-01 20:27:04 UTC (rev 6741)
@@ -1,2694 +1,2694 @@
-#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:Installation-and-Getting}
-
-\end_inset
-
-Installation and Getting Help
-\end_layout
-
-\begin_layout Section
-Introduction
-\end_layout
-
-\begin_layout Standard
-Installing PyLith is a three-stage process:
-\end_layout
-
-\begin_layout Itemize
-Install the development version of PETSc (Section 
-\begin_inset LatexCommand \vref{sec:Installing-PETSc}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Itemize
-Install PyLith (Section 
-\begin_inset LatexCommand \vref{sec:Installing-PyLith}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Itemize
-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 the 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 the 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 Standard
-PyLith is developed and tested on Linux and Mac OS X.
-\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.
-\end_layout
-
-\begin_layout Subsection
-Requesting Help
-\end_layout
-
-\begin_layout Standard
-The 
-\begin_inset LatexCommand \htmlurl[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
-
-.
-\end_layout
-
-\begin_layout Subsection
-Reporting Bugs
-\end_layout
-
-\begin_layout Standard
-CIG uses 
-\family typewriter
-Roundup
-\family default
- for bug tracking.
- If you find a bug in PyLith, please submit a bug report to the 
-\begin_inset LatexCommand \htmlurl[CIG Roundup System]{www.geodynamics.org/roundup/}
-
-\end_inset
-
-.
- 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
-Create New
-\family default
- under 
-\family sans
-Issues
-\family default
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:System-Requirements}
-
-\end_inset
-
-System Requirements
-\end_layout
-
-\begin_layout Standard
-Installation of PyLith requires the following:
-\end_layout
-
-\begin_layout Itemize
-A Fortran compiler
-\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 the PETSc library
-\end_layout
-
-\begin_layout Subsection
-Fortran Compiler
-\end_layout
-
-\begin_layout Standard
-The core of PyLith is Fortran-77 code which can be compiled with any Fortran-77
- or Fortran-9x compiler.
-\end_layout
-
-\begin_layout Standard
-There are several free Fortran compilers available.
- GCC 4 contains a Fortran-95 compiler called 
-\family typewriter
-gfortran
-\family default
-.
- Earlier versions of GCC include 
-\family typewriter
-g77
-\family default
-, which is also suitable for building PyLith.
- Another free alternative is 
-\family typewriter
-g95
-\family default
-; the G95 project offers pre-built binaries for a variety of systems, which
- makes it an attractive option for Mac OS X users.
-\end_layout
-
-\begin_layout Standard
-PyLith has also been tested with commercial Fortran compilers, including
- Intel's 
-\family typewriter
-ifort
-\family default
- and the Portland Group compiler.
-\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 'python' 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 include 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
-\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
-.
-\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 \htmlurl[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
-
-.
-\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 \htmlurl[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 \htmlurl[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">
-<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 specifing 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 Mecurial 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 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 LyX-Code
-
-\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 the 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 the 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
+#LyX 1.4.3-4 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:Installation-and-Getting}
+
+\end_inset
+
+Installation and Getting Help
+\end_layout
+
+\begin_layout Section
+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 Standard
+PyLith is developed and tested on Linux and Mac OS X.
+\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.
+\end_layout
+
+\begin_layout Subsection
+Requesting Help
+\end_layout
+
+\begin_layout Standard
+The 
+\begin_inset LatexCommand \htmlurl[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
+
+.
+\end_layout
+
+\begin_layout Subsection
+Reporting Bugs
+\end_layout
+
+\begin_layout Standard
+CIG uses 
+\family typewriter
+Roundup
+\family default
+ for bug tracking.
+ If you find a bug in PyLith, please submit a bug report to the 
+\begin_inset LatexCommand \htmlurl[CIG Roundup System]{www.geodynamics.org/roundup/}
+
+\end_inset
+
+.
+ 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
+Create New
+\family default
+ under 
+\family sans
+Issues
+\family default
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:System-Requirements}
+
+\end_inset
+
+System Requirements
+\end_layout
+
+\begin_layout Standard
+Installation of PyLith requires the following:
+\end_layout
+
+\begin_layout Itemize
+A Fortran compiler
+\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 the PETSc library
+\end_layout
+
+\begin_layout Subsection
+Fortran Compiler
+\end_layout
+
+\begin_layout Standard
+The core of PyLith is Fortran-77 code which can be compiled with any Fortran-77
+ or Fortran-9x compiler.
+\end_layout
+
+\begin_layout Standard
+There are several free Fortran compilers available.
+ GCC 4 contains a Fortran-95 compiler called 
+\family typewriter
+gfortran
+\family default
+.
+ Earlier versions of GCC include 
+\family typewriter
+g77
+\family default
+, which is also suitable for building PyLith.
+ Another free alternative is 
+\family typewriter
+g95
+\family default
+; the G95 project offers pre-built binaries for a variety of systems, which
+ makes it an attractive option for Mac OS X users.
+\end_layout
+
+\begin_layout Standard
+PyLith has also been tested with commercial Fortran compilers, including
+ Intel's 
+\family typewriter
+ifort
+\family default
+ and the Portland Group compiler.
+\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 'python' 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 include 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
+\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
+.
+\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 \htmlurl[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
+
+.
+\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 \htmlurl[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 \htmlurl[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">
+<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 specifing 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 Mecurial 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 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 LyX-Code
+
+\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 the 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 the 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