Commit f42c903a authored by Simone Butzer's avatar Simone Butzer

Add documentation into doc-folder (2)

parent 5de7fbda
[Dolphin]
Timestamp=2016,3,2,12,0,51
Version=3
ViewMode=1
[Dolphin]
SortOrder=1
Timestamp=2016,4,12,15,34,1
Version=3
ViewMode=1
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
\documentclass[12pt,twoside,a4paper]{report}
%\usepackage{ngerman}
\usepackage[ngerman,english]{babel}
%\usepackage[latin1]{inputenc}
\usepackage[reqno]{amsmath}
\usepackage{natbib}
\usepackage{anysize}
%\usepackage{sidecap}
%\marginsize{3.0}{1.0}{1.0}{1.0}
\usepackage{pslatex}
\usepackage{graphicx}
\usepackage{color}
\definecolor{Gray}{gray}{0.5}
\usepackage[margin=10pt,font=small,labelfont=bf]{caption}
\usepackage[position=top,singlelinecheck=false]{subfig}
\usepackage{multirow}
\usepackage{lscape}
\usepackage[verbose]{placeins}
%\usepackage{longtable}
\setlength{\parindent}{0mm}
\numberwithin{equation}{chapter}
\numberwithin{figure}{chapter}
\numberwithin{table}{chapter}
\usepackage{amssymb}
% Kopf- und Fusszeilen definieren
\usepackage{fancyhdr}
\pagestyle{fancy}
\renewcommand{\headrulewidth}{0.4pt}
\fancyhead[RO,LE]{\thepage}
\fancyhead[RE]{\slshape \rightmark}
\fancyhead[LO]{\slshape \leftmark}
\fancyfoot[C]{}
% Aendern der Schriftart
\usepackage{mathptmx}
\usepackage[scaled=0.92]{helvet}
%\renewcommand{\familydefault}{\sfdefault}
% Changing font for mathcal
\DeclareMathAlphabet{\mathcal}{OMS}{cmsy}{m}{n}
% adding hyperref package
% - adding backlinks in bibliography by option pagebackref
\usepackage[colorlinks, linkcolor = black, citecolor = black, filecolor = black, urlcolor = blue]{hyperref}
\usepackage{eso-pic}
\usepackage{color}
\usepackage{bibentry}
\nobibliography*
% define depth of table of content
\setcounter{tocdepth}{2}
%----------------------------------------------------------------------
% my definitions
\DeclareMathOperator\Sdd{\mathrm{d}}
\begin{document}
%-------------------- Titelseite --------------------%
\input{manual_title.tex}
\FloatBarrier
\newpage
\thispagestyle{empty}
\quad
\newpage
\pagestyle{fancy}
%-------------------- Titelseite (Ende) --------------------%
%\input{Abstract.tex}
%\cleardoublepage
\pagenumbering{Roman}
\section*{Authors}
The IFOS3D code was first developed by Simone Butzer at the Karlsruhe Institute of Technology (KIT) from 2009-2014. Contributions were given by Andre Kurzmann and Lisa Groos.\\
\newline
The forward code is based on the viscoelastic FD code SOFI3D by \cite{boh02}.\\
\newline
Different external libraries for time domain filtering are used. The copyright of the source codes are held by different persons:\\
\newline
cseife.c, cseife.h:\\
Copyright $\copyright$ 2005 by Thomas Forbriger (BFO Schiltach) \\
\newline
cseife\_deriv.c, cseife\_gauss.c, cseife\_rekfl.c, cseife\_rfk.c and cseife\_tides.c:\\
Copyright $\copyright$ 1984 by Erhard Wielandt\\
This algorithm was part of seife.f. A current version of seife.f can be obtained from http://www.software-for-seismometry.de/\\
\newline
The Matlab implementation of a few SU routines, mainly used to read and write SU files are:\\
Copyright $\copyright$ 2008, Signal Analysis and Imaging Group\\
For more information: http://www-geo.phys.ualberta.ca/saig/SeismicLab\\
Author: M.D.Sacchi\\
\newline
%\noindent
%Since then it has been developed and maintained by a development team: in alphabetical order,\\
%\newline
%(since 2015)\\
%...
% (add other developers here in the future).
\newpage
\section*{License}\label{license}
IFOS3D is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.0 of the License only.\\
\newline
IFOS3D is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with IFOS3D. See file COPYING and/or \path{http://www.gnu.org/licenses/gpl-2.0.html}.\\
\newline
The Authors of IFOS3D are listed in file \path{AUTHORS}.
%------------------------------------------------------------------------------------------------%
\section*{Acknowledgments}
%------------------------------------------------------------------------------------------------%
We thank the seismic working group of the Geophysical Institute at KIT for constructive discussions.
\noindent The development of the code was supported by the Karlsruhe Institute of Technology (KIT), the Deutsche Forschungsgemeinschaft (DFG), the Bundesministerium f\"ur Bildung und Forschung (BMBF) and the Wave Inversion Technology (WIT) Consortium.
\noindent The code was tested and optimized at the computing centres of the Karlsruhe Institute of Technology (KIT), the supercomputing center in Juelich and the HLRS in Stuttgart.
\newline
%------------------------------------------------------------------------------------------------%
\section*{References}
%------------------------------------------------------------------------------------------------%
\noindent\bibentry{But13}\\
\noindent\bibentry{But15}\\
\tableofcontents
\cleardoublepage
\pagenumbering{arabic}
%Implementation FWI
\input{manual_summary.tex}
\clearpage
\input{manual_implementation.tex}
\clearpage
\input{manual_howto.tex}
\clearpage
\input{manual_input.tex}
\clearpage
\input{manual_toy.tex}
\clearpage
\phantomsection
\addcontentsline{toc}{chapter}{Bibliography}
\bibliographystyle{gji}
\bibliography{manual_IFOS3D}
\begin{appendix}
\input{manual_code_overview.tex}
\end{appendix}
%\cleardoublepage
%\input{Danksagung.tex}
\end{document}
\chapter{Source code short description}\label{sec:code_overview}
In the following we will give a short overview about the different programs of the IFOS3D source code.\\
\\
\textbf{ifos3d} - main program.\\
\\
\textbf{Makefile} - makefile for IFOS3D.\\
\\
\textbf{fd.h} - include file for IFOS3D. \\
\\
\textbf{globvar.h} - defines global variables for IFOS3D.\\
\subsection*{Subprograms}
\textbf{absorb.c} - calculation of absorbing boundary coefficients using exponential damping \citep{Cer85}.\\
\\
\textbf{av\_mat.c} - averaging material parameters for the staggered-grid\\
\\
\textbf{checkfd\_ssg.c} - check for stability, grid dispersion and the accessibility of data output directories and files. \\
\\
\textbf{comm\_ini.c} - initialisation of repeated comunications. This may reduce the network overhead.\\
\\
\textbf{conjugategrad.c} - calculation of the conjugate gradient direction (MORA, 1987).\\
\\
\textbf{CPML\_coeff.c} - defining damping profiles for CPML boundary condition. This C-PML implementation is adapted from the 2nd order isotropic CPML code
by Dimitri Komatitsch and based in part on formulas given in Roden and Gedney (2000). \\
\\
\textbf{CPML\_ini\_elastic.c} - definition of CPML boundary domains for each submodel.\\
\\
\textbf{cpmodel.c} - copying of model parameters into a testmodel.\\
\\
\textbf{disc\_fourier.c} - calculation of a discrete Fourier transfomation on the fly: Fouriercomponents of forward or backpropagated wavefields are summed up for each frequency.\\
\\
\textbf{exchange\_Fv.c} - exchange of wavefield velocities (frequency donain) at grid boundaries between processors.\\
\\
\textbf{exchange\_par.c} - exchange of input parameters between processors.\\
\\
\textbf{exchange\_s.c} - exchange of stress values at grid boundaries between processors.\\
\\
\textbf{filt\_seis.c} - filtering of seismograms in time domain with a Butterworth filter of the libseife library. Lowpass or highpass filtering can be applied. \\
\\
\textbf{gradient\_F.c} - gradient calculation in frequency domain: gradient as multiplication of forward and conjugate backpropagated wavefield spatial derivatives are calculated by 4th order finite differences.\\
\\
\textbf{hess\_apply.c} - preconditioning of gradient with diagonal Hessian approximation.\\
\\
\textbf{hess\_F.c} - calculation of diagonal Hessian approximation in frequency domain.\\
\\
\textbf{hh.c} - generation of an elastic or viscoelastic model specified by $v_p$, $v_s$ and $\rho$.\\
\\
\textbf{info.c} - printing information about IFOS3D.\\
\\
\textbf{initproc.c} - dividing the 3-D FD grid into domains and assigning the processors to these domains,\\
\\
\textbf{lbfgs.c} - calculation of L-BFGS update.\\
\\
\textbf{lbfgs\_save.c} - saving gradient for L-BFGS calculation; only first iteration, later saved in lbfgs.c.\\
\\
\textbf{matcopy.c} - exchange of model parameters to neighbouring processors for the averaging of material properties.\\
\\
\textbf{merge.c} - merge snapshots files written by the different processes to a single file. \\
\\
\textbf{mergemod.c} - merge model files written by the different processes to a single file. Used for gradients and model output in IFOS3D. \\
\\
\textbf{model2\_5D.c} - creation of a 2.5D model from a 3D model, (attention: not in parallel!!); 2.5D model parameters constant in z-direction.\\
\\
\textbf{modelupdate.c} - update of model for next iteration.\\
\\
\textbf{note.c} - writing note to stdout.\\
\\
\textbf{outgrad.c} - output of gradients to GRAD\_FILE.\\
\\
\textbf{outmod.c} - output of model parameters $v_p$, $v_s$ and $\rho$ to MOD\_OUT\_FILE.\\
\\
\textbf{output\_source\_signal.c} - output source signal e.g. for cross-correlation, deconvolution or comparison with analytical solutions. \\
\\
\textbf{outseis.c} - writing seismograms to disk. \\
\\
\textbf{precongrad.c} - gradient preconditioning around sources, receivers and at model boundaries.\\
\\
\textbf{psource.c} - generation of explosive source at source nodes.\\
\\
\textbf{rd\_sour.c} - reading external source wavelet.\\
\\
\textbf{read\_checkpoint.c} - reading wavefield from checkpoint file.\\
\\
\textbf{readdsk.c} - reading one single amplitude from file.\\
\\
\textbf{readhess.c} - reading Hessian from files.\\
\\
\textbf{readinv.c} - reading inversion parameters from workflow.\\
\\
\textbf{readmod.c} - reading elastic model properties ($v_p$, $v_s$, density) from file.\\
\\
\textbf{read\_par.c} - reading FD-Parameters from input-file. \\
\\
\textbf{readseis.c} - reading seismograms from files.\\
\\
\textbf{receiver.c} - finding global grid positions for the receivers.\\
\\
\textbf{residual.c} - calculation of data residuals (displacement) and L2 norm.\\
\\
\textbf{rwsegy.c} - reading and writing SEG-Y, SU, BIN, TXT and UKOOA P190.\\
\\
\textbf{save\_checkpoint.c} - saving wavefield to checkpoint file.\\
\\
\textbf{saveseis.c} - writing seismograms to files.\\
\\
\textbf{segy.h} - include file for SEGY traces.\\
\\
\textbf{seismerge.c} - merging SEG-Y files.\\
\\
\textbf{seismo\_ssg.c} - storing amplitudes (particle velocities or pressure) at receiver positions in arrays.\\
\\
\textbf{smooth.c} - smoothing model parameters (complete model or boundaries only), not in parallel.\\
\\
\textbf{snapmerge.c} - loop over snapshotfiles which have to be merged.\\
\\
\textbf{snap\_ssg.c} - writing 3D snapshot for current timestep to disk.\\
\\
\textbf{sources.c} - reading source parameters from source file.\\
\\
\textbf{splitrec.c} - computation of local receiver coordinates (within each subgrid). \\
\\
\textbf{splitsrc.c} - computation of local source coordinates (within each subgrid).\\
\\
\textbf{steplength.c} - steplength calculation using a parabola method.\\
\\
\textbf{surface\_ssg.c} - stress free surface condition using the mirroring technique.\\
\\
\textbf{surface\_ssg\_elastic.c} - stress free surface condition, elastic case.\\
\\
\textbf{timing.c} - output timing information (real time for updates etc.).\\
\\
\textbf{update\_s\_ssg.c} - updating stress values by a staggered grid finite difference scheme of nth order accuracy in space and second order accuracy in time (viscoelastic version).\\
\\
\textbf{update\_s\_ssg\_CPML.c} - updating stress values in the CPML-boundaries (4th order spatial FD sheme) (viscoelastic version).\\
\\
\textbf{update\_s\_ssg\_CPML\_elastic.c} - updating stress values in the CPML-boundaries (4th order spatial FD sheme) (elastic version).\\
\\
\textbf{update\_s\_ssg\_elastic.c} - updating stress values by a staggered grid finite difference scheme of nth order accuracy in space and second order accuracy in time (elastic version).\\
\\
\textbf{update\_v\_ssg.c} - updating velocity values by a staggered grid finite difference scheme of nth order accuracy in space and second order accuracy in time.\\
\\
\textbf{update\_v\_ssg\_CPML.c} - updating velocity values in the CPML-boundaries (4th order spatial FD sheme).\\
\\
\textbf{util.c} - some utility-routines from numerical recipes \citep{pre90}.\\
\\
\textbf{wavelet.c} - Calculating source signal at different source positions for input source parameters.\\
\\
\textbf{writedsk.c} - writing one single amplitude on disk.\\
\\
\textbf{writemod.c} - writing local model to file (not in use, see outmod).\\
\\
\textbf{writepar.c} - writing FD-Parameter to output file stdout or log-file.\\
\\
\textbf{zero\_grad.c} - initialise gradient with zero.\\
\\
\textbf{zero\_invers.c} - initialise wavefield (frequency domain) with zero.\\
\\
\textbf{zero\_wavefield.c} - initialise wavefield with zero.\\
\ No newline at end of file
\chapter{Getting started}
\label{Gettingstarted}
\section{Requirements}
\label{requirements}
IFOS3D was tested on different Linux platforms. To run IFOS3D an MPI implementation (one of the three listed below) and a C-Compiler is required.
The code was tested on our local workstation cluster using Suse Linux and OpenMPI. Additionally applications were performed on the JUROPA and JURECA supercomputers in Juelich (Germany) and the Hermit supercomputer at HLRS in Stuttgart (Germany). The following programs should be installed on you machine for a proper run and processing of data. These requirements are similar to the forward solver SOFI3D.
\begin{center}
% use packages: array
\begin{small}
\begin{tabular}{lll}
Program & Description & Weblink \\
OpenMPI & MPI Implementation & \tiny{\url{http://www.mcs.anl.gov/research/projects/mpich2}} \\
& (for the parallelization) & \\
MPICH2 & MPI Implementation & \url{http://www.open-mpi.org} \\
& (for the parallelization) & \\
LAM/MPI & MPI Implementation & \url{http://www.lam-mpi.org} \\
& (for the parallelization) & \\
C-Compiler & the whole code is written in C,& \\
& any C-Compiler should be able & \\
& to compile it & \\
Seismic Un*x & Seismic processing package, & \url{http://www.cwp.mines.edu/cwpcodes} \\
(SU) & SOFI3D outputs seismic data & \\
& in the SU format & \\
Matlab & Preferred program package for & \url{http://www.mathworks.de} \\
(commercial)& the visualization of snapshots, also & \\
& useful for the display and & \\
& processing of seismograms & \\
xmovie & Console based movie program, can & usually included in Linux distribution\\
& be used for the quick display & otherwise install from repository\\
& of snapshot data &
\end{tabular}
\end{small}
\end{center}
\section{Installation - The folder structure}
After unpacking the software package (e.g. by \textbf{tar -zxvf ifos3D.tgz}) and changing to the directory ifos3D ( \textbf{cd ifos3D}) you will find different subdirectories:\vspace{0.2cm}\\
\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}\\
\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}\\
This directory contains the following folders:
\begin{itemize}
\item \textbf{in\_and\_out}: contains in- and outputfiles of IFOS3D parameters
\item \textbf{sources}: source parameters
\item \textbf{receiver}: receiver locations
\item \textbf{su}: seismogram outputfiles
\item \textbf{su\_obs}: observed seismograms
\item \textbf{model}: model in- and output
\item \textbf{grad}: gradient output
\item \textbf{hess}: diagonal hessian in- and output
\end{itemize}\vspace{0.2cm}
\textbf{scripts}\\
Here, you will find examples of script-files used to submit modeling jobs on cluster-computers.\vspace{0.2cm}\\
\textbf{src}\\
This directory contains the complete source codes. The different subprograms are listed in appendix~\ref{sec:code_overview}.\vspace{0.2cm}\\
\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.
\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}\\
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}.
This diff is collapsed.
This diff is collapsed.
\chapter{Introduction}
In the 1980's \cite{Lai83}, \cite{Tar84} and \cite{Mor87} suggested a new inversion strategy known as full waveform inversion (FWI). This method aims to reconstruct multi-parameter images of the subsurface by iteratively minimising the misfit between modeled and observed data. Thus it takes the full information content of the seismograms into account and can offer a significantly improved resolution compared to conventional methods. The optimisation problem is generally solved with gradient-based methods, which can be implemented very efficiently for FWI using the adjoint approach \citep[e.g.][]{Tar84, Mor87}. \\
Different approximations are generally used to limit the large number of unknown subsurface parameters and to mitigate the computational costs of the inversion. Many applications are performed in the 2D approximation. This leads to an enormous decrease of the number of subsurface parameters. Still, the 2D approximation is unable to explain 3D scattering and can lead to artefacts in 3D heterogeneous medium. Furthermore the use of a 3D FWI offers the possibility to invert for 3D structures and to gain a 3D image of the subsurface. Often, wave propagation in FWI applications is described with the (visco-) acoustic wave equation. Herby only compressional waves are considered which can be sufficient in marine seismics. However, in land seismics the abundance of shear waves and surface waves favours the (visco-) elastic wave equation. Still, studies on the implementation and application of 3D elastic FWI as performed by \cite{Epa08}, \cite{Fic09}, \cite{Cas11}, \cite{Gua12} and \cite{But13} are rare and computationally expensive.\\
\\
IFOS3D is a 3D elastic full waveform inversion tool which aims to resolve the elastic parameters (compressional and shear wave velocity and density) of the 3D subsurface. It is based on the conjugate gradient method. For a good computational performance the gradient is calculated with a time-frequency approach. Hereby the wavefields are simulated with the fast and efficient finite-difference forward solver SOFI3D in time domain \citep{boh02}. The gradient calculation is then performed in frequency domain for discrete frequencies. A discrete Fourier transform on the fly enables the transformation from time to frequency domain. For an optimisation of the gradient method IFOS3D offers the calculation of a diagonal Hessian approximation and application of the L-BFGS method.\\
The IFOS3D program is an extension of the SOFI3D forward modeling code for inversion and is thus closely linked to this program. SOFI3D is based on the FD approach described by \cite{Vir86} and \cite{Lev88}. The present program SOFI3D (elastic version) has the following extensions
\begin{itemize}
\item employs higher order FD operators,
\item applies Perfectly Matched Layer boundary conditions at the edges of the numerical mesh \citep{Kom07},
\item works in MPI parallel environment ONLY, i.e. SOFI3D is a implementation based on a domain decomposition
\citep{boh02}.
\end{itemize}
The manual of SOFI3D gives a detailed description of the forward modelling solver, its features and the corresponding input parameters.\\
\\
IFOS3D was successfully tested in different synthetic applications including transmission and surface acquisition geometries \citep{But13,But15}. A detailed description of the theory and implementation of the program is given by \cite{But15}. This manual will give an overview about the structure and implementation of IFOS3D which is necessary to run the program. The different input parameters are decribed in detail. Additionally IFOS3D comes with a toy example which is described in this guide. It can be performed in a few steps and therefore offers a good access to IFOS3D.
\ No newline at end of file
\thispagestyle{empty}
\sffamily
\AddToShipoutPictureBG*{\includegraphics[width=\paperwidth,height=\paperheight]{fig/title_page1_sofi_ifos.pdf}}
\noindent\includegraphics[width=1.0\textwidth]{fig/IFOS3D_title1.pdf}
\vspace{0.3 \textwidth}
%\begin{center}
%\includegraphics[width=.7\textwidth]{fig/logo_SOFI_IFOS.eps}
%\vspace{0.2\textwidth}
%\end{center}
\rmfamily
\ No newline at end of file
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment