api.tex

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

with an error message, using the \texttt{sf\_error} function.  It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.

\lstinputlisting[firstline=15,lastline=20,frame=single]{\RSF/api/clip.f}
Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in \texttt{n1=},
\texttt{n2=}, etc. parameters. The \texttt{n1} parameter refers to the
fastest axis. If the input dataset is a collection of traces,
\texttt{n1} refers to the trace length. We extract it using the
\texttt{sf\_histint} function (integer parameter from history) and
abort if no value for \texttt{n1} is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
\texttt{n1} is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting \texttt{n2},
\texttt{n3}, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
\texttt{sf\_leftsize} function.  Calling \texttt{sf\_leftsize(in,0)}
returns the total number of elements in the hypercube (the product of
\texttt{n1}, \texttt{n2}, etc.), calling \texttt{sf\_leftsize(in,1)}
returns the number of traces (the product of \texttt{n2}, \texttt{n3},
etc.), calling \texttt{sf\_leftsize(in,2)} returns the product of
\texttt{n3}, \texttt{n4}, etc. By calling \texttt{sf\_leftsize}, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.

\lstinputlisting[firstline=22,lastline=23,frame=single]{\RSF/api/clip.f}
The clip parameter is read from the command line, where it can be
specified, for example, as \texttt{clip=10}. The parameter has the
\texttt{float} type, therefore we read it with the
\texttt{sf\_getfloat} function. If no \texttt{clip=} parameter is
found among the command line arguments, the program is aborted with an
error message using the \texttt{sf\_error} function.

\lstinputlisting[firstline=25,lastline=37,frame=single]{\RSF/api/clip.f}
Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

\subsection{Compiling}

To compile the Fortran-77 program, run
\begin{verbatim}
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
\end{verbatim}
Change \texttt{f77} to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in \texttt{\$RSFROOT/lib/rsfconfig.py}.

\section{Fortran-90 interface}

\lstset{language=fortran}

The Fortran-90 clip function is listed below.

\lstinputlisting[frame=single]{\RSF/api/clip.f90}

Let us examine it in detail.

\lstinputlisting[firstline=2,lastline=2,frame=single]{\RSF/api/clip.f90}
The program starts with importing the \texttt{rsf} module.

\lstinputlisting[firstline=10,lastline=10,frame=single]{\RSF/api/clip.f90}
A call to \texttt{sf\_init} is needed to initialize the command-line
interface.

\lstinputlisting[firstline=11,lastline=12,frame=single]{\RSF/api/clip.f90}
The standard input and output files are initialized with
\texttt{rsf\_input} and \texttt{rsf\_output} functions. Both functions
accept optional arguments. For example, if the command line contains
\texttt{vel=velocity.rsf}, then both
\texttt{rsf\_input("velocity.rsf")} and \texttt{rsf\_input("vel")} are
acceptable.

\lstinputlisting[firstline=14,lastline=15,frame=single]{\RSF/api/clip.f90}
A call to \texttt{from\_par} extracts the ``\texttt{n1}'' parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube.  The \texttt{n1} parameter refers to the
fastest axis. If the input dataset is a collection of traces,
\texttt{n1} corresponds to the trace length. We could proceed in a
similar fashion, extracting \texttt{n2}, \texttt{n3}, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the \texttt{filesize} function.  Calling
\texttt{filesize(in)} returns the total number of elements in the
hypercube (the product of \texttt{n1}, \texttt{n2}, etc.), calling
\texttt{filesize(in,1)} returns the number of traces (the product of
\texttt{n2}, \texttt{n3}, etc.), calling \texttt{filesize(in,2)}
returns the product of \texttt{n3}, \texttt{n4}, etc. By calling
\texttt{filesize}, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.

\lstinputlisting[firstline=17,lastline=17,frame=single]{\RSF/api/clip.f90}
The clip parameter is read from the command line, where it can be
specified, for example, as \texttt{clip=10}. If we knew a good default
value for \texttt{clip}, we could specify it with an optional
argument, i.e. \texttt{call~from\_par("clip",clip,default)}.

\lstinputlisting[firstline=21,lastline=28,frame=single]{\RSF/api/clip.f90}
Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

\subsection{Compiling}
To compile the Fortran-90 program, run
\begin{verbatim}
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
\end{verbatim}
Change \texttt{f90} to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in \texttt{\$RSFROOT/lib/rsfconfig.py}.

\section{Python interface}

\lstset{language=python}

The Python clip script is listed below.

\lstinputlisting[frame=single]{\RSF/api/clippy.exe}
Let us examine it in detail. 

\lstinputlisting[firstline=3,lastline=4,frame=single]{\RSF/api/clippy.exe}
The script starts with importing the \texttt{numpy} and \texttt{rsf}
modules.

\lstinputlisting[firstline=6,lastline=9,frame=single]{\RSF/api/clippy.exe}
Next, we initialize the command line interface and the standard input and
output files. We also make sure that the input file type is floating point.

\lstinputlisting[firstline=11,lastline=13,frame=single]{\RSF/api/clippy.exe}
We extract the ``\texttt{n1}'' parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube.  The
\texttt{n1} parameter refers to the fastest axis. If the input dataset
is a collection of traces, \texttt{n1} corresponds to the trace
length. We could proceed in a similar fashion, extracting \texttt{n2},
\texttt{n3}, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the \texttt{size}
method of the \texttt{Input} class1.  Calling \texttt{size(0)} returns
the total number of elements in the hypercube (the product of
\texttt{n1}, \texttt{n2}, etc.), calling \texttt{size(1)} returns the
number of traces (the product of \texttt{n2}, \texttt{n3}, etc.),
calling \texttt{size(2)} returns the product of \texttt{n3},
\texttt{n4}, etc.

\lstinputlisting[firstline=15,lastline=16,frame=single]{\RSF/api/clippy.exe}
The clip parameter is read from the command line, where it can be specified,
for example, as \texttt{clip=10}.

\lstinputlisting[firstline=20,lastline=23,frame=single]{\RSF/api/clippy.exe}
Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

\subsection{Compiling}

The python script does not require compilation. Simply make sure that
\texttt{\$RSFROOT/lib} is in \texttt{PYTHONPATH}. 

\section{MATLAB interface} % a meaningless comment

\lstset{language=matlab}

The MATLAB clip function is listed below.

\lstinputlisting[frame=single]{\RSF/api/clip.m}

Let us examine it in detail. 

\lstinputlisting[firstline=4,lastline=4,frame=single]{\RSF/api/clip.m}
We start by figuring out the input file dimensions.

\lstinputlisting[firstline=5,lastline=6,frame=single]{\RSF/api/clip.m}
The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.

\lstinputlisting[firstline=7,lastline=8,frame=single]{\RSF/api/clip.m}
Next, we allocate the trace array and create an output file.

\lstinputlisting[firstline=10,lastline=15,frame=single]{\RSF/api/clip.m}
Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

\subsection{Compiling}

The MATLAB script does not require compilation. Simply make sure that
\texttt{\$RSFROOT/lib} is in \texttt{MATLABPATH}.

\section{Installation} 

To install the interface to a particular language, use \texttt{API=}
parameter in the RSF configuration. For example, to to install C++ and
Fortran-90 API bindings in addition to the basic package, run
\begin{verbatim}
scons API=c++,fortran-90 config
\end{verbatim}
Only the C interface is configured by default. The configuration
parameters are stored in \texttt{\$RSFROOT/lib/rsfconfig.py}.

\bibliographystyle{seg} 
\bibliography{api}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: