paper.tex

国外免费地震资料处理软件包

software language of ``Madagascar'' is C. Interfaces to other
languages (C++, Fortran-77, Fortran-90, Python) are also provided.
\item \textbf{processing flows}: ``Madagascar'' is also an environment
  for reproducible numerical experiments in a very broad sense. These
  numerical experiments (or ``computational recipes'') can be done not
  only using ``Madagascar'' command line programs but also Matlab,
  Mathematica, Python, or other seismic packages (e.g. SEP, Seismic
  Unix). We adopted SCons for this part as we shall demonstrate later.
\item \textbf{documentation}: the most upper layer of ``Madagascar''
  and maybe the most critical for reproducible research is
  documentation. ``Madagascar'' establishes a direct link between the
  figures of a paper or a report and the codes that were used to
  generate them. This layer uses SCons in combination with \LaTeX\ to
  generate PDF, HTML, and MediaWiki files real easy and undoubtly
  makes ``Madagascar'' an environment of choice for technology
  transfer, report, thesis, and peer-reviewed publication writing.
\end{itemize}

\section{Example experiments}

%
The main \texttt{SConstruct} commands defined in our reproducible
research environment are collected in Table~\ref{tbl:commands}.

\tabl{commands}{Basic methods of an \texttt{rsfproj} object.}{
\begin{center}
\begin{tabular}{|p{0.9\textwidth}|} \hline
\noindent\texttt{Fetch(data\_file,dir[,ftp\_server\_info])}\\ \ \\
\indent A rule to download \texttt{$<$data\_file$>$} from a specific
directory \texttt{$<$dir$>$} of an FTP server
\texttt{$<$ftp\_server\_info$>$}. \\
\hline 
\noindent\texttt{Flow(target[s],source[s],command[s][,stdin][,stdout])}\\ \ \\
\indent A rule to generate \texttt{$<$target[s]$>$} from
\texttt{$<$source[s]$>$} using \texttt{command[s]} \\
\hline 
\noindent\texttt{Plot(intermediate\_plot[,source],plot\_command)} or\\
\texttt{Plot(intermediate\_plot,intermediate\_plots,combination})\\ \ \\
\indent A rule to generate \texttt{$<$intermediate\_plot$>$} 
in the working directory. \\
\hline 
\noindent\texttt{Result(plot[,source],plot\_command)} or\\ 
\texttt{Result(plot,intermediate\_plots,combination})\\ \ \\
\indent A rule to generate a final \texttt{$<$plot$>$} in
the special \texttt{Fig} folder of the working directory. \\
\hline 
\noindent\texttt{End()} \\ \ \\
\indent A rule to collect default targets. \\
\hline 
\end{tabular}
\end{center}}

