Skip to content

Commit

Permalink
updates manual, mostly using verbatim for code sections for better di…
Browse files Browse the repository at this point in the history 
…splay in markdown
  • Loading branch information
daniel peter committed May 5, 2015
1 parent afab080 commit c9e833c
Show file tree
Hide file tree
Showing 17 changed files with 525 additions and 550 deletions.
101 changes: 48 additions & 53 deletions doc/USER_MANUAL/02_getting_started.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,9 @@ \chapter{Getting Started}\label{cha:Getting-Started}
\section{Configuring and compiling the source code}

To get the SPECFEM3D\_GLOBE software package, type this:

\begin{lyxcode}
git clone --recursive --branch devel https://github.com/geodynamics/specfem3d\_globe.git
\end{lyxcode}
\begin{verbatim}
git clone --recursive --branch devel https://github.com/geodynamics/specfem3d_globe.git
\end{verbatim}

We recommend that you add {\texttt{ulimit -S -s unlimited}} to your {\texttt{.bash\_profile}} file and/or {\texttt{limit stacksize unlimited }} to your {\texttt{.cshrc}} file to suppress any potential limit to the size of the Unix stack.\\

Expand All @@ -16,10 +15,9 @@ \section{Configuring and compiling the source code}
you explicitly specify the appropriate command names for your Fortran
compiler and MPI package (another option is to define FC, CC and MPIF90 in your .bash\_profile
or your .cshrc file):

\begin{lyxcode}
./configure~FC=ifort~MPIFC=mpif90
\end{lyxcode}
\begin{verbatim}
./configure FC=ifort MPIFC=mpif90
\end{verbatim}

Before running the \texttt{configure} script, you should probably edit file \texttt{flags.guess} to make sure that it contains the best compiler options for your system. Known issues or things to check are:

Expand All @@ -30,9 +28,10 @@ \section{Configuring and compiling the source code}
\end{description}

When compiling on an IBM machine with the \texttt{xlf} and \texttt{xlc} compilers, we suggest running the \texttt{configure} script
with the following options:\\

\noindent\texttt{./configure FC=xlf90\_r MPIFC=mpif90 CC=xlc\_r CFLAGS="-O3 -q64" FCFLAGS="-O3 -q64"}.\\
with the following options:
\begin{verbatim}
./configure FC=xlf90_r MPIFC=mpif90 CC=xlc_r CFLAGS="-O3 -q64" FCFLAGS="-O3 -q64"
\end{verbatim}

On SGI systems, \texttt{flags.guess} automatically informs \texttt{configure}
to insert ``\texttt{TRAP\_FPE=OFF}'' into the generated \texttt{Makefile}
Expand Down Expand Up @@ -60,10 +59,10 @@ \section{Configuring and compiling the source code}
when you attempt to build the code. If you are unsure about this,
it is usually safe to set both \texttt{FC} and \texttt{MPIFC} to the
MPI compiler command for your system:
\begin{verbatim}
./configure FC=mpif90 MPIFC=mpif90
\end{verbatim}
\end{description}
\begin{lyxcode}
./configure~FC=mpif90~MPIFC=mpif90
\end{lyxcode}
\begin{description}
\item [{\texttt{FLAGS\_CHECK}}] Compiler flags.
\item [{\texttt{LOCAL\_PATH\_IS\_ALSO\_GLOBAL}}]
Expand Down Expand Up @@ -151,31 +150,28 @@ \section{Using the GPU version of the code}
OpenCL can be enabled with the \texttt{--with-opencl} flag, and the
compilation can be controlled through three variables: \texttt{OCL\_LIB=},
\texttt{OCL\_INC=} and \texttt{OCL\_GPU\_FLAGS=}.\\
\noindent
\texttt{./configure --with-opencl OCL\_LIB= OCL\_INC= OCL\_GPU\_FLAGS=
..}\\
\texttt{OCL\_INC=} and \texttt{OCL\_GPU\_FLAGS=}.
\begin{verbatim}
./configure --with-opencl OCL_LIB= OCL_INC= OCL_GPU_FLAGS=..
\end{verbatim}
Cuda configuration can be enabled with \texttt{--with-cuda} flag and
\texttt{CUDA\_FLAGS=}, \texttt{CUDA\_LIB=}, \texttt{CUDA\_INC=}
and \texttt{ MPI\_INC=} variables.\\
\noindent
\texttt{./configure --with-cuda=cuda5 CUDA\_FLAGS= CUDA\_LIB= CUDA\_INC= MPI\_INC= ..}\\
and \texttt{ MPI\_INC=} variables.
\begin{verbatim}
./configure --with-cuda=cuda5 CUDA_FLAGS= CUDA_LIB= CUDA_INC= MPI_INC= ..
\end{verbatim}
Both environments can be compiled simultaneously by merging these two lines.
For the runtime configuration, the \texttt{GPU\_MODE} flag must be set
to \texttt{.true.}. In addition, we use three parameters to select the
environments and GPU: \\
\noindent
\texttt{GPU\_RUNTIME = 0|1|2}\\
\texttt{GPU\_PLATFORM = filter|*}\\
\texttt{GPU\_DEVICE = filter|*}\\
environments and GPU:
\begin{verbatim}
GPU_RUNTIME = 0|1|2
GPU_PLATFORM = filter|*
GPU_DEVICE = filter|*
\end{verbatim}
\texttt{GPU\_RUNTIME} sets the runtime environments: $2$ for OpenCL,
$1$ for Cuda and 0 for compile-time decision (hence, SPECFEM should
Expand Down Expand Up @@ -222,12 +218,11 @@ \section{Compiling on an IBM BlueGene}
\underline{More recent installation instruction for IBM BlueGene, from October 2012:}\\
\noindent
Edit file \texttt{flags.guess} and put this for \texttt{FLAGS\_CHECK}:\\
\noindent
\texttt{-g -qfullpath -O2 -qsave -qstrict -qtune=qp -qarch=qp -qcache=auto -qhalt=w}\\
\noindent
\texttt{-qfree=f90 -qsuffix=f=f90 -qlanglvl=95pure -Q -Q+rank,swap\_all -Wl,-relax}\\
Edit file \texttt{flags.guess} and put this for \texttt{FLAGS\_CHECK}:
\begin{verbatim}
-g -qfullpath -O2 -qsave -qstrict -qtune=qp -qarch=qp -qcache=auto -qhalt=w \
-qfree=f90 -qsuffix=f=f90 -qlanglvl=95pure -Q -Q+rank,swap_all -Wl,-relax
\end{verbatim}
\noindent
The most relevant are the -qarch and -qtune flags, otherwise if these flags are set to ``auto'' then they are wrongly assigned to
Expand All @@ -243,20 +238,20 @@ \section{Compiling on an IBM BlueGene}
or \texttt{module load bgq-xl} (another, less efficient option is to load the GNU compilers using \texttt{module load bgq-gnu/4.4.6} or similar).\\
\noindent
Then, to configure the code, type this:\\
\noindent
\texttt{./configure FC=bgxlf90\_r MPIFC=mpixlf90\_r CC=bgxlc\_r LOCAL\_PATH\_IS\_ALSO\_GLOBAL=true}\\
Then, to configure the code, type this:
\begin{verbatim}
./configure FC=bgxlf90_r MPIFC=mpixlf90_r CC=bgxlc_r LOCAL_PATH_IS_ALSO_GLOBAL=true
\end{verbatim}
\noindent
\underline{Older installation instruction for IBM BlueGene, from 2011:}\\
\noindent
To compile the code on an IBM BlueGene, Laurent L\'eger from IDRIS, France, suggests the following: compile the code with
\noindent
\texttt{ FLAGS\_CHECK="-O3 -qsave -qstrict -qtune=auto -qarch=450d -qcache=auto \\}
\texttt{ -qfree=f90 -qsuffix=f=f90 -g -qlanglvl=95pure -qhalt=w -Q -Q+rank,swap\_all -Wl,-relax"}
\begin{verbatim}
FLAGS\_CHECK="-O3 -qsave -qstrict -qtune=auto -qarch=450d -qcache=auto \
-qfree=f90 -qsuffix=f=f90 -g -qlanglvl=95pure -qhalt=w -Q -Q+rank,swap_all -Wl,-relax"
\end{verbatim}
\noindent
Option "-Wl,-relax" must be added on many (but not all) BlueGene systems to be able to link the binaries \texttt{xmeshfem3D}
Expand All @@ -266,20 +261,20 @@ \section{Compiling on an IBM BlueGene}
\noindent
One then just needs to pass the right commands to the \texttt{configure} script:
\noindent
\texttt{ ./configure --prefix=/path/to/SPECFEM3DG\_SP --host=Babel --build=BGP \\}
\texttt{ FC=bgxlf90\_r MPIFC=mpixlf90\_r CC=bgxlc\_r \\}
\texttt{ LOCAL\_PATH\_IS\_ALSO\_GLOBAL=false}
\begin{verbatim}
./configure --prefix=/path/to/SPECFEM3DG_SP --host=Babel --build=BGP \
FC=bgxlf90_r MPIFC=mpixlf90_r CC=bgxlc_r \
LOCAL_PATH_IS_ALSO_GLOBAL=false
\end{verbatim}
\noindent
This trick can be useful for all hosts on which one needs to cross-compile.
\noindent
On BlueGene, one also needs to run the \texttt{xcreate\_header\_file} binary file manually rather than in the Makefile:
\noindent
\texttt{bgrun -np 1 -mode VN -exe ./bin/xcreate\_header\_file}
\begin{verbatim}
bgrun -np 1 -mode VN -exe ./bin/xcreate_header_file
\end{verbatim}
\section{Using a cross compiler}
Expand Down
44 changes: 21 additions & 23 deletions doc/USER_MANUAL/03_running_the_mesher.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
%\end{minipage}
\hfill
%\begin{minipage}[htp]{0.5\textwidth}
\includegraphics[width=0.45\textwidth]{figures/fullmesh_18.pdf} \\
\includegraphics[width=0.45\textwidth]{figures/fullmesh_18.pdf}\\
%\end{minipage}
%\end{minipage}
\end{center}
Expand Down Expand Up @@ -112,7 +112,8 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
17~s. Therefore, since accuracy is determined by the number of grid
points per shortest wavelength, for any particular value of $\nexxi$
the simulation will be accurate to a shortest period determined approximately
by \begin{equation}
by
\begin{equation}
\mbox{shortest period (s)}\simeq(256/\nexxi)\times17.\label{eq:shortest_period}
\end{equation}
The number of grid points in each orthogonal direction of the reference
Expand Down Expand Up @@ -154,7 +155,7 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
above the d120 discontinuity we switch back to the classical AK135 model of \cite{KeEnBu95},
i.e., we use AK135-F below and AK135 above.
%
\item [{\texttt{1}D\_ref}] A recent 1D Earth model developed by \citet{KuDzEk06}.
\item [{\texttt{1D\_ref}}] A recent 1D Earth model developed by \citet{KuDzEk06}.
This model is the 1D background model for the 3D models s362ani, s362wmani,
s362ani\_prem, and s29ea.
\end{description}
Expand All @@ -164,14 +165,13 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
synthetics, the mesher accommodates versions of various 1D models
with a single crustal layer with the properties of the original upper
crust. These `one-crust' models are:

\texttt{1D\_isotropic\_prem\_onecrust}

\texttt{1D\_transversely\_isotropic\_prem\_onecrust}

\texttt{1D\_iasp91\_onecrust}, \texttt{1D\_1066a\_onecrust}

\texttt{1D\_ak135f\_no\_mud\_onecrust}
\begin{verbatim}
1D_isotropic_prem_onecrust
1D_transversely_isotropic_prem_onecrust
1D_iasp91_onecrust
1D_1066a_onecrust
1D_ak135f_no_mud_onecrust
\end{verbatim}

\begin{description}
\item [{\textmd{Fully~3D~models:}}]~
Expand All @@ -196,19 +196,19 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
We use the PREM radial attenuation model when \texttt{ATTENUATION}
is incorporated.
%
\item [{\texttt{\textcolor{black}{s362ani}}}] A global shear-wave speed
\item [{\texttt{s362ani}}] A global shear-wave speed
model developed by \citet{KuDzEk06}. In this model, radial anisotropy
is confined to the uppermost mantle. The model (and the corresponding
mesh) incorporate tomography on the 650\textasciitilde{}km and 410\textasciitilde{}km
discontinuities in the 1D reference model REF.
%
\item [{\texttt{\textcolor{black}{s362wmani}}}] A version of S362ANI with
\item [{\texttt{s362wmani}}] A version of S362ANI with
anisotropy allowed throughout the mantle.
%
\item [{\texttt{\textcolor{black}{s362ani\_prem}}}] A version of S362ANI
\item [{\texttt{s362ani\_prem}}] A version of S362ANI
calculated using PREM as the 1D reference model.
%
\item [{\texttt{\textcolor{black}{s29ea}}}] A global model with higher
\item [{\texttt{s29ea}}] A global model with higher
resolution in the upper mantle beneath Eurasia calculated using REF
as the 1D reference model.
%
Expand Down Expand Up @@ -250,7 +250,7 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
%
Thus, flattening f = 1/299.8 is what is used in SPECFEM3D\_GLOBE, as it should. And thus eccentricity squared $e^2 = 1 - (1-f)^2 = 1 - (1 - 1/299.8)^2 = 0.00665998813529$, and the correction factor used in the code to convert geographic latitudes to geocentric is $1 - e^2 = (1-f)^2 = (1 - 1/299.8)^2 = 0.9933400118647$.
%
As a comparison, the classical World Geodetic System reference ellipsoid WGS 84 (see e.g. en.wikipedia.org/wiki/World\_Geodetic\_System) has $f = 1/298.2572236$.
As a comparison, the classical World Geodetic System reference ellipsoid WGS 84 (see e.g. \url{http://en.wikipedia.org/wiki/World_Geodetic_System}) has $f = 1/298.2572236$.
%
\item [{\texttt{TOPOGRAPHY}}] Set to \texttt{.true.} if topography and
bathymetry should be incorporated based upon model ETOPO4 \citep{Etopo5}.
Expand Down Expand Up @@ -284,7 +284,7 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
of meshing but is required for the solver, i.e., you may change this
parameter after running the mesher.
%
\item [{\texttt{PARTIAL\_PHYS\_DISPERSION\_ONLY or UNDO\_ATTENUATION}}] To undo attenuation for sensitivity kernel calculations or forward runs with \texttt{SAVE\_FORWARD}
\item [{\texttt{PARTIAL\_PHYS\_DISPERSION\_ONLY} or \texttt{UNDO\_ATTENUATION}}] To undo attenuation for sensitivity kernel calculations or forward runs with \texttt{SAVE\_FORWARD}
use one (and only one) of the two flags below. \texttt{UNDO\_ATTENUATION} is much better (it is exact) and is simpler to use
but it requires a significant amount of disk space for temporary storage. It has the advantage of requiring only two simulations for adjoint tomography instead
of three in the case of \texttt{PARTIAL\_PHYS\_DISPERSION\_ONLY}, i.e. for adjoint tomography it is globally significantly less expensive (each run is slightly more
Expand Down Expand Up @@ -796,12 +796,10 @@ \chapter{Running the Mesher \texttt{xmeshfem3D}}\label{cha:Running-the-Mesher}
in \texttt{output\_mesher.txt}; this file provides lots of details
about the mesh that was generated. Alternatively, output can be directed
to the screen instead by uncommenting a line in \texttt{constants.h}:

\begin{lyxcode}
!~uncomment~this~to~write~messages~to~the~screen~

!~integer,~parameter~::~IMAIN~=~ISTANDARD\_OUTPUT~~
\end{lyxcode}
\begin{verbatim}
! uncomment this to write messages to the screen
! integer, parameter :: IMAIN = ISTANDARD_OUTPUT
\end{verbatim}
Note that on very fast machines, writing to the screen may slow down
the code.

Expand Down
Loading

0 comments on commit c9e833c

Please sign in to comment.