Merge pull request #1166 from danielpeter/devel

bug fix for binary databases; updates contributing infos and doc; update noise routines

CONTRIBUTING.md

@@ -1 +1,80 @@
-Instruction for how to contribute to SPECFEM2D are available at https://github.com/SPECFEM/specfem3d/wiki.
+# Contributing to SPECFEM2D
+
+You want to contribute to the SPECFEM code? Great, let's check out this set of simple guidelines to follow for contributions.
+
+## Contributing as a user
+
+Software needs constant maintaining and updating to keep up with newest hardware and compilers.
+You found an issue when running the code? Please consider creating a "*New issue*" on the [SPECFEM2D Issues github page](https://github.com/SPECFEM/specfem2d/issues). 
+
+Describe the problem as detailed as possible to help us reproduce the error. You can also attach console outputs from the executables to make it easier for debugging. Feel free to add an appropriate label to highlight the issue by checking out "*Labels*" on the right side of the page. Once done, click the button "*Submit new issue*". Catching bugs is always welcome, many thanks to you for improving the code!
+
+## Contributing as a developer
+
+You have a new feature, bug fix, or other modification you want to contribute to the code? In this case, consider submitting a "*Pull request*" to the **devel branch** of our github code repository. 
+
+This will require a few steps to setup your own github fork and be able to create a PR to the official devel version of the SPECFEM code (**note that only Pull requests towards devel are accepted**). The most basic setup looks the following:
+
+1. Create your fork of the repository:<br>
+Go to the main [SPECFEM2D github repository](https://github.com/SPECFEM/specfem2d) and click the "*Fork*" button at the top of the page. This will create a copy of the SPECFEM2D repository in your personal GitHub account.
+
+2. Clone your fork to your local workstation/laptop:<br>
+```
+git clone --recursive --branch devel https://github.com/SPECFEM/specfem2d.git
+```
+Once you change into your local folder `cd specfem2d/`, all git commands will be recognized.  
+Now, add the remote address of the SPECFEM2D repository:
+```
+git remote add upstream https://github.com/SPECFEM/specfem2d.git
+```
+With `git remote -v`, you should see now an output like:
+```
+origin  https://github.com/<your-github-account-name>/specfem2d.git (fetch)
+origin  https://github.com/<your-github-account-name>/specfem2d.git (push)
+upstream  https://github.com/SPECFEM/specfem2d.git (fetch)
+upstream  https://github.com/SPECFEM/specfem2d.git (push)
+```
+Please make sure that your local version is up-to-date with the upstream version. To so, you can either call 
+```
+git pull upstream devel
+```
+or 
+```
+git fetch upstream
+git rebase --interactive upstream/devel
+```
+
+3. Apply your modifications to your local code and commit your changes:<br>
+Check first the status of the files, and/or differences applied before committing, by typing
+``` 
+git status
+```
+and
+``` 
+git diff
+```
+Then, create the commit with a short descriptive message by
+```
+git commit -m "<my-commit-description-message>"
+```
+Remember that it is good practice to have small commits with a single purpose.
+
+4. Push your modifications to your github repository:<br>
+```
+git push
+```
+
+5. Now, open a new "*Pull request*" on the github website:<br>
+Go to your personal github repository website, and possibly click on the branch button to change to the **devel** branch. 
+Github might already recognize that you have new changes uploaded, sees that your branch is "*ahead of SPECFEM:devel*" and provides you with the option to "*Contribute*" by clicking on the "*Open pull request*" button.<br><br>
+In the "*Open a pull request*" page, double-check that the base repository is: **SPECFEM/specfem2d, base: devel**. The head repository should be your personal fork with "*compare: devel*". Write an appropriate title and add more descriptions to your pull request in the "*Leave a comment*" section. Finally, click the "*Create pull request*" button.
+
+6. We'll do the rest by reviewing your code changes, checking if the Github Actions, Travis and Azure checks all look okay. We might follow up with you by commenting on the PR, as you can still fix smaller issues in the PR by committing them to your github fork version.<br>
+
+Finally, if the are no merge conflicts, the new version still compiles and tests pass, we'll merge your PR into the SPECFEM devel version - **with big thanks to you from the maintainers and the whole community!**
+
+
+## Further informations
+
+More detailed developer informations and instructions for how to contribute in general to SPECFEM codes are available at:<br>
+[https://github.com/SPECFEM/specfem3d/wiki](https://github.com/SPECFEM/specfem3d/wiki).

EXAMPLES/noise_uniform/changemask.sh

@@ -1,7 +1,5 @@
 #!/bin/bash
 
-codefile=../../src/specfem2D/noise_tomography.f90
-
 mask=$1
 if [ "$mask" == "" ]; then echo "./changemask [uniform/nonuniform]"; exit 1; fi
 
@@ -10,43 +8,17 @@ echo "mask: $mask"
 echo
 if [ "$mask" == "uniform" ]; then
 echo "setting uniform mask ..."
-sed -i "s:NOISE_DIST_TYPE =.*;NOISE_DIST_TYPE = 0:" $codefile
+echo "0" > NOISE_TOMOGRAPHY/use_non_uniform_noise_distribution
 
 elif [ "$mask" == "nonuniform" ]; then
 echo "setting nonuniform mask ..."
-sed -i "s:NOISE_DIST_TYPE =.*;NOISE_DIST_TYPE = 1:" $codefile
+echo "1" > NOISE_TOMOGRAPHY/use_non_uniform_noise_distribution
 
 else
 echo "mask: $mask not recognized, please use uniform or nonuniform"
 exit 1
 fi
 
 echo
-echo "done, see file: $codefile"
-echo "Please recompile source code to take effect..."
+echo "done, see file: NOISE_TOMOGRAPHY/use_non_uniform_noise_distribution"
 echo
-
-# obsolete... but left for reference
-#cd masks
-#select maskfile in `find -type f`
-#do
-#case $maskfile in
-#    *) echo $maskfile; break;;
-#esac
-#done
-#cd ..
-
-
-#line1=`grep -n '^[ \t]*subroutine create_mask_noise' $codefile | cut -d':' -f1`
-#line2=`grep -n '^[ \t]*end subroutine create_mask_noise' $codefile | cut -d':' -f1`
-
-#if [ `echo $line1 | wc -l` -ne 1 ]; then echo "Error reading noise_tomography.f90"; exit 1; fi
-#if [ `echo $line2 | wc -l` -ne 1 ]; then echo "Error reading noise_tomography.f90"; exit 2; fi
-#if [ ! -n "$line1" ]; then echo "Error reading noise_tomography.f90"; exit 3; fi
-#if [ ! -n "$line2" ]; then echo "Error reading noise_tomography.f90"; exit 4; fi
-
-#awk -vline1=$line1 '{if (NR < line1) print $0}' < $codefile > temp1
-#awk -vline2=$line2 '{if (NR > line2) print $0}' < $codefile > temp2
-
-#cat temp1 masks/$maskfile temp2 > $codefile
-#rm temp?

doc/USER_MANUAL/01_introduction.tex

@@ -6,53 +6,53 @@ \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.\newline
 
 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}.\\
+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}.\newline
 
 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.\newline
 
 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}.\newline
 
 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{https://github.com/SPECFEM/specfem2d}
-for the source code.\\
+for the source code.\newline
 
 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}.\newline
 
 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.\newline
 
 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}.\newline
 
 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}.\newline
 
 The SEM was originally developed in computational fluid dynamics \citep{Pat84,MaPa89}
 and has been successfully adapted to address problems in seismic wave propagation.
@@ -62,23 +62,23 @@ \chapter{Introduction}
 whereas applications involving Chebyshev basis functions and a non-diagonal mass matrix
 include \cite{SePr94}, \cite{PrCaSe94} and \cite{SePrPr95}.
 In the Legendre version that we use in SPECFEM the mass matrix is purposely slightly inexact but diagonal (but can be made exact if needed, see \cite{Teu15}),
-while in the Chebyshev version it is exact but non diagonal.\\
+while in the Chebyshev version it is exact but non diagonal.\newline
 
 Beware that, in a spectral-element method, some spurious modes (that have some similarities with classical so-called "Hourglass modes" in finite-element techniques,
 although in the SEM they are not zero-energy modes) can appear in some (but not all) cases in the spectral element in which the source is located.
 Fortunately, they do not propagate away from the source element.
 However, this means that if you put a receiver in the same spectral element as a source, the recorded signals may in some cases be wrong, typically exhibiting some spurious
 oscillations, which are often even non causal.
 If that is the case, an easy option is to slightly change the mesh in the source region in order to get rid of these Hourglass-like spurious modes,
-as explained in \cite{DuLiScGa14}, in which this phenomenon is described in details, and in which practical solutions to avoid it are suggested.\\
+as explained in \cite{DuLiScGa14}, in which this phenomenon is described in details, and in which practical solutions to avoid it are suggested.\newline
 
 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}.\newline
 
-This new release of the code includes 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}.\newline
 
 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,
@@ -90,7 +90,7 @@ \chapter{Introduction}
 \section{Citation}
 %------------------------------------------------------------------------------------------------%
 
-You can find all the references below in \BibTeX format in file \texttt{doc/USER\_MANUAL/bibliography.bib}.\\
+You can find all the references below in \BibTeX format in file \texttt{doc/USER\_MANUAL/bibliography.bib}.\newline
 
 If you use this code for your own research, please cite at least one article
 written by the developers of the package, for instance:

doc/USER_MANUAL/02_getting_started.tex

@@ -35,7 +35,8 @@ \chapter{Getting Started}\label{cha:Getting-Started}
 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:
 
 \begin{description}[font=\ttfamily]
-\item [Intel ifort compiler] See if you need to add \texttt{-assume byterecl} for your machine.\\
+\item [Intel ifort compiler] See if you need to add \texttt{-assume byterecl} for your machine.\newline
+
 In the case of that compiler, we have noticed that initial release versions sometimes have bugs or issues that can lead to wrong results when running the code, thus we \emph{strongly} recommend using a version for which at least one service pack or update has been installed.
 \red{In particular, for version 17 of that compiler, users have reported problems (making the code crash at run time) with the \texttt{-assume buffered\_io} option; if you notice problems,
 remove that option from file \texttt{flags.guess} or change it to \texttt{-assume nobuffered\_io} and try again.}
@@ -94,7 +95,7 @@ \chapter{Getting Started}\label{cha:Getting-Started}
 
 If you have problems configuring the code on a Cray machine, i.e. for instance if you get an error message from the \texttt{configure} script, try exporting these two variables:
 \texttt{MPI\_INC=\${CRAY\_MPICH2\_DIR}/include and FCLIBS=" "}, and for more details if needed you can refer to the \texttt{utils/Cray\_compiler\_information} directory.
-You can also have a look at the configure script called\\
+You can also have a look at the configure script called\newline
 \texttt{utils/Cray\_compiler\_information/configure\_SPECFEM\_for\_Piz\_Daint.bash}.
 
 \section{Visualizing the subroutine calling tree of the source code}
@@ -104,10 +105,10 @@ \section{Visualizing the subroutine calling tree of the source code}
 
 \section{Becoming a developer of the code, or making small modifications in the source code}
 
-If you want to develop new features in the code, and/or if you want to make small changes, improvements, or bug fixes, you are very welcome to contribute.\\
+If you want to develop new features in the code, and/or if you want to make small changes, improvements, or bug fixes, you are very welcome to contribute.\newline
 
-To do so, i.e. to access the development branch of the source code with read/write access (in a safe way, no need to worry too much about breaking the package, there is a robot called BuildBot that is in charge of checking and validating all new contributions and changes), please visit this Web page:\\
-\url{https://github.com/SPECFEM/specfem2d/wiki}\\
+To do so, i.e. to access the development branch of the source code with read/write access (in a safe way, no need to worry too much about breaking the package, there is a robot called BuildBot that is in charge of checking and validating all new contributions and changes), please visit this Web page:\newline
+\url{https://github.com/SPECFEM/specfem2d/wiki}\newline
 
 \noindent
 To visualize the call tree (calling tree) of the source code, you can see the Doxygen tool available in directory \texttt{doc/call\_trees\_of\_the\_source\_code}.