[cig-commits] [commit] devel: updates manual (c3b9c7e)
cig_noreply at geodynamics.org
cig_noreply at geodynamics.org
Tue Dec 23 05:06:56 PST 2014
Repository : https://github.com/geodynamics/specfem3d
On branch : devel
Link : https://github.com/geodynamics/specfem3d/compare/c92aeae6613ca38c29e96dd169c292160dc53e21...c3b9c7ef07feb7d057fa71da18323d53b9c27233
>---------------------------------------------------------------
commit c3b9c7ef07feb7d057fa71da18323d53b9c27233
Author: daniel peter <peterda at ethz.ch>
Date: Tue Dec 23 13:27:28 2014 +0100
updates manual
>---------------------------------------------------------------
c3b9c7ef07feb7d057fa71da18323d53b9c27233
doc/USER_MANUAL/figures/Hollywood_CMT.pdf | Bin 87073 -> 85524 bytes
doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.pdf | Bin 12581411 -> 12615202 bytes
doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.tex | 135 +++++++++++++------------
3 files changed, 69 insertions(+), 66 deletions(-)
diff --git a/doc/USER_MANUAL/figures/Hollywood_CMT.pdf b/doc/USER_MANUAL/figures/Hollywood_CMT.pdf
index 5eec136..9dfe8b4 100644
Binary files a/doc/USER_MANUAL/figures/Hollywood_CMT.pdf and b/doc/USER_MANUAL/figures/Hollywood_CMT.pdf differ
diff --git a/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.pdf b/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.pdf
index c654c31..90216aa 100644
Binary files a/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.pdf and b/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.pdf differ
diff --git a/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.tex b/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.tex
index 5d17a99..ace4157 100644
--- a/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.tex
+++ b/doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.tex
@@ -412,12 +412,11 @@ On SGI systems, \texttt{flags.guess} automatically informs \texttt{configure}
to insert `\texttt{`TRAP\_FPE=OFF}'' into the generated \texttt{Makefile}
in order to turn underflow trapping off.\\
-You can add -DFORCE\_VECTORIZATION to the compiler options in \texttt{flags.guess} (for all compilers, except for IBM for which the syntax is -WF,-DFORCE\_VECTORIZATION )
-to speed up the code in the fluid (acoustic) parts (only; FORCE\_VECTORIZATION support for elastic parts has been discontinued in the source code).
+You can add \texttt{--enable-vectorization} to the configuration options to speed up the code in the fluid (acoustic) and elastic parts.
This works fine if (and only if) your computer always allocates a contiguous memory block for each allocatable array;
-this is the case for most machines and most compilers, but not all. For more details see https://github.com/geodynamics/specfem3d/issues/81 .
-To check if that option works fine on your machine, run the code with and without it for a model containing a significant fluid layer
-(or entirely fluid) and make sure the seismograms are identical.\\
+this is the case for most machines and most compilers, but not all. To disable this feature, use option \texttt{--disable-vectorization}.
+For more details see \href{https://github.com/geodynamics/specfem3d/issues/81}{github.com/geodynamics/specfem3d/issues/81} .
+To check if that option works fine on your machine, run the code with and without it for an acoustic/elastic model and make sure the seismograms are identical.\\
Note that we use CUBIT (now called Trelis) to create meshes of hexahedra, but other packages
can be used as well, for instance GiD from \url{http://gid.cimne.upc.es}
@@ -706,19 +705,19 @@ The important entries in the Doxyfile are:
\begin{itemize}
\item[\textbullet] a good and short summary for the basic utilisation of Doxygen:
-\texttt{http://www.softeng.rl.ac.uk/blog/2010/jan/30/callgraph-fortran-doxygen/} ,
+\url{http://www.softeng.rl.ac.uk/blog/2010/jan/30/callgraph-fortran-doxygen/},
\item[\textbullet] to configure the diagrams :
-\texttt{http://www.stack.nl/~dimitri/doxygen/manual/diagrams.html} ,
+\url{http://www.stack.nl/~dimitri/doxygen/manual/diagrams.html},
\item[\textbullet] the complete alphabetical index of the tags in Doxyfile:
-\texttt{http://www.stack.nl/~dimitri/doxygen/manual/config.html} ,
+\url{http://www.stack.nl/~dimitri/doxygen/manual/config.html},
\item[\textbullet] more generally, the Doxygen manual:
-\texttt{http://www.stack.nl/~dimitri/doxygen/manual/index.html} .
+\url{http://www.stack.nl/~dimitri/doxygen/manual/index.html}.
\end{itemize}
@@ -778,7 +777,7 @@ of a single volume with topography.}
\label{fig:mount.cubit}
\end{figure}
-
+\noindent
The basic steps in creating a load-balanced, partitioned mesh with
CUBIT are:
\begin{description}
@@ -930,7 +929,8 @@ blocks above, e.g. 'face\_abs\_xmin'.
After the block definitions are done, you export the mesh using the
script \texttt{cubit2specfem3d.py} provided in each of the example
-directories (linked to the common script \texttt{CUBIT\_GEOCUBIT/cubit2specfem3d.py}). If the export was successful, you should find the following
+directories (linked to the common script \texttt{CUBIT\_GEOCUBIT/cubit2specfem3d.py}).
+If the export was successful, you should find the following
files in a subdirectory \texttt{MESH/}:
\begin{description}
\item [{absorbing\_cpml\_file}] \textbf{(only needed in case of C-PML absorbing
@@ -1129,7 +1129,10 @@ block IDs belonging to volumes in order to check the quality of the
hexahedral elements. You also have to determine a number of parameters
of your mesh, such as the number of nodes and number of elements and
modify the header of the \texttt{check\_mesh\_quality\_CUBIT\_Abaqus.f90}
-source file. Then, in the main directory, type
+source file in directory \texttt{src/check\_mesh\_quality\_CUBIT\_Abaqus/}.
+
+\noindent
+Then, in the main directory, type
\begin{lyxcode}
{\small make~xcheck\_mesh\_quality\_CUBIT\_Abaqus}{\small \par}
\end{lyxcode}
@@ -1215,9 +1218,9 @@ If all paths and flags have been set correctly, the executable \texttt{bin/xdeco
should be produced.
The partitioning is done in serial for now (in the next release we
-will provide a parallel version of that code). It needs to be run in the \texttt{bin/} directory because it expects the \texttt{../DATA/Par\_file}. The synopsis is:
+will provide a parallel version of that code). It needs to be run in the main directory because it expects the \texttt{./DATA/Par\_file}. The synopsis is:
\begin{lyxcode}
-./xdecompose\_mesh~nparts~input\_directory~output\_directory
+./bin/xdecompose\_mesh~nparts~input\_directory~output\_directory
\end{lyxcode}
where
\begin{itemize}
@@ -1225,13 +1228,13 @@ where
for the parallel simulations,
\item \texttt{input\_directory} is the directory which holds all the files
generated by the Python script \texttt{cubit2specfem3d.py} explained
-in the previous Section~\ref{subsec:Exporting-the-Mesh}, e.g. \texttt{MESH/},
+in the previous Section~\ref{subsec:Exporting-the-Mesh}, e.g. \texttt{./MESH/},
and
\item \texttt{output\_directory} is the directory for the output of this
partitioner which stores ACII-format files named like \texttt{proc{*}{*}{*}{*}{*}{*}\_Database}
for each partition. These files will be needed for creating the distributed
databases, and have to reside in the directory \texttt{LOCAL\_PATH}
-specified in the main \texttt{Par\_file}, e.g. in directory \texttt{OUTPUT\_FILES/DATABASES\_MPI}.
+specified in the main \texttt{Par\_file}, e.g. in directory \texttt{./OUTPUT\_FILES/DATABASES\_MPI}.
Please see Chapter~\ref{cha:Creating-Distributed-Databases} for
further details.
\end{itemize}
@@ -1259,13 +1262,14 @@ of elements. In this example we use $5^{2}=25$ processors. }
\end{figure}
+\noindent
In the main directory, type
\begin{lyxcode}
{\small make~xmeshfem3D}{\small \par}
\end{lyxcode}
If all paths and flags have been set correctly, the mesher should
now compile and produce the executable \texttt{bin/xmeshfem3D}. Please
-note that \texttt{xmeshfem3D} must be called directly from the \texttt{bin/}
+note that \texttt{xmeshfem3D} must be called directly from the main
directory, as most of the binaries of the package.
Input for the mesh generation program is provided through the parameter
@@ -1489,7 +1493,7 @@ specific model parameters.}
\label{fig:workflow.databases}
\end{figure}
-
+\noindent
In the main directory, type
\begin{lyxcode}
{\small make~xgenerate\_databases}{\small \par}
@@ -1497,7 +1501,7 @@ In the main directory, type
Input for the program is provided through the main parameter file
\texttt{Par\_file}, which resides in the subdirectory \texttt{DATA}.
Please note that \texttt{xgenerate\_databases} must be called directly
-from the \texttt{bin/} directory, as most of the binaries of the package.
+from the main directory, as most of the binaries of the package.
\section{\label{cha:Main-Parameter}Main parameter file \texttt{Par\_file}}
@@ -1858,8 +1862,9 @@ to compile the solver. In the main directory, type
{\small make~xspecfem3D}{\small \par}
\end{lyxcode}
Please note that \texttt{xspecfem3D} must be called directly from
-the \texttt{bin/} directory, as most of the binaries of the package.
+the main directory, as most of the binaries of the package.\\
+\noindent
The solver needs three input files in the \texttt{DATA} directory
to run:
\begin{description}
@@ -1892,28 +1897,26 @@ Any other change to the \texttt{Par\_file} implies rerunning both
the database generator \texttt{xgenerate\_databases} and the solver
\texttt{xspecfem3D}.
+
For any particular earthquake, the \texttt{CMTSOLUTION} file that
represents the point source may be obtained directly from the Harvard
Centroid-Moment Tensor (CMT) web page \urlwithparentheses{www.seismology.harvard.edu}.
-It looks like this:
-\begin{lyxcode}
-\begin{figure}[H]
-\noindent \begin{centering}
-{\small \includegraphics[width=1\textwidth]{figures/Hollywood_CMT}
+It looks like the example shown in Fig. \ref{fig:CMTSOLUTION-file}.
+%\begin{lyxcode}
+\begin{figure}[htp]
+\noindent
+\begin{centering}
+{\small \includegraphics[width=0.8\textwidth]{figures/Hollywood_CMT}
}
-\par\end{centering}
-
-
-
-\caption{\label{fig:CMTSOLUTION-file}\texttt{CMTSOLUTION} file based on the
+\par
+\end{centering}
+\caption{\texttt{CMTSOLUTION} file based on the
format from the Harvard CMT catalog. \textbf{M} is the moment tensor,
$M_{0}${\small {} }is the seismic moment, and $M_{w}$ is the moment
magnitude.}
+\label{fig:CMTSOLUTION-file}
\end{figure}
-
-
-
-\end{lyxcode}
+%\end{lyxcode}
The \texttt{CMTSOLUTION} file should be edited in the following way:
\begin{itemize}
\item Set the latitude or UTM $x$ coordinate, longitude or UTM $y$ coordinate, depth of the source (in km).
@@ -1964,9 +1967,9 @@ from the original \texttt{CMTSOLUTION} file and $t_{\mathrm{synthetic}}$
is the time in the first column of the output seismogram.
\end{itemize}
-\begin{figure}
+\begin{figure}[htp]
\noindent \begin{centering}
-\includegraphics[width=2.5in]{figures/gauss_vs_triangle_mod}
+\includegraphics[width=3.5in]{figures/gauss_vs_triangle_mod}
\par\end{centering}
\caption{Comparison of the shape of a triangle and the Gaussian function actually
@@ -2176,18 +2179,18 @@ this can be useful when using a very large supercomputer to compute
many earthquakes in a catalog, in which case it can be better from
a batch job submission point of view to start fewer and much larger jobs,
each of them computing several earthquakes in parallel.
-To turn that option on, set parameter NUMBER\_OF\_SIMULTANEOUS\_RUNS
+To turn that option on, set parameter \texttt{NUMBER\_OF\_SIMULTANEOUS\_RUNS}
to a value greater than 1 in file setup/constants.h.in before
configuring and compiling the code.
When that option is on, of course the number of processor cores used to start
-the code in the batch system must be a multiple of NUMBER\_OF\_SIMULTANEOUS\_RUNS,
+the code in the batch system must be a multiple of \texttt{NUMBER\_OF\_SIMULTANEOUS\_RUNS},
all the individual runs must use the same number of processor cores,
-which as usual is NPROC in the input file DATA/Par\_file,
+which as usual is \texttt{NPROC} in the input file \texttt{DATA/Par\_file},
and thus the total number of processor cores to request from the batch system
-should be NUMBER\_OF\_SIMULTANEOUS\_RUNS $\times$ NPROC.
-All the runs to perform must be placed in directories called run0001, run0002, run0003 and so on (with exactly four digits)
+should be \texttt{NUMBER\_OF\_SIMULTANEOUS\_RUNS $\times$ NPROC}.
+All the runs to perform must be placed in directories called \texttt{run0001}, \texttt{run0002}, \texttt{run0003} and so on (with exactly four digits)
and you must create a link from the root directory of the code
-to the first copy of the executable programs by typing " ln -s run0001/bin bin ".
+to the first copy of the executable programs by typing \texttt{ln -s run0001/bin bin}.
\chapter{\label{cha:Fault-Kinematics-Dynamics}Kinematic and dynamic fault
@@ -2208,8 +2211,8 @@ A fault surface must lie at the interface between elements (the mesh
must honor the fault surfaces). Moreover, a fault is made of two surfaces
in contact. Each of these two surfaces needs a separate set of nodes.
This approach is known as \textquotedbl{}split nodes\textquotedbl{}.
-Currently faults can only be run with \texttt{xdecompose\_mesh }and\texttt{
-CUBIT. xmeshfem3D }is not yet ready to handle faults.\\
+Currently faults can only be run with \texttt{xdecompose\_mesh} and
+\texttt{CUBIT}. \texttt{xmeshfem3D} is not yet ready to handle faults.\\
To facilitate the mesh generation with split nodes in CUBIT, we need
to separate the two fault surfaces by a small distance, effectively
creating a tiny opening of the fault (Figure \ref{fig:examples.splitnodes},
@@ -2274,7 +2277,7 @@ offset by a small distance on either side of the fault}
\end{figure}
-The CUBIT scripts ({*}.jou and {*}.py) in the directory $\mathtt{EXAMPLES}$
+The CUBIT scripts ({*}.jou and {*}.py) in the directory \texttt{EXAMPLES}
generate more complicated meshes. The {*}.py files are Python scripts
that execute CUBIT commands and use the CUBIT-python interface for
SPECFEM3D (see next section). The Python language allows to define
@@ -2350,7 +2353,7 @@ and
\item Splay fault models from Wendt et al. (2009)\\
\end{itemize}
-Read the documents in the directory $\mathtt{EXAMPLES/*/description}$.
+Read the documents in the directory \texttt{EXAMPLES/*/description}.
They contain a description of the example and additional instructions
to run it. Visualize the results with the Matlab scripts in the directory
$\mathtt{EXAMPLES/*/post}$
@@ -2387,7 +2390,7 @@ on the foot wall).
\section{Input Files}
-Three additional input files are required in the \texttt{DATA} directory
+Three additional input files are required in the \texttt{DATA/} directory
for dynamic and kinematic faults. They are $\mathtt{Par\_file\_faults}$,
$\mathtt{FAULT\_STATIONS}$ and $\mathtt{input\_file.txt}$ (optional).
If the former does not exist, the code assumes that there are no faults.\\
@@ -2569,7 +2572,7 @@ in a purely elastic simulation. Here is how to set the time step accordingly:
\item Run a test simulation without viscosity ($\mathtt{eta}$=0 and only
a few time steps)
\item Look for the \textquotedbl{}maximum suggested time step\textquotedbl{}
-in $\mathtt{OUTPUT\_FILES/output\_mesher.txt}$. This is the critical
+in \texttt{OUTPUT\_FILES/output\_mesher.txt}. This is the critical
timestep of a purely elastic simulation, $\mathtt{dtc\_bulk}$.
\item Reset the timestep of the simulation with a Kelvin-Voigt material
to a value smaller than\\
@@ -2582,10 +2585,10 @@ than element faces on the fault.
\section{Output Files }
-Several output files are saved in $\mathtt{OUTPUT\_FILES}$:\\
+Several output files are saved in \texttt{OUTPUT\_FILES/}:\\
\begin{enumerate}
-\item Seismograms for each station on the fault plane given in $\mathtt{DATA/FAUL\_STATIONS}$.
+\item Seismograms for each station on the fault plane given in \texttt{DATA/FAUL\_STATIONS}.
One output file is generated for each station, named after the station.
The files are ascii and start with a header (22 lines long) followed
by a data block with the following format, one line per time sample:\\
@@ -2622,7 +2625,7 @@ convention controls their sign, but not their amplitude). Slip is
defined as displacement of the hanging wall relative to the footwall.
\item Seismograms at stations in the bulk (out of the fault plane) given
-in $\mathtt{DATA/STATIONS}$.
+in \texttt{DATA/STATIONS}.
\item Rupture time files are named $\mathtt{Rupture\_time\_FAULT}$-$\mathtt{id}$.
One file is generated for each fault. The files are ascii and start
with a header (12 lines long) followed by a data block with the following
@@ -2653,7 +2656,7 @@ in directory $\mathtt{utils}$. The functions are internally documented
\texttt{FSEM3D\_snapshot} reads a fault data snapshot\\
-The directories $\mathtt{EXAMPLES/*/post}$ contain additional Matlab
+The directories \texttt{EXAMPLES/*/post} contain additional Matlab
scripts to generate figures specific to each example.
@@ -2710,14 +2713,14 @@ as the regular \texttt{DATA/STATIONS} file.
\item Depending on what type of misfit function is used for the source inversion,
adjoint sources need to be computed from the original recorded seismograms
for the selected stations and saved in a sub-directory called \texttt{SEM/}
-in the root directory of the code, with the format \texttt{STA.NT.BX?.adj}, where \texttt{STA},
-\texttt{NT} are the station name and network code given in the \texttt{DATA/STATIONS\_ADJOINT}
+in the root directory of the code, with the format \texttt{NT.STA.BX?.adj}, where \texttt{NT},
+\texttt{STA} are the network code and station name given in the \texttt{DATA/STATIONS\_ADJOINT}
file, and \texttt{BX?} represents the component name of a particular
adjoint seismogram. Please note that the band code can change depending
on your sampling rate (see Appendix~\ref{cha:channel-codes} for
further details).
\item The adjoint seismograms are in the same format as the original seismogram
-(\texttt{STA.NT.BX?.sem?}), with the same start time, time interval
+(\texttt{NT.STA.BX?.sem?}), with the same start time, time interval
and record length.
\end{itemize}
\item Notice that even if you choose to time reverse only one component
@@ -2743,10 +2746,10 @@ seismograms from \texttt{LOCAL\_PATH}.
\begin{itemize}
\item These adjoint seismograms are recorded at the locations of the original
earthquake sources given by the \texttt{DATA/CMTSOLUTION} file, and
-have names of the form \texttt{S?????.NT.S??.sem} for the six-component
+have names of the form \texttt{NT.S?????.S??.sem} for the six-component
strain tensor (\texttt{SNN,SEE,SZZ,SNE,SNZ,SEZ}) at these locations,
and ~\\
- \texttt{S?????.NT.BX?.sem} for the three-component displacements
+ \texttt{NT.S?????.BX?.sem} for the three-component displacements
(\texttt{BXN,BXE,BXZ}) recorded at these locations.
\item \texttt{S?????} denotes the source number; for example, if the original
\texttt{CMTSOLUTION} provides only a point source, then the seismograms
@@ -3293,7 +3296,7 @@ This file will be created by the solver run. Then type
\end{lyxcode}
and run the executable \texttt{xcreate\_movie\_shakemap\_AVS\_DX\_GMT}
-in the \texttt{bin/} subdirectory. It will create visualization files
+in the main directory. It will create visualization files
in your format of choice. The code will prompt the user for input
parameters.
@@ -3362,8 +3365,8 @@ it in the root directory, type:
\begin{lyxcode}
{\footnotesize make~xcombine\_vol\_data~}{\footnotesize \par}
\end{lyxcode}
-which will create the executable \texttt{xcombine\_vol\_data} in the
-directory \texttt{bin/}. To output the usage of this executable, type
+which will create the executable \texttt{bin/xcombine\_vol\_data}.
+To output the usage of this executable, type
\begin{lyxcode}
{\footnotesize ./bin/xcombine\_vol\_data~}{\footnotesize \par}
\end{lyxcode}
@@ -3936,16 +3939,16 @@ while the second command rotates the processed SEM synthetics.
The forward and adjoint simulations generate synthetic seismograms
in the \texttt{OUTPUT\_FILES/} directory by default. For the forward
-simulation, the files are named like \texttt{STA.NT.BX?.semd} for
-two-column time series, or \texttt{STA.NT.BX?.semd.sac} for ASCII
-SAC format, where STA and NT are the station name and network code,
+simulation, the files are named like \texttt{NT.STA.BX?.semd} for
+two-column time series, or \texttt{NT.STA.BX?.semd.sac} for ASCII
+SAC format, where NT and STA are the network code and station name,
and \texttt{BX?} stands for the component name. Please see the Appendix~\ref{cha:Coordinates}
and \ref{cha:channel-codes} for further details.
The adjont simulations generate synthetic seismograms with the name
-\texttt{S?????.NT.S??.sem} (refer to Section \ref{sec:Adjoint-simulation-sources}
+\texttt{NT.S?????.S??.sem} (refer to Section \ref{sec:Adjoint-simulation-sources}
for details). The kernel simulations output the back-reconstructed
-synthetic seismogram in the name \texttt{STA.NT.BX?.semd}, mainly
+synthetic seismogram in the name \texttt{NT.STA.BX?.semd}, mainly
for the purpose of checking the accuracy of the reconstruction. Refer
to Section \ref{sec:Adjoint-simulation-finite} for further details.
@@ -4372,7 +4375,7 @@ in the \texttt{DATA/} subdirectory. Depending on the resolution of
your simulations, if you choose a sampling rate greater than $0.01$
s and less than $1$ s, a seismogram recording displacements on the
vertical component of a station \texttt{ASBS} (network \texttt{AZ})
-will be named \texttt{ASBS.AZ.MXZ.semd.sac}, whereas it will be \texttt{ASBS.AZ.BXZ.semd.sac},
+will be named \texttt{AZ.ASBS.MXZ.semd.sac}, whereas it will be \texttt{AZ.ASBS.BXZ.semd.sac},
if the sampling rate is greater than 0.0125 and less equal to 0.1
s.
More information about the CIG-COMMITS
mailing list