5_Getting_Started.tex 9.6 KB
Newer Older
Tilman Steinweg's avatar
Tilman Steinweg committed
1 2 3 4 5 6 7 8 9
%------------------------------------------------------------------------------------------------%

\chapter{\label{cha:Getting-Started}Getting Started}

%------------------------------------------------------------------------------------------------%

In the following sections, we give a short description of the different modeling  parameters, options and how the program is used in a parallel MPI environment.

\section{Requirements}
Florian Wittkamp's avatar
Florian Wittkamp committed
10
The parallelization employs functions of the Message Passing Interface (MPI). MPI has to be installed when compiling and running the IFOS software. At least two implementations exist for Unix-based networks: OpenMPI and MPICH2. The LAM-MPI implementation is no longer supported by the developers. Currently all three implementation work with IFOS. OpenMPI and MPICH2 are MPI programming environments and development systems for heterogeneous computers on a network. With OpenMPI or MPICH2, a dedicated cluster or an existing network computing  infrastructure can act as one parallel computer solving one problem. The latest version of OpenMPI can be obtained from \href{http://www.open-mpi.org}{http://www.open-mpi.org}.% MPICH2 is available at \href{http://www.open-mpi.org}{http://www-unix.mcs.anl.gov/mpi/mpich}. LAM-MPI can be downloaded here: \href{http://www.lam-mpi.org}{http://www.lam-mpi.org}.
Tilman Steinweg's avatar
Tilman Steinweg committed
11 12 13 14


\section{Installation}
\label{installation}
Florian Wittkamp's avatar
Florian Wittkamp committed
15
After unpacking the software package (e.g. by \textit{tar -zxvf IFOS.tgz}) and changing to the directory IFOS (\textit{cd IFOS})  you will find different subdirectories:
Tilman Steinweg's avatar
Tilman Steinweg committed
16 17

\textbf{bin}\\
Florian Wittkamp's avatar
Florian Wittkamp committed
18
This directory contains all executable programs, generally IFOS and snapmerge. These executables are generated using the command \textit{make $<$program$>$} (see below).
Tilman Steinweg's avatar
Tilman Steinweg committed
19 20

\textbf{contrib}\\
Florian Wittkamp's avatar
Florian Wittkamp committed
21
This directory contains external contributions to IFOS.
Tilman Steinweg's avatar
Tilman Steinweg committed
22 23 24 25 26

\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 (see above).

\textbf{genmod}\\
Florian Wittkamp's avatar
Florian Wittkamp committed
27
Contains the model and benchmark files for IFOS.
Tilman Steinweg's avatar
Tilman Steinweg committed
28 29

\textbf{mfiles}\\
30
Here some Matlab routines (m-files) are stored. These Matlab programs can be used to find optimal relaxation frequencies to approximate a constant Q (qapprox.m) or to plot Q as a function of frequency for certain relaxation frequencies and value of tau (qplot.m). It is necessary to have the Matlab Optimization Toolbox installed. For further details we refer to \cite{bohlen:98} and to the paper in which the so-called tau-method is described \cite{blanch:95}.
Tilman Steinweg's avatar
Tilman Steinweg committed
31 32

\textbf{par}\\
Florian Wittkamp's avatar
Florian Wittkamp committed
33
Parameter files for IFOS modeling.
Tilman Steinweg's avatar
Tilman Steinweg committed
34

35 36
% \textbf{scripts}\\
% Here, you will find examples of script-files used to submit modeling jobs on cluster-computers.
Tilman Steinweg's avatar
Tilman Steinweg committed
37 38 39 40 41

\textbf{src}\\
This directory contains the complete source codes.  The following programs are available and may be compiled using make $<$program$>$.


Florian Wittkamp's avatar
Florian Wittkamp committed
42 43
\section{Compilation of IFOS}\label{compexec}
Before compiling the main program IFOS you have to compile the required additional libraries e.g. for timedomain filtering, the inversion for the correction filter for the unknown source time function and so on. In the IFOS/par directory simply use:
Tilman Steinweg's avatar
Tilman Steinweg committed
44 45 46 47 48
\newline

\textit{make}
\newline

49
which will install the following libraries:
Tilman Steinweg's avatar
Tilman Steinweg committed
50 51 52 53 54 55 56

{\color{blue}{\begin{verbatim}
lib cseife
lib stfinv
lib aff
lib fourier
\end{verbatim}}}
Florian Wittkamp's avatar
Florian Wittkamp committed
57
as well as the binary of IFOS itself.
Tilman Steinweg's avatar
Tilman Steinweg committed
58 59 60
In contrib/Makefile\_var there were several environment variables which are necessary to compile the libraries successfully. Furthermore, it is necessary to preinstall FFTW - Fastest Fourier Transform in the West (\href{http://www.fftw.org/}{http://www.fftw.org/}). Please check the successful installation in the folder contrib/header.
\newline
  
Florian Wittkamp's avatar
Florian Wittkamp committed
61
The source code of IFOS is located in the directory IFOS/src. To compile IFOS the name of the model function has to be entered in the src/MAKEFILE. Depending on your MPI environment (MPI distribution) you may need to modify the compiler options in src/Makefile. For a few typical platforms the compiler options are available in src/Makefile. It is often useful to enable a moderate level of optimization (typically -O3). The highest level of optimization -O4 can lead to a strong performance improvement. For example the optimization option -O4 of the hcc LAM compiler leads to a speedup of IFOS of approximately 30~\%. Eventhough keep in mind that -O4 can also lead to crashes and compilation errors, when used in combination with certain compilers. No other changes in the Makefile should be necessary. 
Tilman Steinweg's avatar
Tilman Steinweg committed
62
{\color{blue}{\begin{verbatim}
Florian Wittkamp's avatar
Florian Wittkamp committed
63
# Makefile for IFOS
Tilman Steinweg's avatar
Tilman Steinweg committed
64 65 66 67 68 69

#--------------------------------------------------------
# edit here:

# source code for model generation

70 71 72 73 74
#MODEL = hh.c
MODEL = ../genmod/1D_linear_gradient_visc.c
MODEL_AC = ../genmod/1D_linear_gradient_ac.c
MODEL_EL = ../genmod/1D_linear_gradient_el.c
MODEL_VAC = ../genmod/1D_linear_gradient_viscac.c
Tilman Steinweg's avatar
Tilman Steinweg committed
75 76
EXEC= ../bin

77 78 79 80
# Description:
# CC = Compiler
# LFLAGS = Linker flag
# CFLAGS = Compiler flag
Tilman Steinweg's avatar
Tilman Steinweg committed
81

82 83 84 85
# LINUX with OpenMPI / IntelMPI and INTEL Compiler
# Use icc whenever possible, this will be much faster than gcc
CC=mpiicc
LFLAGS=-lm -lcseife -lstfinv -laff -lfourierxx -lfftw3 -lstdc++
Tilman Steinweg's avatar
Tilman Steinweg committed
86
CFLAGS=-O3
87 88
SFLAGS=-L./../contrib/libcseife -L./../contrib/bin
IFLAGS=-I./../contrib/libcseife -I./../contrib/header -I.
Tilman Steinweg's avatar
Tilman Steinweg committed
89

90 91 92 93 94 95
# LINUX with OpenMPI / IntelMPI and GCC Compiler
#CC=mpicc
#LFLAGS=-lm -lcseife -lstfinv -laff -lfourierxx -lfftw3 -lstdc++
#CFLAGS=-O3
#SFLAGS=-L./../contrib/libcseife -L./../contrib/bin
#IFLAGS=-I./../contrib/libcseife -I./../contrib/header -I.
Tilman Steinweg's avatar
Tilman Steinweg committed
96 97 98 99 100 101


# after this line, no further editing should be necessary
# --------------------------------------------------------
\end{verbatim}}} 

Florian Wittkamp's avatar
Florian Wittkamp committed
102
The program snapmerge that is used to merge the snapshots (see below) can be compiled with ''make snapmerge'' in the directory /src. Since this is not a MPI program (no MPI functions are called) the MPI libraries are not required and any standard compiler (like gcc and cc) can be used to compile this program. The executables IFOS and snapmerge are located in the directory /bin. 
Tilman Steinweg's avatar
Tilman Steinweg committed
103 104

\section{Running the program}\label{compexec1} 
Florian Wittkamp's avatar
Florian Wittkamp committed
105 106
Each IFOS run reads the required parameters from a parameter file par/IFOS.json. A detailed description of the parameters are described in chapter \ref{Definition-parameters_json}. 
The command to start a simulation on 8 processor with the lowest priority of -19 (in order to allow working on the a workstation while running a simulation) is as follows. Please note, that we assume you have navigated to the folder IFOS/par.
Tilman Steinweg's avatar
Tilman Steinweg committed
107 108
\newline

Florian Wittkamp's avatar
Florian Wittkamp committed
109
\textit{mpirun -np 8 nice -19 ../bin/IFOS IFOS.json }
Tilman Steinweg's avatar
Tilman Steinweg committed
110 111
\newline

Florian Wittkamp's avatar
Florian Wittkamp committed
112
It is often useful to save the standard output of the program for later reference. The screen output may be saved to IFOS.out using
Tilman Steinweg's avatar
Tilman Steinweg committed
113 114
\newline

Florian Wittkamp's avatar
Florian Wittkamp committed
115
\textit{mpirun -np 8 nice -19 ../bin/IFOS IFOS.json > IFOS.out}
Tilman Steinweg's avatar
Tilman Steinweg committed
116 117
\newline

118
% \newpage
Tilman Steinweg's avatar
Tilman Steinweg committed
119

120
After the output of geometry and model parameters the code starts the time stepping and displaying information:
Tilman Steinweg's avatar
Tilman Steinweg committed
121 122

{\color{blue}{\begin{verbatim} 
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
==============================================================================

 MYID=0 * Starting simulation (forward model) for shot 1 of 5. Iteration 1 ** 

==============================================================================

 ****************************************
 ****************************************

==============================================================================

 MYID=0 * Starting simulation (forward model) for shot 2 of 5. Iteration 1 ** 

==============================================================================

 ****************************************
 ****************************************

==============================================================================

 MYID=0 * Starting simulation (forward model) for shot 3 of 5. Iteration 1 ** 

==============================================================================

 ****************************************
 ****************************************

==============================================================================

 MYID=0 * Starting simulation (forward model) for shot 4 of 5. Iteration 1 ** 

==============================================================================

 ****************************************
 ****************************************

==============================================================================

 MYID=0 * Starting simulation (forward model) for shot 5 of 5. Iteration 1 ** 

==============================================================================

 ****************************************
 ****************************************

 Forward calculation finished.
Tilman Steinweg's avatar
Tilman Steinweg committed
169 170 171
\end{verbatim}}}  

\section{Postprocessing}  
Florian Wittkamp's avatar
Florian Wittkamp committed
172
The wavefield snapshots can be merged using the program \textit{snapmerge}. The program snapmerge is not a MPI program. Therefore, it can be executed without MPI and the mpirun command. You can run snapmerge on any PC since a MPI environment is not required. You may therefore copy the snapshot outputs of the different nodes to another non-MPI computer to merge the files together. \textit{snapmerge} reads the required information from the IFOS parameter file. Simply type
Tilman Steinweg's avatar
Tilman Steinweg committed
173 174
\newline

Florian Wittkamp's avatar
Florian Wittkamp committed
175
\textit{../bin/snapmerge IFOS.json  }
Tilman Steinweg's avatar
Tilman Steinweg committed
176 177 178
\newline

% {\color{blue}{\begin{verbatim}
Florian Wittkamp's avatar
Florian Wittkamp committed
179
% -bash-2.05b$~/IFOS/par> ../bin/snapmerge IFOS.json  
Tilman Steinweg's avatar
Tilman Steinweg committed
180 181 182 183 184 185 186 187 188 189 190 191 192
% \end{verbatim}}}

Depending on the model size the merge process may take a few seconds or hours. For the simple block model it only takes a few seconds. The output should read like this:
{\color{blue}{\begin{verbatim}
 pressure (files: ./snap/test.bin.p.??? ).

 writing merged snapshot file to  ./snap/test.bin.p
 Opening snapshot files: ./snap/test.bin.p.???  ... finished.
 Copying... ... finished.
 Use
 xmovie n1=100 n2=100 < ./snap/test.bin.p loop=1 label1=Y label2=X title=%g
 to play movie.
\end{verbatim}}} 
Florian Wittkamp's avatar
Florian Wittkamp committed
193
IFOS