5_Getting_Started.tex 9.54 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}
10
The parallelization employs functions of the Message Passing Interface (MPI). MPI has to be installed when compiling and running the IFOS2D 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 IFOS2D. 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}
15
After unpacking the software package (e.g. by \textit{tar -zxvf IFOS2D.tgz}) and changing to the directory IFOS2D (\textit{cd IFOS2D})  you will find different subdirectories:
Tilman Steinweg's avatar
Tilman Steinweg committed
16 17

\textbf{bin}\\
18
This directory contains all executable programs, generally IFOS2D 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}\\
21
This directory contains external contributions to IFOS2D.
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}\\
27
Contains the model and benchmark files for IFOS2D.
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}\\
33
Parameter files for IFOS2D 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$>$.


42 43
\section{Compilation of IFOS2D}\label{compexec}
Before compiling the main program IFOS2D 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 IFOS2D/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}}}
57
as well as the binary of IFOS2D 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
  
61
The source code of IFOS2D is located in the directory IFOS2D/src. To compile IFOS2D 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 IFOS2D 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}
63
# Makefile for IFOS2D
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}}} 

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 IFOS2D and snapmerge are located in the directory /bin. 
Tilman Steinweg's avatar
Tilman Steinweg committed
103 104

\section{Running the program}\label{compexec1} 
105 106
Each IFOS2D run reads the required parameters from a parameter file par/IFOS2D.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 IFOS2D/par.
Tilman Steinweg's avatar
Tilman Steinweg committed
107 108
\newline

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

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

115
\textit{mpirun -np 8 nice -19 ../bin/IFOS2D IFOS2D.json > IFOS2D.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}  
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 IFOS2D parameter file. Simply type
Tilman Steinweg's avatar
Tilman Steinweg committed
173 174
\newline

175
\textit{../bin/snapmerge IFOS2D.json}
Tilman Steinweg's avatar
Tilman Steinweg committed
176 177 178 179 180 181 182 183 184 185 186 187
\newline

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.
188
\end{verbatim}}}