updated manual

Still changes to be done in toy example chapter.
(figures with rotated coordinate system)

doc/latex/manual_howto.tex

@@ -10,9 +10,9 @@ The code was tested on our local workstation cluster using Suse Linux and OpenMP
 \begin{small}
 \begin{tabular}{lll}
 Program & Description & Weblink \\ 
-OpenMPI & MPI Implementation & \tiny{\url{http://www.mcs.anl.gov/research/projects/mpich2}} \\
+OpenMPI & MPI Implementation & \url{http://www.open-mpi.org} \\
  & (for the parallelization) & \\
-MPICH2 & MPI Implementation & \url{http://www.open-mpi.org} \\  
+MPICH2 & MPI Implementation & \tiny{\url{http://www.mcs.anl.gov/research/projects/mpich2}} \\ 
 & (for the parallelization) & \\
 LAM/MPI & MPI Implementation & \url{http://www.lam-mpi.org} \\
 & (for the parallelization) & \\
@@ -37,7 +37,7 @@ After unpacking the software package (e.g. by  \textbf{tar -zxvf ifos3D.tgz}) an
 \textbf{bin}\\
 This directory contains all executable programs, like ifos3D and snapmerge. These executables are generated using the command  \textbf{make $<$program$>$} (see below).\vspace{0.2cm}\\
 \textbf{doc}\\
-This directory contains documentation on the software (this users guide) as well as some important papers in PDF format on which the software is based on.\vspace{0.2cm}\\ 
+This directory contains documentation on the software (this users guide). \vspace{0.2cm}\\ 
 \textbf{mfiles}\\
 Here some Matlab routines (m-files) are stored. They can be used vor processing and visualisation of data. \vspace{0.2cm}\\
 \textbf{par}\\
@@ -59,10 +59,10 @@ This directory contains the complete source codes. The different subprograms are
 \textbf{libcseife}\\
 The libcseife library serves for filtering seismograms
 \section{Compilation}
-Before compiling the main program ifos3D, the libcseife library for the filtering of seismograms needs to be installed. In order to do this change to the directory libcseife. Remove the *.d files and perform \textbf{make all}. If problems with the compilation arise open \textit{Makefile} and adjust the compiler options for your system.\\
-To compile the main program IFOS3D you can use the shell script \textit{compileIFOS3D.sh} in the \textit{par}-directory. This script executes make ifos3D in the \textit{src}-directory. To change the compiler options open the \textit{Makefile} in \textit{src}. Here you can also find examples for compiler options on different systems where IFOS3D or SOFI3D were used in the past.
+To compile ifos3D change to the \textit{par}-directory and perform \textbf{make}. The Makefile will first compile the external libseife library and then compile the main program. In some cases it's necessary to  remove the *.d files in the \textit{libseife}-directory. If problems with the compilation arise go to the \textit{libseife}-directory open \textit{Makefile} and adjust the compiler options for your system.\\
+To change the compiler options open the \textit{Makefile} in \textit{src}-directory. Here you can also find examples for compiler options on different systems where IFOS3D or SOFI3D were used in the past.
 \section{Running IFOS3D}
 To start the program with OpenMPI you can use the command\\
-\textbf{mpirun -np 8 nice -19 ../bin/ifos3D ./in\_and\_out/ifOS3D\_toy.inp $\mid$ tee ./in\_and\_out/ifos3D.out}\\
+\textbf{mpirun -np 8 nice -19 ../bin/ifos3D ./in\_and\_out/ifOS3D\_toy.json $\mid$ tee ./in\_and\_out/ifos3D.out}\\
 which runs IFOS3D on 8 processors with lowest priority. The standard output is written to \textit{/in\_and\_out/ifos3D.out}. You can also use the shell-script \textit{par/startIFOS3D.sh}.\\
 For 3D FWI applications it is often useful to use supercomputers in high performance computing centers. Some examples for job scripts can be found in the directory \textit{scripts}.

doc/latex/manual_implementation.tex

@@ -28,7 +28,8 @@ The elastic medium is described by the density $\rho$ and the Lam\'e parameters
 \subsection{Finite difference modeling}\label{sec:FDmodeling}
 For the simulations of 3D elastic wave propagation these equations are approximated by finite differences (FD). For the calculation of partial derivatives, the wavefield parameters and model parameters are discretised on a staggered-grid system \citep{Vir86, Lev88}. The 3D staggered-grid system is sketched in Figure~\ref{fig:stag_grid}. We use a Cartesian grid (x,y,z)=(i,j,k). The model parameters $\lambda$, $\mu$ and $\rho$ and the diagonal stress components $\sigma_{ii}$ are localised on the full grid points, whereas velocities and off-diagonal stress components are calculated on a grid which is half a grid point shifted to the original system. Compared to a conventional Cartesian grid, the staggered grid enables a larger grid spacing for the same level of accuracy.\\
 \begin{figure}
-\includegraphics[width=0.7\textwidth]{fig/staggered_grid}
+\centering
+\includegraphics[width=0.74\textwidth]{fig/ssg_grid}
 \caption[Staggered grid system]{Staggered-grid coordinate system used for 3D FD modelling in SOFI3D}\label{fig:stag_grid}
 \end{figure}
 The derivatives are approximated by centered finite differences. The easiest finite-differences are of second order, where the two adjacent grid points with a grid space $dh$ are used to calculate the derivative between these grid points as follows
@@ -46,7 +47,7 @@ Hereby the summation of the update values over all time steps accounts for the t
 \subsubsection*{Boundary conditions}
 There are two ways to avoid arteficial reflections from model boundaries in SOFI3D. The first exponentially damps waves within a boundary zone surrounding the model by multiplying the amplitudes with an exponentially decaying factor \citep{Cer85}. At least 30 gridpoints thickness at boundary zones is required. The second method is the implementation of convolutional perfectly matched layers (C-PMLs) \citep{Ber94,Kom07}. This method can offer a much better performance compared to the  conventional exponential damping and a boundary zone of 10 gridpoints thickness is generally sufficient. However, in case of strong contrasts and heterogeneities at the model boundary instabilities can be caused.
 \subsubsection*{The free surface}
-At the free surface, the vertical stress components $\sigma_{xz}$, $\sigma_{yz}$ and  $\sigma_{zz}$ are zero. A planar free surface is implemented implicitely in SOFI3D with the mirroring technique described by \cite{Lev88}.
+At the free surface, the vertical stress components $\sigma_{xy}$, $\sigma_{yy}$ and  $\sigma_{zy}$ are zero. A planar free surface is implemented implicitely in SOFI3D with the mirroring technique described by \cite{Lev88}.
 \subsubsection*{Grid dispersion and stability} 
 To mitigate numerical dispersion and grid anisotropy of the wavefield the grid spacing must be chosen sufficiently small. For a fourth-order spatial and second-order temporal scheme the criterion 
 \begin{equation}

doc/latex/manual_toy.tex

@@ -30,7 +30,7 @@ The model does not contain a free surface (\textbf{FREE\_SURF}=0) and as boundar
 \end{center}
 \end{figure}
 Sources and receivers are arranged within $x$-$y$-planes, as indicated in Figure~\ref{fig:toy_model}. The sources are listed in \textit{sources/sources\_toy.dat} (\textbf{SOURCE\_FILE}). We use 12 (3$\times$4) sources in 92\,m depth with a central frequency of \textbf{FC}=300\,Hz. The sources are vertical directed point forces (\textbf{QUELLTYP}=4) with sin$^3$-wavelets (\textbf{QUELLART=4}) as source time functions. The corresponding source wavelet can be seen in figure~\ref{fig:toy_wavelet}a. This source wavelet comprises the low frequencies with $40\%$ of the maximum amplitude left at about 400\,Hz (figure~\ref{fig:toy_wavelet}b). \\
-The receivers are arranged using a horizontal receiver array (\textbf{REC\_ARRAY}=1) in 24\,m depth. The distance between the receivers is \textbf{DRX}=\textbf{DRY}=10 gridpoints, which gives a total number of 169 receivers. 
+The receivers are arranged using a horizontal receiver array (\textbf{READREC}=2, \textbf{REC\_ARRAY}=1) in 24\,m depth. The distance between the receivers is \textbf{DRX}=\textbf{DRY}=10 gridpoints, which gives a total number of 169 receivers. 
 \subsection{Inversion parameters}
 For the inversion we use homogeneous starting models with $v_s=3600$\,m/s and $v_p=6200$\,m/s. In total 60 iterations are performed (\textbf{ITMIN, ITMAX }= 1, 60) and five frequencies are employed simultanously (\textbf{NFMAX}=5). For preconditioning of gradients a local taper is applied around source and receiver positions (\textbf{DAMPTYPE}=2). We do not use the diagonal Hessian approximation (\textbf{HESS}=0) or the L-BFGS method (\textbf{LBFGS}=0). Out of the total number of 12 shots we use 4 shots for the steplength estimation (\textbf{NSHOTS\_STEP}=4) and start with an initial test steplength of 0.02 (\textbf{TESTSTEP}=0.02). The filenames for gradient and model output are given in the input file.
 \subsubsection*{The workflow}
@@ -119,8 +119,8 @@ Model parameters are written into the folder \textit{model} in each iteration fo
 The results for the toy example is plotted for two 2D slices. Figure~\ref{fig:toy_result1} shows a horizontal slice through the box area. The three different box areas seen in the real model in a) and c) are well resolved for $v_p$ (b) and $v_s$ (d) after 60 iterations. However the $v_s$-model offers a clearly higher resolution due to the smaller wavelengths compared to the $v_p$-model. In transmission geometry a resolution down to one wavelength is possible and higher frequencies would be necessary to gain a better resolved box in $v_p$.
 \begin{figure}[h!]
 \begin{center}
-\includegraphics[width=\textwidth]{fig_toy/toy_model_result}
-\caption[Toy example - final inverted models, horizontal slice]{Final inverted models (60 iteartions) compared to real models for horizontal slice at $z$=60\,m: a) real model $v_p$, b) inverted  model $v_p$, c) real model $v_s$ and d) inverted model $v_s$;  }\label{fig:toy_result1}
+\includegraphics[width=\textwidth]{fig_toy/toy_model_result_new}
+\caption[Toy example - final inverted models, horizontal slice]{Final inverted models (60 iteartions) compared to real models for horizontal slice at $z$=60\,m: a) real model $v_p$, b) inverted  model $v_p$, c) real model $v_s$ and d) inverted model $v_s$. The dashed line indicates the absorbing frame;  }\label{fig:toy_result1}
 \end{center}
 \end{figure}
 A vertical slice of the models is plotted in figure~\ref{fig:toy_result2}. Overall, the vertical direction is more difficult to reconstruct, as can be ssen in the inverted models of $v_p$ (b) and $v_s$ (d) compared to the real models (a,b). The boundaries of the box are relatively well recovered for both parameters. The inversion of $v_p$ reconstructs the two main areas of the box, however the small high velocity area (dark red) cannot be resolved. This area is indicated in the inverted $v_s$ model, again showing the higher resolution of this parameter.

par/in_and_out/ifos3d_inv_all_parameters_commented.json

@@ -48,7 +48,7 @@
 			"RUN_MULTIPLE_SHOTS" : "1",
 			
 			"Following lines can be ignored if SRCREC!=2" : "comment",
-			"Plane wave (PW) excitation,if PLANE_WAVE_DEPTH>0, SRCREC is treated as 0" : "comment",
+			"Plane wave (PW) excitation" : "comment",
 			"depth_of_PW_excitation_(no<=0)_(in_meter)" : "comment",
 			"PLANE_WAVE_DEPTH" : "0.0",
 			"dip_of_PW_from_vertical_(in_degrees)" : "comment",