These commands are defined in \texttt{\$RSFROOT/lib/rsfproj.py} where
\texttt{RSFROOT} is the environmental variable to the Madagascar
installation directory. The source of this file is in
\href{http://svn.sourceforge.net/viewvc/rsf/trunk/python/rsfproj.py?view=markup}{python/rsfproj.py}.

\subsection{Example 1}

To follow the first example, select a working project directory and
copy the following code
to a file named \texttt{SConstruct}\footnote{The source of this file is also accessible at \href{http://svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/scons/easystart/SConstruct?view=markup}{book/rsf/scons/easystart/SConstruct}.}.

%
\definecolor{frame}{rgb}{0.905,0.905,0.905}
\lstset{language=Python,backgroundcolor=\color{frame},showstringspaces=false,numbers=left,numberstyle=\tiny}
\lstinputlisting[frame=single]{easystart/SConstruct}

This is our ``hello  world'' example that illustrates the basic use of
some of the commands presented in Table~\ref{tbl:commands}. The plan
for this experiment is simply to download data from a public data
server, to convert it to an appropriate file format and to generate a
figure for publication. But let us have a closer look at the
\texttt{SConstruct} script and try to decorticate it.\\

\lstinputlisting[firstline=1,lastline=1,frame=single]{easystart/SConstruct}
%
is a standard Python command that loads the Madagascar project
management module \texttt{rsfproj.py} which provides our extension to
SCons.\\

\lstinputlisting[firstline=4,lastline=4,frame=single]{easystart/SConstruct}
%
instructs SCons to connect to a public data server (the default server
if no FTP server information is provided) and to fetch the data file
\texttt{lena.img} from the \texttt{data/imgs} directory. 
\begin{comment}
Note that
Madagascar expects a \texttt{data} folder on top of the specified
directory (i.e.  \texttt{imgs}). In the directory where you have your
SConstruct, running \texttt{scons lena.img} on the command line will
download the file \texttt{lena.img}.  The equivalent command lines are
\footnote{use login: anonymous, password: anonymous}
\begin{verbatim}
bash$ ftp egl.beg.utexas.edu
ftp> bin
ftp> cd data/imgs
ftp> get lena.img
ftp> bye
\end{verbatim}
\end{comment}
%
Try running ``\texttt{scons lena.img}'' on the command line. The successful output should look like
\begin{verbatim}
bash$ scons lena.img
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
retrieve(["lena.img"], [])
scons: done building targets.
\end{verbatim}
with the target file \texttt{lena.img} appearing in your directory.
In the following examples, we will use \texttt{-Q} (quiet) option of
\texttt{scons} to suppress the verbose output.

\lstinputlisting[firstline=7,lastline=9,frame=single]{easystart/SConstruct}
%
prepares the Madagascar header file \texttt{lena.hdr} using the
standard Unix command \texttt{echo}. 
%
\begin{verbatim}
bash$ scons -Q lena.hdr
echo n1=512 n2=513 in=lena.img data_format=native_uchar > lena.hdr
\end{verbatim}
%
Since \texttt{echo} does not take a standard input, stdin is set to 0
in the Flow command otherwise the first source is the standard input.
Likewise, the first target is the standard output unless otherwise
specified. 
%Note the triple quotes used because the actual command is
%broken into several lines in the SConstruct. 
Note that
\texttt{lena.img} is referred as \texttt{\$SOURCE} in the command. This
allows us to change the name of the source file without changing the command.

The data format of the \texttt{lena.img} image file is \texttt{uchar}
(unsigned character), the image consists of 513 traces with 512
samples per trace.  Our next step is to convert the image
representation to floating point numbers and to window out the first
trace so that the final image is a 512 by 512 square. The two
transformations are conveniently combined into one with the help of a Unix pipe.

\lstinputlisting[firstline=12,lastline=12,frame=single]{easystart/SConstruct}
%
\begin{verbatim}
  bash$ scons -Q lena
  scons: *** Do not know how to make target `lena'.  Stop.
\end{verbatim}
What happened? In the absence of the file suffix, the \texttt{Flow}
command assumes that the target file suffix is ``\texttt{.rsf}''. Let us try again.
\begin{verbatim}
scons -Q lena.rsf
< lena.hdr /RSF/bin/sfdd type=float | /RSF/bin/sfwindow f2=1 > lena.rsf
\end{verbatim}
Notice that Madagascar modules \texttt{sfdd} and \texttt{sfwindow} get
substituted for the corresponding short names in the
\texttt{SConstruct} file. The file \texttt{lena.rsf} is in a regularly
sampled format\footnote{See \url{http://rsf.sourceforge.net/wiki/index.php/Format}} and can be examined, for example, with \texttt{sfin lena.rsf}\footnote{See \url{http://rsf.sourceforge.net/wiki/index.php/Programs\#sfin}.}.
\begin{verbatim}
bash$ sfin lena.rsf
lena.rsf:
    in="/datapath/lena.rsf@"
    esize=4 type=float form=native
    n1=512         d1=1           o1=0
    n2=512         d2=1           o2=1
        262144 elements 1048576 bytes
\end{verbatim}
In the last step, we will create a plot file for displaying the image
on the screen and for including it in the publication.
%
\lstinputlisting[firstline=15,lastline=19,frame=single]{easystart/SConstruct}
%
Notice that we broke the long command string into multiple lines by
using Python's triple quote syntax. All the extra white space will be
ignored when the multiple line string gets translated into the command
line.  The \texttt{Result} command has special targets associated with
it. Try, for example, ``\texttt{scons lena.view}'' to observe the
figure \texttt{Fig/lena.vpl} generated in a specially created
\texttt{Fig} directory and displayed on the screen. The output should
look like Figure~\ref{fig:lena}.
%
\inputdir{easystart} 
\sideplot{lena}{height=.25\textheight}{The output of the first numerical experiment.}
%
The reproducible script ends with\\
%
\lstinputlisting[firstline=22,lastline=22,frame=single]{easystart/SConstruct}

Ready to experiment? Try some of the following:
\begin{enumerate}
\item Run \texttt{scons -c}. The \texttt{-c} (clean) option tells
  SCons to remove all default targets (the \texttt{Fig/lena.vpl} image
  file in our case) and also all intermediate targets that it generated. 
\begin{verbatim}
bash$ scons -c -Q
Removed lena.img
Removed lena.hdr
Removed lena.rsf
Removed /datapath/lena.rsf@
Removed Fig/lena.vpl
\end{verbatim}
Run \texttt{scons} again, and the default target will be regenerated.
\begin{verbatim}
bash$ scons -Q
retrieve(["lena.img"], [])
echo n1=512 n2=513 in=lena.img data_format=native_uchar > lena.hdr
< lena.hdr /RSF/bin/sfdd type=float | /RSF/bin/sfwindow f2=1 > lena.rsf
< lena.rsf /RSF/bin/sfgrey title="Hello, World!" transp=n color=b \
bias=128 clip=100 screenratio=1 > Fig/lena.vpl
\end{verbatim}
\item Edit your \texttt{SConstruct} file and change some of the
  plotting parameters. For example, change the value of \texttt{clip}
  from \texttt{clip=100} to \texttt{clip=50}. Run \texttt{scons} again
  and observe that only the last part of the processing flow
  (precisely, the part affected by the parameter change) is being run:
\begin{verbatim}
bash$ scons -Q view
< lena.rsf /RSF/bin/sfgrey title="Hello, World!" transp=n color=b \
bias=128 clip=50 screenratio=1 > Fig/lena.vpl
/RSF/bin/xtpen Fig/lena.vpl
\end{verbatim}
  SCons is smart enough to recognize that your editing did not affect
  any of the previous results in the data flow chain! Keeping track of
  dependencies is the main feature that separates data processing and
  computational experimenting with SCons from using linear shell
  scripts.  For computationally demanding data processing, this
  feature can save you a lot of time and can make your experiments
  more interactive and enjoyable.
\item A special parameter to SCons (defined in \texttt{rsfproj.py})
  can time the execution of each step in the processing flow. Try
  running \texttt{scons TIMER=y}.
\item The \texttt{rsfproj} module has direct access to the database
  that stores parameters of all Madagascar modules. Try running
  \texttt{scons CHECKPAR=y} to see parameter checking enforced before
  computations\footnote{This feature is new and experimental and may
    not work properly yet}.
\end{enumerate}

The summary of our SCons commands is given in Table~\ref{tbl:proj}.

\tabl{proj}{SCons commands and options defined in \texttt{rsfproj}.}{
\begin{center}
\begin{tabular}{|p{0.9\textwidth}|}
  \hline 
  \noindent\texttt{scons $<$file$>$} \\ \ \\
  \indent Generate \texttt{$<$file$>$} (usually requires \texttt{.rsf} suffix for \texttt{Flow} targets and \texttt{.vpl} suffix for \texttt{Plot} targets.) \\
 \hline
  \noindent\texttt{scons}\\ \ \\
  \indent Generate default targets (usually 
  figures specified in \texttt{Result}.) \\