with an error message, using the \texttt{sf\_error} function.  It isgenerally a good idea to check the input for user errors and, if theycannot 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. Byconvention, the dimensions of the cube are stored in \texttt{n1=},\texttt{n2=}, etc. parameters. The \texttt{n1} parameter refers to thefastest 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) andabort if no value for \texttt{n1} is found. Since Fortran-77 cannoteasily handle dynamic allocation, we also need to check that\texttt{n1} is not larger than the size of the statically allocatedarray. 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}, weavoid the need to extract additional parameters for the hypercubedimensions 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 bespecified, 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 isfound among the command line arguments, the program is aborted with anerror 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 andinclude additional compiler flags if necessary. The flags that RSF typicallyuses 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-lineinterface.\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 functionsaccept 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")} areacceptable.\lstinputlisting[firstline=14,lastline=15,frame=single]{\RSF/api/clip.f90}A call to \texttt{from\_par} extracts the ``\texttt{n1}'' parameterfrom the input file. Conceptually, the RSF data model is amultidimensional hypercube.  The \texttt{n1} parameter refers to thefastest axis. If the input dataset is a collection of traces,\texttt{n1} corresponds to the trace length. We could proceed in asimilar fashion, extracting \texttt{n2}, \texttt{n3}, etc. If we areinterested in the total number of traces, like in the clip example, ashortcut is to use the \texttt{filesize} function.  Calling\texttt{filesize(in)} returns the total number of elements in thehypercube (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 parametersfor 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 bespecified, for example, as \texttt{clip=10}. If we knew a good defaultvalue for \texttt{clip}, we could specify it with an optionalargument, 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 andinclude additional compiler flags if necessary. The flags that RSF typicallyuses 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 andoutput 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 datasetis a collection of traces, \texttt{n1} corresponds to the tracelength. 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)} returnsthe total number of elements in the hypercube (the product of\texttt{n1}, \texttt{n2}, etc.), calling \texttt{size(1)} returns thenumber 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 otherdimensions 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++ andFortran-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 configurationparameters are stored in \texttt{\$RSFROOT/lib/rsfconfig.py}.\bibliographystyle{seg} \bibliography{api}%%% Local Variables: %%% mode: latex%%% TeX-master: t%%% End: