Merge pull request #476 from komatits/devel

added a sentence about varying density in fluids to the users manual

doc/USER_MANUAL/manual_SPECFEM2D.tex

@@ -187,62 +187,69 @@ \chapter{Introduction}
 
 SPECFEM2D allows users to perform 2D and 2.5D (i.e., axisymmetric) simulations of
 acoustic, elastic, viscoelastic, and poroelastic seismic wave propagation
-as well as full waveform imaging (FWI) or adjoint tomography.
+as well as full waveform imaging (FWI) or adjoint tomography.\\
+
+\red{In fluids,
+%% DK DK removed that because gravity is implemented in SPECFEM3D but not in SPECFEM2D
+% when gravity is turned off,
+SPECFEM2D uses the classical linearized Euler equation; thus if you have sharp local variations of density in the fluid (highly heterogeneous fluids
+in terms of density) or if density becomes extremely small in some regions of your model (e.g. for upper-atmosphere studies), before using the code please make sure the linearized Euler equation is a valid approximation in the case you want to study. For more details on that see e.g. \cite{COA2011}.}\\
+
 The 2D spectral-element solver accommodates
 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,
 (an)elastic, and poroelastic media. The package also considers 2D SH
 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 discontinuous \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{Kom11,MiKo10,KoMiEr09,KoErGoMi10}.
-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.
 Early seismic wave propagation applications of the SEM, utilizing Legendre basis functions and a
 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 non-diagonal 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{Kom11,MiKo10,KoMiEr09,KoErGoMi10}.
+This new release of the code includes support for GPU graphics card acceleration \citep{Kom11,MiKo10,KoMiEr09,KoErGoMi10}.\\
 
 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 the off-plane stress $\sigma_{zz}$ is not equal to zero,