[cig-commits] [commit] devel: doc: Remove extra newlines and unindentations. (35bb3c2)
cig_noreply at geodynamics.org
cig_noreply at geodynamics.org
Thu Feb 6 06:09:46 PST 2014
Repository : ssh://geoshell/specfem2d
On branch : devel
Link : https://github.com/geodynamics/specfem2d/compare/24dca31bf087ee51d2d1db912640d58ade2df07c...a3880316a04510a6c88ed36ceee2fab3c0169f6e
>---------------------------------------------------------------
commit 35bb3c269c7673191d28f03476358154d1af2cd4
Author: Elliott Sales de Andrade <esalesde at physics.utoronto.ca>
Date: Sat Jan 25 02:06:16 2014 -0500
doc: Remove extra newlines and unindentations.
Using spacing instead of indents is contrary to most LaTeX styles
guides (at least while using the default document classes), and more
importantly, was applied very inconsistently.
Several newlines were used to make pseudo-lists, so I replaced those
with real lists.
Some unindentation was used to make paragraphs appear as continuations
of an earlier paragraph. The correct way to do that is to either not
leave the blank line, or comment out the blank (such as the case with
intervening environments).
>---------------------------------------------------------------
35bb3c269c7673191d28f03476358154d1af2cd4
doc/USER_MANUAL/manual_SPECFEM2D.pdf | Bin 3119434 -> 3119748 bytes
doc/USER_MANUAL/manual_SPECFEM2D.tex | 284 ++++++++++++++++++-----------------
2 files changed, 148 insertions(+), 136 deletions(-)
diff --git a/doc/USER_MANUAL/manual_SPECFEM2D.pdf b/doc/USER_MANUAL/manual_SPECFEM2D.pdf
index dc09876..da9ac07 100644
Binary files a/doc/USER_MANUAL/manual_SPECFEM2D.pdf and b/doc/USER_MANUAL/manual_SPECFEM2D.pdf differ
diff --git a/doc/USER_MANUAL/manual_SPECFEM2D.tex b/doc/USER_MANUAL/manual_SPECFEM2D.tex
index 1d588de..fd58c7a 100644
--- a/doc/USER_MANUAL/manual_SPECFEM2D.tex
+++ b/doc/USER_MANUAL/manual_SPECFEM2D.tex
@@ -85,7 +85,7 @@
Version 7.0
}
-\date{\noindent \today}
+\date{\today}
\maketitle
@@ -94,9 +94,8 @@ The SPECFEM2D package was first developed by Dimitri Komatitsch and Jean-Pierre
and then by Dimitri Komatitsch at Harvard University (USA), Caltech (USA) and then CNRS and University of Pau (France) from 1998 to 2005.
The story started on March 28, 1995, when Prof. Yvon Maday from CNRS and University of Paris, France, gave a lecture to
Dimitri Komatitsch and Jean-Pierre Vilotte at IPG about the nice properties of the spectral-element method that he had used for
-other equations. We are deeply indebted and thankful to him for that.\\
+other equations. We are deeply indebted and thankful to him for that.
-\noindent
Since then it has been developed and maintained by a development team: in alphabetical order,
Paul Cristini,
Dimitri Komatitsch,
@@ -164,12 +163,12 @@ regular and unstructured meshes, generated for example by Cubit
\urlwithparentheses{http://cubit.sandia.gov},
Gmsh \urlwithparentheses{http://geuz.org/gmsh}
or GiD \urlwithparentheses{http://www.gid.cimne.upc.es}.
-Even mesh creation packages that generate triangles, for instance Delaunay-Voronoi triangulation codes, can be used because each triangle can then easily be decomposed into three quadrangles by linking the barycenter to the center of each edge; while this approach does not generate quadrangles of optimal quality, it can ease mesh creation in some situations and it has been shown that the spectral-element method can very accurately handle distorted mesh elements.\\
+Even mesh creation packages that generate triangles, for instance Delaunay-Voronoi triangulation codes, can be used because each triangle can then easily be decomposed into three quadrangles by linking the barycenter to the center of each edge; while this approach does not generate quadrangles of optimal quality, it can ease mesh creation in some situations and it has been shown that the spectral-element method can very accurately handle distorted mesh elements.
With version 7.0, the 2D spectral-element solver accommodates Convolution PML absorbing layers and well as higher-order time schemes
(4th order Runge-Kutta and LDDRK4-6).
Convolution or Auxiliary Differential Equation Perfectly Matched absorbing Layers (C-PML or ADE-PML)
-are described in \cite{MaKoEz08,MaKoGe08,MaKo09,MaKoGeBr10,KoMa07}.\\
+are described in \cite{MaKoEz08,MaKoGe08,MaKo09,MaKoGeBr10,KoMa07}.
The solver has adjoint capabilities and can
calculate finite-frequency sensitivity kernels \citep{TrKoLi08,PeKoLuMaLeCaLeMaLiBlNiBaTr11} for acoustic,
@@ -177,27 +176,27 @@ calculate finite-frequency sensitivity kernels \citep{TrKoLi08,PeKoLuMaLeCaLeMaL
and P-SV wave propagation. Finally, the solver can run
both in serial and in parallel. See SPECFEM2D
\urlwithparentheses{http://www.geodynamics.org/cig/software/packages/seismo/specfem2d}
-for the source code.\\
+for the source code.
The SEM is a continuous Galerkin technique \citep{TrKoLi08,PeKoLuMaLeCaLeMaLiBlNiBaTr11}, which can easily be made discontinous \citep{BeMaPa94,Ch00,KoWoHu02,ChCaVi03,LaWaBe05,Kop06,WiStBuGh10,AcKo11}; it is then close to a particular case of the discontinuous Galerkin technique \citep{ReHi73,LeRa74,Arn82,JoPi86,BoMaHe91,FaRi99,HuHuRa99,CoKaSh00,GiHeWa02,RiWh03,MoRi05,GrScSc06,AiMoMu06,BeLaPi06,DuKa06,DeSeWh08,PuAmKa09,WiStBuGh10,DeSe10,EtChViGl10}, with optimized efficiency because of its tensorized basis functions \citep{WiStBuGh10,AcKo11}.
-In particular, it can accurately handle very distorted mesh elements \citep{OlSe11}.\\
+In particular, it can accurately handle very distorted mesh elements \citep{OlSe11}.
It has very good accuracy and convergence properties \citep{MaPa89,SePr94,DeFiMu02,Coh02,DeSe07,SeOl08,AiWa09,AiWa10,MeStTh12}.
The spectral element approach admits spectral rates of convergence and allows exploiting $hp$-convergence schemes.
It is also very well suited to parallel implementation on very large supercomputers \citep{KoTsChTr03,TsKoChTr03,KoLaMi08a,CaKoLaTiMiLeSnTr08,KoViCh10}
as well as on clusters of GPU accelerating graphics cards \citep{KoMiEr09,KoErGoMi10,Kom11}.
-Tensor products inside each element can be optimized to reach very high efficiency \citep{DeFiMu02}, and mesh point and element numbering can be optimized to reduce processor cache misses and improve cache reuse \citep{KoLaMi08a}. The SEM can also handle triangular (in 2D) or tetrahedral (in 3D) elements \citep{WinBoyd96,TaWi00,KoMaTrTaWi01,Coh02,MeViSa06} as well as mixed meshes, although with increased cost and reduced accuracy in these elements, as in the discontinuous Galerkin method.\\
+Tensor products inside each element can be optimized to reach very high efficiency \citep{DeFiMu02}, and mesh point and element numbering can be optimized to reduce processor cache misses and improve cache reuse \citep{KoLaMi08a}. The SEM can also handle triangular (in 2D) or tetrahedral (in 3D) elements \citep{WinBoyd96,TaWi00,KoMaTrTaWi01,Coh02,MeViSa06} as well as mixed meshes, although with increased cost and reduced accuracy in these elements, as in the discontinuous Galerkin method.
Note that in many geological models in the context of seismic wave propagation studies
(except for instance for fault dynamic rupture studies, in which very high frequencies or supershear rupture need to be modeled near the fault, see e.g. \cite{BeGlCrViPi07,BeGlCrVi09,PuAmKa09,TaCrEtViBeSa10})
a continuous formulation is sufficient because material property contrasts are not drastic and thus
-conforming mesh doubling bricks can efficiently handle mesh size variations \citep{KoTr02a,KoLiTrSuStSh04,LeChLiKoHuTr08,LeChKoHuTr09,LeKoHuTr09}.\\
+conforming mesh doubling bricks can efficiently handle mesh size variations \citep{KoTr02a,KoLiTrSuStSh04,LeChLiKoHuTr08,LeChKoHuTr09,LeKoHuTr09}.
For a detailed introduction to the SEM as applied to regional
seismic wave propagation, please consult \citet{PeKoLuMaLeCaLeMaLiBlNiBaTr11,TrKoLi08,KoVi98,KoTr99,ChKoViCaVaFe07} and
in particular \citet{LeKoHuTr09,LeChKoHuTr09,LeChLiKoHuTr08,GoAmTaCaSmSaMaKo09,WiKoScTr04,KoLiTrSuStSh04}.
A detailed theoretical analysis of the dispersion
-and stability properties of the SEM is available in \citet{Coh02}, \citet{DeSe07}, \citet{SeOl07}, \citet{SeOl08} and \citet{MeStTh12}.\\
+and stability properties of the SEM is available in \citet{Coh02}, \citet{DeSe07}, \citet{SeOl07}, \citet{SeOl08} and \citet{MeStTh12}.
The SEM was originally developed in computational fluid dynamics \citep{Pat84,MaPa89}
and has been successfully adapted to address problems in seismic wave propagation.
@@ -205,15 +204,15 @@ Early seismic wave propagation applications of the SEM, utilizing Legendre basis
perfectly diagonal mass matrix, include \cite{CoJoTo93}, \cite{Kom97},
\cite{FaMaPaQu97}, \cite{CaGa97}, \cite{KoVi98} and \cite{KoTr99},
whereas applications involving Chebyshev basis functions and a nondiagonal mass matrix
-include \cite{SePr94}, \cite{PrCaSe94} and \cite{SePrPr95}.\\
+include \cite{SePr94}, \cite{PrCaSe94} and \cite{SePrPr95}.
All SPECFEM2D software is written in Fortran2003 with full portability
in mind, and conforms strictly to the Fortran2003 standard. It uses
no obsolete or obsolescent features of Fortran. The package uses
parallel programming based upon the Message Passing Interface (MPI)
-\citep{GrLuSk94,Pac97}.\\
+\citep{GrLuSk94,Pac97}.
-The next release of the code will include support for GPU graphics card acceleration \citep{KoMiEr09,KoErGoMi10,MiKo10,Kom11}.\\
+The next release of the code will include support for GPU graphics card acceleration \citep{KoMiEr09,KoErGoMi10,MiKo10,Kom11}.
The code uses the plane strain convention when the standard P-SV equation case is used, i.e.,
the off-plane strain $\epsilon_{zz}$ is zero by definition of the plane strain convention but thus the off-plane stress $\sigma_{zz}$ is not equal to zero,
@@ -293,9 +292,9 @@ directory in which you want to install the package, type
tar -zxvf SPECFEM2D_7.0.0.tar.gz
\end{verbatim}
The directory \texttt{SPECFEM2D-7.0.0/} will then contain
-the source code. In the following, we will refer to this directory as the root directory \texttt{SPECFEM2D/}. \\
+the source code. In the following, we will refer to this directory as the root directory \texttt{SPECFEM2D/}.
-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.\\
+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.
Then, to configure the software for your system, run the
\texttt{configure} shell script. This script will attempt to guess
@@ -303,11 +302,13 @@ the appropriate configuration values for your system. However, at
a minimum, it is recommended that you explicitly specify the appropriate
command names for your Fortran compiler (another option is to define FC, CC and MPIF90 in your .bash\_profile
or your .cshrc file):
+%
\begin{verbatim}
./configure FC=ifort
\end{verbatim}
-
+%
If you want to run in parallel, i.e., using more than one processor core, then you would type
+%
\begin{verbatim}
./configure FC=ifort MPIFC=mpif90 --with-mpi
\end{verbatim}
@@ -330,26 +331,33 @@ Fran\c{c}ois Pellegrini et al. from LaBRI and INRIA in Bordeaux, France, downloa
In case no SCOTCH libraries can be found on the system, the configuration will bundle the version provided with the source code for compilation.
The path to an existing SCOTCH installation can to be set explicitly with the option \texttt{-{}-with-scotch-dir}.
Just as an example:
+%
\begin{verbatim}
./configure FC=ifort MPIFC=mpif90 --with-mpi --with-scotch-dir=/opt/scotch
\end{verbatim}
-
+%
If you use the Intel ifort compiler to compile the code, we recommend that you use the Intel icc C compiler to compile Scotch, i.e., use:
+%
\begin{verbatim}
./configure CC=icc FC=ifort MPIFC=mpif90
\end{verbatim}
-
+%
For further details about the installation of SCOTCH,
go to subdirectory \texttt{scotch\_5.1.11/} and read \texttt{INSTALL.txt}. You may want to download more recent versions of SCOTCH in the future from \urlwithparentheses{http://www.labri.fr/perso/pelegrin/scotch/scotch_en.html} . Support for the METIS graph partitioner has been discontinued because SCOTCH is more recent and performs better.
-Edit the \texttt{Makefile} for more specific modifications. Especially, there are several options available :\\
-\texttt{-DUSE\_MPI} compiles with use of an MPI library. \\
-\texttt{-DUSE\_SCOTCH} enables use of graph partitioner SCOTCH.
-
+You may edit the \texttt{Makefile} for more specific modifications. Especially, there are several options available:
+%
+\begin{itemize}
+\item \texttt{-DUSE\_MPI} compiles with use of an MPI library.
+\item \texttt{-DUSE\_SCOTCH} enables use of graph partitioner SCOTCH.
+\end{itemize}
+%
After these steps, go back to the main directory of SPECFEM2D/ and type
+%
\begin{verbatim}
make
\end{verbatim}
+%
to create all executables which will be placed into the folder \texttt{./bin/}.
By default, the solver runs in single precision. This is fine for most application, but if for some reason
@@ -384,15 +392,13 @@ Packages such as \texttt{doxywizard} can be used to visualize the subroutine cal
\label{fig:workflow.databases}
\end{figure}
-
-\noindent
To run the mesher, please follow these steps:
-
+%
\begin{itemize}
\item edit the input file \texttt{DATA/Par\_file}, which describes the simulation.
The default \texttt{DATA/Par\_file} provided with the code contains detailed comments and should be almost self-explanatory
-(note that older \texttt{DATA/Par\_file} files provided in the \texttt{EXAMPLES} directory work fine but some of the comments
+(note that some of the older \texttt{DATA/Par\_file} files provided in the \texttt{EXAMPLES} directory work fine but some of the comments
they contain may be obsolete or even wrong; thus refer to the default \texttt{DATA/Par\_file} instead for reliable explanations).
If you need more details we do not have a detailed description of all the parameters for the 2D version in this manual
but you can find useful information in the manuals of the 3D versions, since many parameters and the general philosophy is similar. They are available at
@@ -400,7 +406,7 @@ but you can find useful information in the manuals of the 3D versions, since man
To create acoustic (fluid) regions, just set the S wave speed to zero and the code will see that these elements are fluid and switch to the right equations there automatically, and automatically match them with the solid regions
\item if you are using an external mesher (like GID or CUBIT / Trelis), you should set \texttt{read\_external\_mesh} to \texttt{.true.}:
- \begin{description}
+ \begin{description}
\item[\texttt{mesh\_file}] is the file describing the mesh : first line is the number of elements, then a list of 4 nodes (quadrilaterals only) forming each elements on each line.
\item[\texttt{nodes\_coords\_file}] is the file containing the coordinates ($x$ and $z$) of each node: number of nodes on the first line, then coordinates x and z on each line.
@@ -424,15 +430,18 @@ If you use 9-node elements, list only the first and last points of the edge and
located around the middle of the edge; the right 9-node curvature will be restored automatically by the code.
\item[\texttt{tangential\_detection\_curve\_file}] contains points describing the envelope, used for \texttt{source\_normal\_to\_surface} and \texttt{rec\_normal\_to\_surface}. Should be fine grained, and ordained clockwise. Number of points on the first line, then (x,z) coordinates on each line.
- \end{description}
+ \end{description}
\item if you have compiled with MPI, you must specify the number of processes.
\end{itemize}
+%
Then type
+%
\begin{verbatim}
./bin/xmeshfem2D
\end{verbatim}
+%
to create the mesh (which will be stored in directory \texttt{OUTPUT\_FILES/}). \texttt{xmeshfem2D} is serial; it will output several files called \texttt{Database??????}, one for each process.
%%
@@ -443,9 +452,9 @@ to create the mesh (which will be stored in directory \texttt{OUTPUT\_FILES/}).
(within gnuplot, type `\texttt{plot "OUTPUT\_FILES/gridfile.gnu" w l}`).}
\label{fig:example.mesh}
\end{figure}
-%%
Regarding mesh point numbering in the files created by the mesher, we use the classical convention of 4-node and 9-node finite elements:
+%
\begin{verbatim}
4 . . . . 7 . . . . 3
. .
@@ -457,7 +466,7 @@ Regarding mesh point numbering in the files created by the mesher, we use the cl
. .
1 . . . . 5 . . . . 2
\end{verbatim}
-\noindent
+%
the local coordinate system being $\xi$ and $\eta$ (\texttt{xi} and \texttt{eta}).
Note that this convention is used to describe the geometry only. In the solver the wave field is then described based on high-order Lagrange interpolants
at Gauss-Lobatto-Legendre points, as is classical in spectral-element methods.
@@ -479,10 +488,8 @@ The geometry is generated by loading file \texttt{SqrCirc.geo} into
Gmsh. The end of the \texttt{.geo} file contains several lines which
are required in order to define the sides of the box and the media.
This is done using the following conventions :
-
-\medskip
-
-
+%
+\begin{quote}
\texttt{\textit{Physical Line(\textquotedbl Top\textquotedbl)
= \{1\}; }}
\textsf{\textit{\small line corresponding to the top of the box}}
@@ -506,16 +513,12 @@ This is done using the following conventions :
\texttt{\textit{Physical Surface(\textquotedbl M2\textquotedbl)
= \{11,12\}; }}
\textsf{\textit{\small interior of the two circles}}
-
-\medskip
-
-
+\end{quote}
+%
For instance, if you want to fill the two circles with two different
materials, you will have to write :
-
-\medskip
-
-
+%
+\begin{quote}
\texttt{\textit{Physical Surface(\textquotedbl M1\textquotedbl)
= \{10\}; }}
\textsf{\textit{\small surrounding medium}}
@@ -527,10 +530,8 @@ materials, you will have to write :
\texttt{\textit{Physical Surface(\textquotedbl M3\textquotedbl)
= \{12\}; }}
\textsf{\textit{\small interior of the small circle}}
-
-\medskip
-
-
+\end{quote}
+%
and, consequently, you will have to define a new medium numbered \texttt{3}
in the \texttt{Par\_file}.
@@ -539,7 +540,6 @@ in the \texttt{Par\_file}.
\caption{Geometry and mesh of the two circle model generated with Gmsh\label{fig:Gmsh-example}}
\end{figure}
-
Then, a 2D mesh can be created and saved after selecting the appropriate
options in Gmsh : \texttt{All quads} in \texttt{Subdivision algorithm}
and \texttt{1} or \texttt{2} in \texttt{Element order} whether you
@@ -547,15 +547,18 @@ want a 4 or 9 node mesh. This operation will generate a \texttt{SqrCirc.msh}
file which must be processed to get all the files required by SPECFEM2D
when using an external mesh (see previous section). This is done by
running a python script called LibGmsh2Specfem.py, located in directory UTILS/Gmsh:
+%
\begin{verbatim}
python LibGmsh2Specfem.py SqrCirc -t A -b A -r A -l A
\end{verbatim}
+%
Where the options \texttt{-t}, \texttt{-b},\texttt{ -r} and \texttt{-l}
represent the different sides of the model (top, bottom, right and
left) and can take the values \texttt{A} or \texttt{F} if the corresponding
side is respectively absorbing or free. All boundaries are absorbing
by default. The connections of the generated filenames to the filenames
indicated in the previous section are :
+%
\begin{itemize}
\item \texttt{Mesh\_SqrCirc} is the \texttt{\textbf{mesh\_file}}
\item \texttt{Material\_SqrCirc} is the \texttt{\textbf{material\_file}}
@@ -563,8 +566,9 @@ indicated in the previous section are :
\item \texttt{Surf\_abs\_SqrCirc} is the \texttt{\textbf{absorbing\_surface\_file}}
\item \texttt{Surf\_free\_SqrCirc} is the \texttt{\textbf{free\_surface\_file}}
\end{itemize}
+%
In addition, four files like \texttt{free\_surface\_file} corresponding
-to the sides of the model are generated.\\
+to the sides of the model are generated.
If you use CPML, an additional file listing the CPML elements is needed.
Its first line is the total number of
@@ -611,13 +615,10 @@ you should be careful because mathematically a PML cannot handle heterogeneities
normal to the PML edge inside the PML layer. This comes from the fact that the damping profile
that is defined assumes a constant velocity and density model along the normal
direction.
-
Thus, you need to modify your velocity and density model in order for it to be 1D inside
the PML, as shown in Figure~\ref{fig:modify_external_velocity_model_to_use_PML}.
-
This applies to the bottom layer as well; there you should make sure
that your model is 1D and thus constant along the vertical direction.
-
To summarize, only use a 2D velocity and density model inside the physical region, and in
all the PML layers extend it by continuity from its values along the
inner PML edge.
@@ -638,17 +639,21 @@ are significantly less efficient).}
%------------------------------------------------------------------------------------------------%
To examine the quality of the elements in your externally build mesh, type
+%
\begin{verbatim}
./bin/xcheck_quality_external_mesh
\end{verbatim}
+%
(and answer "3" to the first question asked).
This code will tell you which element in the whole mesh has the worst quality (maximum skewness, i.e. maximum deformation of the element angles) and it should be enough to modify this element with the external software package used for the meshing, and
to repeat the operation until the maximum skewness of the whole mesh is less or equal to about 0.75 (above is dangerous: from 0.75 to 0.80 could still work, but if there is a single element above 0.80 the mesh should be improved).
The code also shows a histogram of 20 classes of skewness which tells how many element are above the skewness = 0.75, and to which percentage of the total this amounts. To see this histogram, you could type:
+%
\begin{verbatim}
gnuplot plot_mesh_quality_histogram.gnu
\end{verbatim}
+%
This tool is useful to estimate the mesh quality and to see it evolve along the successive corrections.
%------------------------------------------------------------------------------------------------%
@@ -656,6 +661,7 @@ This tool is useful to estimate the mesh quality and to see it evolve along the
%------------------------------------------------------------------------------------------------%
To examine (using Gnuplot) how the mesh samples the wave field, type
+%
\begin{verbatim}
gnuplot plot_points_per_wavelength_histogram.gnu
\end{verbatim}
@@ -671,7 +677,7 @@ and also check the following histogram printed on the screen or in the output fi
and 5.5 in acoustic media)
\end{verbatim}
-\noindent If you see that you have a significant number of mesh elements below the threshold indicated, then your simulations
+If you see that you have a significant number of mesh elements below the threshold indicated, then your simulations
will not be accurate and you should create a denser mesh. Conversely, if you have a significant number of mesh elements above the threshold indicated,
the mesh your created is too dense, it will be extremely accurate but the simulations will be slow; using a coarser mesh would be sufficient and would lead to faster simulations.
@@ -682,12 +688,13 @@ the mesh your created is too dense, it will be extremely accurate but the simula
%------------------------------------------------------------------------------------------------%
To run the solver, type:
+%
\begin{verbatim}
./bin/xspecfem2D
\end{verbatim}
+%
to run the main solver (use \texttt{mpirun} or equivalent if you compiled with parallel support). This will output the seismograms and snapshots of the wave fronts at different time steps in directory \texttt{OUTPUT\_FILES/}. To visualize them, type "\texttt{gs OUTPUT\_FILES/vect*.ps}" to see the Postscript files (in which the wave field is represented with small arrows, fluid/solid matching interfaces with a thick pink line, and absorbing edges with a thick green line) and "\texttt{gimp OUTPUT\_FILES/image*.gif}" to see the color snapshot showing a pixelized image of one of the two components of the wave field (or pressure, depending on what you have selected for the output in \texttt{DATA/Par\_file}).
-
%%
\begin{figure}[htbp]
\centering
@@ -699,8 +706,8 @@ to run the main solver (use \texttt{mpirun} or equivalent if you compiled with p
\end{figure}
%%
-\noindent
Please consider these following points, when running the solver:
+%
\begin{itemize}
\item the \texttt{DATA/Par\_file} given with the code works fine, you can use it without any modification to test the code
@@ -728,8 +735,8 @@ Replace \texttt{surange} with \texttt{suxwigb} to see wiggle plots for the seism
\end{itemize}
-\noindent
The \texttt{SOURCE} file located in the \texttt{DATA/} directory should be edited in the following way:
+%
\begin{description}
\item[source\_surf] Set this flag to \texttt{.true.} to force the source to be located at the surface of the model, otherwise
the source will be placed inside the medium
@@ -769,9 +776,11 @@ the serial code \texttt{convolve\_source\_timefunction.f90} and the
script \texttt{convolve\_source\_timefunction.sh} for this purpose,
or alternatively use signal-processing software packages such as SAC \urlwithparentheses{www.llnl.gov/sac}.
Type
+%
\begin{verbatim}
- make convolve_source_timefunction
+ make xconvolve_source_timefunction
\end{verbatim}
+%
to compile the code and then set the parameter \texttt{hdur} in \texttt{convolve\_source\_timefunction.sh}
to the desired half-duration.
%%
@@ -793,6 +802,7 @@ in the post-processing. This time shift parameter can be non-zero when using mul
\item[Mxx,Mzz,Mxz] Moment tensor components (valid only for moment tensor sources, source\_type "2").
Note that the units for the components of a moment tensor source are different in SPECFEM2D and in SPECFEM3D:
+%
\begin{description}
\item[SPECFEM3D:] in SPECFEM3D the moment tensor components are in dyne*cm
\item[SPECFEM2D:] in SPECFEM2D the moment tensor components are in N*m
@@ -814,6 +824,7 @@ Dunzhu Li, Don Helmberger, Robert W. Clayton and Daoyuan Sun, submitted to Geoph
\item[factor] amplification factor
\end{description}
+
Note, the zero time of the simulation corresponds to the center of the triangle/Gaussian,
or the centroid time of the earthquake. The start time of the simulation
is $t=-1.2*\texttt{half duration} + \texttt{t0}$ (the factor 1.2 is to make sure the moment
@@ -822,9 +833,6 @@ the half duration is obtained by 1/f0.
If you prefer, you can fix this start time by setting the parameter \texttt{USER\_T0} in the \texttt{constants.h} file
to a positive, non-zero value. The simulation in that case would start at a starting time equal to \texttt{-USER\_T0}.
-
-
-
%------------------------------------------------------------------------------------------------%
\subsection*{Caution}
%------------------------------------------------------------------------------------------------%
@@ -832,15 +840,11 @@ to a positive, non-zero value. The simulation in that case would start at a star
See file \texttt{todo\_list\_please\_dont\_remove.txt} for a list of known bugs, problems, or missing options.
%------------------------------------------------------------------------------------------------%
-
\subsection*{Coupled Simulations}
-
%------------------------------------------------------------------------------------------------%
The code supports acoustic/elastic, acoustic/poroelastic, elastic/poroelastic,
-and acoustic,elastic/poroelastic simulations.\\
-
-\noindent
+and acoustic, elastic/poroelastic simulations.
Elastic/poroelastic coupling supports anisotropy, but not attenuation for the
elastic material.
@@ -850,6 +854,7 @@ elastic material.
%------------------------------------------------------------------------------------------------%
For elastic materials, you have these additional options:
+%
\begin{description}
\item[P-SV:]
To run a P-SV waves calculation propagating in the x-z plane,
@@ -860,11 +865,11 @@ To run a SH (membrane) waves calculation traveling in the x-z plane with a
y-component of motion, set \texttt{p\_sv = .false.}
\end{description}
+%
This feature is only implemented for elastic materials and sensitivity kernels
can be calculated (see \cite{TaLiTr07} for details on membrane
surface waves).
-
A useful Python script called \texttt{SEM\_save\_dir.py}, written by Paul Cristini from
Laboratoire de Mecanique et d'Acoustique, CNRS, Marseille, France, is provided.
It allows one to automatically save all the parameters and results of a given simulation.
@@ -873,11 +878,9 @@ It allows one to automatically save all the parameters and results of a given si
\section{How to use anisotropy}
%------------------------------------------------------------------------------------------------%
-\begin{flushleft}
Following \cite{CaKoKo88}, we use the classical reduced Voigt notation to represent symmetric
tensors \citep{Hel94,Car07}:
-\end{flushleft}
-%%%
+%
\begin{quotation}
The constitutive relation of a heterogeneous anisotropic and elastic solid
is expressed by the generalized Hooke's law, which can be written as
@@ -905,8 +908,7 @@ replaced by a single number according to the following correspondence:
(12) = (21) \rightarrow 6.
\end{align*}
\end{quotation}
-
-\noindent
+%
Thus in the most general 2D case we have the following convention for the stress-strain relationship:
%
\begin{verbatim}
@@ -929,6 +931,7 @@ where the notations are for instance \texttt{duz\_dx = d(Uz) / dx}.
%------------------------------------------------------------------------------------------------%
Check the following new inputs in \texttt{Par\_file}:
+%
\begin{description}
\item In section \textbf{"\# geometry of model and mesh description"}:\\
\texttt{TURN\_VISCATTENUATION\_ON}, \texttt{Q0}, and \texttt{FREQ0} deal with viscous damping in a poroelastic medium.
@@ -1007,6 +1010,7 @@ permeability.
%------------------------------------------------------------------------------------------------%
\section{How to set plane waves as initial conditions}
To simulate propagation of incoming plane waves in the simulation domain, initial conditions based on analytical formulae of plane waves in homogenous model need to be set. No additional body or boundary forces are required. To set up this senario:
+%
\begin{description}
\item{\verb+Par_file+:}
\begin{itemize}
@@ -1070,8 +1074,6 @@ Degree $N$ & Newmark & LDDRK4-6 & RK4 \\ [0.5ex]
% is used to refer this table in the text
\end{table}
%
-\clearpage
-\noindent
\begin{table}[t]
\caption{CFL upper bound for an elastic simulation with Vp/Vs = $\sqrt{2}$.}
% title of Table
@@ -1118,43 +1120,53 @@ Degree $N$ & Newmark & LDDRK4-6 & RK4 \\ [0.5ex]
%------------------------------------------------------------------------------------------------%
\begin{enumerate}
-\item[1.] Run a forward simulation: \\
-=> \texttt{SIMULATION\_TYPE = 1} \\
-=> \texttt{SAVE\_FORWARD = .true.}\\
-=> \texttt{seismotype = 1} (we need to save the displacement fields to later on derive the
+\item Run a forward simulation:
+\begin{itemize}
+\item \texttt{SIMULATION\_TYPE = 1}
+\item \texttt{SAVE\_FORWARD = .true.}
+\item \texttt{seismotype = 1} (we need to save the displacement fields to later on derive the
adjoint source. Note: if the user forgets it, the program corrects it when reading the proper
\texttt{SIMULATION\_TYPE} and \texttt{SAVE\_FORWARD} combination and a warning message appears in the ouput
-file)\\
-
-Important output files (for example, for the elastic case, P-SV waves): \\
-\texttt{absorb\_elastic\_bottom*****.bin}\\
-\texttt{absorb\_elastic\_left*****.bin}\\
-\texttt{absorb\_elastic\_right*****.bin}\\
-\texttt{absorb\_elastic\_top*****.bin}\\
-\texttt{lastframe\_elastic*****.bin}\\
-\texttt{S****.AA.BXX.semd}\\
-\texttt{S****.AA.BXZ.semd}\\
-
-\item[2.] Define the adjoint source: \\
-Use \texttt{adj\_seismogram.f90}\\
-Edit to update \texttt{NSTEP}, \texttt{nrec}, \texttt{t0}, \texttt{deltat}, and the position of the cut to pic
+file)
+\end{itemize}
+
+Important output files (for example, for the elastic case, P-SV waves):
+\begin{itemize}
+\item \texttt{absorb\_elastic\_bottom*****.bin}
+\item \texttt{absorb\_elastic\_left*****.bin}
+\item \texttt{absorb\_elastic\_right*****.bin}
+\item \texttt{absorb\_elastic\_top*****.bin}
+\item \texttt{lastframe\_elastic*****.bin}
+\item \texttt{S****.AA.BXX.semd}
+\item \texttt{S****.AA.BXZ.semd}
+\end{itemize}
+
+\item Define the adjoint source:
+\begin{itemize}
+\item Use \texttt{adj\_seismogram.f90}
+\item Edit to update \texttt{NSTEP}, \texttt{nrec}, \texttt{t0}, \texttt{deltat}, and the position of the cut to pick
any given phase if needed (\texttt{tstart},\texttt{tend}), add the right number of stations, and
put one component of the source to zero if needed.
-The ouput files of \texttt{adj\_seismogram.f90} are \texttt{S****.AA.BXX.adj} and \texttt{S****.AA.BXZ.adj}, for P-SV waves (and
+\item The output files of \texttt{adj\_seismogram.f90} are \texttt{S****.AA.BXX.adj} and \texttt{S****.AA.BXZ.adj}, for P-SV waves (and
\texttt{S****.AA.BXY.adj}, for SH (membrane) waves). Note that you will need these three
files (\texttt{S****.AA.BXX.adj}, \texttt{S****.AA.BXY.adj} and \texttt{S****.AA.BXZ.adj}) to be present in the \texttt{SEM/} directory
together with the \texttt{absorb\_elastic\_****.bin} and \texttt{lastframe\_elastic.bin} files to be read
-when running the adjoint simulation.\\
+when running the adjoint simulation.
+\end{itemize}
-\item[3.] Run the adjoint simulation: \\
-Make sure that the adjoint source files absorbing boundaries and last frame files are
-in the \texttt{OUTPUT\_FILES/} directory.\\
-=> \texttt{SIMULATION\_TYPE = 3}\\
-=> \texttt{SAVE\_FORWARD = .false.}\\
+\item Run the adjoint simulation:
+\begin{itemize}
+\item Make sure that the adjoint source files absorbing boundaries and last frame files are
+in the \texttt{OUTPUT\_FILES/} directory.
+\item \texttt{SIMULATION\_TYPE = 3}
+\item \texttt{SAVE\_FORWARD = .false.}
+\end{itemize}
-Output files (for example for the elastic case):\\
-\texttt{snapshot\_rho\_kappa\_mu*****}\\
-\texttt{snapshot\_rhop\_alpha\_beta*****}\\
+Output files (for example for the elastic case):
+\begin{itemize}
+\item \texttt{snapshot\_rho\_kappa\_mu*****}
+\item \texttt{snapshot\_rhop\_alpha\_beta*****}
+\end{itemize}
which are the primary moduli kernels and the phase velocities kernels respectively, in ascii format
and at the local level, that is as "kernels(i,j,ispec)".
@@ -1166,19 +1178,19 @@ and at the local level, that is as "kernels(i,j,ispec)".
SPECFEM2D can produce the gradient of the misfit function for a
tomographic inversion, but options for using the gradient within an
iterative inversion are left to the user (e.g., conjugate-gradient,
-steepest descent). The plan is to include some examples in the future.\\
+steepest descent). The plan is to include some examples in the future.
% This from Yang Luo:
The algorithm is simple:
-
+%
\begin{enumerate}
-\item[1.] calculate the forward wave field $\mathbf{s}(x,t)$
-\item[2.] calculate the adjoint wave field $\mathbf{s}^\dagger(x,t)$
-\item[3.] calculate their interaction $\mathbf{s}(x,t) \cdot \mathbf{s}^\dagger(x,T-t)$ (these symbolic, temporal and spatial derivatives should be included)
-\item[4.] integrate the interactions, which is summation in the code.
+\item calculate the forward wave field $\mathbf{s}(x,t)$
+\item calculate the adjoint wave field $\mathbf{s}^\dagger(x,t)$
+\item calculate their interaction $\mathbf{s}(x,t) \cdot \mathbf{s}^\dagger(x,T-t)$ (these symbolic, temporal and spatial derivatives should be included)
+\item integrate the interactions, which is summation in the code.
\end{enumerate}
-
-That is all. Step 3 has some tricks in implementation, but which can be skipped by regular users.\\
+%
+That is all. Step 3 has some tricks in implementation, but which can be skipped by regular users.
If you look into SPECFEM2D, besides "rhop\_ac\_kl" and "rho\_ac\_kl",
there are more variables such as "kappa\_ac\_kl" and "rho\_el\_kl" etc.
@@ -1188,7 +1200,8 @@ there are more variables such as "kappa\_ac\_kl" and "rho\_el\_kl" etc.
\subsection*{Caution}
-Please note that
+Please note that:
+%
\begin{itemize}
\item at the moment, adjoint simulations do not support anisotropy, attenuation, and viscous damping.
@@ -1217,6 +1230,7 @@ We also changed the relationship between adjoint potential and adjoint displacem
(the relationship between forward potential and forward displacement remains the same as previsouly defined).
The new definition is critical when there are adjoint sources (in other words, receivers) in the acoustic domain,
and is the direct consequence of the optimization problem.
+%
\begin{eqnarray*}
\mathbf{s}&\equiv&\frac{1}{\rho}~\mathbf{\nabla}\phi \\
p&\equiv&-\kappa(\nabla\cdot\mathbf{s}) =-\partial_t^2\phi \\
@@ -1239,7 +1253,6 @@ of Technology, Department of Mechanical Engineering (Cambridge, Massachusetts, U
The non-structured global numbering software was provided by Paul
F. Fischer (Brown University, Providence, Rhode Island, USA, now at Argonne National Laboratory, USA).
-
Please e-mail your feedback, questions, comments, and suggestions
to Jeroen Tromp \urlwithparentheses{jtromp-AT-princeton.edu} or to the CIG Computational Seismology Mailing List \urlwithparentheses{cig-seismo at geodynamics.org}.
@@ -1250,13 +1263,14 @@ to Jeroen Tromp \urlwithparentheses{jtromp-AT-princeton.edu} or to the CIG Compu
%------------------------------------------------------------------------------------------------%
+\begin{quote}
Main historical authors: Dimitri Komatitsch and Jeroen Tromp
Princeton University, USA,
and CNRS / INRIA / University of Pau, France
$\copyright$ Princeton University and CNRS / INRIA / University of Pau, July 2012
-
+\end{quote}
%------------------------------------------------------------------------------------------------%
@@ -1278,34 +1292,39 @@ $\copyright$ Princeton University and CNRS / INRIA / University of Pau, July 201
\section*{FAQ}
-\begin{description}
-\item[Regarding the structure of some of the database files] : \newline
+\subsection*{Regarding the structure of some of the database files}
-\textbf{Question:} Can anyone tell me what the columns of the SPECFEM2D boundary
+\paragraph{Question:} Can anyone tell me what the columns of the SPECFEM2D boundary
condition files in \texttt{SPECFEM2D/DATA/}~\\
-\texttt{Mesh\_canyon} are?\\
-
-\texttt{SPECFEM2D/DATA/Mesh\_canyon/canyon\_absorbing\_surface\_file} \\
-\texttt{SPECFEM2D/DATA/Mesh\_canyon/canyon\_free\_surface\_file}
+\texttt{Mesh\_canyon} are?
+%
+\begin{verbatim}
+ SPECFEM2D/DATA/Mesh_canyon/canyon_absorbing_surface_file
+ SPECFEM2D/DATA/Mesh_canyon/canyon_free_surface_file
+\end{verbatim}
-\textbf{Answer:} \texttt{canyon\_absorbing\_surface\_file} refers to parameters related to the
+\paragraph{Answer:} \texttt{canyon\_absorbing\_surface\_file} refers to parameters related to the
absorbing conditions:
The first number (180) is the number of absorbing elements (nelemabs in the
code).
-Then the columns are:\\
-column 1 = the element number\\
-column 2 = the number of nodes of this element that form the absorbing surface\\
-column 3 = the first node\\
-column 4 = the second node\\
+Then the columns are:
+\begin{itemize}
+\item column 1 = the element number
+\item column 2 = the number of nodes of this element that form the absorbing surface
+\item column 3 = the first node
+\item column 4 = the second node
+\end{itemize}
\texttt{canyon\_free\_surface\_file} refers to the elements of the free surface
(relevant for enforcing free surface condition for acoustic media):
The first number (160) is the number of elements of the free surface.
-Then the columns are (similar to the absorbing case):\\
-column 1 = the element number\\
-column 2 = the number of nodes of this element that form the absorbing surface\\
-column 3 = the first node\\
-column 4 = the second node\\
+Then the columns are (similar to the absorbing case):
+\begin{itemize}
+\item column 1 = the element number
+\item column 2 = the number of nodes of this element that form the absorbing surface
+\item column 3 = the first node
+\item column 4 = the second node
+\end{itemize}
Concerning the free surface description file, nodes/edges pertaining to
elastic elements are discarded when the file is read (if for whatever
@@ -1317,13 +1336,6 @@ These files are opened and read in \texttt{meshfem2D.F90} using subroutines
\texttt{read\_abs\_surface()} and \texttt{read\_}~\\
\texttt{acoustic\_surface()}, which are in \texttt{part\_unstruct.F90}
-
-
-
-
-\end{description}
-
-
%------------------------------------------------------------------------------------------------%
\end{document}
More information about the CIG-COMMITS
mailing list