Madagascar - User contributions [en]

Guide to madagascar API

2013-10-06T11:57:59Z

Nick: /* Fortran-90 interface */ Good practice -- always explicitly deallocate arrays

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<c>
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</c>

Let us examine it in detail.
<c>
#include <rsf.h>
</c>

The include preprocessing directive is required to access the RSF interface.
<c>
sf_file in=NULL, out=NULL; /* Input and output files */
</c>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<c>
/* Initialize RSF */
sf_init(argc,argv);
</c>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<c>
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</c>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<c>
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</c>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> 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.
<c>
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</c>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<c>
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</c>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<c>
/* allocate floating point array */
trace = sf_floatalloc (n1);
</c>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<c>
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</c>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<c>
sf_close();
exit(0)
</c>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<cpp>
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</cpp>

Let us examine it line by line.
<cpp>
#include <rsf.hh>
</cpp>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<cpp>
sf_init(argc,argv); // Initialize RSF
</cpp>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<cpp>
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</cpp>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<cpp>
in.get("n1",n1);
n2=in.size(1);
</cpp>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<cpp>
par.get("clip",clip); // parameter from the command line
</cpp>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<cpp>
std::valarray<float> trace(n1);
</cpp>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<cpp>
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</cpp>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<fortran>
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</fortran>

Let us examine it in detail.
<fortran>
call sf_init()
</fortran>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<fortran>
in = sf_input("in")
out = sf_output("out")
</fortran>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<fortran>
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</fortran>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> 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.
<fortran>
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</fortran>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<fortran>
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<fortran>
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<fortran>
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do

deallocate (trace)

end program Clipit
</fortran>

Let us examine it in detail.
<fortran>
use rsf
</fortran>

The program starts with importing the <tt>rsf</tt> module.
<fortran>
call sf_init() ! initialize RSF
</fortran>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<fortran>
in = rsf_input()
out = rsf_output()
</fortran>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<fortran>
if (sf_float /= gettype(in)) call sf_error("Need float type")

</fortran>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<fortran>
n2 = filesize(in,1)
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<fortran>
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==

The Python clip script is listed below.
<python>
#!/usr/bin/env python

import numpy
import rsf.api as rsf

par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type

n1 = input.int("n1")
n2 = input.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</python>

Let us examine it in detail.
<python>
import numpy
import rsf.api as rsf
</python>

The script starts with importing the <tt>numpy</tt> module and the
<tt>rsf</tt> API.
<python>
par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type
</python>

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.
<python>
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</python>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class1. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<python>
clip = par.float("clip")
assert clip
</python>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<python>
for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</python>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=10 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<python>
import numpy, rsf.api

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)
data = data.transpose() # Example of numpy in action

print data
</python>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16. 17.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17. 18.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<python>
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</python>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<python>
show()
</python>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<python>
savefig('myfile.png')
</python>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<python>
#!/usr/bin/env python
import rsf.api, numpy, sys, pylab

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)

pylab.imshow(data)
pylab.savefig('out.png')
</python>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Guide to madagascar API

2013-10-06T11:57:14Z

Nick: /* C interface */ Good practice -- always explicitly deallocate arrays

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<c>
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</c>

Let us examine it in detail.
<c>
#include <rsf.h>
</c>

The include preprocessing directive is required to access the RSF interface.
<c>
sf_file in=NULL, out=NULL; /* Input and output files */
</c>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<c>
/* Initialize RSF */
sf_init(argc,argv);
</c>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<c>
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</c>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<c>
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</c>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> 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.
<c>
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</c>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<c>
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</c>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<c>
/* allocate floating point array */
trace = sf_floatalloc (n1);
</c>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<c>
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</c>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<c>
sf_close();
exit(0)
</c>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<cpp>
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</cpp>

Let us examine it line by line.
<cpp>
#include <rsf.hh>
</cpp>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<cpp>
sf_init(argc,argv); // Initialize RSF
</cpp>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<cpp>
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</cpp>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<cpp>
in.get("n1",n1);
n2=in.size(1);
</cpp>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<cpp>
par.get("clip",clip); // parameter from the command line
</cpp>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<cpp>
std::valarray<float> trace(n1);
</cpp>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<cpp>
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</cpp>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<fortran>
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</fortran>

Let us examine it in detail.
<fortran>
call sf_init()
</fortran>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<fortran>
in = sf_input("in")
out = sf_output("out")
</fortran>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<fortran>
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</fortran>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> 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.
<fortran>
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</fortran>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<fortran>
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<fortran>
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<fortran>
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do
end program Clipit
</fortran>

Let us examine it in detail.
<fortran>
use rsf
</fortran>

The program starts with importing the <tt>rsf</tt> module.
<fortran>
call sf_init() ! initialize RSF
</fortran>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<fortran>
in = rsf_input()
out = rsf_output()
</fortran>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<fortran>
if (sf_float /= gettype(in)) call sf_error("Need float type")

</fortran>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<fortran>
n2 = filesize(in,1)
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<fortran>
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==

The Python clip script is listed below.
<python>
#!/usr/bin/env python

import numpy
import rsf.api as rsf

par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type

n1 = input.int("n1")
n2 = input.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</python>

Let us examine it in detail.
<python>
import numpy
import rsf.api as rsf
</python>

The script starts with importing the <tt>numpy</tt> module and the
<tt>rsf</tt> API.
<python>
par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type
</python>

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.
<python>
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</python>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class1. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<python>
clip = par.float("clip")
assert clip
</python>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<python>
for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</python>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=10 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<python>
import numpy, rsf.api

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)
data = data.transpose() # Example of numpy in action

print data
</python>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16. 17.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17. 18.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<python>
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</python>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<python>
show()
</python>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<python>
savefig('myfile.png')
</python>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<python>
#!/usr/bin/env python
import rsf.api, numpy, sys, pylab

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)

pylab.imshow(data)
pylab.savefig('out.png')
</python>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Package overview

2013-02-22T01:29:32Z

Nick: Reverted edits by NanetteWashington1968 (talk) to last revision by Ediazpantin

[[Image:Fotolia_5127720_XS.jpg|right|]]

The mission of the Madagascar project is to provide a '''shared research environment''' for computational data analysis in geophysics and related fields.

The Madagascar environment consists of:
# Standalone programs for out-of-core data analysis;
# Standalone programs for geophysical data processing and imaging;
# A development kit for C, C++, Java, Fortran-77, Fortran-90, Python, Matlab, and Octave;
# A framework for reproducible numerical experiments, based on [http://www.scons.org/ SCons];
# A framework for scientific publications, based on [http://www.scons.org/ SCons] and [http://en.wikipedia.org/wiki/LaTeX LaTeX];
# A collection of reproducible scientific articles also used as usage examples and regression tests for the standalone programs;
# A collection of datasets used as input to reproducible numerical experiments.

This guide serves as a brief introduction of different components and shows how they all fit together.

==How to obtain Madagascar==

See [[Download|download]] and [[Installation | installation instructions]]. Madagascar runs on Unix/Linux platforms, including MacOS X and Unix emulations under Miscrosoft Windows. Its installation requires, at a minimum, a working C compiler and Python.

==How to find your way around Madagascar==

Start by checking the [[Reproducible_Documents|list of reproducible papers]]. If any of these papers looks close to your interests, follow the links until you find a figure with a "wrench" button under it [[Image:configure.png]]. Click on the wrench, and it will open a computational recipe used for generating the figure (the <tt>SConstruct</tt> file).
<python>
from rsf.proj import *
Flow('rose',None,
'''
math n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5
output="x2*(8+sin(6*x1+x2/10))" |
rtoc |
math output="input*exp(I*x1)"
''')
Result('rose',
'graph title=Rose screenratio=1 wantaxis=n')
End()
</python>
You can copy this recipe to your computer or simply find it already existing in the "book" subtree under the Madagascar source directory. For example, the recipe at http://www.reproducibility.org/RSF/book/rsf/rsf/sfmath.html also exists in the file <tt>RSFSRC/book/rsf/rsf/sfmath/SConstruct</tt>. After copying or locating the appropriate <tt>SConstruct</tt> file,
run
<pre>
scons view
</pre>
on the command line to generate all the figures in the selected project and to display them on your screen. For example, try
<pre>
bash$ cd RSFSRC/book/rsf/rsf/sfmath
bash$ scons view
</pre>
where <tt>bash$</tt> stands for the Unix prompt and <tt>RSFSRC</tt> stands for the Madagascar source directory. The output should look like
<pre>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
/RSFROOT/bin/sfmath n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5 output="x2*(8+sin(6*x1+x2/10))" | /RSFROOT/bin/sfrtoc |
/RSFROOT/bin/sfmath output="input*exp(I*x1)" > rose.rsf
< rose.rsf /RSFROOT/bin/sfgraph title=Rose screenratio=1 wantaxis=n > Fig/rose.vpl
/RSFROOT/bin/sfpen Fig/rose.vpl
scons: done building targets.
</pre>
with a picture appearing on your screen.
[[Image:rose.png|frame|center]]
If there are several figures in the recipe, you can run
<pre>
scons figurename.view
</pre>
(e.g. <tt>scons rose.view</tt>) to display individual figures. To remove all files that <tt>scons view</tt> generated, run
<pre>
scons -c view
</pre>
If you want to know in advance what commands will be executed to generate the figures, try
<pre>
scons -n view
</pre>
You can output this command to a file
<pre>
scons -n -Q view > script.sh
</pre>
and use <tt>script.sh</tt> as a shell script. If you are to make modifications to the data processing recipe (changing parameters or trying new data), working with SCons is more powerful and convenient than running shell scripts.

A computational recipe puts together individual commands through Unix pipes and SCons rules. These commands act like Lego blocks for creating complex data analysis constructions. In the example above, three "blocks" are used: <tt>sfmath</tt>, <tt>sfrtoc</tt>, and <tt>sfgraph</tt>. To find out what a particular command is doing, you can follow the links from the bottom of the web page http://www.reproducibility.org/RSF/book/rsf/rsf/sfmath.html
Alternatively, run the command without arguments on the command line. Running
<pre>
bash$ sfrtoc
</pre>
produces something like
<pre>
NAME
sfrtoc
DESCRIPTION
Convert real data to complex (by adding zero imaginary part).
SYNOPSIS
sfrtoc < real.rsf > cmplx.rsf
COMMENTS
See also: sfcmplx
USED IN
bei/ft1/plane4
bei/ft1/autocor
bei/ft1/brad
[...]
SOURCE
user/main/rtoc.c
DOCUMENTATION
http://reproducibility.org/wiki/Guide_to_madagascar_programs#sfrtoc
</pre>

The DOCUMENTATION section provides a link to a more detailed documentation on the web. The most useful part is the USED IN section, which points to more examples of using the program. As an exercise, change directory to <tt>RSFSRC/book/bei/ft1/plane4</tt> or any other example directory, examine the <tt>SConstruct</tt> file, and run <tt>scons view</tt>. Alternatively, look at http://www.reproducibility.org/RSF/book/bei/ft1/plane4.html

Want to find a program by keywords? Try <tt>sfdoc -k</tt>.
<pre>
bash$ sfdoc -k complex
sfsort: Sort a float/complex vector by absolute values.
sfrtoc: Convert real data to complex (by adding zero imaginary part).
sfjacobi2: Find eigenvalues of a general complex matrix by Jacobi-like iteration.
sfboolcmp: Element-wise boolean comparison of values. For int/float/complex data-sets.
sfcmatmult: Simple matrix multiplication for complex matrices
sfimag: Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
sfthr: Threshold float/complex inputs given a constant/varying threshold level.
sfcpef: 1-D prediction-error filter estimation from complex data
sfroots: Find roots of a complex polynomial.
sfreal: Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
sfcmplx: Create a complex dataset from its real and imaginary parts.
sfsin: Simple operations with complex sinusoids
sfcdottest: Generic dot-product test for complex linear operators with adjoints
sfcconjgrad: Generic conjugate-gradient solver for linear inversion with complex data
</pre>

Individual components of the Madagascar environment are described in more details below.

==Madagascar components==

===Standalone programs===
The list of all standalone programs is available [http://www.reproducibility.org/RSF/ online]. Most programs act as filters on input data and can be chained through Unix pipes, i.e.:
<bash>
< data.rsf sfwindow n1=100 | sfbandpass fhi=60 > data2.rsf
</bash>
This approach follows the Unix philosophy, as formulated by Doug McIlroy, the inventor of Unix pipes (Salus, 1994<ref>Salus, P. H., 1994, A quarter-century of Unix: Addison-Wesley.</ref>):
#Write programs that do one thing and do it well.
#Write programs to work together.
#Write programs to handle text streams, because that is a universal interface.

Following the Unix convention, programs have brief <tt>man</tt> pages, which explain the program purpose and parameters. You can access this documentation by running a program without parameters. To search for a program by a keyword, use <tt>sfdoc -k <keyword></tt>.

The [[guide to madagascar programs]] provides more detailed documentation for selected programs while the [[task-centric program list]] attempts to categorize them. You can see the programs in actual use in the [[Reproducible Documents]].

===Data format===

For data, Madagascar uses the [[Guide to RSF file format| Regularly Sampled Format]] (RSF), which is based on the concept of hypercubes (n-D arrays, or regularly sampled functions of several variables), much like the SEPlib (its closest relative), DDS, or the regularly-sampled version of the Javaseis format (SVF). Up to 9 dimensions are supported. For 1D it is conceptually analogous to a time series, for 2D to a raster image, and for 3D to a [http://en.wikipedia.org/wiki/Voxel voxel volume]. The format (actually a [http://en.wikipedia.org/wiki/Meta meta]format) makes use of a ASCII file with metadata (information about the data), including a pointer (<tt>in=</tt> parameter) to the location of the file with the actual data values. Irregularly sampled data are currently handled as a pair of datasets, one containing data and the second containing the corresponding irregular geometry information. Programs for conversion to and from other formats such as SEG-Y and SU are provided.

For graphics, Madagascar currently uses the Vplot vector graphics format. Converters to other graphics formats (Postscript, PNG, GIF, JPEG) are also provided.

===Reproducible documents===

A reproducible document consists of LaTeX source combined with SCons rules required to fully build the documents. These rules are expressed in terms of SCons extensions that are provided as part of Madagascar.

This is the key to the reproducibility aspect of Madagascar. An introduction to reproducible Madagascar documents is at [[Reproducible_computational_experiments_using_SCons]] .

===Vplot graphics===

In contrast to most other Madagascar Components, graphics components produce Vplot data as output.

Vplot is a device independent graphics format that allows both vector and raster elements (as such,
it is comparable to Postscript). Vplot files are interpreted by a number of output devices. Its typical usage is for a visual display in X-windows. A list of them is [[Guide to madagascar programs#Plotting programs | provided on the wiki]].

Here is an example of a Madagascar pipe. In this case it takes a subsection of a file, low-pass
filters it, and saves the result

<bash>
< data.rsf sfwindow n1=100 | sfbandpass fhi=60 > data2.rsf
</bash>

In this more elaborate case, the final output is passed to a graphics program and plotted.

<bash>
< data.rsf sfwindow n1=100 | sfbandpass fhi=60 | sfcontour | xtpen
</bash>

More extensive examples are seen in [[Guide to madagascar programs]] . The novice reader should probably read the material below before proceeding to that page.

===Reproducibility and Project Management===

Madagascar uses and extends [http://www.scons.org/ SCons], an open-source
software construction package, to document and maintain data processing flows. Documented projects become
computational recipes that can be easily exchanged among Madagascar users.

SCons is a rule-based package in Python typically used as a build system analogous to <tt>make</tt>. Familiarity with any build system will
be helpful in understanding SCons. SCons statements, as python statements, are invoked in the sequence they are
written, but as such they only define rules. The rules are invoked in accordance with a dependency graph which
SCons builds based on those rules. Components regarded as "up-to-date" are not rebuilt.

SCons allows for user-contributed Builders (meta-rule categories) and Madagascar uses this capability extensively.
The idea is that building an output file based on a workflow chain is very much analogous to building a
software package based on a software tool chain. The calculation is seen simply as a build with dependencies.
This is a considerable benefit in developing alternative workflows using a given dataset. The system
maintains an awareness of already completed calculations. Without user intervention, redundant calculations
are avoided.

Madagascar calculations are thus expressed as SCons scripts (<tt>SConstruct</tt> files). SCons extensions follow SCons conventions in beginning
with an uppercase letter. The most common Madagascar extensions are <tt>Flow()</tt>, <tt>Result()</tt>, and <tt>End()</tt>. A <tt>Flow()</tt> invocation wraps Madagascar computational components. <tt>Result()</tt> is a version of <tt>Flow()</tt> with a graphical output. Finally an
End() actually invokes the default rules for multiple results.

Finally, Madagascar enables a collection of reproducible documents, organized in living books. Each
reproducible book contains a collection of Madagascar recipes (<tt>SConstruct</tt> files) used to generate book figures. The recipes
cover a variety of data processing and imaging tasks described in the books. Figures and recipes serve
dual purpose with respect to Madagascar maintenance. They provide demos for introducing new users to the
functionality of the package and, at the same time, [[Automatic Testing|regression tests]] for assuring the system stability
under change.

==Madagascar Trivia==

===Why the Name "Madagascar"?===

[http://www.reproducibility.org/rsflog/index.php?/archives/67-Madagascar.html Whimsy, really]. It seems easier to remember than the previous name "RSF", and it provides us interesting [http://www.reproducibility.org/rsflog/index.php?/archives/178-Ahay!.html mascots].

===License===

The Madagascar package is released in an open-source form under the standard [http://www.gnu.org/copyleft/gpl.html GNU GPL] license. In simple
words, there are no restrictions on the use of the software (including copying, modifying, selling, etc.)
However, there are restrictions on the software redistribution intended to prevent the package from losing
its open-source status. Users are encouraged to [[Contributing new programs to Madagascar|submit their modifications]] back to the original distribution for the benefit of the whole [[Package_overview#Community|community]].

===Community===

Madagascar seeks to be an open and active community. Mailing lists are maintained, and annual meetings take place. See
* [[Conferences]]
* [http://www.ahay.org/rsflog Development blog]
* [https://lists.sourceforge.net/lists/listinfo/rsf-user RSF-user mailing list]
* [https://lists.sourceforge.net/lists/listinfo/rsf-devel RSF-devel mailing list]
Your participation is welcome.

===History===

Madagascar was first publicly presented at the [[Conferences#Vienna_2006_.28EAGE.29|EAGE Workshop]] in Vienna in June 2006. The work on the package (previously named RSF) was started by Sergey Fomel in 2003. Since then, many people have contributed to it. See [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/AUTHORS.txt?view=markup AUTHORS.txt] for an incomplete list.

While being written mostly from scratch, Madagascar borrows ideas from the design of [http://sepwww.stanford.ed/doku.php?id=sep:software:seplib SEPlib], a package maintained by Bob Clapp at the Stanford Exploration Project (SEP). Generations of SEP students and researchers contributed to SEPlib. Most important contributions came from Rob Clayton, Jon Claerbout, Dave Hale, Stew Levin, Rick Ottolini, Joe Dellinger, Steve Cole, Dave Nichols, Martin Karrenbach, Biondo Biondi, and Bob Clapp.

Madagascar also borrows ideas from [http://timna.mines.edu/cwpcodes/ Seismic Unix] (SU), an open-source package maintained by John Stockwell at the Center for Wave Phenomena (CWP) at the Colorado School of Mines (Stockwell, 1997<ref>Stockwell, J. W., 1997, Free software in education: A case study of CWP/SU: Seismic Unix: The Leading Edge, '''16''', 1045--1049.</ref>;Stockwell, 1999<ref>--------, 1999, The CWP/SU: Seismic Un*x package: Computers and Geosciences, '''25''', 415--419.</ref>). Main contributors to SU included Einar Kjartansson, Shuki Ronen, Jack Cohen, Chris Liner, Dave Hale, and John Stockwell. SU adopted an open-source BSD-style license starting with release 40 (April 10, 2007).

<references/>

Guide to madagascar programs

2012-12-07T03:58:43Z

Nick: /* sfmath */

<center>''This page was created from the LaTeX source in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/rsf/prog.tex?view=markup book/rsf/rsf/prog.tex] using [[latex2wiki]]''</center>

This guide introduces some of the most used <tt>madagascar</tt> programs and illustrates their usage with examples.
=Main programs=
The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/ system/main] in the Madagascar distribution. The "main" programs perform general-purpose operations on RSF hypercubes regardless of the data dimensionality or physical dimensions.

==sfadd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Add, multiply, or divide RSF datasets.
|-
! colspan="4" | sfadd > out.rsf scale= add= sqrt= abs= log= exp= mode= [< file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | The various operations, if selected, occur in the following order: (1) Take absolute value, abs= (2) Add a scalar, add= (3) Take the natural logarithm, log= (4) Take the square root, sqrt= (5) Multiply by a scalar, scale= (6) Compute the base-e exponential, exp= (7) Add, multiply, or divide the data sets, mode= sfadd operates on integer, float, or complex data, but all the input and output files must be of the same data type. An alternative to sfadd is sfmath, which is more versatile, but may be less efficient.
|-
| ''bools '' || '''abs=''' || || If true take absolute value [nin]
|-
| ''floats '' || '''add=''' || || Scalar values to add to each dataset [nin]
|-
| ''bools '' || '''exp=''' || || If true compute exponential [nin]
|-
| ''bools '' || '''log=''' || || If true take logarithm [nin]
|-
| ''string '' || '''mode=''' || || 'a' means add (default), 'p' or 'm' means multiply, 'd' means divide
|-
| ''floats '' || '''scale=''' || || Scalar values to multiply each dataset with [nin]
|-
| ''bools '' || '''sqrt=''' || || If true take square root [nin]
|}

<tt>sfadd</tt> is useful for combining (adding, dividing, or
multiplying) several datasets. What if you want to subtract two
datasets? Easy. Use the <tt>scale</tt> parameter as follows:
<pre>
bash$ sfadd data1.rsf data2.rsf scale=1,-1 > diff.rsf
</pre>
or
<pre>
bash$ sfadd < data1.rsf data2.rsf scale=1,-1 > diff.rsf
</pre>
The same task can be accomplished with the more general <tt>sfmath</tt> program:
<pre>
bash$ sfmath one=data1.rsf two=data2.rsf output='one-two' > diff.rsf
</pre>
or
<pre>
bash$ sfmath < data1.rsf two=data2.rsf output='input-two' > diff.rsf
</pre>
In both cases, the size and shape of <tt>data1.rsf</tt> and
<tt>data2.rsf</tt> hypercubes should be the same, and a warning
message is printed out if the the axis sampling parameters (such as
<tt>o1</tt> or <tt>d1</tt>) in these files are different.
====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/add.c?view=markup system/main/add.c]====
The first input file is either in the list or in the standard input.
<c>
/* find number of input files */
if (isatty(fileno(stdin))) {
/* no input file in stdin */
nin=0;
} else {
in[0] = sf_input("in");
nin=1;
}
</c>

Collect input files in the <tt>in</tt> array from all command-line
parameters that don't contain an "<tt>=</tt>" sign. The total number
of input files in <tt>nin</tt>.
<c>
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'=')) continue;
in[nin] = sf_input(argv[i]);
nin++;
}
if (0==nin) sf_error ("no input");
/* nin = no of input files*/
</c>

A helper function <tt>check_compat</tt> checks the compatibility of
input files.
<c>
static void
check_compat (sf_datatype type /* data type */,
size_t nin /* number of files */,
sf_file* in /* input files [nin] */,
int dim /* file dimensionality */,
const int* n /* dimensions [dim] */)
/* Check that the input files are compatible.
Issue error for type mismatch or size mismatch.
Issue warning for grid parameters mismatch. */
{
int ni, id;
size_t i;
float d, di, o, oi;
char key[3];
const float tol=1.e-5; /* tolerance for comparison */

for (i=1; i < nin; i++) {
if (sf_gettype(in[i]) != type)
sf_error ("type mismatch: need %d",type);
for (id=1; id <= dim; id++) {
(void) snprintf(key,3,"n%d",id);
if (!sf_histint(in[i],key,&ni) || ni != n[id-1])
sf_error("%s mismatch: need %d",key,n[id-1]);
(void) snprintf(key,3,"d%d",id);
if (sf_histfloat(in[0],key,&d)) {
if (!sf_histfloat(in[i],key,&di) ||
(fabsf(di-d) > tol*fabsf(d)))
sf_warning("%s mismatch: need %g",key,d);
} else {
d = 1.;
}
(void) snprintf(key,3,"o%d",id);
if (sf_histfloat(in[0],key,&o) &&
(!sf_histfloat(in[i],key,&oi) ||
(fabsf(oi-o) > tol*fabsf(d))))
sf_warning("%s mismatch: need %g",key,o);
}
}
}
</c>

Finally, we enter the main loop, where input data are getting read
buffer by buffer and combined in the total product depending on the
data type.
<c>
for (nbuf /= sf_esize(in[0]); nsiz > 0; nsiz -= nbuf) {
if (nbuf > nsiz) nbuf=nsiz;

for (j=0; j < nin; j++) {
collect = (bool) (j != 0);
switch(type) {
case SF_FLOAT:
sf_floatread((float*) bufi,
nbuf,
in[j]);
add_float(collect,
nbuf,
(float*) buf,
(const float*) bufi,
cmode,
scale[j],
add[j],
abs_flag[j],
log_flag[j],
sqrt_flag[j],
exp_flag[j]);
break;
</c>

The data combination program for floating point numbers is
<tt>add_float</tt>.
<c>
static void add_float (bool collect, /* if collect */
size_t nbuf, /* buffer size */
float* buf, /* output [nbuf] */
const float* bufi, /* input [nbuf] */
char cmode, /* operation */
float scale, /* scale factor */
float add, /* add factor */
bool abs_flag, /* if abs */
bool log_flag, /* if log */
bool sqrt_flag, /* if sqrt */
bool exp_flag /* if exp */)
/* Add floating point numbers */
{
size_t j;
float f;

for (j=0; j < nbuf; j++) {
f = bufi[j];
if (abs_flag) f = fabsf(f);
f += add;
if (log_flag) f = logf(f);
if (sqrt_flag) f = sqrtf(f);
if (1. != scale) f *= scale;
if (exp_flag) f = expf(f);
if (collect) {
switch (cmode) {
case 'p': /* product */
case 'm': /* multiply */
buf[j] *= f;
break;
case 'd': /* delete */
if (f != 0.) buf[j] /= f;
break;
default: /* add */
buf[j] += f;
break;
}
} else {
buf[j] = f;
}
}
}
</c>

==sfattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display dataset attributes.
|-
! colspan="4" | sfattr < in.rsf want=
|-
| colspan="4" | Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr" ******************************************* rms = 0.992354 mean value = 0.987576 2-norm value = 9.92354 variance = 0.00955481 standard deviation = 0.0977487 maximum value = 1.12735 at 97 minimum value = 0.151392 at 100 number of nonzero samples = 100 total number of samples = 100 ******************************************* rms = sqrt[ sum(data^2) / n ] mean = sum(data) / n norm = sum(abs(data)^lval)^(1/lval) variance = [ sum(data^2) - n*mean^2 ] / [ n-1 ] standard deviation = sqrt [ variance ]
|-
| ''int '' || '''lval=2''' || || norm option, lval is a non-negative integer, computes the vector lval-norm
|-
| ''string '' || '''want=''' || || 'all'(default),'rms','mean','norm','var','std','max','min','nonzero','samples','short'
:want= 'rms' displays the root mean square
:want= 'norm' displays the square norm, otherwise specified by lval.
:want= 'var' displays the variance
:want= 'std' displays the standard deviation
:want= 'nonzero' displays number of nonzero samples
:want= 'samples' displays total number of samples
:want= 'short' displays a short one-line version
|}

<tt>sfattr</tt> is a useful diagnostic program. It reports certain
statistical values for an RSF dataset: RMS (root-mean-square)
amplitude, mean value, vector norm value, variance, standard deviation,
maximum and minimum values, number of nonzero samples, and the total
number of samples.
If we denote data values as <math>d_i</math> for <math>i=0,1,2,\ldots,n</math>, then the RMS
value is <math>\sqrt{\frac{1}{n}\,\sum\limits_{i=0}^n d_i^2}</math>, the mean
value is <math>\frac{1}{n}\,\sum\limits_{i=0}^n d_i</math>, the <math>L_2</math>-norm value
is <math>\sqrt{\sum\limits_{i=0}^n d_i^2}</math>, the variance is
<math>\frac{1}{n-1}\,\left[\sum\limits_{i=0}^n d_i^2 - \frac{1}{n}\left(\sum\limits_{i=0}^n d_i\right)^2\right]</math>, and the standard
deviation is the square root of the variance. Using <tt>sfattr</tt>
is a quick way to see the distribution of data values and check it for anomalies.

The output can be parsed using utilities such as <tt>awk</tt>, to extract only a numeric value for feeding it as a parameter value into a command line interface. Notice the backticks in the example below:
<bash>
sfgrey <vel.rsf allpos=y bias=`sfattr <vel.rsf want=min | awk '{print $4}'` | sfpen
</bash>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/attr.c?view=markup system/main/attr.c]====

Computations start by finding the input data (<tt>in</tt>) size
(<tt>nsiz</tt>) and dimensions (<tt>dim</tt>).
<c>
dim = (size_t) sf_filedims (in,n);
for (nsiz=1, i=0; i < dim; i++) {
nsiz *= n[i];
}
</c>

In the main loop, we read the input data buffer by buffer.
<c>
for (nleft=nsiz; nleft > 0; nleft -= nbuf) {
nbuf = (bufsiz < nleft)? bufsiz: nleft;
switch (type) {
case SF_FLOAT:
sf_floatread((float*) buf,nbuf,in);
break;
case SF_INT:
sf_intread((int*) buf,nbuf,in);
break;
case SF_COMPLEX:
sf_complexread((sf_complex*) buf,nbuf,in);
break;
case SF_UCHAR:
sf_ucharread((unsigned char*) buf,nbuf,in);
break;
case SF_CHAR:
default:
sf_charread(buf,nbuf,in);
break;
}
</c>

The data attributes are accumulated in corresponding double-precision
variables.
<c>
fsum += f;
fsqr += f*f;
</c>

Finally, the attributes are reduced and printed out.
<c>
fmean = fsum/nsiz;
if (lval==2) fnorm = sqrt(fsqr);
else if (lval==0) fnorm = nsiz-nzero;
else fnorm = pow(flval,1./lval);
frms = sqrt(fsqr/nsiz);
if (nsiz > 1) fvar = (fsqr-nsiz*fmean*fmean)/(nsiz-1);
else fvar = 0.0;
fstd = sqrt(fvar);
</c>

<c>
if(NULL==want || 0==strcmp(want,"rms"))
printf("rms = %g \n",(float) frms);
if(NULL==want || 0==strcmp(want,"mean"))
printf("mean value = %g \n",(float) fmean);
if(NULL==want || 0==strcmp(want,"norm"))
printf("%d-norm value = %g \n",lval,(float) fnorm);
if(NULL==want || 0==strcmp(want,"var"))
printf("variance = %g \n",(float) fvar);
if(NULL==want || 0==strcmp(want,"std"))
printf("standard deviation = %g \n",(float) fstd);
</c>

==sfcat==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Concatenate datasets.
|-
! colspan="4" | sfcat > out.rsf space= axis=3 nspace=(int) (ni/(20*nin) + 1) [<file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | sfmerge inserts additional space between merged data.
|-
| ''int '' || '''axis=3''' || || Axis being merged
|-
| ''int '' || '''nspace=(int) (ni/(20*nin) + 1)''' || || if space=y, number of traces to insert
|-
| ''bool '' || '''space=''' || [y/n] || Insert additional space.
:y is default for sfmerge, n is default for sfcat
|}

<tt>sfcat</tt> and <tt>sfmerge</tt> concatenate two or more files
together along a particular axis. It is the same program, only
<tt>sfcat</tt> has the default <tt>space=n</tt> and <tt>sfmerge</tt>
has the default <tt>space=y</tt>.
Example of <tt>sfcat</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcat one.rsf one.rsf axis=1 > two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=4 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
12 elements 48 bytes
</pre>
Example of <tt>sfmerge</tt>:
<pre>
bash$ sfmerge one.rsf one.rsf axis=2 > two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=7 d2=0.1 o2=0 label2="Distance" unit2="km"
14 elements 56 bytes
</pre>
In this case, an extra empty trace is inserted between the two merged files.
The axes that are not being merged are checked for consistency:
<pre>
bash$ sfcat one.rsf two.rsf > three.rsf
sfcat: n2 mismatch: need 3
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cat.c?view=markup system/main/cat.c]====
The first input file is either in the list or in the standard input.
<c>
in = (sf_file*) sf_alloc ((size_t) argc,sizeof(sf_file));

if (!sf_stdin()) { /* no input file in stdin */
nin=0;
} else {
in[0] = sf_input("in");
nin=1;
}
</c>

Everything on the command line that does not contain a "=" sign is
treated as a file name, and the corresponding file object is added to the list.
<c>
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'='))
continue; /* not a file */
in[nin] = sf_input(argv[i]);
nin++;
}
if (0==nin) sf_error ("no input");
</c>

As explained above, if the <tt>space=</tt> parameter is not set, it is
inferred from the program name: <tt>sfmerge</tt> corresponds to
<tt>space=y</tt> and <tt>sfcat</tt> corresponds to <tt>space=n</tt>.
<c>
if (!sf_getbool("space",&space)) {
/* Insert additional space.
y is default for sfmerge, n is default for sfcat */
prog = sf_getprog();
if (NULL != strstr (prog, "merge")) {
space = true;
} else if (NULL != strstr (prog, "cat")) {
space = false;
} else {
sf_warning("%s is neither merge nor cat,"
" assume merge",prog);
space = true;
}
}
</c>

Find the axis for the merging (from the command line <tt>axis=</tt>
argument) and figure out two sizes: <tt>n1</tt> for everything after
the axis and <tt>n2</tt> for everything before the axis.
<c>
n1=1;
n2=1;
for (i=1; i <= dim; i++) {
if (i < axis) n1 *= n[i-1];
else if (i > axis) n2 *= n[i-1];
}
</c>

In the output, the selected axis will get extended.
<c>
/* figure out the length of extended axis */
ni = 0;
for (j=0; j < nin; j++) {
ni += naxis[j];
}

if (space) {
if (!sf_getint("nspace",&nspace))
nspace = (int) (ni/(20*nin) + 1);
/* if space=y, number of traces to insert */
ni += nspace*(nin-1);
}

(void) snprintf(key,3,"n%d",axis);
sf_putint(out,key,(int) ni);
</c>

The rest is simple: loop through the datasets reading and writing the
data in buffer-size chunks and adding extra empty chunks if
<tt>space=y</tt>.
<c>
for (i2=0; i2 < n2; i2++) {
for (j=0; j < nin; j++) {
for (ni = n1*naxis[j]*esize; ni > 0; ni -= nbuf) {
nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
sf_charread (buf,nbuf,in[j]);
sf_charwrite (buf,nbuf,out);
}
if (!space || j == nin-1) continue;
/* Add spaces */
memset(buf,0,BUFSIZ);
for (ni = n1*nspace*esize; ni > 0; ni -= nbuf) {
nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
sf_charwrite (buf,nbuf,out);
}
}
}
</c>

==sfcdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for complex linear operators with adjoints
|-
! colspan="4" | sfcdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|-
| ''file '' || '''dat=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|}

A simple demonstration of the program can be made taking advantage that the complex-to-complex FFT is a linear operator:

<bash>
sfspike n1=100 | sfrtoc > spike.rsf
< spike.rsf sffft axis=1 pad=1 > spike2.rsf
sfcdottest sffft mod=spike.rsf dat=spike2.rsf axis=1 pad=1
</bash>

The output should show values identical down to the last decimal:

<pre>
sfcdottest: L[m]*d=(3.73955,-1.86955)
sfcdottest: L'[d]*m=(3.73955,-1.86955)
</pre>

==sfcmplx==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Create a complex dataset from its real and imaginary parts.
|-
! colspan="4" | sfcmplx > cmplx.rsf real.rsf imag.rsf
|-
| colspan="4" | There has to be only two input files specified and no additional parameters.
|}

<tt>sfcmplx</tt> simply creates a complex dataset from its real and
imaginary parts. The reverse operation can be accomplished with
<tt>sfreal</tt> and <tt>sfimag</tt>.
Example of <tt>sfcmplx</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcmplx one.rsf one.rsf > cmplx.rsf
bash$ sfin cmplx.rsf
cmplx.rsf:
in="/tmp/cmplx.rsf@"
esize=8 type=complex form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 48 bytes
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cmplx.c?view=markup system/main/cmplx.c]====
The program flow is simple. First, get the names of the input files.
<c>
/* the first two non-parameters are real and imaginary files */
for (i=1; i< argc; i++) {
if (NULL == strchr(argv[i],'=')) {
if (NULL == real) {
real = sf_input (argv[i]);
} else {
imag = sf_input (argv[i]);
break;
}
}
}
if (NULL == imag) {
if (NULL == real) sf_error ("not enough input");
/* if only one input, real is in stdin */
imag = real;
real = sf_input("in");
}
</c>

The main part of the program reads the real and imaginary parts buffer by buffer and assembles and writes out the complex input.
<c>
for (nleft= (size_t) (rsize*resize); nleft > 0; nleft -= nbuf) {
nbuf = (BUFSIZ < nleft)? BUFSIZ: nleft;
sf_charread(rbuf,nbuf,real);
sf_charread(ibuf,nbuf,imag);
for (i=0; i < nbuf; i += resize) {
memcpy(cbuf+2*i, rbuf+i,(size_t) resize);
memcpy(cbuf+2*i+resize,ibuf+i,(size_t) resize);
}
sf_charwrite(cbuf,2*nbuf,cmplx);
}
</c>
==sfconjgrad==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic conjugate-gradient solver for linear inversion
|-
! colspan="4" | sfconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
|-
| ''int '' || '''niter=1''' || || number of iterations
|}

<tt>sfconjgrad</tt> is a generic program for least-squares linear
inversion with the [http://en.wikipedia.org/wiki/Conjugate_gradient_method conjugate-gradient method]. Suppose you have an
executable program <tt><prog></tt> that takes an RSF file from the
standard input and produces an RSF file in the standard output. It may
take any number of additional parameters but one of them must be
<tt>adj=</tt> that sets the forward (<tt>adj=0</tt>) or adjoint
(<tt>adj=1</tt>) operations. The program <tt><prog></tt> is typically
an RSF program but it could be anything (a script, a multiprocessor
MPI program, etc.) as long as it implements a linear operator
<math>\mathbf{L}</math> and its adjoint. There are no restrictions on the data
size or shape. You can easily test the adjointness with
<tt>sfdottest</tt>. The <tt>sfconjgrad</tt> program searches for a
vector <math>\mathbf{m}</math> that minimizes the least-square misfit
<math>\|\mathbf{d - L\,m}\|^2</math> for the given input data vector <math>\mathbf{d}</math>.

The pseudocode for <tt>sfconjgrad</tt> is given at the end of the [http://www.reproducibility.org/RSF/book/gee/lsq/paper.pdf "Model fitting with least squares" chapter] of ''Imaging Estimation by Example'' by Jon Claerbout, with the earliest form published in [http://sepwww.stanford.edu/data/media/public/oldreports/sep48/48_25.pdf "Conjugate Gradient Tutorial"] (SEP-48, 1986, same author). A simple toy implementation with a small matrix shows that this is algorithm produces the same steps as the algorithm described in equations 45-49 of [http://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf "An introduction to the Conjugate Gradient Method Without the Agonizing Pain"] by J.R. Shewchuk, 1994, when the equation <math>A^T A x = A^T b</math> (in Shewchuk's notation) is solved. Multiplying with the transpose ensures a correct solution even when matrix A is square but not symmetric, or not square at all. The program [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad] implements this algorithm for the case when inputs are complex.

Here is an example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
The <tt>sfdottest</tt> program can perform the dot product test to
check that the adjoint mode works correctly.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=5.28394
sfdottest: L'[d]*m=5.28394
</pre>
Your numbers may be different because <tt>sfdottest</tt> generates new
random input on each run.
Next, let us make some random data with <tt>sfnoise</tt>.
<pre>
bash$ sfnoise seed=2005 rep=y < vec.rsf > dat.rsf
</pre>
and try to invert the filtering operation using <tt>sfconjgrad</tt>:
<pre>
bash$ sfconjgrad sfhelicon filt=flt.rsf lag=lag.rsf mod=vec.rsf < dat.rsf > mod.rsf niter=10
sfconjgrad: iter 1 of 10
sfconjgrad: grad=3253.65
sfconjgrad: iter 2 of 10
sfconjgrad: grad=289.421
sfconjgrad: iter 3 of 10
sfconjgrad: grad=92.3481
sfconjgrad: iter 4 of 10
sfconjgrad: grad=36.9417
sfconjgrad: iter 5 of 10
sfconjgrad: grad=18.7228
sfconjgrad: iter 6 of 10
sfconjgrad: grad=11.1794
sfconjgrad: iter 7 of 10
sfconjgrad: grad=7.26941
sfconjgrad: iter 8 of 10
sfconjgrad: grad=5.15945
sfconjgrad: iter 9 of 10
sfconjgrad: grad=4.23055
sfconjgrad: iter 10 of 10
sfconjgrad: grad=3.57495
</pre>
The output shows that, in 10 iterations, the norm of the gradient vector decreases by almost 1000.
We can check the residual misfit before
<pre>
bash$ < dat.rsf sfattr want=norm
norm value = 49.7801
</pre>
and after
<pre>
bash$ sfhelicon filt=flt.rsf lag=lag.rsf < mod.rsf | sfadd scale=1,-1 dat.rsf | sfattr want=norm
norm value = 5.73563
</pre>
In 10 iterations, the misfit decreased by an order of magnitude. The
result can be improved by running the program for more iterations.

An equivalent implementation for complex-valued inputs is [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad]. A simple, lightweight Python implementation can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/user/fomels/conjgrad.py?view=markup $PYTHONPATH/rsf/conjgrad.py].

==sfcp==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Copy or move a dataset.
|-
! colspan="4" | sfcp in.rsf out.rsf
|-
| colspan="4" | sfcp - copy, sfmv - move. Mimics standard Unix commands.
|}

The <tt>sfcp</tt> and <tt>sfmv</tt> command imitate the Unix
<tt>cp</tt> and <tt>mv</tt> commands and serve for copying and moving
RSF files. Example:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcp one.rsf two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cp.c?view=markup system/main/cp.c]====
First, we look for the two first command-line arguments that don't
have the "=" character in them and consider them as the names of the
input and the output files.
<c>
/* the first two non-parameters are in and out files */
for (i=1; i< argc; i++) {
if (NULL == strchr(argv[i],'=')) {
if (NULL == in) {
infile = argv[i];
in = sf_input (infile);
} else {
out = sf_output (argv[i]);
break;
}
}
}
if (NULL == in || NULL == out)
sf_error ("not enough input");
</c>

Next, we use library functions sf_cp and sf_rm to do the actual work.
<c>
sf_cp(in,out);
if (NULL != strstr (sf_getprog(),"mv"))
sf_rm(infile,false,false,false);
</c>

==sfcut==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Zero a portion of the dataset.
|-
! colspan="4" | sfcut < in.rsf > out.rsf verb=n [j1=1 j2=1 ... f1=0 f2=0 ... n1=n1 n2=n2 ... max1= max2= ... min1= min2= ...]
|-
| colspan="4" | jN defines the jump in N-th dimension fN is the window start nN is the window size minN and maxN is the maximum and minimum in N-th dimension Reverse of window.
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

The <tt>sfcut</tt> command is related to <tt>sfwindow</tt> and has the same
set of arguments only instead of extracting the selected window, it fills it
with zeroes. The size of the input data is preserved.
Examples:
<pre>
bash$ sfspike n1=5 n2=5 > in.rsf
bash$ < in.rsf sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ < in.rsf sfcut n1=2 f1=1 n2=3 f2=2 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 0 0 1 1
15: 1 0 0 1 1
20: 1 0 0 1 1
bash$ < in.rsf sfcut j1=2 | sfdisfil
0: 0 1 0 1 0
5: 0 1 0 1 0
10: 0 1 0 1 0
15: 0 1 0 1 0
20: 0 1 0 1 0
</pre>

==sfdd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert between different formats.
|-
! colspan="4" | sfdd < in.rsf > out.rsf line=8 form= type= format=
|-
| ''string '' || '''form=''' || || ascii, native, xdr
|-
| ''string '' || '''format=''' || || Element format (for conversion to ASCII)
|-
| ''int '' || '''line=8''' || || Number of numbers per line (for conversion to ASCII)
|-
| ''string '' || '''type=''' || || int, float, complex
|}

The <tt>sfdd</tt> program is used to change either the form (<tt>ascii</tt>,
<tt>xdr</tt>, <tt>native</tt>) or the type (<tt>complex</tt>, <tt>float</tt>,
<tt>int</tt>, <tt>char</tt>) of the input dataset.
In the example below, we create a plain text (ASCII) file with numbers and
then use <tt>sfdd</tt> to generate an RSF file in <tt>xdr</tt> form with
<tt>complex</tt> numbers.
<pre>
bash$ cat test.txt
1 2 3 4 5 6
bash$ echo n1=6 data_format=ascii_int in=test.txt > test.rsf
bash$ sfin test.rsf
test.rsf:
in="test.txt"
esize=0 type=int form=ascii
n1=6 d1=? o1=?
6 elements
bash$ sfdd < test.rsf form=xdr type=complex > test2.rsf
bash$ sfin test2.rsf
test2.rsf:
in="/tmp/test2.rsf@"
esize=8 type=complex form=xdr
n1=3 d1=? o1=?
3 elements 24 bytes
bash$ sfdisfil < test2.rsf
0: 1, 2i 3, 4i 5, 6i
</pre>
To learn more about the RSF data format, consult the [[Guide to RSF file format| guide to RSF format]].

==sfdisfil==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Print out data values.
|-
! colspan="4" | sfdisfil < in.rsf number=y col=0 format= header= trailer=
|-
| colspan="4" | Alternatively, use sfdd and convert to ASCII form.
|-
| ''int '' || '''col=0''' || || Number of columns.
:The default depends on the data type:
:10 for int and char,
:5 for float,
:3 for complex
|-
| ''string '' || '''format=''' || || Format for numbers (printf-style).
:The default depends on the data type: "%4d " for int and char, "%13.4g" for float, "%10.4g,%10.4gi" for complex
|-
| ''string '' || '''header=''' || || Optional header string to output before data
|-
| ''bool '' || '''number=y''' || [y/n] || If number the elements
|-
| ''string '' || '''trailer=''' || || Optional trailer string to output after data
|}

The <tt>sfdisfil</tt> program simply dumps the data contents to the standard
output in a text form. It is used mostly for debugging purposes to quickly
examine RSF files. Here is an example:
<pre>
bash$ sfmath o1=0 d1=2 n1=12 output=x1 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 2 4 6 8
5: 10 12 14 16 18
10: 20 22
</pre>
The output format is easily configurable.
<pre>
bash$ < test.rsf sfdisfil col=6 number=n format="%5.1f"
0.0 2.0 4.0 6.0 8.0 10.0
12.0 14.0 16.0 18.0 20.0 22.0
</pre>
Along with <tt>sfdd</tt>, <tt>sfdisfil</tt> provides a simple way to convert
RSF data to an ASCII form.

==sfdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for linear operators with adjoints
|-
! colspan="4" | sfdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|}

<tt>sfdottest</tt> is a generic dot-product test program for testing
linear operators. Suppose there is an executable program
<tt><prog></tt> that takes an RSF file from the standard input and
produces an RSF file in the standard output. It may take any number of
additional parameters but one of them must be <tt>adj=</tt> that sets
the forward (<tt>adj=0</tt>) or adjoint (<tt>adj=1</tt>) operations.
The program <tt><prog></tt> is typically an RSF program but it could
be anything (a script, a multiprocessor MPI program, etc.) as long as
it implements a linear operator <math>\mathbf{L}</math> and its adjoint
<math>\mathbf{L}^T</math>. The <tt>sfdottest</tt> program is testing the equality
<center><math>
d^T\,L\,m = m^T\,L^T\,d
</math></center>
by using random vectors <math>\mathbf{m}</math> and <math>\mathbf{d}</math>. You can invoke it with
<pre>
bash$ sfdottest <prog> [optional aruments] mod=mod.rsf dat=dat.rsf
</pre>
where <tt>mod.rsf</tt> and <tt>dat.rsf</tt> are RSF files that
represent vectors from the model and data spaces. Pay attention to the
dimension and size of these vectors! If the program does not respond
for a very long time, it is quite possible that the dimension and size
of the vectors are inconsistent with the requirement of the program to be
tested. <tt>sfdottest</tt>
does not create any temporary files and does not have any restrictive
limitations on the size of the vectors.
Here is an example. We first setup a vector with 100 elements using
<tt>sfspike</tt> and then run <tt>sfdottest</tt> to test the
<tt>sfcausint</tt> program. <tt>sfcausint</tt> implements a linear
operator of causal integration and its adjoint, the anti-causal
integration.
<pre>
bash$ sfspike n1=100 > vec.rsf
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=1410.2
sfdottest: L'[d]*m=1410.2
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=1165.87
sfdottest: L'[d]*m=1165.87
</pre>
The numbers are different on subsequent runs because of changing
seed in the random number generator.
Here is a somewhat more complicated example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
Now the <tt>sfdottest</tt> program can perform the dot product test.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=8.97375
sfdottest: L'[d]*m=8.97375
</pre>
Here is the same program tested in the inverse filtering mode:
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf div=y
sfdottest: L[m]*d=15.0222
sfdottest: L'[d]*m=15.0222
</pre>

==sfget==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Output parameters from the header.
|-
! colspan="4" | sfget < in.rsf parform=y par1 par2 ...
|-
| ''bool '' || '''parform=y''' || [y/n] || If y, print out parameter=value. If n, print out value.
|}

The <tt>sfget</tt> program extracts a parameter value from an RSF file. It is
useful mostly for scripting. Here is, for example, a quick calculation of the
maximum value on the first axis in an RSF dataset (the output of
<tt>sfspike</tt>) using the standard Unix <tt>bc</tt> calculator.
<pre>
bash$ ( sfspike n1=100 | sfget n1 d1 o1; echo "o1+(n1-1)*d1" ) | bc
.396
</pre>
See also <tt>sfput</tt>.

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/get.c?view=markup system/main/get.c]====
The implementation is trivial. Loop through all command-line parameters that contain
the "=" character.
<c>
for (i = 1; i < argc; i++) {
key = argv[i];
if (NULL != strchr(key,'=')) continue;
</c>

Get the parameter value (as string) and output it as either
<tt>key=value</tt> or <tt>value</tt>, depending on the
<tt>parform</tt> parameter.
<c>
string = sf_histstring(in,key);
if (NULL == string) {
sf_warning("No key %s",key);
} else {
if (parform) printf ("%s=",key);
printf("%s\n",string);
}
</c>

==sfheadercut==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Zero a portion of a dataset based on a header mask.
|-
! colspan="4" | sfheadercut mask=head.rsf < in.rsf > out.rsf
|-
| colspan="4" | The input data is a collection of traces n1xn2, mask is an integer array of size n2.
|}

<tt>sfheadercut</tt> is close to <tt>sfheaderwindow</tt> but instead
of windowing the dataset, it fills the traces specified by the header
mask with zeroes. The size of the input data is preserved.
Here is an example of using <tt>sfheaderwindow</tt> for
zeroing every other trace in the input file. First, let us create
an input file with ten traces:
<pre>
bash$ sfmath n1=5 n2=10 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
35: 8 8 8 8 8
40: 9 9 9 9 9
45: 10 10 10 10 10
</pre>
Next, we can create a mask with alternating ones and zeros using
<tt>sfinterleave</tt>.
<pre>
bash$ sfspike n1=5 mag=1 | sfdd type=int > ones.rsf
bash$ sfspike n1=5 mag=0 | sfdd type=int > zeros.rsf
bash$ sfinterleave axis=1 ones.rsf zeros.rsf > mask.rsf
bash$ sfdisfil < mask.rsf
0: 1 0 1 0 1 0 1 0 1 0
</pre>
Finally, <tt>sfheadercut</tt> zeros the input traces.
<pre>
bash$ sfheadercut < input.rsf mask=mask.rsf > output.rsf
bash$ sfdisfil < output.rsf
0: 1 1 1 1 1
5: 0 0 0 0 0
10: 3 3 3 3 3
15: 0 0 0 0 0
20: 5 5 5 5 5
25: 0 0 0 0 0
30: 7 7 7 7 7
35: 0 0 0 0 0
40: 9 9 9 9 9
45: 0 0 0 0 0
</pre>

==sfheadersort==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Sort a dataset according to a header key.
|-
! colspan="4" | sfheadersort < in.rsf > out.rsf head=
|-
| ''string '' || '''head=''' || || header file
|}

<tt>sfheadersort</tt> is used to sort traces in the input file
according to trace header information.
Here is an example of using
<tt>sfheadersort</tt> for randomly shuffling traces in the input
file. First, let us create an input file with seven traces:
<pre>
bash$ sfmath n1=5 n2=7 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
</pre>
Next, we can create a random file with seven header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=7 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
0: 0.05256 -0.2879 0.1487 0.4097 0.1548
5: 0.4501 0.2836
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally, we
apply <tt>sfheadersort</tt> to shuffle the input traces.
<pre>
bash$ < input.rsf sfheadersort head=random.rsf > output.rsf
bash$ < output.rsf sfdisfil
0: 2 2 2 2 2
5: 1 1 1 1 1
10: 3 3 3 3 3
15: 5 5 5 5 5
20: 7 7 7 7 7
25: 4 4 4 4 4
30: 6 6 6 6 6
</pre>
As expected, the order of traces in the output file corresponds to the
order of values in the header. Thanks to the separation between
headers and data, the operation of <tt>sfheadersort</tt> is optimally
efficient. It first sorts the headers and only then accesses the data,
reading each data trace only once.

==sfheaderwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a dataset based on a header mask.
|-
! colspan="4" | sfheaderwindow mask=head.rsf < in.rsf > out.rsf
|-
| colspan="4" | The input data is a collection of traces n1xn2, mask is an integer array os size n2, windowed is n1xm2, where m2 is the number of nonzero elements in mask.
|}

<tt>sfheaderwindow</tt> is used to window traces in the input file
according to trace header information.
Here is an example of using <tt>sfheaderwindow</tt> for randomly
selecting part of the traces in the input file. First, let us create
an input file with ten traces:
<pre>
bash$ sfmath n1=5 n2=10 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
35: 8 8 8 8 8
40: 9 9 9 9 9
45: 10 10 10 10 10
</pre>
Next, we can create a random file with ten header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=10 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
0: -0.005768 0.02258 -0.04331 -0.4129 -0.3909
5: -0.03582 0.4595 -0.3326 0.498 -0.3517
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally,
we apply <tt>sfheaderwindow</tt> to window the input traces selecting
only those for which the header is greater than zero.
<pre>
bash$ < random.rsf sfmask min=0 > mask.rsf
bash$ < mask.rsf sfdisfil
0: 0 1 0 0 0 0 1 0 1 0
bash$ < input.rsf sfheaderwindow mask=mask.rsf > output.rsf
bash$ < output.rsf sfdisfil
0: 2 2 2 2 2
5: 7 7 7 7 7
10: 9 9 9 9 9
</pre>
In this case, only three traces are selected for the output. Thanks to
the separation between headers and data, the operation of
<tt>sfheaderwindow</tt> is optimally efficient.

==sfin==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display basic information about RSF files.
|-
! colspan="4" | sfin info=y check=2. trail=y file1.rsf file2.rsf ...
|-
| colspan="4" | n1,n2,... are data dimensions o1,o2,... are axis origins d1,d2,... are axis sampling intervals label1,label2,... are axis labels unit1,unit2,... are axis units
|-
| ''float '' || '''check=2.''' || || Portion of the data (in Mb) to check for zero values.
|-
| ''bool '' || '''info=y''' || [y/n] || If n, only display the name of the data file.
|-
| ''bool '' || '''trail=y''' || [y/n] || If n, skip trailing dimensions of one
|}

<tt>sfin</tt> is one of the most useful programs for operating with
RSF files. It produces quick information on the file hypercube
dimensions and checks the consistency of the associated data file.
Here is an example. Let us create an RSF file and examine it with <tt>sfin</tt>.
<pre>
bash$ sfspike n1=100 n2=20 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/tmp/spike.rsf@"
esize=4 type=float form=native
n1=100 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
2000 elements 8000 bytes
</pre>
<tt>sfin</tt> reports the following information:

*location of the data file (<tt>/tmp/spike.rsf\@</tt>)
*element size (4 bytes)
*element type (floating point)
*element form (native)
*hypercube dimensions (100 by 20)
*axes scale (0.004 and 0.1)
*axes origin (0 and 0)
*axes labels
*axes units
*total number of elements
*total number of bytes in the data file
Suppose that the file got corrupted by a buggy program and reports
incorrect dimensions. The <tt>sfin</tt> program should be able to
catch the discrepancy.
<pre>
bash$ echo n2=100 >> spike.rsf
bash$ sfin spike.rsf > /dev/null
sfin: Actually 8000 bytes, 20% of expected.
</pre>
<tt>sfin</tt> also checks the first records in the file for zeros.
<pre>
bash$ sfspike n1=100 n2=100 k2=99 > spike2.rsf
bash$ sfin spike2.rsf >/dev/null
sfin: The first 32768 bytes are all zeros
</pre>
The number of bytes to check is adjustable
<pre>
bash$ sfin spike2.rsf check=0.01 >/dev/null
sfin: The first 16384 bytes are all zeros
</pre>
You can also output only the location of the data file. This is
sometimes handy in scripts.
<pre>
bash$ sfin spike.rsf spike2.rsf info=n
/tmp/spike.rsf@ /tmp/spike2.rsf@
</pre>
An alternative is to use <tt>sfget</tt>, as follows:
<pre>
bash$ sfget parform=n in < spike.rsf
/tmp/spike.rsf@
</pre>
To actually eliminate annoying trailing dimensions of length one (not just stop displaying them with <tt>trail=n</tt>), you may use <tt>sed</tt>. Example for eliminating axis 6:
<bash>
sed -i 's/n6=1//g' file.rsf
</bash>

==sfinterleave==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Combine several datasets by interleaving.
|-
! colspan="4" | sfinterleave > out.rsf axis=3 [< file0.rsf] file1.rsf file2.rsf ...
|-
| ''int '' || '''axis=3''' || || Axis for interleaving
|}

<tt>sfinterleave</tt> combines two or more datasets by interleaving them on one
of the axes. Here is a quick example:
<pre>
bash$ sfspike n1=5 n2=5 > one.rsf
bash$ sfdisfil < one.rsf
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ sfscale < one.rsf dscale=2 > two.rsf
bash$ sfdisfil < two.rsf
0: 2 2 2 2 2
5: 2 2 2 2 2
10: 2 2 2 2 2
15: 2 2 2 2 2
20: 2 2 2 2 2
bash$ sfinterleave one.rsf two.rsf axis=1 | sfdisfil
0: 1 2 1 2 1
5: 2 1 2 1 2
10: 1 2 1 2 1
15: 2 1 2 1 2
20: 1 2 1 2 1
25: 2 1 2 1 2
30: 1 2 1 2 1
35: 2 1 2 1 2
40: 1 2 1 2 1
45: 2 1 2 1 2
bash$ sfinterleave < one.rsf two.rsf axis=2 | sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 1 1 1 1 1
15: 2 2 2 2 2
20: 1 1 1 1 1
25: 2 2 2 2 2
30: 1 1 1 1 1
35: 2 2 2 2 2
40: 1 1 1 1 1
45: 2 2 2 2 2
</pre>

==sfmask==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Create a mask.
|-
! colspan="4" | sfmask < in.rsf > out.rsf min=-FLT_MAX max=+FLT_MAX
|-
| colspan="4" | Mask is an integer data with ones and zeros. Ones correspond to input values between min and max. The output can be used with sfheaderwindow.
|-
| ''float '' || '''max=+FLT_MAX''' || || maximum header value
|-
| ''float '' || '''min=-FLT_MAX''' || || minimum header value
|}

<tt>sfmask</tt> creates an integer output of ones and zeros comparing
the values of the input data to specified <tt>min=</tt> and
<tt>max=</tt> parameters. It is useful for <tt>sfheaderwindow</tt> and
in many other applications. Here is a quick example:
<pre>
bash$ sfmath n1=10 output="sin(x1)" > sin.rsf
bash$ < sin.rsf sfdisfil
0: 0 0.8415 0.9093 0.1411 -0.7568
5: -0.9589 -0.2794 0.657 0.9894 0.4121
bash$ < sin.rsf sfmask min=-0.5 max=0.5 | sfdisfil
0: 1 0 0 1 0 0 1 0 0 1
</pre>

==sfmath==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Mathematical operations on data files.
|-
! colspan="4" | sfmath > out.rsf n#= d#=(1,1,...) o#=(0,0,...) label#= unit#= type= label= unit= output=
|-
| colspan="4" | Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs, erf, erfc (for float data), arg, conj, real, imag (for complex data). sfmath will work on float or complex data, but all the input and output files must be of the same data type. An alternative to sfmath is sfadd, which may be more efficient, but is less versatile. Examples: sfmath x=file1.rsf y=file2.rsf power=file3.rsf output='sin((x+2*y)^power)' > out.rsf sfmath < file1.rsf tau=file2.rsf output='exp(tau*input)' > out.rsf sfmath n1=100 type=complex output="exp(I*x1)" > out.rsf Arguments which are not treated as variables in mathematical expressions: datapath=, type=, out= See also: sfheadermath.
|-
| ''float '' || '''d#=(1,1,...)''' || || sampling on #-th axis
|-
| ''string '' || '''label=''' || || data label
|-
| ''string '' || '''label#=''' || || label on #-th axis
|-
| ''largeint'' || '''n#=''' || || size of #-th axis
|-
| ''float '' || '''o#=(0,0,...)''' || || origin on #-th axis
|-
| ''string '' || '''output=''' || || Mathematical description of the output
|-
| ''string '' || '''type=''' || || output data type [float,complex]
|-
| ''string '' || '''unit=''' || || data unit
|-
| ''string '' || '''unit#=''' || || unit on #-th axis
|}

<tt>sfmath</tt> is a versatile program for mathematical operations
with RSF files. It can operate with several input files, all of the
same dimensions and data type. The data type can be real (floating
point) or complex. Here is an example that demonstrates several
features of <tt>sfmath</tt>.
<pre>
bash$ sfmath n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5 \
output="x2*(8+sin(6*x1+x2/10))" > rad.rsf
bash$ < rad.rsf sfrtoc | sfmath output="input*exp(I*x1)" > rose.rsf
bash$ < rose.rsf sfgraph title=Rose screenratio=1 wantaxis=n | sfpen
</pre>
The first line creates a 2-D dataset that consists of 40 traces 629
samples each. The values of the data are computed with the formula
"x2*(8+sin(6*x1+x2/10))", where <tt>x1</tt> refers to the
coordinate on the first axis, and <tt>x2</tt> is the coordinate of the
second axis. In the second line, we convert the data from real to
complex using <tt>sfrtoc</tt> and produce a complex dataset using
formula "input*exp(I*x1)", where <tt>input</tt> refers to the
input file. Finally, we plot the complex data as a collection of
parametric curves using <tt>sfgraph</tt> and display the result using
<tt>sfpen</tt>. The plot appearing on your screen should look similar
to the figure.
[[Image:rose.png|frame|center|This figure was created with <tt>sfmath</tt>.]]
One possible alternative to the second line above is
<pre>
bash$ < rad.rsf sfmath output=x1 > ang.rsf
bash$ sfmath r=rad.rsf a=ang.rsf output="r*cos(a)" > cos.rsf
bash$ sfmath r=rad.rsf a=ang.rsf output="r*sin(a)" > sin.rsf
bash$ sfcmplx cos.rsf sin.rsf > rose.rsf
</pre>
Here we refer to input files by names (<tt>r</tt> and <tt>a</tt>) and combine the names in a formula.

Functions can be nested and combined, and variable names, as well as the the <tt>input</tt> keyword may be combined with the axes keywords <tt>x1</tt>, <tt>x2</tt>, etc. Here is an example that shifts a wavelet -0.4s to t=0, computes the frequency-domain complex square root (equivalent to the convolutional square root in time), and shifts the result back to t=0.4s:
<bash>
pi=3.14159265
tshift=0.4

sfspike n1=256 k1=101 |\
sfbandpass flo=4 fhi=30 |\
sffft1 opt=n sym=y |\
sfmath output="sqrt(input*exp(2*$pi*$tshift*x1*I))*exp(-2*$pi*$tshift*x1*I)" |\
sffft1 opt=n sym=y inv=y |\
sfgraph |\
sfpen
</bash>

==sfpad==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Pad a dataset with zeros.
|-
! colspan="4" | sfpad < in.rsf > out.rsf beg#=0 end#=0 n#=
|-
| colspan="4" | n#out is equivalent to n#, both of them overwrite end#.
|-
| ''int '' || '''beg#=0''' || || the number of zeros to add before the beginning of #-th axis
|-
| ''int '' || '''end#=0''' || || the number of zeros to add after the end of #-th axis
|-
| ''int '' || '''n#=''' || || the output length of #-th axis - padding at the end
|}

<tt>sfpad</tt> increases the dimensions of the input dataset by padding
the data with zeroes. Here are some simple examples.
<pre>
bash$ sfspike n1=5 n2=3 > one.rsf
bash$ sfdisfil < one.rsf
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
bash$ < one.rsf sfpad n2=5 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 0 0 0 0 0
20: 0 0 0 0 0
bash$ < one.rsf sfpad beg2=2 | sfdisfil
0: 0 0 0 0 0
5: 0 0 0 0 0
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ < one.rsf sfpad beg2=1 end2=1 | sfdisfil
0: 0 0 0 0 0
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 0 0 0 0 0
bash$ < one.rsf sfwindow n1=3 | sfpad n1=5 n2=5 beg1=1 beg2=1 | sfdisfil
0: 0 0 0 0 0
5: 0 1 1 1 0
10: 0 1 1 1 0
15: 0 1 1 1 0
20: 0 0 0 0 0
</pre>
You can use <tt>sfcat</tt> to pad data with values other than zeroes.

==sfput==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Input parameters into a header.
|-
! colspan="4" | sfput < in.rsf > out.rsf [parameter=value list]
|}

<tt>sfput</tt> is a very simple program. It simply appends parameters
from the command line to the output RSF file. One can achieve similar
results with editing the file by hand or with standard Unix utilities like
<tt>sed</tt> and <tt>echo</tt>. <tt>sfput</tt> is sometimes more
convenient because it handles input/output operations similarly to
other Madagascar programs.
<pre>
bash$ sfspike n1=10 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/tmp/spike.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
10 elements 40 bytes
bash$ sfput < spike.rsf d1=25 label1=Depth unit1=m > spike2.rsf
bash$ sfin spike2.rsf
spike2.rsf:
in="/tmp/spike2.rsf@"
esize=4 type=float form=native
n1=10 d1=25 o1=0 label1="Depth" unit1="m"
10 elements 40 bytes
</pre>

==sfreal==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
|-
! colspan="4" | sfreal < cmplx.rsf > real.rsf
|}

<tt>sfreal</tt> extracts the real part of a complex type dataset. The
imaginary part can be extracted with <tt>sfimag</tt>, an the real
and imaginary part can be combined together with <tt>sfcmplx</tt>.
Here is a simple example. Let us first create a complex dataset
with <tt>sfmath</tt>
<pre>
bash$ sfmath n1=10 type=complex output="(2+I)*x1" > cmplx.rsf
bash$ fdisfil < cmplx.rsf
0: 0, 0i 2, 1i 4, 2i
3: 6, 3i 8, 4i 10, 5i
6: 12, 6i 14, 7i 16, 8i
9: 18, 9i
</pre>
Extracting the real part with <tt>sfreal</tt>:
<pre>
bash$ sfreal < cmplx.rsf | sfdisfil
0: 0 2 4 6 8
5: 10 12 14 16 18
</pre>
Extracting the imaginary part with <tt>sfimag</tt>:
<pre>
bash$ sfimag < cmplx.rsf | sfdisfil
0: 0 1 2 3 4
5: 5 6 7 8 9
</pre>

==sfreverse==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Reverse one or more axes in the data hypercube.
|-
! colspan="4" | sfreverse < in.rsf > out.rsf which=-1 verb=false memsize=sf_memsize() opt=
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''string '' || '''opt=''' || || If y, change o and d parameters on the reversed axis;
:if i, don't change o and d
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|-
| ''int '' || '''which=-1''' || || Which axis to reverse.
:To reverse a given axis, start with 0,
:add 1 to number to reverse n1 dimension,
:add 2 to number to reverse n2 dimension,
:add 4 to number to reverse n3 dimension, etc.
:Thus, which=7 would reverse the first three dimensions,
:which=5 just n1 and n3, etc.
:which=0 will just pass the input on through unchanged.
|}
Here is an example of using <tt>sfreverse</tt>. First, let us create a
2-D dataset.
<pre>
bash$ sfmath n1=5 d1=1 n2=3 d2=1 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
</pre>
Reversing the first axis:
<pre>
bash$ < test.rsf sfreverse which=1 | sfdisfil
0: 4 3 2 1 0
5: 5 4 3 2 1
10: 6 5 4 3 2
</pre>
Reversing the second axis:
<pre>
bash$ < test.rsf sfreverse which=2 | sfdisfil
0: 2 3 4 5 6
5: 1 2 3 4 5
10: 0 1 2 3 4
</pre>
Reversing both the first and the second axis:
<pre>
bash$ < test.rsf sfreverse which=3 | sfdisfil
0: 2 3 4 5 6
5: 1 2 3 4 5
10: 0 1 2 3 4
</pre>
As you can see, the <tt>which=</tt> parameter controls the axes that are
being reversed by encoding them into one number.
When an axis is reversed, what happens with its axis origin and
sampling parameters? This behavior is controlled by <tt>opt=</tt>. In
our example,
<pre>
bash$ < test.rsf sfget n1 o1 d1
n1=5
o1=0
d1=1
bash$ < test.rsf sfreverse which=1 | sfget o1 d1
o1=4
d1=-1
</pre>
The default behavior (equivalent to <tt>opt=y</tt>) puts the origin
<tt>o1</tt> at the end of the axis and reverses the sampling parameter
<tt>d1</tt>. Using <tt>opt=n</tt> preserves the sampling but reverses
the origin.
<pre>
bash$ < test.rsf sfreverse which=1 opt=n | sfget o1 d1
o1=-4
d1=1
</pre>
Using <tt>opt=i</tt> preserves both the sampling and the origin while
reversing the axis.
<pre>
bash$ < test.rsf sfreverse which=1 opt=i | sfget o1 d1
o1=0
d1=1
</pre>
One of the three possible behaviors may be desirable depending on the
application.

==sfrm==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Remove RSF files together with their data.
|-
! colspan="4" | sfrm file1.rsf [file2.rsf ...] [-i] [-v] [-f]
|-
| colspan="4" | Mimics the standard Unix rm command. See also: sfmv, sfcp.
|}

<tt>sfrm</tt> is a program for removing RSF files. Its arguments mimic
the arguments of the standard Unix <tt>rm</tt> utility: <tt>-v</tt>
for verbosity, <tt>-i</tt> for interactive inquiry, <tt>-f</tt> for
force removal of suspicious files. Unlike the Unix <tt>rm</tt>,
<tt>sfrm</tt> removes both the RSF header files and the binary files
that the headers point to.
Example:
<pre>
bash$ sfspike n1=10 > spike.rsf datapath=./
bash$ sfget in < spike.rsf
in=./spike.rsf@
bash$ ls spike*
spike.rsf spike.rsf@
bash$ sfrm -v spike.rsf
sfrm: sf_rm: Removing header spike.rsf
sfrm: sf_rm: Removing data ./spike.rsf@
bash$ ls spike*
ls: No match.
</pre>
==sfrotate==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Rotate a portion of one or more axes in the data hypercube.
|-
! colspan="4" | sfrotate < in.rsf > out.rsf verb=n memsize=sf_memsize() rot#=(0,0,...)
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''int '' || '''rot#=(0,0,...)''' || || length of #-th axis that is moved to the end
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

<tt>sfrotate</tt> modifies the input dataset by splitting it into
parts and putting the parts back in a different order. Here is a quick example.
<pre>
bash$ sfmath n1=5 d1=1 n2=3 d2=1 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
</pre>
Rotating the first axis by putting the last two columns in front:
<pre>
bash$ < test.rsf sfrotate rot1=2 | sfdisfil
0: 3 4 0 1 2
5: 4 5 1 2 3
10: 5 6 2 3 4
</pre>
Rotating the second axis by putting the last row in front:
<pre>
bash$ < test.rsf sfrotate rot2=1 | sfdisfil
0: 2 3 4 5 6
5: 0 1 2 3 4
10: 1 2 3 4 5
</pre>
Rotating both the first and the second axis:
<pre>
bash$ < test.rsf sfrotate rot1=3 rot2=1 | sfdisfil
0: 4 5 6 2 3
5: 2 3 4 0 1
10: 3 4 5 1 2
</pre>
The transformation is shown schematically in Figure~(fig:rotate).
[[Image:rotate.png|frame|center|Schematic transformation of data with <tt>sfrotate</tt>.]]

==sfrtoc==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert real data to complex (by adding zero imaginary part).
|-
! colspan="4" | sfrtoc < real.rsf > cmplx.rsf
|-
| colspan="4" | See also: sfcmplx
|}
The input to <tt>sfrtoc</tt> can be any <tt>type=float</tt> dataset:
<pre>
bash$ sfspike n1=10 n2=20 n3=30 >real.rsf
bash$ sfin real.rsf
real.rsf:
in="/var/tmp/real.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
</pre>
The output dataset will have <tt>type=complex</tt>, and its binary will be twice the size of the input:
<pre>
bash$ <real.rsf sfrtoc >complex.rsf
bash$ sfin complex.rsf
complex.rsf:
in="/var/tmp/complex.rsf@"
esize=8 type=complex form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 48000 bytes
</pre>

==sfscale==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Scale data.
|-
! colspan="4" | sfscale < in.rsf > out.rsf axis=0 rscale=0. dscale=1.
|-
| colspan="4" | To scale by a constant factor, you can also use sfmath or sfheadermath.
|-
| ''int '' || '''axis=0''' || || Scale by maximum in the dimensions up to this axis.
|-
| ''float '' || '''dscale=1.''' || || Scale by this factor (works if rscale=0)
|-
| ''float '' || '''rscale=0.''' || || Scale by this factor.
|}
<tt>sfscale</tt> scales the input dataset by a factor. Here
are some simple examples. First, let us create a test dataset.
<pre>
bash$ sfmath n1=5 n2=3 o1=1 o2=1 output="x1*x2" > test.rsf
bash$ < test.rsf sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
10: 3 6 9 12 15
</pre>
Scale every data point by 2:
<pre>
bash$ < test.rsf sfscale dscale=2 | sfdisfil
0: 2 4 6 8 10
5: 4 8 12 16 20
10: 6 12 18 24 30
</pre>
Divide every trace by its maximum value:
<pre>
bash$ < test.rsf sfscale axis=1 | sfdisfil
0: 0.2 0.4 0.6 0.8 1
5: 0.2 0.4 0.6 0.8 1
10: 0.2 0.4 0.6 0.8 1
</pre>
Divide by the maximum value in the whole 2-D dataset:
<pre>
bash$ < test.rsf sfscale axis=2 | sfdisfil
0: 0.06667 0.1333 0.2 0.2667 0.3333
5: 0.1333 0.2667 0.4 0.5333 0.6667
10: 0.2 0.4 0.6 0.8 1
</pre>
The <tt>rscale=</tt> parameter is synonymous to <tt>dscale=</tt> except
when it is equal to zero. With <tt>sfscale dscale=0</tt>, the dataset gets
multiplied by zero. If using <tt>rscale=0</tt>, the other parameters are
used to define scaling. Thus, <tt>sfscale rscale=0 axis=1</tt> is
equivalent to <tt>sfscale axis=1</tt>, and <tt>sfscale rscale=0</tt>
is equivalent to <tt>sfscale dscale=1</tt>.

==sfspike==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate simple data: spikes, boxes, planes, constants.
|-
! colspan="4" | sfspike > spike.rsf mag= nsp=1 k#=[0,...] l#=[k1,k2,...] p#=[0,...] n#= o#=[0,0,...] d#=[0.004,0.1,0.1,...] label#=[Time,Distance,Distance,...] unit#=[s,km,km,...] title=
|-
| colspan="4" | Spike positioning is given in samples and starts with 1.
|-
| ''float '' || '''d#=[0.004,0.1,0.1,...]''' || || sampling on #-th axis
|-
| ''ints '' || '''k#=[0,...]''' || || spike starting position [nsp]
|-
| ''ints '' || '''l#=[k1,k2,...]''' || || spike ending position [nsp]
|-
| ''string '' || '''label#=[Time,Distance,Distance,...]''' || || label on #-th axis
|-
| ''floats '' || '''mag=''' || || spike magnitudes [nsp]
|-
| ''int '' || '''n#=''' || || size of #-th axis
|-
| ''int '' || '''nsp=1''' || || Number of spikes
|-
| ''float '' || '''o#=[0,0,...]''' || || origin on #-th axis
|-
| ''floats '' || '''p#=[0,...]''' || || spike inclination (in samples) [nsp]
|-
| ''string '' || '''title=''' || || title for plots
|-
| ''string '' || '''unit#=[s,km,km,...]''' || || unit on #-th axis
|}

<tt>sfspike</tt> takes no input and generates an output with
"spikes". It is an easy way to create data. Here is an example:
<pre>
bash$ sfspike n1=5 n2=3 k1=4 k2=1 | sfdisfil
0: 0 0 0 1 0
5: 0 0 0 0 0
10: 0 0 0 0 0
</pre>
The spike location is specified by parameters <tt>k1=4</tt> and
<tt>k2=1</tt>. Note that the locations are numbered starting from 1.
If one of the parameters is omitted or given the value of zero, the
spike in the corresponding direction becomes a plane:
<pre>
bash$ sfspike n1=5 n2=3 k1=4 | sfdisfil
0: 0 0 0 1 0
5: 0 0 0 1 0
10: 0 0 0 1 0

</pre>
If no spike parameters are given, the whole dataset is filled with ones:
<pre>
bash$ sfspike n1=5 n2=3 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
</pre>
To create several spikes, use the <tt>nsp=</tt> parameter and give a comma-separated list of values to <tt>k#=</tt> arguments:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 | sfdisfil
0: 1 0 0 0 0
5: 0 0 1 0 0
10: 0 0 0 1 0
</pre>
If the number of values in the list is smaller than <tt>nsp</tt>, the
last value gets repeated, and the spikes add on top of each other,
creating larger amplitudes:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3 k2=1,2 | sfdisfil
0: 1 0 0 0 0
5: 0 0 2 0 0
10: 0 0 0 0 0
</pre>
The magnitude of the spikes can be controlled explicitly with the
<tt>mag=</tt> parameter:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 mag=1,4,2 | sfdisfil
0: 1 0 0 0 0
5: 0 0 4 0 0
10: 0 0 0 2 0
</pre>
You can create boxes instead of spikes by using <tt>l#=</tt>
parameters:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 l1=4 k2=2 mag=8 | sfdisfil
0: 0 0 0 0 0
5: 0 8 8 8 0
10: 0 0 0 0 0
</pre>
In this case, <tt>k1=2</tt> specifies the box start, and <tt>l1=4</tt>
specifies the box end.
Finally, multi-dimensional planes can be given an inclination by using <tt>p#=</tt> parameters:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 p2=1 | sfdisfil
0: 0 1 0 0 0
5: 0 0 1 0 0
10: 0 0 0 1 0
</pre>
Note that <tt>sfspike</tt> interprets the <tt>p#=</tt> parameters in stepout from sample to sample, not in terms of axes units (i.e. s/m).

More than one p parameter can be specified. In this case, a (hyper) plane will be created.

When the inclination value is not integer, simple linear interpolation is used:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 p2=0.7 | sfdisfil
0: 0 1 0 0 0
5: 0 0.3 0.7 0 0
10: 0 0 0.6 0.4 0
</pre>
<tt>sfspike</tt> supplies default dimensions and labels to all axis:
<pre>
bash$ sfspike n1=5 n2=3 n3=4 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=5 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=4 d3=0.1 o3=0 label3="Distance" unit3="km"
60 elements 240 bytes
</pre>
As you can see, the first axis is assumed to be time, with sampling of
<math>0.004</math> seconds. All other axes are assumed to be distance, with
sampling of <math>0.1</math> kilometers. All these parameters can be changed on
the command line.
<pre>
bash$ sfspike n1=5 n2=3 n3=4 label3=Offset unit3=ft d3=20 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=5 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=4 d3=20 o3=0 label3="Offset" unit3="ft"
60 elements 240 bytes
</pre>

==sfspray==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Extend a dataset by duplicating in the specified axis dimension.
|-
! colspan="4" | sfspray < in.rsf > out.rsf axis=2 n= d= o= label= unit=
|-
| colspan="4" | This operation is adjoint to sfstack.
|-
| ''int '' || '''axis=2''' || || which axis to spray
|-
| ''float '' || '''d=''' || || Sampling of the newly created dimension
|-
| ''string '' || '''label=''' || || Label of the newly created dimension
|-
| ''int '' || '''n=''' || || Size of the newly created dimension
|-
| ''float '' || '''o=''' || || Origin of the newly created dimension
|-
| ''string '' || '''unit=''' || || Units of the newly created dimension
|}

<tt>sfspray</tt> extends the input hypercube by replicating the data
in one of the dimensions. The output dataset acquires one additional
dimension. Here is an example:
Start with a 2-D dataset
<pre>
bash$ sfmath n1=5 n2=2 output=x1+x2 > test.rsf
bash$ sfin test.rsf
test.rsf:
in="/var/tmp/test.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=2 d2=1 o2=0
10 elements 40 bytes
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
</pre>
Extend the data in the second dimension
<pre>
bash$ < test.rsf sfspray axis=2 n=3 > test2.rsf
bash$ sfin test2.rsf
test2.rsf:
in="/var/tmp/test2.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=3 d2=1 o2=0
n3=2 d3=1 o3=0
30 elements 120 bytes
bash$ < test2.rsf sfdisfil
0: 0 1 2 3 4
5: 0 1 2 3 4
10: 0 1 2 3 4
15: 1 2 3 4 5
20: 1 2 3 4 5
25: 1 2 3 4 5
</pre>
The output is three-dimensional, with traces from the original
data duplicated along the second axis.
Extend the data in the third dimension
<pre>
bash$ < test.rsf sfspray axis=3 n=2 > test3.rsf
bash$ sfin test3.rsf
test3.rsf:
in="/var/tmp/test3.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=2 d2=1 o2=0
n3=2 d3=? o3=?
20 elements 80 bytes
bash$ < test3.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 0 1 2 3 4
15: 1 2 3 4 5
</pre>
The output is also three-dimensional, with the original data replicated
along the third axis.

==sfstack==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Stack a dataset over one of the dimensions.
|-
! colspan="4" | sfstack < in.rsf > out.rsf axis=2 rms=n norm=y min=n max=n
|-
| colspan="4" | This operation is adjoint to sfspray.
|-
| ''int '' || '''axis=2''' || || which axis to stack
|-
| ''bool '' || '''max=n''' || [y/n] || If y, find maximum instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''min=n''' || [y/n] || If y, find minimum instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''norm=y''' || [y/n] || If y, normalize by fold.
|-
| ''bool '' || '''rms=n''' || [y/n] || If y, compute the root-mean-square instead of stack.
|}
While <tt>sfspray</tt> adds a dimension to a hypercube,
<tt>sfstack</tt> effectively removes one of the dimensions by stacking
over it. Here are some examples:
<pre>
bash$ sfmath n1=5 n2=3 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
bash$ < test.rsf sfstack axis=2 | sfdisfil
0: 1.5 2 3 4 5
bash$ < test.rsf sfstack axis=1 | sfdisfil
0: 2.5 3 4
</pre>
Why is the first value not 1 (in the first case) or 2 (in the second
case)? By default, <tt>sfstack</tt> normalizes the stack by the fold
(the number of non-zero entries). To avoid normalization, use
<tt>norm=n</tt>, as follows:
<pre>
bash$ < test.rsf sfstack norm=n | sfdisfil
0: 3 6 9 12 15
</pre>
<tt>sfstack</tt> can also compute root-mean-square values as
well as minimum and maximum values.
<pre>
bash$ < test.rsf sfstack rms=y | sfdisfil
0: 1.581 2.16 3.109 4.082 5.066
bash$ < test.rsf sfstack min=y | sfdisfil
0: 0 1 2 3 4
bash$ < test.rsf sfstack axis=1 max=y | sfdisfil
0: 4 5 6
</pre>

==sftransp==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Transpose two axes in a dataset.
|-
! colspan="4" | sftransp < in.rsf > out.rsf memsize=sf_memsize() plane=
|-
| colspan="4" | If you get a "Cannot allocate memory" error, give the program a memsize=1 command-line parameter to force out-of-core operation.
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''int '' || '''plane=''' || || Two-digit number with axes to transpose. The default is 12
|}

The <tt>sftransp</tt> program transposes the input hypercube
exchanging the two axes specified by the plane= parameter.
<pre>
bash$ sfspike n1=10 n2=20 n3=30 > orig123.rsf
bash$ sfin orig123.rsf
orig123.rsf:
in="/var/tmp/orig123.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
bash$ <orig123.rsf sftransp plane=23 >out132.rsf
bash$ sfin out132.rsf
out132.rsf:
in="/var/tmp/out132.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=30 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=20 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
bash$ <orig123.rsf sftransp plane=13 >out321.rsf
bash$ sfin out321.rsf
out321.rsf:
in="/var/tmp/out132.rsf@"
esize=4 type=float form=native
n1=30 d1=0.1 o1=0 label1="Distance" unit1="km"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=10 d3=0.004 o3=0 label3="Time" unit3="s"
6000 elements 24000 bytes
</pre>
<tt>sftransp</tt> tries to fit the dataset in memory to transpose it
there but, if not enough memory is available, it performs a slower
transpose out of core using disk operations. You can control the
amount of available memory using the memsize= parameter or
the RSFMEMSIZE environmental variable.

==sfwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a portion of the dataset.
|-
! colspan="4" | sfwindow < in.rsf > out.rsf verb=n squeeze=y j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''int '' || '''f#=(0,...)''' || || window start in #-th dimension
|-
| ''int '' || '''j#=(1,...)''' || || jump in #-th dimension
|-
| ''float '' || '''max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)''' || || maximum in #-th dimension
|-
| ''float '' || '''min#=(o1,o2,,...)''' || || minimum in #-th dimension
|-
| ''int '' || '''n#=(0,...)''' || || window size in #-th dimension
|-
| ''bool '' || '''squeeze=y''' || [y/n] || if y, squeeze dimensions equal to 1 to the end
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

sfwindow is used to window a portion of the dataset. Here is
a quick example: Start by creating some data.
<pre>
bash$ sfmath n1=5 n2=3 o1=1 o2=1 output="x1*x2" > test.rsf
bash$ < test.rsf sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
10: 3 6 9 12 15
</pre>
Now window the first two rows:
<pre>
bash$ < test.rsf sfwindow n2=2 | sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
</pre>
Window the first three columns:
<pre>
bash$ < test.rsf sfwindow n1=3 | sfdisfil
0: 1 2 3 2 4
5: 6 3 6 9
</pre>
Window the middle row:
<pre>
bash$ < test.rsf sfwindow f2=1 n2=1 | sfdisfil
0: 2 4 6 8 10
</pre>
You can interpret the f# and n# parameters as
meaning "skip that many rows/columns" and "select that many
rows/columns" correspondingly. Window the middle point in the dataset:
<pre>
bash$ < test.rsf sfwindow f1=2 n1=1 f2=1 n2=1 | sfdisfil
0: 6
</pre>
Window every other column:
<pre>
bash$ < test.rsf sfwindow j1=2 | sfdisfil
0: 1 3 5 2 6
5: 10 3 9 15
</pre>
Window every third column:
<pre>
bash$ < test.rsf sfwindow j1=3 | sfdisfil
0: 1 4 2 8 3
5: 12
</pre>
Alternatively, sfwindow can use the minimum and maximum
parameters to select a window. In the following example, we are
creating a dataset with sfspike and then windowing a portion of it
between 1 and 2 seconds in time and sampled at 8 miliseconds.
<pre>
bash$ sfspike n1=1000 n2=10 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=1000 d1=0.004 o1=0 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
10000 elements 40000 bytes
bash$ < spike.rsf sfwindow min1=1 max1=2 d1=0.008 > window.rsf
bash$ sfin window.rsf
window.rsf:
in="/var/tmp/window.rsf@"
esize=4 type=float form=native
n1=126 d1=0.008 o1=1 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
1260 elements 5040 bytes
</pre>
By default, sfwindow "squeezes" the hypercube dimensions
that are equal to one toward the end of the dataset. Here is an
example of taking a time slice:
<pre>
bash$ < spike.rsf sfwindow n1=1 min1=1 > slice.rsf
bash$ sfin slice.rsf
slice.rsf:
in="/var/tmp/slice.rsf@"
esize=4 type=float form=native
n1=10 d1=0.1 o1=0 label1="Distance" unit1="km"
n2=1 d2=0.004 o2=1 label2="Time" unit2="s"
10 elements 40 bytes
</pre>
You can change this behavior by specifying squeeze=n.
<pre>
bash$ < spike.rsf sfwindow n1=1 min1=1 squeeze=n > slice.rsf
bash$ sfin slice.rsf
slice.rsf:
in="/var/tmp/slice.rsf@"
esize=4 type=float form=native
n1=1 d1=0.004 o1=1 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
10 elements 40 bytes
</pre>

=Seismic programs=
Programs in this category are specific for operations on seismic data. The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/seismic/ system/seismic] in the Madagascar distribution.

==sffkamo==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Computes Azimuth Move-Out (AMO) operator in the f-k log-stretch domain
|-
! colspan="4" | sffkamo < in.rsf > out.rsf h1= h2= f1= f2= maxe=10.
|-
| ''float '' || '''f1=''' || || input azimuth in degrees
|-
| ''float '' || '''f2=''' || || output azimuth in degrees
|-
| ''float '' || '''h1=''' || || input offset
|-
| ''float '' || '''h2=''' || || output offset
|-
| ''float '' || '''maxe=10.''' || || stability constraint
|}
Sample workflow from [http://m8r.info/RSF/book/sep/fkamo/paper_html/ SEP-110, 63-70 (2001)], with the addition of a bandpass for the input:

Create input -- a (t,x,y) common-offset cube:
<bash>
sfspike \
n1=128 o1=0.4 d1=0.0032 k1=65 label1=t \
n2=256 o2=-1.536 d2=0.012 k2=129 label2=x \
n3=128 o3=-1.024 d3=0.016 k3=65 label3=y | \
sfbandpass flo=5 fhi=60 > spikebps.rsf
</bash>

Apply log-stretch FFT:
<bash>
<spikebps.rsf sfstretch rule=L dens=4 |\
sffft1 |\
sffft3 axis=2 |\
sffft3 axis=3 > spikefft3.rsf
</bash>

Compute AMO operator for a file of the dimensions of <tt>spikefft3.rsf</tt>. The only information taken from stdin are the n, o, d parameters:
<bash>
<spikefft3.rsf sffkamo h2=2 f2=10 h1=1.8 f1=30 >oper.rsf
</bash>

Apply the operator by multiplication and fft back to (t, mx, my):
<bash>
< spikefft3.rsf sfadd mode=prod oper.rsf |\
sffft3 axis=3 inv=y |\
sffft3 axis=2 inv=y |\
sffft1 inv=y |\
sfstretch rule=L dens=4 inv=y > spikeamo.rsf
</bash>

Prepare for 8-bit greyscale visualization:
<bash>
< spikeamo.rsf sfbyte pclip=100 gainpanel=a > spikebyte.rsf
</bash>

Picture from the middle of the impulse response:
<bash>
<spikebyte.rsf sfgrey3 frame1=65 frame2=129 frame3=65 \
point1=0.333 title='AMO saddle, no f-k filter' | sfpen &
</bash>

Picture illustrating the artifacts (i.e. need for f-k filter):
<bash>
< spikebyte.rsf sfgrey3 frame1=65 frame2=97 frame3=97 \
point1=0.333 title='No f-k filter' | sfpen &
</bash>

Apply the f-k filter and (in this case) visualize:
<bash>
< spikeamo.rsf sffft1 |\
sffft3 axis=2 |\
sffft3 axis=3 |\
sfdipfilter v1=-2.5 v2=-1.5 v3=1.5 v4=2.5 taper=2 pass=0 dim=3 |\
sffft3 axis=3 inv=y |\
sffft3 axis=2 inv=y |\
sffft1 inv=y |\
sfbyte pclip=100 gainpanel=a |\
sfgrey3 frame1=65 frame2=97 frame3=97 point1=0.333 title='With f-k filter' |\
sfpen &
</bash>

==sfheaderattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Integer header attributes.
|-
! colspan="4" | sfheaderattr < head.rsf
|-
| colspan="4" | Only nonzero values are reported.
|}

The <tt>sfheaderattr</tt> examines the contents of a trace header file,
typically generated by <tt>sfsegyread</tt>. In the example below, we examine
trace headers in the output of <tt>suplane</tt>, a program from Seismic Unix.
<pre>
bash$ suplane > plane.su
bash$ sfsegyread tape=plane.su su=y tfile=tfile.rsf > plane.rsf
bash$ sfheaderattr < tfile.rsf
*******************************************
71 headers, 32 traces
key[0]="tracl" min[0]=1 max[31]=32 mean=16.5
key[1]="tracr" min[0]=1 max[31]=32 mean=16.5
key[11]="offset" min[0]=400 max[31]=400 mean=400
key[38]="ns" min[0]=64 max[31]=64 mean=64
key[39]="dt" min[0]=4000 max[31]=4000 mean=4000
*******************************************
</pre>
For different standard keywords, a minimum, maximum, and mean values
are reported unless they are identically zero. This quick inspection
can help in identifying meaningful keywords set in the data. The input
data type must be <tt>int</tt>.

==sfheadermath==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Mathematical operations, possibly on header keys.
|-
! colspan="4" | sfheadermath < in.rsf > out.rsf memsize=sf_memsize() output=
|-
| colspan="4" | Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs See also sfmath. An addition operation can be performed by sfstack.
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''string '' || '''output=''' || || Describes the output in a mathematical notation.
|}
<tt>sfheadermath</tt> is a versatile program for mathematical
operations on rows of the input file. If the input file is an
<tt>n1</tt> by <tt>n2</tt> matrix, the output will be a <tt>1</tt> by
<tt>n2</tt> matrix that contains one row made out of mathematical
operations on the other rows. <tt>sfheadermath</tt> can identify a row
by number or by a standard SEGY keyword. The latter is useful for
processing headers extracted from SEGY or SU files.
Here is an example. First, we create an SU file with <tt>suplane</tt> and convert it to RSF using <tt>sfsegyread</tt>.
<pre>
bash$ suplane > plane.su
bash$ sfsegyread tape=plane.su su=y tfile=tfile.rsf > plane.rsf
</pre>
The trace header information is saved in <tt>tfile.rsf</tt>. It
contains 71 headers for 32 traces in integer format.
<pre>
bash$ sfin tfile.rsf
tfile.rsf:
in="/tmp/tfile.rsf@"
esize=4 type=int form=native
n1=71 d1=? o1=?
n2=32 d2=? o2=?
2272 elements 9088 bytes
</pre>
Next, we will convert <tt>tfile.rsf</tt> to a floating-point format
and run <tt>sfheadermath</tt> to create a new header.
<pre>
bash$ < tfile.rsf sfdd type=float | \
sfheadermath myheader=1 output="sqrt(myheader+(2+10*offset^2))" > new.rsf
bash$ sfin new.rsf
new.rsf:
in="/tmp/new.rsf@"
esize=4 type=float form=native
n1=1 d1=? o1=?
n2=32 d2=? o2=?
32 elements 128 bytes
</pre>
We defined "myheader" as being the row number 1 in the input (note
that numbering starts with 0) and combined it with "offset", which
is a standard SEGY keyword that denotes row number 11 (see the output
of <tt>sfheaderattr</tt> above.) A variety of mathematical expressions
can be defined in the <tt>output=</tt> string. The expression
processing engine is shared with <tt>sfmath</tt>.

==sfsegyheader==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Make a trace header file for segywrite.
|-
! colspan="4" | sfsegyheader < in.rsf > out.rsf n1= d1=
|-
| colspan="4" | Use the output for tfile= argument in segywrite.
|-
| ''float '' || '''d1=''' || || trace sampling
|-
| ''int '' || '''n1=''' || || number of samples in a trace
|}

==sfsegyread==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a SEG-Y or SU dataset to RSF.
|-
! colspan="4" | sfsegyread mask=msk.rsf > out.rsf tfile=hdr.rsf verb=n su= suxdr=n endian=y format=segyformat (bhead) ns=segyns (bhead) tape= read= hfile= bfile=
|-
| colspan="4" | Data headers and trace headers are separated from the data. "suread" is equivalent to "segyread su=y" SEGY key names: tracl: trace sequence number within line 0 tracr: trace sequence number within reel 4 fldr: field record number 8 tracf: trace number within field record 12 ep: energy source point number 16 cdp: CDP ensemble number 20 cdpt: trace number within CDP ensemble 24 trid: trace identification code: 1 = seismic data 2 = dead 3 = dummy 4 = time break 5 = uphole 6 = sweep 7 = timing 8 = water break 9---, N = optional use (N = 32,767) 28 nvs: number of vertically summed traces 30 nhs: number of horizontally summed traces 32 duse: data use: 1 = production 2 = test 34 offset: distance from source point to receiver group (negative if opposite to direction in which the line was shot) 36 gelev: receiver group elevation from sea level (above sea level is positive) 40 selev: source elevation from sea level (above sea level is positive) 44 sdepth: source depth (positive) 48 gdel: datum elevation at receiver group 52 sdel: datum elevation at source 56 swdep: water depth at source 60 gwdep: water depth at receiver group 64 scalel: scale factor for previous 7 entries with value plus or minus 10 to the power 0, 1, 2, 3, or 4 (if positive, multiply, if negative divide) 68 scalco: scale factor for next 4 entries with value plus or minus 10 to the power 0, 1, 2, 3, or 4 (if positive, multiply, if negative divide) 70 sx: X source coordinate 72 sy: Y source coordinate 76 gx: X group coordinate 80 gy: Y group coordinate 84 counit: coordinate units code: for previous four entries 1 = length (meters or feet) 2 = seconds of arc (in this case, the X values are unsigned longitude and the Y values are latitude, a positive value designates the number of seconds east of Greenwich or north of the equator 88 wevel: weathering velocity 90 swevel: subweathering velocity 92 sut: uphole time at source 94 gut: uphole time at receiver group 96 sstat: source static correction 98 gstat: group static correction 100 tstat: total static applied 102 laga: lag time A, time in ms between end of 240- byte trace identification header and time break, positive if time break occurs after end of header, time break is defined as the initiation pulse which maybe recorded on an auxiliary trace or as otherwise specified by the recording system 104 lagb: lag time B, time in ms between the time break and the initiation time of the energy source, may be positive or negative 106 delrt: delay recording time, time in ms between initiation time of energy source and time when recording of data samples begins (for deep water work if recording does not start at zero time) 108 muts: mute time--start 110 mute: mute time--end 112 ns: number of samples in this trace 114 dt: sample interval, in micro-seconds 116 gain: gain type of field instruments code: 1 = fixed 2 = binary 3 = floating point 4 ---- N = optional use 118 igc: instrument gain constant 120 igi: instrument early or initial gain 122 corr: correlated: 1 = no 2 = yes 124 sfs: sweep frequency at start 126 sfe: sweep frequency at end 128 slen: sweep length in ms 130 styp: sweep type code: 1 = linear 2 = cos-squared 3 = other 132 stas: sweep trace length at start in ms 134 stae: sweep trace length at end in ms 136 tatyp: taper type: 1=linear, 2=cos^2, 3=other 138 afilf: alias filter frequency if used 140 afils: alias filter slope 142 nofilf: notch filter frequency if used 144 nofils: notch filter slope 146 lcf: low cut frequency if used 148 hcf: high cut frequncy if used 150 lcs: low cut slope 152 hcs: high cut slope 154 year: year data recorded 156 day: day of year 158 hour: hour of day (24 hour clock) 160 minute: minute of hour 162 sec: second of minute 164 timbas: time basis code: 1 = local 2 = GMT 3 = other 166 trwf: trace weighting factor, defined as 1/2^N volts for the least sigificant bit 168 grnors: geophone group number of roll switch position one 170 grnofr: geophone group number of trace one within original field record 172 grnlof: geophone group number of last trace within original field record 174 gaps: gap size (total number of groups dropped) 176 otrav: overtravel taper code: 1 = down (or behind) 2 = up (or ahead) 178 cdpx: X coordinate of CDP 180 cdpy: Y coordinate of CDP 184 iline: in-line number 188 xline: cross-line number 192 shnum: shotpoint number 196 shsca: shotpoint scalar 200 tval: trace value meas. 202 tconst4: transduction const 204 tconst2: transduction const 208 tunits: transduction units 210 device: device identifier 212 tscalar: time scalar 214 stype: source type 216 sendir: source energy dir. 218 unknown: unknown 222 smeas4: source measurement 224 smeas2: source measurement 228 smeasu: source measurement unit 230 unass1: unassigned 232 unass2: unassigned 236
|-
| ''string '' || '''bfile=''' || || output binary data header file
|-
| ''bool '' || '''endian=y''' || [y/n] || Whether to automatically estimate endianness or not
|-
| ''int '' || '''format=segyformat (bhead)''' || [1,2,3,5] || Data format. The default is taken from binary header.
:1 is IBM floating point
:2 is 4-byte integer
:3 is 2-byte integer
:5 is IEEE floating point
|-
| ''string '' || '''hfile=''' || || output text data header file
|-
| ''string '' || '''mask=''' || || optional header mask for reading only selected traces (auxiliary input file name)
|-
| ''int '' || '''ns=segyns (bhead)''' || || Number of samples. The default is taken from binary header
|-
| ''string '' || '''read=''' || || what to read: h - header, d - data, b - both (default)
|-
| ''bool '' || '''su=''' || [y/n] || y if input is SU, n if input is SEGY
|-
| ''bool '' || '''suxdr=n''' || [y/n] || y, SU has XDR support
|-
| ''string '' || '''tape=''' || || input data
|-
| ''string '' || '''tfile=''' || || output trace header file (auxiliary output file name)
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

The SEG Y format is an [http://en.wikipedia.org/wiki/Open_standard open standard] for the exchange of geophysical data. It is controlled by the non-profit [http://www.seg.org/SEGportalWEBproject/portals/SEG_Online.portal?_nfpb=true&_pageLabel=pg_gen_content&Doc_Url=prod/SEG-Publications/Pub-Yearbook/committees.htm SEG Technical Standards Committee]. There are two versions of this standard: [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev0.pdf rev0] (1975)<ref>Barry, K.M., Cavers, D.A., and Kneale, C.W. 1975. Recommended standards for digital tape formats. ''Geophysics'', '''40''', no. 02, 344–352.</ref> and [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev1.pdf rev1] (2002)<ref>Norris, M.W., Faichney, A.K., ''Eds''. 2001. SEG Y rev1 Data Exchange format. Society of Exploration Geophysicists, Tulsa, OK, 45 pp.</ref>. The implementation in <tt>sfsegyread</tt> is a mixture of rev0 (i.e. no checks for Extended Textual Headers) and rev1 ([http://en.wikipedia.org/wiki/IEEE_floating-point_standard IEEE floating point format] allowed for trace data samples).

A SEG-Y file as understood by <tt>sfsegyread</tt> contains a "Reel Identification Header" (3200 bytes in EBCDIC followed by 400 bytes in a binary encoding), followed by a number of "Trace Blocks". Each "Trace Block" contains a 240-byte "Trace Header" (binary) followed by "Trace Data" -- a sequence of <tt>ns</tt> samples. Binary values in both reel headers and trace headers are two's complement integers, either two bytes or four bytes long. There are no floating-point values defined in the headers. Trace Data samples can have various encodings, either floating point or integer, described further down, but they are all big-endian. To convert from SEG-Y to RSF, <tt>sfsegyread</tt> will strip the tape reel EBCDIC header and convert it to ASCII, will extract the reel binary header without changing it, and will put the trace headers into one RSF file, and the traces themselves on another.

===SEG-Y Trace Headers===
In the SEG-Y standard, only the first 180 bytes of the 240-byte trace header are defined; bytes 181-240 are reserved for non-standard header information, and these locations are increasingly used in modern SEG-Y files and its variants. The standard provides for a total of 71 4-byte and 2-byte predefined header words. These 71 standard words have defined lengths and byte offsets, and only these words and byte locations are read using <tt>segyread</tt> and output to the RSF header file with the <tt>hfile=</tt> option. The user may remap these predefined keywords to a different byte offsets.

===SU File Format===
An [http://www.cwp.mines.edu/sututor/node22.html SU file] is nothing more than a SEG-Y file without the reel headers, and with the Trace Data samples in the native encoding of the CPU the file was created on (Attention -- limited portability!). So, to convert from SU to RSF, <tt>sfsegyread</tt> will just separate headers and traces into two RSF files.

===SEG-Y specific parameters===
*<tt>hfile=</tt> specifies the name of the file in which the EBCDIC reel header will be put after conversion to ASCII. If you are certain there is no useful information in it, <tt>hfile=/dev/null</tt> works just fine. If you do not specify anything for this parameter you will get an ASCII file named <tt>header</tt> in the current directory. If you want to quickly preview this header before running <tt>sfsegyread</tt>, use<pre>dd if=input.segy count=40 bs=80 cbs=80 conv=unblock,ascii</pre>
*<tt>bfile=</tt> specifies name of the file in which the binary reel header (the 400-bytes thing following the 3600-bytes EBCDIC) will be put without any conversion. The default name is "binary". Unless you have software that knows how to read exactly this special type of file, it will be completely useless, so do <tt>bfile=/dev/null</tt>
*<tt>format=</tt> specifies the format in which the trace data samples are in the SEG-Y input file. This is read from the binary reel header of the SEG-Y file. Valid values are 1(IBM floating point), 2 (4-byte integer), 3 (2-byte integer) and 5 (IEEE floating point). If the input file is SU, the format will be assumed to be the native <tt>float</tt> format.

*<tt>keyname=</tt> specifies the byte offset to remap a header using the trace header key names shown above. For example, if the CDP locations have been placed in bytes 181-184 instead of the standard 21-24, <tt>cdp=180</tt> will remap the trace header to that location.

===SU-specific parameters===
*<tt>suxdr=</tt> specifies whether the input file was created with a SU package with XDR support enabled. If you have access to the source code of your SU install (try <tt>$CWPROOT/src</tt>), type: <tt>grep 'XDRFLAG =' $CWPROOT/src/Makefile.config</tt> and look at the last uncommented entry. If no value is given for <tt>XDRFLAG</tt>, the package was not compiled with XDR support.
===Common parameters===
*<tt>su=</tt> specifies if the input file is SU or SEG-Y. Default is <tt>su=n</tt> (SEG-Y file).
*<tt>tape=</tt> specifies the input data. Stdin could not be used because <tt>sfsegyread</tt> has to work with tapes, and needs to fseek back and forth through the input file. Thankfully, output is on stdout.
*<tt>read=</tt> specifies what parts of the "Trace Blocks" will be read. It can be <tt>read=t</tt> (only trace data is read), <tt>read=h</tt> (only trace headers are read) or <tt>read=b</tt> (both are read).
*<tt>tfile=</tt> gives the name of the RSF file to which trace headers are written. Obviously, it should be only specified with <tt>read=h</tt> or <tt>read=b</tt>.
*<tt>mask=</tt> is an optional parameter specifying the name of a mask that says which traces will be read. The mask is a 1-D RSF file with integers. The number of samples in the mask is the same as the number of traces in the unmasked SEG-Y. In places corresponding to unwanted traces there should be zeros in the mask.
*<tt>ns=</tt> specifies the number of samples in a trace. For SEG-Y files, the default is taken from the binary reel header, and for SU files, from the header of the first trace. This parameter is however critical enough that a command line override was given for it.
*<tt>verbose=</tt> is the verbosity flag. Can be <tt>y</tt> or <tt>n</tt>.
*<tt>endian=</tt> is a y/n flag (default y), specifying whether to automatically estimate or not if samples in the Trace Data blocks are big-endian or little-endian. Try it if you are in trouble and do not know what else to do, otherwise let the automatic estimation do its job.

==sfsegywrite==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert an RSF dataset to SEGY or SU.
|-
! colspan="4" | sfsegywrite < in.rsf tfile=hdr.rsf verb=false su=false endian=sf_endian() tape= hfile= bfile=
|-
| colspan="4" | Merges trace headers with data.
|-
| ''string '' || '''bfile=''' || || input binary data header file
|-
| ''bool '' || '''endian=sf_endian()''' || [y/n] || big/little endian flag. The default is estimated automatically
|-
| ''string '' || '''hfile=''' || || input text data header file
|-
| ''bool '' || '''su=n''' || [y/n] || y if output is SU, n if output is SEGY
|-
| ''string '' || '''tape=''' || ||
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}
Please see <tt>sfsegyread</tt> for a complete description of parameter meanings and background issues. Parameters <tt>bfile</tt> and <tt>hfile</tt> should only be given values when the desired file is SEG-Y (default). The output file is specified by the <tt>tape=</tt> tag.
=Generic programs=
Programs in this category are general signal and image processing programs. The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/generic/ system/generic] in the Madagascar distribution.
==sfnoise==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Add random noise to the data.
|-
! colspan="4" | sfnoise < in.rsf > out.rsf seed=time(NULL) type=y var= range= mean=0 rep=n
|-
| ''float '' || '''mean=0''' || || noise mean
|-
| ''float '' || '''range=''' || || noise range (default=1)
|-
| ''bool '' || '''rep=n''' || [y/n] || if y, replace data with noise
|-
| ''int '' || '''seed=time(NULL)''' || || random seed
|-
| ''bool '' || '''type=y''' || [y/n] || noise distribution, y: normal, n: uniform
|-
| ''float '' || '''var=''' || || noise variance
|}
See the [http://www.ahay.org/rsflog/index.php?/archives/262-Program-of-the-month-sfnoise.html Program of the Month] blog entry.

=Plotting programs (stable)=
The source files for these programs can be found under
[http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/plot/main/ plot/main]
in the Madagascar distribution.

==sfbox==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Draw a balloon-style label.
|-
! colspan="4" | sfbox lab_color=VP_WHITE lab_fat=0 pscale=1. pointer=y reverse=n lat=0. long=90. angle=0. x0=0. y0=0. scale0=1. xt=2. yt=0. x_oval=0. y_oval=0. boxit=y length= scalet= size=.25 label= > out.vpl
|-
| ''float '' || '''angle=0.''' || || longitude of floating label in 3-D
|-
| ''bool '' || '''boxit=y''' || [y/n] || if y, create a box around text
|-
| ''int '' || '''lab_color=VP_WHITE''' || || label color
|-
| ''int '' || '''lab_fat=0''' || || label fatness
|-
| ''string '' || '''label=''' || || text for label
|-
| ''float '' || '''lat=0.''' || ||
|-
| ''float '' || '''length=''' || || normalization for xt and yt
|-
| ''float '' || '''long=90.''' || || latitude and longitude of viewpoint in 3-D
|-
| ''bool '' || '''pointer=y''' || [y/n] || if y, create arrow pointer
|-
| ''float '' || '''pscale=1.''' || || scale factor for width of pointer
|-
| ''bool '' || '''reverse=n''' || [y/n] ||
|-
| ''float '' || '''scale0=1.''' || || scale factor for x0 and y0
|-
| ''float '' || '''scalet=''' || ||
|-
| ''float '' || '''size=.25''' || || text height in inches
|-
| ''float '' || '''x0=0.''' || ||
|-
| ''float '' || '''x_oval=0.''' || ||
|-
| ''float '' || '''xt=2.''' || ||
|-
| ''float '' || '''y0=0.''' || || position of the pointer tip
|-
| ''float '' || '''y_oval=0.''' || || size of the oval around pointer
|-
| ''float '' || '''yt=0.''' || || relative position of text
|}
==sfcontour==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Contour plot.
|-
! colspan="4" | sfcontour < in.rsf c= min1=o1 min2=o2 max1=o1+(n1-1)*d1 max2=o2+(n2-1)*d2 nc=50 dc= c0= transp=y minval= maxval= allpos=y barlabel= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''bool '' || '''allpos=y''' || [y/n] || contour positive values only
|-
| ''string '' || '''barlabel=''' || ||
|-
| ''floats '' || '''c=''' || || [nc]
|-
| ''float '' || '''c0=''' || || first contour
|-
| ''float '' || '''dc=''' || || contour increment
|-
| ''float '' || '''max1=o1+(n1-1)*d1''' || ||
|-
| ''float '' || '''max2=o2+(n2-1)*d2''' || || data window to plot
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''min1=o1''' || ||
|-
| ''float '' || '''min2=o2''' || ||
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''nc=50''' || || number of contours
|-
| ''bool '' || '''transp=y''' || [y/n] || if y, transpose the axes
|}
==sfdots==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot signal with lollipops.
|-
! colspan="4" | sfdots < in.rsf labels= dots=(n1 <= 130)? 1: 0 seemean=(bool) (n2 <= 30) strings=(bool) (n1 <= 400) connect=1 corners= silk=n gaineach=y labelsz=8 yreverse=n constsep=n seedead=n transp=n xxscale=1. yyscale=1. clip=-1. overlap=0.9 screenratio=VP_SCREEN_RATIO screenht=VP_STANDARD_HEIGHT screenwd=screenhigh / screenratio radius=dd1/3 label1= unit1= title= > plot.vpl
|-
| ''float '' || '''clip=-1.''' || || data clip
|-
| ''int '' || '''connect=1''' || || connection type: 1 - diagonal, 2 - bar, 4 - only for non-zero data
|-
| ''bool '' || '''constsep=n''' || [y/n] || if y, use constant trace separation
|-
| ''int '' || '''corners=''' || || number of polygon corners (default is 6)
|-
| ''int '' || '''dots=(n1 <= 130)? 1: 0''' || || type of dots: 1 - baloon, 0 - no dots, 2 - only for non-zero data
|-
| ''bool '' || '''gaineach=y''' || [y/n] || if y, gain each trace independently
|-
| ''string '' || '''label1=''' || ||
|-
| ''strings'' || '''labels=''' || || trace labels [n2]
|-
| ''int '' || '''labelsz=8''' || || label size
|-
| ''float '' || '''overlap=0.9''' || || trace overlap
|-
| ''float '' || '''radius=dd1/3''' || || dot radius
|-
| ''float '' || '''screenht=VP_STANDARD_HEIGHT''' || || screen height
|-
| ''float '' || '''screenratio=VP_SCREEN_RATIO''' || || screen aspect ratio
|-
| ''float '' || '''screenwd=screenhigh / screenratio''' || || screen width
|-
| ''bool '' || '''seedead=n''' || [y/n] || if y, show zero traces
|-
| ''bool '' || '''seemean=(bool) (n2 <= 30)''' || [y/n] || if y, draw axis lines
|-
| ''bool '' || '''silk=n''' || [y/n] || if y, silky plot
|-
| ''bool '' || '''strings=(bool) (n1 <= 400)''' || [y/n] || if y, draw strings
|-
| ''string '' || '''title=''' || ||
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axis
|-
| ''string '' || '''unit1=''' || ||
|-
| ''float '' || '''xxscale=1.''' || || x scaling
|-
| ''bool '' || '''yreverse=n''' || [y/n] || if y, reverse y axis
|-
| ''float '' || '''yyscale=1.''' || || y scaling
|}
==sfgraph3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate 3-D cube plot for surfaces.
|-
! colspan="4" | sfgraph3 < in.rsf orient=1 min= max= point1=0.5 point2=0.5 frame1=0.5*(min+max) frame2=n1-1 frame3=0 movie=0 dframe=1 n1pix=n1/point1+n3/(1.-point1) n2pix=n2/point2+n3/(1.-point2) flat=y > plot.vpl
|-
| ''float '' || '''dframe=1''' || || frame increment in a movie
|-
| ''bool '' || '''flat=y''' || [y/n] || if n, display perspective view
|-
| ''float '' || '''frame1=0.5*(min+max)''' || ||
|-
| ''int '' || '''frame2=n1-1''' || ||
|-
| ''int '' || '''frame3=0''' || || frame numbers for cube faces
|-
| ''float '' || '''max=''' || || maximum function value
|-
| ''float '' || '''min=''' || || minimum function value
|-
| ''int '' || '''movie=0''' || || 0: no movie, 1: movie over axis 1, 2: axis 2, 3: axis 3
|-
| ''int '' || '''n1pix=n1/point1+n3/(1.-point1)''' || || number of vertical pixels
|-
| ''int '' || '''n2pix=n2/point2+n3/(1.-point2)''' || || number of horizontal pixels
|-
| ''int '' || '''orient=1''' || || function orientation
|-
| ''float '' || '''point1=0.5''' || || fraction of the vertical axis for front face
|-
| ''float '' || '''point2=0.5''' || || fraction of the horizontal axis for front face
|}
==sfgraph==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Graph plot.
|-
! colspan="4" | sfgraph < in.rsf symbolsz= pclip=100. transp=n symbol= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''float '' || '''pclip=100.''' || || clip percentile
|-
| ''string '' || '''symbol=''' || || if set, plot with symbols instead of lines
|-
| ''floats '' || '''symbolsz=''' || || symbol size (default is 2) [n2]
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axes
|}
==sfgrey3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate 3-D cube plot.
|-
! colspan="4" | sfgrey3 < in.rsf point1=0.5 point2=0.5 frame1=0 frame2=n2-1 frame3=0 movie=0 dframe=1 n1pix=n1/point1+n3/(1.-point1) n2pix=n2/point2+n3/(1.-point2) flat=y scalebar=n minval= maxval= barreverse=n nreserve=8 bar= color= > plot.vpl
|-
| colspan="4" | Requires an "unsigned char" input (the output of sfbyte).
|-
| ''string '' || '''bar=''' || || file for scalebar data
|-
| ''bool '' || '''barreverse=n''' || [y/n] || if y, go from small to large on the bar scale
|-
| ''string '' || '''color=''' || || color scheme (default is i)
|-
| ''int '' || '''dframe=1''' || || frame increment in a movie
|-
| ''bool '' || '''flat=y''' || [y/n] || if n, display perspective view
|-
| ''int '' || '''frame1=0''' || ||
|-
| ''int '' || '''frame2=n2-1''' || ||
|-
| ''int '' || '''frame3=0''' || || frame numbers for cube faces
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''movie=0''' || || 0: no movie, 1: movie over axis 1, 2: axis 2, 3: axis 3
|-
| ''int '' || '''n1pix=n1/point1+n3/(1.-point1)''' || || number of vertical pixels
|-
| ''int '' || '''n2pix=n2/point2+n3/(1.-point2)''' || || number of horizontal pixels
|-
| ''int '' || '''nreserve=8''' || || reserved colors
|-
| ''float '' || '''point1=0.5''' || || fraction of the vertical axis for front face
|-
| ''float '' || '''point2=0.5''' || || fraction of the horizontal axis for front face
|-
| ''bool '' || '''scalebar=n''' || [y/n] || if y, draw scalebar
|}

Different [http://reproducibility.org/rsflog/index.php?/archives/14-Color-schemes.html color schemes] are available
for sfgrey and sfgrey3. Examples are in the book at [http://reproducibility.org/RSF/book/rsf/rsf/sfgrey.html rsf/rsf/sfgrey].

==sfgrey==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate raster plot.
|-
! colspan="4" | sfgrey < in.rsf > out.rsf bar=bar.rsf transp=y yreverse=y xreverse=n gpow= phalf= clip= pclip= gainstep=0.5+n1/256. allpos=n bias=0. polarity=n verb=n scalebar=n minval= maxval= barreverse=n wantframenum=(bool) (n3 > 1) nreserve=8 gainpanel= bar= color= > (plot.vpl | char.rsf)
|-
| colspan="4" | Can input char values. If called "byte", outputs char values. Run "sfdoc stdplot" for more parameters.
|-
| ''bool '' || '''allpos=n''' || [y/n] || if y, assume positive data
|-
| ''string '' || '''bar=''' || || file for scalebar data
|-
| ''bool '' || '''barreverse=n''' || [y/n] || if y, go from small to large on the bar scale
|-
| ''float '' || '''bias=0.''' || || subtract bias from data
|-
| ''float '' || '''clip=''' || ||
|-
| ''string '' || '''color=''' || || color scheme (default is i)
|-
| ''string '' || '''gainpanel=''' || || gain reference: 'a' for all, 'e' for each, or number
|-
| ''int '' || '''gainstep=0.5+n1/256.''' || || subsampling for gpow and clip estimation
|-
| ''float '' || '''gpow=''' || ||
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''nreserve=8''' || || reserved colors
|-
| ''float '' || '''pclip=''' || || data clip percentile (default is 99)
|-
| ''float '' || '''phalf=''' || || percentage for estimating gpow
|-
| ''bool '' || '''polarity=n''' || [y/n] || if y, reverse polarity (white is high by default)
|-
| ''bool '' || '''scalebar=n''' || [y/n] ||
|-
| ''bool '' || '''transp=y''' || [y/n] || if y, transpose the display axes
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''bool '' || '''wantframenum=(bool) (n3 > 1)''' || [y/n] || if y, display third axis position in the corner
|-
| ''bool '' || '''xreverse=n''' || [y/n] || if y, reverse the horizontal axis
|-
| ''bool '' || '''yreverse=y''' || [y/n] || if y, reverse the vertical axis
|}

Different [http://reproducibility.org/rsflog/index.php?/archives/14-Color-schemes.html color schemes] are available
and examples are in the book at [http://reproducibility.org/RSF/book/rsf/rsf/sfgrey.html rsf/rsf/sfgrey].

==sfplas==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot Assembler - convert ascii to vplot.
|-
! colspan="4" | sfplas
|}
==sfpldb==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot Debugger - convert vplot to ascii.
|-
! colspan="4" | sfpldb
|}
==sfplotrays==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot rays.
|-
! colspan="4" | sfplotrays frame=frame.rsf nt=n1*n2 jr=1 frame= < rays.rsf > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''string '' || '''frame=''' || ||
|-
| ''int '' || '''jr=1''' || || skip rays
|-
| ''int '' || '''nt=n1*n2''' || || maximum ray length
|}
==sfthplot==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Hidden-line surface plot.
|-
! colspan="4" | sfthplot < in.rsf uflag=y dflag=y alpha=45. titlsz=9 axissz=6 plotfat=0 titlefat=2 axisfat=2 plotcolup=VP_YELLOW plotcoldn=VP_RED axis=y axis1=y axis2=y axis3=y clip=0. pclip=100. gainstep=0.5+nx/256. bias=0. dclip=1. norm=y xc=1.5 zc=3 ratio=5. zmax= zmin= sz=6. label#= unit#= tpow=0 epow=0 gpow=1 title= > plot.vpl
|-
| ''float '' || '''alpha=45.''' || || apparent angle in degrees, |alpha| < 89
|-
| ''bool '' || '''axis=y''' || [y/n] ||
|-
| ''bool '' || '''axis1=y''' || [y/n] ||
|-
| ''bool '' || '''axis2=y''' || [y/n] ||
|-
| ''bool '' || '''axis3=y''' || [y/n] || plot axis
|-
| ''int '' || '''axisfat=2''' || || axes fatness
|-
| ''int '' || '''axissz=6''' || || axes size
|-
| ''float '' || '''bias=0.''' || || subtract bias from data
|-
| ''float '' || '''clip=0.''' || || data clip
|-
| ''float '' || '''dclip=1.''' || || change the clip: clip *= dclip
|-
| ''bool '' || '''dflag=y''' || [y/n] || if y, plot down side of the surface
|-
| ''float '' || '''epow=0''' || || exponential gain
|-
| ''int '' || '''gainstep=0.5+nx/256.''' || || subsampling for gpow and clip estimation
|-
| ''float '' || '''gpow=1''' || || power gain
|-
| ''string '' || '''label#=''' || || label on #-th axis
|-
| ''bool '' || '''norm=y''' || [y/n] || normalize by the clip
|-
| ''float '' || '''pclip=100.''' || || data clip percentile
|-
| ''int '' || '''plotcoldn=VP_RED''' || || color of the lower side
|-
| ''int '' || '''plotcolup=VP_YELLOW''' || || color of the upper side
|-
| ''int '' || '''plotfat=0''' || || line fatness
|-
| ''float '' || '''ratio=5.''' || || plot adjustment
|-
| ''float '' || '''sz=6.''' || || vertical scale
|-
| ''string '' || '''title=''' || ||
|-
| ''int '' || '''titlefat=2''' || || title fatness
|-
| ''int '' || '''titlsz=9''' || || title size
|-
| ''string '' || '''tpow=0''' || || time power gain
|-
| ''bool '' || '''uflag=y''' || [y/n] || if y, plot upper side of the surface
|-
| ''string '' || '''unit#=''' || || unit on #-th axis
|-
| ''float '' || '''xc=1.5''' || ||
|-
| ''float '' || '''zc=3''' || || lower left corner of the plot
|-
| ''float '' || '''zmax=''' || ||
|-
| ''float '' || '''zmin=''' || ||
|}
==sfwiggle==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot data with wiggly traces.
|-
! colspan="4" | sfwiggle < in.rsf xpos=xpos.rsf xmax= xmin= poly=n fatp=1 xmask=1 ymask=1 pclip=98. zplot=0.75 clip=0. seemean=n verb=n transp=n yreverse=n xreverse=n xpos= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''float '' || '''clip=0.''' || || data clip (estimated from pclip by default
|-
| ''int '' || '''fatp=1''' || ||
|-
| ''float '' || '''pclip=98.''' || || clip percentile
|-
| ''bool '' || '''poly=n''' || [y/n] ||
|-
| ''bool '' || '''seemean=n''' || [y/n] || if y, plot mean lines of traces
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axes
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''int '' || '''xmask=1''' || ||
|-
| ''float '' || '''xmax=''' || || maximum trace position (if using xpos)
|-
| ''float '' || '''xmin=''' || || minimum trace position (if using xpos)
|-
| ''string '' || '''xpos=''' || || optional header file with trace positions
|-
| ''bool '' || '''xreverse=n''' || [y/n] || if y, reverse the horizontal axis
|-
| ''int '' || '''ymask=1''' || ||
|-
| ''bool '' || '''yreverse=n''' || [y/n] || if y, reverse the vertical axis
|-
| ''float '' || '''zplot=0.75''' || ||
|}
=Plotting programs (development)=
==sfplsurf==
<tt>sfplsurf</tt> utilizes PLplot's surface rendering capabilities. Output is dumped to stdout in VPLOT format, so it can easily be used in the same way as <tt>sfgrey</tt> or other plotting programs. It also supports animation, if n3 > 1 in the input file. A SConstruct usage example can be found below. A [http://reproducibility.org/wikilocal/movies/sfplsurf_membrane.mpg movie of the output] is available as well.

<python>
from rsf.proj import *

# x & y dimensions
o1=-2
o2=-2
n1=41
n2=41
d1=0.1
d2=0.1
# z dimension
o3=-1
n3=21
d3=0.1

Flow('membrane',None,
'''
math o1=%g o2=%g n1=%d n2=%d d1=%g d2=%g
o3=%g n3=%d d3=%g
output="x3*cos(x1*x1+x2*x2)*exp(-0.1*(x1*x1+x2*x2))"
''' % (o1,o2,n1,n2,d1,d2,o3,n3,d3))

Result('membrane',
'''
plsurf title="Membrane" mesh=n color=j
minval=%g maxval=%g
''' % (o3,o3 + d3*(n3-1)))

End()
</python>

=system/generic programs=
==sfremap1==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | 1-D ENO interpolation.
|-
! colspan="4" | sfremap1 < in.rsf > out.rsf pattern=pattern.rsf n1=n1 d1=d1 o1=o1 order=3
|-
| ''float '' || '''d1=d1''' || || Output sampling
|-
| ''int '' || '''n1=n1''' || || Number of output samples
|-
| ''float '' || '''o1=o1''' || || Output origin
|-
| ''int '' || '''order=3''' || || Interpolation order
|-
| ''string '' || '''pattern=''' || || auxiliary input file name
|}
To give an example of usage, we will create an input for <tt>sfremap1</tt> with:
<pre>
sfmath n1=11 n2=11 d1=1 d2=1 o1=-5 o2=-5 output="x1*x1+x2*x2" > inp2remap1.rsf
</pre>
Let us interpolate the data across both dimensions, then display it:
<pre>
< inp2remap1.rsf sfremap1 n1=1001 d1=0.01 | sftransp | \
sfremap1 n1=1001 d1=0.01 | sftransp | sfgrey allpos=y | sfpen
</pre>
The comparison with the uninterpolated data ( <tt>< inp2remap1.rsf sfgrey allpos=y | sfpen</tt> ) is quite telling.

=system/seismic programs=
==sfstretch==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Stretch of the time axis.
|-
! colspan="4" | sfstretch < in.rsf > out.rsf datum=dat.rsf inv=n dens=1 v0= half=y delay= tdelay= hdelay= nout=dens*n1 extend=4 mute=0 maxstr=0 rule=
|-
| ''file '' || '''datum=''' || || auxiliary input file name
|-
| ''float '' || '''delay=''' || || time delay for rule=lmo
|-
| ''int '' || '''dens=1''' || || axis stretching factor
|-
| ''int '' || '''extend=4''' || || trace extension
|-
| ''bool '' || '''half=y''' || [y/n] || if y, the second axis is half-offset instead of full offset
|-
| ''float '' || '''hdelay=''' || || offset delay for rule=rad
|-
| ''bool '' || '''inv=n''' || [y/n] || if y, do inverse stretching
|-
| ''float '' || '''maxstr=0''' || || maximum stretch
|-
| ''int '' || '''mute=0''' || || tapering size
|-
| ''int '' || '''nout=dens*n1''' || || output axis length (if inv=n)
|-
| ''string '' || '''rule=''' || || Stretch rule:
:n - normal moveout (nmostretch), default
:l - linear moveout (lmostretch)
:L - logarithmic stretch (logstretch)
:2 - t^2 stretch (t2stretch)
:c - t^2 chebyshev stretch (t2chebstretch)
:r - radial moveout (radstretch)
:d - datuming (datstretch)
|-
| ''float '' || '''tdelay=''' || || time delay for rule=rad
|-
| ''float '' || '''v0=''' || || moveout velocity
|}

<tt>sfstretch rule=d</tt> (aka <tt>sfdatstretch</tt>) can be used to apply statics. Here is a synthetic example, courtesy of Alessandro Frigeri:
<pre>
# generate a dataset with 'flat' signals
sfmath n1=200 n2=100 output="sin(0.5*x1)" type=float > scan.rsf

# generate a sinusoidal elevation correction
sfmath n1=100 output="3*sin(x1)" type=float > statics.rsf

# apply statics, producing a 'wavy' output.
sfstretch < scan.rsf > out.rsf datum=statics.rsf rule=d
</pre>

=user/fomels programs=
==sfpick==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Automatic picking from semblance-like panels.
|-
! colspan="4" | sfpick < scn.rsf > pik.rsf vel0=o2 niter=100 an=1. gate=3 smooth=y rect#=(1,1,...) rect1=1 rect2=1 ...
|-
| colspan="4" | rectN defines the size of the smoothing stencil in N-th dimension. Theory in Appendix B of: S. Fomel, 2009, Velocity analysis using AB semblance: Geophysical Prospecting, v. 57, 311-321. Reproducible version in RSFSRC/book/jsg/avo
|-
| ''float '' || '''an=1.''' || || axes anisotropy
|-
| ''int '' || '''gate=3''' || || picking gate
|-
| ''int '' || '''niter=100''' || || number of iterations
|-
| ''int '' || '''rect#=(1,1,...)''' || || smoothing radius on #-th axis
|-
| ''bool '' || '''smooth=y''' || [y/n] || if apply smoothing
|-
| ''float '' || '''vel0=o2''' || || surface velocity
|}
Short description of the algorithm:
# Start from the top (first time slice), pick an initial (source) point, evaluate all other points with the direct traveltime.
# At each grid point at the next level, find the traveltime to points at the previous level, add the traveltimes from the previous level, and select minimum. The search radius is limited by the aperture (gate= parameter in sfpick).
# Repeat step 2 until reaching the bottom.
# Pick the minimum traveltime at the bottom and track the ray back to the source by following the traveltime gradient direction.
# Postprocessing (smooth= parameter in sfpick): smooth the picked ray path using shaping regularization.

The algorithm was discovered and rediscovered by many people. The best reference is probably ''V. Meshbey, E. Ragoza, D. Kosloff, U. Egozi, and D. Wexler, 2002, Three-dimensional Travel-time Calculation Based on Fermat's Principle: Pure and Applied Geophysics, v. 159, 1563-1582.''

=user/ivlad programs=
==sfprep4plot==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Resamples a 2-D dataset to the desired picture resolution, with antialias
|-
! colspan="4" | sfprep4plot inp= out= verb=n h=none w=none unit= ppi= prar=y
|-
| colspan="4" | Only one of the h and w parameters needs to be specified. If prar=n, no action will be taken on axis for which h/w was not specified If prar=y and only one par (h or w) is specified, the picture will scale along both axes until it is of the specified dimension.
|-
| ''int '' || '''h=none''' || || output height
|-
| ''string '' || '''inp=''' || || input file
|-
| ''string '' || '''out=''' || || output file
|-
| ''int '' || '''ppi=''' || || output resolution (px/in). Necessary when unit!=px
|-
| ''bool '' || '''prar=y''' || [y/n] || if y, PReserve Aspect Ratio of input
|-
| ''string '' || '''unit=''' || || unit of h and w. Can be: px(default), mm, cm, in
|-
| ''bool '' || '''verb=n''' || [y/n] || if y, print system commands, outputs
|-
| ''int '' || '''w=none''' || || output width
|}
For a figure that does not need the aspect ratio preserved,
and needs to fill a 1280x1024 projector display:
<pre>
sfprep4plot inp=file1.rsf out=file2.rsf w=1280 h=1024 prar=n
</pre>
For a print figure that has to fit in a 6x8in box
at a resolution of 250 dpi, preserving the aspect ratio:
<pre>
sfprep4plot inp=file1.rsf out=file2.rsf w=6 h=8 unit=in ppi=250
</pre>
A comparison of images before and after the application of <tt>sfprep4plot</tt>, courtesy of Joachim Mispel, is shown below:

[[Image:sf_prep4plot.jpg]]

==sfcsv2rsf==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a delimited-text ASCII file to RSF binary floating point or int.
|-
! colspan="4" | sfcsv2rsf help=n delimiter=, dtype=float verb=n debug=n trunc=n o1=0. o2=0. d1=1. d2=1. unit1=unknown unit2=unknown label1=unknown label2=unknown
|-
| colspan="4" | Zeros will be added if number of elements is not the same in each row. n1 and n2 are computed automatically. For consistency with sfdisfil and sfmatmult, output is C-style order (row-first), i.e. rows in input file become dimension-1 columns in output. Output encoding is native.
|-
| ''float '' || '''d1=1.''' || ||
|-
| ''float '' || '''d2=1.''' || ||
|-
| ''bool '' || '''debug=n''' || [y/n] || Extra verbosity for debugging
|-
| ''string '' || '''delimiter=,''' || || Separator between values in input file
|-
| ''string '' || '''dtype=float''' || || Input type
|-
| ''bool '' || '''help=n''' || [y/n] ||
|-
| ''string '' || '''label1=unknown''' || ||
|-
| ''string '' || '''label2=unknown''' || ||
|-
| ''float '' || '''o1=0.''' || ||
|-
| ''float '' || '''o2=0.''' || ||
|-
| ''bool '' || '''trunc=n''' || [y/n] || Truncate or add zeros if nr elems in rows differs
|-
| ''string '' || '''unit1=unknown''' || ||
|-
| ''string '' || '''unit2=unknown''' || ||
|-
| ''bool '' || '''verb=n''' || [y/n] || Whether to echo n1, n2, infill/truncation
|}

A small usage example follow below. First, create an input file:

<bash>
$ echo -e '5,6,8,9.2\n11,124,5,0,1' | tee file.csv
5,6,8,9.2
11,124,5,0,1
</bash>

You may notice that the number of values in each row is different.

Run <tt>sfcsv2rsf</tt>. Notice that no options are needed. By default, zeros will be appended to make the rows equal length:

<bash>
$ <file.csv sfcsv2rsf > junk.rsf ; sfdisfil < junk.rsf
0: 5 6 8 9.2 0
5: 11 124 5 0 1
</bash>

Notice that sfdisfil displays in column order (i.e. matrix is transposed if the number of rows is right). The dimensions of the file are actually transposed on disk:

$ sfin junk.rsf
junk.rsf:
in="/data/path/junk.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0 unit1="unknown"
n2=2 d2=1 o2=0 unit2="unknown"
10 elements 40 bytes
</bash>

You may want to run the output through <tt>sftransp</tt>, depending on your needs. However, if creating an input for <tt>sfmatmult</tt>, this will not be necessary, because <tt>sfmatmult</tt> is made to work with matrices that are displayed with <tt>sfdisfil</tt>, and takes as input a transpose matrix.

Pipes can be used, of course, to skip the creation of intermediary files:

<bash>
$ <file.csv sfcsv2rsf | sfdisfil
0: 5 6 8 9.2 0
5: 11 124 5 0 1
</bash>

Note that since this program does not need any arguments (just stdin and stdout), when called with no arguments it will not display the man page. In order to consult the automatically generated documentation, you need to pass the option <tt>help=y</tt> .

=user/jennings programs=
==sfsizes==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display the size of RSF files.
|-
! colspan="4" | sfsizes files=y human=n file1.rsf file2.rsf ...
|-
| colspan="4" | Prints the element size, number of elements, and number of bytes for a list of RSF files. Non-RSF files are ignored.
|-
| ''bool '' || '''files=y''' || [y/n] || If y, print size of each file. If n, print only total.
|-
| ''bool '' || '''human=n''' || [y/n] || If y, print human-readable file size. If n, print byte count.
|}

This program computes the "theoretical" size in bytes of the data fork of RSF files. The actual space occupied on disk may be different and machine dependent due to disk blocking factors, etc. This theoretical array size should be reproducible. It is also fast because the program only reads the RSF headers files, not the actual data.

For example, to get the total size of all RSF files in a directory, in human readable format, without listing each file:
<pre>
sfsizes files=n human=y *.rsf
</pre>
This will also work because sfsizes simply skips any non-RSF file:
<pre>
sfsizes files=n human=y *
</pre>
==sffiglist==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Compare Vplot files in Fig and Lock directories
|-
! colspan="4" | sffiglist figdir= lockdir= list= show=
|-
| colspan="4" |
Parameter '''figdir''' is path to Fig directory, default is ./Fig.

 Parameter '''lockdir''' is path to Lock directory:
 If '''figdir''' is in $RSFSRC/book/[book]/[chapter]/[section],
 then default '''lockdir''' is $RSFFIGS/[book]/[chapter]/[section].
 If '''figdir''' is not in $RSFSRC/book/[book]/[chapter]/[section],
 then default '''lockdir''' is $RSFALTFIGS/[book]/[chapter]/[section].

 Parameter '''list''' controls files to list, default is all.
 Parameter '''show''' controls files to flip with sfpen, default is none.

 '''list|show''' = none (No files, print only summary.)
 '''list|show''' = diff (Files that are different, determined by sfvplotdiff.)
 '''list|show''' = miss (Files missing from figdir or lockdir, and different files.)
 '''list|show''' = all (All files.)

 File list codes:
 space indicates files that are the same.
 - indicates file in lockdir that is missing from figdir.
 + indicates extra file in figdir that is missing from lockdir.
 number is return code from sfvplotdiff indicating different files.
|-
| ''string '' || '''figdir=''' || || fig directory, default = ./Fig
|-
| ''string '' || '''list=''' || || how much to list [none,diff,miss,all], default = all
|-
| ''string '' || '''lockdir=''' || || lock directory, default = lock counterpart of figdir
|-
| ''string '' || '''show=''' || || how much to show [none,diff,miss,all], default = none
|}

This tool lists Vplot files in "Fig" and "Lock" directories and compares them using sfvplotdiff.

The Fig directory defaults to ./Fig and the Lock directory defaults to the
corresponding directory where "scons lock" puts things, but either
default can be overridden with the user parameters '''figdir''' and '''lockdir''' so that, for example,
files in two different Fig directories can be compared.

The default for the Lock directory has some logic to look in $RSFFIGS
when Fig is in $RSFSRC/book, or to look in $RSFALTFIGS when Fig is not
in $RSFSRC/book because I like to keep two different Lock directories:
one for stuff in book and another for my own stuff that is not in
book. However, I tried to make the code default to reasonable things
if any of these environment variables are not defined.

The tool gives a summary count of files that are the same, files that
are different, files in Fig that are missing from Lock, and files in
Lock that are missing from Fig.

The parameters '''list''' (default=all) and '''show''' (default=none) control which files are listed or "flipped" with sfpen. The file listing indicates which files are the same, which are different, and which are missing from Fig or Lock.

For example, to list all the Vplot files in Fig and Lock:
<pre>
sffiglist list=all
</pre>
To list all Vplot files and flip only files that are different:
<pre>
sffiglist list=all show=diff
</pre>

=user/psava programs=

==sfawefd2d==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | acoustic time-domain FD modeling
|-
! colspan="4" | sfawefd < Fwav.rsf vel=Fvel.rsf sou=Fsou.rsf rec=Frec.rsf wfl=Fwfl.rsf > Fdat.rsf den=Fden.rsf ompchunk=1 ompnth=0 verb=n snap=n free=n expl=n jdata=1 jsnap=nt nq1=sf_n(a1) nq2=sf_n(a2) oq1=sf_o(a1) oq2=sf_o(a2)
|-
| ''file '' || '''den=''' || || auxiliary input file name
|-
| ''bool '' || '''expl=n''' || [y/n] || "exploding reflector"
|-
| ''bool '' || '''free=n''' || [y/n] || free surface flag
|-
| ''int '' || '''jdata=1''' || ||
|-
| ''int '' || '''jsnap=nt''' || || save wavefield every *jsnap* time steps
|-
| ''int '' || '''nq1=sf_n(a1)''' || ||
|-
| ''int '' || '''nq2=sf_n(a2)''' || ||
|-
| ''int '' || '''ompchunk=1''' || || OpenMP data chunk size
|-
| ''int '' || '''ompnth=0''' || || OpenMP available threads
|-
| ''float '' || '''oq1=sf_o(a1)''' || ||
|-
| ''float '' || '''oq2=sf_o(a2)''' || ||
|-
| ''file '' || '''rec=''' || || auxiliary input file name
|-
| ''bool '' || '''snap=n''' || [y/n] || wavefield snapshots flag
|-
| ''file '' || '''sou=''' || || auxiliary input file name
|-
| ''file '' || '''vel=''' || || auxiliary input file name
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''file '' || '''wfl=''' || || auxiliary output file name
|}

An example will be demonstrated below on a model with nx=nz=200, dx=dz=4m (size: 800x800m). There are two layers: the first one is 100x200 samples in (z,x) and the velocity is 1500m/s; the second layer has the same dimension and the velocity is 3000m/s. Density is set to 1 for the whole grid. A source and a receiver are co-located at x=400 and z=100. The full wavefield for the entire model aperture will be saved every 10th time step.

<bash>
# Velocity model:
sfspike >Fvel.rsf mag=1500,3000 nsp=2 k1=1,101 l1=100,200 d1=4 d2=4 \
label1=z label2=x n1=200 n2=200 o1=2 o2=2 unit1=m unit2=m

# Density model:
sfspike >Fden.rsf mag=1 nsp=1 k1=1 l1=200 d1=4 d2=4 label1=z \
label2=x n1=200 n2=200 o1=2 o2=2 unit1=m unit2=m

# Source position (x,z):
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 >Fsou.rsf

# Receiver position (x,z):
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 >Frec.rsf

# Source wavelet:
sfspike nsp=1 n1=2000 d1=0.0005 k1=200 | sfricker1 frequency=20 |\
sftransp >Fwav.rsf

# Creating data at specified receiver + saving full wavefield every 10th step:
sfawefd2d <Fwav.rsf vel=Fvel.rsf sou=Fsou.rsf rec=Frec.rsf wfl=Fwfl.rsf \
den=Fden.rsf >Fdat.rsf verb=y free=y expl=y snap=y dabc=y jdata=1 jsnap=10
echo 'label1=z unit1=m label2=x unit2=m' >> Fwfl.rsf

# View the wavefield movie:
< Fwfl.rsf sfgrey gainpanel=a pclip=99 color=j scalebar=y | sfpen

# View a wavefield snapshot:
< Fwfl.rsf sfwindow f3=80 n3=1 |\
sfgrey pclip=99 color=j title='snapshot at t=0.4s' |\
sfpen

# View the data recorded at receiver:
<Fdat.rsf sfwindow |\
sfgraph title='Data recorded at receiver' unit2='' label2=amplitude |\
sfpen
</bash>

[[Image:sfawefd_wfld.jpg|frame|center|sfawefd wavefield screenshot]]
[[Image:sfawefd_dat.png|frame|center|sfawefd data screenshot]]

Attention: time steps that are too large can result in numerical instability.

==sfsrmig3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | 3-D S/R migration with extended SSF
|-
! colspan="4" | sfsrmig3 slo=Fs_s.rsf sls=Fs_r.rsf < Fw_s.rsf rwf=Fw_r.rsf > Fi.rsf cig=Fc.rsf ompchunk=1 ompnth=0 verb=y eps=0.01 twoway=n nrmax=1 dtmax=0.004 pmx=0 pmy=0 tmx=0 tmy=0 vpvs=1. hsym=n nht=1 oht=0 dht=0.1 nht=1 oht=0 dht=0.1 hsym=n nhh=1 ohh=0 dhh=0.1 nha=180 oha=0 dha=2.0 nhb=180 ohb=0 dhb=2.0 itype=
|-
| ''file '' || '''cig=''' || || auxiliary output file name
|-
| ''float '' || '''dha=2.0''' || ||
|-
| ''float '' || '''dhb=2.0''' || ||
|-
| ''float '' || '''dhh=0.1''' || ||
|-
| ''float '' || '''dht=0.1''' || ||
|-
| ''float '' || '''dtmax=0.004''' || || max time error
|-
| ''float '' || '''eps=0.01''' || || stability parameter
|-
| ''bool '' || '''hsym=n''' || [y/n] ||
|-
| ''string '' || '''itype=''' || || imaging condition type
:o = zero lag (default)
:e = extended
:x = space-lags
:h = space-lags magnitude
:t = time-lag
|-
| ''int '' || '''nha=180''' || ||
|-
| ''int '' || '''nhb=180''' || ||
|-
| ''int '' || '''nhh=1''' || ||
|-
| ''int '' || '''nht=1''' || ||
|-
| ''int '' || '''nrmax=1''' || || max number of refs
|-
| ''float '' || '''oha=0''' || ||
|-
| ''float '' || '''ohb=0''' || ||
|-
| ''float '' || '''ohh=0''' || ||
|-
| ''float '' || '''oht=0''' || ||
|-
| ''int '' || '''ompchunk=1''' || || OpenMP data chunk size
|-
| ''int '' || '''ompnth=0''' || || OpenMP available threads
|-
| ''int '' || '''pmx=0''' || || padding on x
|-
| ''int '' || '''pmy=0''' || || padding on y
|-
| ''file '' || '''rwf=''' || || auxiliary input file name
|-
| ''file '' || '''slo=''' || || auxiliary input file name
|-
| ''string '' || '''sls=''' || || auxiliary input file name
|-
| ''int '' || '''tmx=0''' || || taper on x
|-
| ''int '' || '''tmy=0''' || || taper on y
|-
| ''bool '' || '''twoway=n''' || [y/n] || two-way traveltime
|-
| ''bool '' || '''verb=y''' || [y/n] || verbosity flag
|-
| ''float '' || '''vpvs=1.''' || || Vp/Vs ratio
|}

This program performs 3-D and 2-D shot-record (a.k.a. shot-profile) migration with an extended Split-Step Fourier (SSF) extrapolator with multiple reference velocities (hence "extended"). It takes as input a shot wavefield (<tt>stdin</tt>), receiver wavefield (<tt>rwf=</tt>) and slowness model (<tt>slo=</tt>). Outputs are an image (<tt>stdout</tt>) and a cube of Common Image Gathers (<tt>cig=</tt>). An important parameter is <tt>nrmax</tt>, the number of reference velocities. Its default value is 1, but for reasonable results it should be 5 or so. It is also good to specify nonzero taper values (<tt>tmx</tt> and, for 3-D, <tt>tmy</tt> as well). The values of padding parameters <tt>pmx</tt> and <tt>pmy</tt> are split in two by the program, i.e. if your data x axis is 501-points long, specify pmx=11 to get a value of 512 that will result in fast Fourier Transforms.

The program will also migrate converted-wave data if a file with the S-wave slowness model (<tt>sls=</tt>) is provided.

The <tt>vpvs</tt> parameter is only used when <tt>itype=h</tt>. Do not specify a <tt>vpvs</tt> value unless you know really well what you are doing.

===Usage example===
The commands below, slightly modified from [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/data/sigsbee/ptest/SConstruct?revision=3993&view=markup RSFSRC/book/data/sigsbee/ptest], show how to prepare the [http://www.reproducibility.org/RSF/book/data/sigsbee Sigsbee 2A] data and velocity for migration.

Convert input data (shots) from SEG-Y to RSF:
<bash>
sfsegyread tape=sigsbee2a_nfs.segy tfile=tdata.rsf hfile=/dev/null bfile=/dev/null > ddata.rsf
</bash>
Convert trace headers to float (required by <tt>sfheadermath</tt>):
<bash>
< tdata.rsf sfdd type=float > trchdr.rsf
</bash>
Shot positions:
<bash>
< trchdr.rsf sfheadermath output="fldr + 10925/150" | sfwindow squeeze=y > tsi.rsf
</bash>
Extract offset positions from the trace header files, eliminate length-1 axis, scale, create a header for binning (required by <tt>sfintbin</tt>):
<bash>
< trchdr.rsf sfheadermath output="offset" |\
sfwindow squeeze=y |\
sfmath output="input/75" |\
sfcat axis=2 space=n tsi.rsf |\
sftransp |\
sfdd type=int > tos.rsf
</bash>
Binning and muting:
<bash>
< ddata.rsf sfintbin head=tos.rsf xkey=0 ykey=1 |\
sfput label1=Time unit1=s d2=0.075 o2=0.0 label2=hx d3=0.150 o3=10.925 label3=sx |\
sfmutter half=false t0=1.0 v0=6.0 |\
sfput d2=0.02286 o2=0 unit2=km d3=0.04572 o3=3.32994 unit3=km > shots.rsf
</bash>
Keeping only 20 shots so that this 1-node job will not take forever, FFT-ing, decimating frequency slices (same as shortening the time axis), and creating y and hy axes of length 1:
<bash>
< shots.rsf sfwindow n3=20 f3=10 j3=20 |\
sffft1 |\
sfwindow n1=200 min1=1 j1=3 |\
sfspray axis=3 n=1 o=0 d=1 label=hy |\
sfspray axis=5 n=1 o=0 d=1 label=sy > rfft.rsf
</bash>
The dimensions of the cube thus created are:
<pre>
$ sfin rfft.rsf trail=n
rfft.rsf:
in="/var/tmp/rfft.rsf@"
esize=8 type=complex form=native
n1=200 d1=0.25 o1=1 label1="Frequency" unit1="Hz"
n2=348 d2=0.02286 o2=0 label2="hx" unit2="km"
n3=1 d3=1 o3=0 label3="hy" unit3="km"
n4=20 d4=0.9144 o4=3.78714 label4="sx" unit4="km"
1392000 elements 11136000 bytes
</pre>
Create the source wavelet (limited to the same frequency band as the data) and Fourier transform it:
<bash>
sfspike k1=1 n1=1500 d1=0.008 |\
sfbandpass flo=15 fhi=25 |\
sffft1 |\
sfwindow n1=200 min1=1 j1=3 |\
sfput label1=freq > sfft.rsf
</bash>
This creates a frequency-domain wavelet:
<pre>
$ sfin sfft.rsf
sfft.rsf:
in="/var/tmp/sfft.rsf@"
esize=8 type=complex form=native
n1=200 d1=0.25 o1=1 label1="freq" unit1="Hz"
200 elements 1600 bytes
</pre>
Create "synched" source and receiver wavefields with <tt>srsyn</tt> from wavelet and data frequency slices. Basically both the receiver and shot frequency slices are "placed" at the right location and padded with zeros up to the dimension of the x axis specified below.
<bash>
< rfft.rsf sfsrsyn nx=1067 dx=0.02286 ox=3.05562 wav=sfft.rsf swf=swav.rsf > rwav.rsf
</bash>
This creates frequency slices ready for migration for both source and receiver, only axis 1 (frequency) must become axis 3, for both datasets:
<bash>
< swav.rsf sftransp plane=12 | sftransp plane=23 > stra.rsf
</bash>
<bash>
< rwav.rsf sftransp plane=12 | sftransp plane=23 > rtra.rsf
</bash>
This creates a surface receiver wavefield ready for input to migration. Axis 4 is shot number. The values of axis 4 are arbitrary because each shot has been padded with zeros so that it covers the entire velocity model. Therefore the aperture of the downward continuation for each shot will be as large as the survey.
<pre>
sfin trail=n rtra.rsf
rtra.rsf:
in="/var/tmp/rtra.rsf@"
esize=8 type=complex form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=200 d3=0.25 o3=1 label3="w" unit3="Hz"
n4=20 d4=1 o4=0 label4="e" unit4="km"
4268000 elements 34144000 bytes
</pre>
Convert the velocity model from SEG-Y to RSF, decimate, convert from feet to km, transpose, convert to slowness and insert an additional axis:
<bash>
sfsegyread tape=sigsbee2a_migvel.sgy tfile=/dev/null hfile=/dev/null bfile=/dev/null |\
sfput o1=0 d1=0.00762 label1=z unit1=km o2=3.05562 d2=0.01143 label2=x unit2=km |\
sfwindow j1=4 j2=2 |\
sfscale rscale=0.0003048 |\
sftransp |\
sfmath output="1/input" |\
sfspray axis=2 n=1 d=1 o=0 |\
sfput label2=y > slow.rsf
</bash>
This creates a slowness file ready for input to migration, with an x axis identical to the x axis of the wavefield files:
<pre>
$ sfin slow.rsf
slow.rsf:
in="/var/tmp/slow.rsf@"
esize=4 type=float form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=301 d3=0.03048 o3=0 label3="z" unit3="km"
321167 elements 1284668 bytes
</pre>
Finally, the migration command (for a 4-processor machine, hence the <tt>ompnth</tt> value). We choose not to compute any image gathers (<tt>itype=o</tt>), but due to the construction of the program we still have to explicitly assign the <tt>cig</tt> tag, or else a RSF file with the name of the tag and no rsf extension will be created:
<bash>
< stra.rsf sfsrmig3 nrmax=20 dtmax=5e-05 eps=0.01 verb=y ompnth=4 \
tmx=16 rwf=rtra.rsf slo=slow.rsf itype=o cig=/dev/null > img.rsf
</bash>
The migration of 20 shots takes approximately 3 hours on a 4-processor machine (1 shot=9 minutes). Without the frequency slice decimation by a factor of 3 and the depth axis decimation by a factor of 4, it would have taken twelve times as much. The resulting image has a y axis of length 1:
<pre>
$ sfin img.rsf trail=n
img.rsf:
in="/var/tmp/img.rsf@"
esize=4 type=float form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=301 d3=0.03048 o3=0 label3="z" unit3="km"
321167 elements 1284668 bytes
</pre>
To properly visualize the image, we need to eliminate the axis of length 1, then transpose the x and z axes to their natural position:
<bash>
<img.rsf sfwindow squeeze=y | sftransp | sfgrey > img.vpl
</bash>

=References=
<references/>

SEPlib to m8r dictionary

2012-11-08T03:06:09Z

Nick: /* Programs */ Wedge

[http://sep.stanford.edu/doku.php?id=sep:software:seplib SEPlib] is a software package for seismic data processing developed at the [http://sep.stanford.edu/doku.php Stanford Exploration Project]. The dictionary below is intended for SEPlib users who are interested in either using Madagascar (m8r) or in finding out which algorithms/utilities are present in m8r, but not in SEPlib.

A m8r program, or a chain of m8r programs, will be considered equivalent to a SEPlib counterpart only if it has at least all the capabilities of its SEPlib counterpart. The fact that two of [http://sepwww.stanford.edu/data/media/public/sep/prof/index.html Claerbout's books] (''Basic Earth Imaging'' and ''Imaging Estimation by Example'') and several SEP report articles have been [[Reproducible_Documents | reproduced with Madagascar]] shows that at least a significant subset of SEPlib is fully translatable. Individual programs may not be equivalent option-for-option. Like Lego blocks, they come together only when data flow examples are created from them, and such flows can certainly made fully equivalent even if the "building blocks" may differ slightly.

The starting point of the list below was the list of manual pages in SEPlib 6.5.3 (<tt>docs/man/man{1,3}/*.mn</tt> in the source code distribution). For programs, those files starting with a capital leter (the SEPlib convention for program names) were considered.

==Programs==
* 5dFFT
* Agc: [http://www.ahay.org/RSF/sfagc.html sfagc]
* AMO: [http://www.ahay.org/RSF/sffkamo.html sffkamo]
* Aniso2d
* Attr3dhead: [http://www.ahay.org/RSF/headerattr.html sfheaderattr]
* Attr: [http://www.ahay.org/RSF/sfattr.html sfattr]
* Balance
* Box: [http://www.ahay.org/RSF/sfbox.html sfbox]
* Byte: [http://www.ahay.org/RSF/sfgrey.html sfgrey] (with appropriate options -- what are those?)
* CAM: [http://www.ahay.org/RSF/sfcamig3.html sfcamig3]
* Cfft: [http://www.ahay.org/RSF/sffft3.html sffft3]
* Contour: [http://www.ahay.org/RSF/sfcontour.html sfcontour]
* Cp3d
* Cp: [http://www.ahay.org/RSF/sfcp.html sfcp]
* Create3d
* Cubeplot: [http://www.ahay.org/RSF/sfgrey3.html sfgrey3]: <tt>Cubeplot out=file.H >/dev/null</tt> is equivalent to <tt>sfgrey3 > file.rsf</tt>, and <tt>Cubeplot | Tube</tt> is equivalent to <tt>sfgrey3 | sfpen</tt>
* Dd: see Sdd
* Dip_azim
* Dip: [http://www.ahay.org/RSF/sfdip.html sfdip]
* Dis3dhead
* Disfil: [http://www.ahay.org/RSF/sfdisfil.html sfdisfil]
* Dots: [http://www.ahay.org/RSF/sfdots.html sfdots]
* Edit
* Energy
* Envelope: [http://www.ahay.org/RSF/sfenvelope.html sfenvelope]
* Fdmod2: [http://www.ahay.org/RSF/sfawefd2d.html sfawefd2d]
* Filter: [http://www.ahay.org/RSF/sfconv.html sfconv]
* FMeikonal: [http://www.ahay.org/RSF/sfeikonal.html sfeikonal]
* Fold3d
* Ft3d
* Ftplot
* Fx2d
* Gauss
* Get: [http://www.ahay.org/RSF/sfget.html sfget]
* Gfgradz
* Graph: [http://www.ahay.org/RSF/sfgraph.html sfgraph]
* Grey: [http://www.ahay.org/RSF/sfgrey.html sfgrey]: <tt>Grey out=file.H >/dev/null</tt> is equivalent to <tt>sfgrey > file.rsf</tt>, and <tt>Grey | Tube</tt> is equivalent to <tt>sfgrey | sfpen</tt>
* Grid_fold
* Halfint: [http://www.ahay.org/RSF/sfhalfint.html sfhalfint]
* Headermath: [http://www.ahay.org/RSF/sfheadermath.html sfheadermath]
* Helicon: [http://www.ahay.org/RSF/sfhelicon.html sfhelicon]
* Histogram: [http://www.ahay.org/RSF/sfhistogram.html sfhistogram]
* Hwt3d: [http://www.ahay.org/RSF/sfhwt3d.html sfhwt3d]
* Hypint: [http://www.ahay.org/RSF/sfveltran.html sfveltran]
* Hypmovie
* Hypsum
* In: [http://www.ahay.org/RSF/sfin.html sfin]
* In3d
* Interleave: [http://www.ahay.org/RSF/sfinterleave.html sfinterleave]
* Interp
* Iso2d
* Kirch_2d_depth
* Kirmod3d: [http://www.ahay.org/RSF/sfkirmod3.html sfkirmod3]
* Log
* Lpfilt: [http://www.ahay.org/RSF/sfbandpass.html sfbandpass]
* Marine_geom3d
* Math: [http://www.ahay.org/RSF/sfmath.html sfmath]
* MCvfit
* Median: [http://www.ahay.org/RSF/sfmedian.html sfmedian]
* Merge: [http://www.ahay.org/RSF/sfmerge.html sfmerge]
* Miss: [http://www.ahay.org/RSF/sfmiss.html sfmiss]
* MTTmaps
* Mute3d
* Mute: [http://www.ahay.org/RSF/sfmutter.html sfmutter]
* Mv3d
* Mv: [http://www.ahay.org/RSF/sfmv.html sfmv]
* Nmo3d
* Noise: [http://www.ahay.org/RSF/sfnoise.html sfnoise]
* OFF2ANG: [http://www.ahay.org/RSF/sfradon.html sfradon] or [http://www.ahay.org/RSF/sfslant.html sfslant], followed by [http://www.ahay.org/RSF/sftan2ang.html sftan2ang].
* Operplot
* Overlay
* Pad: [http://www.ahay.org/RSF/sfpad.html sfpad] for padding with zeros, or [http://www.ahay.org/RSF/sfspray.html sfspray] for extending with the last value. Using sfspray directly will result in extending over an additional axis. To have an actual equivalent to Pad with extend option (extension across the same axis), sfspray can be used together with sfcat, i.e.: <tt>< inp.rsf sfwindow f2=-1 | sfspray axis=2 n=10 | sfcat axis=2 order=2,1 inp.rsf > out.rsf</tt>
* Pef: [http://www.ahay.org/RSF/sfpef.html sfpef]
* Phase: [http://www.ahay.org/RSF/sfsrmig3.html sfsrmig3] or [http://www.ahay.org/RSF/sfcamig3.html sfcamig3]
* Reshape
* Reverse: [http://www.ahay.org/RSF/sfreverse.html sfreverse]
* Rickmovie
* Ricksep
* Rm3d
* Rm: [http://www.ahay.org/RSF/sfrm.html sfrm]
* Scale: [http://www.ahay.org/RSF/sfscale.html sfscale]
* Scat3d
* Scat
* Sdd: [http://www.ahay.org/RSF/sfdd.html sfdd], with option <tt>type=</tt> controlling the output (instead of <tt>esize=</tt>)
* Segy2sep: [http://www.ahay.org/RSF/sfsegyread.html sfsegyread]
* Seis_vel
* Sep2segy: [http://www.ahay.org/RSF/sfsegywrite.html sfsegywrite]
* Sep2su: [http://www.ahay.org/RSF/sfsegywrite.html sfsuwrite, aka sfsegywrite su=y]
* Smooth: [http://www.ahay.org/RSF/sfsmooth.html sfsmooth]
* Spectra: [http://www.ahay.org/RSF/sfspectra.html sfspectra]
* Spike: [http://www.ahay.org/RSF/sfspike.html sfspike]
* SRM
* Stack3d
* Stolt: [http://www.ahay.org/RSF/sfstolt.html sfstolt]
* Stretch: [http://www.ahay.org/RSF/sfstretch.html sfstretch]
* Su2sep: [http://www.ahay.org/RSF/sfsegyread.html sfsuread, aka sfsegyread su=y]
* Surface
* Synch3d
* Ta2vplot: [http://ahay.org/RSF/sfgrey.html sfgrey]
* Thplot: [http://ahay.org/RSF/sfthplot.html sfthplot]
* Tpow: [http://www.ahay.org/RSF/sftpow.html sftpow]
* Transf
* Transp: [http://www.ahay.org/RSF/sftransp.html sftransp]
* Trcamp
* Tube: sfpen
* Vconvert
* Velan3d
* Velan: [http://www.ahay.org/RSF/sfvscan.html sfvscan]
* Vel: [http://www.ahay.org/RSF/sfmakevel.html sfmakevel]
* Wavelet
* Wedge: [http://www.ahay.org/RSF/sfspray.html sfspray]: <tt>Wedge axis= nn= oo= dd=</tt> is equivalent to <tt>sfspray axis= n= o= d=</tt>
* Wiggle: [http://www.ahay.org/RSF/sfwiggle.html sfwiggle]
* Window3d
* Window_key: [http://www.ahay.org/RSF/sfheaderwindow.html sfheaderwindow]
* Window: [http://www.ahay.org/RSF/sfwindow.html sfwindow]

==Library procedures==
* adj_mod
* alloc
* array
* autocorr
* auxclose
* auxpar
* auxputch
* auxputhead
* binpull1
* binpull2
* bound
* boxconv
* box
* broyden_mod
* burg2
* burg
* butter
* c2h
* cadd
* cartesian
* causint
* cdiv
* cdoubint
* cdstep
* cefft
* cent
* cexp
* cgmeth
* cgstep
* chain
* ciexp
* cinv
* clog
* cmplx
* cmult
* cneg
* compress
* conjg
* conjgrad
* conv
* copy_data_pointer
* copy_history
* createhelix
* createmshelix
* createnhelix
* cross_wilson
* csmult
* cspow
* csqrt
* csub
* cvfft
* datapath
* ddot
* doc
* dottest
* energy
* evaluate_expression
* fastmarch
* fetch
* finish_susep
* fold
* fullnm
* gauss
* getch_add_string
* getch
* h2c
* halfdifa
* hclose
* hconest
* helderiv
* heliarr
* helicon
* helixcartmod
* helix
* hetch
* hwt_trace_rays
* hwt_travel_cube
* igrad1
* igrad2
* init_3d
* initpar
* init_sep3d
* init_sep3d_par
* init_sep3d_tag
* integer
* interpolate_mod
* invint2
* irls
* lapfac
* lint1
* lint2
* lopef
* lsqr
* make_unpipe
* matmult
* misinput
* mshconest
* mshelicon
* nbound
* nhconest
* nhelicon
* nhelix
* nmis2
* nmo_mod
* nonlin_solver
* npef
* npolydiv
* pad_it
* partan
* patch
* pefest
* pef
* polydiv
* pqueue
* print_sep3d
* putch
* puthead
* quantile
* quick_sort
* refft
* refine2
* regrid
* rms2int
* rvfft
* sep3d_add_drn
* sep3d_axes_allocate
* sep3d_axis_index
* sep3dc_clean
* sep3dc_collect_data
* sep3dc_collect_headers
* sep3dc_conform
* sep3dc_coord_copy
* sep3dc_copy
* sep3dc_delete
* sep3dc_desection_tag
* sep3dc_distribute_data
* sep3dc_distribute_headers
* sep3dc_ge_space
* sep3dc_grab_grid_values
* sep3dc_grab_headers
* sep3dc_grab_key_vali
* sep3dc_grab_key_vals
* sep3dc_grid_copy
* sep3dc_header_copy
* sep3dc_inorder
* sep3dc_key_index
* sep3dc_local_buffer_size
* sep_3d_close
* sep3dc_ndims
* sep3d_collect_data
* sep3d_collect_headers
* sep3d_conform
* sep3d_copy
* sep3dc_read_data
* sep3dc_reshape
* sep3dc_rite_num_traces
* sep3dc_section_tag
* sep3dc_set_grid_values
* sep3dc_set_key_vals
* sep3dc_set_number_headers
* sep3dc_update_ntraces
* sep3dc_write_description
* sep3dc_write_status
* sep3d_desection
* sep3d_distribute_data
* sep3d_distribute_headers
* sep3df
* sep3d_ge_space
* sep3d_grab_coords
* sep3d_grab_grid_values
* sep3d_grab_headers
* sep3d_grab_key_vals
* sep3d_grab_sect_param
* sep3d_grab_sep3d
* sep3d_grid_copy
* sep3d_header_copy
* sep3d_initialize
* sep3d_key_allocate
* sep3d_key_index
* sep3d_local_buffer_size
* sep3d_ndims
* sep3d_own
* sep3d_read_data
* sep3d_reshape
* sep3d_rite_num_traces
* sep3d_section
* sep3d_section_tag
* sep3d_set_coords
* sep3d_set_key_vals
* sep3d_set_number_headers
* sep3d_set_sect_param
* sep3d_set_sep3d
* sep3d_store_grid_values
* sep3d_synch
* sep3d_update_ntraces
* sep3d_with_drn
* sep3d_write_data
* sep3d_write_description
* separg
* sep_copy_gff
* sep_copy_grid
* sep_copy_header_keys
* sep_copy_hff
* seperr
* sep_extract_val_by_index
* sep_get_data_axis_par
* sep_get_grid_axis_par
* sep_get_grid_window
* sep_get_header_axis_par
* sep_get_key_fmt
* sep_get_key_index
* sep_get_key_name
* sep_get_key_type
* sep_get_number_data_axes
* sep_get_number_grid_axes
* sep_get_number_header_axes
* sep_get_number_keys
* sep_get_val_by_index
* sep_get_val_by_name
* sep_get_val_headers
* sep_put_data_axis_par
* sep_put_grid_axis_par
* sep_put_grid_window
* sep_put_header_axis_par
* sep_put_key
* sep_put_number_keys
* sep_put_val_by_index
* sep_put_val_headers
* sep_reorder_data_fast
* sep_reorder_data
* sep_set_no_grid
* sep_set_no_headers
* sepwarn
* sgainpar
* signoi
* slice
* solver
* solver_prec
* solver_reg
* spp
* sqroot
* sreed
* sreed_window
* srite
* srite_window
* sseek_block
* sseek
* ssize_block
* ssize
* steepdip
* steering
* tgettr
* tputtr
* triangle1
* triangle2
* triangle
* valid_structure
* velan_subs_mod
* velsimp
* veltran
* weicam_init
* weight
* weihcig_init
* weihcig
* weipcig_init
* weipcig
* weisll_init
* weisll
* weissf_init
* weissf
* weiwem_init
* weiwem
* wilson

Code Projects

2012-10-07T20:43:38Z

Nick: svgpen

If you are a software developer, you can help Madagascar with one of the following projects:

===Binary packages===

For ease of installation, we would like to distribute Madagascar not only in the source form but also in binary packages. This is [https://sourceforge.net/p/rsf/feature-requests/5/ Feature Request #5].

* RPM

See [[Packaging_madagascar|Instructions for creating Fedora RPM]].

* Debian
* Macports
* Cygwin

===XTpen replacement===

The default viewing program for Linux, '''xtpen''', depends on the Athena sidget set ([http://en.wikipedia.org/wiki/Xaw libXaw library]). The <tt>libXaw</tt> library is no longer supplied by default with common Linux distributions. Therefore, it would be good to replace <tt>xtpen</tt> with a program of similar functionality that would built with the libraries supplied out of the box.

An alternative viewing program, '''oglpen''', depends on [http://en.wikipedia.org/wiki/Opengl OpenGL] which is also not always available. '''x11pen''' depends only on the core X libraries but is broken.

See also [https://sourceforge.net/p/rsf/feature-requests/34/ Feature Request #34] for '''aquapen''' on Macs.

===Interactivity===

At the 2011 [[Houston 2011|workshop in Houston]], Joe Dellinger presented a [http://www.beg.utexas.edu/pttc/2011/2011_pres_02_07_dellinger.pdf detailed plan] for adding interactivity to Vplot graphics. Someone needs to follow the plan and implement the suggested changes. The currently broken elementary interactivity in '''xtpen''' is [http://sourceforge.net/p/rsf/bugs/8/ Bug #8].

===3D viewer===

Sometimes interactive capabilies are needed not to produce reproducible results but simply to quickly browse through the data. A 3-D interactive viewer for RSF files could be a standalone program simplifying data browsing.

[http://www.ahay.org/RSF/sfthreedcube.html sfthreedcube] is a start.

===svgpen===
Add a svgpen to vplot, so vplot-based utilities can output SVG files that use png or jpg for the raster background parts. Then any web browser can be used as a viewer, and interactivity can be added via javascript.

Download

2012-10-07T20:36:17Z

Nick: /* Current development version */ new download procedure for developers

[[Image:Fotolia_2043821_XS.jpg|right|]]
You can choose to download either the latest stable release, or the current development version (frequently updated).

==Stable release==

[http://sourceforge.net/projects/rsf/files/ Download the source code distribution from Sourceforge], then unpack the directory with
<pre>gunzip < madagascar-*.tar.gz | tar xvf -</pre>
or
<pre>bunzip2 < madagascar-*.tar.bz2 | tar xvf -</pre>
The <tt>bz2</tt> file is a bit smaller, but takes longer to unpack.

Next, follow [[Installation|Installation instructions]] to install.

==Current development version==

To download the most recent Madagascar source code, you need to have a [http://subversion.apache.org/ Subversion client] (<tt>svn</tt>) installed. If you want to download it read-only, run the following command:
<pre>
svn co <nowiki>http://svn.code.sf.net/p/rsf/code/trunk</nowiki> RSFSRC
</pre>
Replace <tt>RSFSRC</tt> with the path where you want to put the Madagascar source code.
If you are a Madagascar project contributor and you want to download it in read-write mode, use
<pre>
svn co \
--username=<your_sourceforge_username> \
svn+ssh://<your_sourceforge_username>@svn.code.sf.net/p/rsf/code/trunk \
RSFSRC
</pre>

Next, follow [[Installation|Installation instructions]] to install.

You can also [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/ browse the Subversion repository].

===Updating===

To update the Madagascar source code on your computer with the changes made by developers, <tt>cd</tt> to the directory where you placed the sources and run
<pre>
svn update
</pre>

===Troubleshooting===

*If, after running the <tt>svn co...</tt> command, nothing happens, no message, no return to the command line: you may be behind a proxy. This is especially likely if your computer is on a corporate Intranet. To get past a proxy, you need to tell Subversion: (1) The IP number or URL of the proxy and (2) the port that will allow <tt>svn</tt> through – most likely 80, the standard HTTP port. Open your <tt>~/.subversion/servers</tt> file in a text editor. If this file does not exist, running any <tt>svn</tt> command (even an unsuccessful one, like the one above) will automatically create the file. In the <tt>[global]</tt> section, add the following lines, with your own proxy URL and port names instead of the dummy ones below:
<pre>http-proxy-host = www-proxy.yourcompany.com
http-proxy-port = 80
</pre> Now your <tt>svn</tt> commands should work. You can find more details [http://subversion.tigris.org/faq.html#proxy in the Subversion documentation]. It would also be a good idea to set in your <tt>.bashrc</tt> or <tt>.cshrc</tt> the environment variable <tt>HTTP_PROXY</tt> to your adaptation of <pre>http://www-proxy.yourcompany.com:80</pre> so that input datasets for reproducible figures can be downloaded automatically when you need them.

*If you get a "is already a working copy for a different URL" error, this means you have an existing directory downloaded from another server. Run <tt>svn switch --relocate</tt> to switch servers.

*If you are using an old Linux distribution (e.g. RedHat 9), the version of Subversion included with your distribution may need to be updated to handle the secure URL (<nowiki>https://</nowiki>). If <tt>svn</tt> complains about an "unrecognized URL scheme" (and you've given it the correctly formatted URL), then you need to update it.

*If you are behind a firewall, you may need to set up more variables in your file <tt>~/.subversion/servers</tt> (check with your IT support for all the required variables to get past the proxy) as for example
<pre>
[global]
http-proxy-host = proxy-host-company.site.corp
http-proxy-port = 1111
http-proxy-username = Yourusernameforproxy
http-proxy-password = Yourpasswordforproxy
</pre>
It would be a good idea then to protect your file <tt>~/.subversion/servers</tt> from being read by others.

==Other packages==
There are two other packages that might be useful in conjunction with RSF:
===Reproducible figures===

Using Subversion, run
<pre>svn co http://svn.code.sf.net/p/rsf/code/figs $RSFROOT/share/madagascar/figs </pre>
This installs a wide collection of more than 5,000 reproducible figures. It may take a long time to download and more than 6 Gb of disk space.
The figures are preserved with the purpose of regression testing whenever the software or the environment change.

You can reproduce the figures (excluding those generated with proprietary data or additional software) by running <tt>scons lock</tt> in individual project directories or by going to <tt>RSFSRC</tt> and running
<pre>sfbooklist command="scons lock" book</pre>

===LATEX package===

[[SEGTeX]] is a LaTeX package for geophysical publications. It can be used with madagascar for writing [[Reproducible Documents|reproducible papers]].

Adding new programs to Madagascar

2012-08-15T23:33:11Z

Nick: /* Wiki documentation */ updated path

[[Image:Fotolia_800161_XS.jpg|right|]]
Whether you want to share your work with the world or keep it for yourself, madagascar is fully extensible. The following instructions explain the simplest way to add your own programs to the package.

==How to add your program==

#Create a directory for yourself or your group under <tt>RSFSRC/user</tt>, where <tt>RSFSRC</tt> is the top source directory. Put your programs there.
#The following conventions are adopted:
#*Files containing main programs start with <tt>M</tt>, i.e. <tt>Mmyprog.c</tt> or <tt>Mmyprog.py</tt>. Each main program file should start with a short one-line comment describing its purpose.
#*Files containing subroutines start with small letters. A header/interface file <tt>myprog.h</tt> is automatically generated from <tt>myprog.c</tt>. By using header files, dependencies between different functions will be figured out automatically. Include a comment of the form /*^*/ after any block of text that you want to be included in the header file. ''Such blocks must not contain any all-whitespace lines.'' Include a comment of the form /*< My function description >*/ after a function definition if you want its interface included in the header file. It is a good habit to comment interfaces to all your functions.
#Create a <tt>SConstruct</tt> file in your directory by following examples from other <tt>user</tt> directories. Inside the triple quotation marks after <tt>progs=</tt>, replace the names of their programs with the names of your programs with spaces between the names.
#Note that running <tt>scons</tt> inside your <tt>user</tt> directory compiles programs with debugging flags to make them suitable for debugging with common debuggers such as [http://www.gnu.org/software/gdb/ gdb], dbx, or [http://www.etnus.com/ TotalView]. Running <tt>scons install</tt> inside the top source directory will compile your programs with optimization flags and install them in <tt>$RSFROOT</tt>.

==How to share your program with others==

Follow the guide on [[Contributing new programs to Madagascar]].

==How to document your program==
There are three levels of documentation. From the most simple to the most complex, they are: in-code documentation, the Wiki, and reproducible papers.
===In-code documentation===
Of course, do comment your code -- focusing on "why" (the code itself describes the "how"). Keep comments sparse so that as much code as possible can be kept in mind at the same time by the human reader. Use the other levels for more information.

If you follow a certain syntax for some of your comments, then the scripts in the Madagascar framework will be able to automatically produce a self-doc page for your program. This page will be displayed in the terminal (using basic text-mode formatting) when the program is invoked without any arguments, and a HTML version will be automatically generated in $RSFDOC (default: $RSFROOT/doc). The self-doc page has the following sections: <tt>Name</tt>, <tt>Description</tt>, <tt>Synopsis</tt>, <tt>Comments</tt>, <tt>Parameters</tt>, <tt>Used in</tt>, <tt>Source</tt> and <tt>Version</tt>.
====Self-doc for C programs====
To automatically populate the <tt>Description</tt> and <tt>Comments</tt> sections, use the following syntax. Start the file with:
<c>
/* Short description line
Comments here blablabla lorem ipsum dolores sit amet...

You can use several paragraphs for comments, no problem.*/

/* Copyright notice */
</c>
Notice that: (1) the description line is the first line in the file; (2) Comments are closed and then open again on a new line for Copyright (so that Copyright does not show up in the documentation).

To make input parameters and their default values (if they exist) automatically appear in the <tt>Synopsis</tt> and <tt>Parameters</tt> sections, make sure to read the parameters in the code like in the following example:
<c>
if (!sf_getbool("su",&su)) su=false;
/* y if input is SU, n if input is SEGY */
</c>
Notice that there are no complex logical operations inside the <tt>if</tt>, that there is no space between the equal sign and the right and left hand, and that a short comment follows immediately. If by necessity the parameter is read in a complex fashion, use angular brackets inside the short line following the read block, i.e.:
<pre>
... sf_getfloat ... complex stuff ...
/*< parameter_name parameter meaning >*/
</pre>

====Self-doc for Python programs====
To automatically populate the <tt>Description</tt> page, and <tt>Comments</tt> sections, use the following syntax. Start the file with:
<python>
#! /usr/bin/env python
'''My one-line description of this program
If I have comments, put them in the lines below.

I can use several paragraphs for that'''

# Copyright notice...
</python>
Then, make sure to
<python>
import rsfprog
</python>
To make input parameters and their default values (if they exist) automatically appear in the <tt>Synopsis</tt> and <tt>Parameters</tt> sections, make sure to follow each argument read with a comment, and call <tt>selfdoc</tt> if no argument was given. Here is an example from <tt>user/ivlad/Mpclip.py</tt>:
<python>
par = rsf.Par(argv)

inp = par.string('inp') # input file
out = par.string('out') # output file
if None in (inp, out):
rsfprog.selfdoc() # self-doc
return error

verb = par.bool('verb', False) # if y, print system commands, outputs
</python>

====Self-doc for Fortran 90 programs====
To automatically populate the <tt>Description</tt> section (<tt>Comments</tt> is not available), use the following syntax. Start the file with:
<pre>
! One-line short description, leave a blank line after it

! Copyright notice...
</pre>

To make input parameters and their default values (if they exist) automatically appear in the <tt>Synopsis</tt> and <tt>Parameters</tt> sections, make sure to read the parameters in the code like in the following example:
<pre>
call from_par( "n1", nt, 512 ) ! Param description on same line or first line after
</pre>

===Wiki documentation===
The self-doc is good as a reminder of what the parameters mean and what their default values are, but more is usually needed for someone who never used the tool. This is what the [[Guide to madagascar programs|Guide to programs]] is for. Whenever you change or create a program, make sure to add a section for it in there too, if possible with an implementation section. Documenting programs that already exist is also a great idea.

You may have noticed that each program section on that page starts with a table that has the same content as the self-doc. That is created automatically the following way. Say you want to create this table for <tt>sfattr</tt>. At a command line, type:
<pre>
sfdoc -m $HOME attr
</pre>
This will create the file <tt>$HOME/sfattr.wiki</tt>. Its content can be copied and pasted into the Madagascar wiki, as they already are in the MediaWiki format. Another directory can be used instead of $HOME.

If your program/script reads an environment variable, make sure you check [[Advanced Installation#Environment variables|the list of environment variables used by Madagascar]] and add your new variable or your peculiar usage of an existing variable.

After creating the appropriate section in the [[Guide to madagascar programs|Guide to programs]], add your program name without the <tt>sf</tt> prefix to the <tt>docprogs</tt> list at the beginning of <tt>RSFSRC/framework/rsf/doc.py</tt> . This will ensure that a link to the wiki section is created in the auto-generated HTML program page in <tt>$RSFDOC</tt>.

Add your program to the [[Task-centric program list]] so that it can be found by those users who do not already know they need it.

===Reproducible documents===
<tt>Madagascar</tt> programs are tested and illustrated by means of [[Reproducible_Documents|reproducible documents]]. See the [[Reproducible computational experiments using SCons|Guide to SCons interface for reproducible computations]] for a brief explanation of what a reproducible paper is and how to produce one.

==Style guide==
* Use components (macros, types, functions) from the Madagascar library to maximize component reuse and to make sure you do not reinvent the wheel. Be familiar with the [[Library Reference]].
* User interface convention: if your program provides a verbosity option, use <tt>verb=n [y/n]</tt>
* Do not keep commented code in your program. This does not refer to writing comments about code, but to commenting out actual code. You can always use the version control system to retrieve the older version
* Initialize all pointers (including variables of type <tt>sf_file</tt>) with NULL
* If you have one or more calls to <tt>sf_input</tt> in your program, call <tt>sf_close</tt> before exit to avoid file leaks (temporary files left in $DATAPATH after an operation involving pipes)

==How to test your program==
The testing mechanism is semi-automatic. Testing can be done for any program that is used in a reproducible document in the <tt>RSF/book</tt> directory. To test whether the change you made in a program called, say, <tt>sfmyprog</tt> introduced any new bugs, make sure you have the latest set of stored figures from the [[Installation#RSF_reproducible_figures|figures repository]] and do the following:

#<tt>cd RSF/book</tt>
#Run <pre>scons sfmyprog.test</pre> If the error messages are not helpful you can omit them from the console, but keep them in a file like this (sh): <pre>scons sfmyprog.test 2> sfmyprog.test.err</pre> or like this (csh): <pre>(scons sfmyprog.test > /dev/stdin) >& sfmyprog.test.err</pre>
#If testing fails, find the directory and figure where failure happened from the "<tt>Comparing ... and ...</tt>" statement just before the beginning of the error messages. The directory name will appear before that in a line "<tt> Testing in ...</tt>". <tt>cd</tt> to that directory. Let's say the figure that failed is called <tt>myfig.vpl</tt>. Run <pre>scons myfig.flip</pre> That will open a graphical display window that will quickly alternate between the stored figure and your figure.
#* If the figures look identical, then it means the differences are due to rounding errors and other insignificant differences between platforms (work is done on improving the comparison mechanism). Load your figure into your copy of the figures repository with <pre>scons myfig.lock</pre>
#* If you see differences between the two figures, then it is time to debug your program.

==Tips and tricks==
===Backups===
You may want to back up only your developer directory, not the entire Madagascar source tree. If you do not want to or do not have the permissions to change the backup scripts, you will need to make your RSF user directory a link to somewhere else. To get that to work, you need to modify your <tt>username/SConstruct</tt>. First thing in the file, define
<python>
RSF_src_root = '/path/to/madagascar/source/root/'
</python>
Then, replace <tt>../..</tt> throughout the SConstruct with
<python>
os.path.join(RSF_src_root,'whatever_followed_after_dotdots')
</python> .

===External libraries===
To link your programs to an external library, add to the <tt>env.Prepend</tt> statement in <tt>username/Sconstruct</tt>
the paths to its <tt>include</tt> dir, <tt>lib</tt> dir and the name of the library you are linking to.

===Emacs customization===

If you use [http://www.gnu.org/software/emacs/ Emacs], the following might be helpful.

* Install the [http://www.emacswiki.org/cgi-bin/wiki/PythonMode python mode] (if you don't have it installed already) and put
<lisp>
(setq auto-mode-alist
(cons '("SConstruct" . python-mode) auto-mode-alist))
</lisp>
:in your <tt>.emacs</tt> file to enable it on <tt>SConstruct</tt> files.

* Put
<lisp>
(set-default 'compile-command "scons")
</lisp>
:in your <tt>.emacs</tt> file to have <tt>scons</tt> as the default compile command.

* Use
<lisp>
(add-hook 'c-mode-common-hook
'(lambda () (c-set-style "linux")
(c-set-offset 'case-label 4)
(setq c-basic-offset 4)))
</lisp>
:to make sure that the identation in C files follows the previously adopted convention.

=== Vim customization ===

To enable syntax highlighting on SConstruct files in vim, add the following to your <tt>~/.vimrc</tt> file:

<bash>
au BufRead,BufNewFile SConstruct setfiletype python

syntax enable
</bash>

Guide to madagascar programs

2012-08-15T23:22:03Z

Nick: /* sfawefd */

<center>''This page was created from the LaTeX source in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/rsf/prog.tex?view=markup book/rsf/rsf/prog.tex] using [[latex2wiki]]''</center>

This guide introduces some of the most used <tt>madagascar</tt> programs and illustrates their usage with examples.
=Main programs=
The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/ system/main] in the Madagascar distribution. The "main" programs perform general-purpose operations on RSF hypercubes regardless of the data dimensionality or physical dimensions.

==sfadd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Add, multiply, or divide RSF datasets.
|-
! colspan="4" | sfadd > out.rsf scale= add= sqrt= abs= log= exp= mode= [< file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | The various operations, if selected, occur in the following order: (1) Take absolute value, abs= (2) Add a scalar, add= (3) Take the natural logarithm, log= (4) Take the square root, sqrt= (5) Multiply by a scalar, scale= (6) Compute the base-e exponential, exp= (7) Add, multiply, or divide the data sets, mode= sfadd operates on integer, float, or complex data, but all the input and output files must be of the same data type. An alternative to sfadd is sfmath, which is more versatile, but may be less efficient.
|-
| ''bools '' || '''abs=''' || || If true take absolute value [nin]
|-
| ''floats '' || '''add=''' || || Scalar values to add to each dataset [nin]
|-
| ''bools '' || '''exp=''' || || If true compute exponential [nin]
|-
| ''bools '' || '''log=''' || || If true take logarithm [nin]
|-
| ''string '' || '''mode=''' || || 'a' means add (default), 'p' or 'm' means multiply, 'd' means divide
|-
| ''floats '' || '''scale=''' || || Scalar values to multiply each dataset with [nin]
|-
| ''bools '' || '''sqrt=''' || || If true take square root [nin]
|}

<tt>sfadd</tt> is useful for combining (adding, dividing, or
multiplying) several datasets. What if you want to subtract two
datasets? Easy. Use the <tt>scale</tt> parameter as follows:
<pre>
bash$ sfadd data1.rsf data2.rsf scale=1,-1 > diff.rsf
</pre>
or
<pre>
bash$ sfadd < data1.rsf data2.rsf scale=1,-1 > diff.rsf
</pre>
The same task can be accomplished with the more general <tt>sfmath</tt> program:
<pre>
bash$ sfmath one=data1.rsf two=data2.rsf output='one-two' > diff.rsf
</pre>
or
<pre>
bash$ sfmath < data1.rsf two=data2.rsf output='input-two' > diff.rsf
</pre>
In both cases, the size and shape of <tt>data1.rsf</tt> and
<tt>data2.rsf</tt> hypercubes should be the same, and a warning
message is printed out if the the axis sampling parameters (such as
<tt>o1</tt> or <tt>d1</tt>) in these files are different.
====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/add.c?view=markup system/main/add.c]====
The first input file is either in the list or in the standard input.
<c>
/* find number of input files */
if (isatty(fileno(stdin))) {
/* no input file in stdin */
nin=0;
} else {
in[0] = sf_input("in");
nin=1;
}
</c>

Collect input files in the <tt>in</tt> array from all command-line
parameters that don't contain an "<tt>=</tt>" sign. The total number
of input files in <tt>nin</tt>.
<c>
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'=')) continue;
in[nin] = sf_input(argv[i]);
nin++;
}
if (0==nin) sf_error ("no input");
/* nin = no of input files*/
</c>

A helper function <tt>check_compat</tt> checks the compatibility of
input files.
<c>
static void
check_compat (sf_datatype type /* data type */,
size_t nin /* number of files */,
sf_file* in /* input files [nin] */,
int dim /* file dimensionality */,
const int* n /* dimensions [dim] */)
/* Check that the input files are compatible.
Issue error for type mismatch or size mismatch.
Issue warning for grid parameters mismatch. */
{
int ni, id;
size_t i;
float d, di, o, oi;
char key[3];
const float tol=1.e-5; /* tolerance for comparison */

for (i=1; i < nin; i++) {
if (sf_gettype(in[i]) != type)
sf_error ("type mismatch: need %d",type);
for (id=1; id <= dim; id++) {
(void) snprintf(key,3,"n%d",id);
if (!sf_histint(in[i],key,&ni) || ni != n[id-1])
sf_error("%s mismatch: need %d",key,n[id-1]);
(void) snprintf(key,3,"d%d",id);
if (sf_histfloat(in[0],key,&d)) {
if (!sf_histfloat(in[i],key,&di) ||
(fabsf(di-d) > tol*fabsf(d)))
sf_warning("%s mismatch: need %g",key,d);
} else {
d = 1.;
}
(void) snprintf(key,3,"o%d",id);
if (sf_histfloat(in[0],key,&o) &&
(!sf_histfloat(in[i],key,&oi) ||
(fabsf(oi-o) > tol*fabsf(d))))
sf_warning("%s mismatch: need %g",key,o);
}
}
}
</c>

Finally, we enter the main loop, where input data are getting read
buffer by buffer and combined in the total product depending on the
data type.
<c>
for (nbuf /= sf_esize(in[0]); nsiz > 0; nsiz -= nbuf) {
if (nbuf > nsiz) nbuf=nsiz;

for (j=0; j < nin; j++) {
collect = (bool) (j != 0);
switch(type) {
case SF_FLOAT:
sf_floatread((float*) bufi,
nbuf,
in[j]);
add_float(collect,
nbuf,
(float*) buf,
(const float*) bufi,
cmode,
scale[j],
add[j],
abs_flag[j],
log_flag[j],
sqrt_flag[j],
exp_flag[j]);
break;
</c>

The data combination program for floating point numbers is
<tt>add_float</tt>.
<c>
static void add_float (bool collect, /* if collect */
size_t nbuf, /* buffer size */
float* buf, /* output [nbuf] */
const float* bufi, /* input [nbuf] */
char cmode, /* operation */
float scale, /* scale factor */
float add, /* add factor */
bool abs_flag, /* if abs */
bool log_flag, /* if log */
bool sqrt_flag, /* if sqrt */
bool exp_flag /* if exp */)
/* Add floating point numbers */
{
size_t j;
float f;

for (j=0; j < nbuf; j++) {
f = bufi[j];
if (abs_flag) f = fabsf(f);
f += add;
if (log_flag) f = logf(f);
if (sqrt_flag) f = sqrtf(f);
if (1. != scale) f *= scale;
if (exp_flag) f = expf(f);
if (collect) {
switch (cmode) {
case 'p': /* product */
case 'm': /* multiply */
buf[j] *= f;
break;
case 'd': /* delete */
if (f != 0.) buf[j] /= f;
break;
default: /* add */
buf[j] += f;
break;
}
} else {
buf[j] = f;
}
}
}
</c>

==sfattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display dataset attributes.
|-
! colspan="4" | sfattr < in.rsf want=
|-
| colspan="4" | Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr" ******************************************* rms = 0.992354 mean value = 0.987576 2-norm value = 9.92354 variance = 0.00955481 standard deviation = 0.0977487 maximum value = 1.12735 at 97 minimum value = 0.151392 at 100 number of nonzero samples = 100 total number of samples = 100 ******************************************* rms = sqrt[ sum(data^2) / n ] mean = sum(data) / n norm = sum(abs(data)^lval)^(1/lval) variance = [ sum(data^2) - n*mean^2 ] / [ n-1 ] standard deviation = sqrt [ variance ]
|-
| ''int '' || '''lval=2''' || || norm option, lval is a non-negative integer, computes the vector lval-norm
|-
| ''string '' || '''want=''' || || 'all'(default),'rms','mean','norm','var','std','max','min','nonzero','samples','short'
:want= 'rms' displays the root mean square
:want= 'norm' displays the square norm, otherwise specified by lval.
:want= 'var' displays the variance
:want= 'std' displays the standard deviation
:want= 'nonzero' displays number of nonzero samples
:want= 'samples' displays total number of samples
:want= 'short' displays a short one-line version
|}

<tt>sfattr</tt> is a useful diagnostic program. It reports certain
statistical values for an RSF dataset: RMS (root-mean-square)
amplitude, mean value, vector norm value, variance, standard deviation,
maximum and minimum values, number of nonzero samples, and the total
number of samples.
If we denote data values as <math>d_i</math> for <math>i=0,1,2,\ldots,n</math>, then the RMS
value is <math>\sqrt{\frac{1}{n}\,\sum\limits_{i=0}^n d_i^2}</math>, the mean
value is <math>\frac{1}{n}\,\sum\limits_{i=0}^n d_i</math>, the <math>L_2</math>-norm value
is <math>\sqrt{\sum\limits_{i=0}^n d_i^2}</math>, the variance is
<math>\frac{1}{n-1}\,\left[\sum\limits_{i=0}^n d_i^2 - \frac{1}{n}\left(\sum\limits_{i=0}^n d_i\right)^2\right]</math>, and the standard
deviation is the square root of the variance. Using <tt>sfattr</tt>
is a quick way to see the distribution of data values and check it for anomalies.

The output can be parsed using utilities such as <tt>awk</tt>, to extract only a numeric value for feeding it as a parameter value into a command line interface. Notice the backticks in the example below:
<bash>
sfgrey <vel.rsf allpos=y bias=`sfattr <vel.rsf want=min | awk '{print $4}'` | sfpen
</bash>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/attr.c?view=markup system/main/attr.c]====

Computations start by finding the input data (<tt>in</tt>) size
(<tt>nsiz</tt>) and dimensions (<tt>dim</tt>).
<c>
dim = (size_t) sf_filedims (in,n);
for (nsiz=1, i=0; i < dim; i++) {
nsiz *= n[i];
}
</c>

In the main loop, we read the input data buffer by buffer.
<c>
for (nleft=nsiz; nleft > 0; nleft -= nbuf) {
nbuf = (bufsiz < nleft)? bufsiz: nleft;
switch (type) {
case SF_FLOAT:
sf_floatread((float*) buf,nbuf,in);
break;
case SF_INT:
sf_intread((int*) buf,nbuf,in);
break;
case SF_COMPLEX:
sf_complexread((sf_complex*) buf,nbuf,in);
break;
case SF_UCHAR:
sf_ucharread((unsigned char*) buf,nbuf,in);
break;
case SF_CHAR:
default:
sf_charread(buf,nbuf,in);
break;
}
</c>

The data attributes are accumulated in corresponding double-precision
variables.
<c>
fsum += f;
fsqr += f*f;
</c>

Finally, the attributes are reduced and printed out.
<c>
fmean = fsum/nsiz;
if (lval==2) fnorm = sqrt(fsqr);
else if (lval==0) fnorm = nsiz-nzero;
else fnorm = pow(flval,1./lval);
frms = sqrt(fsqr/nsiz);
if (nsiz > 1) fvar = (fsqr-nsiz*fmean*fmean)/(nsiz-1);
else fvar = 0.0;
fstd = sqrt(fvar);
</c>

<c>
if(NULL==want || 0==strcmp(want,"rms"))
printf("rms = %g \n",(float) frms);
if(NULL==want || 0==strcmp(want,"mean"))
printf("mean value = %g \n",(float) fmean);
if(NULL==want || 0==strcmp(want,"norm"))
printf("%d-norm value = %g \n",lval,(float) fnorm);
if(NULL==want || 0==strcmp(want,"var"))
printf("variance = %g \n",(float) fvar);
if(NULL==want || 0==strcmp(want,"std"))
printf("standard deviation = %g \n",(float) fstd);
</c>

==sfcat==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Concatenate datasets.
|-
! colspan="4" | sfcat > out.rsf space= axis=3 nspace=(int) (ni/(20*nin) + 1) [<file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | sfmerge inserts additional space between merged data.
|-
| ''int '' || '''axis=3''' || || Axis being merged
|-
| ''int '' || '''nspace=(int) (ni/(20*nin) + 1)''' || || if space=y, number of traces to insert
|-
| ''bool '' || '''space=''' || [y/n] || Insert additional space.
:y is default for sfmerge, n is default for sfcat
|}

<tt>sfcat</tt> and <tt>sfmerge</tt> concatenate two or more files
together along a particular axis. It is the same program, only
<tt>sfcat</tt> has the default <tt>space=n</tt> and <tt>sfmerge</tt>
has the default <tt>space=y</tt>.
Example of <tt>sfcat</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcat one.rsf one.rsf axis=1 > two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=4 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
12 elements 48 bytes
</pre>
Example of <tt>sfmerge</tt>:
<pre>
bash$ sfmerge one.rsf one.rsf axis=2 > two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=7 d2=0.1 o2=0 label2="Distance" unit2="km"
14 elements 56 bytes
</pre>
In this case, an extra empty trace is inserted between the two merged files.
The axes that are not being merged are checked for consistency:
<pre>
bash$ sfcat one.rsf two.rsf > three.rsf
sfcat: n2 mismatch: need 3
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cat.c?view=markup system/main/cat.c]====
The first input file is either in the list or in the standard input.
<c>
in = (sf_file*) sf_alloc ((size_t) argc,sizeof(sf_file));

if (!sf_stdin()) { /* no input file in stdin */
nin=0;
} else {
in[0] = sf_input("in");
nin=1;
}
</c>

Everything on the command line that does not contain a "=" sign is
treated as a file name, and the corresponding file object is added to the list.
<c>
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'='))
continue; /* not a file */
in[nin] = sf_input(argv[i]);
nin++;
}
if (0==nin) sf_error ("no input");
</c>

As explained above, if the <tt>space=</tt> parameter is not set, it is
inferred from the program name: <tt>sfmerge</tt> corresponds to
<tt>space=y</tt> and <tt>sfcat</tt> corresponds to <tt>space=n</tt>.
<c>
if (!sf_getbool("space",&space)) {
/* Insert additional space.
y is default for sfmerge, n is default for sfcat */
prog = sf_getprog();
if (NULL != strstr (prog, "merge")) {
space = true;
} else if (NULL != strstr (prog, "cat")) {
space = false;
} else {
sf_warning("%s is neither merge nor cat,"
" assume merge",prog);
space = true;
}
}
</c>

Find the axis for the merging (from the command line <tt>axis=</tt>
argument) and figure out two sizes: <tt>n1</tt> for everything after
the axis and <tt>n2</tt> for everything before the axis.
<c>
n1=1;
n2=1;
for (i=1; i <= dim; i++) {
if (i < axis) n1 *= n[i-1];
else if (i > axis) n2 *= n[i-1];
}
</c>

In the output, the selected axis will get extended.
<c>
/* figure out the length of extended axis */
ni = 0;
for (j=0; j < nin; j++) {
ni += naxis[j];
}

if (space) {
if (!sf_getint("nspace",&nspace))
nspace = (int) (ni/(20*nin) + 1);
/* if space=y, number of traces to insert */
ni += nspace*(nin-1);
}

(void) snprintf(key,3,"n%d",axis);
sf_putint(out,key,(int) ni);
</c>

The rest is simple: loop through the datasets reading and writing the
data in buffer-size chunks and adding extra empty chunks if
<tt>space=y</tt>.
<c>
for (i2=0; i2 < n2; i2++) {
for (j=0; j < nin; j++) {
for (ni = n1*naxis[j]*esize; ni > 0; ni -= nbuf) {
nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
sf_charread (buf,nbuf,in[j]);
sf_charwrite (buf,nbuf,out);
}
if (!space || j == nin-1) continue;
/* Add spaces */
memset(buf,0,BUFSIZ);
for (ni = n1*nspace*esize; ni > 0; ni -= nbuf) {
nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
sf_charwrite (buf,nbuf,out);
}
}
}
</c>

==sfcdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for complex linear operators with adjoints
|-
! colspan="4" | sfcdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|-
| ''file '' || '''dat=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|}

A simple demonstration of the program can be made taking advantage that the complex-to-complex FFT is a linear operator:

<bash>
sfspike n1=100 | sfrtoc > spike.rsf
< spike.rsf sffft axis=1 pad=1 > spike2.rsf
sfcdottest sffft mod=spike.rsf dat=spike2.rsf axis=1 pad=1
</bash>

The output should show values identical down to the last decimal:

<pre>
sfcdottest: L[m]*d=(3.73955,-1.86955)
sfcdottest: L'[d]*m=(3.73955,-1.86955)
</pre>

==sfcmplx==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Create a complex dataset from its real and imaginary parts.
|-
! colspan="4" | sfcmplx > cmplx.rsf real.rsf imag.rsf
|-
| colspan="4" | There has to be only two input files specified and no additional parameters.
|}

<tt>sfcmplx</tt> simply creates a complex dataset from its real and
imaginary parts. The reverse operation can be accomplished with
<tt>sfreal</tt> and <tt>sfimag</tt>.
Example of <tt>sfcmplx</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcmplx one.rsf one.rsf > cmplx.rsf
bash$ sfin cmplx.rsf
cmplx.rsf:
in="/tmp/cmplx.rsf@"
esize=8 type=complex form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 48 bytes
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cmplx.c?view=markup system/main/cmplx.c]====
The program flow is simple. First, get the names of the input files.
<c>
/* the first two non-parameters are real and imaginary files */
for (i=1; i< argc; i++) {
if (NULL == strchr(argv[i],'=')) {
if (NULL == real) {
real = sf_input (argv[i]);
} else {
imag = sf_input (argv[i]);
break;
}
}
}
if (NULL == imag) {
if (NULL == real) sf_error ("not enough input");
/* if only one input, real is in stdin */
imag = real;
real = sf_input("in");
}
</c>

The main part of the program reads the real and imaginary parts buffer by buffer and assembles and writes out the complex input.
<c>
for (nleft= (size_t) (rsize*resize); nleft > 0; nleft -= nbuf) {
nbuf = (BUFSIZ < nleft)? BUFSIZ: nleft;
sf_charread(rbuf,nbuf,real);
sf_charread(ibuf,nbuf,imag);
for (i=0; i < nbuf; i += resize) {
memcpy(cbuf+2*i, rbuf+i,(size_t) resize);
memcpy(cbuf+2*i+resize,ibuf+i,(size_t) resize);
}
sf_charwrite(cbuf,2*nbuf,cmplx);
}
</c>
==sfconjgrad==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic conjugate-gradient solver for linear inversion
|-
! colspan="4" | sfconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
|-
| ''int '' || '''niter=1''' || || number of iterations
|}

<tt>sfconjgrad</tt> is a generic program for least-squares linear
inversion with the [http://en.wikipedia.org/wiki/Conjugate_gradient_method conjugate-gradient method]. Suppose you have an
executable program <tt><prog></tt> that takes an RSF file from the
standard input and produces an RSF file in the standard output. It may
take any number of additional parameters but one of them must be
<tt>adj=</tt> that sets the forward (<tt>adj=0</tt>) or adjoint
(<tt>adj=1</tt>) operations. The program <tt><prog></tt> is typically
an RSF program but it could be anything (a script, a multiprocessor
MPI program, etc.) as long as it implements a linear operator
<math>\mathbf{L}</math> and its adjoint. There are no restrictions on the data
size or shape. You can easily test the adjointness with
<tt>sfdottest</tt>. The <tt>sfconjgrad</tt> program searches for a
vector <math>\mathbf{m}</math> that minimizes the least-square misfit
<math>\|\mathbf{d - L\,m}\|^2</math> for the given input data vector <math>\mathbf{d}</math>.

The pseudocode for <tt>sfconjgrad</tt> is given at the end of the [http://www.reproducibility.org/RSF/book/gee/lsq/paper.pdf "Model fitting with least squares" chapter] of ''Imaging Estimation by Example'' by Jon Claerbout, with the earliest form published in [http://sepwww.stanford.edu/data/media/public/oldreports/sep48/48_25.pdf "Conjugate Gradient Tutorial"] (SEP-48, 1986, same author). A simple toy implementation with a small matrix shows that this is algorithm produces the same steps as the algorithm described in equations 45-49 of [http://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf "An introduction to the Conjugate Gradient Method Without the Agonizing Pain"] by J.R. Shewchuk, 1994, when the equation <math>A^T A x = A^T b</math> (in Shewchuk's notation) is solved. Multiplying with the transpose ensures a correct solution even when matrix A is square but not symmetric, or not square at all. The program [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad] implements this algorithm for the case when inputs are complex.

Here is an example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
The <tt>sfdottest</tt> program can perform the dot product test to
check that the adjoint mode works correctly.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=5.28394
sfdottest: L'[d]*m=5.28394
</pre>
Your numbers may be different because <tt>sfdottest</tt> generates new
random input on each run.
Next, let us make some random data with <tt>sfnoise</tt>.
<pre>
bash$ sfnoise seed=2005 rep=y < vec.rsf > dat.rsf
</pre>
and try to invert the filtering operation using <tt>sfconjgrad</tt>:
<pre>
bash$ sfconjgrad sfhelicon filt=flt.rsf lag=lag.rsf mod=vec.rsf < dat.rsf > mod.rsf niter=10
sfconjgrad: iter 1 of 10
sfconjgrad: grad=3253.65
sfconjgrad: iter 2 of 10
sfconjgrad: grad=289.421
sfconjgrad: iter 3 of 10
sfconjgrad: grad=92.3481
sfconjgrad: iter 4 of 10
sfconjgrad: grad=36.9417
sfconjgrad: iter 5 of 10
sfconjgrad: grad=18.7228
sfconjgrad: iter 6 of 10
sfconjgrad: grad=11.1794
sfconjgrad: iter 7 of 10
sfconjgrad: grad=7.26941
sfconjgrad: iter 8 of 10
sfconjgrad: grad=5.15945
sfconjgrad: iter 9 of 10
sfconjgrad: grad=4.23055
sfconjgrad: iter 10 of 10
sfconjgrad: grad=3.57495
</pre>
The output shows that, in 10 iterations, the norm of the gradient vector decreases by almost 1000.
We can check the residual misfit before
<pre>
bash$ < dat.rsf sfattr want=norm
norm value = 49.7801
</pre>
and after
<pre>
bash$ sfhelicon filt=flt.rsf lag=lag.rsf < mod.rsf | sfadd scale=1,-1 dat.rsf | sfattr want=norm
norm value = 5.73563
</pre>
In 10 iterations, the misfit decreased by an order of magnitude. The
result can be improved by running the program for more iterations.

An equivalent implementation for complex-valued inputs is [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad]. A simple, lightweight Python implementation can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/user/fomels/conjgrad.py?view=markup $PYTHONPATH/rsf/conjgrad.py].

==sfcp==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Copy or move a dataset.
|-
! colspan="4" | sfcp in.rsf out.rsf
|-
| colspan="4" | sfcp - copy, sfmv - move. Mimics standard Unix commands.
|}

The <tt>sfcp</tt> and <tt>sfmv</tt> command imitate the Unix
<tt>cp</tt> and <tt>mv</tt> commands and serve for copying and moving
RSF files. Example:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcp one.rsf two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cp.c?view=markup system/main/cp.c]====
First, we look for the two first command-line arguments that don't
have the "=" character in them and consider them as the names of the
input and the output files.
<c>
/* the first two non-parameters are in and out files */
for (i=1; i< argc; i++) {
if (NULL == strchr(argv[i],'=')) {
if (NULL == in) {
infile = argv[i];
in = sf_input (infile);
} else {
out = sf_output (argv[i]);
break;
}
}
}
if (NULL == in || NULL == out)
sf_error ("not enough input");
</c>

Next, we use library functions sf_cp and sf_rm to do the actual work.
<c>
sf_cp(in,out);
if (NULL != strstr (sf_getprog(),"mv"))
sf_rm(infile,false,false,false);
</c>

==sfcut==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Zero a portion of the dataset.
|-
! colspan="4" | sfcut < in.rsf > out.rsf verb=n [j1=1 j2=1 ... f1=0 f2=0 ... n1=n1 n2=n2 ... max1= max2= ... min1= min2= ...]
|-
| colspan="4" | jN defines the jump in N-th dimension fN is the window start nN is the window size minN and maxN is the maximum and minimum in N-th dimension Reverse of window.
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

The <tt>sfcut</tt> command is related to <tt>sfwindow</tt> and has the same
set of arguments only instead of extracting the selected window, it fills it
with zeroes. The size of the input data is preserved.
Examples:
<pre>
bash$ sfspike n1=5 n2=5 > in.rsf
bash$ < in.rsf sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ < in.rsf sfcut n1=2 f1=1 n2=3 f2=2 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 0 0 1 1
15: 1 0 0 1 1
20: 1 0 0 1 1
bash$ < in.rsf sfcut j1=2 | sfdisfil
0: 0 1 0 1 0
5: 0 1 0 1 0
10: 0 1 0 1 0
15: 0 1 0 1 0
20: 0 1 0 1 0
</pre>

==sfdd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert between different formats.
|-
! colspan="4" | sfdd < in.rsf > out.rsf line=8 form= type= format=
|-
| ''string '' || '''form=''' || || ascii, native, xdr
|-
| ''string '' || '''format=''' || || Element format (for conversion to ASCII)
|-
| ''int '' || '''line=8''' || || Number of numbers per line (for conversion to ASCII)
|-
| ''string '' || '''type=''' || || int, float, complex
|}

The <tt>sfdd</tt> program is used to change either the form (<tt>ascii</tt>,
<tt>xdr</tt>, <tt>native</tt>) or the type (<tt>complex</tt>, <tt>float</tt>,
<tt>int</tt>, <tt>char</tt>) of the input dataset.
In the example below, we create a plain text (ASCII) file with numbers and
then use <tt>sfdd</tt> to generate an RSF file in <tt>xdr</tt> form with
<tt>complex</tt> numbers.
<pre>
bash$ cat test.txt
1 2 3 4 5 6
bash$ echo n1=6 data_format=ascii_int in=test.txt > test.rsf
bash$ sfin test.rsf
test.rsf:
in="test.txt"
esize=0 type=int form=ascii
n1=6 d1=? o1=?
6 elements
bash$ sfdd < test.rsf form=xdr type=complex > test2.rsf
bash$ sfin test2.rsf
test2.rsf:
in="/tmp/test2.rsf@"
esize=8 type=complex form=xdr
n1=3 d1=? o1=?
3 elements 24 bytes
bash$ sfdisfil < test2.rsf
0: 1, 2i 3, 4i 5, 6i
</pre>
To learn more about the RSF data format, consult the [[Guide to RSF file format| guide to RSF format]].

==sfdisfil==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Print out data values.
|-
! colspan="4" | sfdisfil < in.rsf number=y col=0 format= header= trailer=
|-
| colspan="4" | Alternatively, use sfdd and convert to ASCII form.
|-
| ''int '' || '''col=0''' || || Number of columns.
:The default depends on the data type:
:10 for int and char,
:5 for float,
:3 for complex
|-
| ''string '' || '''format=''' || || Format for numbers (printf-style).
:The default depends on the data type: "%4d " for int and char, "%13.4g" for float, "%10.4g,%10.4gi" for complex
|-
| ''string '' || '''header=''' || || Optional header string to output before data
|-
| ''bool '' || '''number=y''' || [y/n] || If number the elements
|-
| ''string '' || '''trailer=''' || || Optional trailer string to output after data
|}

The <tt>sfdisfil</tt> program simply dumps the data contents to the standard
output in a text form. It is used mostly for debugging purposes to quickly
examine RSF files. Here is an example:
<pre>
bash$ sfmath o1=0 d1=2 n1=12 output=x1 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 2 4 6 8
5: 10 12 14 16 18
10: 20 22
</pre>
The output format is easily configurable.
<pre>
bash$ < test.rsf sfdisfil col=6 number=n format="%5.1f"
0.0 2.0 4.0 6.0 8.0 10.0
12.0 14.0 16.0 18.0 20.0 22.0
</pre>
Along with <tt>sfdd</tt>, <tt>sfdisfil</tt> provides a simple way to convert
RSF data to an ASCII form.

==sfdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for linear operators with adjoints
|-
! colspan="4" | sfdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|}

<tt>sfdottest</tt> is a generic dot-product test program for testing
linear operators. Suppose there is an executable program
<tt><prog></tt> that takes an RSF file from the standard input and
produces an RSF file in the standard output. It may take any number of
additional parameters but one of them must be <tt>adj=</tt> that sets
the forward (<tt>adj=0</tt>) or adjoint (<tt>adj=1</tt>) operations.
The program <tt><prog></tt> is typically an RSF program but it could
be anything (a script, a multiprocessor MPI program, etc.) as long as
it implements a linear operator <math>\mathbf{L}</math> and its adjoint
<math>\mathbf{L}^T</math>. The <tt>sfdottest</tt> program is testing the equality
<center><math>
d^T\,L\,m = m^T\,L^T\,d
</math></center>
by using random vectors <math>\mathbf{m}</math> and <math>\mathbf{d}</math>. You can invoke it with
<pre>
bash$ sfdottest <prog> [optional aruments] mod=mod.rsf dat=dat.rsf
</pre>
where <tt>mod.rsf</tt> and <tt>dat.rsf</tt> are RSF files that
represent vectors from the model and data spaces. Pay attention to the
dimension and size of these vectors! If the program does not respond
for a very long time, it is quite possible that the dimension and size
of the vectors are inconsistent with the requirement of the program to be
tested. <tt>sfdottest</tt>
does not create any temporary files and does not have any restrictive
limitations on the size of the vectors.
Here is an example. We first setup a vector with 100 elements using
<tt>sfspike</tt> and then run <tt>sfdottest</tt> to test the
<tt>sfcausint</tt> program. <tt>sfcausint</tt> implements a linear
operator of causal integration and its adjoint, the anti-causal
integration.
<pre>
bash$ sfspike n1=100 > vec.rsf
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=1410.2
sfdottest: L'[d]*m=1410.2
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=1165.87
sfdottest: L'[d]*m=1165.87
</pre>
The numbers are different on subsequent runs because of changing
seed in the random number generator.
Here is a somewhat more complicated example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
Now the <tt>sfdottest</tt> program can perform the dot product test.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=8.97375
sfdottest: L'[d]*m=8.97375
</pre>
Here is the same program tested in the inverse filtering mode:
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf div=y
sfdottest: L[m]*d=15.0222
sfdottest: L'[d]*m=15.0222
</pre>

==sfget==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Output parameters from the header.
|-
! colspan="4" | sfget < in.rsf parform=y par1 par2 ...
|-
| ''bool '' || '''parform=y''' || [y/n] || If y, print out parameter=value. If n, print out value.
|}

The <tt>sfget</tt> program extracts a parameter value from an RSF file. It is
useful mostly for scripting. Here is, for example, a quick calculation of the
maximum value on the first axis in an RSF dataset (the output of
<tt>sfspike</tt>) using the standard Unix <tt>bc</tt> calculator.
<pre>
bash$ ( sfspike n1=100 | sfget n1 d1 o1; echo "o1+(n1-1)*d1" ) | bc
.396
</pre>
See also <tt>sfput</tt>.

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/get.c?view=markup system/main/get.c]====
The implementation is trivial. Loop through all command-line parameters that contain
the "=" character.
<c>
for (i = 1; i < argc; i++) {
key = argv[i];
if (NULL != strchr(key,'=')) continue;
</c>

Get the parameter value (as string) and output it as either
<tt>key=value</tt> or <tt>value</tt>, depending on the
<tt>parform</tt> parameter.
<c>
string = sf_histstring(in,key);
if (NULL == string) {
sf_warning("No key %s",key);
} else {
if (parform) printf ("%s=",key);
printf("%s\n",string);
}
</c>

==sfheadercut==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Zero a portion of a dataset based on a header mask.
|-
! colspan="4" | sfheadercut mask=head.rsf < in.rsf > out.rsf
|-
| colspan="4" | The input data is a collection of traces n1xn2, mask is an integer array of size n2.
|}

<tt>sfheadercut</tt> is close to <tt>sfheaderwindow</tt> but instead
of windowing the dataset, it fills the traces specified by the header
mask with zeroes. The size of the input data is preserved.
Here is an example of using <tt>sfheaderwindow</tt> for
zeroing every other trace in the input file. First, let us create
an input file with ten traces:
<pre>
bash$ sfmath n1=5 n2=10 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
35: 8 8 8 8 8
40: 9 9 9 9 9
45: 10 10 10 10 10
</pre>
Next, we can create a mask with alternating ones and zeros using
<tt>sfinterleave</tt>.
<pre>
bash$ sfspike n1=5 mag=1 | sfdd type=int > ones.rsf
bash$ sfspike n1=5 mag=0 | sfdd type=int > zeros.rsf
bash$ sfinterleave axis=1 ones.rsf zeros.rsf > mask.rsf
bash$ sfdisfil < mask.rsf
0: 1 0 1 0 1 0 1 0 1 0
</pre>
Finally, <tt>sfheadercut</tt> zeros the input traces.
<pre>
bash$ sfheadercut < input.rsf mask=mask.rsf > output.rsf
bash$ sfdisfil < output.rsf
0: 1 1 1 1 1
5: 0 0 0 0 0
10: 3 3 3 3 3
15: 0 0 0 0 0
20: 5 5 5 5 5
25: 0 0 0 0 0
30: 7 7 7 7 7
35: 0 0 0 0 0
40: 9 9 9 9 9
45: 0 0 0 0 0
</pre>

==sfheadersort==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Sort a dataset according to a header key.
|-
! colspan="4" | sfheadersort < in.rsf > out.rsf head=
|-
| ''string '' || '''head=''' || || header file
|}

<tt>sfheadersort</tt> is used to sort traces in the input file
according to trace header information.
Here is an example of using
<tt>sfheadersort</tt> for randomly shuffling traces in the input
file. First, let us create an input file with seven traces:
<pre>
bash$ sfmath n1=5 n2=7 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
</pre>
Next, we can create a random file with seven header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=7 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
0: 0.05256 -0.2879 0.1487 0.4097 0.1548
5: 0.4501 0.2836
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally, we
apply <tt>sfheadersort</tt> to shuffle the input traces.
<pre>
bash$ < input.rsf sfheadersort head=random.rsf > output.rsf
bash$ < output.rsf sfdisfil
0: 2 2 2 2 2
5: 1 1 1 1 1
10: 3 3 3 3 3
15: 5 5 5 5 5
20: 7 7 7 7 7
25: 4 4 4 4 4
30: 6 6 6 6 6
</pre>
As expected, the order of traces in the output file corresponds to the
order of values in the header. Thanks to the separation between
headers and data, the operation of <tt>sfheadersort</tt> is optimally
efficient. It first sorts the headers and only then accesses the data,
reading each data trace only once.

==sfheaderwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a dataset based on a header mask.
|-
! colspan="4" | sfheaderwindow mask=head.rsf < in.rsf > out.rsf
|-
| colspan="4" | The input data is a collection of traces n1xn2, mask is an integer array os size n2, windowed is n1xm2, where m2 is the number of nonzero elements in mask.
|}

<tt>sfheaderwindow</tt> is used to window traces in the input file
according to trace header information.
Here is an example of using <tt>sfheaderwindow</tt> for randomly
selecting part of the traces in the input file. First, let us create
an input file with ten traces:
<pre>
bash$ sfmath n1=5 n2=10 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
35: 8 8 8 8 8
40: 9 9 9 9 9
45: 10 10 10 10 10
</pre>
Next, we can create a random file with ten header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=10 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
0: -0.005768 0.02258 -0.04331 -0.4129 -0.3909
5: -0.03582 0.4595 -0.3326 0.498 -0.3517
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally,
we apply <tt>sfheaderwindow</tt> to window the input traces selecting
only those for which the header is greater than zero.
<pre>
bash$ < random.rsf sfmask min=0 > mask.rsf
bash$ < mask.rsf sfdisfil
0: 0 1 0 0 0 0 1 0 1 0
bash$ < input.rsf sfheaderwindow mask=mask.rsf > output.rsf
bash$ < output.rsf sfdisfil
0: 2 2 2 2 2
5: 7 7 7 7 7
10: 9 9 9 9 9
</pre>
In this case, only three traces are selected for the output. Thanks to
the separation between headers and data, the operation of
<tt>sfheaderwindow</tt> is optimally efficient.

==sfin==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display basic information about RSF files.
|-
! colspan="4" | sfin info=y check=2. trail=y file1.rsf file2.rsf ...
|-
| colspan="4" | n1,n2,... are data dimensions o1,o2,... are axis origins d1,d2,... are axis sampling intervals label1,label2,... are axis labels unit1,unit2,... are axis units
|-
| ''float '' || '''check=2.''' || || Portion of the data (in Mb) to check for zero values.
|-
| ''bool '' || '''info=y''' || [y/n] || If n, only display the name of the data file.
|-
| ''bool '' || '''trail=y''' || [y/n] || If n, skip trailing dimensions of one
|}

<tt>sfin</tt> is one of the most useful programs for operating with
RSF files. It produces quick information on the file hypercube
dimensions and checks the consistency of the associated data file.
Here is an example. Let us create an RSF file and examine it with <tt>sfin</tt>.
<pre>
bash$ sfspike n1=100 n2=20 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/tmp/spike.rsf@"
esize=4 type=float form=native
n1=100 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
2000 elements 8000 bytes
</pre>
<tt>sfin</tt> reports the following information:

*location of the data file (<tt>/tmp/spike.rsf\@</tt>)
*element size (4 bytes)
*element type (floating point)
*element form (native)
*hypercube dimensions (100 by 20)
*axes scale (0.004 and 0.1)
*axes origin (0 and 0)
*axes labels
*axes units
*total number of elements
*total number of bytes in the data file
Suppose that the file got corrupted by a buggy program and reports
incorrect dimensions. The <tt>sfin</tt> program should be able to
catch the discrepancy.
<pre>
bash$ echo n2=100 >> spike.rsf
bash$ sfin spike.rsf > /dev/null
sfin: Actually 8000 bytes, 20% of expected.
</pre>
<tt>sfin</tt> also checks the first records in the file for zeros.
<pre>
bash$ sfspike n1=100 n2=100 k2=99 > spike2.rsf
bash$ sfin spike2.rsf >/dev/null
sfin: The first 32768 bytes are all zeros
</pre>
The number of bytes to check is adjustable
<pre>
bash$ sfin spike2.rsf check=0.01 >/dev/null
sfin: The first 16384 bytes are all zeros
</pre>
You can also output only the location of the data file. This is
sometimes handy in scripts.
<pre>
bash$ sfin spike.rsf spike2.rsf info=n
/tmp/spike.rsf@ /tmp/spike2.rsf@
</pre>
An alternative is to use <tt>sfget</tt>, as follows:
<pre>
bash$ sfget parform=n in < spike.rsf
/tmp/spike.rsf@
</pre>
To actually eliminate annoying trailing dimensions of length one (not just stop displaying them with <tt>trail=n</tt>), you may use <tt>sed</tt>. Example for eliminating axis 6:
<bash>
sed -i 's/n6=1//g' file.rsf
</bash>

==sfinterleave==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Combine several datasets by interleaving.
|-
! colspan="4" | sfinterleave > out.rsf axis=3 [< file0.rsf] file1.rsf file2.rsf ...
|-
| ''int '' || '''axis=3''' || || Axis for interleaving
|}

<tt>sfinterleave</tt> combines two or more datasets by interleaving them on one
of the axes. Here is a quick example:
<pre>
bash$ sfspike n1=5 n2=5 > one.rsf
bash$ sfdisfil < one.rsf
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ sfscale < one.rsf dscale=2 > two.rsf
bash$ sfdisfil < two.rsf
0: 2 2 2 2 2
5: 2 2 2 2 2
10: 2 2 2 2 2
15: 2 2 2 2 2
20: 2 2 2 2 2
bash$ sfinterleave one.rsf two.rsf axis=1 | sfdisfil
0: 1 2 1 2 1
5: 2 1 2 1 2
10: 1 2 1 2 1
15: 2 1 2 1 2
20: 1 2 1 2 1
25: 2 1 2 1 2
30: 1 2 1 2 1
35: 2 1 2 1 2
40: 1 2 1 2 1
45: 2 1 2 1 2
bash$ sfinterleave < one.rsf two.rsf axis=2 | sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 1 1 1 1 1
15: 2 2 2 2 2
20: 1 1 1 1 1
25: 2 2 2 2 2
30: 1 1 1 1 1
35: 2 2 2 2 2
40: 1 1 1 1 1
45: 2 2 2 2 2
</pre>

==sfmask==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Create a mask.
|-
! colspan="4" | sfmask < in.rsf > out.rsf min=-FLT_MAX max=+FLT_MAX
|-
| colspan="4" | Mask is an integer data with ones and zeros. Ones correspond to input values between min and max. The output can be used with sfheaderwindow.
|-
| ''float '' || '''max=+FLT_MAX''' || || maximum header value
|-
| ''float '' || '''min=-FLT_MAX''' || || minimum header value
|}

<tt>sfmask</tt> creates an integer output of ones and zeros comparing
the values of the input data to specified <tt>min=</tt> and
<tt>max=</tt> parameters. It is useful for <tt>sfheaderwindow</tt> and
in many other applications. Here is a quick example:
<pre>
bash$ sfmath n1=10 output="sin(x1)" > sin.rsf
bash$ < sin.rsf sfdisfil
0: 0 0.8415 0.9093 0.1411 -0.7568
5: -0.9589 -0.2794 0.657 0.9894 0.4121
bash$ < sin.rsf sfmask min=-0.5 max=0.5 | sfdisfil
0: 1 0 0 1 0 0 1 0 0 1
</pre>

==sfmath==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Mathematical operations on data files.
|-
! colspan="4" | sfmath > out.rsf type= unit= output=
|-
| colspan="4" | Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs, conj (for complex data). sfmath will work on float or complex data, but all the input and output files must be of the same data type. An alternative to sfmath is sfadd, which may be more efficient, but is less versatile. Examples: sfmath x=file1.rsf y=file2.rsf power=file3.rsf output='sin((x+2*y)^power)' > out.rsf sfmath < file1.rsf tau=file2.rsf output='exp(tau*input)' > out.rsf sfmath n1=100 type=complex output="exp(I*x1)" > out.rsf See also: sfheadermath.
|-
| ''string '' || '''output=''' || || Mathematical description of the output
|-
| ''string '' || '''type=''' || || output data type [float,complex]
|-
| ''string '' || '''unit=''' || ||
|}

<tt>sfmath</tt> is a versatile program for mathematical operations
with RSF files. It can operate with several input file, all of the
same dimensions and data type. The data type can be real (floating
point) or complex. Here is an example that demonstrates several
features of <tt>sfmath</tt>.
<pre>
bash$ sfmath n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5 \
output="x2*(8+sin(6*x1+x2/10))" > rad.rsf
bash$ < rad.rsf sfrtoc | sfmath output="input*exp(I*x1)" > rose.rsf
bash$ < rose.rsf sfgraph title=Rose screenratio=1 wantaxis=n | sfpen
</pre>
The first line creates a 2-D dataset that consists of 40 traces 629
samples each. The values of the data are computed with the formula
"x2*(8+sin(6*x1+x2/10))", where <tt>x1</tt> refers to the
coordinate on the first axis, and <tt>x2</tt> is the coordinate of the
second axis. In the second line, we convert the data from real to
complex using <tt>sfrtoc</tt> and produce a complex dataset using
formula "input*exp(I*x1)", where <tt>input</tt> refers to the
input file. Finally, we plot the complex data as a collection of
parametric curves using <tt>sfgraph</tt> and display the result using
<tt>sfpen</tt>. The plot appearing on your screen should look similar
to the figure.
[[Image:rose.png|frame|center|This figure was created with <tt>sfmath</tt>.]]
One possible alternative to the second line above is
<pre>
bash$ < rad.rsf sfmath output=x1 > ang.rsf
bash$ sfmath r=rad.rsf a=ang.rsf output="r*cos(a)" > cos.rsf
bash$ sfmath r=rad.rsf a=ang.rsf output="r*sin(a)" > sin.rsf
bash$ sfcmplx cos.rsf sin.rsf > rose.rsf
</pre>
Here we refer to input files by names (<tt>r</tt> and <tt>a</tt>) and combine the names in a formula.

==sfpad==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Pad a dataset with zeros.
|-
! colspan="4" | sfpad < in.rsf > out.rsf [beg1= beg2= ... end1= end2=... | n1= n2 = ... | n1out= n2out= ...]
|-
| colspan="4" | begN specifies the number of zeros to add before the beginning of axis N. endN specifies the number of zeros to add after the end of axis N. Alternatively: nN or nNout specify the output length of axis N, padding occurs at the end. nN and nNout are equivalent.
|}

<tt>pad</tt> increases the dimensions of the input dataset by padding
the data with zeroes. Here are some simple examples.
<pre>
bash$ sfspike n1=5 n2=3 > one.rsf
bash$ sfdisfil < one.rsf
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
bash$ < one.rsf sfpad n2=5 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 0 0 0 0 0
20: 0 0 0 0 0
bash$ < one.rsf sfpad beg2=2 | sfdisfil
0: 0 0 0 0 0
5: 0 0 0 0 0
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ < one.rsf sfpad beg2=1 end2=1 | sfdisfil
0: 0 0 0 0 0
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 0 0 0 0 0
bash$ < one.rsf sfwindow n1=3 | sfpad n1=5 n2=5 beg1=1 beg2=1 | sfdisfil
0: 0 0 0 0 0
5: 0 1 1 1 0
10: 0 1 1 1 0
15: 0 1 1 1 0
20: 0 0 0 0 0
</pre>
You can use <tt>sfcat</tt> to pad data with values other than zeroes.

==sfput==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Input parameters into a header.
|-
! colspan="4" | sfput < in.rsf > out.rsf
|}

<tt>sfput</tt> is a very simple program. It simply appends parameters
from the command line to the output RSF file. One can achieve similar
results with editing by hand or with standard Unix utilities like
<tt>sed</tt> and <tt>echo</tt>. <tt>sfput</tt> is sometimes more
convenient because it handles input/output operations similarly to
other regular RSF programs.
<pre>
bash$ sfspike n1=10 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/tmp/spike.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
10 elements 40 bytes
bash$ sfput < spike.rsf d1=25 label1=Depth unit1=m > spike2.rsf
bash$ sfin spike2.rsf
spike2.rsf:
in="/tmp/spike2.rsf@"
esize=4 type=float form=native
n1=10 d1=25 o1=0 label1="Depth" unit1="m"
10 elements 40 bytes
</pre>

==sfreal==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
|-
! colspan="4" | sfreal < cmplx.rsf > real.rsf
|}

<tt>sfreal</tt> extracts the real part of a complex type dataset. The
imaginary part can be extracted with <tt>sfimag</tt>, an the real
and imaginary part can be combined together with <tt>sfcmplx</tt>.
Here is a simple example. Let us first create a complex dataset
with <tt>sfmath</tt>
<pre>
bash$ sfmath n1=10 type=complex output="(2+I)*x1" > cmplx.rsf
bash$ fdisfil < cmplx.rsf
0: 0, 0i 2, 1i 4, 2i
3: 6, 3i 8, 4i 10, 5i
6: 12, 6i 14, 7i 16, 8i
9: 18, 9i
</pre>
Extracting the real part with <tt>sfreal</tt>:
<pre>
bash$ sfreal < cmplx.rsf | sfdisfil
0: 0 2 4 6 8
5: 10 12 14 16 18
</pre>
Extracting the imaginary part with <tt>sfimag</tt>:
<pre>
bash$ sfimag < cmplx.rsf | sfdisfil
0: 0 1 2 3 4
5: 5 6 7 8 9
</pre>

==sfreverse==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Reverse one or more axes in the data hypercube.
|-
! colspan="4" | sfreverse < in.rsf > out.rsf which=-1 verb=false memsize=sf_memsize() opt=
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''string '' || '''opt=''' || || If y, change o and d parameters on the reversed axis;
:if i, don't change o and d
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|-
| ''int '' || '''which=-1''' || || Which axis to reverse.
:To reverse a given axis, start with 0,
:add 1 to number to reverse n1 dimension,
:add 2 to number to reverse n2 dimension,
:add 4 to number to reverse n3 dimension, etc.
:Thus, which=7 would reverse the first three dimensions,
:which=5 just n1 and n3, etc.
:which=0 will just pass the input on through unchanged.
|}
Here is an example of using <tt>sfreverse</tt>. First, let us create a
2-D dataset.
<pre>
bash$ sfmath n1=5 d1=1 n2=3 d2=1 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
</pre>
Reversing the first axis:
<pre>
bash$ < test.rsf sfreverse which=1 | sfdisfil
0: 4 3 2 1 0
5: 5 4 3 2 1
10: 6 5 4 3 2
</pre>
Reversing the second axis:
<pre>
bash$ < test.rsf sfreverse which=2 | sfdisfil
0: 2 3 4 5 6
5: 1 2 3 4 5
10: 0 1 2 3 4
</pre>
Reversing both the first and the second axis:
<pre>
bash$ < test.rsf sfreverse which=3 | sfdisfil
0: 2 3 4 5 6
5: 1 2 3 4 5
10: 0 1 2 3 4
</pre>
As you can see, the <tt>which=</tt> parameter controls the axes that are
being reversed by encoding them into one number.
When an axis is reversed, what happens with its axis origin and
sampling parameters? This behavior is controlled by <tt>opt=</tt>. In
our example,
<pre>
bash$ < test.rsf sfget n1 o1 d1
n1=5
o1=0
d1=1
bash$ < test.rsf sfreverse which=1 | sfget o1 d1
o1=4
d1=-1
</pre>
The default behavior (equivalent to <tt>opt=y</tt>) puts the origin
<tt>o1</tt> at the end of the axis and reverses the sampling parameter
<tt>d1</tt>. Using <tt>opt=n</tt> preserves the sampling but reverses
the origin.
<pre>
bash$ < test.rsf sfreverse which=1 opt=n | sfget o1 d1
o1=-4
d1=1
</pre>
Using <tt>opt=i</tt> preserves both the sampling and the origin while
reversing the axis.
<pre>
bash$ < test.rsf sfreverse which=1 opt=i | sfget o1 d1
o1=0
d1=1
</pre>
One of the three possible behaviors may be desirable depending on the
application.

==sfrm==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Remove RSF files together with their data.
|-
! colspan="4" | sfrm file1.rsf [file2.rsf ...] [-i] [-v] [-f]
|-
| colspan="4" | Mimics the standard Unix rm command. See also: sfmv, sfcp.
|}

<tt>sfrm</tt> is a program for removing RSF files. Its arguments mimic
the arguments of the standard Unix <tt>rm</tt> utility: <tt>-v</tt>
for verbosity, <tt>-i</tt> for interactive inquiry, <tt>-f</tt> for
force removal of suspicious files. Unlike the Unix <tt>rm</tt>,
<tt>sfrm</tt> removes both the RSF header files and the binary files
that the headers point to.
Example:
<pre>
bash$ sfspike n1=10 > spike.rsf datapath=./
bash$ sfget in < spike.rsf
in=./spike.rsf@
bash$ ls spike*
spike.rsf spike.rsf@
bash$ sfrm -v spike.rsf
sfrm: sf_rm: Removing header spike.rsf
sfrm: sf_rm: Removing data ./spike.rsf@
bash$ ls spike*
ls: No match.
</pre>
==sfrotate==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Rotate a portion of one or more axes in the data hypercube.
|-
! colspan="4" | sfrotate < in.rsf > out.rsf verb=n memsize=sf_memsize() rot#=(0,0,...)
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''int '' || '''rot#=(0,0,...)''' || || length of #-th axis that is moved to the end
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

<tt>sfrotate</tt> modifies the input dataset by splitting it into
parts and putting the parts back in a different order. Here is a quick example.
<pre>
bash$ sfmath n1=5 d1=1 n2=3 d2=1 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
</pre>
Rotating the first axis by putting the last two columns in front:
<pre>
bash$ < test.rsf sfrotate rot1=2 | sfdisfil
0: 3 4 0 1 2
5: 4 5 1 2 3
10: 5 6 2 3 4
</pre>
Rotating the second axis by putting the last row in front:
<pre>
bash$ < test.rsf sfrotate rot2=1 | sfdisfil
0: 2 3 4 5 6
5: 0 1 2 3 4
10: 1 2 3 4 5
</pre>
Rotating both the first and the second axis:
<pre>
bash$ < test.rsf sfrotate rot1=3 rot2=1 | sfdisfil
0: 4 5 6 2 3
5: 2 3 4 0 1
10: 3 4 5 1 2
</pre>
The transformation is shown schematically in Figure~(fig:rotate).
[[Image:rotate.png|frame|center|Schematic transformation of data with <tt>sfrotate</tt>.]]

==sfrtoc==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert real data to complex (by adding zero imaginary part).
|-
! colspan="4" | sfrtoc < real.rsf > cmplx.rsf
|-
| colspan="4" | See also: sfcmplx
|}
The input to <tt>sfrtoc</tt> can be any <tt>type=float</tt> dataset:
<pre>
bash$ sfspike n1=10 n2=20 n3=30 >real.rsf
bash$ sfin real.rsf
real.rsf:
in="/var/tmp/real.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
</pre>
The output dataset will have <tt>type=complex</tt>, and its binary will be twice the size of the input:
<pre>
bash$ <real.rsf sfrtoc >complex.rsf
bash$ sfin complex.rsf
complex.rsf:
in="/var/tmp/complex.rsf@"
esize=8 type=complex form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 48000 bytes
</pre>

==sfscale==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Scale data.
|-
! colspan="4" | sfscale < in.rsf > out.rsf axis=0 rscale=0. dscale=1.
|-
| colspan="4" | To scale by a constant factor, you can also use sfmath or sfheadermath.
|-
| ''int '' || '''axis=0''' || || Scale by maximum in the dimensions up to this axis.
|-
| ''float '' || '''dscale=1.''' || || Scale by this factor (works if rscale=0)
|-
| ''float '' || '''rscale=0.''' || || Scale by this factor.
|}
<tt>sfscale</tt> scales the input dataset by a factor. Here
are some simple examples. First, let us create a test dataset.
<pre>
bash$ sfmath n1=5 n2=3 o1=1 o2=1 output="x1*x2" > test.rsf
bash$ < test.rsf sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
10: 3 6 9 12 15
</pre>
Scale every data point by 2:
<pre>
bash$ < test.rsf sfscale dscale=2 | sfdisfil
0: 2 4 6 8 10
5: 4 8 12 16 20
10: 6 12 18 24 30
</pre>
Divide every trace by its maximum value:
<pre>
bash$ < test.rsf sfscale axis=1 | sfdisfil
0: 0.2 0.4 0.6 0.8 1
5: 0.2 0.4 0.6 0.8 1
10: 0.2 0.4 0.6 0.8 1
</pre>
Divide by the maximum value in the whole 2-D dataset:
<pre>
bash$ < test.rsf sfscale axis=2 | sfdisfil
0: 0.06667 0.1333 0.2 0.2667 0.3333
5: 0.1333 0.2667 0.4 0.5333 0.6667
10: 0.2 0.4 0.6 0.8 1
</pre>
The <tt>rscale=</tt> parameter is synonymous to <tt>dscale=</tt> except
when it is equal to zero. With <tt>sfscale dscale=0</tt>, the dataset gets
multiplied by zero. If using <tt>rscale=0</tt>, the other parameters are
used to define scaling. Thus, <tt>sfscale rscale=0 axis=1</tt> is
equivalent to <tt>sfscale axis=1</tt>, and <tt>sfscale rscale=0</tt>
is equivalent to <tt>sfscale dscale=1</tt>.

==sfspike==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate simple data: spikes, boxes, planes, constants.
|-
! colspan="4" | sfspike > spike.rsf mag= nsp=1 k#=[0,...] l#=[k1,k2,...] p#=[0,...] n#= o#=[0,0,...] d#=[0.004,0.1,0.1,...] label#=[Time,Distance,Distance,...] unit#=[s,km,km,...] title=
|-
| colspan="4" | Spike positioning is given in samples and starts with 1.
|-
| ''float '' || '''d#=[0.004,0.1,0.1,...]''' || || sampling on #-th axis
|-
| ''ints '' || '''k#=[0,...]''' || || spike starting position [nsp]
|-
| ''ints '' || '''l#=[k1,k2,...]''' || || spike ending position [nsp]
|-
| ''string '' || '''label#=[Time,Distance,Distance,...]''' || || label on #-th axis
|-
| ''floats '' || '''mag=''' || || spike magnitudes [nsp]
|-
| ''int '' || '''n#=''' || || size of #-th axis
|-
| ''int '' || '''nsp=1''' || || Number of spikes
|-
| ''float '' || '''o#=[0,0,...]''' || || origin on #-th axis
|-
| ''floats '' || '''p#=[0,...]''' || || spike inclination (in samples) [nsp]
|-
| ''string '' || '''title=''' || || title for plots
|-
| ''string '' || '''unit#=[s,km,km,...]''' || || unit on #-th axis
|}

<tt>sfspike</tt> takes no input and generates an output with
"spikes". It is an easy way to create data. Here is an example:
<pre>
bash$ sfspike n1=5 n2=3 k1=4 k2=1 | sfdisfil
0: 0 0 0 1 0
5: 0 0 0 0 0
10: 0 0 0 0 0
</pre>
The spike location is specified by parameters <tt>k1=4</tt> and
<tt>k2=1</tt>. Note that the locations are numbered starting from 1.
If one of the parameters is omitted or given the value of zero, the
spike in the corresponding direction becomes a plane:
<pre>
bash$ sfspike n1=5 n2=3 k1=4 | sfdisfil
0: 0 0 0 1 0
5: 0 0 0 1 0
10: 0 0 0 1 0

</pre>
If no spike parameters are given, the whole dataset is filled with ones:
<pre>
bash$ sfspike n1=5 n2=3 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
</pre>
To create several spikes, use the <tt>nsp=</tt> parameter and give a comma-separated list of values to <tt>k#=</tt> arguments:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 | sfdisfil
0: 1 0 0 0 0
5: 0 0 1 0 0
10: 0 0 0 1 0
</pre>
If the number of values in the list is smaller than <tt>nsp</tt>, the
last value gets repeated, and the spikes add on top of each other,
creating larger amplitudes:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3 k2=1,2 | sfdisfil
0: 1 0 0 0 0
5: 0 0 2 0 0
10: 0 0 0 0 0
</pre>
The magnitude of the spikes can be controlled explicitly with the
<tt>mag=</tt> parameter:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 mag=1,4,2 | sfdisfil
0: 1 0 0 0 0
5: 0 0 4 0 0
10: 0 0 0 2 0
</pre>
You can create boxes instead of spikes by using <tt>l#=</tt>
parameters:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 l1=4 k2=2 mag=8 | sfdisfil
0: 0 0 0 0 0
5: 0 8 8 8 0
10: 0 0 0 0 0
</pre>
In this case, <tt>k1=2</tt> specifies the box start, and <tt>l1=4</tt>
specifies the box end.
Finally, multi-dimensional planes can be given an inclination by using <tt>p#=</tt> parameters:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 p2=1 | sfdisfil
0: 0 1 0 0 0
5: 0 0 1 0 0
10: 0 0 0 1 0
</pre>
Note that <tt>sfspike</tt> interprets the <tt>p#=</tt> parameters in stepout from sample to sample, not in terms of axes units (i.e. s/m).

More than one p parameter can be specified. In this case, a (hyper) plane will be created.

When the inclination value is not integer, simple linear interpolation is used:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 p2=0.7 | sfdisfil
0: 0 1 0 0 0
5: 0 0.3 0.7 0 0
10: 0 0 0.6 0.4 0
</pre>
<tt>sfspike</tt> supplies default dimensions and labels to all axis:
<pre>
bash$ sfspike n1=5 n2=3 n3=4 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=5 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=4 d3=0.1 o3=0 label3="Distance" unit3="km"
60 elements 240 bytes
</pre>
As you can see, the first axis is assumed to be time, with sampling of
<math>0.004</math> seconds. All other axes are assumed to be distance, with
sampling of <math>0.1</math> kilometers. All these parameters can be changed on
the command line.
<pre>
bash$ sfspike n1=5 n2=3 n3=4 label3=Offset unit3=ft d3=20 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=5 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=4 d3=20 o3=0 label3="Offset" unit3="ft"
60 elements 240 bytes
</pre>

==sfspray==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Extend a dataset by duplicating in the specified axis dimension.
|-
! colspan="4" | sfspray < in.rsf > out.rsf axis=2 n= d= o= label= unit=
|-
| colspan="4" | This operation is adjoint to sfstack.
|-
| ''int '' || '''axis=2''' || || which axis to spray
|-
| ''float '' || '''d=''' || || Sampling of the newly created dimension
|-
| ''string '' || '''label=''' || || Label of the newly created dimension
|-
| ''int '' || '''n=''' || || Size of the newly created dimension
|-
| ''float '' || '''o=''' || || Origin of the newly created dimension
|-
| ''string '' || '''unit=''' || || Units of the newly created dimension
|}

<tt>sfspray</tt> extends the input hypercube by replicating the data
in one of the dimensions. The output dataset acquires one additional
dimension. Here is an example:
Start with a 2-D dataset
<pre>
bash$ sfmath n1=5 n2=2 output=x1+x2 > test.rsf
bash$ sfin test.rsf
test.rsf:
in="/var/tmp/test.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=2 d2=1 o2=0
10 elements 40 bytes
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
</pre>
Extend the data in the second dimension
<pre>
bash$ < test.rsf sfspray axis=2 n=3 > test2.rsf
bash$ sfin test2.rsf
test2.rsf:
in="/var/tmp/test2.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=3 d2=1 o2=0
n3=2 d3=1 o3=0
30 elements 120 bytes
bash$ < test2.rsf sfdisfil
0: 0 1 2 3 4
5: 0 1 2 3 4
10: 0 1 2 3 4
15: 1 2 3 4 5
20: 1 2 3 4 5
25: 1 2 3 4 5
</pre>
The output is three-dimensional, with traces from the original
data duplicated along the second axis.
Extend the data in the third dimension
<pre>
bash$ < test.rsf sfspray axis=3 n=2 > test3.rsf
bash$ sfin test3.rsf
test3.rsf:
in="/var/tmp/test3.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=2 d2=1 o2=0
n3=2 d3=? o3=?
20 elements 80 bytes
bash$ < test3.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 0 1 2 3 4
15: 1 2 3 4 5
</pre>
The output is also three-dimensional, with the original data replicated
along the third axis.

==sfstack==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Stack a dataset over one of the dimensions.
|-
! colspan="4" | sfstack < in.rsf > out.rsf axis=2 rms=n norm=y min=n max=n
|-
| colspan="4" | This operation is adjoint to sfspray.
|-
| ''int '' || '''axis=2''' || || which axis to stack
|-
| ''bool '' || '''max=n''' || [y/n] || If y, find maximum instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''min=n''' || [y/n] || If y, find minimum instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''norm=y''' || [y/n] || If y, normalize by fold.
|-
| ''bool '' || '''rms=n''' || [y/n] || If y, compute the root-mean-square instead of stack.
|}
While <tt>sfspray</tt> adds a dimension to a hypercube,
<tt>sfstack</tt> effectively removes one of the dimensions by stacking
over it. Here are some examples:
<pre>
bash$ sfmath n1=5 n2=3 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
bash$ < test.rsf sfstack axis=2 | sfdisfil
0: 1.5 2 3 4 5
bash$ < test.rsf sfstack axis=1 | sfdisfil
0: 2.5 3 4
</pre>
Why is the first value not 1 (in the first case) or 2 (in the second
case)? By default, <tt>sfstack</tt> normalizes the stack by the fold
(the number of non-zero entries). To avoid normalization, use
<tt>norm=n</tt>, as follows:
<pre>
bash$ < test.rsf sfstack norm=n | sfdisfil
0: 3 6 9 12 15
</pre>
<tt>sfstack</tt> can also compute root-mean-square values as
well as minimum and maximum values.
<pre>
bash$ < test.rsf sfstack rms=y | sfdisfil
0: 1.581 2.16 3.109 4.082 5.066
bash$ < test.rsf sfstack min=y | sfdisfil
0: 0 1 2 3 4
bash$ < test.rsf sfstack axis=1 max=y | sfdisfil
0: 4 5 6
</pre>

==sftransp==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Transpose two axes in a dataset.
|-
! colspan="4" | sftransp < in.rsf > out.rsf memsize=sf_memsize() plane=
|-
| colspan="4" | If you get a "Cannot allocate memory" error, give the program a memsize=1 command-line parameter to force out-of-core operation.
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''int '' || '''plane=''' || || Two-digit number with axes to transpose. The default is 12
|}

The <tt>sftransp</tt> program transposes the input hypercube
exchanging the two axes specified by the plane= parameter.
<pre>
bash$ sfspike n1=10 n2=20 n3=30 > orig123.rsf
bash$ sfin orig123.rsf
orig123.rsf:
in="/var/tmp/orig123.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
bash$ <orig123.rsf sftransp plane=23 >out132.rsf
bash$ sfin out132.rsf
out132.rsf:
in="/var/tmp/out132.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=30 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=20 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
bash$ <orig123.rsf sftransp plane=13 >out321.rsf
bash$ sfin out321.rsf
out321.rsf:
in="/var/tmp/out132.rsf@"
esize=4 type=float form=native
n1=30 d1=0.1 o1=0 label1="Distance" unit1="km"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=10 d3=0.004 o3=0 label3="Time" unit3="s"
6000 elements 24000 bytes
</pre>
<tt>sftransp</tt> tries to fit the dataset in memory to transpose it
there but, if not enough memory is available, it performs a slower
transpose out of core using disk operations. You can control the
amount of available memory using the memsize= parameter or
the RSFMEMSIZE environmental variable.

==sfwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a portion of the dataset.
|-
! colspan="4" | sfwindow < in.rsf > out.rsf verb=n squeeze=y j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''int '' || '''f#=(0,...)''' || || window start in #-th dimension
|-
| ''int '' || '''j#=(1,...)''' || || jump in #-th dimension
|-
| ''float '' || '''max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)''' || || maximum in #-th dimension
|-
| ''float '' || '''min#=(o1,o2,,...)''' || || minimum in #-th dimension
|-
| ''int '' || '''n#=(0,...)''' || || window size in #-th dimension
|-
| ''bool '' || '''squeeze=y''' || [y/n] || if y, squeeze dimensions equal to 1 to the end
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

sfwindow is used to window a portion of the dataset. Here is
a quick example: Start by creating some data.
<pre>
bash$ sfmath n1=5 n2=3 o1=1 o2=1 output="x1*x2" > test.rsf
bash$ < test.rsf sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
10: 3 6 9 12 15
</pre>
Now window the first two rows:
<pre>
bash$ < test.rsf sfwindow n2=2 | sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
</pre>
Window the first three columns:
<pre>
bash$ < test.rsf sfwindow n1=3 | sfdisfil
0: 1 2 3 2 4
5: 6 3 6 9
</pre>
Window the middle row:
<pre>
bash$ < test.rsf sfwindow f2=1 n2=1 | sfdisfil
0: 2 4 6 8 10
</pre>
You can interpret the f# and n# parameters as
meaning "skip that many rows/columns" and "select that many
rows/columns" correspondingly. Window the middle point in the dataset:
<pre>
bash$ < test.rsf sfwindow f1=2 n1=1 f2=1 n2=1 | sfdisfil
0: 6
</pre>
Window every other column:
<pre>
bash$ < test.rsf sfwindow j1=2 | sfdisfil
0: 1 3 5 2 6
5: 10 3 9 15
</pre>
Window every third column:
<pre>
bash$ < test.rsf sfwindow j1=3 | sfdisfil
0: 1 4 2 8 3
5: 12
</pre>
Alternatively, sfwindow can use the minimum and maximum
parameters to select a window. In the following example, we are
creating a dataset with sfspike and then windowing a portion of it
between 1 and 2 seconds in time and sampled at 8 miliseconds.
<pre>
bash$ sfspike n1=1000 n2=10 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=1000 d1=0.004 o1=0 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
10000 elements 40000 bytes
bash$ < spike.rsf sfwindow min1=1 max1=2 d1=0.008 > window.rsf
bash$ sfin window.rsf
window.rsf:
in="/var/tmp/window.rsf@"
esize=4 type=float form=native
n1=126 d1=0.008 o1=1 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
1260 elements 5040 bytes
</pre>
By default, sfwindow "squeezes" the hypercube dimensions
that are equal to one toward the end of the dataset. Here is an
example of taking a time slice:
<pre>
bash$ < spike.rsf sfwindow n1=1 min1=1 > slice.rsf
bash$ sfin slice.rsf
slice.rsf:
in="/var/tmp/slice.rsf@"
esize=4 type=float form=native
n1=10 d1=0.1 o1=0 label1="Distance" unit1="km"
n2=1 d2=0.004 o2=1 label2="Time" unit2="s"
10 elements 40 bytes
</pre>
You can change this behavior by specifying squeeze=n.
<pre>
bash$ < spike.rsf sfwindow n1=1 min1=1 squeeze=n > slice.rsf
bash$ sfin slice.rsf
slice.rsf:
in="/var/tmp/slice.rsf@"
esize=4 type=float form=native
n1=1 d1=0.004 o1=1 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
10 elements 40 bytes
</pre>

=Seismic programs=
Programs in this category are specific for operations on seismic data. The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/seismic/ system/seismic] in the Madagascar distribution.

==sffkamo==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Computes Azimuth Move-Out (AMO) operator in the f-k log-stretch domain
|-
! colspan="4" | sffkamo < in.rsf > out.rsf h1= h2= f1= f2= maxe=10.
|-
| ''float '' || '''f1=''' || || input azimuth in degrees
|-
| ''float '' || '''f2=''' || || output azimuth in degrees
|-
| ''float '' || '''h1=''' || || input offset
|-
| ''float '' || '''h2=''' || || output offset
|-
| ''float '' || '''maxe=10.''' || || stability constraint
|}
Sample workflow from [http://m8r.info/RSF/book/sep/fkamo/paper_html/ SEP-110, 63-70 (2001)], with the addition of a bandpass for the input:

Create input -- a (t,x,y) common-offset cube:
<bash>
sfspike \
n1=128 o1=0.4 d1=0.0032 k1=65 label1=t \
n2=256 o2=-1.536 d2=0.012 k2=129 label2=x \
n3=128 o3=-1.024 d3=0.016 k3=65 label3=y | \
sfbandpass flo=5 fhi=60 > spikebps.rsf
</bash>

Apply log-stretch FFT:
<bash>
<spikebps.rsf sfstretch rule=L dens=4 |\
sffft1 |\
sffft3 axis=2 |\
sffft3 axis=3 > spikefft3.rsf
</bash>

Compute AMO operator for a file of the dimensions of <tt>spikefft3.rsf</tt>. The only information taken from stdin are the n, o, d parameters:
<bash>
<spikefft3.rsf sffkamo h2=2 f2=10 h1=1.8 f1=30 >oper.rsf
</bash>

Apply the operator by multiplication and fft back to (t, mx, my):
<bash>
< spikefft3.rsf sfadd mode=prod oper.rsf |\
sffft3 axis=3 inv=y |\
sffft3 axis=2 inv=y |\
sffft1 inv=y |\
sfstretch rule=L dens=4 inv=y > spikeamo.rsf
</bash>

Prepare for 8-bit greyscale visualization:
<bash>
< spikeamo.rsf sfbyte pclip=100 gainpanel=a > spikebyte.rsf
</bash>

Picture from the middle of the impulse response:
<bash>
<spikebyte.rsf sfgrey3 frame1=65 frame2=129 frame3=65 \
point1=0.333 title='AMO saddle, no f-k filter' | sfpen &
</bash>

Picture illustrating the artifacts (i.e. need for f-k filter):
<bash>
< spikebyte.rsf sfgrey3 frame1=65 frame2=97 frame3=97 \
point1=0.333 title='No f-k filter' | sfpen &
</bash>

Apply the f-k filter and (in this case) visualize:
<bash>
< spikeamo.rsf sffft1 |\
sffft3 axis=2 |\
sffft3 axis=3 |\
sfdipfilter v1=-2.5 v2=-1.5 v3=1.5 v4=2.5 taper=2 pass=0 dim=3 |\
sffft3 axis=3 inv=y |\
sffft3 axis=2 inv=y |\
sffft1 inv=y |\
sfbyte pclip=100 gainpanel=a |\
sfgrey3 frame1=65 frame2=97 frame3=97 point1=0.333 title='With f-k filter' |\
sfpen &
</bash>

==sfheaderattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Integer header attributes.
|-
! colspan="4" | sfheaderattr < head.rsf
|-
| colspan="4" | Only nonzero values are reported.
|}

The <tt>sfheaderattr</tt> examines the contents of a trace header file,
typically generated by <tt>sfsegyread</tt>. In the example below, we examine
trace headers in the output of <tt>suplane</tt>, a program from Seismic Unix.
<pre>
bash$ suplane > plane.su
bash$ sfsegyread tape=plane.su su=y tfile=tfile.rsf > plane.rsf
bash$ sfheaderattr < tfile.rsf
*******************************************
71 headers, 32 traces
key[0]="tracl" min[0]=1 max[31]=32 mean=16.5
key[1]="tracr" min[0]=1 max[31]=32 mean=16.5
key[11]="offset" min[0]=400 max[31]=400 mean=400
key[38]="ns" min[0]=64 max[31]=64 mean=64
key[39]="dt" min[0]=4000 max[31]=4000 mean=4000
*******************************************
</pre>
For different standard keywords, a minimum, maximum, and mean values
are reported unless they are identically zero. This quick inspection
can help in identifying meaningful keywords set in the data. The input
data type must be <tt>int</tt>.

==sfheadermath==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Mathematical operations, possibly on header keys.
|-
! colspan="4" | sfheadermath < in.rsf > out.rsf memsize=sf_memsize() output=
|-
| colspan="4" | Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs See also sfmath. An addition operation can be performed by sfstack.
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''string '' || '''output=''' || || Describes the output in a mathematical notation.
|}
<tt>sfheadermath</tt> is a versatile program for mathematical
operations on rows of the input file. If the input file is an
<tt>n1</tt> by <tt>n2</tt> matrix, the output will be a <tt>1</tt> by
<tt>n2</tt> matrix that contains one row made out of mathematical
operations on the other rows. <tt>sfheadermath</tt> can identify a row
by number or by a standard SEGY keyword. The latter is useful for
processing headers extracted from SEGY or SU files.
Here is an example. First, we create an SU file with <tt>suplane</tt> and convert it to RSF using <tt>sfsegyread</tt>.
<pre>
bash$ suplane > plane.su
bash$ sfsegyread tape=plane.su su=y tfile=tfile.rsf > plane.rsf
</pre>
The trace header information is saved in <tt>tfile.rsf</tt>. It
contains 71 headers for 32 traces in integer format.
<pre>
bash$ sfin tfile.rsf
tfile.rsf:
in="/tmp/tfile.rsf@"
esize=4 type=int form=native
n1=71 d1=? o1=?
n2=32 d2=? o2=?
2272 elements 9088 bytes
</pre>
Next, we will convert <tt>tfile.rsf</tt> to a floating-point format
and run <tt>sfheadermath</tt> to create a new header.
<pre>
bash$ < tfile.rsf sfdd type=float | \
sfheadermath myheader=1 output="sqrt(myheader+(2+10*offset^2))" > new.rsf
bash$ sfin new.rsf
new.rsf:
in="/tmp/new.rsf@"
esize=4 type=float form=native
n1=1 d1=? o1=?
n2=32 d2=? o2=?
32 elements 128 bytes
</pre>
We defined "myheader" as being the row number 1 in the input (note
that numbering starts with 0) and combined it with "offset", which
is a standard SEGY keyword that denotes row number 11 (see the output
of <tt>sfheaderattr</tt> above.) A variety of mathematical expressions
can be defined in the <tt>output=</tt> string. The expression
processing engine is shared with <tt>sfmath</tt>.

==sfsegyheader==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Make a trace header file for segywrite.
|-
! colspan="4" | sfsegyheader < in.rsf > out.rsf n1= d1=
|-
| colspan="4" | Use the output for tfile= argument in segywrite.
|-
| ''float '' || '''d1=''' || || trace sampling
|-
| ''int '' || '''n1=''' || || number of samples in a trace
|}

==sfsegyread==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a SEG-Y or SU dataset to RSF.
|-
! colspan="4" | sfsegyread mask=msk.rsf > out.rsf tfile=hdr.rsf verb=n su= suxdr=n endian=y format=segyformat (bhead) ns=segyns (bhead) tape= read= hfile= bfile=
|-
| colspan="4" | Data headers and trace headers are separated from the data. "suread" is equivalent to "segyread su=y" SEGY key names: tracl: trace sequence number within line 0 tracr: trace sequence number within reel 4 fldr: field record number 8 tracf: trace number within field record 12 ep: energy source point number 16 cdp: CDP ensemble number 20 cdpt: trace number within CDP ensemble 24 trid: trace identification code: 1 = seismic data 2 = dead 3 = dummy 4 = time break 5 = uphole 6 = sweep 7 = timing 8 = water break 9---, N = optional use (N = 32,767) 28 nvs: number of vertically summed traces 30 nhs: number of horizontally summed traces 32 duse: data use: 1 = production 2 = test 34 offset: distance from source point to receiver group (negative if opposite to direction in which the line was shot) 36 gelev: receiver group elevation from sea level (above sea level is positive) 40 selev: source elevation from sea level (above sea level is positive) 44 sdepth: source depth (positive) 48 gdel: datum elevation at receiver group 52 sdel: datum elevation at source 56 swdep: water depth at source 60 gwdep: water depth at receiver group 64 scalel: scale factor for previous 7 entries with value plus or minus 10 to the power 0, 1, 2, 3, or 4 (if positive, multiply, if negative divide) 68 scalco: scale factor for next 4 entries with value plus or minus 10 to the power 0, 1, 2, 3, or 4 (if positive, multiply, if negative divide) 70 sx: X source coordinate 72 sy: Y source coordinate 76 gx: X group coordinate 80 gy: Y group coordinate 84 counit: coordinate units code: for previous four entries 1 = length (meters or feet) 2 = seconds of arc (in this case, the X values are unsigned longitude and the Y values are latitude, a positive value designates the number of seconds east of Greenwich or north of the equator 88 wevel: weathering velocity 90 swevel: subweathering velocity 92 sut: uphole time at source 94 gut: uphole time at receiver group 96 sstat: source static correction 98 gstat: group static correction 100 tstat: total static applied 102 laga: lag time A, time in ms between end of 240- byte trace identification header and time break, positive if time break occurs after end of header, time break is defined as the initiation pulse which maybe recorded on an auxiliary trace or as otherwise specified by the recording system 104 lagb: lag time B, time in ms between the time break and the initiation time of the energy source, may be positive or negative 106 delrt: delay recording time, time in ms between initiation time of energy source and time when recording of data samples begins (for deep water work if recording does not start at zero time) 108 muts: mute time--start 110 mute: mute time--end 112 ns: number of samples in this trace 114 dt: sample interval, in micro-seconds 116 gain: gain type of field instruments code: 1 = fixed 2 = binary 3 = floating point 4 ---- N = optional use 118 igc: instrument gain constant 120 igi: instrument early or initial gain 122 corr: correlated: 1 = no 2 = yes 124 sfs: sweep frequency at start 126 sfe: sweep frequency at end 128 slen: sweep length in ms 130 styp: sweep type code: 1 = linear 2 = cos-squared 3 = other 132 stas: sweep trace length at start in ms 134 stae: sweep trace length at end in ms 136 tatyp: taper type: 1=linear, 2=cos^2, 3=other 138 afilf: alias filter frequency if used 140 afils: alias filter slope 142 nofilf: notch filter frequency if used 144 nofils: notch filter slope 146 lcf: low cut frequency if used 148 hcf: high cut frequncy if used 150 lcs: low cut slope 152 hcs: high cut slope 154 year: year data recorded 156 day: day of year 158 hour: hour of day (24 hour clock) 160 minute: minute of hour 162 sec: second of minute 164 timbas: time basis code: 1 = local 2 = GMT 3 = other 166 trwf: trace weighting factor, defined as 1/2^N volts for the least sigificant bit 168 grnors: geophone group number of roll switch position one 170 grnofr: geophone group number of trace one within original field record 172 grnlof: geophone group number of last trace within original field record 174 gaps: gap size (total number of groups dropped) 176 otrav: overtravel taper code: 1 = down (or behind) 2 = up (or ahead) 178 cdpx: X coordinate of CDP 180 cdpy: Y coordinate of CDP 184 iline: in-line number 188 xline: cross-line number 192 shnum: shotpoint number 196 shsca: shotpoint scalar 200 tval: trace value meas. 202 tconst4: transduction const 204 tconst2: transduction const 208 tunits: transduction units 210 device: device identifier 212 tscalar: time scalar 214 stype: source type 216 sendir: source energy dir. 218 unknown: unknown 222 smeas4: source measurement 224 smeas2: source measurement 228 smeasu: source measurement unit 230 unass1: unassigned 232 unass2: unassigned 236
|-
| ''string '' || '''bfile=''' || || output binary data header file
|-
| ''bool '' || '''endian=y''' || [y/n] || Whether to automatically estimate endianness or not
|-
| ''int '' || '''format=segyformat (bhead)''' || [1,2,3,5] || Data format. The default is taken from binary header.
:1 is IBM floating point
:2 is 4-byte integer
:3 is 2-byte integer
:5 is IEEE floating point
|-
| ''string '' || '''hfile=''' || || output text data header file
|-
| ''string '' || '''mask=''' || || optional header mask for reading only selected traces (auxiliary input file name)
|-
| ''int '' || '''ns=segyns (bhead)''' || || Number of samples. The default is taken from binary header
|-
| ''string '' || '''read=''' || || what to read: h - header, d - data, b - both (default)
|-
| ''bool '' || '''su=''' || [y/n] || y if input is SU, n if input is SEGY
|-
| ''bool '' || '''suxdr=n''' || [y/n] || y, SU has XDR support
|-
| ''string '' || '''tape=''' || || input data
|-
| ''string '' || '''tfile=''' || || output trace header file (auxiliary output file name)
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

The SEG Y format is an [http://en.wikipedia.org/wiki/Open_standard open standard] for the exchange of geophysical data. It is controlled by the non-profit [http://www.seg.org/SEGportalWEBproject/portals/SEG_Online.portal?_nfpb=true&_pageLabel=pg_gen_content&Doc_Url=prod/SEG-Publications/Pub-Yearbook/committees.htm SEG Technical Standards Committee]. There are two versions of this standard: [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev0.pdf rev0] (1975)<ref>Barry, K.M., Cavers, D.A., and Kneale, C.W. 1975. Recommended standards for digital tape formats. ''Geophysics'', '''40''', no. 02, 344–352.</ref> and [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev1.pdf rev1] (2002)<ref>Norris, M.W., Faichney, A.K., ''Eds''. 2001. SEG Y rev1 Data Exchange format. Society of Exploration Geophysicists, Tulsa, OK, 45 pp.</ref>. The implementation in <tt>sfsegyread</tt> is a mixture of rev0 (i.e. no checks for Extended Textual Headers) and rev1 ([http://en.wikipedia.org/wiki/IEEE_floating-point_standard IEEE floating point format] allowed for trace data samples).

A SEG-Y file as understood by <tt>sfsegyread</tt> contains a "Reel Identification Header" (3200 bytes in EBCDIC followed by 400 bytes in a binary encoding), followed by a number of "Trace Blocks". Each "Trace Block" contains a 240-byte "Trace Header" (binary) followed by "Trace Data" -- a sequence of <tt>ns</tt> samples. Binary values in both reel headers and trace headers are two's complement integers, either two bytes or four bytes long. There are no floating-point values defined in the headers. Trace Data samples can have various encodings, either floating point or integer, described further down, but they are all big-endian. To convert from SEG-Y to RSF, <tt>sfsegyread</tt> will strip the tape reel EBCDIC header and convert it to ASCII, will extract the reel binary header without changing it, and will put the trace headers into one RSF file, and the traces themselves on another.

===SEG-Y Trace Headers===
In the SEG-Y standard, only the first 180 bytes of the 240-byte trace header are defined; bytes 181-240 are reserved for non-standard header information, and these locations are increasingly used in modern SEG-Y files and its variants. The standard provides for a total of 71 4-byte and 2-byte predefined header words. These 71 standard words have defined lengths and byte offsets, and only these words and byte locations are read using <tt>segyread</tt> and output to the RSF header file with the <tt>hfile=</tt> option. The user may remap these predefined keywords to a different byte offsets.

===SU File Format===
An [http://www.cwp.mines.edu/sututor/node22.html SU file] is nothing more than a SEG-Y file without the reel headers, and with the Trace Data samples in the native encoding of the CPU the file was created on (Attention -- limited portability!). So, to convert from SU to RSF, <tt>sfsegyread</tt> will just separate headers and traces into two RSF files.

===SEG-Y specific parameters===
*<tt>hfile=</tt> specifies the name of the file in which the EBCDIC reel header will be put after conversion to ASCII. If you are certain there is no useful information in it, <tt>hfile=/dev/null</tt> works just fine. If you do not specify anything for this parameter you will get an ASCII file named <tt>header</tt> in the current directory. If you want to quickly preview this header before running <tt>sfsegyread</tt>, use<pre>dd if=input.segy count=40 bs=80 cbs=80 conv=unblock,ascii</pre>
*<tt>bfile=</tt> specifies name of the file in which the binary reel header (the 400-bytes thing following the 3600-bytes EBCDIC) will be put without any conversion. The default name is "binary". Unless you have software that knows how to read exactly this special type of file, it will be completely useless, so do <tt>bfile=/dev/null</tt>
*<tt>format=</tt> specifies the format in which the trace data samples are in the SEG-Y input file. This is read from the binary reel header of the SEG-Y file. Valid values are 1(IBM floating point), 2 (4-byte integer), 3 (2-byte integer) and 5 (IEEE floating point). If the input file is SU, the format will be assumed to be the native <tt>float</tt> format.

*<tt>keyname=</tt> specifies the byte offset to remap a header using the trace header key names shown above. For example, if the CDP locations have been placed in bytes 181-184 instead of the standard 21-24, <tt>cdp=180</tt> will remap the trace header to that location.

===SU-specific parameters===
*<tt>suxdr=</tt> specifies whether the input file was created with a SU package with XDR support enabled. If you have access to the source code of your SU install (try <tt>$CWPROOT/src</tt>), type: <tt>grep 'XDRFLAG =' $CWPROOT/src/Makefile.config</tt> and look at the last uncommented entry. If no value is given for <tt>XDRFLAG</tt>, the package was not compiled with XDR support.
===Common parameters===
*<tt>su=</tt> specifies if the input file is SU or SEG-Y. Default is <tt>su=n</tt> (SEG-Y file).
*<tt>tape=</tt> specifies the input data. Stdin could not be used because <tt>sfsegyread</tt> has to work with tapes, and needs to fseek back and forth through the input file. Thankfully, output is on stdout.
*<tt>read=</tt> specifies what parts of the "Trace Blocks" will be read. It can be <tt>read=t</tt> (only trace data is read), <tt>read=h</tt> (only trace headers are read) or <tt>read=b</tt> (both are read).
*<tt>tfile=</tt> gives the name of the RSF file to which trace headers are written. Obviously, it should be only specified with <tt>read=h</tt> or <tt>read=b</tt>.
*<tt>mask=</tt> is an optional parameter specifying the name of a mask that says which traces will be read. The mask is a 1-D RSF file with integers. The number of samples in the mask is the same as the number of traces in the unmasked SEG-Y. In places corresponding to unwanted traces there should be zeros in the mask.
*<tt>ns=</tt> specifies the number of samples in a trace. For SEG-Y files, the default is taken from the binary reel header, and for SU files, from the header of the first trace. This parameter is however critical enough that a command line override was given for it.
*<tt>verbose=</tt> is the verbosity flag. Can be <tt>y</tt> or <tt>n</tt>.
*<tt>endian=</tt> is a y/n flag (default y), specifying whether to automatically estimate or not if samples in the Trace Data blocks are big-endian or little-endian. Try it if you are in trouble and do not know what else to do, otherwise let the automatic estimation do its job.

==sfsegywrite==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert an RSF dataset to SEGY or SU.
|-
! colspan="4" | sfsegywrite < in.rsf tfile=hdr.rsf verb=false su=false endian=sf_endian() tape= hfile= bfile=
|-
| colspan="4" | Merges trace headers with data.
|-
| ''string '' || '''bfile=''' || || input binary data header file
|-
| ''bool '' || '''endian=sf_endian()''' || [y/n] || big/little endian flag. The default is estimated automatically
|-
| ''string '' || '''hfile=''' || || input text data header file
|-
| ''bool '' || '''su=n''' || [y/n] || y if output is SU, n if output is SEGY
|-
| ''string '' || '''tape=''' || ||
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}
Please see <tt>sfsegyread</tt> for a complete description of parameter meanings and background issues. Parameters <tt>bfile</tt> and <tt>hfile</tt> should only be given values when the desired file is SEG-Y (default). The output file is specified by the <tt>tape=</tt> tag.
=Generic programs=
Programs in this category are general signal and image processing programs. The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/generic/ system/generic] in the Madagascar distribution.
==sfnoise==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Add random noise to the data.
|-
! colspan="4" | sfnoise < in.rsf > out.rsf seed=time(NULL) type=y var= range= mean=0 rep=n
|-
| ''float '' || '''mean=0''' || || noise mean
|-
| ''float '' || '''range=''' || || noise range (default=1)
|-
| ''bool '' || '''rep=n''' || [y/n] || if y, replace data with noise
|-
| ''int '' || '''seed=time(NULL)''' || || random seed
|-
| ''bool '' || '''type=y''' || [y/n] || noise distribution, y: normal, n: uniform
|-
| ''float '' || '''var=''' || || noise variance
|}
See the [http://www.ahay.org/rsflog/index.php?/archives/262-Program-of-the-month-sfnoise.html Program of the Month] blog entry.

=Plotting programs (stable)=
The source files for these programs can be found under
[http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/plot/main/ plot/main]
in the Madagascar distribution.

==sfbox==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Draw a balloon-style label.
|-
! colspan="4" | sfbox lab_color=VP_WHITE lab_fat=0 pscale=1. pointer=y reverse=n lat=0. long=90. angle=0. x0=0. y0=0. scale0=1. xt=2. yt=0. x_oval=0. y_oval=0. boxit=y length= scalet= size=.25 label= > out.vpl
|-
| ''float '' || '''angle=0.''' || || longitude of floating label in 3-D
|-
| ''bool '' || '''boxit=y''' || [y/n] || if y, create a box around text
|-
| ''int '' || '''lab_color=VP_WHITE''' || || label color
|-
| ''int '' || '''lab_fat=0''' || || label fatness
|-
| ''string '' || '''label=''' || || text for label
|-
| ''float '' || '''lat=0.''' || ||
|-
| ''float '' || '''length=''' || || normalization for xt and yt
|-
| ''float '' || '''long=90.''' || || latitude and longitude of viewpoint in 3-D
|-
| ''bool '' || '''pointer=y''' || [y/n] || if y, create arrow pointer
|-
| ''float '' || '''pscale=1.''' || || scale factor for width of pointer
|-
| ''bool '' || '''reverse=n''' || [y/n] ||
|-
| ''float '' || '''scale0=1.''' || || scale factor for x0 and y0
|-
| ''float '' || '''scalet=''' || ||
|-
| ''float '' || '''size=.25''' || || text height in inches
|-
| ''float '' || '''x0=0.''' || ||
|-
| ''float '' || '''x_oval=0.''' || ||
|-
| ''float '' || '''xt=2.''' || ||
|-
| ''float '' || '''y0=0.''' || || position of the pointer tip
|-
| ''float '' || '''y_oval=0.''' || || size of the oval around pointer
|-
| ''float '' || '''yt=0.''' || || relative position of text
|}
==sfcontour==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Contour plot.
|-
! colspan="4" | sfcontour < in.rsf c= min1=o1 min2=o2 max1=o1+(n1-1)*d1 max2=o2+(n2-1)*d2 nc=50 dc= c0= transp=y minval= maxval= allpos=y barlabel= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''bool '' || '''allpos=y''' || [y/n] || contour positive values only
|-
| ''string '' || '''barlabel=''' || ||
|-
| ''floats '' || '''c=''' || || [nc]
|-
| ''float '' || '''c0=''' || || first contour
|-
| ''float '' || '''dc=''' || || contour increment
|-
| ''float '' || '''max1=o1+(n1-1)*d1''' || ||
|-
| ''float '' || '''max2=o2+(n2-1)*d2''' || || data window to plot
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''min1=o1''' || ||
|-
| ''float '' || '''min2=o2''' || ||
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''nc=50''' || || number of contours
|-
| ''bool '' || '''transp=y''' || [y/n] || if y, transpose the axes
|}
==sfdots==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot signal with lollipops.
|-
! colspan="4" | sfdots < in.rsf labels= dots=(n1 <= 130)? 1: 0 seemean=(bool) (n2 <= 30) strings=(bool) (n1 <= 400) connect=1 corners= silk=n gaineach=y labelsz=8 yreverse=n constsep=n seedead=n transp=n xxscale=1. yyscale=1. clip=-1. overlap=0.9 screenratio=VP_SCREEN_RATIO screenht=VP_STANDARD_HEIGHT screenwd=screenhigh / screenratio radius=dd1/3 label1= unit1= title= > plot.vpl
|-
| ''float '' || '''clip=-1.''' || || data clip
|-
| ''int '' || '''connect=1''' || || connection type: 1 - diagonal, 2 - bar, 4 - only for non-zero data
|-
| ''bool '' || '''constsep=n''' || [y/n] || if y, use constant trace separation
|-
| ''int '' || '''corners=''' || || number of polygon corners (default is 6)
|-
| ''int '' || '''dots=(n1 <= 130)? 1: 0''' || || type of dots: 1 - baloon, 0 - no dots, 2 - only for non-zero data
|-
| ''bool '' || '''gaineach=y''' || [y/n] || if y, gain each trace independently
|-
| ''string '' || '''label1=''' || ||
|-
| ''strings'' || '''labels=''' || || trace labels [n2]
|-
| ''int '' || '''labelsz=8''' || || label size
|-
| ''float '' || '''overlap=0.9''' || || trace overlap
|-
| ''float '' || '''radius=dd1/3''' || || dot radius
|-
| ''float '' || '''screenht=VP_STANDARD_HEIGHT''' || || screen height
|-
| ''float '' || '''screenratio=VP_SCREEN_RATIO''' || || screen aspect ratio
|-
| ''float '' || '''screenwd=screenhigh / screenratio''' || || screen width
|-
| ''bool '' || '''seedead=n''' || [y/n] || if y, show zero traces
|-
| ''bool '' || '''seemean=(bool) (n2 <= 30)''' || [y/n] || if y, draw axis lines
|-
| ''bool '' || '''silk=n''' || [y/n] || if y, silky plot
|-
| ''bool '' || '''strings=(bool) (n1 <= 400)''' || [y/n] || if y, draw strings
|-
| ''string '' || '''title=''' || ||
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axis
|-
| ''string '' || '''unit1=''' || ||
|-
| ''float '' || '''xxscale=1.''' || || x scaling
|-
| ''bool '' || '''yreverse=n''' || [y/n] || if y, reverse y axis
|-
| ''float '' || '''yyscale=1.''' || || y scaling
|}
==sfgraph3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate 3-D cube plot for surfaces.
|-
! colspan="4" | sfgraph3 < in.rsf orient=1 min= max= point1=0.5 point2=0.5 frame1=0.5*(min+max) frame2=n1-1 frame3=0 movie=0 dframe=1 n1pix=n1/point1+n3/(1.-point1) n2pix=n2/point2+n3/(1.-point2) flat=y > plot.vpl
|-
| ''float '' || '''dframe=1''' || || frame increment in a movie
|-
| ''bool '' || '''flat=y''' || [y/n] || if n, display perspective view
|-
| ''float '' || '''frame1=0.5*(min+max)''' || ||
|-
| ''int '' || '''frame2=n1-1''' || ||
|-
| ''int '' || '''frame3=0''' || || frame numbers for cube faces
|-
| ''float '' || '''max=''' || || maximum function value
|-
| ''float '' || '''min=''' || || minimum function value
|-
| ''int '' || '''movie=0''' || || 0: no movie, 1: movie over axis 1, 2: axis 2, 3: axis 3
|-
| ''int '' || '''n1pix=n1/point1+n3/(1.-point1)''' || || number of vertical pixels
|-
| ''int '' || '''n2pix=n2/point2+n3/(1.-point2)''' || || number of horizontal pixels
|-
| ''int '' || '''orient=1''' || || function orientation
|-
| ''float '' || '''point1=0.5''' || || fraction of the vertical axis for front face
|-
| ''float '' || '''point2=0.5''' || || fraction of the horizontal axis for front face
|}
==sfgraph==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Graph plot.
|-
! colspan="4" | sfgraph < in.rsf symbolsz= pclip=100. transp=n symbol= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''float '' || '''pclip=100.''' || || clip percentile
|-
| ''string '' || '''symbol=''' || || if set, plot with symbols instead of lines
|-
| ''floats '' || '''symbolsz=''' || || symbol size (default is 2) [n2]
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axes
|}
==sfgrey3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate 3-D cube plot.
|-
! colspan="4" | sfgrey3 < in.rsf point1=0.5 point2=0.5 frame1=0 frame2=n2-1 frame3=0 movie=0 dframe=1 n1pix=n1/point1+n3/(1.-point1) n2pix=n2/point2+n3/(1.-point2) flat=y scalebar=n minval= maxval= barreverse=n nreserve=8 bar= color= > plot.vpl
|-
| colspan="4" | Requires an "unsigned char" input (the output of sfbyte).
|-
| ''string '' || '''bar=''' || || file for scalebar data
|-
| ''bool '' || '''barreverse=n''' || [y/n] || if y, go from small to large on the bar scale
|-
| ''string '' || '''color=''' || || color scheme (default is i)
|-
| ''int '' || '''dframe=1''' || || frame increment in a movie
|-
| ''bool '' || '''flat=y''' || [y/n] || if n, display perspective view
|-
| ''int '' || '''frame1=0''' || ||
|-
| ''int '' || '''frame2=n2-1''' || ||
|-
| ''int '' || '''frame3=0''' || || frame numbers for cube faces
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''movie=0''' || || 0: no movie, 1: movie over axis 1, 2: axis 2, 3: axis 3
|-
| ''int '' || '''n1pix=n1/point1+n3/(1.-point1)''' || || number of vertical pixels
|-
| ''int '' || '''n2pix=n2/point2+n3/(1.-point2)''' || || number of horizontal pixels
|-
| ''int '' || '''nreserve=8''' || || reserved colors
|-
| ''float '' || '''point1=0.5''' || || fraction of the vertical axis for front face
|-
| ''float '' || '''point2=0.5''' || || fraction of the horizontal axis for front face
|-
| ''bool '' || '''scalebar=n''' || [y/n] || if y, draw scalebar
|}

Different [http://reproducibility.org/rsflog/index.php?/archives/14-Color-schemes.html color schemes] are available
for sfgrey and sfgrey3. Examples are in the book at [http://reproducibility.org/RSF/book/rsf/rsf/sfgrey.html rsf/rsf/sfgrey].

==sfgrey==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate raster plot.
|-
! colspan="4" | sfgrey < in.rsf > out.rsf bar=bar.rsf transp=y yreverse=y xreverse=n gpow= phalf= clip= pclip= gainstep=0.5+n1/256. allpos=n bias=0. polarity=n verb=n scalebar=n minval= maxval= barreverse=n wantframenum=(bool) (n3 > 1) nreserve=8 gainpanel= bar= color= > (plot.vpl | char.rsf)
|-
| colspan="4" | Can input char values. If called "byte", outputs char values. Run "sfdoc stdplot" for more parameters.
|-
| ''bool '' || '''allpos=n''' || [y/n] || if y, assume positive data
|-
| ''string '' || '''bar=''' || || file for scalebar data
|-
| ''bool '' || '''barreverse=n''' || [y/n] || if y, go from small to large on the bar scale
|-
| ''float '' || '''bias=0.''' || || subtract bias from data
|-
| ''float '' || '''clip=''' || ||
|-
| ''string '' || '''color=''' || || color scheme (default is i)
|-
| ''string '' || '''gainpanel=''' || || gain reference: 'a' for all, 'e' for each, or number
|-
| ''int '' || '''gainstep=0.5+n1/256.''' || || subsampling for gpow and clip estimation
|-
| ''float '' || '''gpow=''' || ||
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''nreserve=8''' || || reserved colors
|-
| ''float '' || '''pclip=''' || || data clip percentile (default is 99)
|-
| ''float '' || '''phalf=''' || || percentage for estimating gpow
|-
| ''bool '' || '''polarity=n''' || [y/n] || if y, reverse polarity (white is high by default)
|-
| ''bool '' || '''scalebar=n''' || [y/n] ||
|-
| ''bool '' || '''transp=y''' || [y/n] || if y, transpose the display axes
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''bool '' || '''wantframenum=(bool) (n3 > 1)''' || [y/n] || if y, display third axis position in the corner
|-
| ''bool '' || '''xreverse=n''' || [y/n] || if y, reverse the horizontal axis
|-
| ''bool '' || '''yreverse=y''' || [y/n] || if y, reverse the vertical axis
|}

Different [http://reproducibility.org/rsflog/index.php?/archives/14-Color-schemes.html color schemes] are available
and examples are in the book at [http://reproducibility.org/RSF/book/rsf/rsf/sfgrey.html rsf/rsf/sfgrey].

==sfplas==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot Assembler - convert ascii to vplot.
|-
! colspan="4" | sfplas
|}
==sfpldb==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot Debugger - convert vplot to ascii.
|-
! colspan="4" | sfpldb
|}
==sfplotrays==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot rays.
|-
! colspan="4" | sfplotrays frame=frame.rsf nt=n1*n2 jr=1 frame= < rays.rsf > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''string '' || '''frame=''' || ||
|-
| ''int '' || '''jr=1''' || || skip rays
|-
| ''int '' || '''nt=n1*n2''' || || maximum ray length
|}
==sfthplot==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Hidden-line surface plot.
|-
! colspan="4" | sfthplot < in.rsf uflag=y dflag=y alpha=45. titlsz=9 axissz=6 plotfat=0 titlefat=2 axisfat=2 plotcolup=VP_YELLOW plotcoldn=VP_RED axis=y axis1=y axis2=y axis3=y clip=0. pclip=100. gainstep=0.5+nx/256. bias=0. dclip=1. norm=y xc=1.5 zc=3 ratio=5. zmax= zmin= sz=6. label#= unit#= tpow=0 epow=0 gpow=1 title= > plot.vpl
|-
| ''float '' || '''alpha=45.''' || || apparent angle in degrees, |alpha| < 89
|-
| ''bool '' || '''axis=y''' || [y/n] ||
|-
| ''bool '' || '''axis1=y''' || [y/n] ||
|-
| ''bool '' || '''axis2=y''' || [y/n] ||
|-
| ''bool '' || '''axis3=y''' || [y/n] || plot axis
|-
| ''int '' || '''axisfat=2''' || || axes fatness
|-
| ''int '' || '''axissz=6''' || || axes size
|-
| ''float '' || '''bias=0.''' || || subtract bias from data
|-
| ''float '' || '''clip=0.''' || || data clip
|-
| ''float '' || '''dclip=1.''' || || change the clip: clip *= dclip
|-
| ''bool '' || '''dflag=y''' || [y/n] || if y, plot down side of the surface
|-
| ''float '' || '''epow=0''' || || exponential gain
|-
| ''int '' || '''gainstep=0.5+nx/256.''' || || subsampling for gpow and clip estimation
|-
| ''float '' || '''gpow=1''' || || power gain
|-
| ''string '' || '''label#=''' || || label on #-th axis
|-
| ''bool '' || '''norm=y''' || [y/n] || normalize by the clip
|-
| ''float '' || '''pclip=100.''' || || data clip percentile
|-
| ''int '' || '''plotcoldn=VP_RED''' || || color of the lower side
|-
| ''int '' || '''plotcolup=VP_YELLOW''' || || color of the upper side
|-
| ''int '' || '''plotfat=0''' || || line fatness
|-
| ''float '' || '''ratio=5.''' || || plot adjustment
|-
| ''float '' || '''sz=6.''' || || vertical scale
|-
| ''string '' || '''title=''' || ||
|-
| ''int '' || '''titlefat=2''' || || title fatness
|-
| ''int '' || '''titlsz=9''' || || title size
|-
| ''string '' || '''tpow=0''' || || time power gain
|-
| ''bool '' || '''uflag=y''' || [y/n] || if y, plot upper side of the surface
|-
| ''string '' || '''unit#=''' || || unit on #-th axis
|-
| ''float '' || '''xc=1.5''' || ||
|-
| ''float '' || '''zc=3''' || || lower left corner of the plot
|-
| ''float '' || '''zmax=''' || ||
|-
| ''float '' || '''zmin=''' || ||
|}
==sfwiggle==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot data with wiggly traces.
|-
! colspan="4" | sfwiggle < in.rsf xpos=xpos.rsf xmax= xmin= poly=n fatp=1 xmask=1 ymask=1 pclip=98. zplot=0.75 clip=0. seemean=n verb=n transp=n yreverse=n xreverse=n xpos= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''float '' || '''clip=0.''' || || data clip (estimated from pclip by default
|-
| ''int '' || '''fatp=1''' || ||
|-
| ''float '' || '''pclip=98.''' || || clip percentile
|-
| ''bool '' || '''poly=n''' || [y/n] ||
|-
| ''bool '' || '''seemean=n''' || [y/n] || if y, plot mean lines of traces
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axes
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''int '' || '''xmask=1''' || ||
|-
| ''float '' || '''xmax=''' || || maximum trace position (if using xpos)
|-
| ''float '' || '''xmin=''' || || minimum trace position (if using xpos)
|-
| ''string '' || '''xpos=''' || || optional header file with trace positions
|-
| ''bool '' || '''xreverse=n''' || [y/n] || if y, reverse the horizontal axis
|-
| ''int '' || '''ymask=1''' || ||
|-
| ''bool '' || '''yreverse=n''' || [y/n] || if y, reverse the vertical axis
|-
| ''float '' || '''zplot=0.75''' || ||
|}
=Plotting programs (development)=
==sfplsurf==
<tt>sfplsurf</tt> utilizes PLplot's surface rendering capabilities. Output is dumped to stdout in VPLOT format, so it can easily be used in the same way as <tt>sfgrey</tt> or other plotting programs. It also supports animation, if n3 > 1 in the input file. A SConstruct usage example can be found below. A [http://reproducibility.org/wikilocal/movies/sfplsurf_membrane.mpg movie of the output] is available as well.

<python>
from rsf.proj import *

# x & y dimensions
o1=-2
o2=-2
n1=41
n2=41
d1=0.1
d2=0.1
# z dimension
o3=-1
n3=21
d3=0.1

Flow('membrane',None,
'''
math o1=%g o2=%g n1=%d n2=%d d1=%g d2=%g
o3=%g n3=%d d3=%g
output="x3*cos(x1*x1+x2*x2)*exp(-0.1*(x1*x1+x2*x2))"
''' % (o1,o2,n1,n2,d1,d2,o3,n3,d3))

Result('membrane',
'''
plsurf title="Membrane" mesh=n color=j
minval=%g maxval=%g
''' % (o3,o3 + d3*(n3-1)))

End()
</python>

=system/generic programs=
==sfremap1==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | 1-D ENO interpolation.
|-
! colspan="4" | sfremap1 < in.rsf > out.rsf pattern=pattern.rsf n1=n1 d1=d1 o1=o1 order=3
|-
| ''float '' || '''d1=d1''' || || Output sampling
|-
| ''int '' || '''n1=n1''' || || Number of output samples
|-
| ''float '' || '''o1=o1''' || || Output origin
|-
| ''int '' || '''order=3''' || || Interpolation order
|-
| ''string '' || '''pattern=''' || || auxiliary input file name
|}
To give an example of usage, we will create an input for <tt>sfremap1</tt> with:
<pre>
sfmath n1=11 n2=11 d1=1 d2=1 o1=-5 o2=-5 output="x1*x1+x2*x2" > inp2remap1.rsf
</pre>
Let us interpolate the data across both dimensions, then display it:
<pre>
< inp2remap1.rsf sfremap1 n1=1001 d1=0.01 | sftransp | \
sfremap1 n1=1001 d1=0.01 | sftransp | sfgrey allpos=y | sfpen
</pre>
The comparison with the uninterpolated data ( <tt>< inp2remap1.rsf sfgrey allpos=y | sfpen</tt> ) is quite telling.

=system/seismic programs=
==sfstretch==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Stretch of the time axis.
|-
! colspan="4" | sfstretch < in.rsf > out.rsf datum=dat.rsf inv=n dens=1 v0= half=y delay= tdelay= hdelay= nout=dens*n1 extend=4 mute=0 maxstr=0 rule=
|-
| ''file '' || '''datum=''' || || auxiliary input file name
|-
| ''float '' || '''delay=''' || || time delay for rule=lmo
|-
| ''int '' || '''dens=1''' || || axis stretching factor
|-
| ''int '' || '''extend=4''' || || trace extension
|-
| ''bool '' || '''half=y''' || [y/n] || if y, the second axis is half-offset instead of full offset
|-
| ''float '' || '''hdelay=''' || || offset delay for rule=rad
|-
| ''bool '' || '''inv=n''' || [y/n] || if y, do inverse stretching
|-
| ''float '' || '''maxstr=0''' || || maximum stretch
|-
| ''int '' || '''mute=0''' || || tapering size
|-
| ''int '' || '''nout=dens*n1''' || || output axis length (if inv=n)
|-
| ''string '' || '''rule=''' || || Stretch rule:
:n - normal moveout (nmostretch), default
:l - linear moveout (lmostretch)
:L - logarithmic stretch (logstretch)
:2 - t^2 stretch (t2stretch)
:c - t^2 chebyshev stretch (t2chebstretch)
:r - radial moveout (radstretch)
:d - datuming (datstretch)
|-
| ''float '' || '''tdelay=''' || || time delay for rule=rad
|-
| ''float '' || '''v0=''' || || moveout velocity
|}

<tt>sfstretch rule=d</tt> (aka <tt>sfdatstretch</tt>) can be used to apply statics. Here is a synthetic example, courtesy of Alessandro Frigeri:
<pre>
# generate a dataset with 'flat' signals
sfmath n1=200 n2=100 output="sin(0.5*x1)" type=float > scan.rsf

# generate a sinusoidal elevation correction
sfmath n1=100 output="3*sin(x1)" type=float > statics.rsf

# apply statics, producing a 'wavy' output.
sfstretch < scan.rsf > out.rsf datum=statics.rsf rule=d
</pre>

=user/fomels programs=
==sfpick==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Automatic picking from semblance-like panels.
|-
! colspan="4" | sfpick < scn.rsf > pik.rsf vel0=o2 niter=100 an=1. gate=3 smooth=y rect#=(1,1,...) rect1=1 rect2=1 ...
|-
| colspan="4" | rectN defines the size of the smoothing stencil in N-th dimension. Theory in Appendix B of: S. Fomel, 2009, Velocity analysis using AB semblance: Geophysical Prospecting, v. 57, 311-321. Reproducible version in RSFSRC/book/jsg/avo
|-
| ''float '' || '''an=1.''' || || axes anisotropy
|-
| ''int '' || '''gate=3''' || || picking gate
|-
| ''int '' || '''niter=100''' || || number of iterations
|-
| ''int '' || '''rect#=(1,1,...)''' || || smoothing radius on #-th axis
|-
| ''bool '' || '''smooth=y''' || [y/n] || if apply smoothing
|-
| ''float '' || '''vel0=o2''' || || surface velocity
|}
Short description of the algorithm:
# Start from the top (first time slice), pick an initial (source) point, evaluate all other points with the direct traveltime.
# At each grid point at the next level, find the traveltime to points at the previous level, add the traveltimes from the previous level, and select minimum. The search radius is limited by the aperture (gate= parameter in sfpick).
# Repeat step 2 until reaching the bottom.
# Pick the minimum traveltime at the bottom and track the ray back to the source by following the traveltime gradient direction.
# Postprocessing (smooth= parameter in sfpick): smooth the picked ray path using shaping regularization.

The algorithm was discovered and rediscovered by many people. The best reference is probably ''V. Meshbey, E. Ragoza, D. Kosloff, U. Egozi, and D. Wexler, 2002, Three-dimensional Travel-time Calculation Based on Fermat's Principle: Pure and Applied Geophysics, v. 159, 1563-1582.''

=user/ivlad programs=
==sfprep4plot==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Resamples a 2-D dataset to the desired picture resolution, with antialias
|-
! colspan="4" | sfprep4plot inp= out= verb=n h=none w=none unit= ppi= prar=y
|-
| colspan="4" | Only one of the h and w parameters needs to be specified. If prar=n, no action will be taken on axis for which h/w was not specified If prar=y and only one par (h or w) is specified, the picture will scale along both axes until it is of the specified dimension.
|-
| ''int '' || '''h=none''' || || output height
|-
| ''string '' || '''inp=''' || || input file
|-
| ''string '' || '''out=''' || || output file
|-
| ''int '' || '''ppi=''' || || output resolution (px/in). Necessary when unit!=px
|-
| ''bool '' || '''prar=y''' || [y/n] || if y, PReserve Aspect Ratio of input
|-
| ''string '' || '''unit=''' || || unit of h and w. Can be: px(default), mm, cm, in
|-
| ''bool '' || '''verb=n''' || [y/n] || if y, print system commands, outputs
|-
| ''int '' || '''w=none''' || || output width
|}
For a figure that does not need the aspect ratio preserved,
and needs to fill a 1280x1024 projector display:
<pre>
sfprep4plot inp=file1.rsf out=file2.rsf w=1280 h=1024 prar=n
</pre>
For a print figure that has to fit in a 6x8in box
at a resolution of 250 dpi, preserving the aspect ratio:
<pre>
sfprep4plot inp=file1.rsf out=file2.rsf w=6 h=8 unit=in ppi=250
</pre>
A comparison of images before and after the application of <tt>sfprep4plot</tt>, courtesy of Joachim Mispel, is shown below:

[[Image:sf_prep4plot.jpg]]

==sfcsv2rsf==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a delimited-text ASCII file to RSF binary floating point or int.
|-
! colspan="4" | sfcsv2rsf help=n delimiter=, dtype=float verb=n debug=n trunc=n o1=0. o2=0. d1=1. d2=1. unit1=unknown unit2=unknown label1=unknown label2=unknown
|-
| colspan="4" | Zeros will be added if number of elements is not the same in each row. n1 and n2 are computed automatically. For consistency with sfdisfil and sfmatmult, output is C-style order (row-first), i.e. rows in input file become dimension-1 columns in output. Output encoding is native.
|-
| ''float '' || '''d1=1.''' || ||
|-
| ''float '' || '''d2=1.''' || ||
|-
| ''bool '' || '''debug=n''' || [y/n] || Extra verbosity for debugging
|-
| ''string '' || '''delimiter=,''' || || Separator between values in input file
|-
| ''string '' || '''dtype=float''' || || Input type
|-
| ''bool '' || '''help=n''' || [y/n] ||
|-
| ''string '' || '''label1=unknown''' || ||
|-
| ''string '' || '''label2=unknown''' || ||
|-
| ''float '' || '''o1=0.''' || ||
|-
| ''float '' || '''o2=0.''' || ||
|-
| ''bool '' || '''trunc=n''' || [y/n] || Truncate or add zeros if nr elems in rows differs
|-
| ''string '' || '''unit1=unknown''' || ||
|-
| ''string '' || '''unit2=unknown''' || ||
|-
| ''bool '' || '''verb=n''' || [y/n] || Whether to echo n1, n2, infill/truncation
|}

A small usage example follow below. First, create an input file:

<bash>
$ echo -e '5,6,8,9.2\n11,124,5,0,1' | tee file.csv
5,6,8,9.2
11,124,5,0,1
</bash>

You may notice that the number of values in each row is different.

Run <tt>sfcsv2rsf</tt>. Notice that no options are needed. By default, zeros will be appended to make the rows equal length:

<bash>
$ <file.csv sfcsv2rsf > junk.rsf ; sfdisfil < junk.rsf
0: 5 6 8 9.2 0
5: 11 124 5 0 1
</bash>

Notice that sfdisfil displays in column order (i.e. matrix is transposed if the number of rows is right). The dimensions of the file are actually transposed on disk:

$ sfin junk.rsf
junk.rsf:
in="/data/path/junk.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0 unit1="unknown"
n2=2 d2=1 o2=0 unit2="unknown"
10 elements 40 bytes
</bash>

You may want to run the output through <tt>sftransp</tt>, depending on your needs. However, if creating an input for <tt>sfmatmult</tt>, this will not be necessary, because <tt>sfmatmult</tt> is made to work with matrices that are displayed with <tt>sfdisfil</tt>, and takes as input a transpose matrix.

Pipes can be used, of course, to skip the creation of intermediary files:

<bash>
$ <file.csv sfcsv2rsf | sfdisfil
0: 5 6 8 9.2 0
5: 11 124 5 0 1
</bash>

Note that since this program does not need any arguments (just stdin and stdout), when called with no arguments it will not display the man page. In order to consult the automatically generated documentation, you need to pass the option <tt>help=y</tt> .

=user/jennings programs=
==sfsizes==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display the size of RSF files.
|-
! colspan="4" | sfsizes files=y human=n file1.rsf file2.rsf ...
|-
| colspan="4" | Prints the element size, number of elements, and number of bytes for a list of RSF files. Non-RSF files are ignored.
|-
| ''bool '' || '''files=y''' || [y/n] || If y, print size of each file. If n, print only total.
|-
| ''bool '' || '''human=n''' || [y/n] || If y, print human-readable file size. If n, print byte count.
|}

This program computes the "theoretical" size in bytes of the data fork of RSF files. The actual space occupied on disk may be different and machine dependent due to disk blocking factors, etc. This theoretical array size should be reproducible. It is also fast because the program only reads the RSF headers files, not the actual data.

For example, to get the total size of all RSF files in a directory, in human readable format, without listing each file:
<pre>
sfsizes files=n human=y *.rsf
</pre>
This will also work because sfsizes simply skips any non-RSF file:
<pre>
sfsizes files=n human=y *
</pre>
==sffiglist==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Compare Vplot files in Fig and Lock directories
|-
! colspan="4" | sffiglist figdir= lockdir= list= show=
|-
| colspan="4" |
Parameter '''figdir''' is path to Fig directory, default is ./Fig.

 Parameter '''lockdir''' is path to Lock directory:
 If '''figdir''' is in $RSFSRC/book/[book]/[chapter]/[section],
 then default '''lockdir''' is $RSFFIGS/[book]/[chapter]/[section].
 If '''figdir''' is not in $RSFSRC/book/[book]/[chapter]/[section],
 then default '''lockdir''' is $RSFALTFIGS/[book]/[chapter]/[section].

 Parameter '''list''' controls files to list, default is all.
 Parameter '''show''' controls files to flip with sfpen, default is none.

 '''list|show''' = none (No files, print only summary.)
 '''list|show''' = diff (Files that are different, determined by sfvplotdiff.)
 '''list|show''' = miss (Files missing from figdir or lockdir, and different files.)
 '''list|show''' = all (All files.)

 File list codes:
 space indicates files that are the same.
 - indicates file in lockdir that is missing from figdir.
 + indicates extra file in figdir that is missing from lockdir.
 number is return code from sfvplotdiff indicating different files.
|-
| ''string '' || '''figdir=''' || || fig directory, default = ./Fig
|-
| ''string '' || '''list=''' || || how much to list [none,diff,miss,all], default = all
|-
| ''string '' || '''lockdir=''' || || lock directory, default = lock counterpart of figdir
|-
| ''string '' || '''show=''' || || how much to show [none,diff,miss,all], default = none
|}

This tool lists Vplot files in "Fig" and "Lock" directories and compares them using sfvplotdiff.

The Fig directory defaults to ./Fig and the Lock directory defaults to the
corresponding directory where "scons lock" puts things, but either
default can be overridden with the user parameters '''figdir''' and '''lockdir''' so that, for example,
files in two different Fig directories can be compared.

The default for the Lock directory has some logic to look in $RSFFIGS
when Fig is in $RSFSRC/book, or to look in $RSFALTFIGS when Fig is not
in $RSFSRC/book because I like to keep two different Lock directories:
one for stuff in book and another for my own stuff that is not in
book. However, I tried to make the code default to reasonable things
if any of these environment variables are not defined.

The tool gives a summary count of files that are the same, files that
are different, files in Fig that are missing from Lock, and files in
Lock that are missing from Fig.

The parameters '''list''' (default=all) and '''show''' (default=none) control which files are listed or "flipped" with sfpen. The file listing indicates which files are the same, which are different, and which are missing from Fig or Lock.

For example, to list all the Vplot files in Fig and Lock:
<pre>
sffiglist list=all
</pre>
To list all Vplot files and flip only files that are different:
<pre>
sffiglist list=all show=diff
</pre>

=user/psava programs=

==sfawefd2d==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | acoustic time-domain FD modeling
|-
! colspan="4" | sfawefd < Fwav.rsf vel=Fvel.rsf sou=Fsou.rsf rec=Frec.rsf wfl=Fwfl.rsf > Fdat.rsf den=Fden.rsf ompchunk=1 ompnth=0 verb=n snap=n free=n expl=n jdata=1 jsnap=nt nq1=sf_n(a1) nq2=sf_n(a2) oq1=sf_o(a1) oq2=sf_o(a2)
|-
| ''file '' || '''den=''' || || auxiliary input file name
|-
| ''bool '' || '''expl=n''' || [y/n] || "exploding reflector"
|-
| ''bool '' || '''free=n''' || [y/n] || free surface flag
|-
| ''int '' || '''jdata=1''' || ||
|-
| ''int '' || '''jsnap=nt''' || || save wavefield every *jsnap* time steps
|-
| ''int '' || '''nq1=sf_n(a1)''' || ||
|-
| ''int '' || '''nq2=sf_n(a2)''' || ||
|-
| ''int '' || '''ompchunk=1''' || || OpenMP data chunk size
|-
| ''int '' || '''ompnth=0''' || || OpenMP available threads
|-
| ''float '' || '''oq1=sf_o(a1)''' || ||
|-
| ''float '' || '''oq2=sf_o(a2)''' || ||
|-
| ''file '' || '''rec=''' || || auxiliary input file name
|-
| ''bool '' || '''snap=n''' || [y/n] || wavefield snapshots flag
|-
| ''file '' || '''sou=''' || || auxiliary input file name
|-
| ''file '' || '''vel=''' || || auxiliary input file name
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''file '' || '''wfl=''' || || auxiliary output file name
|}

An example will be demonstrated below on a model with nx=nz=200, dx=dz=4m (size: 800x800m). There are two layers: the first one is 100x200 samples in (z,x) and the velocity is 1500m/s; the second layer has the same dimension and the velocity is 3000m/s. Density is set to 1 for the whole grid. A source and a receiver are co-located at x=400 and z=100. The full wavefield for the entire model aperture will be saved every 10th time step.

<bash>
# Velocity model:
sfspike >Fvel.rsf mag=1500,3000 nsp=2 k1=1,101 l1=100,200 d1=4 d2=4 \
label1=z label2=x n1=200 n2=200 o1=2 o2=2 unit1=m unit2=m

# Density model:
sfspike >Fden.rsf mag=1 nsp=1 k1=1 l1=200 d1=4 d2=4 label1=z \
label2=x n1=200 n2=200 o1=2 o2=2 unit1=m unit2=m

# Source position (x,z):
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 >Fsou.rsf

# Receiver position (x,z):
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 >Frec.rsf

# Source wavelet:
sfspike nsp=1 n1=2000 d1=0.0005 k1=200 | sfricker1 frequency=20 |\
sftransp >Fwav.rsf

# Creating data at specified receiver + saving full wavefield every 10th step:
sfawefd2d <Fwav.rsf vel=Fvel.rsf sou=Fsou.rsf rec=Frec.rsf wfl=Fwfl.rsf \
den=Fden.rsf >Fdat.rsf verb=y free=y expl=y snap=y dabc=y jdata=1 jsnap=10
echo 'label1=z unit1=m label2=x unit2=m' >> Fwfl.rsf

# View the wavefield movie:
< Fwfl.rsf sfgrey gainpanel=a pclip=99 color=j scalebar=y | sfpen

# View a wavefield snapshot:
< Fwfl.rsf sfwindow f3=80 n3=1 |\
sfgrey pclip=99 color=j title='snapshot at t=0.4s' |\
sfpen

# View the data recorded at receiver:
<Fdat.rsf sfwindow |\
sfgraph title='Data recorded at receiver' unit2='' label2=amplitude |\
sfpen
</bash>

[[Image:sfawefd_wfld.jpg|frame|center|sfawefd wavefield screenshot]]
[[Image:sfawefd_dat.png|frame|center|sfawefd data screenshot]]

Attention: time steps that are too large can result in numerical instability.

==sfsrmig3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | 3-D S/R migration with extended SSF
|-
! colspan="4" | sfsrmig3 slo=Fs_s.rsf sls=Fs_r.rsf < Fw_s.rsf rwf=Fw_r.rsf > Fi.rsf cig=Fc.rsf ompchunk=1 ompnth=0 verb=y eps=0.01 twoway=n nrmax=1 dtmax=0.004 pmx=0 pmy=0 tmx=0 tmy=0 vpvs=1. hsym=n nht=1 oht=0 dht=0.1 nht=1 oht=0 dht=0.1 hsym=n nhh=1 ohh=0 dhh=0.1 nha=180 oha=0 dha=2.0 nhb=180 ohb=0 dhb=2.0 itype=
|-
| ''file '' || '''cig=''' || || auxiliary output file name
|-
| ''float '' || '''dha=2.0''' || ||
|-
| ''float '' || '''dhb=2.0''' || ||
|-
| ''float '' || '''dhh=0.1''' || ||
|-
| ''float '' || '''dht=0.1''' || ||
|-
| ''float '' || '''dtmax=0.004''' || || max time error
|-
| ''float '' || '''eps=0.01''' || || stability parameter
|-
| ''bool '' || '''hsym=n''' || [y/n] ||
|-
| ''string '' || '''itype=''' || || imaging condition type
:o = zero lag (default)
:e = extended
:x = space-lags
:h = space-lags magnitude
:t = time-lag
|-
| ''int '' || '''nha=180''' || ||
|-
| ''int '' || '''nhb=180''' || ||
|-
| ''int '' || '''nhh=1''' || ||
|-
| ''int '' || '''nht=1''' || ||
|-
| ''int '' || '''nrmax=1''' || || max number of refs
|-
| ''float '' || '''oha=0''' || ||
|-
| ''float '' || '''ohb=0''' || ||
|-
| ''float '' || '''ohh=0''' || ||
|-
| ''float '' || '''oht=0''' || ||
|-
| ''int '' || '''ompchunk=1''' || || OpenMP data chunk size
|-
| ''int '' || '''ompnth=0''' || || OpenMP available threads
|-
| ''int '' || '''pmx=0''' || || padding on x
|-
| ''int '' || '''pmy=0''' || || padding on y
|-
| ''file '' || '''rwf=''' || || auxiliary input file name
|-
| ''file '' || '''slo=''' || || auxiliary input file name
|-
| ''string '' || '''sls=''' || || auxiliary input file name
|-
| ''int '' || '''tmx=0''' || || taper on x
|-
| ''int '' || '''tmy=0''' || || taper on y
|-
| ''bool '' || '''twoway=n''' || [y/n] || two-way traveltime
|-
| ''bool '' || '''verb=y''' || [y/n] || verbosity flag
|-
| ''float '' || '''vpvs=1.''' || || Vp/Vs ratio
|}

This program performs 3-D and 2-D shot-record (a.k.a. shot-profile) migration with an extended Split-Step Fourier (SSF) extrapolator with multiple reference velocities (hence "extended"). It takes as input a shot wavefield (<tt>stdin</tt>), receiver wavefield (<tt>rwf=</tt>) and slowness model (<tt>slo=</tt>). Outputs are an image (<tt>stdout</tt>) and a cube of Common Image Gathers (<tt>cig=</tt>). An important parameter is <tt>nrmax</tt>, the number of reference velocities. Its default value is 1, but for reasonable results it should be 5 or so. It is also good to specify nonzero taper values (<tt>tmx</tt> and, for 3-D, <tt>tmy</tt> as well). The values of padding parameters <tt>pmx</tt> and <tt>pmy</tt> are split in two by the program, i.e. if your data x axis is 501-points long, specify pmx=11 to get a value of 512 that will result in fast Fourier Transforms.

The program will also migrate converted-wave data if a file with the S-wave slowness model (<tt>sls=</tt>) is provided.

The <tt>vpvs</tt> parameter is only used when <tt>itype=h</tt>. Do not specify a <tt>vpvs</tt> value unless you know really well what you are doing.

===Usage example===
The commands below, slightly modified from [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/data/sigsbee/ptest/SConstruct?revision=3993&view=markup RSFSRC/book/data/sigsbee/ptest], show how to prepare the [http://www.reproducibility.org/RSF/book/data/sigsbee Sigsbee 2A] data and velocity for migration.

Convert input data (shots) from SEG-Y to RSF:
<bash>
sfsegyread tape=sigsbee2a_nfs.segy tfile=tdata.rsf hfile=/dev/null bfile=/dev/null > ddata.rsf
</bash>
Convert trace headers to float (required by <tt>sfheadermath</tt>):
<bash>
< tdata.rsf sfdd type=float > trchdr.rsf
</bash>
Shot positions:
<bash>
< trchdr.rsf sfheadermath output="fldr + 10925/150" | sfwindow squeeze=y > tsi.rsf
</bash>
Extract offset positions from the trace header files, eliminate length-1 axis, scale, create a header for binning (required by <tt>sfintbin</tt>):
<bash>
< trchdr.rsf sfheadermath output="offset" |\
sfwindow squeeze=y |\
sfmath output="input/75" |\
sfcat axis=2 space=n tsi.rsf |\
sftransp |\
sfdd type=int > tos.rsf
</bash>
Binning and muting:
<bash>
< ddata.rsf sfintbin head=tos.rsf xkey=0 ykey=1 |\
sfput label1=Time unit1=s d2=0.075 o2=0.0 label2=hx d3=0.150 o3=10.925 label3=sx |\
sfmutter half=false t0=1.0 v0=6.0 |\
sfput d2=0.02286 o2=0 unit2=km d3=0.04572 o3=3.32994 unit3=km > shots.rsf
</bash>
Keeping only 20 shots so that this 1-node job will not take forever, FFT-ing, decimating frequency slices (same as shortening the time axis), and creating y and hy axes of length 1:
<bash>
< shots.rsf sfwindow n3=20 f3=10 j3=20 |\
sffft1 |\
sfwindow n1=200 min1=1 j1=3 |\
sfspray axis=3 n=1 o=0 d=1 label=hy |\
sfspray axis=5 n=1 o=0 d=1 label=sy > rfft.rsf
</bash>
The dimensions of the cube thus created are:
<pre>
$ sfin rfft.rsf trail=n
rfft.rsf:
in="/var/tmp/rfft.rsf@"
esize=8 type=complex form=native
n1=200 d1=0.25 o1=1 label1="Frequency" unit1="Hz"
n2=348 d2=0.02286 o2=0 label2="hx" unit2="km"
n3=1 d3=1 o3=0 label3="hy" unit3="km"
n4=20 d4=0.9144 o4=3.78714 label4="sx" unit4="km"
1392000 elements 11136000 bytes
</pre>
Create the source wavelet (limited to the same frequency band as the data) and Fourier transform it:
<bash>
sfspike k1=1 n1=1500 d1=0.008 |\
sfbandpass flo=15 fhi=25 |\
sffft1 |\
sfwindow n1=200 min1=1 j1=3 |\
sfput label1=freq > sfft.rsf
</bash>
This creates a frequency-domain wavelet:
<pre>
$ sfin sfft.rsf
sfft.rsf:
in="/var/tmp/sfft.rsf@"
esize=8 type=complex form=native
n1=200 d1=0.25 o1=1 label1="freq" unit1="Hz"
200 elements 1600 bytes
</pre>
Create "synched" source and receiver wavefields with <tt>srsyn</tt> from wavelet and data frequency slices. Basically both the receiver and shot frequency slices are "placed" at the right location and padded with zeros up to the dimension of the x axis specified below.
<bash>
< rfft.rsf sfsrsyn nx=1067 dx=0.02286 ox=3.05562 wav=sfft.rsf swf=swav.rsf > rwav.rsf
</bash>
This creates frequency slices ready for migration for both source and receiver, only axis 1 (frequency) must become axis 3, for both datasets:
<bash>
< swav.rsf sftransp plane=12 | sftransp plane=23 > stra.rsf
</bash>
<bash>
< rwav.rsf sftransp plane=12 | sftransp plane=23 > rtra.rsf
</bash>
This creates a surface receiver wavefield ready for input to migration. Axis 4 is shot number. The values of axis 4 are arbitrary because each shot has been padded with zeros so that it covers the entire velocity model. Therefore the aperture of the downward continuation for each shot will be as large as the survey.
<pre>
sfin trail=n rtra.rsf
rtra.rsf:
in="/var/tmp/rtra.rsf@"
esize=8 type=complex form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=200 d3=0.25 o3=1 label3="w" unit3="Hz"
n4=20 d4=1 o4=0 label4="e" unit4="km"
4268000 elements 34144000 bytes
</pre>
Convert the velocity model from SEG-Y to RSF, decimate, convert from feet to km, transpose, convert to slowness and insert an additional axis:
<bash>
sfsegyread tape=sigsbee2a_migvel.sgy tfile=/dev/null hfile=/dev/null bfile=/dev/null |\
sfput o1=0 d1=0.00762 label1=z unit1=km o2=3.05562 d2=0.01143 label2=x unit2=km |\
sfwindow j1=4 j2=2 |\
sfscale rscale=0.0003048 |\
sftransp |\
sfmath output="1/input" |\
sfspray axis=2 n=1 d=1 o=0 |\
sfput label2=y > slow.rsf
</bash>
This creates a slowness file ready for input to migration, with an x axis identical to the x axis of the wavefield files:
<pre>
$ sfin slow.rsf
slow.rsf:
in="/var/tmp/slow.rsf@"
esize=4 type=float form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=301 d3=0.03048 o3=0 label3="z" unit3="km"
321167 elements 1284668 bytes
</pre>
Finally, the migration command (for a 4-processor machine, hence the <tt>ompnth</tt> value). We choose not to compute any image gathers (<tt>itype=o</tt>), but due to the construction of the program we still have to explicitly assign the <tt>cig</tt> tag, or else a RSF file with the name of the tag and no rsf extension will be created:
<bash>
< stra.rsf sfsrmig3 nrmax=20 dtmax=5e-05 eps=0.01 verb=y ompnth=4 \
tmx=16 rwf=rtra.rsf slo=slow.rsf itype=o cig=/dev/null > img.rsf
</bash>
The migration of 20 shots takes approximately 3 hours on a 4-processor machine (1 shot=9 minutes). Without the frequency slice decimation by a factor of 3 and the depth axis decimation by a factor of 4, it would have taken twelve times as much. The resulting image has a y axis of length 1:
<pre>
$ sfin img.rsf trail=n
img.rsf:
in="/var/tmp/img.rsf@"
esize=4 type=float form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=301 d3=0.03048 o3=0 label3="z" unit3="km"
321167 elements 1284668 bytes
</pre>
To properly visualize the image, we need to eliminate the axis of length 1, then transpose the x and z axes to their natural position:
<bash>
<img.rsf sfwindow squeeze=y | sftransp | sfgrey > img.vpl
</bash>

=References=
<references/>

Madagascar Code Patterns

2011-10-29T01:20:22Z

Nick: /* Loop over ensembles */

All patterns are in C, unless otherwise noted.

==Loop over ensembles==
This is a simple loop over reading 1-D arrays ("traces"), 2-D ("gathers"), etc.

It is necessary in the case of algorithms that act on one ensemble at a time. Parallelizable with OMP.

==I/O-optimized loop over samples==
===Description and usage===
It consists of looping over an entire dataset and applying a given procedure to every single sample in a dataset, regardless of what "trace"/"frame"/"volume" it belongs to. Example: computing the sum of all elements of a dataset; computing a histogram; performing a clip operation; etc. It uses the BUFSIZ macro defined in <tt>stdio.h</tt> to ensure efficient stream I/O. Its occurences can be easily found by grepping for BUFSIZ in the codebase.
===Example===
<c>
int n; /* Total number of elements in dataset */
int nbuf; /* Number of elements in I/O buffer */
float *fbuf; /* I/O array */
sf_file in=NULL; /* Input file. Here is stdin, but this is not compulsory */

in = sf_input("in");

n = sf_filesize(in);

/* This example uses float as data type.
Any other data type (int, sf_complex, etc) can be used, as appropriate */
nbuf = BUFSIZ/sizeof(float);

fbuf = sf_floatalloc(nbuf);

for (; n > 0; n -= nbuf) {

if (nbuf > n) nbuf = n;

sf_floatread(fbuf, nbuf, in);

for (i=0; i < nbuf; i++) {
/* Do computations here */
}
}
</c>

===Potential for improvement===
This pattern should be parallelized using OpenMP.

The [http://www.delorie.com/gnu/docs/glibc/libc_226.html GNU C Library documentation] states that when doing I/O on a file (as opposed to a stream), the <tt>st_blksize</tt> field of the file attributes is a better choice than <tt>BUFSIZ</tt>.

==OMP parallelized loop==
===Description and usage===
Shared-memory parallelization using the [https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] library.
===Example===
===Potential for improvement===

==Parallelized, I/O-optimized loop over samples==
===Description and usage===
===Example===
===Potential for improvement===

Madagascar Code Patterns

2011-10-29T01:16:15Z

Nick: /*Loop over ensembles */ vulnerability

All patterns are in C, unless otherwise noted.

==Loop over ensembles==
This is a simple loop over reading 1-D arrays ("traces"), 2-D ("gathers"), etc.

It is necessary in the case of algorithms that act on one ensemble at a time. Parallelizable with OMP.

It has the potential bug that the ensemble array is allocated using dimensions that are of type int (usually 4-byte). This will overflow on some rare occasions, and they should either be defined as 8-byte, or there should be a check function in which dimensions are read into a 8-byte int type and checked whether they will overflow the int. A different function than sf_histint needs to be created for this purpose, or the check to be implemented inside sf_histint.

==I/O-optimized loop over samples==
===Description and usage===
It consists of looping over an entire dataset and applying a given procedure to every single sample in a dataset, regardless of what "trace"/"frame"/"volume" it belongs to. Example: computing the sum of all elements of a dataset; computing a histogram; performing a clip operation; etc. It uses the BUFSIZ macro defined in <tt>stdio.h</tt> to ensure efficient stream I/O. Its occurences can be easily found by grepping for BUFSIZ in the codebase.
===Example===
<c>
int n; /* Total number of elements in dataset */
int nbuf; /* Number of elements in I/O buffer */
float *fbuf; /* I/O array */
sf_file in=NULL; /* Input file. Here is stdin, but this is not compulsory */

in = sf_input("in");

n = sf_filesize(in);

/* This example uses float as data type.
Any other data type (int, sf_complex, etc) can be used, as appropriate */
nbuf = BUFSIZ/sizeof(float);

fbuf = sf_floatalloc(nbuf);

for (; n > 0; n -= nbuf) {

if (nbuf > n) nbuf = n;

sf_floatread(fbuf, nbuf, in);

for (i=0; i < nbuf; i++) {
/* Do computations here */
}
}
</c>

===Potential for improvement===
This pattern should be parallelized using OpenMP.

The [http://www.delorie.com/gnu/docs/glibc/libc_226.html GNU C Library documentation] states that when doing I/O on a file (as opposed to a stream), the <tt>st_blksize</tt> field of the file attributes is a better choice than <tt>BUFSIZ</tt>.

==OMP parallelized loop==
===Description and usage===
Shared-memory parallelization using the [https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] library.
===Example===
===Potential for improvement===

==Parallelized, I/O-optimized loop over samples==
===Description and usage===
===Example===
===Potential for improvement===

Windows

2011-10-17T01:06:47Z

Nick: /* Screenshots */

<tt>Madagascar</tt> has been run on Microsoft Windows machines under various types of environments:

==Cygwin==

[[Image:cygwin-icon.gif|left|]] <tt>Madagascar</tt> can run under [http://cygwin.com Cygwin], which provides a Unix environment under Windows.

To obtain Cygwin, go to its web page, download and run the installer. This should create a Cygwin program, which when run, creates a POSIX shell window similar-looking to the Windows command window but which behaves in a more Unix-like way.

'''NOTE''': If you are unfamiliar with Unix-like systems, a good place to start is Greg Wilson's [http://www.osl.iu.edu/~lums/swc/www/shell.html Software Carpentry] course.

You will need to install several additional Cygwin components before Madagascar can run. To get these, rerun the installer program (called '''Setup''' and represented by an icon with a black "C" shape enclosing a green arrow).

# Start '''Setup''' program.
# Keep clicking (defaults should work, but you can choose a mirror on your own continent) until you see a collapsed list (boxed "+" signs) in a selection box.
# Choose the following before downloading.
## Open the '''Devel''' section and select
##* gcc
##* make
## If you want to use the development version of <tt>Madagascar</tt>, also choose
##* subversion
## If you have a favorite unix editor, choose it under '''Editors''' (novices may wish to work with Notepad for a while). Both <tt>vim</tt> and <tt>emacs</tt> are available.
## Open '''Interpreters''' and select
##* python
## Open '''Net''' and select
##* sunrpc
## Open '''Libs''' and select
##* opengl
## If you intend to use X-window, open '''X11''' and select
##* libX11-devel
##* libXaw-devel
## If you intend to use LaTeX, open '''Publishing''' and select
##* tetex
## If you intend to use <tt>ppmpen</tt>, open '''Graphics''' and select
##* libnetpbm-devel
## If you intend to use <tt>tiffpen</tt>, open '''Graphics''' and select
##* libtiff-devel
## If you intend to use <tt>gdpen</tt>, open '''Graphics''' and select
##* libgd-devel
# Next, click '''Next>'''
#: Your download will proceed.
# When done, click '''Finish'''.

After performing this steps, proceed to a normal Madagascar [[Installation]].

For running X applications such as '''xtpen''', make sure to run '''startx''' first to open an X terminal window.

===Troubleshooting===

If you get errors "unable to remap...", note the following:

A proper work of a Cygwin installation may require running '''rebaseall''', a program that fixes library dependencies. You only need to run it once.
# Quit all Cygwin processes
# Start '''ash''' (<tt><cygroot>\bin\ash.exe</tt>)
# Execute <tt>/usr/bin/rebaseall</tt>

===Screenshots===

* Running Cygwin's '''setup''' program

[[Image:setup.png|600px]]

* Selecting packages

[[Image:select.png|600px]]

* Running Cygwin's '''bash''' program

[[Image:bash.png|600px]]

* Testing <tt>Madagascar</tt> installation

[[Image:test.png|600px]]

[[Image:welcome.png|600px]]
===Matlab API===
To use the Matlab API with Madagascar under Cygwin, make sure you have Mex installed, and create a symbolic link, i.e.:
<bash>
ln -s /location/of/mex.bat /usr/bin/mex
</bash>

==Interix==
[http://en.wikipedia.org/wiki/Interix Interix] is the name of the Unix environment for Windows provided by Microsoft through the following software packages:
* [http://en.wikipedia.org/wiki/Microsoft_Windows_Services_for_UNIX Services For Unix] (SFU), available as a [http://www.microsoft.com/downloads/details.aspx?FamilyID=896c9688-601b-44f1-81a4-02878ff11778&DisplayLang=en free download] for the Windows NT family of operating systems up to and including Windows XP Professional ([http://www.reproducibility.org/rsflog/uploads/PS0001.jpg screenshot of m8r running on SFU] from an [http://www.reproducibility.org/rsflog/index.php?/archives/68-RSFMadagascar-on-Windows-using-SFU.html April 2006 entry on the m8r blog]). SFU availability was discontinued in 2009.
* [http://technet.microsoft.com/en-us/library/cc779522.aspx Subsystem for UNIX-based Applications] (SUA), included with Windows Server 2003 R2 and Windows Vista.

==SSH + X server==
If you can count on a network connection to a full UNIX machine while you run Madagascar, you actually need to install under MS Windows just a SSH client and a X server, and just run the Madagascar installed on the UNIX machine. Cygwin provides both, but it is big and slow. Faster and more lightweight alternatives are:
* [http://mobaxterm.mobatek.net/en/ MobaXterm], an enhanced terminal with an X server and a set of Unix commands (GNU/Cygwin) packaged in a single portable exe file;
* [http://sourceforge.net/projects/xming/ Xming] as X server and [http://en.wikipedia.org/wiki/PuTTY PuTTY] as SSH client (remember to check the "Tunnel X11 connections" box when saving the session configuration).

Windows

2011-10-17T01:04:55Z

Nick: /* Pictures */

<tt>Madagascar</tt> has been run on Microsoft Windows machines under various types of environments:

==Cygwin==

[[Image:cygwin-icon.gif|left|]] <tt>Madagascar</tt> can run under [http://cygwin.com Cygwin], which provides a Unix environment under Windows.

To obtain Cygwin, go to its web page, download and run the installer. This should create a Cygwin program, which when run, creates a POSIX shell window similar-looking to the Windows command window but which behaves in a more Unix-like way.

'''NOTE''': If you are unfamiliar with Unix-like systems, a good place to start is Greg Wilson's [http://www.osl.iu.edu/~lums/swc/www/shell.html Software Carpentry] course.

You will need to install several additional Cygwin components before Madagascar can run. To get these, rerun the installer program (called '''Setup''' and represented by an icon with a black "C" shape enclosing a green arrow).

# Start '''Setup''' program.
# Keep clicking (defaults should work, but you can choose a mirror on your own continent) until you see a collapsed list (boxed "+" signs) in a selection box.
# Choose the following before downloading.
## Open the '''Devel''' section and select
##* gcc
##* make
## If you want to use the development version of <tt>Madagascar</tt>, also choose
##* subversion
## If you have a favorite unix editor, choose it under '''Editors''' (novices may wish to work with Notepad for a while). Both <tt>vim</tt> and <tt>emacs</tt> are available.
## Open '''Interpreters''' and select
##* python
## Open '''Net''' and select
##* sunrpc
## Open '''Libs''' and select
##* opengl
## If you intend to use X-window, open '''X11''' and select
##* libX11-devel
##* libXaw-devel
## If you intend to use LaTeX, open '''Publishing''' and select
##* tetex
## If you intend to use <tt>ppmpen</tt>, open '''Graphics''' and select
##* libnetpbm-devel
## If you intend to use <tt>tiffpen</tt>, open '''Graphics''' and select
##* libtiff-devel
## If you intend to use <tt>gdpen</tt>, open '''Graphics''' and select
##* libgd-devel
# Next, click '''Next>'''
#: Your download will proceed.
# When done, click '''Finish'''.

After performing this steps, proceed to a normal Madagascar [[Installation]].

For running X applications such as '''xtpen''', make sure to run '''startx''' first to open an X terminal window.

===Troubleshooting===

If you get errors "unable to remap...", note the following:

A proper work of a Cygwin installation may require running '''rebaseall''', a program that fixes library dependencies. You only need to run it once.
# Quit all Cygwin processes
# Start '''ash''' (<tt><cygroot>\bin\ash.exe</tt>)
# Execute <tt>/usr/bin/rebaseall</tt>

===Screenshots===

* Running Cygwin's '''setup''' program

[[Image:setup.png|600px]]

* Selecting packages

[[Image:select.png|600px]]

* Running Cygwin's '''bash''' program

[[Image:bash.png|600px]]

* Testing <tt>Madagascar</tt> installation

[[Image:test.png|600px]]

[[Image:welcome.png|600px]]

==Interix==
[http://en.wikipedia.org/wiki/Interix Interix] is the name of the Unix environment for Windows provided by Microsoft through the following software packages:
* [http://en.wikipedia.org/wiki/Microsoft_Windows_Services_for_UNIX Services For Unix] (SFU), available as a [http://www.microsoft.com/downloads/details.aspx?FamilyID=896c9688-601b-44f1-81a4-02878ff11778&DisplayLang=en free download] for the Windows NT family of operating systems up to and including Windows XP Professional ([http://www.reproducibility.org/rsflog/uploads/PS0001.jpg screenshot of m8r running on SFU] from an [http://www.reproducibility.org/rsflog/index.php?/archives/68-RSFMadagascar-on-Windows-using-SFU.html April 2006 entry on the m8r blog]). SFU availability was discontinued in 2009.
* [http://technet.microsoft.com/en-us/library/cc779522.aspx Subsystem for UNIX-based Applications] (SUA), included with Windows Server 2003 R2 and Windows Vista.

==SSH + X server==
If you can count on a network connection to a full UNIX machine while you run Madagascar, you actually need to install under MS Windows just a SSH client and a X server, and just run the Madagascar installed on the UNIX machine. Cygwin provides both, but it is big and slow. Faster and more lightweight alternatives are:
* [http://mobaxterm.mobatek.net/en/ MobaXterm], an enhanced terminal with an X server and a set of Unix commands (GNU/Cygwin) packaged in a single portable exe file;
* [http://sourceforge.net/projects/xming/ Xming] as X server and [http://en.wikipedia.org/wiki/PuTTY PuTTY] as SSH client (remember to check the "Tunnel X11 connections" box when saving the session configuration).

Contributing new programs to Madagascar

2011-08-18T03:34:15Z

Nick: suggestion to add info to NEWS.txt

If you want to share your code with other Madagascar users:
# Follow the guide on [[Adding new programs to Madagascar]].
# If your employer holds the copyright for your software, obtain a permission to distribute under a [http://www.gnu.org/copyleft/gpl.html GPL license] and place a copyright and GPL license notice in each file with code.
# [http://sourceforge.net/account/registration/ Register at SourceForge].
# Find out who the project administrators are (Look for "Project Admins" on [http://sourceforge.net/projects/rsf/ this page]) and pass your SourceForge user name to one of them.
# Upload your directory to the repository using <tt>[http://svnbook.red-bean.com/en/1.0/re01.html svn add]</tt> and <tt>[http://svnbook.red-bean.com/en/1.1/re06.html svn commit]</tt>.
# Announce your changes in the release notes for the upcoming stable version ([http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/NEWS.txt?view=markup $RSFSRC/NEWS.txt])
# Make sure to add reproducible examples of using your program under the <tt>RSFSRC/book</tt> tree. Create new directories if necessary and commit them to the repository. As a rule, programs without examples are not included in the release version.

Some additional useful information is included below.

==Repository procedure suggestions==
Please try to:
* Do [http://en.wikipedia.org/wiki/Atomic_commit atomic commits].
* Use <tt>svn commit -m "your message here"</tt> to let others know what changed.
** Alternatively, set the <tt>EDITOR</tt> or <tt>SVN_EDITOR</tt> environmental variables to your favorite editor and edit your message there.
* If you plan to do large-scale substantive changes, create a Subversion [http://en.wikipedia.org/wiki/Branching_(software) branch] by running
<pre>
svn copy https://rsf.svn.sourceforge.net/svnroot/rsf/trunk https://rsf.svn.sourceforge.net/svnroot/rsf/yourbranchname
svn co https://rsf.svn.sourceforge.net/svnroot/rsf/yourbranchname
</pre>
For coding style suggestions, please see [[Adding_new_programs_to_Madagascar#Style_guide | the "Adding new programs" section]].

==Backward compatibility features==
If you introduce or notice a feature that is used solely for backwards compatibility with an old version of a dependency, please document it here, so that the feature can be eliminated when the Madagascar community stops supporting that version of that dependency<ref>This could be more elegantly done by using a special string to flag a backwards compatibility comment in the code, then have the documentation builder build this list automatically. This would make it more likely for this page to be kept in synch with the codebase.</ref>.

===Python 2.2 and older===
* In <tt>framework/rsfdoc.py</tt>: Everything in the <tt>have_datetime_module=False</tt> branches

===Python 2.3 and older===
* In <tt>configure.py</tt>: Everything in the <tt>have_subprocess=False</tt> branches
* In <tt>configure.py</tt>: See code after comment "For Py 2.4 and up this can be done more elegantly..."
* In <tt>user/ivlad/ivlad.py</tt>: Everything in the <tt>have_subprocess=False</tt> branches
* The entire <tt>api/python/rsfbak.py</tt> (also needed on systems which do not have recent versions of numpy ''and'' SWIG)
===Python 2.4 and older===
* try (try...except)... finally construct instead of try... except... finally in <tt>framework/rsfdoc.py</tt>

==Mitigating missing dependencies==
The main idea is to attempt to provide [http://en.wikipedia.org/wiki/Graceful_degradation graceful degradation] when facing a missing dependency. Quoting the Wikipedia page on fault-tolerant systems, this "enables a system to continue operating properly in the event of the failure of (or one or more faults within) some of its components. If its operating quality decreases at all, the decrease is proportional to the severity of the failure, as compared to a naively-designed system in which even a small failure can cause total breakdown."
===SWIG or numpy===
Graceful degradation is implemented. Please see the [[Advanced_Installation#Python API | Advanced Installation / Python API]] for an introduction to this issue. The module providing the limited functionality is <tt>api/python/rsfbak.py</tt>, which emulates header and command-line parameter reading functions from headers from the "official" development kit. When writing a Python program manipulating headers, it may be tempting to write <tt>import rsfbak</tt> because it is present anyway, but it is not a good idea. Use instead something like:
<python>
try:
import rsf
except: # Python devkit not installed
import rsfbak as rsf
</python>
The reason is that the <tt>rsf</tt> Python module is an interface to the homonymous C library, which ensures a unitary implementation of I/O throughout the package, and it should be used whenever possible. Having programs that do RSF I/O but never uses the official library practically forks the API, which is a Bad Thing. Using the pattern above ensures the alternate partial implementation is permanently synced with the principal implementation.

==Reasons for the existence of certain features==
===Why pyc files are generated during the install step===
Python bytecode files, with the pyc extensions, are created during the <tt>scons install</tt> in order to:
* Register them in SCons' dependency tree, so that they are removed by <tt>scons -c install</tt>
* Avoid a situation in which a user tries to execute a Madagascar Python program, but creating the pyc file during a module import fails because of lack of write access to <tt>$RSFROOT/lib</tt>.

==cfortran.h==
This source code file provides a machine-independent interface between C procedures, Fortran procedures and global data (more details [http://www-zeus.desy.de/~burow/cfortran/ on the website of its initial author]). It is a dependency of the F77 and F90 APIs, as well as of vplot. It is included in m8r in <tt>api/f90</tt> with a link in <tt>api/f77</tt>. Version 4.3 (2002) is still distributed through the website of the original author. Another version (fork?) is [http://root.cern.ch/viewvc/trunk/montecarlo/eg/inc/cfortran.h?view=log maintained at CERN] and distributed in the include directory of the interface to event generators in the Monte Carlo libraries in the [http://cernlib.web.cern.ch/cernlib/ CERN Program Library] (CERNlib). Debian distributes the Free Software part of this package as <tt>cernlib</tt>. Under Fedora, <tt>cfortran.h</tt> is included in <tt>cernlib-g77-devel</tt> and <tt>cernlib-devel</tt>, which happily overwrite each other's files and create copies of <tt>cfortran.h</tt> in two different locations deeply nested under <tt>/usr/include</tt>. CERNlib's Debian maintainer states that [http://people.debian.org/~kmccarty/cernlib/index.html "CERNlib is an ancient mass of mostly Fortran code"] and that [http://people.debian.org/~kmccarty/physics-software-rant.html "Most components of CERNLIB are completely broken on modern 64-bit architectures"], so m8r developers should be aware that CERNlib will probably be superseded at some point in the future by [http://en.wikipedia.org/wiki/ROOT ROOT], with upstream <tt>cfortran.h</tt> maintenance possibly continuing this way.

==Static code checks==
Madagascar contains the beginning of an implementation of static code checks for security vulnerabilities and coding mistakes with [http://www.splint.org/ Splint]. This is visible in the code through the presence of comments like <tt>/*@out@*/</tt> and <tt>/*@null@*/</tt>, which instruct Splint about the intent of different variables and function return values. Future plans include using also dynamic checking by [http://valgrind.org/ Valgrind] or IBM's [http://www-306.ibm.com/software/awdtools/purify/ Rational Purify]. Madagascar code metrics are [http://www.ohloh.net/p/m8r/analyses/latest assessed periodically by Ohloh].

==Maintaining the maintenance tools==
Please document scripts used to maintain the Madagascar codebase, and save them in <tt>RSFSRC/admin</tt>. Cleanup procedures may need to be repeated in the future, as authors are human and can make the same mistakes again.

==Information flow map==
The vector graphics original of this map in [http://en.wikipedia.org/wiki/Dia_(software) Dia] format is available upon request through the rsf-devel mailing list.
[[Image:M8rmap.png]]
<references/>
==Dual licensing Madagascar code==
When in a contractual work relationship, you may find it handy to reuse some of your own existing public code for which you own the copyright. This may also apply if you are doing contract work for a client on behalf of your employer, who owns the copyright.

If your code does not have any GPL-ed dependencies, and the copyright owner agrees to releasing the code under a different license than the GPL, then you are free to go ahead and do it. However, make sure that in every file you state:
* who is the copyright owner,
* what are the terms of the proprietary license that it is being released under,
* that the code has already been licensed to the public under the GNU GPL prior to this as part of the Madagascar package
It is important to specify all these items, lest years later, someone in your client's company finds the code, realizes that similar code is part of Madagascar, and wrongly believes that the copyright belonged to his company, and that you infringed it by releasing the code under the GPL.

Make sure that proper copyright and licensing statements are in place in case of dual licensing, even if you are on very good terms with your client, and are certain that they will not falsely accuse you of wrongdoing. Companies get acquired, employees and even owners leave companies, policies and business strategies change, and old contracts, licenses and legal documents get discarded or lost in a mass of old junk. Each source code file should contain all the relevant copyright and licensing information.

Manual

2011-08-13T01:30:01Z

Nick: /* Community */ New Google Groups

[[Image:Fotolia_8418493_XS.jpg|right|]]
As the number of pages on the Wiki grows, the navbar starts becoming insufficient for proper organization of all documentation. A top-down view of all materials about Madagascar is also useful for determining whether gaps in coverage exist. This page will stay in the Sandbox for a long while -- until all gaps have been filled.

Ideally the manual will only consist of either links to wiki pages, or own content. "Forking", i.e. creating a modified copy of a page especially for the manual, invariably ends up with one version getting out of synch.

=About Madagascar=
==Introduction==
[[Main Page]] of the wiki, and the [[Package overview]].

==For people who do not read manuals==
Point them to [[Download]], [[Installation|Short Install Guide]], and the [[Revisiting SEP tour with Madagascar and SCons|SEPlib Tour Revisited]].

==Why use Madagascar?==
An articulate description of the reasons on the [[Why Madagascar]] page. Have some spectacular pictures obtained with algorithms that are not present in other packages. Describe algorithms/tools unavailable in other open-source geophysical data analysis packages.

==Community==
A description of the current Madagascar community, with the map of downloads and an estimate of the number of installs, who are the biggest users, outstanding research results obtained with Madagascar, etc. Links to the [http://reproducibility.org/rsflog/ blog], [https://lists.sourceforge.net/lists/listinfo/rsf-user user mailing list], [https://lists.sourceforge.net/lists/listinfo/rsf-devel developer mailing list]. Mention of the Google Groups mirrors for [https://groups.google.com/forum/#!forum/osdeve_mirror_geophysics_rsf-user rsf-user] and [https://groups.google.com/forum/#!forum/osdeve_mirror_geophysics_rsf-devel rsf-devel] Also mention the [http://sourceforge.net/tracker/?group_id=162909&atid=825645 bug tracker] and [http://sourceforge.net/tracker/?group_id=162909&atid=825648 feature request tracker], encouraging the community to use them more. Mention [http://sourceforge.net/forum/?group_id=162909 forums] as an alternative for those who want to ask questions or conduct discussions without subscribing to a mailing list.

==History==
A history of Madagascar, with the SEPlib/SU part of the [[Introduction_to_madagascar#Alternatives|"Alternatives" section of the Introduction]], and mentions of landmark events (short descriptions where necessary):
* 2003: Work started by Sergey Fomel
* 2004-08 (?): made available to selected alpha users
* 2005-02-16: RSF Blog started
* 2006-03-17: Registered on Sourceforge
* 2006-04-19: [http://www.m8r.info/rsflog/index.php?/archives/67-Madagascar.html Name change from RSF to Madagascar]
* 2006-06-11: Public launch at the Open Source E&P Software EAGE Workshop (Vienna)
* 2006-06-18: [http://www.m8r.info/rsflog/index.php?/archives/74-Mailing-lists-and-madagascar-0.9.1.html First stable version (0.9.1). Mailing lists created]
* 2006-07-23: [http://www.m8r.info/rsflog/index.php?/archives/86-New-madagascar-logo.html Madagascar logo created by Scott Rodgers (BEG)]
* 2007-04-27: Release 0.9.4
* 2007-11-10: Release 0.9.5
* 2008-06-14: Release 0.9.6
* 2009-01-03: Release 0.9.7
* 2009-08-01: Release 0.9.8
* 2010-05-02: Release 0.9.9
* 2010-07-23: Release 1.0
* For details on releases after 1.0, see [[Release Notes]]

A link to the appendix containing the content of the [[Conferences]] and [[Publications]] pages.

=Downloading and installing Madagascar=
==Download==
[[Download]]
==Install==
# [[Installation|Short installation guide]]
# [[Advanced Installation|Advanced installation guide]]
==Licensing and export regulations==
* Explanation and text of the GPL 2+
* [[US export control]]

=Using Madagascar=
==The lightning-quick tour==
The [[Revisiting SEP tour with Madagascar and SCons|revisited SEP Tour]]

==The Madagascar file formats==
===The Regularly Sampled Format (RSF)===
The current [[Guide_to_RSF_file_format|Guide to RSF file format]]
===Handling irregularly sampled data===
Explain the principle of the current method (sfheadermath/sfheaderwindow used on the trace header block output by su/segyread)
===Importing and exporting data from and to SEG-Y and SU===
sfsegyread and sfsuread, with examples

===Importing and exporting data from and to raster images===
[[Raster image I/O]]
===Visualizing data and exporting figures with vplot===
* Explanation of vplot format
* Preempting display aliasing in raster plots with <tt>sfprep4plot</tt>
* How to create vplot images with sfgraph, sfgrey, sfdots, etc. [[Common pen parameters]]
* How to display vplot images with sfpen. How it defaults to <tt>oglpen</tt> on systems that support OpenGL, and <tt>xtpen</tt> on systems that do not support it, but have X Windows.
* How to convert vplot images to other formats with <tt>vpconvert</tt>. This tool can work on a single plot, i.e.:
<bash>
vpconvert file.vpl file.jpg
</bash>
or an entire collection of files:
<bash>
vpconvert format=tiff Fig/*.vpl
</bash>
The <tt>vpconvert</tt> program can export to and from a multitude of file formats: avi, eps, gif, jpg, mpeg, pdf, png, ppm, ps, svg, and tif, and is the recommended vpl import and export tool. Older single-purpose utilities (vplot2gif and vplot2avi) are still available.

===Visualizing data and exporting figures with GLE===
[[Graphics with GLE]]

===Visualizing data and exporting figures with gnuplot===
[[Graphics with gnuplot]]
===Visualizing data and exporting figures with PLplot===
[http://plplot.sourceforge.net/examples.php PLplot] is a device-independent vector-plotting library. Their concept is very similar to that of vplot, but instead
of separated device-dependent pens (like xtpen or pspen) they use loadable "drivers" (organized as shared objects and connected to a plotting programs in a plugin fashion). They have an extensive high-level interface for different types of plots.

A sample Madagascar program which utilizes PLplot's surface rendering capabilities is [[Guide_to_madagascar_programs#Plotting_programs_.28development.29 | sfplsurf]].

==Calling existing Madagascar programs==
===Finding out what program you need===
# [http://reproducibility.org/rsflog/index.php?/archives/128-How-do-I-find-programs-in-madagascar.html sfdoc -k]
# [[Task-centric program list]] and all its subordinate nodes
# Collection of 2-3 page reproducible papers -- "How to do raytracing in Madagascar"; "How to do modeling in Madagascar"; etc
# [[SU to m8r dictionary]]
# [[SEPlib to m8r dictionary]]
# Other such dictionaries, for free or proprietary seismic processing packages. Such dictionaries are also useful because they will highlight algorithms/utilities present in such packages but missing from m8r.

This chapter is now just a sketch, should get quite big. Users approach tools in a task-centric fashion, i.e. Q1:"how do I do X with Madagascar?", A1:"With feature Y"; Q2: "How do I use feature Y to this end?" M8r is very good at answering Q2, but people ask Q1 first. Many of the reproducible papers included so far contain cutting-edge research. Users learning how to use Madagascar need to start with something much more simple, where they do not have to focus on understanding research on top of understanding software.

===Learning how to use a given program===
# Command-line self-doc
# Local html self-doc (<tt>$RSFROOT/doc/index.html</tt>). Contains all programs installed on the user's machine and only those programs.
# [http://reproducibility.org/RSF/ Online self-doc]
# The wiki [[Guide_to_madagascar_programs|Guide to Programs]].
# Series of dedicated reproducible papers that present the theory behind specific geophysical programs and demonstrate it with various types of inputs and combination of parameters, like [http://www.reproducibility.org/RSF/book/sep/fkamo/paper_html/paper.html this paper] does for SEPlib's AMO program.
# Combining together multiple programs -- the reproducible papers; pointer to relevant section of the manual ("Exploring reproducible papers")

==What is reproducibility==
The whole [[Reproducibility]] page, combined with Section 1 from [[Reproducible computational experiments using SCons]]

==Exploring existing reproducible papers==
===Papers and books included in the Madagascar distribution===
[[Reproducible Documents]] and more.

===How to reproduce specific figures in existing papers===
A frequently encountered case is when a researcher wants to reproduce only one or several figures from an entire paper, but not the entire paper. This can happen because on that system LaTeX dependencies of Madagascar are missing or not working properly, or simply because the researcher is interested only in that result.
# '''Finding the paper directory:''' If the interesting article has been found by browsing/hyperlink to [[Reproducible Documents]], then the reproducibility package corresponding to <pre>http://www.reproducibility.org/RSF/book/<bookname>/<papername>/paper_html/</pre> can be found in <pre>RSFSRC/book/<bookname>/<papername>/</pre>
# '''Finding result names:''' Use the html version of the paper, or grep in all <tt>.tex</tt> files in the directory for a text string that occurs in the figure legend. Multiple-panel figures may have individual names for each panel. [Note: In pdf versions obtained with scons pdf in paper directory, neither the book name nor paper directory name nor figure names are given. LaTeX options to have figure names as well as a Geophysics-style header/footer with more details on the first page may be in order]
# '''Finding where to launch the re-build''': In some cases, rules for creating a result are specified in SConstruct files in subdirectories of the main paper directory. If step 4 fails in the main paper directory, then you will have to find where the figure is built. Because result names may be generated automatically, a simple grep may not be enough and you may need to read the SConstruct and python modules imported by it to figure out if the result is generated there.
# '''Re-build''' and display the figure by typing <tt>scons resultname.view</tt> in the appropriate directory.

SConstructs containing a <tt>Fetch</tt> instruction will attempt to download public-domain input data from a communal server when the "scons" command is run. A fast internet connection is necessary in this case.

===How to reproduce entire papers using stored figures===
# See the previous section for how to find the paper directory
# Pointer to how to download stored figures ([[Download#Reproducible figures]])
*<tt>scons pdf</tt>
*<tt>scons read</tt>

Troubleshooting:
* In case of failure with this kind of messages (details here), you miss TeX system dependencies. Install a TeX system. [http://www.tug.org/texlive/ Tex Live] should have it all. Note: It's a 1 Gb download. Too large for many individual users to bother with it and for most IT departments of companies to review for security. We should implement individual dependency checking, like we do in the installation.
* In case of failure with <tt>LaTeX Error: File `geophysics.cls' not found</tt> you have LaTeX, but you are missing [[SEGTeX]]
* If <tt>scons pdf</tt> in the paper directory requires pdf figures already in place in order to work, run <tt>sftour scons lock</tt> (?).

===How to reproduce entire papers and all their figures===
# See an earlier section for how to find the paper directory
# The relevant SCons command (<tt>scons lock</tt>, or <tt>sftour scons lock</tt>, as in [[Download#Reproducible figures]] to force reproducing the figures in the paper even when the reference figures repository is present

Tell the user to expect conditional reproducibility: If Matlab is not present, rsftex will not try to build the figures but will use the stored PDF files (same goes for Mathematica, xfig, etc.)

===How to reproduce whole books===
The [http://sourceforge.net/mailarchive/forum.php?thread_name=20061222142849.9688.qmail%40web34215.mail.mud.yahoo.com&forum_name=rsf-user 2006-12-22 rsf-user thread], [http://reproducibility.org/rsflog/index.php?/archives/142-Assembling-reports-from-papers.html the 2007-04-08 blog entry] and more.

From Jim's 2009-03-7 rsf-devel message:
Here is a way to generate all the targets in the subdirectories of $RSFSRC/book/geostats/spatial_stats:
<bash>
cd $RSFSRC/book/geostats/spatial_stats
sftour scons
</bash>
That works pretty nice. It generates all the targets in each of the 4 subdirectories of book/geostats/spatial_stats.

Now suppose I want to capture the output and errors in a log file (tcsh):
<bash>
sftour scons >& scons.log
</bash>
That's nice, except all the output goes into one log file in book/geostats/spatial_stats. Suppose I want 4 separate log files, one in each of the subdirectories. This will do the trick:
<bash>
sftour 'scons >& scons.log'
</bash>
The quotes make the entire string go to sftour as the command to run in each directory, instead of just 'scons'.

So far so good. Now suppose I want to go up one directory level and do the process recursively:
<bash>
cd $RSFSRC/book/geostats
sftour sftour 'scons >& scons.log'
</bash>
Well, that runs scons in each of the book/geostats/*/* directories, but it only makes 3 log files in the 3 subdirectories of book/geostats, not 14 log files in the 14 book/geostats/*/* directories. I can get 14 separate log files like this:
<bash>
sftour "sftour 'scons >& scons.log'"
</bash>
That does what I want. Now suppose I want to go up one more level to $RSFSRC/book and run the process recursively three levels deep:
<bash>
sftour sftour "sftour 'scons >& scons.log'"
</bash>
This works, but it doesn't put the log files in the bottom level, it puts them one level up. I can't fix it the same way I did before because I've run out of quotes :-) Here is one way to do it (tcsh):
<pre>
foreach i (*)
if ( -d $i) then
echo ++++++ $i
cd $i
sftour "sftour '/usr/bin/time -p scons >& scons.log'"
cd ..
endif
end
</pre>

From Sergey's 2009-03-10 rsf-devel message: A more elegant solution is
<bash>
sftour sftour scons >& ../../%/%/scons.log
</bash>

==Writing a LaTeX paper in the Madagascar framework==
Follows the natural progression of learning of somebody who may even not know LaTeX, let alone SCons.
# A paper with no figures.
# A paper with NR-only figures
==Creating a reproducible paper==
Sections 2 and 3 from [[Reproducible computational experiments using SCons]]. Also, mention the "SCons macros" in <tt>book/Recipes</tt>.

Publications included in Madagascar's book directories are tested periodically. Those publications that fail the tests and are not easily repaired are moved to <tt>book/Grave</tt>, with a note on how the tests failed and why the problems could not be fixed.
==Data-conditional reproducibility==
Due to seismic data licensing terms, an author may find it possible to make public everything that is needed to make a publication reproducible, except for the data. In such conditions, the paper is still acceptable for inclusion in the Madagascar collection. To indicate that certain datasets are private, the relevant <tt>SConstruct</tt> files should use <tt>Fetch(...,local=1)</tt> or tt>Fetch(...,server=private.server)</tt>, where <tt>private.server</tt> is a password-protected private server. Affected vplot figures should be uploaded to the [[Download#Reproducible figures | figure repository]]. Reproducibility testing will be skipped for the affected figures, but the html and pdf versions of the publications will still be created.

The usage of public seismic datasets, such as those at http://software.seg.org/, is strongly encouraged.

==Creating a reproducible book==

=Developing in Madagascar=
==Writing your own programs==
===Introduction to the Madagascar API===
# The existing [[Guide_to_madagascar_API|data clipping API demo]]
# A more complex [[Guide_to_programming_with_madagascar|finite differences API demo]] – add Python, F77 and Matlab APIs to it

===How to add your program===
[[Adding_new_programs_to_madagascar#How_to_add_your_program|The relevant section in "Adding programs"]]

===How to document your program===
[[Adding_new_programs_to_madagascar#How_to_document_your_program|The relevant section in "Adding programs"]]

===Style guide===
[[Adding_new_programs_to_madagascar#Style_guide|The relevant section in "Adding programs"]]

===How to test your program===
[[Adding_new_programs_to_madagascar#How_to_test_your_program|The relevant section in "Adding programs"]]

===How to parallelize your programs===
The [[Parallel Computing]] page.

===Tips and tricks===
[[Adding_new_programs_to_madagascar#Tips_and_tricks|The relevant section in "Adding programs"]]

===Madagascar library reference===
* [[Library Reference]]
* The [http://m8r.info/rsf_epydoc/ Python API documentation]
* The [http://m8r.info/RSF/book/rsf/manual/manual_html/ Programming Reference Manual]

==Adding programs to the central repository==
==Framework development and maintenance==
Description of m8r's inner works for those who want to help improve and maintain Madagascar. [[Maintenance guide]] and perhaps other stuff.
==Graphics development with vplot==
[[Graphics development with vplot]]
==Packaging madagascar==
[[Packaging madagascar]]

=Datasets distributed with Madagascar=
* Description of datasets – pictures of the velocity model, of sample gathers, zero-offset sections, migrated image.
* Comment on which are the main problems they illustrate (internal multiples? overturning waves? etc). Algorithm used for generating them, references to published literature describing the datasets
* Command line options for correctly reading them from the storage format (SEG-Y, most probably) into RSF
* In general, expand the [[Reproducible_Documents#Madagascar_Datasets | datasets section of Reproducible Documents page]] to include other datasets

=Other open-source data analysis packages=
==Geophysical software==
[[Other open-source geophysical packages]]. Briefly discuss each of them. Mention "dictionaries" from them to m8r where available (should attempt to have dictionaries for all of them)

==Other tools==
There are many other useful open-source or public domain software tools in the domain of applied mathematics, that can be used complementary to Madagascar. A few common examples, in alphabetical order, are:

* [http://www.alglib.net/ ALGLIB]: a highly portable numerical analysis and data processing library;
* [http://www.caam.rice.edu/software/ARPACK/ ARPACK] ("The ARnoldi PACKage"): a library written in FORTRAN 77 for solving large-scale eigenvalue problems;
* [http://math-atlas.sourceforge.net/ ATLAS] ("Automatically Tuned Linear Algebra Software"): a linear algebra library, implementing the [http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms BLAS] APIs for C and Fortran77;
* [http://www.oonumerics.org/blitz/ Blitz++]: a C++ class library for scientific computing which provides performance on par with Fortran 77/90;
* [http://www.dune-project.org/ DUNE] ("Distributed and Unified Numerics Environment"): a modular toolbox for solving partial differential equations with grid-based methods. It supports the easy implementation of methods like Finite Elements, Finite Volumes, and also Finite Differences.
* [http://fftw.org/ FFTW] ("The Fastest Fourier Transform in the West"): Hardware-adaptive FFT libraries;
* [http://www.gnu.org/software/gsl/ GNU Scientific Library]: a C library for numerical calculations in many branches of applied mathematics and science;
* [http://gts.sourceforge.net/index.html GNU Triangulated Surface Library]: a library providing a set of useful functions to deal with 3D surfaces meshed with interconnected triangles;
* [http://www.netlib.org/lapack/ LAPACK] ("The Linear Algebra PACKage"): a collection of routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems;
* [http://en.wikipedia.org/wiki/MINPACK MINPACK]: a library of FORTRAN subroutines for the solving of systems of nonlinear equations, or the least squares minimization of the residual of a set of linear or nonlinear equations;
* [http://www.mcs.anl.gov/petsc/petsc-2/ PETSc] ("the Portable, Extensible Toolkit for Scientific computation"): A set of serial and parallel, linear and nonlinear, solvers for large-scale, sparse linear and nonlinear systems of equations;
* [http://www.scipy.org/ SciPY] ("Scientific Python"): a toolbox for scientific computing in Python;
* [http://www.boost.org/doc/libs/1_39_0/libs/numeric/ublas/doc/index.htm uBLAS]: a C++ template class library that provides BLAS level 1, 2, 3 functionality for dense, packed and sparse matrices.

Most [http://en.wikipedia.org/ Wikipedia] pages of the above libraries are valuable resources, as is Wikipedia's [http://en.wikipedia.org/wiki/List_of_numerical_analysis_software list of numerical analysis software]. Other libraries and standalone programs are available through the [http://www.netlib.org/ Netlib repository] and indexed by the [http://gams.nist.gov/ Guide to Available Mathematical Software]. The U.S. DOE's [http://acts.nersc.gov/ ACTS Collection] is another valuable repository.

==Madagascar in conferences and publications==
The content of the [[Conferences]] and [[Publications]] pages. A mention about the reproducible documents that are listed in the "Papers and books included in the Madagascar distribution" sections.
==Madagascar project system administrator's guide==
[[Mediawiki installation, customization and operation]]

Raster image I/O

2011-08-13T01:16:34Z

Nick: /* Converting RSF 2-D data to raster images */

==Converting raster images to RSF files==
One option is <tt>sftif2byte</tt> or <tt>sfjpg2byte</tt>. It requires the TIFF or JPEG library, respectively, to be present at the compilation time.
<bash>
< lena.tif sftif2byte | sfdd type=float > lena.rsf
</bash>
<bash>
< lena.jpg sfjpg2byte | sfdd type=float > lena.rsf
</bash>
Another option is to use the <tt>convert</tt> utility from [http://www.imagemagick.org ImageMagick]. For a grayscale image:
<bash>
< lena.jpg convert - lena.gray
echo in=lena.gray data_format=native_uchar n1=512 n2=512 | sfdd type=float > lena.rsf
</bash>
or, for a color image:
<bash>
< lena.jpg convert - lena.rgb

echo in=lena.rgb data_format=native_uchar n1=3 n2=512 n3=512 | sfdd type=float > lena.rsf

# Red component:
< lena_rgb.rsf sfwindow n1=1 f1=0 > lena_red.rsf
# Green:
< lena_rgb.rsf sfwindow n1=1 f1=1 > lena_green.rsf
# Blue:
< lena_rgb.rsf sfwindow n1=1 f1=2 > lena_blue.rsf
</bash>

==Converting RSF 2-D data to raster images==
If Madagascar has been compiled with TIFF support, <tt>sfbyte2tif</tt> can be used:
<bash>
< model.rsf sfbyte | sfbyte2tif > model.tif
</bash>
If Madagascar has been compiled with JPEG support, <tt>sfbyte2jpg</tt> can be used:
<bash>
< model.rsf sfbyte | sfbyte2jpg > model.jpg
</bash>
Then, another program can be used to convert the JPEG file to another format.
If [http://www.imagemagick.org ImageMagick] is present, it can be used to convert a RSF binary to almost any image format. In a SConstruct, the workflow would look like:
<python>
Flow('data.gray','data',
'''
transp | # Make data in row-major order
byte gainpanell=all allpos=y | # Convert data to byte representation
disfil col=1 number=n format="%02X" | # Dump data in one column in ASCII-hex
xxd -r -p # Read ASCII output and convert it to binary form
''')

Flow('data.png','data.gray',
'''
convert -size %dx%d -depth 8 ${SOURCES[0]} ${TARGETS[0]} # Run ImageMagick
''' % (n2, n1), stdin=0, stdout=0)
</python>

To output to another format, just change the extension in the last <tt>Flow()</tt> from .png to .gif or .jpg, for example. Create the output simply by running: <tt>scons data.png</tt>

Contributing new programs to Madagascar

2011-08-13T01:14:43Z

Nick: Dual licensing

If you want to share your code with other Madagascar users:
# Follow the guide on [[Adding new programs to Madagascar]].
# If your employer holds the copyright for your software, obtain a permission to distribute under a [http://www.gnu.org/copyleft/gpl.html GPL license] and place a copyright and GPL license notice in each file with code.
# [http://sourceforge.net/account/registration/ Register at SourceForge].
# Find out who the project administrators are (Look for "Project Admins" on [http://sourceforge.net/projects/rsf/ this page]) and pass your SourceForge user name to one of them.
# Upload your directory to the repository using <tt>[http://svnbook.red-bean.com/en/1.0/re01.html svn add]</tt> and <tt>[http://svnbook.red-bean.com/en/1.1/re06.html svn commit]</tt>.
# Make sure to add reproducible examples of using your program under the <tt>RSFSRC/book</tt> tree. Create new directories if necessary and commit them to the repository. As a rule, programs without examples are not included in the release version.

Some additional useful information is included below.

==Repository procedure suggestions==
Please try to:
* Do [http://en.wikipedia.org/wiki/Atomic_commit atomic commits].
* Use <tt>svn commit -m "your message here"</tt> to let others know what changed.
** Alternatively, set the <tt>EDITOR</tt> or <tt>SVN_EDITOR</tt> environmental variables to your favorite editor and edit your message there.
* If you plan to do large-scale substantive changes, create a Subversion [http://en.wikipedia.org/wiki/Branching_(software) branch] by running
<pre>
svn copy https://rsf.svn.sourceforge.net/svnroot/rsf/trunk https://rsf.svn.sourceforge.net/svnroot/rsf/yourbranchname
svn co https://rsf.svn.sourceforge.net/svnroot/rsf/yourbranchname
</pre>
For coding style suggestions, please see [[Adding_new_programs_to_Madagascar#Style_guide | the "Adding new programs" section]].

==Backward compatibility features==
If you introduce or notice a feature that is used solely for backwards compatibility with an old version of a dependency, please document it here, so that the feature can be eliminated when the Madagascar community stops supporting that version of that dependency<ref>This could be more elegantly done by using a special string to flag a backwards compatibility comment in the code, then have the documentation builder build this list automatically. This would make it more likely for this page to be kept in synch with the codebase.</ref>.

===Python 2.2 and older===
* In <tt>framework/rsfdoc.py</tt>: Everything in the <tt>have_datetime_module=False</tt> branches

===Python 2.3 and older===
* In <tt>configure.py</tt>: Everything in the <tt>have_subprocess=False</tt> branches
* In <tt>configure.py</tt>: See code after comment "For Py 2.4 and up this can be done more elegantly..."
* In <tt>user/ivlad/ivlad.py</tt>: Everything in the <tt>have_subprocess=False</tt> branches
* The entire <tt>api/python/rsfbak.py</tt> (also needed on systems which do not have recent versions of numpy ''and'' SWIG)
===Python 2.4 and older===
* try (try...except)... finally construct instead of try... except... finally in <tt>framework/rsfdoc.py</tt>

==Mitigating missing dependencies==
The main idea is to attempt to provide [http://en.wikipedia.org/wiki/Graceful_degradation graceful degradation] when facing a missing dependency. Quoting the Wikipedia page on fault-tolerant systems, this "enables a system to continue operating properly in the event of the failure of (or one or more faults within) some of its components. If its operating quality decreases at all, the decrease is proportional to the severity of the failure, as compared to a naively-designed system in which even a small failure can cause total breakdown."
===SWIG or numpy===
Graceful degradation is implemented. Please see the [[Advanced_Installation#Python API | Advanced Installation / Python API]] for an introduction to this issue. The module providing the limited functionality is <tt>api/python/rsfbak.py</tt>, which emulates header and command-line parameter reading functions from headers from the "official" development kit. When writing a Python program manipulating headers, it may be tempting to write <tt>import rsfbak</tt> because it is present anyway, but it is not a good idea. Use instead something like:
<python>
try:
import rsf
except: # Python devkit not installed
import rsfbak as rsf
</python>
The reason is that the <tt>rsf</tt> Python module is an interface to the homonymous C library, which ensures a unitary implementation of I/O throughout the package, and it should be used whenever possible. Having programs that do RSF I/O but never uses the official library practically forks the API, which is a Bad Thing. Using the pattern above ensures the alternate partial implementation is permanently synced with the principal implementation.

==Reasons for the existence of certain features==
===Why pyc files are generated during the install step===
Python bytecode files, with the pyc extensions, are created during the <tt>scons install</tt> in order to:
* Register them in SCons' dependency tree, so that they are removed by <tt>scons -c install</tt>
* Avoid a situation in which a user tries to execute a Madagascar Python program, but creating the pyc file during a module import fails because of lack of write access to <tt>$RSFROOT/lib</tt>.

==cfortran.h==
This source code file provides a machine-independent interface between C procedures, Fortran procedures and global data (more details [http://www-zeus.desy.de/~burow/cfortran/ on the website of its initial author]). It is a dependency of the F77 and F90 APIs, as well as of vplot. It is included in m8r in <tt>api/f90</tt> with a link in <tt>api/f77</tt>. Version 4.3 (2002) is still distributed through the website of the original author. Another version (fork?) is [http://root.cern.ch/viewvc/trunk/montecarlo/eg/inc/cfortran.h?view=log maintained at CERN] and distributed in the include directory of the interface to event generators in the Monte Carlo libraries in the [http://cernlib.web.cern.ch/cernlib/ CERN Program Library] (CERNlib). Debian distributes the Free Software part of this package as <tt>cernlib</tt>. Under Fedora, <tt>cfortran.h</tt> is included in <tt>cernlib-g77-devel</tt> and <tt>cernlib-devel</tt>, which happily overwrite each other's files and create copies of <tt>cfortran.h</tt> in two different locations deeply nested under <tt>/usr/include</tt>. CERNlib's Debian maintainer states that [http://people.debian.org/~kmccarty/cernlib/index.html "CERNlib is an ancient mass of mostly Fortran code"] and that [http://people.debian.org/~kmccarty/physics-software-rant.html "Most components of CERNLIB are completely broken on modern 64-bit architectures"], so m8r developers should be aware that CERNlib will probably be superseded at some point in the future by [http://en.wikipedia.org/wiki/ROOT ROOT], with upstream <tt>cfortran.h</tt> maintenance possibly continuing this way.

==Static code checks==
Madagascar contains the beginning of an implementation of static code checks for security vulnerabilities and coding mistakes with [http://www.splint.org/ Splint]. This is visible in the code through the presence of comments like <tt>/*@out@*/</tt> and <tt>/*@null@*/</tt>, which instruct Splint about the intent of different variables and function return values. Future plans include using also dynamic checking by [http://valgrind.org/ Valgrind] or IBM's [http://www-306.ibm.com/software/awdtools/purify/ Rational Purify]. Madagascar code metrics are [http://www.ohloh.net/p/m8r/analyses/latest assessed periodically by Ohloh].

==Maintaining the maintenance tools==
Please document scripts used to maintain the Madagascar codebase, and save them in <tt>RSFSRC/admin</tt>. Cleanup procedures may need to be repeated in the future, as authors are human and can make the same mistakes again.

==Information flow map==
The vector graphics original of this map in [http://en.wikipedia.org/wiki/Dia_(software) Dia] format is available upon request through the rsf-devel mailing list.
[[Image:M8rmap.png]]
<references/>
==Dual licensing Madagascar code==
When in a contractual work relationship, you may find it handy to reuse some of your own existing public code for which you own the copyright. This may also apply if you are doing contract work for a client on behalf of your employer, who owns the copyright.

If your code does not have any GPL-ed dependencies, and the copyright owner agrees to releasing the code under a different license than the GPL, then you are free to go ahead and do it. However, make sure that in every file you state:
* who is the copyright owner,
* what are the terms of the proprietary license that it is being released under,
* that the code has already been licensed to the public under the GNU GPL prior to this as part of the Madagascar package
It is important to specify all these items, lest years later, someone in your client's company finds the code, realizes that similar code is part of Madagascar, and wrongly believes that the copyright belonged to his company, and that you infringed it by releasing the code under the GPL.

Make sure that proper copyright and licensing statements are in place in case of dual licensing, even if you are on very good terms with your client, and are certain that they will not falsely accuse you of wrongdoing. Companies get acquired, employees and even owners leave companies, policies and business strategies change, and old contracts, licenses and legal documents get discarded or lost in a mass of old junk. Each source code file should contain all the relevant copyright and licensing information.

Mediawiki installation, customization and operation

2011-08-12T02:59:11Z

Nick: /* Disabling media uploads */

==Installation==
The Madagascar Mediawiki installation consists of:
* A SQL database back-end, that holds text, images, history and user data
* A set of PHP scripts, that dynamically generate the HTML pages
* Auxiliary files uploaded directly to the server

Advanced web hosting providers offer "one-click" installs of Mediawiki, but database migration and PHP customization must still be performed.

==Customization==

===Favicon and logo===
In <tt>LocalSettings.php</tt>, set
<php>
$wgFavicon = '/wikilocal/style/favicon.png';
$wgLogo = '/wikilocal/style/Madagascar2.png';
</php>

===Footer===
To insert the images/links to the Ohloh, Sourceforge and Cafepress, edit <tt>includes/Skin.php</tt> to replace the default function <tt>getPoweredBy()</tt> with:

<php>
function getPoweredBy() {
global $wgStylePath;
$ohloh = '<script type="text/javascript" src="http://www.ohloh.net/p/348236/widgets/project_thin_badge.js"></script>';
$sf1='<a href="http://sourceforge.net/projects/rsf">';
$sf2='<img src="http://sflogo.sourceforge.net/sflogo.php?group_id=162909&type=13" width="120" height="30" border="0" ';
$sf3='alt="Get Madagascar at SourceForge.net. Fast, secure and Free Open Source software downloads"/></a> ';
$sourceforge = $sf1.$sf2.$sf3;
$url = htmlspecialchars( "$wgStylePath/common/images/poweredby_mediawiki_88x31.png" );
$banner = htmlspecialchars( "/wikilocal/style/store.png" );
$store = '<a href="http://www.cafepress.com/m8r">
<img src="'.$banner.'" width="88" height="31" border="0" alt="Madagascar Store" /></a> ';
$img = $ohloh.$sourceforge.$store.'<a href="http://www.mediawiki.org/"><img src="'.$url.'" alt="MediaWiki" /></a>';
return $img;
}
</php>
===Extensions===
These are installed in the <tt>extensions</tt> directory. Currently installed extensions are:
* googleAnalytics
* Cite
* [http://www.mediawiki.org/wiki/Extension:ConfirmEdit ConfirmEdit]
* GeSHi (syntax highlighting)
* SpamBlacklist
* [http://www.mediawiki.org/wiki/Extension:VisualMathCaptcha VisualMathCaptcha], installed in conjunction with ConfirmEdit
* Widgets:
** Feed (for the RSFlog RSS feed)
** YouTube (for some on-screen demos and lectures)

==Operation==
===Backups===
Backups should cover the wiki installation (SQL backups must be made by proper script, not by simply copying a file!), as well as a static copy of a wiki to be used in case the database is corrupted during file transfer.
===Defending against spammers and vandals===
====Allowing only registered users to edit the wiki====
This is a measure that was deemed necessary after two years of daily undo-and-block warfare against spammers.
To set it, use in <tt>LocalSettings.php</tt>:
<php>
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createpage'] = false;
$wgGroupPermissions['*']['createtalk'] = false;
</php>

====Disabling registration of new users====
This is a temporary measure, to be used as a stopgap against large attacks, until a permanent effective measure has been found.
====Disallowing users to create new pages====
Again, a temporary measure. For attacks which are not so heavy as to warrant disabling registration of new users, and in which spammers are weeded out manually. Several hours may pass between verifications of edits, in which a spammer can create many new pages. Works for attacks centered on new page creation. To set this, use
<php>
$wgGroupPermissions['user']['createpage'] = false;
</php>
in <tt>LocalSettings.php</tt> .

====Disabling media uploads====
To disable uploads via the web interface, set
<php>
$wgEnableUploads = false;
</php>
in <tt>LocalSettings.php</tt> .
To upload images from the command line, without using the web interface, use
<bash>
php wiki/maintenance/importImages.php /path/to/dir/with/images extensions
</bash>
If file permission problems are encountered, then
<bash>
chmod -R g+w wiki/images
</bash>

Parallel Computing

2011-08-12T00:48:52Z

Nick:

[[Image:Cluster.jpg|right|frame|[http://www.freedigitalphotos.net/images/view_photog.php?photogid=1152 Image: jscreationzs / FreeDigitalPhotos.net]]]
Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Unlike the OpenMP or MPI utilities, this has fault tolerance -- in case of a node failing, restarting the job will allow it to complete.

Simply running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. To fully use the potential of <tt>pscons</tt> for running on a distributed-memory computer, you need to set the environment variables <tt>RSF_CLUSTER</tt> and <tt>RSF_THREADS</tt>, and to use <tt>split</tt> and <tt>reduce</tt> arguments in your SConstruct Flow statements where appropriate.

===Setting the environment variables===

The <tt>RSF_CLUSTER</tt> variable holds, for each node, the name or IP address of that node (in a format that can be used by ssh), followed by the number of threads on the node. For example, creating 26 threads and sending them on 4 nodes, using respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs on each of the last two nodes:
<bash>
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

The <tt>RSF_THREADS</tt> variable holds the sum of the numbers of threads on all nodes, i.e.:
<bash>
export RSF_THREADS=26
</bash>
If <tt>RSF_CLUSTER</tt> is not defined, <tt>RSF_THREADS</tt> can be used to override the auto-detected number of threads used on the local host. This can be useful in the case of processes using a large amount of memory.

In Beowulf-type clusters in which communication of the processor with the local disk is much faster than with the shared network storage, it is important to set in the shell resource file the temporary file location to a local disk, and the <tt>DATAPATH</tt> variable to a network-visible location for global collection of results, i.e.:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

===The split and reduce options in Flow()===
The split option specifies the number of the axis to be split and the size of that axis. For an axis 3 of length 1000 on the standard in file, and collection by concatenation:
<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>
Concatenation is the default reduction method. The other valid option is <tt>reduce='add'</tt> .

In flows that are run by <tt>pscons</tt>, but contain both serial and parallel targets, care must be exercised in order to not create bottlenecks, in which tasks are distributed to multiple nodes, but the nodes sit idle while waiting other nodes to finish computing dependencies. Tasks that are not explicitly parallelized will be sped up by <tt>pscons</tt> if they are independent from each other. For example, building Madagascar with <tt>pscons</tt> instead of scons results in a visible speedup on a multithreaded machine.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons attempts to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel, especially by overloading the I/O system with identical operations.
<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

===What to expect at runtime===
SCons will create intermediate input and output slices in the current directory. For example, for
<bash>
Flow('out','inp','radon np=100 p0=0 dp=0.01',split=[3,256])
</bash>
and
<bash>
RSF_THREADS=8
RSF_CLUSTER='localhost 4 node1.utexas.edu 4'
</bash>
the SCons output will look like:
<bash>
< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=0 squeeze=n > inp__0.rsf

< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=42 squeeze=n > inp__1.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; /bin/env < inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=84 squeeze=n > inp__2.rsf "

< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=126 squeeze=n > inp__3.rsf

< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=168 squeeze=n > inp__4.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; /bin/env < inp.rsf /RSFROOT/bin/sfwindow f3=210 squeeze=n > inp__5.rsf "

< inp__0.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__0.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; /bin/env < inp__1.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__1.rsf "

< inp__3.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__3.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; < spike__4.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__4.rsf "

< inp__2.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__2.rsf

< inp__5.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__5.rsf

< out__0.rsf /RSFROOT/bin/sfcat axis=3 out__1.rsf out__2.rsf out__3.rsf out__4.rsf out__5.rsf > out.rsf
</bash>

Note that operations were sent for execution in parallel, but the display is necessarily serial.

Runtime job monitoring can be achieved with '''sftop'''. To kill a distributed job, use '''sfkill'''.

Parallel Computing

2011-08-11T03:20:58Z

Nick: /* What to expect at runtime */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Unlike the OpenMP or MPI utilities, this has fault tolerance -- in case of a node failing, restarting the job will allow it to complete.

Simply running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. To fully use the potential of <tt>pscons</tt> for running on a distributed-memory computer, you need to set the environment variables <tt>RSF_CLUSTER</tt> and <tt>RSF_THREADS</tt>, and to use <tt>split</tt> and <tt>reduce</tt> arguments in your SConstruct Flow statements where appropriate.

===Setting the environment variables===

The <tt>RSF_CLUSTER</tt> variable holds, for each node, the name or IP address of that node (in a format that can be used by ssh), followed by the number of threads on the node. For example, creating 26 threads and sending them on 4 nodes, using respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs on each of the last two nodes:
<bash>
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

The <tt>RSF_THREADS</tt> variable holds the sum of the numbers of threads on all nodes, i.e.:
<bash>
export RSF_THREADS=26
</bash>
If <tt>RSF_CLUSTER</tt> is not defined, <tt>RSF_THREADS</tt> can be used to override the auto-detected number of threads used on the local host. This can be useful in the case of processes using a large amount of memory.

In Beowulf-type clusters in which communication of the processor with the local disk is much faster than with the shared network storage, it is important to set in the shell resource file the temporary file location to a local disk, and the <tt>DATAPATH</tt> variable to a network-visible location for global collection of results, i.e.:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

===The split and reduce options in Flow()===
The split option specifies the number of the axis to be split and the size of that axis. For an axis 3 of length 1000 on the standard in file, and collection by concatenation:
<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>
Concatenation is the default reduction method. The other valid option is <tt>reduce='add'</tt> .

In flows that are run by <tt>pscons</tt>, but contain both serial and parallel targets, care must be exercised in order to not create bottlenecks, in which tasks are distributed to multiple nodes, but the nodes sit idle while waiting other nodes to finish computing dependencies. Tasks that are not explicitly parallelized will be sped up by <tt>pscons</tt> if they are independent from each other. For example, building Madagascar with <tt>pscons</tt> instead of scons results in a visible speedup on a multithreaded machine.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons attempts to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel, especially by overloading the I/O system with identical operations.
<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

===What to expect at runtime===
SCons will create intermediate input and output slices in the current directory. For example, for
<bash>
Flow('out','inp','radon np=100 p0=0 dp=0.01',split=[3,256])
</bash>
and
<bash>
RSF_THREADS=8
RSF_CLUSTER='localhost 4 node1.utexas.edu 4'
</bash>
the SCons output will look like:
<bash>
< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=0 squeeze=n > inp__0.rsf

< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=42 squeeze=n > inp__1.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; /bin/env < inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=84 squeeze=n > inp__2.rsf "

< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=126 squeeze=n > inp__3.rsf

< inp.rsf /RSFROOT/bin/sfwindow n3=42 f3=168 squeeze=n > inp__4.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; /bin/env < inp.rsf /RSFROOT/bin/sfwindow f3=210 squeeze=n > inp__5.rsf "

< inp__0.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__0.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; /bin/env < inp__1.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__1.rsf "

< inp__3.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__3.rsf

/usr/bin/ssh node1.utexas.edu "cd /home/test ; < spike__4.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__4.rsf "

< inp__2.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__2.rsf

< inp__5.rsf /RSFROOT/bin/sfradon p0=0 np=100 dp=0.01 > out__5.rsf

< out__0.rsf /RSFROOT/bin/sfcat axis=3 out__1.rsf out__2.rsf out__3.rsf out__4.rsf out__5.rsf > out.rsf
</bash>

Note that operations were sent for execution in parallel, but the display is necessarily serial.

Runtime job monitoring can be achieved with '''sftop'''. To kill a distributed job, use '''sfkill'''.

Parallel Computing

2011-08-11T03:13:15Z

Nick: /* Run */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Unlike the OpenMP or MPI utilities, this has fault tolerance -- in case of a node failing, restarting the job will allow it to complete.

Simply running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. To fully use the potential of <tt>pscons</tt> for running on a distributed-memory computer, you need to set the environment variables <tt>RSF_CLUSTER</tt> and <tt>RSF_THREADS</tt>, and to use <tt>split</tt> and <tt>reduce</tt> arguments in your SConstruct Flow statements where appropriate.

===Setting the environment variables===

The <tt>RSF_CLUSTER</tt> variable holds, for each node, the name or IP address of that node (in a format that can be used by ssh), followed by the number of threads on the node. For example, creating 26 threads and sending them on 4 nodes, using respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs on each of the last two nodes:
<bash>
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

The <tt>RSF_THREADS</tt> variable holds the sum of the numbers of threads on all nodes, i.e.:
<bash>
export RSF_THREADS=26
</bash>
If <tt>RSF_CLUSTER</tt> is not defined, <tt>RSF_THREADS</tt> can be used to override the auto-detected number of threads used on the local host. This can be useful in the case of processes using a large amount of memory.

In Beowulf-type clusters in which communication of the processor with the local disk is much faster than with the shared network storage, it is important to set in the shell resource file the temporary file location to a local disk, and the <tt>DATAPATH</tt> variable to a network-visible location for global collection of results, i.e.:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

===The split and reduce options in Flow()===
The split option specifies the number of the axis to be split and the size of that axis. For an axis 3 of length 1000 on the standard in file, and collection by concatenation:
<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>
Concatenation is the default reduction method. The other valid option is <tt>reduce='add'</tt> .

In flows that are run by <tt>pscons</tt>, but contain both serial and parallel targets, care must be exercised in order to not create bottlenecks, in which tasks are distributed to multiple nodes, but the nodes sit idle while waiting other nodes to finish computing dependencies. Tasks that are not explicitly parallelized will be sped up by <tt>pscons</tt> if they are independent from each other. For example, building Madagascar with <tt>pscons</tt> instead of scons results in a visible speedup on a multithreaded machine.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons attempts to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel, especially by overloading the I/O system with identical operations.
<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

===What to expect at runtime===
Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

Parallel Computing

2011-08-11T03:11:44Z

Nick: /* pscons */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Unlike the OpenMP or MPI utilities, this has fault tolerance -- in case of a node failing, restarting the job will allow it to complete.

Simply running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. To fully use the potential of <tt>pscons</tt> for running on a distributed-memory computer, you need to set the environment variables <tt>RSF_CLUSTER</tt> and <tt>RSF_THREADS</tt>, and to use <tt>split</tt> and <tt>reduce</tt> arguments in your SConstruct Flow statements where appropriate.

===Setting the environment variables===

The <tt>RSF_CLUSTER</tt> variable holds, for each node, the name or IP address of that node (in a format that can be used by ssh), followed by the number of threads on the node. For example, creating 26 threads and sending them on 4 nodes, using respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs on each of the last two nodes:
<bash>
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

The <tt>RSF_THREADS</tt> variable holds the sum of the numbers of threads on all nodes, i.e.:
<bash>
export RSF_THREADS=26
</bash>
If <tt>RSF_CLUSTER</tt> is not defined, <tt>RSF_THREADS</tt> can be used to override the auto-detected number of threads used on the local host. This can be useful in the case of processes using a large amount of memory.

In Beowulf-type clusters in which communication of the processor with the local disk is much faster than with the shared network storage, it is important to set in the shell resource file the temporary file location to a local disk, and the <tt>DATAPATH</tt> variable to a network-visible location for global collection of results, i.e.:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

===The split and reduce options in Flow()===
The split option specifies the number of the axis to be split and the size of that axis. For an axis 3 of length 1000 on the standard in file, and collection by concatenation:
<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>
Concatenation is the default reduction method. The other valid option is <tt>reduce='add'</tt> .

In flows that are run by <tt>pscons</tt>, but contain both serial and parallel targets, care must be exercised in order to not create bottlenecks, in which tasks are distributed to multiple nodes, but the nodes sit idle while waiting other nodes to finish computing dependencies. Tasks that are not explicitly parallelized will be sped up by <tt>pscons</tt> if they are independent from each other. For example, building Madagascar with <tt>pscons</tt> instead of scons results in a visible speedup on a multithreaded machine.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons attempts to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel, especially by overloading the I/O system with identical operations.
<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T02:43:25Z

Nick: /* Setting the environment variables */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Just running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. To fully use the potential of <tt>pscons</tt> for running on a distributed-memory computer, you need to set the environment variables <tt>RSF_CLUSTER</tt> and <tt>RSF_THREADS</tt>, and to use a <tt>split</tt> argument in your SConstruct Flow statements where appropriate.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T02:42:29Z

Nick: /* pscons */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Just running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. To fully use the potential of <tt>pscons</tt> for running on a distributed-memory computer, you need to set the environment variables <tt>RSF_CLUSTER</tt> and <tt>RSF_THREADS</tt>, and to use a <tt>split</tt> argument in your SConstruct Flow statements where appropriate.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T02:33:28Z

Nick: /* pscons */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
To get SCons to cut your inputs into slices, run in parallel on one multi-cpu workstation or on multiple cluster nodes and then collect, use the <tt>pscons</tt> wrapper to <tt>scons</tt>. Just running pscons with no special environment variable set is equivalent to running <tt>scons -j nproc</tt>, where <tt>nproc</tt> is the auto-detected number of threads on your system. By setting

Several functionalities have been added in Madagascar for parallel computing on clusters with distributed memory.
The <tt>SConstruct</tt> files have to be run with '''pscons''' instead of <tt>scons</tt>. The command '''pscons''' is a wrapper for
the use of SCons with the option -j.
The environment variables <tt>$RSF_THREADS</tt> and <tt>$RSF_CLUSTER</tt> respectively provide to '''pscons''' the number of threads
and the address list of the nodes you want to use for your computation.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T02:26:56Z

Nick: /* Options in the SConstruct file */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
If

Several functionalities have been added in Madagascar for parallel computing on clusters with distributed memory.
The <tt>SConstruct</tt> files have to be run with '''pscons''' instead of <tt>scons</tt>. The command '''pscons''' is a wrapper for
the use of SCons with the option -j.
The environment variables <tt>$RSF_THREADS</tt> and <tt>$RSF_CLUSTER</tt> respectively provide to '''pscons''' the number of threads
and the address list of the nodes you want to use for your computation.

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T02:25:19Z

Nick: /* Old content below */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==pscons==
If

Several functionalities have been added in Madagascar for parallel computing on clusters with distributed memory.
The <tt>SConstruct</tt> files have to be run with '''pscons''' instead of <tt>scons</tt>. The command '''pscons''' is a wrapper for
the use of SCons with the option -j.
The environment variables <tt>$RSF_THREADS</tt> and <tt>$RSF_CLUSTER</tt> respectively provide to '''pscons''' the number of threads
and the address list of the nodes you want to use for your computation.

== Options in the SConstruct file ==

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Advanced Installation

2011-08-11T01:32:00Z

Nick: /* Used by the Madagascar build process */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS, Scientific Linux, openSUSE==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<bash>
pfexec pkg install SUNWxorg-headers
</bash>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Manual

2011-08-11T01:19:30Z

Nick: /* How to parallelize your programs */ wikified 2007-12-27 blog post

[[Image:Fotolia_8418493_XS.jpg|right|]]
As the number of pages on the Wiki grows, the navbar starts becoming insufficient for proper organization of all documentation. A top-down view of all materials about Madagascar is also useful for determining whether gaps in coverage exist. This page will stay in the Sandbox for a long while -- until all gaps have been filled.

Ideally the manual will only consist of either links to wiki pages, or own content. "Forking", i.e. creating a modified copy of a page especially for the manual, invariably ends up with one version getting out of synch.

=About Madagascar=
==Introduction==
[[Main Page]] of the wiki, and the [[Package overview]].

==For people who do not read manuals==
Point them to [[Download]], [[Installation|Short Install Guide]], and the [[Revisiting SEP tour with Madagascar and SCons|SEPlib Tour Revisited]].

==Why use Madagascar?==
An articulate description of the reasons on the [[Why Madagascar]] page. Have some spectacular pictures obtained with algorithms that are not present in other packages. Describe algorithms/tools unavailable in other open-source geophysical data analysis packages.

==Community==
A description of the current Madagascar community, with the map of downloads and an estimate of the number of installs, who are the biggest users, outstanding research results obtained with Madagascar, etc. Links to the [http://reproducibility.org/rsflog/ blog], [https://lists.sourceforge.net/lists/listinfo/rsf-user user mailing list], [https://lists.sourceforge.net/lists/listinfo/rsf-devel developer mailing list]. Mention of the Google Groups mirrors for [http://groups.google.com/group/osdeve_mirror_geophysics_rsf-user rsf-user] and [http://groups.google.com/group/osdeve_mirror_geophysics_rsf-devel rsf-devel] Also mention the [http://sourceforge.net/tracker/?group_id=162909&atid=825645 bug tracker] and [http://sourceforge.net/tracker/?group_id=162909&atid=825648 feature request tracker], encouraging the community to use them more. Mention [http://sourceforge.net/forum/?group_id=162909 forums] as an alternative for those who want to ask questions or conduct discussions without subscribing to a mailing list.

==History==
A history of Madagascar, with the SEPlib/SU part of the [[Introduction_to_madagascar#Alternatives|"Alternatives" section of the Introduction]], and mentions of landmark events (short descriptions where necessary):
* 2003: Work started by Sergey Fomel
* 2004-08 (?): made available to selected alpha users
* 2005-02-16: RSF Blog started
* 2006-03-17: Registered on Sourceforge
* 2006-04-19: [http://www.m8r.info/rsflog/index.php?/archives/67-Madagascar.html Name change from RSF to Madagascar]
* 2006-06-11: Public launch at the Open Source E&P Software EAGE Workshop (Vienna)
* 2006-06-18: [http://www.m8r.info/rsflog/index.php?/archives/74-Mailing-lists-and-madagascar-0.9.1.html First stable version (0.9.1). Mailing lists created]
* 2006-07-23: [http://www.m8r.info/rsflog/index.php?/archives/86-New-madagascar-logo.html Madagascar logo created by Scott Rodgers (BEG)]
* 2007-04-27: Release 0.9.4
* 2007-11-10: Release 0.9.5
* 2008-06-14: Release 0.9.6
* 2009-01-03: Release 0.9.7
* 2009-08-01: Release 0.9.8
* 2010-05-02: Release 0.9.9
* 2010-07-23: Release 1.0
* For details on releases after 1.0, see [[Release Notes]]

A link to the appendix containing the content of the [[Conferences]] and [[Publications]] pages.

=Downloading and installing Madagascar=
==Download==
[[Download]]
==Install==
# [[Installation|Short installation guide]]
# [[Advanced Installation|Advanced installation guide]]
==Licensing and export regulations==
* Explanation and text of the GPL 2+
* [[US export control]]

=Using Madagascar=
==The lightning-quick tour==
The [[Revisiting SEP tour with Madagascar and SCons|revisited SEP Tour]]

==The Madagascar file formats==
===The Regularly Sampled Format (RSF)===
The current [[Guide_to_RSF_file_format|Guide to RSF file format]]
===Handling irregularly sampled data===
Explain the principle of the current method (sfheadermath/sfheaderwindow used on the trace header block output by su/segyread)
===Importing and exporting data from and to SEG-Y and SU===
sfsegyread and sfsuread, with examples

===Importing and exporting data from and to raster images===
[[Raster image I/O]]
===Visualizing data and exporting figures with vplot===
* Explanation of vplot format
* Preempting display aliasing in raster plots with <tt>sfprep4plot</tt>
* How to create vplot images with sfgraph, sfgrey, sfdots, etc. [[Common pen parameters]]
* How to display vplot images with sfpen. How it defaults to <tt>oglpen</tt> on systems that support OpenGL, and <tt>xtpen</tt> on systems that do not support it, but have X Windows.
* How to convert vplot images to other formats with <tt>vpconvert</tt>. This tool can work on a single plot, i.e.:
<bash>
vpconvert file.vpl file.jpg
</bash>
or an entire collection of files:
<bash>
vpconvert format=tiff Fig/*.vpl
</bash>
The <tt>vpconvert</tt> program can export to and from a multitude of file formats: avi, eps, gif, jpg, mpeg, pdf, png, ppm, ps, svg, and tif, and is the recommended vpl import and export tool. Older single-purpose utilities (vplot2gif and vplot2avi) are still available.

===Visualizing data and exporting figures with GLE===
[[Graphics with GLE]]

===Visualizing data and exporting figures with gnuplot===
[[Graphics with gnuplot]]
===Visualizing data and exporting figures with PLplot===
[http://plplot.sourceforge.net/examples.php PLplot] is a device-independent vector-plotting library. Their concept is very similar to that of vplot, but instead
of separated device-dependent pens (like xtpen or pspen) they use loadable "drivers" (organized as shared objects and connected to a plotting programs in a plugin fashion). They have an extensive high-level interface for different types of plots.

A sample Madagascar program which utilizes PLplot's surface rendering capabilities is [[Guide_to_madagascar_programs#Plotting_programs_.28development.29 | sfplsurf]].

==Calling existing Madagascar programs==
===Finding out what program you need===
# [http://reproducibility.org/rsflog/index.php?/archives/128-How-do-I-find-programs-in-madagascar.html sfdoc -k]
# [[Task-centric program list]] and all its subordinate nodes
# Collection of 2-3 page reproducible papers -- "How to do raytracing in Madagascar"; "How to do modeling in Madagascar"; etc
# [[SU to m8r dictionary]]
# [[SEPlib to m8r dictionary]]
# Other such dictionaries, for free or proprietary seismic processing packages. Such dictionaries are also useful because they will highlight algorithms/utilities present in such packages but missing from m8r.

This chapter is now just a sketch, should get quite big. Users approach tools in a task-centric fashion, i.e. Q1:"how do I do X with Madagascar?", A1:"With feature Y"; Q2: "How do I use feature Y to this end?" M8r is very good at answering Q2, but people ask Q1 first. Many of the reproducible papers included so far contain cutting-edge research. Users learning how to use Madagascar need to start with something much more simple, where they do not have to focus on understanding research on top of understanding software.

===Learning how to use a given program===
# Command-line self-doc
# Local html self-doc (<tt>$RSFROOT/doc/index.html</tt>). Contains all programs installed on the user's machine and only those programs.
# [http://reproducibility.org/RSF/ Online self-doc]
# The wiki [[Guide_to_madagascar_programs|Guide to Programs]].
# Series of dedicated reproducible papers that present the theory behind specific geophysical programs and demonstrate it with various types of inputs and combination of parameters, like [http://www.reproducibility.org/RSF/book/sep/fkamo/paper_html/paper.html this paper] does for SEPlib's AMO program.
# Combining together multiple programs -- the reproducible papers; pointer to relevant section of the manual ("Exploring reproducible papers")

==What is reproducibility==
The whole [[Reproducibility]] page, combined with Section 1 from [[Reproducible computational experiments using SCons]]

==Exploring existing reproducible papers==
===Papers and books included in the Madagascar distribution===
[[Reproducible Documents]] and more.

===How to reproduce specific figures in existing papers===
A frequently encountered case is when a researcher wants to reproduce only one or several figures from an entire paper, but not the entire paper. This can happen because on that system LaTeX dependencies of Madagascar are missing or not working properly, or simply because the researcher is interested only in that result.
# '''Finding the paper directory:''' If the interesting article has been found by browsing/hyperlink to [[Reproducible Documents]], then the reproducibility package corresponding to <pre>http://www.reproducibility.org/RSF/book/<bookname>/<papername>/paper_html/</pre> can be found in <pre>RSFSRC/book/<bookname>/<papername>/</pre>
# '''Finding result names:''' Use the html version of the paper, or grep in all <tt>.tex</tt> files in the directory for a text string that occurs in the figure legend. Multiple-panel figures may have individual names for each panel. [Note: In pdf versions obtained with scons pdf in paper directory, neither the book name nor paper directory name nor figure names are given. LaTeX options to have figure names as well as a Geophysics-style header/footer with more details on the first page may be in order]
# '''Finding where to launch the re-build''': In some cases, rules for creating a result are specified in SConstruct files in subdirectories of the main paper directory. If step 4 fails in the main paper directory, then you will have to find where the figure is built. Because result names may be generated automatically, a simple grep may not be enough and you may need to read the SConstruct and python modules imported by it to figure out if the result is generated there.
# '''Re-build''' and display the figure by typing <tt>scons resultname.view</tt> in the appropriate directory.

SConstructs containing a <tt>Fetch</tt> instruction will attempt to download public-domain input data from a communal server when the "scons" command is run. A fast internet connection is necessary in this case.

===How to reproduce entire papers using stored figures===
# See the previous section for how to find the paper directory
# Pointer to how to download stored figures ([[Download#Reproducible figures]])
*<tt>scons pdf</tt>
*<tt>scons read</tt>

Troubleshooting:
* In case of failure with this kind of messages (details here), you miss TeX system dependencies. Install a TeX system. [http://www.tug.org/texlive/ Tex Live] should have it all. Note: It's a 1 Gb download. Too large for many individual users to bother with it and for most IT departments of companies to review for security. We should implement individual dependency checking, like we do in the installation.
* In case of failure with <tt>LaTeX Error: File `geophysics.cls' not found</tt> you have LaTeX, but you are missing [[SEGTeX]]
* If <tt>scons pdf</tt> in the paper directory requires pdf figures already in place in order to work, run <tt>sftour scons lock</tt> (?).

===How to reproduce entire papers and all their figures===
# See an earlier section for how to find the paper directory
# The relevant SCons command (<tt>scons lock</tt>, or <tt>sftour scons lock</tt>, as in [[Download#Reproducible figures]] to force reproducing the figures in the paper even when the reference figures repository is present

Tell the user to expect conditional reproducibility: If Matlab is not present, rsftex will not try to build the figures but will use the stored PDF files (same goes for Mathematica, xfig, etc.)

===How to reproduce whole books===
The [http://sourceforge.net/mailarchive/forum.php?thread_name=20061222142849.9688.qmail%40web34215.mail.mud.yahoo.com&forum_name=rsf-user 2006-12-22 rsf-user thread], [http://reproducibility.org/rsflog/index.php?/archives/142-Assembling-reports-from-papers.html the 2007-04-08 blog entry] and more.

From Jim's 2009-03-7 rsf-devel message:
Here is a way to generate all the targets in the subdirectories of $RSFSRC/book/geostats/spatial_stats:
<bash>
cd $RSFSRC/book/geostats/spatial_stats
sftour scons
</bash>
That works pretty nice. It generates all the targets in each of the 4 subdirectories of book/geostats/spatial_stats.

Now suppose I want to capture the output and errors in a log file (tcsh):
<bash>
sftour scons >& scons.log
</bash>
That's nice, except all the output goes into one log file in book/geostats/spatial_stats. Suppose I want 4 separate log files, one in each of the subdirectories. This will do the trick:
<bash>
sftour 'scons >& scons.log'
</bash>
The quotes make the entire string go to sftour as the command to run in each directory, instead of just 'scons'.

So far so good. Now suppose I want to go up one directory level and do the process recursively:
<bash>
cd $RSFSRC/book/geostats
sftour sftour 'scons >& scons.log'
</bash>
Well, that runs scons in each of the book/geostats/*/* directories, but it only makes 3 log files in the 3 subdirectories of book/geostats, not 14 log files in the 14 book/geostats/*/* directories. I can get 14 separate log files like this:
<bash>
sftour "sftour 'scons >& scons.log'"
</bash>
That does what I want. Now suppose I want to go up one more level to $RSFSRC/book and run the process recursively three levels deep:
<bash>
sftour sftour "sftour 'scons >& scons.log'"
</bash>
This works, but it doesn't put the log files in the bottom level, it puts them one level up. I can't fix it the same way I did before because I've run out of quotes :-) Here is one way to do it (tcsh):
<pre>
foreach i (*)
if ( -d $i) then
echo ++++++ $i
cd $i
sftour "sftour '/usr/bin/time -p scons >& scons.log'"
cd ..
endif
end
</pre>

From Sergey's 2009-03-10 rsf-devel message: A more elegant solution is
<bash>
sftour sftour scons >& ../../%/%/scons.log
</bash>

==Writing a LaTeX paper in the Madagascar framework==
Follows the natural progression of learning of somebody who may even not know LaTeX, let alone SCons.
# A paper with no figures.
# A paper with NR-only figures
==Creating a reproducible paper==
Sections 2 and 3 from [[Reproducible computational experiments using SCons]]. Also, mention the "SCons macros" in <tt>book/Recipes</tt>.

Publications included in Madagascar's book directories are tested periodically. Those publications that fail the tests and are not easily repaired are moved to <tt>book/Grave</tt>, with a note on how the tests failed and why the problems could not be fixed.
==Data-conditional reproducibility==
Due to seismic data licensing terms, an author may find it possible to make public everything that is needed to make a publication reproducible, except for the data. In such conditions, the paper is still acceptable for inclusion in the Madagascar collection. To indicate that certain datasets are private, the relevant <tt>SConstruct</tt> files should use <tt>Fetch(...,local=1)</tt> or tt>Fetch(...,server=private.server)</tt>, where <tt>private.server</tt> is a password-protected private server. Affected vplot figures should be uploaded to the [[Download#Reproducible figures | figure repository]]. Reproducibility testing will be skipped for the affected figures, but the html and pdf versions of the publications will still be created.

The usage of public seismic datasets, such as those at http://software.seg.org/, is strongly encouraged.

==Creating a reproducible book==

=Developing in Madagascar=
==Writing your own programs==
===Introduction to the Madagascar API===
# The existing [[Guide_to_madagascar_API|data clipping API demo]]
# A more complex [[Guide_to_programming_with_madagascar|finite differences API demo]] – add Python, F77 and Matlab APIs to it

===How to add your program===
[[Adding_new_programs_to_madagascar#How_to_add_your_program|The relevant section in "Adding programs"]]

===How to document your program===
[[Adding_new_programs_to_madagascar#How_to_document_your_program|The relevant section in "Adding programs"]]

===Style guide===
[[Adding_new_programs_to_madagascar#Style_guide|The relevant section in "Adding programs"]]

===How to test your program===
[[Adding_new_programs_to_madagascar#How_to_test_your_program|The relevant section in "Adding programs"]]

===How to parallelize your programs===
The [[Parallel Computing]] page.

===Tips and tricks===
[[Adding_new_programs_to_madagascar#Tips_and_tricks|The relevant section in "Adding programs"]]

===Madagascar library reference===
* [[Library Reference]]
* The [http://m8r.info/rsf_epydoc/ Python API documentation]
* The [http://m8r.info/RSF/book/rsf/manual/manual_html/ Programming Reference Manual]

==Adding programs to the central repository==
==Framework development and maintenance==
Description of m8r's inner works for those who want to help improve and maintain Madagascar. [[Maintenance guide]] and perhaps other stuff.
==Graphics development with vplot==
[[Graphics development with vplot]]
==Packaging madagascar==
[[Packaging madagascar]]

=Datasets distributed with Madagascar=
* Description of datasets – pictures of the velocity model, of sample gathers, zero-offset sections, migrated image.
* Comment on which are the main problems they illustrate (internal multiples? overturning waves? etc). Algorithm used for generating them, references to published literature describing the datasets
* Command line options for correctly reading them from the storage format (SEG-Y, most probably) into RSF
* In general, expand the [[Reproducible_Documents#Madagascar_Datasets | datasets section of Reproducible Documents page]] to include other datasets

=Other open-source data analysis packages=
==Geophysical software==
[[Other open-source geophysical packages]]. Briefly discuss each of them. Mention "dictionaries" from them to m8r where available (should attempt to have dictionaries for all of them)

==Other tools==
There are many other useful open-source or public domain software tools in the domain of applied mathematics, that can be used complementary to Madagascar. A few common examples, in alphabetical order, are:

* [http://www.alglib.net/ ALGLIB]: a highly portable numerical analysis and data processing library;
* [http://www.caam.rice.edu/software/ARPACK/ ARPACK] ("The ARnoldi PACKage"): a library written in FORTRAN 77 for solving large-scale eigenvalue problems;
* [http://math-atlas.sourceforge.net/ ATLAS] ("Automatically Tuned Linear Algebra Software"): a linear algebra library, implementing the [http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms BLAS] APIs for C and Fortran77;
* [http://www.oonumerics.org/blitz/ Blitz++]: a C++ class library for scientific computing which provides performance on par with Fortran 77/90;
* [http://www.dune-project.org/ DUNE] ("Distributed and Unified Numerics Environment"): a modular toolbox for solving partial differential equations with grid-based methods. It supports the easy implementation of methods like Finite Elements, Finite Volumes, and also Finite Differences.
* [http://fftw.org/ FFTW] ("The Fastest Fourier Transform in the West"): Hardware-adaptive FFT libraries;
* [http://www.gnu.org/software/gsl/ GNU Scientific Library]: a C library for numerical calculations in many branches of applied mathematics and science;
* [http://gts.sourceforge.net/index.html GNU Triangulated Surface Library]: a library providing a set of useful functions to deal with 3D surfaces meshed with interconnected triangles;
* [http://www.netlib.org/lapack/ LAPACK] ("The Linear Algebra PACKage"): a collection of routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems;
* [http://en.wikipedia.org/wiki/MINPACK MINPACK]: a library of FORTRAN subroutines for the solving of systems of nonlinear equations, or the least squares minimization of the residual of a set of linear or nonlinear equations;
* [http://www.mcs.anl.gov/petsc/petsc-2/ PETSc] ("the Portable, Extensible Toolkit for Scientific computation"): A set of serial and parallel, linear and nonlinear, solvers for large-scale, sparse linear and nonlinear systems of equations;
* [http://www.scipy.org/ SciPY] ("Scientific Python"): a toolbox for scientific computing in Python;
* [http://www.boost.org/doc/libs/1_39_0/libs/numeric/ublas/doc/index.htm uBLAS]: a C++ template class library that provides BLAS level 1, 2, 3 functionality for dense, packed and sparse matrices.

Most [http://en.wikipedia.org/ Wikipedia] pages of the above libraries are valuable resources, as is Wikipedia's [http://en.wikipedia.org/wiki/List_of_numerical_analysis_software list of numerical analysis software]. Other libraries and standalone programs are available through the [http://www.netlib.org/ Netlib repository] and indexed by the [http://gams.nist.gov/ Guide to Available Mathematical Software]. The U.S. DOE's [http://acts.nersc.gov/ ACTS Collection] is another valuable repository.

==Madagascar in conferences and publications==
The content of the [[Conferences]] and [[Publications]] pages. A mention about the reproducible documents that are listed in the "Papers and books included in the Madagascar distribution" sections.
==Madagascar project system administrator's guide==
[[Mediawiki installation, customization and operation]]

Parallel Computing

2011-08-11T01:17:27Z

Nick: /* MPI (external) */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==MPI + OpenMP (both external)==

It is possible to combine the advantages of shared-memory and distributed-memory architectures by using OpenMP and MPI together.
<bash>
mpirun -np 32 sfmpi sfomp sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
will distribute the job on 32 nodes and split it again on each node using shared-memory threads.

==Old content below==

Several functionalities have been added in Madagascar for parallel computing on clusters with distributed memory.
The <tt>SConstruct</tt> files have to be run with '''pscons''' instead of <tt>scons</tt>. The command '''pscons''' is a wrapper for
the use of SCons with the option -j.
The environment variables <tt>$RSF_THREADS</tt> and <tt>$RSF_CLUSTER</tt> respectively provide to '''pscons''' the number of threads
and the address list of the nodes you want to use for your computation.

== Options in the SConstruct file ==

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T01:16:14Z

Nick: /* OpenMP (internal) */

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M
</bash>
On the last check (2011-08-10), 84 standalone programs (approximately 10% of Madagascar programs) were using OMP. Running this command in the directory <tt>$RSFSRC/api/c</tt> will yield a few functions parallelized with OMP (among which a Fourier Transform).

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==Old content below==

Several functionalities have been added in Madagascar for parallel computing on clusters with distributed memory.
The <tt>SConstruct</tt> files have to be run with '''pscons''' instead of <tt>scons</tt>. The command '''pscons''' is a wrapper for
the use of SCons with the option -j.
The environment variables <tt>$RSF_THREADS</tt> and <tt>$RSF_CLUSTER</tt> respectively provide to '''pscons''' the number of threads
and the address list of the nodes you want to use for your computation.

== Options in the SConstruct file ==

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Parallel Computing

2011-08-11T01:09:39Z

Nick: Merging page with 2007-12-27 post and with new info

Many of the data processing operations are '''data-parallel''': different traces, shot gathers, frequency slices, etc. can be processed independently. Madagascar provides several mechanisms for handling this type of embarrassingly parallel applications on computers with multiple processors.

==OpenMP (internal)==
[https://secure.wikimedia.org/wikipedia/en/wiki/OpenMP OpenMP] is a standard framework for parallel applications on '''shared-memory''' systems. It is supported by the latest versions of [http://gcc.gnu.org/ GCC] and by some other compilers.

To use OpenMP in your program, you do not need to add anything to your SConstruct. Just make sure the OMP libraries are installed on your system before you configure Madagascar, (or -- reinstall them and rerun the configuration command). Of course, you need to use the appropriate pragmas in your code. To find Madagascar programs that use OpenMP and that you can take as a model, run the following command:

<bash>
grep "pragma omp" $RSFSRC/user/*/*.c |\
awk -F ':' '{ print $1 }' |\
uniq |\
awk -F '/' '{ print $NF }' |\
grep M |\
wc -l
</bash>

==OpenMP (external)==

To run on a multi-core shared-memory machine a data-parallel process that does not contain OpenMP calls, use <tt>sfomp</tt>. Thus, a call like
<bash>
sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
becomes
<bash>
sfomp sfradon np=100 p0=0 dp=0.01 < inp.rsf > out.rsf
</bash>
<tt>sfomp</tt> splits the input along the slowest axis (presumed to be data-parallel) and runs it through parallel threads. The number of threads is set by the <tt>OMP_NUM_THREADS</tt> environmental variable or (by default) by the number of available CPUs.

==MPI (internal)==
[http://www.mcs.anl.gov/research/projects/mpi/ MPI] (Message-Passing Interface) is the dominant standard framework for parallel processing on different computer architectures including '''distributed-memory''' systems. Several MPI implementations (such as [http://www.open-mpi.org/ Open MPI] and [http://www.mcs.anl.gov/research/projects/mpich2/ MPICH2]) are available.

An example of compiling a program with <tt>mpicc</tt> and running it under <tt>mpirun</tt> can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/bash/mpi/SConstruct?view=markup $RSFSRC/book/rsf/bash/mpi/SConstruct]

==MPI (external)==
To parallelize a task using MPI but without including MPI calls in your source code, try <tt>sfmpi</tt>, as follows:
<bash>
mpirun -np 8 sfmpi sfradon np=100 p0=0 dp=0.01 input=inp.rsf output=out.rsf
</bash>
where the argument after <tt>-np</tt> specifies the number of processors involved. sfmpi will use this number to split the input along the slowest axis (presumed to be data-parallel) and to run it through parallel threads. Notice that the keywords <tt>input</tt> and <tt>output</tt> are specific to <tt>sfmpi</tt> and they will be used to specify the standard input and output streams of your program.

Some MPI implementations do not support system calls implemented in sfmpi and therefore will not support this feature.

==Old content below==

Several functionalities have been added in Madagascar for parallel computing on clusters with distributed memory.
The <tt>SConstruct</tt> files have to be run with '''pscons''' instead of <tt>scons</tt>. The command '''pscons''' is a wrapper for
the use of SCons with the option -j.
The environment variables <tt>$RSF_THREADS</tt> and <tt>$RSF_CLUSTER</tt> respectively provide to '''pscons''' the number of threads
and the address list of the nodes you want to use for your computation.

== Options in the SConstruct file ==

=== Computing on the local node only by using the option local=1 ===

By default, with '''pscons''', SCons wants to run all the commands of the <tt>SConstruct</tt> file in parallel.
The option '''local=1''' forces SCons to compute locally. It can be very useful in order to prevent serial
parts of your python script to be run inefficiently in parallel.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000',local=1)
</python>

=== Computing on the nodes of the cluster specified by the environment variable <tt>$RSF_CLUSTER</tt> ===

<python>
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04',split=[3,1000],reduce='cat')
</python>

The option '''split''' instructs '''Flow''' to split the input file along the third axis of length 1000.
If you have several source files and want to split only some of them, say the first and the third one, the option to use will be '''split'''=[3,1000,[0,2]]'''.

If we choose <tt>$RSF_THREADS</tt>=26, we obtain, as an itermediate result in the local directory, the files
<tt>spike__0.rsf, spike__1.rsf, ..., spike__25.rsf,</tt> which are sent and distributed for computation on the different nodes
specified by <tt>$RSF_CLUSTER</tt>.
After the parallel computation on the nodes, the resulting files
<tt>radon__0.rsf, radon__1.rsf, ..., radon__25.rsf</tt>, are recombined together to create the output <tt>radon.rsf</tt>.
The parameter '''reduce''' selects the type of recombination. Two typical options are '''reduce'''='cat' or '''reduce'''='add'.

=== Computing in parallel without using any option ===

This choice is appropriate when you write a python loop in your program
and want it to be run in parallel. This is a way, as well, to speed up sequential parts of your program.
However, the user should make judicious decisions as it can have the opposite effect.
Indeed, in a serial part of the program, the second command has to wait for the first to finish the run on a different node and to communicate it.

<python>
Flow('spike',None,'spike n1=100 n2=300 n3=1000')
Flow('radon','spike','radon adj=y p0=-4 np=200 dp=0.04')
</python>

== Setting the environment variables ==

In our example, we used 26 threads and send them on 4 nodes, using
respectively 6 CPUs on the first node, 4 CPUs on the second, and 8 CPUs
on each of the last two nodes.

<bash>
export RSF_THREADS=26
export RSF_CLUSTER='140.168.1.236 6 140.168.1.235 4 140.168.1.234 8 140.168.1.233 8'
</bash>

One important setting is to properly manage the temporary files location specified by <tt>$TMPDATAPATH</tt>
and the data storage location specified by <tt>$DATAPATH</tt> .
The temporary files used during the computation have to be stored locally on each node to avoid too much communication
between the hard disks and the nodes.
The paths will depend on your cluster and you can set them in your <tt>.bashrc</tt> file, for example:

<bash>
export DATAPATH=/disk1/data/myname/
export TMPDATAPATH=/tmp/
</bash>

== Run ==

Once your <tt>SConstruct</tt> file is ready and your environment variables are set,
you can use the following suggested procedure.
It has been tested and is currently used on a linux cluster.

* Make sure the disk located at <tt>$DATAPATH</tt> is mounted on the different nodes.
* Test if there is enough space available on the different nodes of the cluster at the location specified by <tt>$TMPDATAPATH</tt>. This directory may be filled up, if some jobs have been interrupted. Clean this up if necessary.
* Look at what is going on on your cluster with '''sftop'''.
* Everything looks good ? Then go and run '''pscons''' instead of <tt>scons</tt>.
* If you need to kill your processes on the cluster, the command '''sfkill''' can do it remotely on all the nodes for a specific job command. If you kill your jobs, check it did not filled up the <tt>$TMPDATAPATH</tt> with temporary files before you run '''pscons''' again.

One nice feature of running SCons on clusters is fault tolerance (see [http://www.reproducibility.org/rsflog/index.php?/archives/160-Parallel-processing.html relevant blog post]).

Seismic task-centric program list

2011-08-09T03:00:27Z

Nick: /* Elastic modeling */

[[Image:Fotolia_369804_XS.jpg|right|]]
This page presents a list of programs for seismic processing, imaging and analysis. An overview of all task-centric pages can be found in the main [[Task-centric program list]].

The most frequent question encountered from a new user is: "Does Madagascar do [some needed process]?" The first level of classification is therefore by types of geophysical procedures. Then the classifications below try to follow's the user's workflow:
# What sort of data must be processed/imaged: 3-D, 2-D, prestack, poststack?
# If a velocity model is needed, which sort is available? A v(x,z) one, a v(z) or a constant velocity?
# Which algorithm to use if several are available.

'''All program names below should be prefixed with "sf".'''

=Manipulating irregular datasets, regularization and sorting=
* Integer header attributes: [http://reproducibility.org/RSF/sfheaderattr.html headerattr]
* Zero a portion of a dataset based on a header mask: [http://reproducibility.org/RSF/sfheadercut.html headercut]
* Mathematical operations, possibly on header keys: [http://reproducibility.org/RSF/sfheadermath.html headermath]
* Sort a dataset according to a header key: [http://reproducibility.org/RSF/sfheadersort.html headersort]
* Window a dataset based on a header mask: [http://reproducibility.org/RSF/sfheaderwindow.html headerwindow]
* Create a mask: [http://reproducibility.org/RSF/sfmask.html mask]
* Shot interpolation: [http://reproducibility.org/RSF/sfinfill.html infill]
* Data binning (geometry regularization): [http://reproducibility.org/RSF/sfintbin.html intbin] (works especially for basically regular geometries but with skipped or resorted traces)
* Data binning in 1-D slices: [http://reproducibility.org/RSF/sfbin1.html bin1]
* Data binning in 2-D slices: [http://reproducibility.org/RSF/sfbin.html bin]
* Data regularization in 2-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanereg2.html planereg2]
* Data regularization in 3-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanereg3.html planereg3]
* Convert CMPs to shots for regular 2-D geometry: [http://reproducibility.org/RSF/sfcmp2shot.html cmp2shot]
* Convert shots to CMPs for regular 2-D geometry: [http://reproducibility.org/RSF/sfshot2cmp.html shot2cmp]
* 2-D fold maps: [http://ahay.org/RSF/sfhist2.html hist2]

=Interpolation tools=
==Making holes==
* Cut an elliptic hole in data (for interpolation tests): [http://reproducibility.org/RSF/sfhole.html hole]
* Create a synthetic irregular dataset for interpolation tests: [http://reproducibility.org/RSF/sfsyntop.html syntop]
==Actual interpolation==
* Linear interpolation: [http://reproducibility.org/RSF/sflint1.html lint1]
* 1-D cubic spline interpolation: [http://reproducibility.org/RSF/sfspline.html spline]
* Data interpolation in 2-D slices using helix preconditioning: [http://reproducibility.org/RSF/sfinvbin.html invbin]
* 1-D inverse interpolation: [http://reproducibility.org/RSF/sfinvbin1.html invbin1]
* Leveler inverse interpolation in 1-D: [http://reproducibility.org/RSF/sflevint.html levint]
* Find MISSing Input values and Filter in 1-D: [http://reproducibility.org/RSF/sfmisif.html misif]
* Missing data interpolation in 1-D: [http://reproducibility.org/RSF/sfmiss1.html miss1]
* 2-D missing data interpolation: [http://reproducibility.org/RSF/sfmiss2.html miss2]
* Missing data interpolation (N-dimensional) using shaping regularization: [http://reproducibility.org/RSF/sfmiss3.html miss3]
* Multi-dimensional missing data interpolation: [http://reproducibility.org/RSF/sfmiss.html miss]
* Multiscale missing data interpolation (N-dimensional): [http://reproducibility.org/RSF/sfmsmiss.html msmiss]
* 2-D missing data interpolation by differential offset continuation: [http://reproducibility.org/RSF/sfofilp.html ofilp]
* 1-D ENO (Essentially Non Oscillatory) interpolation: [http://reproducibility.org/RSF/sfremap1.html remap1]
* ENO interpolation in 2-D slices: [http://reproducibility.org/RSF/sfenoint2.html enoint2]
* 2-D trace interpolation to a denser grid using PWD ("beyond aliasing" method): [http://reproducibility.org/RSF/sfdealias.html dealias]
* Shot interpolation: [http://reproducibility.org/RSF/sfinfill.html infill]
* Testing forward interpolation in 1-D: [http://reproducibility.org/RSF/sfinttest1.html inttest1]
* Testing forward interpolation in 2-D: [http://reproducibility.org/RSF/sfinttest2.html inttest2]
* Missing data interpolation in 2-D by Laplacian regularization: [http://reproducibility.org/RSF/sflapfill.html lapfill]
* Missing data interpolation using one or two prediction-error filters: [http://reproducibility.org/RSF/sfmaskinv.html maskinv]
* Missing data interpolation in 2-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanemis2.html planemis2]
* Missing data interpolation in 3-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanemis3.html planemis3]
* Missing data interpolation in 2-D using plane-wave destruction and shaping regularization: [http://reproducibility.org/RSF/sfpmshape2.html pmshape2]

=Classic preprocessing=
Excludes: (1) denoising; (2) moveouts/stretches, and (3) interpolations, which will get their own sections.
* Stretch of the time axis: [[Guide_to_madagascar_programs#sfstretch | stretch guide]], [http://reproducibility.org/RSF/sfstretch.html stretch]
* Amplitude balancing: [http://reproducibility.org/RSF/sfabalance.html abalance]
* Compute data envelope: [http://reproducibility.org/RSF/sfenvelope.html envelope]
* Automatic gain control: [http://reproducibility.org/RSF/sfagc.html agc]
* Bandpass filtering: [http://reproducibility.org/RSF/sfbandpass.html bandpass]
* Bandpass filtering using erf function: [http://reproducibility.org/RSF/sferf.html erf]
* Deconvolution (N-dimensional): [http://reproducibility.org/RSF/sfdecon.html decon]
* 1-D convolution: [http://reproducibility.org/RSF/sfconv.html conv]
* Dip filtering (2-D or 3-D): [http://reproducibility.org/RSF/sfdipfilter.html dipfilter]
* Muting: [http://reproducibility.org/RSF/sfmutter.html mutter]
* Stack a dataset over one of the dimensions: [http://reproducibility.org/RSF/sfstack.html stack]
* Time power gain: [http://reproducibility.org/RSF/sftpow.html tpow]
* Frequency spectra: [http://reproducibility.org/RSF/sfspectra.html spectra]
* Frequency spectra in 2-D: [http://reproducibility.org/RSF/sfspectra2.html spectra2]
* Static correction: [http://reproducibility.org/RSF/sfstretch.html datstretch]. Use the the <tt>datum=</tt> parameter to specify file holding time shifts.

=Wavelet estimation=
* Mono-frequency wavelet estimation: [http://reproducibility.org/RSF/sfmonof.html monof]
* Gaussian wavelet estimation in 2-D: [http://reproducibility.org/RSF/sfmonof2.html monof2]
* Ricker wavelet estimation: [http://reproducibility.org/RSF/sfricker.html ricker]

=Denoising/S-N separation=
* Denoising using stationary wavelet transform: [http://reproducibility.org/RSF/sfswtdenoise.html swtdenoise]
* Remove bursty noise by IRLS: [http://reproducibility.org/RSF/sfdeburst.html deburst]
* Burst noise removal using PEF: [http://reproducibility.org/RSF/sfpefdeburst.html pefdeburst]
* Remove spikes in by sliding 1-D medians: [http://reproducibility.org/RSF/sfdespike.html despike]
* Remove spikes in by sliding 2-D medians: [http://reproducibility.org/RSF/sfdespike2.html despike2]
* Remove spikes in by sliding 3-D medians: [http://reproducibility.org/RSF/sfdespike3.html despike3]
* Signal and noise separation (N-dimensional): [http://reproducibility.org/RSF/sfsignoi.html signoi]
* Local signal and noise separation (N-dimensional): [http://reproducibility.org/RSF/sflosignoi.html losignoi]
* Signal and noise separation using plane-wave destruction filters: [http://reproducibility.org/RSF/sfplanesignoi.html planesignoi]
* Signal and noise separation using both frequency components and dips: [http://reproducibility.org/RSF/sfexplanesignoi.html explanesignoi]
* Signal and noise separation using frequency components: [http://reproducibility.org/RSF/sfexpsignoi.html expsignoi]

=Tracewise stretch/moveout operators=
These operators do not carry energy from one trace to the other. The operation can be performed independently on each trace.
* General stretch of the time axis: [http://reproducibility.org/RSF/sfstretch.html stretch]
* Constant-velocity Normal Moveout stretch: [http://reproducibility.org/RSF/sfstretch.html nmostretch]
* Linear Moveout stretch: [http://reproducibility.org/RSF/sfstretch.html lmostretch]
* Log stretch: [http://reproducibility.org/RSF/sfstretch.html logstretch]
* T-square stretch: [http://reproducibility.org/RSF/sfstretch.html t2stretch]
* T-square Chebyshev stretch: [http://reproducibility.org/RSF/sfstretch.html t2chebstretch]
* Radial moveout: [http://reproducibility.org/RSF/sfstretch.html radstretch]
* Datuming stretch: [http://reproducibility.org/RSF/sfstretch.html datstretch]
* Normal moveout: [http://reproducibility.org/RSF/sfnmo.html nmo]
* Inverse normal moveout: [http://reproducibility.org/RSF/sfinmo.html inmo]
* Constant-velocity nearest-neighbor inverse NMO: [http://reproducibility.org/RSF/sfimospray.html imospray]
* Normal moveout in tau-p domain: [http://reproducibility.org/RSF/sftaupmo.html taupmo]
* Slope-based normal moveout: [http://reproducibility.org/RSF/sfpnmo.html pnmo]

=DMO/AMO/Offset continuation=
* Kirchhoff DMO with antialiasing by reparameterization: [http://reproducibility.org/RSF/sfdmo.html dmo]
* Azimuth moveout by log-stretch F-K operator: [http://reproducibility.org/RSF/sffkamo.html fkamo]
* Offset continuation by log-stretch F-K operator: [http://reproducibility.org/RSF/sffkdmo.html fkdmo]
* Offset continuation by finite differences: [http://reproducibility.org/RSF/sffincon.html fincon]
* DMO and stack by finite-difference offset continuation: [http://reproducibility.org/RSF/sffinstack.html finstack]

=Whole-image stretching=
* Stolt stretch: [http://reproducibility.org/RSF/sfstoltstretch.html stoltstretch]
* Cartesian-Coordinates to Riemannian-Coordinates interpolation: [http://reproducibility.org/RSF/sfc2r.html c2r]

=Autopicking=
* Automatic picking from semblance-like panels: [http://reproducibility.org/RSF/sfpick.html pick], [http://reproducibility.org/RSF/sfpick2.html pick2]
* Generate stereopicks from time-migration velocities and slopes: [http://reproducibility.org/RSF/sfpgen.html pgen]
* Generate stereotomography picks from time migration: [http://reproducibility.org/RSF/sfspicks.html spicks]
* Picking local maxima on the first axis: [http://reproducibility.org/RSF/sfmax1.html max1]
* Picking by plane-wave construction: [http://reproducibility.org/RSF/sfpwpick.html pwpick]
* Preconditioning for traveltime picking: [http://reproducibility.org/RSF/sfshearer.html shearer]

=Velocity analysis=
* Velocity transform: [http://reproducibility.org/RSF/sfvelmod.html velmod]
* Slope-based velocity transform: [http://reproducibility.org/RSF/sfpveltran.html pveltran]
* Hyperbolic Radon transform: [http://reproducibility.org/RSF/sfveltran.html veltran]
* Hyperbolic Radon transform with conjugate-directions inversion: [http://reproducibility.org/RSF/sfcgscan.html cgscan]
* Velocity analysis: [http://reproducibility.org/RSF/sfvscan.html vscan]
* 3-D zero-offset WEMVA: [http://reproducibility.org/RSF/sfzomva.html zomva]
* 3-D S/R WEMVA with extended split-step: [http://reproducibility.org/RSF/sfsrmva.html srmva]
* Simple tomography test: [http://reproducibility.org/RSF/sftomo.html tomo]

=Velocity continuation=
* Post-stack 2-D velocity continuation by Chebyshev-tau method: [http://reproducibility.org/RSF/sfchebvc.html chebvc]
* Velocity continuation: [http://reproducibility.org/RSF/sffourvc.html fourvc]
* Velocity continuation after NMO: [http://reproducibility.org/RSF/sffourvc0.html fourvc0]
* Velocity continuation with semblance computation: [http://reproducibility.org/RSF/sffourvc2.html fourvc2]
* Post-stack velocity continuation by implicit finite differences: [http://reproducibility.org/RSF/sfvelcon.html velcon]
* 3-D finite-difference velocity continuation on a helix: [http://reproducibility.org/RSF/sfvelcon3.html velcon3]

=Velocity and data converters=
* Convert RMS to interval velocity: [http://reproducibility.org/RSF/sfdix.html dix]
* Convert RMS to interval velocity using LS and shaping regularization: [http://reproducibility.org/RSF/sfdixshape.html dixshape]
* V(t) function for a linear V(Z) profile: [http://reproducibility.org/RSF/sfvoft.html voft]
* Conversion from depth to time in a V(z) medium: [http://reproducibility.org/RSF/sfdepth2time.html depth2time]
* Time-to-depth conversion in V(z): [http://reproducibility.org/RSF/sftime2depth.html time2depth]
* Convert RMS to interval velocity using LS and plane-wave construction: [http://reproducibility.org/RSF/sfpwdix.html pwdix]

=Ray tracing=
The programs below take as input a velocity model and output ray trajectories.
==2-D, v(x,z)==
* Huygens wavefront tracing: [http://reproducibility.org/RSF/sfhwt2d.html hwt2d]
* For layered media: [http://reproducibility.org/RSF/sflayer.html layer]
* Second-order cell ray tracing with locally parabolic rays: [http://reproducibility.org/RSF/sfcell2.html cell2].
* Ray tracing by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2.html rays2]
==2-D, v(x,z), anisotropic media==
* Ray tracing in VTI media by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2a.html rays2a]
==2-D, v(x,z), multiples==
* By cell ray tracing: [http://reproducibility.org/RSF/sftrace2.html trace2]

== Plotting ==

* Plot rays: [http://reproducibility.org/RSF/sfplotrays.html plotrays]
* Plot rays in 3D with OpenGL: [http://reproducibility.org/RSF/sfplotrays3.html plotsray3]

=Traveltimes computation=
* Analytical traveltime in 2-D, linear v(z): [http://reproducibility.org/RSF/sfvofz.html vofz]
* Huygens wavefront tracing (ray-based method): [http://reproducibility.org/RSF/sfhwtex.html hwtex], [http://reproducibility.org/RSF/sfhwt2d.html hwt2d]

=Modeling=
All methods below deal with acoustic data, unless noted otherwise. Also, to be in the modeling section, a program/chain of programs must produce actual seismograms, not just traveltime curves. Those go into the "Traveltime computation" section.

Programs listed below create time-domain seismic data (wavefield at z=0, i.e. hyperbolas) given a reflectivity model (wavefield at t=0 in the exploding reflector paradigm). Sometimes it is suggestive to plot "shots", i.e. one or several wavefronts at various times. One way to do it with downward-continuation based shot-modeling algorithm is to save the whole wavefield in the time domain, then to extract the slices at the appropriate times. This can get storage-intensive, and slow as it can be IO-bound. Another way is to use a reverse-time procedure and simply save the appropriate time snapshots. This is very CPU-intensive and artifacts can easily appear. The cheapest and the most elegant way is to remember that a wavefront at time t originating from a shot is indistinguishable from the migration impulse response of a spike at time t at the same x location. So to originate a series of wavefronts at intervals dt from a shot at location x and time t, one just has to migrate a sequence of spikes separated by dt at location x. This way, any of the programs in the "migration" section can also be used to create "shots" – including those programs based on survey-sinking!

==Creating reflectivity models==
* For linear arrivals: [http://reproducibility.org/RSF/sfspike.html spike], followed by [http://reproducibility.org/RSF/sfbandpass.html bandpass] or convolution ([http://reproducibility.org/RSF/sfconv.html conv]) with a wavelet
* Simple 2-D synthetics with crossing plane waves: [http://reproducibility.org/RSF/sfmake.html make]
* Generates the 3-D Qdome model: [http://reproducibility.org/RSF/sfqdome.html qdome]
* Generates the 2-D Sigmoid model: [http://reproducibility.org/RSF/sfsigmoid.html sigmoid]
* Generates the 2-D Synmarine model, spreads it across offsets and applies moveout: [http://reproducibility.org/RSF/sfsynmarine.html synmarine] (bandpass or convolution with a wavelet still needed)
* Generates the 2-D Conflicting Dips model: [http://reproducibility.org/RSF/sfconflict.html conflict]
* Simple synthetics with random reflectivity: [http://reproducibility.org/RSF/sfrandrefl.html randrefl]

==Adding noise==
* Synthetics with bursts of noise: [http://reproducibility.org/RSF/sfburstnoise.html burstnoise]
* Add random noise to the data: [http://reproducibility.org/RSF/sfnoise.html noise]

==Creating falsely irregular data==
* Cut an elliptic hole in data: [http://reproducibility.org/RSF/sfhole.html hole]
* Remove random shot gathers from a 2-D dataset: [http://reproducibility.org/RSF/sfshotholes.html shotholes]

==Creating velocity models==
* Generate 2-D layered velocity model from specified interfaces: [http://reproducibility.org/RSF/sfunif2.html unif2]
* Generate 3-D layered velocity model from specified interfaces: [http://reproducibility.org/RSF/sfunif3.html unif3]

==3-D, prestack, v(x,z)==
* Extended split step wavefield extrapolation method: [http://reproducibility.org/RSF/sfsrmod.html srmod]
==3-D, prestack, common-azimuth, v(x,z)==
* Split-step method: [http://reproducibility.org/RSF/sfcamig.html camig]
==3-D, prestack, v(z)==
* Kirchhoff method using analytical Green's functions: [http://reproducibility.org/RSF/sfkirmod3.html kirmod3]
==3-D, zero-offset, v(x,z)==
* Extended split step wavefield extrapolation method: [http://reproducibility.org/RSF/sfsstep2.html sstep2], [http://reproducibility.org/RSF/sfzomig.html zomig]
==3-D, zero-offset, const.v==
* Stolt (F-K) method: [http://reproducibility.org/RSF/sfstolt.html stolt]
==2.5-D, v(z)==
* Kirchhoff method using analytical Green's functions: [http://reproducibility.org/RSF/sfkirmod.html kirmod]
==2-D, prestack, v(x,z)==
* Unknown ray-based method: [http://reproducibility.org/RSF/sfshoot2.html shoot2]
* Second-order cell ray tracing with locally parabolic rays: [http://reproducibility.org/RSF/sfcell2.html cell2].
* Ray tracing by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2.html rays2]
* Time-domain acoustic FD: [http://reproducibility.org/RSF/sfafmod.html afmod], [http://reproducibility.org/RSF/sfawe.html awe], [http://reproducibility.org/RSF/sfawefd.html awefd], [http://reproducibility.org/RSF/sfawefd1.html awefd1], [http://reproducibility.org/RSF/sfafdm2d.html afdm2d]
* Time-domain acoustic linearized FD: [http://reproducibility.org/RSF/sflwefd.html lwefd], [http://reproducibility.org/RSF/sflwefd1.html lwefd1]
* DSR-based survey-continuation WE method: [http://reproducibility.org/RSF/sfdsr2.html dsr2]
==2-D, prestack, v(x,z), anisotropic media==
* Ray tracing in VTI media by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2a.html rays2a]
==2-D, prestack, v(z)==
* DSR-based survey-continuation WE method: [http://reproducibility.org/RSF/sfdsr.html dsr]
* [http://reproducibility.org/RSF/sfspike.html spike], [http://reproducibility.org/RSF/sfbandpass.html bandpass], [http://reproducibility.org/RSF/sfinmo.html inmo]
* Analytical traveltime in a linear slowness squared model: [http://reproducibility.org/RSF/sfs2ofz.html s2ofz]

==2-D, prestack, const. v==
* Kirchhoff: [http://reproducibility.org/RSF/sfpreconstkirch.html preconstkirch]
* Stolt (F-K): [http://reproducibility.org/RSF/sfprestolt.html prestolt]
==2-D, zero-offset, v(x,z)==
* Implicit finite-difference method, 15 and 45 degree approximation: [http://reproducibility.org/RSF/sfmig45.html mig45]
* Riemannian Wavefield Extrapolation: [http://reproducibility.org/RSF/sfrwezomig.html rwezomig]
==2-D, zero-offset, v(z)==
* Wavefield-extrapolation, phase-shift method: [http://reproducibility.org/RSF/sfgazdag.html gazdag]
* Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfkirchnew.html kirchnew]
* 1-D convolution modeling: [http://reproducibility.org/RSF/sfai2refl.html ai2refl]

==Elastic modeling==
* Time-domain 2-D FD method: [http://reproducibility.org/RSF/sfewefd2d.html ewefd2d]
==Anisotropic modeling==
* Time-domain 2-D FD TTI: [http://reproducibility.org/RSF/sfewefd2dtti.html ewefd2dtti]
* [http://reproducibility.org/RSF/sfanifd2d.html anifd2d]

==Unconventional outputs==
* Models PP intercept, PP gradient and PS gradient directly: [http://reproducibility.org/RSF/sfmodrefl2.html modrefl2]
* Outputs PP and PS seismograms in the tau-p domain: [http://reproducibility.org/RSF/sfmodrefl3.html modrefl3]
==Uncertain==
* [http://reproducibility.org/RSF/sfmodrefl.html modrefl] ("Normal reflectivity modeling", according to <tt>sfdoc -k</tt>). Takes as input files with vp, vs and rho, but it is not clear whether it outputs a 2-D or 3-D file, and if modeling is with ray or WE methods.
* 2-D, unknown if prestack or zero-offset, v(x,z), Born modeling: [http://reproducibility.org/RSF/sfaborn.html aborn], [http://reproducibility.org/RSF/sfborn2d.html born2d]

=Migration=

Below, "v(x,z)" means "works when the velocity has lateral velocity variations, and will try to do something about them". This corresponds to what is widely called depth migration, but possibly to "smart" time migrations as well. The "const. v" term will be applied to algorithms that can only deal with constant velocity, regardless of whether the output is in depth or time. The "v(z)" term describes all other migrations. Note that the above terms apply even to migrations that do not need a velocity model!

It is assumed that a 3-D prestack algorithm will be able to migrate a 2-D prestack or a 3-D poststack, that a v(x,z) will be able to deal with a constant-velocity case, and so on. Exceptions to these rules will be highlighted.

The term "survey-sinking" was preferred to "source-receiver" because it can be done in either midpoint-offset, or in source-receiver coordinates, and the two differ in their treatment of amplitudes (a CMP gather is not a wavefield).

==3-D, prestack, wide-azimuth, v(x,z)==
*Survey-sinking scheme in midpoint-offset coordinates with extended split-step extrapolator: [http://reproducibility.org/RSF/sfsrmig.html srmig], [http://reproducibility.org/RSF/sfsrmig2.html srmig2]

==3-D, prestack, common-azimuth, v(x,z)==
*Extended split-step extrapolator: [http://reproducibility.org/RSF/sfcamig.html camig]

==3-D, prestack, one-azimuth, const. v==
The "one-azimuth" term was employed to underline that they take as input 3-D data with a single offset dimension, but they do not employ the common-azimuth approximation<ref>Biondi, B., and Palacharla, G.: 3-D prestack migration of common-azimuth data, Geophysics, v. 61, pp. 1822-1832.</ref> when computing ky.
*F-K scheme: [http://reproducibility.org/RSF/sfprestolt.html prestolt]
*Kirchhoff scheme: [http://reproducibility.org/RSF/sfpreconstkirch.html preconstkirch]

==3-D, poststack, v(x,z)==
*Extended split-step extrapolator: [http://reproducibility.org/RSF/sfsstep2.html sstep2], [http://reproducibility.org/RSF/sfzomig.html zomig]

==3-D, poststack, const. v==
*F-K scheme: [http://reproducibility.org/RSF/sfstolt.html stolt], with impulse response examples in <tt>sep/forwd</tt>
*Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfmig3.html mig3], [http://reproducibility.org/RSF/sfmigsteep3.html migsteep3]

==2-D, prestack, v(x,z)==
*Survey-sinking scheme in midpoint-offset coordinates with PSPI extrapolator: [http://reproducibility.org/RSF/sfdsr.html dsr]
*Survey-sinking scheme in midpoint-offset coordinates with split-step extrapolator: [http://reproducibility.org/RSF/sfdsr2.html dsr2]
*Shot-profile scheme, Riemannian extrapolator: [http://reproducibility.org/RSF/sfrwe2d.html rwe2d], [http://reproducibility.org/RSF/sfrwesrmig.html rwesrmig]

==2-D, prestack, v(z)==
*Slope-based migration: [http://reproducibility.org/RSF/sfpmig.html pmig]

==2-D, prestack, const. v==
*Angle-gather migration: [http://reproducibility.org/RSF/sfagmig.html agmig]

==2-D, poststack, v(x,z)==
*Implicit finite-difference extrapolator, 15 and 45 degree approximations: [http://reproducibility.org/RSF/sfmig45.html mig45]
*Riemannian extrapolator: [http://reproducibility.org/RSF/sfrwezomig.html rwezomig]

==2-D, poststack, v(z)==
*Phase-shift extrapolator: [http://reproducibility.org/RSF/sfgazdag.html gazdag]
*Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfkirchnew.html kirchnew]
*Least-squares Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfkirchinv.html kirchinv]

==2-D, poststack, const. v==
*Implicit finite-difference extrapolator: [http://reproducibility.org/RSF/sfconstfdmig2.html constfdmig2]

==Migration without a velocity model==
*Slope-based 2-D prestack migration, works in v(z) media: [http://reproducibility.org/RSF/sfpmig.html pmig]

==Least-squares migration==
*Kirchhoff, 2-D, post-stack, v(z), with antialiasing: [http://reproducibility.org/RSF/sfkirchinv.html kirchinv]

=Image Cosmetics=
* Automatic gain control: [http://reproducibility.org/RSF/sfagc.html agc]
* Image enhancement by histogram equalization: [http://reproducibility.org/RSF/sfequal.html equal]
* Non-stationary spectral balancing: [http://reproducibility.org/RSF/sfreshape.html reshape]

=Angle gathers=
* Transform from offset-domain common image gathers (ODCIGs) to angle-domain common image gathers: [http://reproducibility.org/RSF/sfradon.html radon], followed by arctangent stretch and conversion from radians to degrees
* Illustration of angle gathers: [http://reproducibility.org/RSF/sfangle.html angle]
* Another illustration of angle gathers: [http://reproducibility.org/RSF/sfangle2.html angle2]
* Transform PP angle gathers to PS angle gathers: [http://reproducibility.org/RSF/sfpp2psang2.html pp2psang2]
* Transform PP angle gathers to PS angle gathers: [http://reproducibility.org/RSF/sfpp2psang.html pp2psang]
* Compute angle gathers for time-shift imaging condition: [http://reproducibility.org/RSF/sfpp2pstsic.html pp2pstsic]
* Apply dip correction for angle-gathers computed with absolute offset: [http://reproducibility.org/RSF/sfabsoffdip.html absoffdip]
* Compute angle gathers for time-shift imaging condition: [http://reproducibility.org/RSF/sftshift.html tshift]

=Dip estimation=
* Estimate a number of constant dips using plane-wave destruction: [http://reproducibility.org/RSF/sfdips.html dips]
* 3-D dip estimation by plane wave destruction: [http://reproducibility.org/RSF/sfdip.html dip]
* 2-D two dip estimation by plane wave destruction: [http://reproducibility.org/RSF/sftwodip2.html twodip2]

=Attribute extraction=
* Compute intercept and gradient by least squares: [http://reproducibility.org/RSF/sfavo.html avo]
* Smooth estimate of instantaneous frequency: [http://reproducibility.org/RSF/sfiphase.html iphase]
* Canny-like edge detector: [http://reproducibility.org/RSF/sfcanny.html canny]
=Horizon extraction=
* Extract horizons from data: [http://reproducibility.org/RSF/sfhslice.html hslice]
* Extract a slice using picked surface (usually from a stack or a semblance): [http://reproducibility.org/RSF/sfslice.html slice]

=Directional wavefields methods=
These algorithms create or use directional wavefields at the surface or in depth. The most-known variety is tau-p, aka p-tau, aka slant stack, aka Linear Radon Transform, aka plane-wave synthesis, aka delayed-shot survey generation, aka Controlled Directional Reception (CDR), aka Controlled Directional Source, aka beam forming, aka plane-wave decomposition. Various people mean various things by these terms, with some agreement that "slant stack" is reserved to more simple flavor of the operation, "plane-wave decomposition" is the more carefully thought one trying to take care of the amplitudes, and CDR refers to shorter cable lengths. The various flavors of beam methods are good cousins of these approaches.
* Time-space-domain slant stack with antialiasing and a rho filter: [http://reproducibility.org/RSF/sfslant.html slant]
* High-resolution Linear Radon Transform: [http://reproducibility.org/RSF/sfradon.html radon]. Inversion approach trying to maximize spikes in the tau-p domain, and filter out other events, including elliptical ones (you may not want to use this for creating inputs to methods that work with ellipses in the tau-p domain!)
* Modeling that outputs PP and PS seismograms in the tau-p domain: [http://reproducibility.org/RSF/sfmodrefl3.html modrefl3]
* Normal moveout in tau-p domain: [http://reproducibility.org/RSF/sftaupmo.html taupmo]
* Diffraction imaging in the plane-wave domain: [http://reproducibility.org/RSF/sfdimag.html dimag]

=Transforms=
* Time-space-domain slant stack with antialiasing and a rho filter: [http://reproducibility.org/RSF/sfslant.html slant]
* High-resolution Linear Radon Transform: [http://reproducibility.org/RSF/sfradon.html radon]. Inversion approach trying to maximize spikes in the tau-p domain, and filter out other events, including elliptical ones (you may not want to use this for creating inputs to methods that work with ellipses in the tau-p domain!)
* Parabolic Radon Transform: [http://reproducibility.org/RSF/sfradon.html radon] with <tt>parab=y</tt>
* Hyperbolic Radon Transform: [http://reproducibility.org/RSF/sfveltran.html veltran]
* Hyperbolic Radon Transform with conjugate-directions inversion: [http://reproducibility.org/RSF/sfcgscan.html cgscan]
* Phase-space Radon transform: [http://reproducibility.org/RSF/sfpradon.html pradon]
* Radial Transform: [http://reproducibility.org/RSF/sfradial.html radial]
* FFT along the first axis: [http://reproducibility.org/RSF/sffft1.html fft1]
* FFT: [http://reproducibility.org/RSF/sffft3.html fft3]
* Frequency spectra: [http://reproducibility.org/RSF/sfspectra.html spectra]
* Frequency spectra in 2-D: [http://reproducibility.org/RSF/sfspectra2.html spectra2]
* 1-D Digital Wavelet Transform: [http://reproducibility.org/RSF/sfdwt.html dwt]
* Multi-dimensional cosine transform: [http://reproducibility.org/RSF/sfcosft.html cosft]
* Seislet transform: [http://reproducibility.org/RSF/sfseislet.html seislet]
* Freqlet transform: [http://reproducibility.org/RSF/sffreqlet.html freqlet]

=Smoothers and rougheners=
* 2-D smoothing by triangle plane-wave construction shaping: [http://reproducibility.org/RSF/sfpwdsmooth2.html pwdsmooth2]
* Recursive Gaussian smoothing on the fast axis: [http://reproducibility.org/RSF/sfgaussmooth.html gaussmooth]
* Smooth first derivative on the first axis: [http://reproducibility.org/RSF/sfsmoothder.html smoothder]
* Multi-dimensional triangle smoothing: [http://reproducibility.org/RSF/sfsmooth.html smooth]
* Smoothing in 2-D by simple regularization: [http://reproducibility.org/RSF/sfsmoothreg2.html smoothreg2]
* Smoothing in 1-D by simple regularization: [http://reproducibility.org/RSF/sfsmoothreg.html smoothreg]
* First derivative with a maximally linear FIR differentiator: [http://reproducibility.org/RSF/sfderiv.html deriv]
* 2-D smooth gradient: [http://reproducibility.org/RSF/sfgrad2.html grad2]
* Gradient on the first axis: [http://reproducibility.org/RSF/sfigrad.html igrad]
* Apply 2-D directional high-pass to highlight data: [http://reproducibility.org/RSF/sflight.html light]
* 1-D non-stationary smoothing: [http://reproducibility.org/RSF/sfnsmooth1.html nsmooth1]
* N-D non-stationary smoothing: [http://reproducibility.org/RSF/sfnsmooth.html nsmooth]
* Multi-dimensional smoothing with boxes: [http://reproducibility.org/RSF/sfboxsmooth.html boxsmooth]
* Half-order integration or differentiation: [http://reproducibility.org/RSF/sfhalfint.html halfint]
* 2-D smoothing by triangle directional shaping: [http://reproducibility.org/RSF/sftrismooth2.html trismooth2]

=Programs yet to be classified=
* [http://reproducibility.org/RSF/sfaliasp.html aliasp]: Aliasing test
* [http://reproducibility.org/RSF/sfapprox.html approx]: Illustrating non-hyperbolic approximations
* [http://reproducibility.org/RSF/sfautocorr.html autocorr]: Autocorrelation for helix filters
* [http://reproducibility.org/RSF/sfcflow.html cflow]: Fast mean-curvature flow
* [http://reproducibility.org/RSF/sfcostaper.html costaper]: Cosine taper around the borders (N-D)
* [http://reproducibility.org/RSF/sfcube2list.html cube2list]: Maps a cube to a list, given a threshold (clip value)
* [http://reproducibility.org/RSF/sfdeblur.html deblur]: Non-stationary debluring by inversion
* [http://reproducibility.org/RSF/sfdijkstra.html dijkstra]: Dijkstra shortest-path algorithm in 2-D
* [http://reproducibility.org/RSF/sfdiplet.html diplet]: Seislet frame
* [http://reproducibility.org/RSF/sfdistance.html distance]: Computing distance function by fast marching eikonal solver (3-D)
* [http://reproducibility.org/RSF/sfdivn.html divn]: Smooth division
* [http://reproducibility.org/RSF/sfeikonal.html eikonal]: Fast marching eikonal solver (3-D)
* [http://reproducibility.org/RSF/sfeikonalvti.html eikonalvti]: Fast marching eikonal solver in VTI media
* [http://reproducibility.org/RSF/sferfdm.html erfdm]
* [http://reproducibility.org/RSF/sfexgr.html exgr]: Exact group velocity in VTI media
* [http://reproducibility.org/RSF/sfextract.html extract]: Forward interpolation in 2-D slices
* [http://reproducibility.org/RSF/sfflat3.html flat3]: 3-D flattening (without picking)
* [http://reproducibility.org/RSF/sfflat.html flat]: Moveout flattening
* [http://reproducibility.org/RSF/sffocus.html focus]: Focusing indicator
* [http://reproducibility.org/RSF/sfframe.html frame]: Create a frame for binning
* [http://reproducibility.org/RSF/sffreqest.html freqest]: Local frequency estimation
* [http://reproducibility.org/RSF/sfgreen.html green]: Phase-space Green's function from down-marching
* [http://reproducibility.org/RSF/sfhconv.html hconv]: Convolution of two helix filters
* [http://reproducibility.org/RSF/sfhelicon.html helicon]: Multidimensional convolution and deconvolution by helix transform
* [http://reproducibility.org/RSF/sfic.html ic]: Imaging condition
* [http://reproducibility.org/RSF/sficor.html icor]: Interferometric cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sfidempatch.html idempatch]: Patching test
* [http://reproducibility.org/RSF/sfimpl1.html impl1]: 1-D anisotropic diffusion
* [http://reproducibility.org/RSF/sfimpl2.html impl2]: 2-D anisotropic diffusion
* [http://reproducibility.org/RSF/sfimpl3.html impl3]: 3-D anisotropic diffusion
* [http://reproducibility.org/RSF/sfinterp2.html interp2]: Multiple-arrival interpolation
* [http://reproducibility.org/RSF/sfinterp3.html interp3]: Multiple-arrival interpolation from down-marching
* [http://reproducibility.org/RSF/sfinterpt.html interpt]: Multiple-arrival interpolation (yet another)
* [http://reproducibility.org/RSF/sfintshow.html intshow]: Output interpolation filter
* [http://reproducibility.org/RSF/sfkolmog.html kolmog]: Kolmogoroff spectral factorization
* [http://reproducibility.org/RSF/sflaps.html laps]: Compute lagged-products
* [http://reproducibility.org/RSF/sflinefit.html linefit]: Fit a line to a set of points in 2-D
* [http://reproducibility.org/RSF/sflopef.html lopef]: Local Prediction-Error Filter (1-D, 2-D, and 3-D)
* [http://reproducibility.org/RSF/sflpef.html lpef]: Find PEF on aliased traces
* [http://reproducibility.org/RSF/sflpf.html lpf]: Local prefiction filter (n-dimensional)
* [http://reproducibility.org/RSF/sflstk.html lstk]: Local slant stacks (2D)
* [http://reproducibility.org/RSF/sfmspef.html mspef]: Multi-scale PEF estimation
* [http://reproducibility.org/RSF/sfnhelicon.html nhelicon]: Non-stationary helix convolution and deconvolution
* [http://reproducibility.org/RSF/sfnpef.html npef]: Estimate Non-stationary PEF in N dimensions
* [http://reproducibility.org/RSF/sfocparcel.html ocparcel]: Patching test for out-of-core patching
* [http://reproducibility.org/RSF/sfoctentwt.html octentwt]: Tent-like weight for out-of-core patching
* [http://reproducibility.org/RSF/sfoff2abs3.html off2abs3]: Transform vector-offset to absolute-offset
* [http://reproducibility.org/RSF/sfoff2abs.html off2abs]: Transform vector-offset to absolute-offset
* [http://reproducibility.org/RSF/sfofpwd2.html ofpwd2]: Objective function of two dips estimation with PWD filters
* [http://reproducibility.org/RSF/sfofpwd.html ofpwd]: Objective function of dip estimation with PWD filters
* [http://reproducibility.org/RSF/sfofsemb.html ofsemb]: Objective function of dip estimation with semblance
* [http://reproducibility.org/RSF/sfparcel.html parcel]: Patching test
* [http://reproducibility.org/RSF/sfpatch.html patch]: Patching (N-dimensional)
* [http://reproducibility.org/RSF/sfpef.html pef]: Multi-dimensional PEF (prediction error filter) estimation
* [http://reproducibility.org/RSF/sfpostfilter2.html postfilter2]: Convert B-spline coefficients to data in 2-D
* [http://reproducibility.org/RSF/sfpredict.html predict]: 2-D plane-wave prediction
* [http://reproducibility.org/RSF/sfpwd.html pwd]: 3-D plane wave destruction
* [http://reproducibility.org/RSF/sfpwdsigk.html pwdsigk]: Signal component separation using plane-wave destruction
* [http://reproducibility.org/RSF/sfrefer.html refer]: Subtract a reference from a grid
* [http://reproducibility.org/RSF/sfreg2tri.html reg2tri]: Decimate a regular grid to triplets for triangulation
* [http://reproducibility.org/RSF/sfricker1.html ricker1]: Convolution with a Ricker wavelet
* [http://reproducibility.org/RSF/sfrweab.html rweab]: Riemannian Wavefield Extrapolation]:* a,b coefficients
* [http://reproducibility.org/RSF/sfrwemete2d.html rwemete2d]: 2-D metric tensor
* [http://reproducibility.org/RSF/sfseisigk.html seisigk]: Signal component separation using seislet transforms
* [http://reproducibility.org/RSF/sfshapebin1.html shapebin1]: 1-D inverse interpolation with shaping regularization
* [http://reproducibility.org/RSF/sfshapebin.html shapebin]: Data binning in 2-D slices by inverse interpolation
* [http://reproducibility.org/RSF/sfshapesigk.html shapesigk]: Signal component separation using plane-wave shaping
* [http://reproducibility.org/RSF/sfshotprop.html shotprop]: Shot propagation
* [http://reproducibility.org/RSF/sfsic3d.html sic3d]: Local slant stacks IC
* [http://reproducibility.org/RSF/sfsic.html sic]: Local slant stacks IC
* [http://reproducibility.org/RSF/sfsplinebank.html splinebank]: Prepare a filter bank for B-spline plane wave filters
* [http://reproducibility.org/RSF/sfsplinefilter.html splinefilter]: Convert data to B-spline coefficients
* [http://reproducibility.org/RSF/sfsrsyn.html srsyn]: Synthesize shot/receiver wavefields for 3-D SR migration
* [http://reproducibility.org/RSF/sftan2ang.html tan2ang]: Compute cos(theta) from 1/|pm| for time-shift imaging condition
* [http://reproducibility.org/RSF/sftcor.html tcor]: Interferometric cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sftentwt.html tentwt]: Tent-like weight for patching
* [http://reproducibility.org/RSF/sftimeshift.html timeshift]: Apply variable time shifts using plane-wave construction
* [http://reproducibility.org/RSF/sftrapez.html trapez]: Convolution with a trapezoidal filter
* [http://reproducibility.org/RSF/sftree.html tree]: Multiple arrivals with a fast algorithm
* [http://reproducibility.org/RSF/sftri2reg.html tri2reg]: Interpolate triangulated triplets to a regular grid
* [http://reproducibility.org/RSF/sftrirand.html trirand]: Edit points for triangulation by removing similar and randomizing
* [http://reproducibility.org/RSF/sftspline.html tspline]: Helix filters for spline in tension
* [http://reproducibility.org/RSF/sftwofreq2.html twofreq2]: 2-D two spectral component estimation
* [http://reproducibility.org/RSF/sfucor.html ucor]: Interferometric cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sfwarp1.html warp1]: Multicomponent data registration by 1-D warping
* [http://reproducibility.org/RSF/sfwarpadd.html warpadd]: Add a perturbation to the warping function
* [http://reproducibility.org/RSF/sfwarpscan.html warpscan]: Multicomponent data registration analysis
* [http://reproducibility.org/RSF/sfwdf.html wdf]: Assymptotic Wigner distribution
* [http://reproducibility.org/RSF/sfwigner.html wigner]: Assymptotic Wigner distribution in space-time
* [http://reproducibility.org/RSF/sfwilson.html wilson]: Wilson-Burg spectral factorization
* [http://reproducibility.org/RSF/sfxcor.html xcor]: Cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sfztrace.html ztrace]: Multiple arrivals by depth marching
* The SCons macros in <tt>RSFSRC/book/packages</tt>

=References=
<references/>

NM task-centric program program list

2011-08-06T16:28:27Z

Nick: /* Multi-file */

List of '''Numerical Methods''' programs in Madagascar. An overview of all task-centric pages can be found in the main [[Task-centric program list]].

'''All program names below should be prefixed with "sf".'''

== Operation on file content ==

* Generate simple data (spikes, boxes, planes, constants): [http://reproducibility.org/RSF/sfspike.html spike]
* Mathematical operations on data files: [http://reproducibility.org/RSF/sfmath.html math]
* Add, multiply, or divide RSF datasets: [http://reproducibility.org/RSF/sfadd.html add]
* Add, multiply, or divide RSF datasets (fast, OMP-enabled): [http://reproducibility.org/RSF/sfparadd.html paradd]
* Create a mask: [http://reproducibility.org/RSF/sfmask.html mask]
* Scale data: [http://reproducibility.org/RSF/sfscale.html scale]
* Rotate a portion of one or more axes in the data hypercube: [http://reproducibility.org/RSF/sfrotate.html rotate]
* Zero a portion of the dataset: [http://reproducibility.org/RSF/sfcut.html cut]
* Extend a dataset by duplicating in the specified axis dimension: [http://reproducibility.org/RSF/sfspray.html spray]

==Complex number operations==
* Convert real data to complex (by adding zero imaginary part): [http://reproducibility.org/RSF/sfrtoc.html rtoc]
* Extract real part of a complex dataset: [http://reproducibility.org/RSF/sfreal.html real]
* Extract imaginary part of a complex dataset: [http://reproducibility.org/RSF/sfreal.html imag]
* Create a complex dataset from its real and imaginary parts: [http://reproducibility.org/RSF/sfcmplx.html cmplx]

=Statistical operations on files=
==Single-file==
* Display dataset attributes: [http://reproducibility.org/RSF/sfattr.html attr]
* 1-D histogram: [http://reproducibility.org/RSF/sfhistogram.html histogram]
* Computes what clip value corresponds to a given pclip: [http://reproducibility.org/RSF/sfquantile.html quantile]
* Clip the data: [http://reproducibility.org/RSF/sfclip.html clip]
* One- or two-sided data clipping: [http://reproducibility.org/RSF/sfclip2.html clip2]
* Percentile clip: [http://reproducibility.org/RSF/sfpclip.html pclip]
* Threshold float/complex inputs given a constant/varying threshold level: [http://reproducibility.org/RSF/sfthr.html thr]
* Soft thresholding: [http://reproducibility.org/RSF/sfthreshold.html threshold]
* Construct incremental minimum or maximum lists from an RSF file: [http://reproducibility.org/RSF/sflistminmax.html listminmax]
* Sort a float/complex vector by absolute values: [http://reproducibility.org/RSF/sfsort.html sort]

==Multi-file==
* Element by element minimum or maximum of two RSF files: [http://reproducibility.org/RSF/sfminmax.html minmax]
* Similarity measure between two datasets: [http://reproducibility.org/RSF/sfsimilarity.html similarity]
* 2-D histogram (inputs from 2 files): [http://reproducibility.org/RSF/sfhist2.html hist2]

= Mathematics algorithms =

==Basic mathematical processes==

* Causal integration on the first axis: [http://reproducibility.org/RSF/sfcausint.html causint]
* Derivative along the first axis: [http://reproducibility.org/RSF/sfigrad.html igrad]
* Fast Fourier Transform along the first axis (from real to complex): [http://reproducibility.org/RSF/sffft1.html fft1]
* FFT transform on extra axis (from complex to complex): [http://reproducibility.org/RSF/sffft1.html fft3]
* 3D FFT with centering and Hermitian scaling: [http://reproducibility.org/RSF/sffft1.html fft3d]
* Frequency spectra: [http://reproducibility.org/RSF/sfspectra.html spectra]
* Frequency spectra in 2-D: [http://reproducibility.org/RSF/sfspectra2.html spectra2]
* 1-D Digital Wavelet Transform: [http://reproducibility.org/RSF/sfdwt.html dwt]
* Multi-dimensional cosine transform: [http://reproducibility.org/RSF/sfcosft.html cosft]

==Linear Algebra==

* Simple matrix multiplication: [http://reproducibility.org/RSF/sfmatmult.html matmult]
* Simple matrix multiplication for complex matrices: [http://reproducibility.org/RSF/sfcmatmult.html cmatmult]
* Find eigenvalues and eigenvectors of a symmetric positive definite matrix: [http://reproducibility.org/RSF/sfdmeig.html dmeig]
* Kroneker product with square matrices: [http://reproducibility.org/RSF/sfkron.html kron]
* Generic conjugate-gradient solver for linear inversion: [http://reproducibility.org/RSF/sfconjgrad.html conjgrad]
* Generic dot-product test for linear operators with adjoints: [http://reproducibility.org/RSF/sfdottest.html dottest]
* Generic conjugate-gradient solver for linear inversion with complex data: [http://reproducibility.org/RSF/sfcconjgrad.html cconjgrad]
* Generic dot-product test for complex linear operators with adjoints: [http://reproducibility.org/RSF/sfcdottest.html cdottest]
* Stack a dataset over one of the dimensions: [http://reproducibility.org/RSF/sfstack.html stack]
* Transpose two axes in a dataset: [http://reproducibility.org/RSF/sftransp.html transp]

== Interpolation ==
* 1-D ENO (Essentiallly Non Oscillatory) interpolation: [http://reproducibility.org/RSF/sfremap1.html remap1]
* 1-D sinc interpolation: [http://reproducibility.org/RSF/sfsinc.html sinc]

NM task-centric program program list

2011-08-06T16:28:01Z

Nick: /* Single-file */

List of '''Numerical Methods''' programs in Madagascar. An overview of all task-centric pages can be found in the main [[Task-centric program list]].

'''All program names below should be prefixed with "sf".'''

== Operation on file content ==

* Generate simple data (spikes, boxes, planes, constants): [http://reproducibility.org/RSF/sfspike.html spike]
* Mathematical operations on data files: [http://reproducibility.org/RSF/sfmath.html math]
* Add, multiply, or divide RSF datasets: [http://reproducibility.org/RSF/sfadd.html add]
* Add, multiply, or divide RSF datasets (fast, OMP-enabled): [http://reproducibility.org/RSF/sfparadd.html paradd]
* Create a mask: [http://reproducibility.org/RSF/sfmask.html mask]
* Scale data: [http://reproducibility.org/RSF/sfscale.html scale]
* Rotate a portion of one or more axes in the data hypercube: [http://reproducibility.org/RSF/sfrotate.html rotate]
* Zero a portion of the dataset: [http://reproducibility.org/RSF/sfcut.html cut]
* Extend a dataset by duplicating in the specified axis dimension: [http://reproducibility.org/RSF/sfspray.html spray]

==Complex number operations==
* Convert real data to complex (by adding zero imaginary part): [http://reproducibility.org/RSF/sfrtoc.html rtoc]
* Extract real part of a complex dataset: [http://reproducibility.org/RSF/sfreal.html real]
* Extract imaginary part of a complex dataset: [http://reproducibility.org/RSF/sfreal.html imag]
* Create a complex dataset from its real and imaginary parts: [http://reproducibility.org/RSF/sfcmplx.html cmplx]

=Statistical operations on files=
==Single-file==
* Display dataset attributes: [http://reproducibility.org/RSF/sfattr.html attr]
* 1-D histogram: [http://reproducibility.org/RSF/sfhistogram.html histogram]
* Computes what clip value corresponds to a given pclip: [http://reproducibility.org/RSF/sfquantile.html quantile]
* Clip the data: [http://reproducibility.org/RSF/sfclip.html clip]
* One- or two-sided data clipping: [http://reproducibility.org/RSF/sfclip2.html clip2]
* Percentile clip: [http://reproducibility.org/RSF/sfpclip.html pclip]
* Threshold float/complex inputs given a constant/varying threshold level: [http://reproducibility.org/RSF/sfthr.html thr]
* Soft thresholding: [http://reproducibility.org/RSF/sfthreshold.html threshold]
* Construct incremental minimum or maximum lists from an RSF file: [http://reproducibility.org/RSF/sflistminmax.html listminmax]
* Sort a float/complex vector by absolute values: [http://reproducibility.org/RSF/sfsort.html sort]

==Multi-file==
* Element by element minimum or maximum of two RSF files: [http://reproducibility.org/RSF/sfminmax.html minmax]
* Similarity measure between two datasets: [http://reproducibility.org/RSF/sfsimilarity.html similarity]

= Mathematics algorithms =

==Basic mathematical processes==

* Causal integration on the first axis: [http://reproducibility.org/RSF/sfcausint.html causint]
* Derivative along the first axis: [http://reproducibility.org/RSF/sfigrad.html igrad]
* Fast Fourier Transform along the first axis (from real to complex): [http://reproducibility.org/RSF/sffft1.html fft1]
* FFT transform on extra axis (from complex to complex): [http://reproducibility.org/RSF/sffft1.html fft3]
* 3D FFT with centering and Hermitian scaling: [http://reproducibility.org/RSF/sffft1.html fft3d]
* Frequency spectra: [http://reproducibility.org/RSF/sfspectra.html spectra]
* Frequency spectra in 2-D: [http://reproducibility.org/RSF/sfspectra2.html spectra2]
* 1-D Digital Wavelet Transform: [http://reproducibility.org/RSF/sfdwt.html dwt]
* Multi-dimensional cosine transform: [http://reproducibility.org/RSF/sfcosft.html cosft]

==Linear Algebra==

* Simple matrix multiplication: [http://reproducibility.org/RSF/sfmatmult.html matmult]
* Simple matrix multiplication for complex matrices: [http://reproducibility.org/RSF/sfcmatmult.html cmatmult]
* Find eigenvalues and eigenvectors of a symmetric positive definite matrix: [http://reproducibility.org/RSF/sfdmeig.html dmeig]
* Kroneker product with square matrices: [http://reproducibility.org/RSF/sfkron.html kron]
* Generic conjugate-gradient solver for linear inversion: [http://reproducibility.org/RSF/sfconjgrad.html conjgrad]
* Generic dot-product test for linear operators with adjoints: [http://reproducibility.org/RSF/sfdottest.html dottest]
* Generic conjugate-gradient solver for linear inversion with complex data: [http://reproducibility.org/RSF/sfcconjgrad.html cconjgrad]
* Generic dot-product test for complex linear operators with adjoints: [http://reproducibility.org/RSF/sfcdottest.html cdottest]
* Stack a dataset over one of the dimensions: [http://reproducibility.org/RSF/sfstack.html stack]
* Transpose two axes in a dataset: [http://reproducibility.org/RSF/sftransp.html transp]

== Interpolation ==
* 1-D ENO (Essentiallly Non Oscillatory) interpolation: [http://reproducibility.org/RSF/sfremap1.html remap1]
* 1-D sinc interpolation: [http://reproducibility.org/RSF/sfsinc.html sinc]

Seismic task-centric program list

2011-08-06T16:25:00Z

Nick: /* Manipulating irregular datasets, regularization and sorting */

[[Image:Fotolia_369804_XS.jpg|right|]]
This page presents a list of programs for seismic processing, imaging and analysis. An overview of all task-centric pages can be found in the main [[Task-centric program list]].

The most frequent question encountered from a new user is: "Does Madagascar do [some needed process]?" The first level of classification is therefore by types of geophysical procedures. Then the classifications below try to follow's the user's workflow:
# What sort of data must be processed/imaged: 3-D, 2-D, prestack, poststack?
# If a velocity model is needed, which sort is available? A v(x,z) one, a v(z) or a constant velocity?
# Which algorithm to use if several are available.

'''All program names below should be prefixed with "sf".'''

=Manipulating irregular datasets, regularization and sorting=
* Integer header attributes: [http://reproducibility.org/RSF/sfheaderattr.html headerattr]
* Zero a portion of a dataset based on a header mask: [http://reproducibility.org/RSF/sfheadercut.html headercut]
* Mathematical operations, possibly on header keys: [http://reproducibility.org/RSF/sfheadermath.html headermath]
* Sort a dataset according to a header key: [http://reproducibility.org/RSF/sfheadersort.html headersort]
* Window a dataset based on a header mask: [http://reproducibility.org/RSF/sfheaderwindow.html headerwindow]
* Create a mask: [http://reproducibility.org/RSF/sfmask.html mask]
* Shot interpolation: [http://reproducibility.org/RSF/sfinfill.html infill]
* Data binning (geometry regularization): [http://reproducibility.org/RSF/sfintbin.html intbin] (works especially for basically regular geometries but with skipped or resorted traces)
* Data binning in 1-D slices: [http://reproducibility.org/RSF/sfbin1.html bin1]
* Data binning in 2-D slices: [http://reproducibility.org/RSF/sfbin.html bin]
* Data regularization in 2-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanereg2.html planereg2]
* Data regularization in 3-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanereg3.html planereg3]
* Convert CMPs to shots for regular 2-D geometry: [http://reproducibility.org/RSF/sfcmp2shot.html cmp2shot]
* Convert shots to CMPs for regular 2-D geometry: [http://reproducibility.org/RSF/sfshot2cmp.html shot2cmp]
* 2-D fold maps: [http://ahay.org/RSF/sfhist2.html hist2]

=Interpolation tools=
==Making holes==
* Cut an elliptic hole in data (for interpolation tests): [http://reproducibility.org/RSF/sfhole.html hole]
* Create a synthetic irregular dataset for interpolation tests: [http://reproducibility.org/RSF/sfsyntop.html syntop]
==Actual interpolation==
* Linear interpolation: [http://reproducibility.org/RSF/sflint1.html lint1]
* 1-D cubic spline interpolation: [http://reproducibility.org/RSF/sfspline.html spline]
* Data interpolation in 2-D slices using helix preconditioning: [http://reproducibility.org/RSF/sfinvbin.html invbin]
* 1-D inverse interpolation: [http://reproducibility.org/RSF/sfinvbin1.html invbin1]
* Leveler inverse interpolation in 1-D: [http://reproducibility.org/RSF/sflevint.html levint]
* Find MISSing Input values and Filter in 1-D: [http://reproducibility.org/RSF/sfmisif.html misif]
* Missing data interpolation in 1-D: [http://reproducibility.org/RSF/sfmiss1.html miss1]
* 2-D missing data interpolation: [http://reproducibility.org/RSF/sfmiss2.html miss2]
* Missing data interpolation (N-dimensional) using shaping regularization: [http://reproducibility.org/RSF/sfmiss3.html miss3]
* Multi-dimensional missing data interpolation: [http://reproducibility.org/RSF/sfmiss.html miss]
* Multiscale missing data interpolation (N-dimensional): [http://reproducibility.org/RSF/sfmsmiss.html msmiss]
* 2-D missing data interpolation by differential offset continuation: [http://reproducibility.org/RSF/sfofilp.html ofilp]
* 1-D ENO (Essentially Non Oscillatory) interpolation: [http://reproducibility.org/RSF/sfremap1.html remap1]
* ENO interpolation in 2-D slices: [http://reproducibility.org/RSF/sfenoint2.html enoint2]
* 2-D trace interpolation to a denser grid using PWD ("beyond aliasing" method): [http://reproducibility.org/RSF/sfdealias.html dealias]
* Shot interpolation: [http://reproducibility.org/RSF/sfinfill.html infill]
* Testing forward interpolation in 1-D: [http://reproducibility.org/RSF/sfinttest1.html inttest1]
* Testing forward interpolation in 2-D: [http://reproducibility.org/RSF/sfinttest2.html inttest2]
* Missing data interpolation in 2-D by Laplacian regularization: [http://reproducibility.org/RSF/sflapfill.html lapfill]
* Missing data interpolation using one or two prediction-error filters: [http://reproducibility.org/RSF/sfmaskinv.html maskinv]
* Missing data interpolation in 2-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanemis2.html planemis2]
* Missing data interpolation in 3-D using plane-wave destruction: [http://reproducibility.org/RSF/sfplanemis3.html planemis3]
* Missing data interpolation in 2-D using plane-wave destruction and shaping regularization: [http://reproducibility.org/RSF/sfpmshape2.html pmshape2]

=Classic preprocessing=
Excludes: (1) denoising; (2) moveouts/stretches, and (3) interpolations, which will get their own sections.
* Stretch of the time axis: [[Guide_to_madagascar_programs#sfstretch | stretch guide]], [http://reproducibility.org/RSF/sfstretch.html stretch]
* Amplitude balancing: [http://reproducibility.org/RSF/sfabalance.html abalance]
* Compute data envelope: [http://reproducibility.org/RSF/sfenvelope.html envelope]
* Automatic gain control: [http://reproducibility.org/RSF/sfagc.html agc]
* Bandpass filtering: [http://reproducibility.org/RSF/sfbandpass.html bandpass]
* Bandpass filtering using erf function: [http://reproducibility.org/RSF/sferf.html erf]
* Deconvolution (N-dimensional): [http://reproducibility.org/RSF/sfdecon.html decon]
* 1-D convolution: [http://reproducibility.org/RSF/sfconv.html conv]
* Dip filtering (2-D or 3-D): [http://reproducibility.org/RSF/sfdipfilter.html dipfilter]
* Muting: [http://reproducibility.org/RSF/sfmutter.html mutter]
* Stack a dataset over one of the dimensions: [http://reproducibility.org/RSF/sfstack.html stack]
* Time power gain: [http://reproducibility.org/RSF/sftpow.html tpow]
* Frequency spectra: [http://reproducibility.org/RSF/sfspectra.html spectra]
* Frequency spectra in 2-D: [http://reproducibility.org/RSF/sfspectra2.html spectra2]
* Static correction: [http://reproducibility.org/RSF/sfstretch.html datstretch]. Use the the <tt>datum=</tt> parameter to specify file holding time shifts.

=Wavelet estimation=
* Mono-frequency wavelet estimation: [http://reproducibility.org/RSF/sfmonof.html monof]
* Gaussian wavelet estimation in 2-D: [http://reproducibility.org/RSF/sfmonof2.html monof2]
* Ricker wavelet estimation: [http://reproducibility.org/RSF/sfricker.html ricker]

=Denoising/S-N separation=
* Denoising using stationary wavelet transform: [http://reproducibility.org/RSF/sfswtdenoise.html swtdenoise]
* Remove bursty noise by IRLS: [http://reproducibility.org/RSF/sfdeburst.html deburst]
* Burst noise removal using PEF: [http://reproducibility.org/RSF/sfpefdeburst.html pefdeburst]
* Remove spikes in by sliding 1-D medians: [http://reproducibility.org/RSF/sfdespike.html despike]
* Remove spikes in by sliding 2-D medians: [http://reproducibility.org/RSF/sfdespike2.html despike2]
* Remove spikes in by sliding 3-D medians: [http://reproducibility.org/RSF/sfdespike3.html despike3]
* Signal and noise separation (N-dimensional): [http://reproducibility.org/RSF/sfsignoi.html signoi]
* Local signal and noise separation (N-dimensional): [http://reproducibility.org/RSF/sflosignoi.html losignoi]
* Signal and noise separation using plane-wave destruction filters: [http://reproducibility.org/RSF/sfplanesignoi.html planesignoi]
* Signal and noise separation using both frequency components and dips: [http://reproducibility.org/RSF/sfexplanesignoi.html explanesignoi]
* Signal and noise separation using frequency components: [http://reproducibility.org/RSF/sfexpsignoi.html expsignoi]

=Tracewise stretch/moveout operators=
These operators do not carry energy from one trace to the other. The operation can be performed independently on each trace.
* General stretch of the time axis: [http://reproducibility.org/RSF/sfstretch.html stretch]
* Constant-velocity Normal Moveout stretch: [http://reproducibility.org/RSF/sfstretch.html nmostretch]
* Linear Moveout stretch: [http://reproducibility.org/RSF/sfstretch.html lmostretch]
* Log stretch: [http://reproducibility.org/RSF/sfstretch.html logstretch]
* T-square stretch: [http://reproducibility.org/RSF/sfstretch.html t2stretch]
* T-square Chebyshev stretch: [http://reproducibility.org/RSF/sfstretch.html t2chebstretch]
* Radial moveout: [http://reproducibility.org/RSF/sfstretch.html radstretch]
* Datuming stretch: [http://reproducibility.org/RSF/sfstretch.html datstretch]
* Normal moveout: [http://reproducibility.org/RSF/sfnmo.html nmo]
* Inverse normal moveout: [http://reproducibility.org/RSF/sfinmo.html inmo]
* Constant-velocity nearest-neighbor inverse NMO: [http://reproducibility.org/RSF/sfimospray.html imospray]
* Normal moveout in tau-p domain: [http://reproducibility.org/RSF/sftaupmo.html taupmo]
* Slope-based normal moveout: [http://reproducibility.org/RSF/sfpnmo.html pnmo]

=DMO/AMO/Offset continuation=
* Kirchhoff DMO with antialiasing by reparameterization: [http://reproducibility.org/RSF/sfdmo.html dmo]
* Azimuth moveout by log-stretch F-K operator: [http://reproducibility.org/RSF/sffkamo.html fkamo]
* Offset continuation by log-stretch F-K operator: [http://reproducibility.org/RSF/sffkdmo.html fkdmo]
* Offset continuation by finite differences: [http://reproducibility.org/RSF/sffincon.html fincon]
* DMO and stack by finite-difference offset continuation: [http://reproducibility.org/RSF/sffinstack.html finstack]

=Whole-image stretching=
* Stolt stretch: [http://reproducibility.org/RSF/sfstoltstretch.html stoltstretch]
* Cartesian-Coordinates to Riemannian-Coordinates interpolation: [http://reproducibility.org/RSF/sfc2r.html c2r]

=Autopicking=
* Automatic picking from semblance-like panels: [http://reproducibility.org/RSF/sfpick.html pick], [http://reproducibility.org/RSF/sfpick2.html pick2]
* Generate stereopicks from time-migration velocities and slopes: [http://reproducibility.org/RSF/sfpgen.html pgen]
* Generate stereotomography picks from time migration: [http://reproducibility.org/RSF/sfspicks.html spicks]
* Picking local maxima on the first axis: [http://reproducibility.org/RSF/sfmax1.html max1]
* Picking by plane-wave construction: [http://reproducibility.org/RSF/sfpwpick.html pwpick]
* Preconditioning for traveltime picking: [http://reproducibility.org/RSF/sfshearer.html shearer]

=Velocity analysis=
* Velocity transform: [http://reproducibility.org/RSF/sfvelmod.html velmod]
* Slope-based velocity transform: [http://reproducibility.org/RSF/sfpveltran.html pveltran]
* Hyperbolic Radon transform: [http://reproducibility.org/RSF/sfveltran.html veltran]
* Hyperbolic Radon transform with conjugate-directions inversion: [http://reproducibility.org/RSF/sfcgscan.html cgscan]
* Velocity analysis: [http://reproducibility.org/RSF/sfvscan.html vscan]
* 3-D zero-offset WEMVA: [http://reproducibility.org/RSF/sfzomva.html zomva]
* 3-D S/R WEMVA with extended split-step: [http://reproducibility.org/RSF/sfsrmva.html srmva]
* Simple tomography test: [http://reproducibility.org/RSF/sftomo.html tomo]

=Velocity continuation=
* Post-stack 2-D velocity continuation by Chebyshev-tau method: [http://reproducibility.org/RSF/sfchebvc.html chebvc]
* Velocity continuation: [http://reproducibility.org/RSF/sffourvc.html fourvc]
* Velocity continuation after NMO: [http://reproducibility.org/RSF/sffourvc0.html fourvc0]
* Velocity continuation with semblance computation: [http://reproducibility.org/RSF/sffourvc2.html fourvc2]
* Post-stack velocity continuation by implicit finite differences: [http://reproducibility.org/RSF/sfvelcon.html velcon]
* 3-D finite-difference velocity continuation on a helix: [http://reproducibility.org/RSF/sfvelcon3.html velcon3]

=Velocity and data converters=
* Convert RMS to interval velocity: [http://reproducibility.org/RSF/sfdix.html dix]
* Convert RMS to interval velocity using LS and shaping regularization: [http://reproducibility.org/RSF/sfdixshape.html dixshape]
* V(t) function for a linear V(Z) profile: [http://reproducibility.org/RSF/sfvoft.html voft]
* Conversion from depth to time in a V(z) medium: [http://reproducibility.org/RSF/sfdepth2time.html depth2time]
* Time-to-depth conversion in V(z): [http://reproducibility.org/RSF/sftime2depth.html time2depth]
* Convert RMS to interval velocity using LS and plane-wave construction: [http://reproducibility.org/RSF/sfpwdix.html pwdix]

=Ray tracing=
The programs below take as input a velocity model and output ray trajectories.
==2-D, v(x,z)==
* Huygens wavefront tracing: [http://reproducibility.org/RSF/sfhwt2d.html hwt2d]
* For layered media: [http://reproducibility.org/RSF/sflayer.html layer]
* Second-order cell ray tracing with locally parabolic rays: [http://reproducibility.org/RSF/sfcell2.html cell2].
* Ray tracing by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2.html rays2]
==2-D, v(x,z), anisotropic media==
* Ray tracing in VTI media by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2a.html rays2a]
==2-D, v(x,z), multiples==
* By cell ray tracing: [http://reproducibility.org/RSF/sftrace2.html trace2]

== Plotting ==

* Plot rays: [http://reproducibility.org/RSF/sfplotrays.html plotrays]
* Plot rays in 3D with OpenGL: [http://reproducibility.org/RSF/sfplotrays3.html plotsray3]

=Traveltimes computation=
* Analytical traveltime in 2-D, linear v(z): [http://reproducibility.org/RSF/sfvofz.html vofz]
* Huygens wavefront tracing (ray-based method): [http://reproducibility.org/RSF/sfhwtex.html hwtex], [http://reproducibility.org/RSF/sfhwt2d.html hwt2d]

=Modeling=
All methods below deal with acoustic data, unless noted otherwise. Also, to be in the modeling section, a program/chain of programs must produce actual seismograms, not just traveltime curves. Those go into the "Traveltime computation" section.

Programs listed below create time-domain seismic data (wavefield at z=0, i.e. hyperbolas) given a reflectivity model (wavefield at t=0 in the exploding reflector paradigm). Sometimes it is suggestive to plot "shots", i.e. one or several wavefronts at various times. One way to do it with downward-continuation based shot-modeling algorithm is to save the whole wavefield in the time domain, then to extract the slices at the appropriate times. This can get storage-intensive, and slow as it can be IO-bound. Another way is to use a reverse-time procedure and simply save the appropriate time snapshots. This is very CPU-intensive and artifacts can easily appear. The cheapest and the most elegant way is to remember that a wavefront at time t originating from a shot is indistinguishable from the migration impulse response of a spike at time t at the same x location. So to originate a series of wavefronts at intervals dt from a shot at location x and time t, one just has to migrate a sequence of spikes separated by dt at location x. This way, any of the programs in the "migration" section can also be used to create "shots" – including those programs based on survey-sinking!

==Creating reflectivity models==
* For linear arrivals: [http://reproducibility.org/RSF/sfspike.html spike], followed by [http://reproducibility.org/RSF/sfbandpass.html bandpass] or convolution ([http://reproducibility.org/RSF/sfconv.html conv]) with a wavelet
* Simple 2-D synthetics with crossing plane waves: [http://reproducibility.org/RSF/sfmake.html make]
* Generates the 3-D Qdome model: [http://reproducibility.org/RSF/sfqdome.html qdome]
* Generates the 2-D Sigmoid model: [http://reproducibility.org/RSF/sfsigmoid.html sigmoid]
* Generates the 2-D Synmarine model, spreads it across offsets and applies moveout: [http://reproducibility.org/RSF/sfsynmarine.html synmarine] (bandpass or convolution with a wavelet still needed)
* Generates the 2-D Conflicting Dips model: [http://reproducibility.org/RSF/sfconflict.html conflict]
* Simple synthetics with random reflectivity: [http://reproducibility.org/RSF/sfrandrefl.html randrefl]

==Adding noise==
* Synthetics with bursts of noise: [http://reproducibility.org/RSF/sfburstnoise.html burstnoise]
* Add random noise to the data: [http://reproducibility.org/RSF/sfnoise.html noise]

==Creating falsely irregular data==
* Cut an elliptic hole in data: [http://reproducibility.org/RSF/sfhole.html hole]
* Remove random shot gathers from a 2-D dataset: [http://reproducibility.org/RSF/sfshotholes.html shotholes]

==Creating velocity models==
* Generate 2-D layered velocity model from specified interfaces: [http://reproducibility.org/RSF/sfunif2.html unif2]
* Generate 3-D layered velocity model from specified interfaces: [http://reproducibility.org/RSF/sfunif3.html unif3]

==3-D, prestack, v(x,z)==
* Extended split step wavefield extrapolation method: [http://reproducibility.org/RSF/sfsrmod.html srmod]
==3-D, prestack, common-azimuth, v(x,z)==
* Split-step method: [http://reproducibility.org/RSF/sfcamig.html camig]
==3-D, prestack, v(z)==
* Kirchhoff method using analytical Green's functions: [http://reproducibility.org/RSF/sfkirmod3.html kirmod3]
==3-D, zero-offset, v(x,z)==
* Extended split step wavefield extrapolation method: [http://reproducibility.org/RSF/sfsstep2.html sstep2], [http://reproducibility.org/RSF/sfzomig.html zomig]
==3-D, zero-offset, const.v==
* Stolt (F-K) method: [http://reproducibility.org/RSF/sfstolt.html stolt]
==2.5-D, v(z)==
* Kirchhoff method using analytical Green's functions: [http://reproducibility.org/RSF/sfkirmod.html kirmod]
==2-D, prestack, v(x,z)==
* Unknown ray-based method: [http://reproducibility.org/RSF/sfshoot2.html shoot2]
* Second-order cell ray tracing with locally parabolic rays: [http://reproducibility.org/RSF/sfcell2.html cell2].
* Ray tracing by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2.html rays2]
* Time-domain acoustic FD: [http://reproducibility.org/RSF/sfafmod.html afmod], [http://reproducibility.org/RSF/sfawe.html awe], [http://reproducibility.org/RSF/sfawefd.html awefd], [http://reproducibility.org/RSF/sfawefd1.html awefd1], [http://reproducibility.org/RSF/sfafdm2d.html afdm2d]
* Time-domain acoustic linearized FD: [http://reproducibility.org/RSF/sflwefd.html lwefd], [http://reproducibility.org/RSF/sflwefd1.html lwefd1]
* DSR-based survey-continuation WE method: [http://reproducibility.org/RSF/sfdsr2.html dsr2]
==2-D, prestack, v(x,z), anisotropic media==
* Ray tracing in VTI media by a Runge-Kutta integrator: [http://reproducibility.org/RSF/sfrays2a.html rays2a]
==2-D, prestack, v(z)==
* DSR-based survey-continuation WE method: [http://reproducibility.org/RSF/sfdsr.html dsr]
* [http://reproducibility.org/RSF/sfspike.html spike], [http://reproducibility.org/RSF/sfbandpass.html bandpass], [http://reproducibility.org/RSF/sfinmo.html inmo]
* Analytical traveltime in a linear slowness squared model: [http://reproducibility.org/RSF/sfs2ofz.html s2ofz]

==2-D, prestack, const. v==
* Kirchhoff: [http://reproducibility.org/RSF/sfpreconstkirch.html preconstkirch]
* Stolt (F-K): [http://reproducibility.org/RSF/sfprestolt.html prestolt]
==2-D, zero-offset, v(x,z)==
* Implicit finite-difference method, 15 and 45 degree approximation: [http://reproducibility.org/RSF/sfmig45.html mig45]
* Riemannian Wavefield Extrapolation: [http://reproducibility.org/RSF/sfrwezomig.html rwezomig]
==2-D, zero-offset, v(z)==
* Wavefield-extrapolation, phase-shift method: [http://reproducibility.org/RSF/sfgazdag.html gazdag]
* Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfkirchnew.html kirchnew]
* 1-D convolution modeling: [http://reproducibility.org/RSF/sfai2refl.html ai2refl]

==Elastic modeling==
* Time-domain FD method: [http://reproducibility.org/RSF/sfewefd.html ewefd]
==Unconventional outputs==
* Models PP intercept, PP gradient and PS gradient directly: [http://reproducibility.org/RSF/sfmodrefl2.html modrefl2]
* Outputs PP and PS seismograms in the tau-p domain: [http://reproducibility.org/RSF/sfmodrefl3.html modrefl3]
==Uncertain==
* [http://reproducibility.org/RSF/sfmodrefl.html modrefl] ("Normal reflectivity modeling", according to <tt>sfdoc -k</tt>). Takes as input files with vp, vs and rho, but it is not clear whether it outputs a 2-D or 3-D file, and if modeling is with ray or WE methods.
* 2-D, unknown if prestack or zero-offset, v(x,z), Born modeling: [http://reproducibility.org/RSF/sfaborn.html aborn], [http://reproducibility.org/RSF/sfborn2d.html born2d]

=Migration=

Below, "v(x,z)" means "works when the velocity has lateral velocity variations, and will try to do something about them". This corresponds to what is widely called depth migration, but possibly to "smart" time migrations as well. The "const. v" term will be applied to algorithms that can only deal with constant velocity, regardless of whether the output is in depth or time. The "v(z)" term describes all other migrations. Note that the above terms apply even to migrations that do not need a velocity model!

It is assumed that a 3-D prestack algorithm will be able to migrate a 2-D prestack or a 3-D poststack, that a v(x,z) will be able to deal with a constant-velocity case, and so on. Exceptions to these rules will be highlighted.

The term "survey-sinking" was preferred to "source-receiver" because it can be done in either midpoint-offset, or in source-receiver coordinates, and the two differ in their treatment of amplitudes (a CMP gather is not a wavefield).

==3-D, prestack, wide-azimuth, v(x,z)==
*Survey-sinking scheme in midpoint-offset coordinates with extended split-step extrapolator: [http://reproducibility.org/RSF/sfsrmig.html srmig], [http://reproducibility.org/RSF/sfsrmig2.html srmig2]

==3-D, prestack, common-azimuth, v(x,z)==
*Extended split-step extrapolator: [http://reproducibility.org/RSF/sfcamig.html camig]

==3-D, prestack, one-azimuth, const. v==
The "one-azimuth" term was employed to underline that they take as input 3-D data with a single offset dimension, but they do not employ the common-azimuth approximation<ref>Biondi, B., and Palacharla, G.: 3-D prestack migration of common-azimuth data, Geophysics, v. 61, pp. 1822-1832.</ref> when computing ky.
*F-K scheme: [http://reproducibility.org/RSF/sfprestolt.html prestolt]
*Kirchhoff scheme: [http://reproducibility.org/RSF/sfpreconstkirch.html preconstkirch]

==3-D, poststack, v(x,z)==
*Extended split-step extrapolator: [http://reproducibility.org/RSF/sfsstep2.html sstep2], [http://reproducibility.org/RSF/sfzomig.html zomig]

==3-D, poststack, const. v==
*F-K scheme: [http://reproducibility.org/RSF/sfstolt.html stolt], with impulse response examples in <tt>sep/forwd</tt>
*Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfmig3.html mig3], [http://reproducibility.org/RSF/sfmigsteep3.html migsteep3]

==2-D, prestack, v(x,z)==
*Survey-sinking scheme in midpoint-offset coordinates with PSPI extrapolator: [http://reproducibility.org/RSF/sfdsr.html dsr]
*Survey-sinking scheme in midpoint-offset coordinates with split-step extrapolator: [http://reproducibility.org/RSF/sfdsr2.html dsr2]
*Shot-profile scheme, Riemannian extrapolator: [http://reproducibility.org/RSF/sfrwe2d.html rwe2d], [http://reproducibility.org/RSF/sfrwesrmig.html rwesrmig]

==2-D, prestack, v(z)==
*Slope-based migration: [http://reproducibility.org/RSF/sfpmig.html pmig]

==2-D, prestack, const. v==
*Angle-gather migration: [http://reproducibility.org/RSF/sfagmig.html agmig]

==2-D, poststack, v(x,z)==
*Implicit finite-difference extrapolator, 15 and 45 degree approximations: [http://reproducibility.org/RSF/sfmig45.html mig45]
*Riemannian extrapolator: [http://reproducibility.org/RSF/sfrwezomig.html rwezomig]

==2-D, poststack, v(z)==
*Phase-shift extrapolator: [http://reproducibility.org/RSF/sfgazdag.html gazdag]
*Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfkirchnew.html kirchnew]
*Least-squares Kirchhoff with antialiasing: [http://reproducibility.org/RSF/sfkirchinv.html kirchinv]

==2-D, poststack, const. v==
*Implicit finite-difference extrapolator: [http://reproducibility.org/RSF/sfconstfdmig2.html constfdmig2]

==Migration without a velocity model==
*Slope-based 2-D prestack migration, works in v(z) media: [http://reproducibility.org/RSF/sfpmig.html pmig]

==Least-squares migration==
*Kirchhoff, 2-D, post-stack, v(z), with antialiasing: [http://reproducibility.org/RSF/sfkirchinv.html kirchinv]

=Image Cosmetics=
* Automatic gain control: [http://reproducibility.org/RSF/sfagc.html agc]
* Image enhancement by histogram equalization: [http://reproducibility.org/RSF/sfequal.html equal]
* Non-stationary spectral balancing: [http://reproducibility.org/RSF/sfreshape.html reshape]

=Angle gathers=
* Transform from offset-domain common image gathers (ODCIGs) to angle-domain common image gathers: [http://reproducibility.org/RSF/sfradon.html radon], followed by arctangent stretch and conversion from radians to degrees
* Illustration of angle gathers: [http://reproducibility.org/RSF/sfangle.html angle]
* Another illustration of angle gathers: [http://reproducibility.org/RSF/sfangle2.html angle2]
* Transform PP angle gathers to PS angle gathers: [http://reproducibility.org/RSF/sfpp2psang2.html pp2psang2]
* Transform PP angle gathers to PS angle gathers: [http://reproducibility.org/RSF/sfpp2psang.html pp2psang]
* Compute angle gathers for time-shift imaging condition: [http://reproducibility.org/RSF/sfpp2pstsic.html pp2pstsic]
* Apply dip correction for angle-gathers computed with absolute offset: [http://reproducibility.org/RSF/sfabsoffdip.html absoffdip]
* Compute angle gathers for time-shift imaging condition: [http://reproducibility.org/RSF/sftshift.html tshift]

=Dip estimation=
* Estimate a number of constant dips using plane-wave destruction: [http://reproducibility.org/RSF/sfdips.html dips]
* 3-D dip estimation by plane wave destruction: [http://reproducibility.org/RSF/sfdip.html dip]
* 2-D two dip estimation by plane wave destruction: [http://reproducibility.org/RSF/sftwodip2.html twodip2]

=Attribute extraction=
* Compute intercept and gradient by least squares: [http://reproducibility.org/RSF/sfavo.html avo]
* Smooth estimate of instantaneous frequency: [http://reproducibility.org/RSF/sfiphase.html iphase]
* Canny-like edge detector: [http://reproducibility.org/RSF/sfcanny.html canny]
=Horizon extraction=
* Extract horizons from data: [http://reproducibility.org/RSF/sfhslice.html hslice]
* Extract a slice using picked surface (usually from a stack or a semblance): [http://reproducibility.org/RSF/sfslice.html slice]

=Directional wavefields methods=
These algorithms create or use directional wavefields at the surface or in depth. The most-known variety is tau-p, aka p-tau, aka slant stack, aka Linear Radon Transform, aka plane-wave synthesis, aka delayed-shot survey generation, aka Controlled Directional Reception (CDR), aka Controlled Directional Source, aka beam forming, aka plane-wave decomposition. Various people mean various things by these terms, with some agreement that "slant stack" is reserved to more simple flavor of the operation, "plane-wave decomposition" is the more carefully thought one trying to take care of the amplitudes, and CDR refers to shorter cable lengths. The various flavors of beam methods are good cousins of these approaches.
* Time-space-domain slant stack with antialiasing and a rho filter: [http://reproducibility.org/RSF/sfslant.html slant]
* High-resolution Linear Radon Transform: [http://reproducibility.org/RSF/sfradon.html radon]. Inversion approach trying to maximize spikes in the tau-p domain, and filter out other events, including elliptical ones (you may not want to use this for creating inputs to methods that work with ellipses in the tau-p domain!)
* Modeling that outputs PP and PS seismograms in the tau-p domain: [http://reproducibility.org/RSF/sfmodrefl3.html modrefl3]
* Normal moveout in tau-p domain: [http://reproducibility.org/RSF/sftaupmo.html taupmo]
* Diffraction imaging in the plane-wave domain: [http://reproducibility.org/RSF/sfdimag.html dimag]

=Transforms=
* Time-space-domain slant stack with antialiasing and a rho filter: [http://reproducibility.org/RSF/sfslant.html slant]
* High-resolution Linear Radon Transform: [http://reproducibility.org/RSF/sfradon.html radon]. Inversion approach trying to maximize spikes in the tau-p domain, and filter out other events, including elliptical ones (you may not want to use this for creating inputs to methods that work with ellipses in the tau-p domain!)
* Parabolic Radon Transform: [http://reproducibility.org/RSF/sfradon.html radon] with <tt>parab=y</tt>
* Hyperbolic Radon Transform: [http://reproducibility.org/RSF/sfveltran.html veltran]
* Hyperbolic Radon Transform with conjugate-directions inversion: [http://reproducibility.org/RSF/sfcgscan.html cgscan]
* Phase-space Radon transform: [http://reproducibility.org/RSF/sfpradon.html pradon]
* Radial Transform: [http://reproducibility.org/RSF/sfradial.html radial]
* FFT along the first axis: [http://reproducibility.org/RSF/sffft1.html fft1]
* FFT: [http://reproducibility.org/RSF/sffft3.html fft3]
* Frequency spectra: [http://reproducibility.org/RSF/sfspectra.html spectra]
* Frequency spectra in 2-D: [http://reproducibility.org/RSF/sfspectra2.html spectra2]
* 1-D Digital Wavelet Transform: [http://reproducibility.org/RSF/sfdwt.html dwt]
* Multi-dimensional cosine transform: [http://reproducibility.org/RSF/sfcosft.html cosft]
* Seislet transform: [http://reproducibility.org/RSF/sfseislet.html seislet]
* Freqlet transform: [http://reproducibility.org/RSF/sffreqlet.html freqlet]

=Smoothers and rougheners=
* 2-D smoothing by triangle plane-wave construction shaping: [http://reproducibility.org/RSF/sfpwdsmooth2.html pwdsmooth2]
* Recursive Gaussian smoothing on the fast axis: [http://reproducibility.org/RSF/sfgaussmooth.html gaussmooth]
* Smooth first derivative on the first axis: [http://reproducibility.org/RSF/sfsmoothder.html smoothder]
* Multi-dimensional triangle smoothing: [http://reproducibility.org/RSF/sfsmooth.html smooth]
* Smoothing in 2-D by simple regularization: [http://reproducibility.org/RSF/sfsmoothreg2.html smoothreg2]
* Smoothing in 1-D by simple regularization: [http://reproducibility.org/RSF/sfsmoothreg.html smoothreg]
* First derivative with a maximally linear FIR differentiator: [http://reproducibility.org/RSF/sfderiv.html deriv]
* 2-D smooth gradient: [http://reproducibility.org/RSF/sfgrad2.html grad2]
* Gradient on the first axis: [http://reproducibility.org/RSF/sfigrad.html igrad]
* Apply 2-D directional high-pass to highlight data: [http://reproducibility.org/RSF/sflight.html light]
* 1-D non-stationary smoothing: [http://reproducibility.org/RSF/sfnsmooth1.html nsmooth1]
* N-D non-stationary smoothing: [http://reproducibility.org/RSF/sfnsmooth.html nsmooth]
* Multi-dimensional smoothing with boxes: [http://reproducibility.org/RSF/sfboxsmooth.html boxsmooth]
* Half-order integration or differentiation: [http://reproducibility.org/RSF/sfhalfint.html halfint]
* 2-D smoothing by triangle directional shaping: [http://reproducibility.org/RSF/sftrismooth2.html trismooth2]

=Programs yet to be classified=
* [http://reproducibility.org/RSF/sfaliasp.html aliasp]: Aliasing test
* [http://reproducibility.org/RSF/sfapprox.html approx]: Illustrating non-hyperbolic approximations
* [http://reproducibility.org/RSF/sfautocorr.html autocorr]: Autocorrelation for helix filters
* [http://reproducibility.org/RSF/sfcflow.html cflow]: Fast mean-curvature flow
* [http://reproducibility.org/RSF/sfcostaper.html costaper]: Cosine taper around the borders (N-D)
* [http://reproducibility.org/RSF/sfcube2list.html cube2list]: Maps a cube to a list, given a threshold (clip value)
* [http://reproducibility.org/RSF/sfdeblur.html deblur]: Non-stationary debluring by inversion
* [http://reproducibility.org/RSF/sfdijkstra.html dijkstra]: Dijkstra shortest-path algorithm in 2-D
* [http://reproducibility.org/RSF/sfdiplet.html diplet]: Seislet frame
* [http://reproducibility.org/RSF/sfdistance.html distance]: Computing distance function by fast marching eikonal solver (3-D)
* [http://reproducibility.org/RSF/sfdivn.html divn]: Smooth division
* [http://reproducibility.org/RSF/sfeikonal.html eikonal]: Fast marching eikonal solver (3-D)
* [http://reproducibility.org/RSF/sfeikonalvti.html eikonalvti]: Fast marching eikonal solver in VTI media
* [http://reproducibility.org/RSF/sferfdm.html erfdm]
* [http://reproducibility.org/RSF/sfexgr.html exgr]: Exact group velocity in VTI media
* [http://reproducibility.org/RSF/sfextract.html extract]: Forward interpolation in 2-D slices
* [http://reproducibility.org/RSF/sfflat3.html flat3]: 3-D flattening (without picking)
* [http://reproducibility.org/RSF/sfflat.html flat]: Moveout flattening
* [http://reproducibility.org/RSF/sffocus.html focus]: Focusing indicator
* [http://reproducibility.org/RSF/sfframe.html frame]: Create a frame for binning
* [http://reproducibility.org/RSF/sffreqest.html freqest]: Local frequency estimation
* [http://reproducibility.org/RSF/sfgreen.html green]: Phase-space Green's function from down-marching
* [http://reproducibility.org/RSF/sfhconv.html hconv]: Convolution of two helix filters
* [http://reproducibility.org/RSF/sfhelicon.html helicon]: Multidimensional convolution and deconvolution by helix transform
* [http://reproducibility.org/RSF/sfic.html ic]: Imaging condition
* [http://reproducibility.org/RSF/sficor.html icor]: Interferometric cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sfidempatch.html idempatch]: Patching test
* [http://reproducibility.org/RSF/sfimpl1.html impl1]: 1-D anisotropic diffusion
* [http://reproducibility.org/RSF/sfimpl2.html impl2]: 2-D anisotropic diffusion
* [http://reproducibility.org/RSF/sfimpl3.html impl3]: 3-D anisotropic diffusion
* [http://reproducibility.org/RSF/sfinterp2.html interp2]: Multiple-arrival interpolation
* [http://reproducibility.org/RSF/sfinterp3.html interp3]: Multiple-arrival interpolation from down-marching
* [http://reproducibility.org/RSF/sfinterpt.html interpt]: Multiple-arrival interpolation (yet another)
* [http://reproducibility.org/RSF/sfintshow.html intshow]: Output interpolation filter
* [http://reproducibility.org/RSF/sfkolmog.html kolmog]: Kolmogoroff spectral factorization
* [http://reproducibility.org/RSF/sflaps.html laps]: Compute lagged-products
* [http://reproducibility.org/RSF/sflinefit.html linefit]: Fit a line to a set of points in 2-D
* [http://reproducibility.org/RSF/sflopef.html lopef]: Local Prediction-Error Filter (1-D, 2-D, and 3-D)
* [http://reproducibility.org/RSF/sflpef.html lpef]: Find PEF on aliased traces
* [http://reproducibility.org/RSF/sflpf.html lpf]: Local prefiction filter (n-dimensional)
* [http://reproducibility.org/RSF/sflstk.html lstk]: Local slant stacks (2D)
* [http://reproducibility.org/RSF/sfmspef.html mspef]: Multi-scale PEF estimation
* [http://reproducibility.org/RSF/sfnhelicon.html nhelicon]: Non-stationary helix convolution and deconvolution
* [http://reproducibility.org/RSF/sfnpef.html npef]: Estimate Non-stationary PEF in N dimensions
* [http://reproducibility.org/RSF/sfocparcel.html ocparcel]: Patching test for out-of-core patching
* [http://reproducibility.org/RSF/sfoctentwt.html octentwt]: Tent-like weight for out-of-core patching
* [http://reproducibility.org/RSF/sfoff2abs3.html off2abs3]: Transform vector-offset to absolute-offset
* [http://reproducibility.org/RSF/sfoff2abs.html off2abs]: Transform vector-offset to absolute-offset
* [http://reproducibility.org/RSF/sfofpwd2.html ofpwd2]: Objective function of two dips estimation with PWD filters
* [http://reproducibility.org/RSF/sfofpwd.html ofpwd]: Objective function of dip estimation with PWD filters
* [http://reproducibility.org/RSF/sfofsemb.html ofsemb]: Objective function of dip estimation with semblance
* [http://reproducibility.org/RSF/sfparcel.html parcel]: Patching test
* [http://reproducibility.org/RSF/sfpatch.html patch]: Patching (N-dimensional)
* [http://reproducibility.org/RSF/sfpef.html pef]: Multi-dimensional PEF (prediction error filter) estimation
* [http://reproducibility.org/RSF/sfpostfilter2.html postfilter2]: Convert B-spline coefficients to data in 2-D
* [http://reproducibility.org/RSF/sfpredict.html predict]: 2-D plane-wave prediction
* [http://reproducibility.org/RSF/sfpwd.html pwd]: 3-D plane wave destruction
* [http://reproducibility.org/RSF/sfpwdsigk.html pwdsigk]: Signal component separation using plane-wave destruction
* [http://reproducibility.org/RSF/sfrefer.html refer]: Subtract a reference from a grid
* [http://reproducibility.org/RSF/sfreg2tri.html reg2tri]: Decimate a regular grid to triplets for triangulation
* [http://reproducibility.org/RSF/sfricker1.html ricker1]: Convolution with a Ricker wavelet
* [http://reproducibility.org/RSF/sfrweab.html rweab]: Riemannian Wavefield Extrapolation]:* a,b coefficients
* [http://reproducibility.org/RSF/sfrwemete2d.html rwemete2d]: 2-D metric tensor
* [http://reproducibility.org/RSF/sfseisigk.html seisigk]: Signal component separation using seislet transforms
* [http://reproducibility.org/RSF/sfshapebin1.html shapebin1]: 1-D inverse interpolation with shaping regularization
* [http://reproducibility.org/RSF/sfshapebin.html shapebin]: Data binning in 2-D slices by inverse interpolation
* [http://reproducibility.org/RSF/sfshapesigk.html shapesigk]: Signal component separation using plane-wave shaping
* [http://reproducibility.org/RSF/sfshotprop.html shotprop]: Shot propagation
* [http://reproducibility.org/RSF/sfsic3d.html sic3d]: Local slant stacks IC
* [http://reproducibility.org/RSF/sfsic.html sic]: Local slant stacks IC
* [http://reproducibility.org/RSF/sfsplinebank.html splinebank]: Prepare a filter bank for B-spline plane wave filters
* [http://reproducibility.org/RSF/sfsplinefilter.html splinefilter]: Convert data to B-spline coefficients
* [http://reproducibility.org/RSF/sfsrsyn.html srsyn]: Synthesize shot/receiver wavefields for 3-D SR migration
* [http://reproducibility.org/RSF/sftan2ang.html tan2ang]: Compute cos(theta) from 1/|pm| for time-shift imaging condition
* [http://reproducibility.org/RSF/sftcor.html tcor]: Interferometric cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sftentwt.html tentwt]: Tent-like weight for patching
* [http://reproducibility.org/RSF/sftimeshift.html timeshift]: Apply variable time shifts using plane-wave construction
* [http://reproducibility.org/RSF/sftrapez.html trapez]: Convolution with a trapezoidal filter
* [http://reproducibility.org/RSF/sftree.html tree]: Multiple arrivals with a fast algorithm
* [http://reproducibility.org/RSF/sftri2reg.html tri2reg]: Interpolate triangulated triplets to a regular grid
* [http://reproducibility.org/RSF/sftrirand.html trirand]: Edit points for triangulation by removing similar and randomizing
* [http://reproducibility.org/RSF/sftspline.html tspline]: Helix filters for spline in tension
* [http://reproducibility.org/RSF/sftwofreq2.html twofreq2]: 2-D two spectral component estimation
* [http://reproducibility.org/RSF/sfucor.html ucor]: Interferometric cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sfwarp1.html warp1]: Multicomponent data registration by 1-D warping
* [http://reproducibility.org/RSF/sfwarpadd.html warpadd]: Add a perturbation to the warping function
* [http://reproducibility.org/RSF/sfwarpscan.html warpscan]: Multicomponent data registration analysis
* [http://reproducibility.org/RSF/sfwdf.html wdf]: Assymptotic Wigner distribution
* [http://reproducibility.org/RSF/sfwigner.html wigner]: Assymptotic Wigner distribution in space-time
* [http://reproducibility.org/RSF/sfwilson.html wilson]: Wilson-Burg spectral factorization
* [http://reproducibility.org/RSF/sfxcor.html xcor]: Cross-correlation of time series (zero-lag output)
* [http://reproducibility.org/RSF/sfztrace.html ztrace]: Multiple arrivals by depth marching
* The SCons macros in <tt>RSFSRC/book/packages</tt>

=References=
<references/>

Advanced Installation

2011-08-06T16:22:39Z

Nick: /* Fedora, CentOS, Scientific Linux, openSUSE */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS, Scientific Linux, openSUSE==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<bash>
pfexec pkg install SUNWxorg-headers
</bash>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Guide to madagascar programs

2011-08-06T02:51:01Z

Nick: /* Seismic programs */

<center>''This page was created from the LaTeX source in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/rsf/prog.tex?view=markup book/rsf/rsf/prog.tex] using [[latex2wiki]]''</center>

This guide introduces some of the most used <tt>madagascar</tt> programs and illustrates their usage with examples.
=Main programs=
The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/ system/main] in the Madagascar distribution. The "main" programs perform general-purpose operations on RSF hypercubes regardless of the data dimensionality or physical dimensions.

==sfadd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Add, multiply, or divide RSF datasets.
|-
! colspan="4" | sfadd > out.rsf scale= add= sqrt= abs= log= exp= mode= [< file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | The various operations, if selected, occur in the following order: (1) Take absolute value, abs= (2) Add a scalar, add= (3) Take the natural logarithm, log= (4) Take the square root, sqrt= (5) Multiply by a scalar, scale= (6) Compute the base-e exponential, exp= (7) Add, multiply, or divide the data sets, mode= sfadd operates on integer, float, or complex data, but all the input and output files must be of the same data type. An alternative to sfadd is sfmath, which is more versatile, but may be less efficient.
|-
| ''bools '' || '''abs=''' || || If true take absolute value [nin]
|-
| ''floats '' || '''add=''' || || Scalar values to add to each dataset [nin]
|-
| ''bools '' || '''exp=''' || || If true compute exponential [nin]
|-
| ''bools '' || '''log=''' || || If true take logarithm [nin]
|-
| ''string '' || '''mode=''' || || 'a' means add (default), 'p' or 'm' means multiply, 'd' means divide
|-
| ''floats '' || '''scale=''' || || Scalar values to multiply each dataset with [nin]
|-
| ''bools '' || '''sqrt=''' || || If true take square root [nin]
|}

<tt>sfadd</tt> is useful for combining (adding, dividing, or
multiplying) several datasets. What if you want to subtract two
datasets? Easy. Use the <tt>scale</tt> parameter as follows:
<pre>
bash$ sfadd data1.rsf data2.rsf scale=1,-1 > diff.rsf
</pre>
or
<pre>
bash$ sfadd < data1.rsf data2.rsf scale=1,-1 > diff.rsf
</pre>
The same task can be accomplished with the more general <tt>sfmath</tt> program:
<pre>
bash$ sfmath one=data1.rsf two=data2.rsf output='one-two' > diff.rsf
</pre>
or
<pre>
bash$ sfmath < data1.rsf two=data2.rsf output='input-two' > diff.rsf
</pre>
In both cases, the size and shape of <tt>data1.rsf</tt> and
<tt>data2.rsf</tt> hypercubes should be the same, and a warning
message is printed out if the the axis sampling parameters (such as
<tt>o1</tt> or <tt>d1</tt>) in these files are different.
====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/add.c?view=markup system/main/add.c]====
The first input file is either in the list or in the standard input.
<c>
/* find number of input files */
if (isatty(fileno(stdin))) {
/* no input file in stdin */
nin=0;
} else {
in[0] = sf_input("in");
nin=1;
}
</c>

Collect input files in the <tt>in</tt> array from all command-line
parameters that don't contain an "<tt>=</tt>" sign. The total number
of input files in <tt>nin</tt>.
<c>
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'=')) continue;
in[nin] = sf_input(argv[i]);
nin++;
}
if (0==nin) sf_error ("no input");
/* nin = no of input files*/
</c>

A helper function <tt>check_compat</tt> checks the compatibility of
input files.
<c>
static void
check_compat (sf_datatype type /* data type */,
size_t nin /* number of files */,
sf_file* in /* input files [nin] */,
int dim /* file dimensionality */,
const int* n /* dimensions [dim] */)
/* Check that the input files are compatible.
Issue error for type mismatch or size mismatch.
Issue warning for grid parameters mismatch. */
{
int ni, id;
size_t i;
float d, di, o, oi;
char key[3];
const float tol=1.e-5; /* tolerance for comparison */

for (i=1; i < nin; i++) {
if (sf_gettype(in[i]) != type)
sf_error ("type mismatch: need %d",type);
for (id=1; id <= dim; id++) {
(void) snprintf(key,3,"n%d",id);
if (!sf_histint(in[i],key,&ni) || ni != n[id-1])
sf_error("%s mismatch: need %d",key,n[id-1]);
(void) snprintf(key,3,"d%d",id);
if (sf_histfloat(in[0],key,&d)) {
if (!sf_histfloat(in[i],key,&di) ||
(fabsf(di-d) > tol*fabsf(d)))
sf_warning("%s mismatch: need %g",key,d);
} else {
d = 1.;
}
(void) snprintf(key,3,"o%d",id);
if (sf_histfloat(in[0],key,&o) &&
(!sf_histfloat(in[i],key,&oi) ||
(fabsf(oi-o) > tol*fabsf(d))))
sf_warning("%s mismatch: need %g",key,o);
}
}
}
</c>

Finally, we enter the main loop, where input data are getting read
buffer by buffer and combined in the total product depending on the
data type.
<c>
for (nbuf /= sf_esize(in[0]); nsiz > 0; nsiz -= nbuf) {
if (nbuf > nsiz) nbuf=nsiz;

for (j=0; j < nin; j++) {
collect = (bool) (j != 0);
switch(type) {
case SF_FLOAT:
sf_floatread((float*) bufi,
nbuf,
in[j]);
add_float(collect,
nbuf,
(float*) buf,
(const float*) bufi,
cmode,
scale[j],
add[j],
abs_flag[j],
log_flag[j],
sqrt_flag[j],
exp_flag[j]);
break;
</c>

The data combination program for floating point numbers is
<tt>add_float</tt>.
<c>
static void add_float (bool collect, /* if collect */
size_t nbuf, /* buffer size */
float* buf, /* output [nbuf] */
const float* bufi, /* input [nbuf] */
char cmode, /* operation */
float scale, /* scale factor */
float add, /* add factor */
bool abs_flag, /* if abs */
bool log_flag, /* if log */
bool sqrt_flag, /* if sqrt */
bool exp_flag /* if exp */)
/* Add floating point numbers */
{
size_t j;
float f;

for (j=0; j < nbuf; j++) {
f = bufi[j];
if (abs_flag) f = fabsf(f);
f += add;
if (log_flag) f = logf(f);
if (sqrt_flag) f = sqrtf(f);
if (1. != scale) f *= scale;
if (exp_flag) f = expf(f);
if (collect) {
switch (cmode) {
case 'p': /* product */
case 'm': /* multiply */
buf[j] *= f;
break;
case 'd': /* delete */
if (f != 0.) buf[j] /= f;
break;
default: /* add */
buf[j] += f;
break;
}
} else {
buf[j] = f;
}
}
}
</c>

==sfattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display dataset attributes.
|-
! colspan="4" | sfattr < in.rsf want=
|-
| colspan="4" | Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr" ******************************************* rms = 0.992354 mean value = 0.987576 2-norm value = 9.92354 variance = 0.00955481 standard deviation = 0.0977487 maximum value = 1.12735 at 97 minimum value = 0.151392 at 100 number of nonzero samples = 100 total number of samples = 100 ******************************************* rms = sqrt[ sum(data^2) / n ] mean = sum(data) / n norm = sum(abs(data)^lval)^(1/lval) variance = [ sum(data^2) - n*mean^2 ] / [ n-1 ] standard deviation = sqrt [ variance ]
|-
| ''int '' || '''lval=2''' || || norm option, lval is a non-negative integer, computes the vector lval-norm
|-
| ''string '' || '''want=''' || || 'all'(default),'rms','mean','norm','var','std','max','min','nonzero','samples','short'
:want= 'rms' displays the root mean square
:want= 'norm' displays the square norm, otherwise specified by lval.
:want= 'var' displays the variance
:want= 'std' displays the standard deviation
:want= 'nonzero' displays number of nonzero samples
:want= 'samples' displays total number of samples
:want= 'short' displays a short one-line version
|}

<tt>sfattr</tt> is a useful diagnostic program. It reports certain
statistical values for an RSF dataset: RMS (root-mean-square)
amplitude, mean value, vector norm value, variance, standard deviation,
maximum and minimum values, number of nonzero samples, and the total
number of samples.
If we denote data values as <math>d_i</math> for <math>i=0,1,2,\ldots,n</math>, then the RMS
value is <math>\sqrt{\frac{1}{n}\,\sum\limits_{i=0}^n d_i^2}</math>, the mean
value is <math>\frac{1}{n}\,\sum\limits_{i=0}^n d_i</math>, the <math>L_2</math>-norm value
is <math>\sqrt{\sum\limits_{i=0}^n d_i^2}</math>, the variance is
<math>\frac{1}{n-1}\,\left[\sum\limits_{i=0}^n d_i^2 - \frac{1}{n}\left(\sum\limits_{i=0}^n d_i\right)^2\right]</math>, and the standard
deviation is the square root of the variance. Using <tt>sfattr</tt>
is a quick way to see the distribution of data values and check it for anomalies.

The output can be parsed using utilities such as <tt>awk</tt>, to extract only a numeric value for feeding it as a parameter value into a command line interface. Notice the backticks in the example below:
<bash>
sfgrey <vel.rsf allpos=y bias=`sfattr <vel.rsf want=min | awk '{print $4}'` | sfpen
</bash>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/attr.c?view=markup system/main/attr.c]====

Computations start by finding the input data (<tt>in</tt>) size
(<tt>nsiz</tt>) and dimensions (<tt>dim</tt>).
<c>
dim = (size_t) sf_filedims (in,n);
for (nsiz=1, i=0; i < dim; i++) {
nsiz *= n[i];
}
</c>

In the main loop, we read the input data buffer by buffer.
<c>
for (nleft=nsiz; nleft > 0; nleft -= nbuf) {
nbuf = (bufsiz < nleft)? bufsiz: nleft;
switch (type) {
case SF_FLOAT:
sf_floatread((float*) buf,nbuf,in);
break;
case SF_INT:
sf_intread((int*) buf,nbuf,in);
break;
case SF_COMPLEX:
sf_complexread((sf_complex*) buf,nbuf,in);
break;
case SF_UCHAR:
sf_ucharread((unsigned char*) buf,nbuf,in);
break;
case SF_CHAR:
default:
sf_charread(buf,nbuf,in);
break;
}
</c>

The data attributes are accumulated in corresponding double-precision
variables.
<c>
fsum += f;
fsqr += f*f;
</c>

Finally, the attributes are reduced and printed out.
<c>
fmean = fsum/nsiz;
if (lval==2) fnorm = sqrt(fsqr);
else if (lval==0) fnorm = nsiz-nzero;
else fnorm = pow(flval,1./lval);
frms = sqrt(fsqr/nsiz);
if (nsiz > 1) fvar = (fsqr-nsiz*fmean*fmean)/(nsiz-1);
else fvar = 0.0;
fstd = sqrt(fvar);
</c>

<c>
if(NULL==want || 0==strcmp(want,"rms"))
printf("rms = %g \n",(float) frms);
if(NULL==want || 0==strcmp(want,"mean"))
printf("mean value = %g \n",(float) fmean);
if(NULL==want || 0==strcmp(want,"norm"))
printf("%d-norm value = %g \n",lval,(float) fnorm);
if(NULL==want || 0==strcmp(want,"var"))
printf("variance = %g \n",(float) fvar);
if(NULL==want || 0==strcmp(want,"std"))
printf("standard deviation = %g \n",(float) fstd);
</c>

==sfcat==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Concatenate datasets.
|-
! colspan="4" | sfcat > out.rsf space= axis=3 nspace=(int) (ni/(20*nin) + 1) [<file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | sfmerge inserts additional space between merged data.
|-
| ''int '' || '''axis=3''' || || Axis being merged
|-
| ''int '' || '''nspace=(int) (ni/(20*nin) + 1)''' || || if space=y, number of traces to insert
|-
| ''bool '' || '''space=''' || [y/n] || Insert additional space.
:y is default for sfmerge, n is default for sfcat
|}

<tt>sfcat</tt> and <tt>sfmerge</tt> concatenate two or more files
together along a particular axis. It is the same program, only
<tt>sfcat</tt> has the default <tt>space=n</tt> and <tt>sfmerge</tt>
has the default <tt>space=y</tt>.
Example of <tt>sfcat</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcat one.rsf one.rsf axis=1 > two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=4 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
12 elements 48 bytes
</pre>
Example of <tt>sfmerge</tt>:
<pre>
bash$ sfmerge one.rsf one.rsf axis=2 > two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=7 d2=0.1 o2=0 label2="Distance" unit2="km"
14 elements 56 bytes
</pre>
In this case, an extra empty trace is inserted between the two merged files.
The axes that are not being merged are checked for consistency:
<pre>
bash$ sfcat one.rsf two.rsf > three.rsf
sfcat: n2 mismatch: need 3
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cat.c?view=markup system/main/cat.c]====
The first input file is either in the list or in the standard input.
<c>
in = (sf_file*) sf_alloc ((size_t) argc,sizeof(sf_file));

if (!sf_stdin()) { /* no input file in stdin */
nin=0;
} else {
in[0] = sf_input("in");
nin=1;
}
</c>

Everything on the command line that does not contain a "=" sign is
treated as a file name, and the corresponding file object is added to the list.
<c>
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'='))
continue; /* not a file */
in[nin] = sf_input(argv[i]);
nin++;
}
if (0==nin) sf_error ("no input");
</c>

As explained above, if the <tt>space=</tt> parameter is not set, it is
inferred from the program name: <tt>sfmerge</tt> corresponds to
<tt>space=y</tt> and <tt>sfcat</tt> corresponds to <tt>space=n</tt>.
<c>
if (!sf_getbool("space",&space)) {
/* Insert additional space.
y is default for sfmerge, n is default for sfcat */
prog = sf_getprog();
if (NULL != strstr (prog, "merge")) {
space = true;
} else if (NULL != strstr (prog, "cat")) {
space = false;
} else {
sf_warning("%s is neither merge nor cat,"
" assume merge",prog);
space = true;
}
}
</c>

Find the axis for the merging (from the command line <tt>axis=</tt>
argument) and figure out two sizes: <tt>n1</tt> for everything after
the axis and <tt>n2</tt> for everything before the axis.
<c>
n1=1;
n2=1;
for (i=1; i <= dim; i++) {
if (i < axis) n1 *= n[i-1];
else if (i > axis) n2 *= n[i-1];
}
</c>

In the output, the selected axis will get extended.
<c>
/* figure out the length of extended axis */
ni = 0;
for (j=0; j < nin; j++) {
ni += naxis[j];
}

if (space) {
if (!sf_getint("nspace",&nspace))
nspace = (int) (ni/(20*nin) + 1);
/* if space=y, number of traces to insert */
ni += nspace*(nin-1);
}

(void) snprintf(key,3,"n%d",axis);
sf_putint(out,key,(int) ni);
</c>

The rest is simple: loop through the datasets reading and writing the
data in buffer-size chunks and adding extra empty chunks if
<tt>space=y</tt>.
<c>
for (i2=0; i2 < n2; i2++) {
for (j=0; j < nin; j++) {
for (ni = n1*naxis[j]*esize; ni > 0; ni -= nbuf) {
nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
sf_charread (buf,nbuf,in[j]);
sf_charwrite (buf,nbuf,out);
}
if (!space || j == nin-1) continue;
/* Add spaces */
memset(buf,0,BUFSIZ);
for (ni = n1*nspace*esize; ni > 0; ni -= nbuf) {
nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
sf_charwrite (buf,nbuf,out);
}
}
}
</c>

==sfcdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for complex linear operators with adjoints
|-
! colspan="4" | sfcdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|-
| ''file '' || '''dat=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|}

A simple demonstration of the program can be made taking advantage that the complex-to-complex FFT is a linear operator:

<bash>
sfspike n1=100 | sfrtoc > spike.rsf
< spike.rsf sffft axis=1 pad=1 > spike2.rsf
sfcdottest sffft mod=spike.rsf dat=spike2.rsf axis=1 pad=1
</bash>

The output should show values identical down to the last decimal:

<pre>
sfcdottest: L[m]*d=(3.73955,-1.86955)
sfcdottest: L'[d]*m=(3.73955,-1.86955)
</pre>

==sfcmplx==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Create a complex dataset from its real and imaginary parts.
|-
! colspan="4" | sfcmplx > cmplx.rsf real.rsf imag.rsf
|-
| colspan="4" | There has to be only two input files specified and no additional parameters.
|}

<tt>sfcmplx</tt> simply creates a complex dataset from its real and
imaginary parts. The reverse operation can be accomplished with
<tt>sfreal</tt> and <tt>sfimag</tt>.
Example of <tt>sfcmplx</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcmplx one.rsf one.rsf > cmplx.rsf
bash$ sfin cmplx.rsf
cmplx.rsf:
in="/tmp/cmplx.rsf@"
esize=8 type=complex form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 48 bytes
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cmplx.c?view=markup system/main/cmplx.c]====
The program flow is simple. First, get the names of the input files.
<c>
/* the first two non-parameters are real and imaginary files */
for (i=1; i< argc; i++) {
if (NULL == strchr(argv[i],'=')) {
if (NULL == real) {
real = sf_input (argv[i]);
} else {
imag = sf_input (argv[i]);
break;
}
}
}
if (NULL == imag) {
if (NULL == real) sf_error ("not enough input");
/* if only one input, real is in stdin */
imag = real;
real = sf_input("in");
}
</c>

The main part of the program reads the real and imaginary parts buffer by buffer and assembles and writes out the complex input.
<c>
for (nleft= (size_t) (rsize*resize); nleft > 0; nleft -= nbuf) {
nbuf = (BUFSIZ < nleft)? BUFSIZ: nleft;
sf_charread(rbuf,nbuf,real);
sf_charread(ibuf,nbuf,imag);
for (i=0; i < nbuf; i += resize) {
memcpy(cbuf+2*i, rbuf+i,(size_t) resize);
memcpy(cbuf+2*i+resize,ibuf+i,(size_t) resize);
}
sf_charwrite(cbuf,2*nbuf,cmplx);
}
</c>
==sfconjgrad==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic conjugate-gradient solver for linear inversion
|-
! colspan="4" | sfconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
|-
| ''int '' || '''niter=1''' || || number of iterations
|}

<tt>sfconjgrad</tt> is a generic program for least-squares linear
inversion with the [http://en.wikipedia.org/wiki/Conjugate_gradient_method conjugate-gradient method]. Suppose you have an
executable program <tt><prog></tt> that takes an RSF file from the
standard input and produces an RSF file in the standard output. It may
take any number of additional parameters but one of them must be
<tt>adj=</tt> that sets the forward (<tt>adj=0</tt>) or adjoint
(<tt>adj=1</tt>) operations. The program <tt><prog></tt> is typically
an RSF program but it could be anything (a script, a multiprocessor
MPI program, etc.) as long as it implements a linear operator
<math>\mathbf{L}</math> and its adjoint. There are no restrictions on the data
size or shape. You can easily test the adjointness with
<tt>sfdottest</tt>. The <tt>sfconjgrad</tt> program searches for a
vector <math>\mathbf{m}</math> that minimizes the least-square misfit
<math>\|\mathbf{d - L\,m}\|^2</math> for the given input data vector <math>\mathbf{d}</math>.

The pseudocode for <tt>sfconjgrad</tt> is given at the end of the [http://www.reproducibility.org/RSF/book/gee/lsq/paper.pdf "Model fitting with least squares" chapter] of ''Imaging Estimation by Example'' by Jon Claerbout, with the earliest form published in [http://sepwww.stanford.edu/data/media/public/oldreports/sep48/48_25.pdf "Conjugate Gradient Tutorial"] (SEP-48, 1986, same author). A simple toy implementation with a small matrix shows that this is algorithm produces the same steps as the algorithm described in equations 45-49 of [http://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf "An introduction to the Conjugate Gradient Method Without the Agonizing Pain"] by J.R. Shewchuk, 1994, when the equation <math>A^T A x = A^T b</math> (in Shewchuk's notation) is solved. Multiplying with the transpose ensures a correct solution even when matrix A is square but not symmetric, or not square at all. The program [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad] implements this algorithm for the case when inputs are complex.

Here is an example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
The <tt>sfdottest</tt> program can perform the dot product test to
check that the adjoint mode works correctly.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=5.28394
sfdottest: L'[d]*m=5.28394
</pre>
Your numbers may be different because <tt>sfdottest</tt> generates new
random input on each run.
Next, let us make some random data with <tt>sfnoise</tt>.
<pre>
bash$ sfnoise seed=2005 rep=y < vec.rsf > dat.rsf
</pre>
and try to invert the filtering operation using <tt>sfconjgrad</tt>:
<pre>
bash$ sfconjgrad sfhelicon filt=flt.rsf lag=lag.rsf \
mod=vec.rsf < dat.rsf > mod.rsf niter=10
sfconjgrad: iter 1 of 10
sfconjgrad: grad=3253.65
sfconjgrad: iter 2 of 10
sfconjgrad: grad=289.421
sfconjgrad: iter 3 of 10
sfconjgrad: grad=92.3481
sfconjgrad: iter 4 of 10
sfconjgrad: grad=36.9417
sfconjgrad: iter 5 of 10
sfconjgrad: grad=18.7228
sfconjgrad: iter 6 of 10
sfconjgrad: grad=11.1794
sfconjgrad: iter 7 of 10
sfconjgrad: grad=7.26941
sfconjgrad: iter 8 of 10
sfconjgrad: grad=5.15945
sfconjgrad: iter 9 of 10
sfconjgrad: grad=4.23055
sfconjgrad: iter 10 of 10
sfconjgrad: grad=3.57495
</pre>
The output shows that, in 10 iterations, the norm of the gradient vector decreases by almost 1000.
We can check the residual misfit before
<pre>
bash$ < dat.rsf sfattr want=norm
norm value = 49.7801
</pre>
and after
<pre>
bash$ sfhelicon filt=flt.rsf lag=lag.rsf < mod.rsf | \
sfadd scale=1,-1 dat.rsf | sfattr want=norm
norm value = 5.73563
</pre>
In 10 iterations, the misfit decreased by an order of magnitude. The
result can be improved by running the program for more iterations.

An equivalent implementation for complex-valued inputs is [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad]. A simple, lightweight Python implementation can be found in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/user/fomels/conjgrad.py?view=markup $RSFROOT/lib/conjgrad.py].

==sfcp==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Copy or move a dataset.
|-
! colspan="4" | sfcp in.rsf out.rsf
|-
| colspan="4" | sfcp - copy, sfmv - move. Mimics standard Unix commands.
|}

The <tt>sfcp</tt> and <tt>sfmv</tt> command imitate the Unix
<tt>cp</tt> and <tt>mv</tt> commands and serve for copying and moving
RSF files. Example:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
in="/tmp/one.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
bash$ sfcp one.rsf two.rsf
bash$ sfin two.rsf
two.rsf:
in="/tmp/two.rsf@"
esize=4 type=float form=native
n1=2 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
6 elements 24 bytes
</pre>

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/cp.c?view=markup system/main/cp.c]====
First, we look for the two first command-line arguments that don't
have the "=" character in them and consider them as the names of the
input and the output files.
<c>
/* the first two non-parameters are in and out files */
for (i=1; i< argc; i++) {
if (NULL == strchr(argv[i],'=')) {
if (NULL == in) {
infile = argv[i];
in = sf_input (infile);
} else {
out = sf_output (argv[i]);
break;
}
}
}
if (NULL == in || NULL == out)
sf_error ("not enough input");
</c>

Next, we use library functions sf_cp and sf_rm to do the actual work.
<c>
sf_cp(in,out);
if (NULL != strstr (sf_getprog(),"mv"))
sf_rm(infile,false,false,false);
</c>

==sfcut==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Zero a portion of the dataset.
|-
! colspan="4" | sfcut < in.rsf > out.rsf verb=n [j1=1 j2=1 ... f1=0 f2=0 ... n1=n1 n2=n2 ... max1= max2= ... min1= min2= ...]
|-
| colspan="4" | jN defines the jump in N-th dimension fN is the window start nN is the window size minN and maxN is the maximum and minimum in N-th dimension Reverse of window.
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

The <tt>sfcut</tt> command is related to <tt>sfwindow</tt> and has the same
set of arguments only instead of extracting the selected window, it fills it
with zeroes. The size of the input data is preserved.
Examples:
<pre>
bash$ sfspike n1=5 n2=5 > in.rsf
bash$ < in.rsf sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ < in.rsf sfcut n1=2 f1=1 n2=3 f2=2 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 0 0 1 1
15: 1 0 0 1 1
20: 1 0 0 1 1
bash$ < in.rsf sfcut j1=2 | sfdisfil
0: 0 1 0 1 0
5: 0 1 0 1 0
10: 0 1 0 1 0
15: 0 1 0 1 0
20: 0 1 0 1 0
</pre>

==sfdd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert between different formats.
|-
! colspan="4" | sfdd < in.rsf > out.rsf line=8 form= type= format=
|-
| ''string '' || '''form=''' || || ascii, native, xdr
|-
| ''string '' || '''format=''' || || Element format (for conversion to ASCII)
|-
| ''int '' || '''line=8''' || || Number of numbers per line (for conversion to ASCII)
|-
| ''string '' || '''type=''' || || int, float, complex
|}

The <tt>sfdd</tt> program is used to change either the form (<tt>ascii</tt>,
<tt>xdr</tt>, <tt>native</tt>) or the type (<tt>complex</tt>, <tt>float</tt>,
<tt>int</tt>, <tt>char</tt>) of the input dataset.
In the example below, we create a plain text (ASCII) file with numbers and
then use <tt>sfdd</tt> to generate an RSF file in <tt>xdr</tt> form with
<tt>complex</tt> numbers.
<pre>
bash$ cat test.txt
1 2 3 4 5 6
bash$ echo n1=6 data_format=ascii_int in=test.txt > test.rsf
bash$ sfin test.rsf
test.rsf:
in="test.txt"
esize=0 type=int form=ascii
n1=6 d1=? o1=?
6 elements
bash$ sfdd < test.rsf form=xdr type=complex > test2.rsf
bash$ sfin test2.rsf
test2.rsf:
in="/tmp/test2.rsf@"
esize=8 type=complex form=xdr
n1=3 d1=? o1=?
3 elements 24 bytes
bash$ sfdisfil < test2.rsf
0: 1, 2i 3, 4i 5, 6i
</pre>
To learn more about the RSF data format, consult the [[Guide to RSF file format| guide to RSF format]].

==sfdisfil==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Print out data values.
|-
! colspan="4" | sfdisfil < in.rsf number=y col=0 format= header= trailer=
|-
| colspan="4" | Alternatively, use sfdd and convert to ASCII form.
|-
| ''int '' || '''col=0''' || || Number of columns.
:The default depends on the data type:
:10 for int and char,
:5 for float,
:3 for complex
|-
| ''string '' || '''format=''' || || Format for numbers (printf-style).
:The default depends on the data type: "%4d " for int and char, "%13.4g" for float, "%10.4g,%10.4gi" for complex
|-
| ''string '' || '''header=''' || || Optional header string to output before data
|-
| ''bool '' || '''number=y''' || [y/n] || If number the elements
|-
| ''string '' || '''trailer=''' || || Optional trailer string to output after data
|}

The <tt>sfdisfil</tt> program simply dumps the data contents to the standard
output in a text form. It is used mostly for debugging purposes to quickly
examine RSF files. Here is an example:
<pre>
bash$ sfmath o1=0 d1=2 n1=12 output=x1 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 2 4 6 8
5: 10 12 14 16 18
10: 20 22
</pre>
The output format is easily configurable.
<pre>
bash$ < test.rsf sfdisfil col=6 number=n format="%5.1f"
0.0 2.0 4.0 6.0 8.0 10.0
12.0 14.0 16.0 18.0 20.0 22.0
</pre>
Along with <tt>sfdd</tt>, <tt>sfdisfil</tt> provides a simple way to convert
RSF data to an ASCII form.

==sfdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for linear operators with adjoints
|-
! colspan="4" | sfdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|}

<tt>sfdottest</tt> is a generic dot-product test program for testing
linear operators. Suppose there is an executable program
<tt><prog></tt> that takes an RSF file from the standard input and
produces an RSF file in the standard output. It may take any number of
additional parameters but one of them must be <tt>adj=</tt> that sets
the forward (<tt>adj=0</tt>) or adjoint (<tt>adj=1</tt>) operations.
The program <tt><prog></tt> is typically an RSF program but it could
be anything (a script, a multiprocessor MPI program, etc.) as long as
it implements a linear operator <math>\mathbf{L}</math> and its adjoint
<math>\mathbf{L}^T</math>. The <tt>sfdottest</tt> program is testing the equality
<center><math>
d^T\,L\,m = m^T\,L^T\,d
</math></center>
by using random vectors <math>\mathbf{m}</math> and <math>\mathbf{d}</math>. You can invoke it with
<pre>
bash$ sfdottest <prog> [optional aruments] mod=mod.rsf dat=dat.rsf
</pre>
where <tt>mod.rsf</tt> and <tt>dat.rsf</tt> are RSF files that
represent vectors from the model and data spaces. Pay attention to the
dimension and size of these vectors! If the program does not respond
for a very long time, it is quite possible that the dimension and size
of the vectors are inconsistent with the requirement of the program to be
tested. <tt>sfdottest</tt>
does not create any temporary files and does not have any restrictive
limitations on the size of the vectors.
Here is an example. We first setup a vector with 100 elements using
<tt>sfspike</tt> and then run <tt>sfdottest</tt> to test the
<tt>sfcausint</tt> program. <tt>sfcausint</tt> implements a linear
operator of causal integration and its adjoint, the anti-causal
integration.
<pre>
bash$ sfspike n1=100 > vec.rsf
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=1410.2
sfdottest: L'[d]*m=1410.2
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=1165.87
sfdottest: L'[d]*m=1165.87
</pre>
The numbers are different on subsequent runs because of changing
seed in the random number generator.
Here is a somewhat more complicated example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
Now the <tt>sfdottest</tt> program can perform the dot product test.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf
sfdottest: L[m]*d=8.97375
sfdottest: L'[d]*m=8.97375
</pre>
Here is the same program tested in the inverse filtering mode:
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf div=y
sfdottest: L[m]*d=15.0222
sfdottest: L'[d]*m=15.0222
</pre>

==sfget==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Output parameters from the header.
|-
! colspan="4" | sfget < in.rsf parform=y par1 par2 ...
|-
| ''bool '' || '''parform=y''' || [y/n] || If y, print out parameter=value. If n, print out value.
|}

The <tt>sfget</tt> program extracts a parameter value from an RSF file. It is
useful mostly for scripting. Here is, for example, a quick calculation of the
maximum value on the first axis in an RSF dataset (the output of
<tt>sfspike</tt>) using the standard Unix <tt>bc</tt> calculator.
<pre>
bash$ ( sfspike n1=100 | sfget n1 d1 o1; echo "o1+(n1-1)*d1" ) | bc
.396
</pre>
See also <tt>sfput</tt>.

====Implementation: [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/main/get.c?view=markup system/main/get.c]====
The implementation is trivial. Loop through all command-line parameters that contain
the "=" character.
<c>
for (i = 1; i < argc; i++) {
key = argv[i];
if (NULL != strchr(key,'=')) continue;
</c>

Get the parameter value (as string) and output it as either
<tt>key=value</tt> or <tt>value</tt>, depending on the
<tt>parform</tt> parameter.
<c>
string = sf_histstring(in,key);
if (NULL == string) {
sf_warning("No key %s",key);
} else {
if (parform) printf ("%s=",key);
printf("%s\n",string);
}
</c>

==sfheadercut==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Zero a portion of a dataset based on a header mask.
|-
! colspan="4" | sfheadercut mask=head.rsf < in.rsf > out.rsf
|-
| colspan="4" | The input data is a collection of traces n1xn2, mask is an integer array of size n2.
|}

<tt>sfheadercut</tt> is close to <tt>sfheaderwindow</tt> but instead
of windowing the dataset, it fills the traces specified by the header
mask with zeroes. The size of the input data is preserved.
Here is an example of using <tt>sfheaderwindow</tt> for
zeroing every other trace in the input file. First, let us create
an input file with ten traces:
<pre>
bash$ sfmath n1=5 n2=10 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
35: 8 8 8 8 8
40: 9 9 9 9 9
45: 10 10 10 10 10
</pre>
Next, we can create a mask with alternating ones and zeros using
<tt>sfinterleave</tt>.
<pre>
bash$ sfspike n1=5 mag=1 | sfdd type=int > ones.rsf
bash$ sfspike n1=5 mag=0 | sfdd type=int > zeros.rsf
bash$ sfinterleave axis=1 ones.rsf zeros.rsf > mask.rsf
bash$ sfdisfil < mask.rsf
0: 1 0 1 0 1 0 1 0 1 0
</pre>
Finally, <tt>sfheadercut</tt> zeros the input traces.
<pre>
bash$ sfheadercut < input.rsf mask=mask.rsf > output.rsf
bash$ sfdisfil < output.rsf
0: 1 1 1 1 1
5: 0 0 0 0 0
10: 3 3 3 3 3
15: 0 0 0 0 0
20: 5 5 5 5 5
25: 0 0 0 0 0
30: 7 7 7 7 7
35: 0 0 0 0 0
40: 9 9 9 9 9
45: 0 0 0 0 0
</pre>

==sfheadersort==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Sort a dataset according to a header key.
|-
! colspan="4" | sfheadersort < in.rsf > out.rsf head=
|-
| ''string '' || '''head=''' || || header file
|}

<tt>sfheadersort</tt> is used to sort traces in the input file
according to trace header information.
Here is an example of using
<tt>sfheadersort</tt> for randomly shuffling traces in the input
file. First, let us create an input file with seven traces:
<pre>
bash$ sfmath n1=5 n2=7 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
</pre>
Next, we can create a random file with seven header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=7 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
0: 0.05256 -0.2879 0.1487 0.4097 0.1548
5: 0.4501 0.2836
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally, we
apply <tt>sfheadersort</tt> to shuffle the input traces.
<pre>
bash$ < input.rsf sfheadersort head=random.rsf > output.rsf
bash$ < output.rsf sfdisfil
0: 2 2 2 2 2
5: 1 1 1 1 1
10: 3 3 3 3 3
15: 5 5 5 5 5
20: 7 7 7 7 7
25: 4 4 4 4 4
30: 6 6 6 6 6
</pre>
As expected, the order of traces in the output file corresponds to the
order of values in the header. Thanks to the separation between
headers and data, the operation of <tt>sfheadersort</tt> is optimally
efficient. It first sorts the headers and only then accesses the data,
reading each data trace only once.

==sfheaderwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a dataset based on a header mask.
|-
! colspan="4" | sfheaderwindow mask=head.rsf < in.rsf > out.rsf
|-
| colspan="4" | The input data is a collection of traces n1xn2, mask is an integer array os size n2, windowed is n1xm2, where m2 is the number of nonzero elements in mask.
|}

<tt>sfheaderwindow</tt> is used to window traces in the input file
according to trace header information.
Here is an example of using <tt>sfheaderwindow</tt> for randomly
selecting part of the traces in the input file. First, let us create
an input file with ten traces:
<pre>
bash$ sfmath n1=5 n2=10 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 3 3 3 3 3
15: 4 4 4 4 4
20: 5 5 5 5 5
25: 6 6 6 6 6
30: 7 7 7 7 7
35: 8 8 8 8 8
40: 9 9 9 9 9
45: 10 10 10 10 10
</pre>
Next, we can create a random file with ten header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=10 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
0: -0.005768 0.02258 -0.04331 -0.4129 -0.3909
5: -0.03582 0.4595 -0.3326 0.498 -0.3517
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally,
we apply <tt>sfheaderwindow</tt> to window the input traces selecting
only those for which the header is greater than zero.
<pre>
bash$ < random.rsf sfmask min=0 > mask.rsf
bash$ < mask.rsf sfdisfil
0: 0 1 0 0 0 0 1 0 1 0
bash$ < input.rsf sfheaderwindow mask=mask.rsf > output.rsf
bash$ < output.rsf sfdisfil
0: 2 2 2 2 2
5: 7 7 7 7 7
10: 9 9 9 9 9
</pre>
In this case, only three traces are selected for the output. Thanks to
the separation between headers and data, the operation of
<tt>sfheaderwindow</tt> is optimally efficient.

==sfin==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display basic information about RSF files.
|-
! colspan="4" | sfin info=y check=2. trail=y file1.rsf file2.rsf ...
|-
| colspan="4" | n1,n2,... are data dimensions o1,o2,... are axis origins d1,d2,... are axis sampling intervals label1,label2,... are axis labels unit1,unit2,... are axis units
|-
| ''float '' || '''check=2.''' || || Portion of the data (in Mb) to check for zero values.
|-
| ''bool '' || '''info=y''' || [y/n] || If n, only display the name of the data file.
|-
| ''bool '' || '''trail=y''' || [y/n] || If n, skip trailing dimensions of one
|}

<tt>sfin</tt> is one of the most useful programs for operating with
RSF files. It produces quick information on the file hypercube
dimensions and checks the consistency of the associated data file.
Here is an example. Let us create an RSF file and examine it with <tt>sfin</tt>.
<pre>
bash$ sfspike n1=100 n2=20 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/tmp/spike.rsf@"
esize=4 type=float form=native
n1=100 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
2000 elements 8000 bytes
</pre>
<tt>sfin</tt> reports the following information:

*location of the data file (<tt>/tmp/spike.rsf\@</tt>)
*element size (4 bytes)
*element type (floating point)
*element form (native)
*hypercube dimensions (100 by 20)
*axes scale (0.004 and 0.1)
*axes origin (0 and 0)
*axes labels
*axes units
*total number of elements
*total number of bytes in the data file
Suppose that the file got corrupted by a buggy program and reports
incorrect dimensions. The <tt>sfin</tt> program should be able to
catch the discrepancy.
<pre>
bash$ echo n2=100 >> spike.rsf
bash$ sfin spike.rsf > /dev/null
sfin: Actually 8000 bytes, 20% of expected.
</pre>
<tt>sfin</tt> also checks the first records in the file for zeros.
<pre>
bash$ sfspike n1=100 n2=100 k2=99 > spike2.rsf
bash$ sfin spike2.rsf >/dev/null
sfin: The first 32768 bytes are all zeros
</pre>
The number of bytes to check is adjustable
<pre>
bash$ sfin spike2.rsf check=0.01 >/dev/null
sfin: The first 16384 bytes are all zeros
</pre>
You can also output only the location of the data file. This is
sometimes handy in scripts.
<pre>
bash$ sfin spike.rsf spike2.rsf info=n
/tmp/spike.rsf@ /tmp/spike2.rsf@
</pre>
An alternative is to use <tt>sfget</tt>, as follows:
<pre>
bash$ sfget parform=n in < spike.rsf
/tmp/spike.rsf@
</pre>
To actually eliminate annoying trailing dimensions of length one (not just stop displaying them with <tt>trail=n</tt>), you may use <tt>sed</tt>. Example for eliminating axis 6:
<bash>
sed -i 's/n6=1//g' file.rsf
</bash>

==sfinterleave==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Combine several datasets by interleaving.
|-
! colspan="4" | sfinterleave > out.rsf axis=3 [< file0.rsf] file1.rsf file2.rsf ...
|-
| ''int '' || '''axis=3''' || || Axis for interleaving
|}

<tt>sfinterleave</tt> combines two or more datasets by interleaving them on one
of the axes. Here is a quick example:
<pre>
bash$ sfspike n1=5 n2=5 > one.rsf
bash$ sfdisfil < one.rsf
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ sfscale < one.rsf dscale=2 > two.rsf
bash$ sfdisfil < two.rsf
0: 2 2 2 2 2
5: 2 2 2 2 2
10: 2 2 2 2 2
15: 2 2 2 2 2
20: 2 2 2 2 2
bash$ sfinterleave one.rsf two.rsf axis=1 | sfdisfil
0: 1 2 1 2 1
5: 2 1 2 1 2
10: 1 2 1 2 1
15: 2 1 2 1 2
20: 1 2 1 2 1
25: 2 1 2 1 2
30: 1 2 1 2 1
35: 2 1 2 1 2
40: 1 2 1 2 1
45: 2 1 2 1 2
bash$ sfinterleave < one.rsf two.rsf axis=2 | sfdisfil
0: 1 1 1 1 1
5: 2 2 2 2 2
10: 1 1 1 1 1
15: 2 2 2 2 2
20: 1 1 1 1 1
25: 2 2 2 2 2
30: 1 1 1 1 1
35: 2 2 2 2 2
40: 1 1 1 1 1
45: 2 2 2 2 2
</pre>

==sfmask==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Create a mask.
|-
! colspan="4" | sfmask < in.rsf > out.rsf min=-FLT_MAX max=+FLT_MAX
|-
| colspan="4" | Mask is an integer data with ones and zeros. Ones correspond to input values between min and max. The output can be used with sfheaderwindow.
|-
| ''float '' || '''max=+FLT_MAX''' || || maximum header value
|-
| ''float '' || '''min=-FLT_MAX''' || || minimum header value
|}

<tt>sfmask</tt> creates an integer output of ones and zeros comparing
the values of the input data to specified <tt>min=</tt> and
<tt>max=</tt> parameters. It is useful for <tt>sfheaderwindow</tt> and
in many other applications. Here is a quick example:
<pre>
bash$ sfmath n1=10 output="sin(x1)" > sin.rsf
bash$ < sin.rsf sfdisfil
0: 0 0.8415 0.9093 0.1411 -0.7568
5: -0.9589 -0.2794 0.657 0.9894 0.4121
bash$ < sin.rsf sfmask min=-0.5 max=0.5 | sfdisfil
0: 1 0 0 1 0 0 1 0 0 1
</pre>

==sfmath==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Mathematical operations on data files.
|-
! colspan="4" | sfmath > out.rsf type= unit= output=
|-
| colspan="4" | Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs, conj (for complex data). sfmath will work on float or complex data, but all the input and output files must be of the same data type. An alternative to sfmath is sfadd, which may be more efficient, but is less versatile. Examples: sfmath x=file1.rsf y=file2.rsf power=file3.rsf output='sin((x+2*y)^power)' > out.rsf sfmath < file1.rsf tau=file2.rsf output='exp(tau*input)' > out.rsf sfmath n1=100 type=complex output="exp(I*x1)" > out.rsf See also: sfheadermath.
|-
| ''string '' || '''output=''' || || Mathematical description of the output
|-
| ''string '' || '''type=''' || || output data type [float,complex]
|-
| ''string '' || '''unit=''' || ||
|}

<tt>sfmath</tt> is a versatile program for mathematical operations
with RSF files. It can operate with several input file, all of the
same dimensions and data type. The data type can be real (floating
point) or complex. Here is an example that demonstrates several
features of <tt>sfmath</tt>.
<pre>
bash$ sfmath n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5 \
output="x2*(8+sin(6*x1+x2/10))" > rad.rsf
bash$ < rad.rsf sfrtoc | sfmath output="input*exp(I*x1)" > rose.rsf
bash$ < rose.rsf sfgraph title=Rose screenratio=1 wantaxis=n | sfpen
</pre>
The first line creates a 2-D dataset that consists of 40 traces 629
samples each. The values of the data are computed with the formula
"x2*(8+sin(6*x1+x2/10))", where <tt>x1</tt> refers to the
coordinate on the first axis, and <tt>x2</tt> is the coordinate of the
second axis. In the second line, we convert the data from real to
complex using <tt>sfrtoc</tt> and produce a complex dataset using
formula "input*exp(I*x1)", where <tt>input</tt> refers to the
input file. Finally, we plot the complex data as a collection of
parametric curves using <tt>sfgraph</tt> and display the result using
<tt>sfpen</tt>. The plot appearing on your screen should look similar
to the figure.
[[Image:rose.png|frame|center|This figure was created with <tt>sfmath</tt>.]]
One possible alternative to the second line above is
<pre>
bash$ < rad.rsf sfmath output=x1 > ang.rsf
bash$ sfmath r=rad.rsf a=ang.rsf output="r*cos(a)" > cos.rsf
bash$ sfmath r=rad.rsf a=ang.rsf output="r*sin(a)" > sin.rsf
bash$ sfcmplx cos.rsf sin.rsf > rose.rsf
</pre>
Here we refer to input files by names (<tt>r</tt> and <tt>a</tt>) and combine the names in a formula.

==sfpad==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Pad a dataset with zeros.
|-
! colspan="4" | sfpad < in.rsf > out.rsf [beg1= beg2= ... end1= end2=... | n1= n2 = ... | n1out= n2out= ...]
|-
| colspan="4" | begN specifies the number of zeros to add before the beginning of axis N. endN specifies the number of zeros to add after the end of axis N. Alternatively: nN or nNout specify the output length of axis N, padding occurs at the end. nN and nNout are equivalent.
|}

<tt>pad</tt> increases the dimensions of the input dataset by padding
the data with zeroes. Here are some simple examples.
<pre>
bash$ sfspike n1=5 n2=3 > one.rsf
bash$ sfdisfil < one.rsf
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
bash$ < one.rsf sfpad n2=5 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 0 0 0 0 0
20: 0 0 0 0 0
bash$ < one.rsf sfpad beg2=2 | sfdisfil
0: 0 0 0 0 0
5: 0 0 0 0 0
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 1 1 1 1 1
bash$ < one.rsf sfpad beg2=1 end2=1 | sfdisfil
0: 0 0 0 0 0
5: 1 1 1 1 1
10: 1 1 1 1 1
15: 1 1 1 1 1
20: 0 0 0 0 0
bash$ < one.rsf sfwindow n1=3 | sfpad n1=5 n2=5 beg1=1 beg2=1 | sfdisfil
0: 0 0 0 0 0
5: 0 1 1 1 0
10: 0 1 1 1 0
15: 0 1 1 1 0
20: 0 0 0 0 0
</pre>
You can use <tt>sfcat</tt> to pad data with values other than zeroes.

==sfput==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Input parameters into a header.
|-
! colspan="4" | sfput < in.rsf > out.rsf
|}

<tt>sfput</tt> is a very simple program. It simply appends parameters
from the command line to the output RSF file. One can achieve similar
results with editing by hand or with standard Unix utilities like
<tt>sed</tt> and <tt>echo</tt>. <tt>sfput</tt> is sometimes more
convenient because it handles input/output operations similarly to
other regular RSF programs.
<pre>
bash$ sfspike n1=10 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/tmp/spike.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
10 elements 40 bytes
bash$ sfput < spike.rsf d1=25 label1=Depth unit1=m > spike2.rsf
bash$ sfin spike2.rsf
spike2.rsf:
in="/tmp/spike2.rsf@"
esize=4 type=float form=native
n1=10 d1=25 o1=0 label1="Depth" unit1="m"
10 elements 40 bytes
</pre>

==sfreal==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
|-
! colspan="4" | sfreal < cmplx.rsf > real.rsf
|}

<tt>sfreal</tt> extracts the real part of a complex type dataset. The
imaginary part can be extracted with <tt>sfimag</tt>, an the real
and imaginary part can be combined together with <tt>sfcmplx</tt>.
Here is a simple example. Let us first create a complex dataset
with <tt>sfmath</tt>
<pre>
bash$ sfmath n1=10 type=complex output="(2+I)*x1" > cmplx.rsf
bash$ fdisfil < cmplx.rsf
0: 0, 0i 2, 1i 4, 2i
3: 6, 3i 8, 4i 10, 5i
6: 12, 6i 14, 7i 16, 8i
9: 18, 9i
</pre>
Extracting the real part with <tt>sfreal</tt>:
<pre>
bash$ sfreal < cmplx.rsf | sfdisfil
0: 0 2 4 6 8
5: 10 12 14 16 18
</pre>
Extracting the imaginary part with <tt>sfimag</tt>:
<pre>
bash$ sfimag < cmplx.rsf | sfdisfil
0: 0 1 2 3 4
5: 5 6 7 8 9
</pre>

==sfreverse==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Reverse one or more axes in the data hypercube.
|-
! colspan="4" | sfreverse < in.rsf > out.rsf which=-1 verb=false memsize=sf_memsize() opt=
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''string '' || '''opt=''' || || If y, change o and d parameters on the reversed axis;
:if i, don't change o and d
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|-
| ''int '' || '''which=-1''' || || Which axis to reverse.
:To reverse a given axis, start with 0,
:add 1 to number to reverse n1 dimension,
:add 2 to number to reverse n2 dimension,
:add 4 to number to reverse n3 dimension, etc.
:Thus, which=7 would reverse the first three dimensions,
:which=5 just n1 and n3, etc.
:which=0 will just pass the input on through unchanged.
|}
Here is an example of using <tt>sfreverse</tt>. First, let us create a
2-D dataset.
<pre>
bash$ sfmath n1=5 d1=1 n2=3 d2=1 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
</pre>
Reversing the first axis:
<pre>
bash$ < test.rsf sfreverse which=1 | sfdisfil
0: 4 3 2 1 0
5: 5 4 3 2 1
10: 6 5 4 3 2
</pre>
Reversing the second axis:
<pre>
bash$ < test.rsf sfreverse which=2 | sfdisfil
0: 2 3 4 5 6
5: 1 2 3 4 5
10: 0 1 2 3 4
</pre>
Reversing both the first and the second axis:
<pre>
bash$ < test.rsf sfreverse which=3 | sfdisfil
0: 2 3 4 5 6
5: 1 2 3 4 5
10: 0 1 2 3 4
</pre>
As you can see, the <tt>which=</tt> parameter controls the axes that are
being reversed by encoding them into one number.
When an axis is reversed, what happens with its axis origin and
sampling parameters? This behavior is controlled by <tt>opt=</tt>. In
our example,
<pre>
bash$ < test.rsf sfget n1 o1 d1
n1=5
o1=0
d1=1
bash$ < test.rsf sfreverse which=1 | sfget o1 d1
o1=4
d1=-1
</pre>
The default behavior (equivalent to <tt>opt=y</tt>) puts the origin
<tt>o1</tt> at the end of the axis and reverses the sampling parameter
<tt>d1</tt>. Using <tt>opt=n</tt> preserves the sampling but reverses
the origin.
<pre>
bash$ < test.rsf sfreverse which=1 opt=n | sfget o1 d1
o1=-4
d1=1
</pre>
Using <tt>opt=i</tt> preserves both the sampling and the origin while
reversing the axis.
<pre>
bash$ < test.rsf sfreverse which=1 opt=i | sfget o1 d1
o1=0
d1=1
</pre>
One of the three possible behaviors may be desirable depending on the
application.

==sfrm==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Remove RSF files together with their data.
|-
! colspan="4" | sfrm file1.rsf [file2.rsf ...] [-i] [-v] [-f]
|-
| colspan="4" | Mimics the standard Unix rm command. See also: sfmv, sfcp.
|}

<tt>sfrm</tt> is a program for removing RSF files. Its arguments mimic
the arguments of the standard Unix <tt>rm</tt> utility: <tt>-v</tt>
for verbosity, <tt>-i</tt> for interactive inquiry, <tt>-f</tt> for
force removal of suspicious files. Unlike the Unix <tt>rm</tt>,
<tt>sfrm</tt> removes both the RSF header files and the binary files
that the headers point to.
Example:
<pre>
bash$ sfspike n1=10 > spike.rsf datapath=./
bash$ sfget in < spike.rsf
in=./spike.rsf@
bash$ ls spike*
spike.rsf spike.rsf@
bash$ sfrm -v spike.rsf
sfrm: sf_rm: Removing header spike.rsf
sfrm: sf_rm: Removing data ./spike.rsf@
bash$ ls spike*
ls: No match.
</pre>
==sfrotate==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Rotate a portion of one or more axes in the data hypercube.
|-
! colspan="4" | sfrotate < in.rsf > out.rsf verb=n memsize=sf_memsize() rot#=(0,0,...)
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''int '' || '''rot#=(0,0,...)''' || || length of #-th axis that is moved to the end
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

<tt>sfrotate</tt> modifies the input dataset by splitting it into
parts and putting the parts back in a different order. Here is a quick example.
<pre>
bash$ sfmath n1=5 d1=1 n2=3 d2=1 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
</pre>
Rotating the first axis by putting the last two columns in front:
<pre>
bash$ < test.rsf sfrotate rot1=2 | sfdisfil
0: 3 4 0 1 2
5: 4 5 1 2 3
10: 5 6 2 3 4
</pre>
Rotating the second axis by putting the last row in front:
<pre>
bash$ < test.rsf sfrotate rot2=1 | sfdisfil
0: 2 3 4 5 6
5: 0 1 2 3 4
10: 1 2 3 4 5
</pre>
Rotating both the first and the second axis:
<pre>
bash$ < test.rsf sfrotate rot1=3 rot2=1 | sfdisfil
0: 4 5 6 2 3
5: 2 3 4 0 1
10: 3 4 5 1 2
</pre>
The transformation is shown schematically in Figure~(fig:rotate).
[[Image:rotate.png|frame|center|Schematic transformation of data with <tt>sfrotate</tt>.]]

==sfrtoc==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert real data to complex (by adding zero imaginary part).
|-
! colspan="4" | sfrtoc < real.rsf > cmplx.rsf
|-
| colspan="4" | See also: sfcmplx
|}
The input to <tt>sfrtoc</tt> can be any <tt>type=float</tt> dataset:
<pre>
bash$ sfspike n1=10 n2=20 n3=30 >real.rsf
bash$ sfin real.rsf
real.rsf:
in="/var/tmp/real.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
</pre>
The output dataset will have <tt>type=complex</tt>, and its binary will be twice the size of the input:
<pre>
bash$ <real.rsf sfrtoc >complex.rsf
bash$ sfin complex.rsf
complex.rsf:
in="/var/tmp/complex.rsf@"
esize=8 type=complex form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 48000 bytes
</pre>

==sfscale==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Scale data.
|-
! colspan="4" | sfscale < in.rsf > out.rsf axis=0 rscale=0. dscale=1.
|-
| colspan="4" | To scale by a constant factor, you can also use sfmath or sfheadermath.
|-
| ''int '' || '''axis=0''' || || Scale by maximum in the dimensions up to this axis.
|-
| ''float '' || '''dscale=1.''' || || Scale by this factor (works if rscale=0)
|-
| ''float '' || '''rscale=0.''' || || Scale by this factor.
|}
<tt>sfscale</tt> scales the input dataset by a factor. Here
are some simple examples. First, let us create a test dataset.
<pre>
bash$ sfmath n1=5 n2=3 o1=1 o2=1 output="x1*x2" > test.rsf
bash$ < test.rsf sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
10: 3 6 9 12 15
</pre>
Scale every data point by 2:
<pre>
bash$ < test.rsf sfscale dscale=2 | sfdisfil
0: 2 4 6 8 10
5: 4 8 12 16 20
10: 6 12 18 24 30
</pre>
Divide every trace by its maximum value:
<pre>
bash$ < test.rsf sfscale axis=1 | sfdisfil
0: 0.2 0.4 0.6 0.8 1
5: 0.2 0.4 0.6 0.8 1
10: 0.2 0.4 0.6 0.8 1
</pre>
Divide by the maximum value in the whole 2-D dataset:
<pre>
bash$ < test.rsf sfscale axis=2 | sfdisfil
0: 0.06667 0.1333 0.2 0.2667 0.3333
5: 0.1333 0.2667 0.4 0.5333 0.6667
10: 0.2 0.4 0.6 0.8 1
</pre>
The <tt>rscale=</tt> parameter is synonymous to <tt>dscale=</tt> except
when it is equal to zero. With <tt>sfscale dscale=0</tt>, the dataset gets
multiplied by zero. If using <tt>rscale=0</tt>, the other parameters are
used to define scaling. Thus, <tt>sfscale rscale=0 axis=1</tt> is
equivalent to <tt>sfscale axis=1</tt>, and <tt>sfscale rscale=0</tt>
is equivalent to <tt>sfscale dscale=1</tt>.

==sfspike==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate simple data: spikes, boxes, planes, constants.
|-
! colspan="4" | sfspike > spike.rsf mag= nsp=1 k#=[0,...] l#=[k1,k2,...] p#=[0,...] n#= o#=[0,0,...] d#=[0.004,0.1,0.1,...] label#=[Time,Distance,Distance,...] unit#=[s,km,km,...] title=
|-
| colspan="4" | Spike positioning is given in samples and starts with 1.
|-
| ''float '' || '''d#=[0.004,0.1,0.1,...]''' || || sampling on #-th axis
|-
| ''ints '' || '''k#=[0,...]''' || || spike starting position [nsp]
|-
| ''ints '' || '''l#=[k1,k2,...]''' || || spike ending position [nsp]
|-
| ''string '' || '''label#=[Time,Distance,Distance,...]''' || || label on #-th axis
|-
| ''floats '' || '''mag=''' || || spike magnitudes [nsp]
|-
| ''int '' || '''n#=''' || || size of #-th axis
|-
| ''int '' || '''nsp=1''' || || Number of spikes
|-
| ''float '' || '''o#=[0,0,...]''' || || origin on #-th axis
|-
| ''floats '' || '''p#=[0,...]''' || || spike inclination (in samples) [nsp]
|-
| ''string '' || '''title=''' || || title for plots
|-
| ''string '' || '''unit#=[s,km,km,...]''' || || unit on #-th axis
|}

<tt>sfspike</tt> takes no input and generates an output with
"spikes". It is an easy way to create data. Here is an example:
<pre>
bash$ sfspike n1=5 n2=3 k1=4 k2=1 | sfdisfil
0: 0 0 0 1 0
5: 0 0 0 0 0
10: 0 0 0 0 0
</pre>
The spike location is specified by parameters <tt>k1=4</tt> and
<tt>k2=1</tt>. Note that the locations are numbered starting from 1.
If one of the parameters is omitted or given the value of zero, the
spike in the corresponding direction becomes a plane:
<pre>
bash$ sfspike n1=5 n2=3 k1=4 | sfdisfil
0: 0 0 0 1 0
5: 0 0 0 1 0
10: 0 0 0 1 0

</pre>
If no spike parameters are given, the whole dataset is filled with ones:
<pre>
bash$ sfspike n1=5 n2=3 | sfdisfil
0: 1 1 1 1 1
5: 1 1 1 1 1
10: 1 1 1 1 1
</pre>
To create several spikes, use the <tt>nsp=</tt> parameter and give a comma-separated list of values to <tt>k#=</tt> arguments:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 | sfdisfil
0: 1 0 0 0 0
5: 0 0 1 0 0
10: 0 0 0 1 0
</pre>
If the number of values in the list is smaller than <tt>nsp</tt>, the
last value gets repeated, and the spikes add on top of each other,
creating larger amplitudes:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3 k2=1,2 | sfdisfil
0: 1 0 0 0 0
5: 0 0 2 0 0
10: 0 0 0 0 0
</pre>
The magnitude of the spikes can be controlled explicitly with the
<tt>mag=</tt> parameter:
<pre>
bash$ sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 mag=1,4,2 | sfdisfil
0: 1 0 0 0 0
5: 0 0 4 0 0
10: 0 0 0 2 0
</pre>
You can create boxes instead of spikes by using <tt>l#=</tt>
parameters:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 l1=4 k2=2 mag=8 | sfdisfil
0: 0 0 0 0 0
5: 0 8 8 8 0
10: 0 0 0 0 0
</pre>
In this case, <tt>k1=2</tt> specifies the box start, and <tt>l1=4</tt>
specifies the box end.
Finally, multi-dimensional planes can be given an inclination by using <tt>p#=</tt> parameters:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 p2=1 | sfdisfil
0: 0 1 0 0 0
5: 0 0 1 0 0
10: 0 0 0 1 0
</pre>
Note that <tt>sfspike</tt> interprets the <tt>p#=</tt> parameters in stepout from sample to sample, not in terms of axes units (i.e. s/m).

More than one p parameter can be specified. In this case, a (hyper) plane will be created.

When the inclination value is not integer, simple linear interpolation is used:
<pre>
bash$ sfspike n1=5 n2=3 k1=2 p2=0.7 | sfdisfil
0: 0 1 0 0 0
5: 0 0.3 0.7 0 0
10: 0 0 0.6 0.4 0
</pre>
<tt>sfspike</tt> supplies default dimensions and labels to all axis:
<pre>
bash$ sfspike n1=5 n2=3 n3=4 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=5 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=4 d3=0.1 o3=0 label3="Distance" unit3="km"
60 elements 240 bytes
</pre>
As you can see, the first axis is assumed to be time, with sampling of
<math>0.004</math> seconds. All other axes are assumed to be distance, with
sampling of <math>0.1</math> kilometers. All these parameters can be changed on
the command line.
<pre>
bash$ sfspike n1=5 n2=3 n3=4 label3=Offset unit3=ft d3=20 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=5 d1=0.004 o1=0 label1="Time" unit1="s"
n2=3 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=4 d3=20 o3=0 label3="Offset" unit3="ft"
60 elements 240 bytes
</pre>

==sfspray==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Extend a dataset by duplicating in the specified axis dimension.
|-
! colspan="4" | sfspray < in.rsf > out.rsf axis=2 n= d= o= label= unit=
|-
| colspan="4" | This operation is adjoint to sfstack.
|-
| ''int '' || '''axis=2''' || || which axis to spray
|-
| ''float '' || '''d=''' || || Sampling of the newly created dimension
|-
| ''string '' || '''label=''' || || Label of the newly created dimension
|-
| ''int '' || '''n=''' || || Size of the newly created dimension
|-
| ''float '' || '''o=''' || || Origin of the newly created dimension
|-
| ''string '' || '''unit=''' || || Units of the newly created dimension
|}

<tt>sfspray</tt> extends the input hypercube by replicating the data
in one of the dimensions. The output dataset acquires one additional
dimension. Here is an example:
Start with a 2-D dataset
<pre>
bash$ sfmath n1=5 n2=2 output=x1+x2 > test.rsf
bash$ sfin test.rsf
test.rsf:
in="/var/tmp/test.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=2 d2=1 o2=0
10 elements 40 bytes
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
</pre>
Extend the data in the second dimension
<pre>
bash$ < test.rsf sfspray axis=2 n=3 > test2.rsf
bash$ sfin test2.rsf
test2.rsf:
in="/var/tmp/test2.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=3 d2=1 o2=0
n3=2 d3=1 o3=0
30 elements 120 bytes
bash$ < test2.rsf sfdisfil
0: 0 1 2 3 4
5: 0 1 2 3 4
10: 0 1 2 3 4
15: 1 2 3 4 5
20: 1 2 3 4 5
25: 1 2 3 4 5
</pre>
The output is three-dimensional, with traces from the original
data duplicated along the second axis.
Extend the data in the third dimension
<pre>
bash$ < test.rsf sfspray axis=3 n=2 > test3.rsf
bash$ sfin test3.rsf
test3.rsf:
in="/var/tmp/test3.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0
n2=2 d2=1 o2=0
n3=2 d3=? o3=?
20 elements 80 bytes
bash$ < test3.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 0 1 2 3 4
15: 1 2 3 4 5
</pre>
The output is also three-dimensional, with the original data replicated
along the third axis.

==sfstack==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Stack a dataset over one of the dimensions.
|-
! colspan="4" | sfstack < in.rsf > out.rsf axis=2 rms=n norm=y min=n max=n
|-
| colspan="4" | This operation is adjoint to sfspray.
|-
| ''int '' || '''axis=2''' || || which axis to stack
|-
| ''bool '' || '''max=n''' || [y/n] || If y, find maximum instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''min=n''' || [y/n] || If y, find minimum instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''norm=y''' || [y/n] || If y, normalize by fold.
|-
| ''bool '' || '''rms=n''' || [y/n] || If y, compute the root-mean-square instead of stack.
|}
While <tt>sfspray</tt> adds a dimension to a hypercube,
<tt>sfstack</tt> effectively removes one of the dimensions by stacking
over it. Here are some examples:
<pre>
bash$ sfmath n1=5 n2=3 output=x1+x2 > test.rsf
bash$ < test.rsf sfdisfil
0: 0 1 2 3 4
5: 1 2 3 4 5
10: 2 3 4 5 6
bash$ < test.rsf sfstack axis=2 | sfdisfil
0: 1.5 2 3 4 5
bash$ < test.rsf sfstack axis=1 | sfdisfil
0: 2.5 3 4
</pre>
Why is the first value not 1 (in the first case) or 2 (in the second
case)? By default, <tt>sfstack</tt> normalizes the stack by the fold
(the number of non-zero entries). To avoid normalization, use
<tt>norm=n</tt>, as follows:
<pre>
bash$ < test.rsf sfstack norm=n | sfdisfil
0: 3 6 9 12 15
</pre>
<tt>sfstack</tt> can also compute root-mean-square values as
well as minimum and maximum values.
<pre>
bash$ < test.rsf sfstack rms=y | sfdisfil
0: 1.581 2.16 3.109 4.082 5.066
bash$ < test.rsf sfstack min=y | sfdisfil
0: 0 1 2 3 4
bash$ < test.rsf sfstack axis=1 max=y | sfdisfil
0: 4 5 6
</pre>

==sftransp==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Transpose two axes in a dataset.
|-
! colspan="4" | sftransp < in.rsf > out.rsf memsize=sf_memsize() plane=
|-
| colspan="4" | If you get a "Cannot allocate memory" error, give the program a memsize=1 command-line parameter to force out-of-core operation.
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''int '' || '''plane=''' || || Two-digit number with axes to transpose. The default is 12
|}

The <tt>sftransp</tt> program transposes the input hypercube
exchanging the two axes specified by the plane= parameter.
<pre>
bash$ sfspike n1=10 n2=20 n3=30 > orig123.rsf
bash$ sfin orig123.rsf
orig123.rsf:
in="/var/tmp/orig123.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=30 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
bash$ <orig123.rsf sftransp plane=23 >out132.rsf
bash$ sfin out132.rsf
out132.rsf:
in="/var/tmp/out132.rsf@"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
n2=30 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=20 d3=0.1 o3=0 label3="Distance" unit3="km"
6000 elements 24000 bytes
bash$ <orig123.rsf sftransp plane=13 >out321.rsf
bash$ sfin out321.rsf
out321.rsf:
in="/var/tmp/out132.rsf@"
esize=4 type=float form=native
n1=30 d1=0.1 o1=0 label1="Distance" unit1="km"
n2=20 d2=0.1 o2=0 label2="Distance" unit2="km"
n3=10 d3=0.004 o3=0 label3="Time" unit3="s"
6000 elements 24000 bytes
</pre>
<tt>sftransp</tt> tries to fit the dataset in memory to transpose it
there but, if not enough memory is available, it performs a slower
transpose out of core using disk operations. You can control the
amount of available memory using the memsize= parameter or
the RSFMEMSIZE environmental variable.

==sfwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a portion of the dataset.
|-
! colspan="4" | sfwindow < in.rsf > out.rsf verb=n squeeze=y j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''int '' || '''f#=(0,...)''' || || window start in #-th dimension
|-
| ''int '' || '''j#=(1,...)''' || || jump in #-th dimension
|-
| ''float '' || '''max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)''' || || maximum in #-th dimension
|-
| ''float '' || '''min#=(o1,o2,,...)''' || || minimum in #-th dimension
|-
| ''int '' || '''n#=(0,...)''' || || window size in #-th dimension
|-
| ''bool '' || '''squeeze=y''' || [y/n] || if y, squeeze dimensions equal to 1 to the end
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

sfwindow is used to window a portion of the dataset. Here is
a quick example: Start by creating some data.
<pre>
bash$ sfmath n1=5 n2=3 o1=1 o2=1 output="x1*x2" > test.rsf
bash$ < test.rsf sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
10: 3 6 9 12 15
</pre>
Now window the first two rows:
<pre>
bash$ < test.rsf sfwindow n2=2 | sfdisfil
0: 1 2 3 4 5
5: 2 4 6 8 10
</pre>
Window the first three columns:
<pre>
bash$ < test.rsf sfwindow n1=3 | sfdisfil
0: 1 2 3 2 4
5: 6 3 6 9
</pre>
Window the middle row:
<pre>
bash$ < test.rsf sfwindow f2=1 n2=1 | sfdisfil
0: 2 4 6 8 10
</pre>
You can interpret the f# and n# parameters as
meaning "skip that many rows/columns" and "select that many
rows/columns" correspondingly. Window the middle point in the dataset:
<pre>
bash$ < test.rsf sfwindow f1=2 n1=1 f2=1 n2=1 | sfdisfil
0: 6
</pre>
Window every other column:
<pre>
bash$ < test.rsf sfwindow j1=2 | sfdisfil
0: 1 3 5 2 6
5: 10 3 9 15
</pre>
Window every third column:
<pre>
bash$ < test.rsf sfwindow j1=3 | sfdisfil
0: 1 4 2 8 3
5: 12
</pre>
Alternatively, sfwindow can use the minimum and maximum
parameters to select a window. In the following example, we are
creating a dataset with sfspike and then windowing a portion of it
between 1 and 2 seconds in time and sampled at 8 miliseconds.
<pre>
bash$ sfspike n1=1000 n2=10 > spike.rsf
bash$ sfin spike.rsf
spike.rsf:
in="/var/tmp/spike.rsf@"
esize=4 type=float form=native
n1=1000 d1=0.004 o1=0 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
10000 elements 40000 bytes
bash$ < spike.rsf sfwindow min1=1 max1=2 d1=0.008 > window.rsf
bash$ sfin window.rsf
window.rsf:
in="/var/tmp/window.rsf@"
esize=4 type=float form=native
n1=126 d1=0.008 o1=1 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
1260 elements 5040 bytes
</pre>
By default, sfwindow "squeezes" the hypercube dimensions
that are equal to one toward the end of the dataset. Here is an
example of taking a time slice:
<pre>
bash$ < spike.rsf sfwindow n1=1 min1=1 > slice.rsf
bash$ sfin slice.rsf
slice.rsf:
in="/var/tmp/slice.rsf@"
esize=4 type=float form=native
n1=10 d1=0.1 o1=0 label1="Distance" unit1="km"
n2=1 d2=0.004 o2=1 label2="Time" unit2="s"
10 elements 40 bytes
</pre>
You can change this behavior by specifying squeeze=n.
<pre>
bash$ < spike.rsf sfwindow n1=1 min1=1 squeeze=n > slice.rsf
bash$ sfin slice.rsf
slice.rsf:
in="/var/tmp/slice.rsf@"
esize=4 type=float form=native
n1=1 d1=0.004 o1=1 label1="Time" unit1="s"
n2=10 d2=0.1 o2=0 label2="Distance" unit2="km"
10 elements 40 bytes
</pre>

=Seismic programs=
Programs in this category are specific for operations on seismic data. The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/seismic/ system/seismic] in the Madagascar distribution.

==sffkamo==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Computes Azimuth Move-Out (AMO) operator in the f-k log-stretch domain
|-
! colspan="4" | sffkamo < in.rsf > out.rsf h1= h2= f1= f2= maxe=10.
|-
| ''float '' || '''f1=''' || || input azimuth in degrees
|-
| ''float '' || '''f2=''' || || output azimuth in degrees
|-
| ''float '' || '''h1=''' || || input offset
|-
| ''float '' || '''h2=''' || || output offset
|-
| ''float '' || '''maxe=10.''' || || stability constraint
|}
Sample workflow from [http://m8r.info/RSF/book/sep/fkamo/paper_html/ SEP-110, 63-70 (2001)], with the addition of a bandpass for the input:

Create input -- a (t,x,y) common-offset cube:
<bash>
sfspike \
n1=128 o1=0.4 d1=0.0032 k1=65 label1=t \
n2=256 o2=-1.536 d2=0.012 k2=129 label2=x \
n3=128 o3=-1.024 d3=0.016 k3=65 label3=y | \
sfbandpass flo=5 fhi=60 > spikebps.rsf
</bash>

Apply log-stretch FFT:
<bash>
<spikebps.rsf sfstretch rule=L dens=4 |\
sffft1 |\
sffft3 axis=2 |\
sffft3 axis=3 > spikefft3.rsf
</bash>

Compute AMO operator for a file of the dimensions of <tt>spikefft3.rsf</tt>. The only information taken from stdin are the n, o, d parameters:
<bash>
<spikefft3.rsf sffkamo h2=2 f2=10 h1=1.8 f1=30 >oper.rsf
</bash>

Apply the operator by multiplication and fft back to (t, mx, my):
<bash>
< spikefft3.rsf sfadd mode=prod oper.rsf |\
sffft3 axis=3 inv=y |\
sffft3 axis=2 inv=y |\
sffft1 inv=y |\
sfstretch rule=L dens=4 inv=y > spikeamo.rsf
</bash>

Prepare for 8-bit greyscale visualization:
<bash>
< spikeamo.rsf sfbyte pclip=100 gainpanel=a > spikebyte.rsf
</bash>

Picture from the middle of the impulse response:
<bash>
<spikebyte.rsf sfgrey3 frame1=65 frame2=129 frame3=65 \
point1=0.333 title='AMO saddle, no f-k filter' | sfpen &
</bash>

Picture illustrating the artifacts (i.e. need for f-k filter):
<bash>
< spikebyte.rsf sfgrey3 frame1=65 frame2=97 frame3=97 \
point1=0.333 title='No f-k filter' | sfpen &
</bash>

Apply the f-k filter and (in this case) visualize:
<bash>
< spikeamo.rsf sffft1 |\
sffft3 axis=2 |\
sffft3 axis=3 |\
sfdipfilter v1=-2.5 v2=-1.5 v3=1.5 v4=2.5 taper=2 pass=0 dim=3 |\
sffft3 axis=3 inv=y |\
sffft3 axis=2 inv=y |\
sffft1 inv=y |\
sfbyte pclip=100 gainpanel=a |\
sfgrey3 frame1=65 frame2=97 frame3=97 point1=0.333 title='With f-k filter' |\
sfpen &
</bash>

==sfheaderattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Integer header attributes.
|-
! colspan="4" | sfheaderattr < head.rsf
|-
| colspan="4" | Only nonzero values are reported.
|}

The <tt>sfheaderattr</tt> examines the contents of a trace header file,
typically generated by <tt>sfsegyread</tt>. In the example below, we examine
trace headers in the output of <tt>suplane</tt>, a program from Seismic Unix.
<pre>
bash$ suplane > plane.su
bash$ sfsegyread tape=plane.su su=y tfile=tfile.rsf > plane.rsf
bash$ sfheaderattr < tfile.rsf
*******************************************
71 headers, 32 traces
key[0]="tracl" min[0]=1 max[31]=32 mean=16.5
key[1]="tracr" min[0]=1 max[31]=32 mean=16.5
key[11]="offset" min[0]=400 max[31]=400 mean=400
key[38]="ns" min[0]=64 max[31]=64 mean=64
key[39]="dt" min[0]=4000 max[31]=4000 mean=4000
*******************************************
</pre>
For different standard keywords, a minimum, maximum, and mean values
are reported unless they are identically zero. This quick inspection
can help in identifying meaningful keywords set in the data. The input
data type must be <tt>int</tt>.

==sfheadermath==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Mathematical operations, possibly on header keys.
|-
! colspan="4" | sfheadermath < in.rsf > out.rsf memsize=sf_memsize() output=
|-
| colspan="4" | Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs See also sfmath. An addition operation can be performed by sfstack.
|-
| ''int '' || '''memsize=sf_memsize()''' || || Max amount of RAM (in Mb) to be used
|-
| ''string '' || '''output=''' || || Describes the output in a mathematical notation.
|}
<tt>sfheadermath</tt> is a versatile program for mathematical
operations on rows of the input file. If the input file is an
<tt>n1</tt> by <tt>n2</tt> matrix, the output will be a <tt>1</tt> by
<tt>n2</tt> matrix that contains one row made out of mathematical
operations on the other rows. <tt>sfheadermath</tt> can identify a row
by number or by a standard SEGY keyword. The latter is useful for
processing headers extracted from SEGY or SU files.
Here is an example. First, we create an SU file with <tt>suplane</tt> and convert it to RSF using <tt>sfsegyread</tt>.
<pre>
bash$ suplane > plane.su
bash$ sfsegyread tape=plane.su su=y tfile=tfile.rsf > plane.rsf
</pre>
The trace header information is saved in <tt>tfile.rsf</tt>. It
contains 71 headers for 32 traces in integer format.
<pre>
bash$ sfin tfile.rsf
tfile.rsf:
in="/tmp/tfile.rsf@"
esize=4 type=int form=native
n1=71 d1=? o1=?
n2=32 d2=? o2=?
2272 elements 9088 bytes
</pre>
Next, we will convert <tt>tfile.rsf</tt> to a floating-point format
and run <tt>sfheadermath</tt> to create a new header.
<pre>
bash$ < tfile.rsf sfdd type=float | \
sfheadermath myheader=1 output="sqrt(myheader+(2+10*offset^2))" > new.rsf
bash$ sfin new.rsf
new.rsf:
in="/tmp/new.rsf@"
esize=4 type=float form=native
n1=1 d1=? o1=?
n2=32 d2=? o2=?
32 elements 128 bytes
</pre>
We defined "myheader" as being the row number 1 in the input (note
that numbering starts with 0) and combined it with "offset", which
is a standard SEGY keyword that denotes row number 11 (see the output
of <tt>sfheaderattr</tt> above.) A variety of mathematical expressions
can be defined in the <tt>output=</tt> string. The expression
processing engine is shared with <tt>sfmath</tt>.

==sfsegyheader==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Make a trace header file for segywrite.
|-
! colspan="4" | sfsegyheader < in.rsf > out.rsf n1= d1=
|-
| colspan="4" | Use the output for tfile= argument in segywrite.
|-
| ''float '' || '''d1=''' || || trace sampling
|-
| ''int '' || '''n1=''' || || number of samples in a trace
|}

==sfsegyread==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a SEG-Y or SU dataset to RSF.
|-
! colspan="4" | sfsegyread mask=msk.rsf > out.rsf tfile=hdr.rsf verb=n su= suxdr=n endian=y format=segyformat (bhead) ns=segyns (bhead) tape= read= hfile= bfile=
|-
| colspan="4" | Data headers and trace headers are separated from the data. "suread" is equivalent to "segyread su=y" SEGY key names: tracl: trace sequence number within line 0 tracr: trace sequence number within reel 4 fldr: field record number 8 tracf: trace number within field record 12 ep: energy source point number 16 cdp: CDP ensemble number 20 cdpt: trace number within CDP ensemble 24 trid: trace identification code: 1 = seismic data 2 = dead 3 = dummy 4 = time break 5 = uphole 6 = sweep 7 = timing 8 = water break 9---, N = optional use (N = 32,767) 28 nvs: number of vertically summed traces 30 nhs: number of horizontally summed traces 32 duse: data use: 1 = production 2 = test 34 offset: distance from source point to receiver group (negative if opposite to direction in which the line was shot) 36 gelev: receiver group elevation from sea level (above sea level is positive) 40 selev: source elevation from sea level (above sea level is positive) 44 sdepth: source depth (positive) 48 gdel: datum elevation at receiver group 52 sdel: datum elevation at source 56 swdep: water depth at source 60 gwdep: water depth at receiver group 64 scalel: scale factor for previous 7 entries with value plus or minus 10 to the power 0, 1, 2, 3, or 4 (if positive, multiply, if negative divide) 68 scalco: scale factor for next 4 entries with value plus or minus 10 to the power 0, 1, 2, 3, or 4 (if positive, multiply, if negative divide) 70 sx: X source coordinate 72 sy: Y source coordinate 76 gx: X group coordinate 80 gy: Y group coordinate 84 counit: coordinate units code: for previous four entries 1 = length (meters or feet) 2 = seconds of arc (in this case, the X values are unsigned longitude and the Y values are latitude, a positive value designates the number of seconds east of Greenwich or north of the equator 88 wevel: weathering velocity 90 swevel: subweathering velocity 92 sut: uphole time at source 94 gut: uphole time at receiver group 96 sstat: source static correction 98 gstat: group static correction 100 tstat: total static applied 102 laga: lag time A, time in ms between end of 240- byte trace identification header and time break, positive if time break occurs after end of header, time break is defined as the initiation pulse which maybe recorded on an auxiliary trace or as otherwise specified by the recording system 104 lagb: lag time B, time in ms between the time break and the initiation time of the energy source, may be positive or negative 106 delrt: delay recording time, time in ms between initiation time of energy source and time when recording of data samples begins (for deep water work if recording does not start at zero time) 108 muts: mute time--start 110 mute: mute time--end 112 ns: number of samples in this trace 114 dt: sample interval, in micro-seconds 116 gain: gain type of field instruments code: 1 = fixed 2 = binary 3 = floating point 4 ---- N = optional use 118 igc: instrument gain constant 120 igi: instrument early or initial gain 122 corr: correlated: 1 = no 2 = yes 124 sfs: sweep frequency at start 126 sfe: sweep frequency at end 128 slen: sweep length in ms 130 styp: sweep type code: 1 = linear 2 = cos-squared 3 = other 132 stas: sweep trace length at start in ms 134 stae: sweep trace length at end in ms 136 tatyp: taper type: 1=linear, 2=cos^2, 3=other 138 afilf: alias filter frequency if used 140 afils: alias filter slope 142 nofilf: notch filter frequency if used 144 nofils: notch filter slope 146 lcf: low cut frequency if used 148 hcf: high cut frequncy if used 150 lcs: low cut slope 152 hcs: high cut slope 154 year: year data recorded 156 day: day of year 158 hour: hour of day (24 hour clock) 160 minute: minute of hour 162 sec: second of minute 164 timbas: time basis code: 1 = local 2 = GMT 3 = other 166 trwf: trace weighting factor, defined as 1/2^N volts for the least sigificant bit 168 grnors: geophone group number of roll switch position one 170 grnofr: geophone group number of trace one within original field record 172 grnlof: geophone group number of last trace within original field record 174 gaps: gap size (total number of groups dropped) 176 otrav: overtravel taper code: 1 = down (or behind) 2 = up (or ahead) 178 cdpx: X coordinate of CDP 180 cdpy: Y coordinate of CDP 184 iline: in-line number 188 xline: cross-line number 192 shnum: shotpoint number 196 shsca: shotpoint scalar 200 tval: trace value meas. 202 tconst4: transduction const 204 tconst2: transduction const 208 tunits: transduction units 210 device: device identifier 212 tscalar: time scalar 214 stype: source type 216 sendir: source energy dir. 218 unknown: unknown 222 smeas4: source measurement 224 smeas2: source measurement 228 smeasu: source measurement unit 230 unass1: unassigned 232 unass2: unassigned 236
|-
| ''string '' || '''bfile=''' || || output binary data header file
|-
| ''bool '' || '''endian=y''' || [y/n] || Whether to automatically estimate endianness or not
|-
| ''int '' || '''format=segyformat (bhead)''' || [1,2,3,5] || Data format. The default is taken from binary header.
:1 is IBM floating point
:2 is 4-byte integer
:3 is 2-byte integer
:5 is IEEE floating point
|-
| ''string '' || '''hfile=''' || || output text data header file
|-
| ''string '' || '''mask=''' || || optional header mask for reading only selected traces (auxiliary input file name)
|-
| ''int '' || '''ns=segyns (bhead)''' || || Number of samples. The default is taken from binary header
|-
| ''string '' || '''read=''' || || what to read: h - header, d - data, b - both (default)
|-
| ''bool '' || '''su=''' || [y/n] || y if input is SU, n if input is SEGY
|-
| ''bool '' || '''suxdr=n''' || [y/n] || y, SU has XDR support
|-
| ''string '' || '''tape=''' || || input data
|-
| ''string '' || '''tfile=''' || || output trace header file (auxiliary output file name)
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}

The SEG Y format is an [http://en.wikipedia.org/wiki/Open_standard open standard] for the exchange of geophysical data. It is controlled by the non-profit [http://www.seg.org/SEGportalWEBproject/portals/SEG_Online.portal?_nfpb=true&_pageLabel=pg_gen_content&Doc_Url=prod/SEG-Publications/Pub-Yearbook/committees.htm SEG Technical Standards Committee]. There are two versions of this standard: [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev0.pdf rev0] (1975)<ref>Barry, K.M., Cavers, D.A., and Kneale, C.W. 1975. Recommended standards for digital tape formats. ''Geophysics'', '''40''', no. 02, 344–352.</ref> and [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev1.pdf rev1] (2002)<ref>Norris, M.W., Faichney, A.K., ''Eds''. 2001. SEG Y rev1 Data Exchange format. Society of Exploration Geophysicists, Tulsa, OK, 45 pp.</ref>. The implementation in <tt>sfsegyread</tt> is a mixture of rev0 (i.e. no checks for Extended Textual Headers) and rev1 ([http://en.wikipedia.org/wiki/IEEE_floating-point_standard IEEE floating point format] allowed for trace data samples).

A SEG-Y file as understood by <tt>sfsegyread</tt> contains a "Reel Identification Header" (3200 bytes in EBCDIC followed by 400 bytes in a binary encoding), followed by a number of "Trace Blocks". Each "Trace Block" contains a 240-byte "Trace Header" (binary) followed by "Trace Data" -- a sequence of <tt>ns</tt> samples. Binary values in both reel headers and trace headers are two's complement integers, either two bytes or four bytes long. There are no floating-point values defined in the headers. Trace Data samples can have various encodings, either floating point or integer, described further down, but they are all big-endian. To convert from SEG-Y to RSF, <tt>sfsegyread</tt> will strip the tape reel EBCDIC header and convert it to ASCII, will extract the reel binary header without changing it, and will put the trace headers into one RSF file, and the traces themselves on another.

===SEG-Y Trace Headers===
In the SEG-Y standard, only the first 180 bytes of the 240-byte trace header are defined; bytes 181-240 are reserved for non-standard header information, and these locations are increasingly used in modern SEG-Y files and its variants. The standard provides for a total of 71 4-byte and 2-byte predefined header words. These 71 standard words have defined lengths and byte offsets, and only these words and byte locations are read using <tt>segyread</tt> and output to the RSF header file with the <tt>hfile=</tt> option. The user may remap these predefined keywords to a different byte offsets.

===SU File Format===
An [http://www.cwp.mines.edu/sututor/node22.html SU file] is nothing more than a SEG-Y file without the reel headers, and with the Trace Data samples in the native encoding of the CPU the file was created on (Attention -- limited portability!). So, to convert from SU to RSF, <tt>sfsegyread</tt> will just separate headers and traces into two RSF files.

===SEG-Y specific parameters===
*<tt>hfile=</tt> specifies the name of the file in which the EBCDIC reel header will be put after conversion to ASCII. If you are certain there is no useful information in it, <tt>hfile=/dev/null</tt> works just fine. If you do not specify anything for this parameter you will get an ASCII file named <tt>header</tt> in the current directory. If you want to quickly preview this header before running <tt>sfsegyread</tt>, use<pre>dd if=input.segy count=40 bs=80 cbs=80 conv=unblock,ascii</pre>
*<tt>bfile=</tt> specifies name of the file in which the binary reel header (the 400-bytes thing following the 3600-bytes EBCDIC) will be put without any conversion. The default name is "binary". Unless you have software that knows how to read exactly this special type of file, it will be completely useless, so do <tt>bfile=/dev/null</tt>
*<tt>format=</tt> specifies the format in which the trace data samples are in the SEG-Y input file. This is read from the binary reel header of the SEG-Y file. Valid values are 1(IBM floating point), 2 (4-byte integer), 3 (2-byte integer) and 5 (IEEE floating point). If the input file is SU, the format will be assumed to be the native <tt>float</tt> format.

*<tt>keyname=</tt> specifies the byte offset to remap a header using the trace header key names shown above. For example, if the CDP locations have been placed in bytes 181-184 instead of the standard 21-24, <tt>cdp=180</tt> will remap the trace header to that location.

===SU-specific parameters===
*<tt>suxdr=</tt> specifies whether the input file was created with a SU package with XDR support enabled. If you have access to the source code of your SU install (try <tt>$CWPROOT/src</tt>), type: <tt>grep 'XDRFLAG =' $CWPROOT/src/Makefile.config</tt> and look at the last uncommented entry. If no value is given for <tt>XDRFLAG</tt>, the package was not compiled with XDR support.
===Common parameters===
*<tt>su=</tt> specifies if the input file is SU or SEG-Y. Default is <tt>su=n</tt> (SEG-Y file).
*<tt>tape=</tt> specifies the input data. Stdin could not be used because <tt>sfsegyread</tt> has to work with tapes, and needs to fseek back and forth through the input file. Thankfully, output is on stdout.
*<tt>read=</tt> specifies what parts of the "Trace Blocks" will be read. It can be <tt>read=t</tt> (only trace data is read), <tt>read=h</tt> (only trace headers are read) or <tt>read=b</tt> (both are read).
*<tt>tfile=</tt> gives the name of the RSF file to which trace headers are written. Obviously, it should be only specified with <tt>read=h</tt> or <tt>read=b</tt>.
*<tt>mask=</tt> is an optional parameter specifying the name of a mask that says which traces will be read. The mask is a 1-D RSF file with integers. The number of samples in the mask is the same as the number of traces in the unmasked SEG-Y. In places corresponding to unwanted traces there should be zeros in the mask.
*<tt>ns=</tt> specifies the number of samples in a trace. For SEG-Y files, the default is taken from the binary reel header, and for SU files, from the header of the first trace. This parameter is however critical enough that a command line override was given for it.
*<tt>verbose=</tt> is the verbosity flag. Can be <tt>y</tt> or <tt>n</tt>.
*<tt>endian=</tt> is a y/n flag (default y), specifying whether to automatically estimate or not if samples in the Trace Data blocks are big-endian or little-endian. Try it if you are in trouble and do not know what else to do, otherwise let the automatic estimation do its job.

==sfsegywrite==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert an RSF dataset to SEGY or SU.
|-
! colspan="4" | sfsegywrite < in.rsf tfile=hdr.rsf verb=false su=false endian=sf_endian() tape= hfile= bfile=
|-
| colspan="4" | Merges trace headers with data.
|-
| ''string '' || '''bfile=''' || || input binary data header file
|-
| ''bool '' || '''endian=sf_endian()''' || [y/n] || big/little endian flag. The default is estimated automatically
|-
| ''string '' || '''hfile=''' || || input text data header file
|-
| ''bool '' || '''su=n''' || [y/n] || y if output is SU, n if output is SEGY
|-
| ''string '' || '''tape=''' || ||
|-
| ''bool '' || '''verb=n''' || [y/n] || Verbosity flag
|}
Please see <tt>sfsegyread</tt> for a complete description of parameter meanings and background issues. Parameters <tt>bfile</tt> and <tt>hfile</tt> should only be given values when the desired file is SEG-Y (default). The output file is specified by the <tt>tape=</tt> tag.
=Generic programs=
Programs in this category are general signal and image processing programs. The source files for these programs can be found under [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/system/seismic/ system/generic] in the Madagascar distribution.
==sfnoise==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Add random noise to the data.
|-
! colspan="4" | sfnoise < in.rsf > out.rsf seed=time(NULL) type=y var= range= mean=0 rep=n
|-
| ''float '' || '''mean=0''' || || noise mean
|-
| ''float '' || '''range=''' || || noise range (default=1)
|-
| ''bool '' || '''rep=n''' || [y/n] || if y, replace data with noise
|-
| ''int '' || '''seed=time(NULL)''' || || random seed
|-
| ''bool '' || '''type=y''' || [y/n] || noise distribution, y: normal, n: uniform
|-
| ''float '' || '''var=''' || || noise variance
|}
See the [http://www.ahay.org/rsflog/index.php?/archives/262-Program-of-the-month-sfnoise.html Program of the Month] blog entry.

=Plotting programs (stable)=
The source files for these programs can be found under
[http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/plot/main/ plot/main]
in the Madagascar distribution.

==sfbox==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Draw a balloon-style label.
|-
! colspan="4" | sfbox lab_color=VP_WHITE lab_fat=0 pscale=1. pointer=y reverse=n lat=0. long=90. angle=0. x0=0. y0=0. scale0=1. xt=2. yt=0. x_oval=0. y_oval=0. boxit=y length= scalet= size=.25 label= > out.vpl
|-
| ''float '' || '''angle=0.''' || || longitude of floating label in 3-D
|-
| ''bool '' || '''boxit=y''' || [y/n] || if y, create a box around text
|-
| ''int '' || '''lab_color=VP_WHITE''' || || label color
|-
| ''int '' || '''lab_fat=0''' || || label fatness
|-
| ''string '' || '''label=''' || || text for label
|-
| ''float '' || '''lat=0.''' || ||
|-
| ''float '' || '''length=''' || || normalization for xt and yt
|-
| ''float '' || '''long=90.''' || || latitude and longitude of viewpoint in 3-D
|-
| ''bool '' || '''pointer=y''' || [y/n] || if y, create arrow pointer
|-
| ''float '' || '''pscale=1.''' || || scale factor for width of pointer
|-
| ''bool '' || '''reverse=n''' || [y/n] ||
|-
| ''float '' || '''scale0=1.''' || || scale factor for x0 and y0
|-
| ''float '' || '''scalet=''' || ||
|-
| ''float '' || '''size=.25''' || || text height in inches
|-
| ''float '' || '''x0=0.''' || ||
|-
| ''float '' || '''x_oval=0.''' || ||
|-
| ''float '' || '''xt=2.''' || ||
|-
| ''float '' || '''y0=0.''' || || position of the pointer tip
|-
| ''float '' || '''y_oval=0.''' || || size of the oval around pointer
|-
| ''float '' || '''yt=0.''' || || relative position of text
|}
==sfcontour==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Contour plot.
|-
! colspan="4" | sfcontour < in.rsf c= min1=o1 min2=o2 max1=o1+(n1-1)*d1 max2=o2+(n2-1)*d2 nc=50 dc= c0= transp=y minval= maxval= allpos=y barlabel= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''bool '' || '''allpos=y''' || [y/n] || contour positive values only
|-
| ''string '' || '''barlabel=''' || ||
|-
| ''floats '' || '''c=''' || || [nc]
|-
| ''float '' || '''c0=''' || || first contour
|-
| ''float '' || '''dc=''' || || contour increment
|-
| ''float '' || '''max1=o1+(n1-1)*d1''' || ||
|-
| ''float '' || '''max2=o2+(n2-1)*d2''' || || data window to plot
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''min1=o1''' || ||
|-
| ''float '' || '''min2=o2''' || ||
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''nc=50''' || || number of contours
|-
| ''bool '' || '''transp=y''' || [y/n] || if y, transpose the axes
|}
==sfdots==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot signal with lollipops.
|-
! colspan="4" | sfdots < in.rsf labels= dots=(n1 <= 130)? 1: 0 seemean=(bool) (n2 <= 30) strings=(bool) (n1 <= 400) connect=1 corners= silk=n gaineach=y labelsz=8 yreverse=n constsep=n seedead=n transp=n xxscale=1. yyscale=1. clip=-1. overlap=0.9 screenratio=VP_SCREEN_RATIO screenht=VP_STANDARD_HEIGHT screenwd=screenhigh / screenratio radius=dd1/3 label1= unit1= title= > plot.vpl
|-
| ''float '' || '''clip=-1.''' || || data clip
|-
| ''int '' || '''connect=1''' || || connection type: 1 - diagonal, 2 - bar, 4 - only for non-zero data
|-
| ''bool '' || '''constsep=n''' || [y/n] || if y, use constant trace separation
|-
| ''int '' || '''corners=''' || || number of polygon corners (default is 6)
|-
| ''int '' || '''dots=(n1 <= 130)? 1: 0''' || || type of dots: 1 - baloon, 0 - no dots, 2 - only for non-zero data
|-
| ''bool '' || '''gaineach=y''' || [y/n] || if y, gain each trace independently
|-
| ''string '' || '''label1=''' || ||
|-
| ''strings'' || '''labels=''' || || trace labels [n2]
|-
| ''int '' || '''labelsz=8''' || || label size
|-
| ''float '' || '''overlap=0.9''' || || trace overlap
|-
| ''float '' || '''radius=dd1/3''' || || dot radius
|-
| ''float '' || '''screenht=VP_STANDARD_HEIGHT''' || || screen height
|-
| ''float '' || '''screenratio=VP_SCREEN_RATIO''' || || screen aspect ratio
|-
| ''float '' || '''screenwd=screenhigh / screenratio''' || || screen width
|-
| ''bool '' || '''seedead=n''' || [y/n] || if y, show zero traces
|-
| ''bool '' || '''seemean=(bool) (n2 <= 30)''' || [y/n] || if y, draw axis lines
|-
| ''bool '' || '''silk=n''' || [y/n] || if y, silky plot
|-
| ''bool '' || '''strings=(bool) (n1 <= 400)''' || [y/n] || if y, draw strings
|-
| ''string '' || '''title=''' || ||
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axis
|-
| ''string '' || '''unit1=''' || ||
|-
| ''float '' || '''xxscale=1.''' || || x scaling
|-
| ''bool '' || '''yreverse=n''' || [y/n] || if y, reverse y axis
|-
| ''float '' || '''yyscale=1.''' || || y scaling
|}
==sfgraph3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate 3-D cube plot for surfaces.
|-
! colspan="4" | sfgraph3 < in.rsf orient=1 min= max= point1=0.5 point2=0.5 frame1=0.5*(min+max) frame2=n1-1 frame3=0 movie=0 dframe=1 n1pix=n1/point1+n3/(1.-point1) n2pix=n2/point2+n3/(1.-point2) flat=y > plot.vpl
|-
| ''float '' || '''dframe=1''' || || frame increment in a movie
|-
| ''bool '' || '''flat=y''' || [y/n] || if n, display perspective view
|-
| ''float '' || '''frame1=0.5*(min+max)''' || ||
|-
| ''int '' || '''frame2=n1-1''' || ||
|-
| ''int '' || '''frame3=0''' || || frame numbers for cube faces
|-
| ''float '' || '''max=''' || || maximum function value
|-
| ''float '' || '''min=''' || || minimum function value
|-
| ''int '' || '''movie=0''' || || 0: no movie, 1: movie over axis 1, 2: axis 2, 3: axis 3
|-
| ''int '' || '''n1pix=n1/point1+n3/(1.-point1)''' || || number of vertical pixels
|-
| ''int '' || '''n2pix=n2/point2+n3/(1.-point2)''' || || number of horizontal pixels
|-
| ''int '' || '''orient=1''' || || function orientation
|-
| ''float '' || '''point1=0.5''' || || fraction of the vertical axis for front face
|-
| ''float '' || '''point2=0.5''' || || fraction of the horizontal axis for front face
|}
==sfgraph==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Graph plot.
|-
! colspan="4" | sfgraph < in.rsf symbolsz= pclip=100. transp=n symbol= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''float '' || '''pclip=100.''' || || clip percentile
|-
| ''string '' || '''symbol=''' || || if set, plot with symbols instead of lines
|-
| ''floats '' || '''symbolsz=''' || || symbol size (default is 2) [n2]
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axes
|}
==sfgrey3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate 3-D cube plot.
|-
! colspan="4" | sfgrey3 < in.rsf point1=0.5 point2=0.5 frame1=0 frame2=n2-1 frame3=0 movie=0 dframe=1 n1pix=n1/point1+n3/(1.-point1) n2pix=n2/point2+n3/(1.-point2) flat=y scalebar=n minval= maxval= barreverse=n nreserve=8 bar= color= > plot.vpl
|-
| colspan="4" | Requires an "unsigned char" input (the output of sfbyte).
|-
| ''string '' || '''bar=''' || || file for scalebar data
|-
| ''bool '' || '''barreverse=n''' || [y/n] || if y, go from small to large on the bar scale
|-
| ''string '' || '''color=''' || || color scheme (default is i)
|-
| ''int '' || '''dframe=1''' || || frame increment in a movie
|-
| ''bool '' || '''flat=y''' || [y/n] || if n, display perspective view
|-
| ''int '' || '''frame1=0''' || ||
|-
| ''int '' || '''frame2=n2-1''' || ||
|-
| ''int '' || '''frame3=0''' || || frame numbers for cube faces
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''movie=0''' || || 0: no movie, 1: movie over axis 1, 2: axis 2, 3: axis 3
|-
| ''int '' || '''n1pix=n1/point1+n3/(1.-point1)''' || || number of vertical pixels
|-
| ''int '' || '''n2pix=n2/point2+n3/(1.-point2)''' || || number of horizontal pixels
|-
| ''int '' || '''nreserve=8''' || || reserved colors
|-
| ''float '' || '''point1=0.5''' || || fraction of the vertical axis for front face
|-
| ''float '' || '''point2=0.5''' || || fraction of the horizontal axis for front face
|-
| ''bool '' || '''scalebar=n''' || [y/n] || if y, draw scalebar
|}

Different [http://reproducibility.org/rsflog/index.php?/archives/14-Color-schemes.html color schemes] are available
for sfgrey and sfgrey3. Examples are in the book at [http://reproducibility.org/RSF/book/rsf/rsf/sfgrey.html rsf/rsf/sfgrey].

==sfgrey==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate raster plot.
|-
! colspan="4" | sfgrey < in.rsf > out.rsf bar=bar.rsf transp=y yreverse=y xreverse=n gpow= phalf= clip= pclip= gainstep=0.5+n1/256. allpos=n bias=0. polarity=n verb=n scalebar=n minval= maxval= barreverse=n wantframenum=(bool) (n3 > 1) nreserve=8 gainpanel= bar= color= > (plot.vpl | char.rsf)
|-
| colspan="4" | Can input char values. If called "byte", outputs char values. Run "sfdoc stdplot" for more parameters.
|-
| ''bool '' || '''allpos=n''' || [y/n] || if y, assume positive data
|-
| ''string '' || '''bar=''' || || file for scalebar data
|-
| ''bool '' || '''barreverse=n''' || [y/n] || if y, go from small to large on the bar scale
|-
| ''float '' || '''bias=0.''' || || subtract bias from data
|-
| ''float '' || '''clip=''' || ||
|-
| ''string '' || '''color=''' || || color scheme (default is i)
|-
| ''string '' || '''gainpanel=''' || || gain reference: 'a' for all, 'e' for each, or number
|-
| ''int '' || '''gainstep=0.5+n1/256.''' || || subsampling for gpow and clip estimation
|-
| ''float '' || '''gpow=''' || ||
|-
| ''float '' || '''maxval=''' || || maximum value for scalebar (default is the data maximum)
|-
| ''float '' || '''minval=''' || || minimum value for scalebar (default is the data minimum)
|-
| ''int '' || '''nreserve=8''' || || reserved colors
|-
| ''float '' || '''pclip=''' || || data clip percentile (default is 99)
|-
| ''float '' || '''phalf=''' || || percentage for estimating gpow
|-
| ''bool '' || '''polarity=n''' || [y/n] || if y, reverse polarity (white is high by default)
|-
| ''bool '' || '''scalebar=n''' || [y/n] ||
|-
| ''bool '' || '''transp=y''' || [y/n] || if y, transpose the display axes
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''bool '' || '''wantframenum=(bool) (n3 > 1)''' || [y/n] || if y, display third axis position in the corner
|-
| ''bool '' || '''xreverse=n''' || [y/n] || if y, reverse the horizontal axis
|-
| ''bool '' || '''yreverse=y''' || [y/n] || if y, reverse the vertical axis
|}

Different [http://reproducibility.org/rsflog/index.php?/archives/14-Color-schemes.html color schemes] are available
and examples are in the book at [http://reproducibility.org/RSF/book/rsf/rsf/sfgrey.html rsf/rsf/sfgrey].

==sfplas==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot Assembler - convert ascii to vplot.
|-
! colspan="4" | sfplas
|}
==sfpldb==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot Debugger - convert vplot to ascii.
|-
! colspan="4" | sfpldb
|}
==sfplotrays==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot rays.
|-
! colspan="4" | sfplotrays frame=frame.rsf nt=n1*n2 jr=1 frame= < rays.rsf > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''string '' || '''frame=''' || ||
|-
| ''int '' || '''jr=1''' || || skip rays
|-
| ''int '' || '''nt=n1*n2''' || || maximum ray length
|}
==sfthplot==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Hidden-line surface plot.
|-
! colspan="4" | sfthplot < in.rsf uflag=y dflag=y alpha=45. titlsz=9 axissz=6 plotfat=0 titlefat=2 axisfat=2 plotcolup=VP_YELLOW plotcoldn=VP_RED axis=y axis1=y axis2=y axis3=y clip=0. pclip=100. gainstep=0.5+nx/256. bias=0. dclip=1. norm=y xc=1.5 zc=3 ratio=5. zmax= zmin= sz=6. label#= unit#= tpow=0 epow=0 gpow=1 title= > plot.vpl
|-
| ''float '' || '''alpha=45.''' || || apparent angle in degrees, |alpha| < 89
|-
| ''bool '' || '''axis=y''' || [y/n] ||
|-
| ''bool '' || '''axis1=y''' || [y/n] ||
|-
| ''bool '' || '''axis2=y''' || [y/n] ||
|-
| ''bool '' || '''axis3=y''' || [y/n] || plot axis
|-
| ''int '' || '''axisfat=2''' || || axes fatness
|-
| ''int '' || '''axissz=6''' || || axes size
|-
| ''float '' || '''bias=0.''' || || subtract bias from data
|-
| ''float '' || '''clip=0.''' || || data clip
|-
| ''float '' || '''dclip=1.''' || || change the clip: clip *= dclip
|-
| ''bool '' || '''dflag=y''' || [y/n] || if y, plot down side of the surface
|-
| ''float '' || '''epow=0''' || || exponential gain
|-
| ''int '' || '''gainstep=0.5+nx/256.''' || || subsampling for gpow and clip estimation
|-
| ''float '' || '''gpow=1''' || || power gain
|-
| ''string '' || '''label#=''' || || label on #-th axis
|-
| ''bool '' || '''norm=y''' || [y/n] || normalize by the clip
|-
| ''float '' || '''pclip=100.''' || || data clip percentile
|-
| ''int '' || '''plotcoldn=VP_RED''' || || color of the lower side
|-
| ''int '' || '''plotcolup=VP_YELLOW''' || || color of the upper side
|-
| ''int '' || '''plotfat=0''' || || line fatness
|-
| ''float '' || '''ratio=5.''' || || plot adjustment
|-
| ''float '' || '''sz=6.''' || || vertical scale
|-
| ''string '' || '''title=''' || ||
|-
| ''int '' || '''titlefat=2''' || || title fatness
|-
| ''int '' || '''titlsz=9''' || || title size
|-
| ''string '' || '''tpow=0''' || || time power gain
|-
| ''bool '' || '''uflag=y''' || [y/n] || if y, plot upper side of the surface
|-
| ''string '' || '''unit#=''' || || unit on #-th axis
|-
| ''float '' || '''xc=1.5''' || ||
|-
| ''float '' || '''zc=3''' || || lower left corner of the plot
|-
| ''float '' || '''zmax=''' || ||
|-
| ''float '' || '''zmin=''' || ||
|}
==sfwiggle==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Plot data with wiggly traces.
|-
! colspan="4" | sfwiggle < in.rsf xpos=xpos.rsf xmax= xmin= poly=n fatp=1 xmask=1 ymask=1 pclip=98. zplot=0.75 clip=0. seemean=n verb=n transp=n yreverse=n xreverse=n xpos= > plot.vpl
|-
| colspan="4" | Run "sfdoc stdplot" for more parameters.
|-
| ''float '' || '''clip=0.''' || || data clip (estimated from pclip by default
|-
| ''int '' || '''fatp=1''' || ||
|-
| ''float '' || '''pclip=98.''' || || clip percentile
|-
| ''bool '' || '''poly=n''' || [y/n] ||
|-
| ''bool '' || '''seemean=n''' || [y/n] || if y, plot mean lines of traces
|-
| ''bool '' || '''transp=n''' || [y/n] || if y, transpose the axes
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''int '' || '''xmask=1''' || ||
|-
| ''float '' || '''xmax=''' || || maximum trace position (if using xpos)
|-
| ''float '' || '''xmin=''' || || minimum trace position (if using xpos)
|-
| ''string '' || '''xpos=''' || || optional header file with trace positions
|-
| ''bool '' || '''xreverse=n''' || [y/n] || if y, reverse the horizontal axis
|-
| ''int '' || '''ymask=1''' || ||
|-
| ''bool '' || '''yreverse=n''' || [y/n] || if y, reverse the vertical axis
|-
| ''float '' || '''zplot=0.75''' || ||
|}
=Plotting programs (development)=
==sfplsurf==
<tt>sfplsurf</tt> utilizes PLplot's surface rendering capabilities. Output is dumped to stdout in VPLOT format, so it can easily be used in the same way as <tt>sfgrey</tt> or other plotting programs. It also supports animation, if n3 > 1 in the input file. A SConstruct usage example can be found below. A [http://reproducibility.org/wikilocal/movies/sfplsurf_membrane.mpg movie of the output] is available as well.

<python>
from rsf.proj import *

# x & y dimensions
o1=-2
o2=-2
n1=41
n2=41
d1=0.1
d2=0.1
# z dimension
o3=-1
n3=21
d3=0.1

Flow('membrane',None,
'''
math o1=%g o2=%g n1=%d n2=%d d1=%g d2=%g
o3=%g n3=%d d3=%g
output="x3*cos(x1*x1+x2*x2)*exp(-0.1*(x1*x1+x2*x2))"
''' % (o1,o2,n1,n2,d1,d2,o3,n3,d3))

Result('membrane',
'''
plsurf title="Membrane" mesh=n color=j
minval=%g maxval=%g
''' % (o3,o3 + d3*(n3-1)))

End()
</python>

=system/generic programs=
==sfremap1==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | 1-D ENO interpolation.
|-
! colspan="4" | sfremap1 < in.rsf > out.rsf pattern=pattern.rsf n1=n1 d1=d1 o1=o1 order=3
|-
| ''float '' || '''d1=d1''' || || Output sampling
|-
| ''int '' || '''n1=n1''' || || Number of output samples
|-
| ''float '' || '''o1=o1''' || || Output origin
|-
| ''int '' || '''order=3''' || || Interpolation order
|-
| ''string '' || '''pattern=''' || || auxiliary input file name
|}
To give an example of usage, we will create an input for <tt>sfremap1</tt> with:
<pre>
sfmath n1=11 n2=11 d1=1 d2=1 o1=-5 o2=-5 output="x1*x1+x2*x2" > inp2remap1.rsf
</pre>
Let us interpolate the data across both dimensions, then display it:
<pre>
< inp2remap1.rsf sfremap1 n1=1001 d1=0.01 | sftransp | \
sfremap1 n1=1001 d1=0.01 | sftransp | sfgrey allpos=y | sfpen
</pre>
The comparison with the uninterpolated data ( <tt>< inp2remap1.rsf sfgrey allpos=y | sfpen</tt> ) is quite telling.

=system/seismic programs=
==sfstretch==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Stretch of the time axis.
|-
! colspan="4" | sfstretch < in.rsf > out.rsf datum=dat.rsf inv=n dens=1 v0= half=y delay= tdelay= hdelay= nout=dens*n1 extend=4 mute=0 maxstr=0 rule=
|-
| ''file '' || '''datum=''' || || auxiliary input file name
|-
| ''float '' || '''delay=''' || || time delay for rule=lmo
|-
| ''int '' || '''dens=1''' || || axis stretching factor
|-
| ''int '' || '''extend=4''' || || trace extension
|-
| ''bool '' || '''half=y''' || [y/n] || if y, the second axis is half-offset instead of full offset
|-
| ''float '' || '''hdelay=''' || || offset delay for rule=rad
|-
| ''bool '' || '''inv=n''' || [y/n] || if y, do inverse stretching
|-
| ''float '' || '''maxstr=0''' || || maximum stretch
|-
| ''int '' || '''mute=0''' || || tapering size
|-
| ''int '' || '''nout=dens*n1''' || || output axis length (if inv=n)
|-
| ''string '' || '''rule=''' || || Stretch rule:
:n - normal moveout (nmostretch), default
:l - linear moveout (lmostretch)
:L - logarithmic stretch (logstretch)
:2 - t^2 stretch (t2stretch)
:c - t^2 chebyshev stretch (t2chebstretch)
:r - radial moveout (radstretch)
:d - datuming (datstretch)
|-
| ''float '' || '''tdelay=''' || || time delay for rule=rad
|-
| ''float '' || '''v0=''' || || moveout velocity
|}

<tt>sfstretch rule=d</tt> (aka <tt>sfdatstretch</tt>) can be used to apply statics. Here is a synthetic example, courtesy of Alessandro Frigeri:
<pre>
# generate a dataset with 'flat' signals
sfmath n1=200 n2=100 output="sin(0.5*x1)" type=float > scan.rsf

# generate a sinusoidal elevation correction
sfmath n1=100 output="3*sin(x1)" type=float > statics.rsf

# apply statics, producing a 'wavy' output.
sfstretch < scan.rsf > out.rsf datum=statics.rsf rule=d
</pre>

=user/fomels programs=
==sfpick==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Automatic picking from semblance-like panels.
|-
! colspan="4" | sfpick < scn.rsf > pik.rsf vel0=o2 niter=100 an=1. gate=3 smooth=y rect#=(1,1,...) rect1=1 rect2=1 ...
|-
| colspan="4" | rectN defines the size of the smoothing stencil in N-th dimension. Theory in Appendix B of: S. Fomel, 2009, Velocity analysis using AB semblance: Geophysical Prospecting, v. 57, 311-321. Reproducible version in RSFSRC/book/jsg/avo
|-
| ''float '' || '''an=1.''' || || axes anisotropy
|-
| ''int '' || '''gate=3''' || || picking gate
|-
| ''int '' || '''niter=100''' || || number of iterations
|-
| ''int '' || '''rect#=(1,1,...)''' || || smoothing radius on #-th axis
|-
| ''bool '' || '''smooth=y''' || [y/n] || if apply smoothing
|-
| ''float '' || '''vel0=o2''' || || surface velocity
|}
Short description of the algorithm:
# Start from the top (first time slice), pick an initial (source) point, evaluate all other points with the direct traveltime.
# At each grid point at the next level, find the traveltime to points at the previous level, add the traveltimes from the previous level, and select minimum. The search radius is limited by the aperture (gate= parameter in sfpick).
# Repeat step 2 until reaching the bottom.
# Pick the minimum traveltime at the bottom and track the ray back to the source by following the traveltime gradient direction.
# Postprocessing (smooth= parameter in sfpick): smooth the picked ray path using shaping regularization.

The algorithm was discovered and rediscovered by many people. The best reference is probably ''V. Meshbey, E. Ragoza, D. Kosloff, U. Egozi, and D. Wexler, 2002, Three-dimensional Travel-time Calculation Based on Fermat's Principle: Pure and Applied Geophysics, v. 159, 1563-1582.''

=user/ivlad programs=
==sfprep4plot==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Resamples a 2-D dataset to the desired picture resolution, with antialias
|-
! colspan="4" | sfprep4plot inp= out= verb=n h=none w=none unit= ppi= prar=y
|-
| colspan="4" | Only one of the h and w parameters needs to be specified. If prar=n, no action will be taken on axis for which h/w was not specified If prar=y and only one par (h or w) is specified, the picture will scale along both axes until it is of the specified dimension.
|-
| ''int '' || '''h=none''' || || output height
|-
| ''string '' || '''inp=''' || || input file
|-
| ''string '' || '''out=''' || || output file
|-
| ''int '' || '''ppi=''' || || output resolution (px/in). Necessary when unit!=px
|-
| ''bool '' || '''prar=y''' || [y/n] || if y, PReserve Aspect Ratio of input
|-
| ''string '' || '''unit=''' || || unit of h and w. Can be: px(default), mm, cm, in
|-
| ''bool '' || '''verb=n''' || [y/n] || if y, print system commands, outputs
|-
| ''int '' || '''w=none''' || || output width
|}
For a figure that does not need the aspect ratio preserved,
and needs to fill a 1280x1024 projector display:
<pre>
sfprep4plot inp=file1.rsf out=file2.rsf w=1280 h=1024 prar=n
</pre>
For a print figure that has to fit in a 6x8in box
at a resolution of 250 dpi, preserving the aspect ratio:
<pre>
sfprep4plot inp=file1.rsf out=file2.rsf w=6 h=8 unit=in ppi=250
</pre>
A comparison of images before and after the application of <tt>sfprep4plot</tt>, courtesy of Joachim Mispel, is shown below:

[[Image:sf_prep4plot.jpg]]

==sfcsv2rsf==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a delimited-text ASCII file to RSF binary floating point or int.
|-
! colspan="4" | sfcsv2rsf help=n delimiter=, dtype=float verb=n debug=n trunc=n o1=0. o2=0. d1=1. d2=1. unit1=unknown unit2=unknown label1=unknown label2=unknown
|-
| colspan="4" | Zeros will be added if number of elements is not the same in each row. n1 and n2 are computed automatically. For consistency with sfdisfil and sfmatmult, output is C-style order (row-first), i.e. rows in input file become dimension-1 columns in output. Output encoding is native.
|-
| ''float '' || '''d1=1.''' || ||
|-
| ''float '' || '''d2=1.''' || ||
|-
| ''bool '' || '''debug=n''' || [y/n] || Extra verbosity for debugging
|-
| ''string '' || '''delimiter=,''' || || Separator between values in input file
|-
| ''string '' || '''dtype=float''' || || Input type
|-
| ''bool '' || '''help=n''' || [y/n] ||
|-
| ''string '' || '''label1=unknown''' || ||
|-
| ''string '' || '''label2=unknown''' || ||
|-
| ''float '' || '''o1=0.''' || ||
|-
| ''float '' || '''o2=0.''' || ||
|-
| ''bool '' || '''trunc=n''' || [y/n] || Truncate or add zeros if nr elems in rows differs
|-
| ''string '' || '''unit1=unknown''' || ||
|-
| ''string '' || '''unit2=unknown''' || ||
|-
| ''bool '' || '''verb=n''' || [y/n] || Whether to echo n1, n2, infill/truncation
|}

A small usage example follow below. First, create an input file:

<bash>
$ echo -e '5,6,8,9.2\n11,124,5,0,1' | tee file.csv
5,6,8,9.2
11,124,5,0,1
</bash>

You may notice that the number of values in each row is different.

Run <tt>sfcsv2rsf</tt>. Notice that no options are needed. By default, zeros will be appended to make the rows equal length:

<bash>
$ <file.csv sfcsv2rsf > junk.rsf ; sfdisfil < junk.rsf
0: 5 6 8 9.2 0
5: 11 124 5 0 1
</bash>

Notice that sfdisfil displays in column order (i.e. matrix is transposed if the number of rows is right). The dimensions of the file are actually transposed on disk:

$ sfin junk.rsf
junk.rsf:
in="/data/path/junk.rsf@"
esize=4 type=float form=native
n1=5 d1=1 o1=0 unit1="unknown"
n2=2 d2=1 o2=0 unit2="unknown"
10 elements 40 bytes
</bash>

You may want to run the output through <tt>sftransp</tt>, depending on your needs. However, if creating an input for <tt>sfmatmult</tt>, this will not be necessary, because <tt>sfmatmult</tt> is made to work with matrices that are displayed with <tt>sfdisfil</tt>, and takes as input a transpose matrix.

Pipes can be used, of course, to skip the creation of intermediary files:

<bash>
$ <file.csv sfcsv2rsf | sfdisfil
0: 5 6 8 9.2 0
5: 11 124 5 0 1
</bash>

Note that since this program does not need any arguments (just stdin and stdout), when called with no arguments it will not display the man page. In order to consult the automatically generated documentation, you need to pass the option <tt>help=y</tt> .

=user/jennings programs=
==sfsizes==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display the size of RSF files.
|-
! colspan="4" | sfsizes files=y human=n file1.rsf file2.rsf ...
|-
| colspan="4" | Prints the element size, number of elements, and number of bytes for a list of RSF files. Non-RSF files are ignored.
|-
| ''bool '' || '''files=y''' || [y/n] || If y, print size of each file. If n, print only total.
|-
| ''bool '' || '''human=n''' || [y/n] || If y, print human-readable file size. If n, print byte count.
|}

This program computes the "theoretical" size in bytes of the data fork of RSF files. The actual space occupied on disk may be different and machine dependent due to disk blocking factors, etc. This theoretical array size should be reproducible. It is also fast because the program only reads the RSF headers files, not the actual data.

For example, to get the total size of all RSF files in a directory, in human readable format, without listing each file:
<pre>
sfsizes files=n human=y *.rsf
</pre>
This will also work because sfsizes simply skips any non-RSF file:
<pre>
sfsizes files=n human=y *
</pre>
==sffiglist==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Compare Vplot files in Fig and Lock directories
|-
! colspan="4" | sffiglist figdir= lockdir= list= show=
|-
| colspan="4" |
Parameter '''figdir''' is path to Fig directory, default is ./Fig.

 Parameter '''lockdir''' is path to Lock directory:
 If '''figdir''' is in $RSFSRC/book/[book]/[chapter]/[section],
 then default '''lockdir''' is $RSFFIGS/[book]/[chapter]/[section].
 If '''figdir''' is not in $RSFSRC/book/[book]/[chapter]/[section],
 then default '''lockdir''' is $RSFALTFIGS/[book]/[chapter]/[section].

 Parameter '''list''' controls files to list, default is all.
 Parameter '''show''' controls files to flip with sfpen, default is none.

 '''list|show''' = none (No files, print only summary.)
 '''list|show''' = diff (Files that are different, determined by sfvplotdiff.)
 '''list|show''' = miss (Files missing from figdir or lockdir, and different files.)
 '''list|show''' = all (All files.)

 File list codes:
 space indicates files that are the same.
 - indicates file in lockdir that is missing from figdir.
 + indicates extra file in figdir that is missing from lockdir.
 number is return code from sfvplotdiff indicating different files.
|-
| ''string '' || '''figdir=''' || || fig directory, default = ./Fig
|-
| ''string '' || '''list=''' || || how much to list [none,diff,miss,all], default = all
|-
| ''string '' || '''lockdir=''' || || lock directory, default = lock counterpart of figdir
|-
| ''string '' || '''show=''' || || how much to show [none,diff,miss,all], default = none
|}

This tool lists Vplot files in "Fig" and "Lock" directories and compares them using sfvplotdiff.

The Fig directory defaults to ./Fig and the Lock directory defaults to the
corresponding directory where "scons lock" puts things, but either
default can be overridden with the user parameters '''figdir''' and '''lockdir''' so that, for example,
files in two different Fig directories can be compared.

The default for the Lock directory has some logic to look in $RSFFIGS
when Fig is in $RSFSRC/book, or to look in $RSFALTFIGS when Fig is not
in $RSFSRC/book because I like to keep two different Lock directories:
one for stuff in book and another for my own stuff that is not in
book. However, I tried to make the code default to reasonable things
if any of these environment variables are not defined.

The tool gives a summary count of files that are the same, files that
are different, files in Fig that are missing from Lock, and files in
Lock that are missing from Fig.

The parameters '''list''' (default=all) and '''show''' (default=none) control which files are listed or "flipped" with sfpen. The file listing indicates which files are the same, which are different, and which are missing from Fig or Lock.

For example, to list all the Vplot files in Fig and Lock:
<pre>
sffiglist list=all
</pre>
To list all Vplot files and flip only files that are different:
<pre>
sffiglist list=all show=diff
</pre>

=user/psava programs=

==sfawefd==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | acoustic time-domain FD modeling
|-
! colspan="4" | sfawefd < Fwav.rsf vel=Fvel.rsf sou=Fsou.rsf rec=Frec.rsf wfl=Fwfl.rsf > Fdat.rsf den=Fden.rsf ompchunk=1 ompnth=0 verb=n snap=n free=n expl=n jdata=1 jsnap=nt nq1=sf_n(a1) nq2=sf_n(a2) oq1=sf_o(a1) oq2=sf_o(a2)
|-
| ''file '' || '''den=''' || || auxiliary input file name
|-
| ''bool '' || '''expl=n''' || [y/n] || "exploding reflector"
|-
| ''bool '' || '''free=n''' || [y/n] || free surface flag
|-
| ''int '' || '''jdata=1''' || ||
|-
| ''int '' || '''jsnap=nt''' || || save wavefield every *jsnap* time steps
|-
| ''int '' || '''nq1=sf_n(a1)''' || ||
|-
| ''int '' || '''nq2=sf_n(a2)''' || ||
|-
| ''int '' || '''ompchunk=1''' || || OpenMP data chunk size
|-
| ''int '' || '''ompnth=0''' || || OpenMP available threads
|-
| ''float '' || '''oq1=sf_o(a1)''' || ||
|-
| ''float '' || '''oq2=sf_o(a2)''' || ||
|-
| ''file '' || '''rec=''' || || auxiliary input file name
|-
| ''bool '' || '''snap=n''' || [y/n] || wavefield snapshots flag
|-
| ''file '' || '''sou=''' || || auxiliary input file name
|-
| ''file '' || '''vel=''' || || auxiliary input file name
|-
| ''bool '' || '''verb=n''' || [y/n] || verbosity flag
|-
| ''file '' || '''wfl=''' || || auxiliary output file name
|}

An example will be demonstrated below on a model with nx=nz=200, dx=dz=4m (size: 800x800m). There are two layers: the first one is 100x200 samples in (z,x) and the velocity is 1500m/s; the second layer has the same dimension and the velocity is 3000m/s. Density is set to 1 for the whole grid. A source and a receiver are co-located at x=400 and z=100. The full wavefield for the entire model aperture will be saved every 10th time step.

<bash>
# Velocity model:
sfspike >Fvel.rsf mag=1500,3000 nsp=2 k1=1,101 l1=100,200 d1=4 d2=4 \
label1=z label2=x n1=200 n2=200 o1=2 o2=2 unit1=m unit2=m

# Density model:
sfspike >Fden.rsf mag=1 nsp=1 k1=1 l1=200 d1=4 d2=4 label1=z \
label2=x n1=200 n2=200 o1=2 o2=2 unit1=m unit2=m

# Source position (x,z):
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 >Fsou.rsf

# Receiver position (x,z):
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 >Frec.rsf

# Source wavelet:
sfspike nsp=1 n1=2000 d1=0.0005 k1=200 | sfricker1 frequency=20 |\
sftransp >Fwav.rsf

# Creating data at specified receiver + saving full wavefield every 10th step:
sfawefd2d <Fwav.rsf vel=Fvel.rsf sou=Fsou.rsf rec=Frec.rsf wfl=Fwfl.rsf \
den=Fden.rsf >Fdat.rsf verb=y free=y expl=y snap=y dabc=y jdata=1 jsnap=10
echo 'label1=z unit1=m label2=x unit2=m' >> Fwfl.rsf

# View the wavefield movie:
< Fwfl.rsf sfgrey gainpanel=a pclip=99 color=j scalebar=y | sfpen

# View a wavefield snapshot:
< Fwfl.rsf sfwindow f3=80 n3=1 |\
sfgrey pclip=99 color=j title='snapshot at t=0.4s' |\
sfpen

# View the data recorded at receiver:
<Fdat.rsf sfwindow |\
sfgraph title='Data recorded at receiver' unit2='' label2=amplitude |\
sfpen
</bash>

[[Image:sfawefd_wfld.jpg|frame|center|sfawefd wavefield screenshot]]
[[Image:sfawefd_dat.png|frame|center|sfawefd data screenshot]]

Attention: time steps that are too large can result in numerical instability.

==sfsrmig3==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | 3-D S/R migration with extended SSF
|-
! colspan="4" | sfsrmig3 slo=Fs_s.rsf sls=Fs_r.rsf < Fw_s.rsf rwf=Fw_r.rsf > Fi.rsf cig=Fc.rsf ompchunk=1 ompnth=0 verb=y eps=0.01 twoway=n nrmax=1 dtmax=0.004 pmx=0 pmy=0 tmx=0 tmy=0 vpvs=1. hsym=n nht=1 oht=0 dht=0.1 nht=1 oht=0 dht=0.1 hsym=n nhh=1 ohh=0 dhh=0.1 nha=180 oha=0 dha=2.0 nhb=180 ohb=0 dhb=2.0 itype=
|-
| ''file '' || '''cig=''' || || auxiliary output file name
|-
| ''float '' || '''dha=2.0''' || ||
|-
| ''float '' || '''dhb=2.0''' || ||
|-
| ''float '' || '''dhh=0.1''' || ||
|-
| ''float '' || '''dht=0.1''' || ||
|-
| ''float '' || '''dtmax=0.004''' || || max time error
|-
| ''float '' || '''eps=0.01''' || || stability parameter
|-
| ''bool '' || '''hsym=n''' || [y/n] ||
|-
| ''string '' || '''itype=''' || || imaging condition type
:o = zero lag (default)
:e = extended
:x = space-lags
:h = space-lags magnitude
:t = time-lag
|-
| ''int '' || '''nha=180''' || ||
|-
| ''int '' || '''nhb=180''' || ||
|-
| ''int '' || '''nhh=1''' || ||
|-
| ''int '' || '''nht=1''' || ||
|-
| ''int '' || '''nrmax=1''' || || max number of refs
|-
| ''float '' || '''oha=0''' || ||
|-
| ''float '' || '''ohb=0''' || ||
|-
| ''float '' || '''ohh=0''' || ||
|-
| ''float '' || '''oht=0''' || ||
|-
| ''int '' || '''ompchunk=1''' || || OpenMP data chunk size
|-
| ''int '' || '''ompnth=0''' || || OpenMP available threads
|-
| ''int '' || '''pmx=0''' || || padding on x
|-
| ''int '' || '''pmy=0''' || || padding on y
|-
| ''file '' || '''rwf=''' || || auxiliary input file name
|-
| ''file '' || '''slo=''' || || auxiliary input file name
|-
| ''string '' || '''sls=''' || || auxiliary input file name
|-
| ''int '' || '''tmx=0''' || || taper on x
|-
| ''int '' || '''tmy=0''' || || taper on y
|-
| ''bool '' || '''twoway=n''' || [y/n] || two-way traveltime
|-
| ''bool '' || '''verb=y''' || [y/n] || verbosity flag
|-
| ''float '' || '''vpvs=1.''' || || Vp/Vs ratio
|}

This program performs 3-D and 2-D shot-record (a.k.a. shot-profile) migration with an extended Split-Step Fourier (SSF) extrapolator with multiple reference velocities (hence "extended"). It takes as input a shot wavefield (<tt>stdin</tt>), receiver wavefield (<tt>rwf=</tt>) and slowness model (<tt>slo=</tt>). Outputs are an image (<tt>stdout</tt>) and a cube of Common Image Gathers (<tt>cig=</tt>). An important parameter is <tt>nrmax</tt>, the number of reference velocities. Its default value is 1, but for reasonable results it should be 5 or so. It is also good to specify nonzero taper values (<tt>tmx</tt> and, for 3-D, <tt>tmy</tt> as well). The values of padding parameters <tt>pmx</tt> and <tt>pmy</tt> are split in two by the program, i.e. if your data x axis is 501-points long, specify pmx=11 to get a value of 512 that will result in fast Fourier Transforms.

The program will also migrate converted-wave data if a file with the S-wave slowness model (<tt>sls=</tt>) is provided.

The <tt>vpvs</tt> parameter is only used when <tt>itype=h</tt>. Do not specify a <tt>vpvs</tt> value unless you know really well what you are doing.

===Usage example===
The commands below, slightly modified from [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/data/sigsbee/ptest/SConstruct?revision=3993&view=markup RSFSRC/book/data/sigsbee/ptest], show how to prepare the [http://www.reproducibility.org/RSF/book/data/sigsbee Sigsbee 2A] data and velocity for migration.

Convert input data (shots) from SEG-Y to RSF:
<bash>
sfsegyread tape=sigsbee2a_nfs.segy tfile=tdata.rsf hfile=/dev/null bfile=/dev/null > ddata.rsf
</bash>
Convert trace headers to float (required by <tt>sfheadermath</tt>):
<bash>
< tdata.rsf sfdd type=float > trchdr.rsf
</bash>
Shot positions:
<bash>
< trchdr.rsf sfheadermath output="fldr + 10925/150" | sfwindow squeeze=y > tsi.rsf
</bash>
Extract offset positions from the trace header files, eliminate length-1 axis, scale, create a header for binning (required by <tt>sfintbin</tt>):
<bash>
< trchdr.rsf sfheadermath output="offset" |\
sfwindow squeeze=y |\
sfmath output="input/75" |\
sfcat axis=2 space=n tsi.rsf |\
sftransp |\
sfdd type=int > tos.rsf
</bash>
Binning and muting:
<bash>
< ddata.rsf sfintbin head=tos.rsf xkey=0 ykey=1 |\
sfput label1=Time unit1=s d2=0.075 o2=0.0 label2=hx d3=0.150 o3=10.925 label3=sx |\
sfmutter half=false t0=1.0 v0=6.0 |\
sfput d2=0.02286 o2=0 unit2=km d3=0.04572 o3=3.32994 unit3=km > shots.rsf
</bash>
Keeping only 20 shots so that this 1-node job will not take forever, FFT-ing, decimating frequency slices (same as shortening the time axis), and creating y and hy axes of length 1:
<bash>
< shots.rsf sfwindow n3=20 f3=10 j3=20 |\
sffft1 |\
sfwindow n1=200 min1=1 j1=3 |\
sfspray axis=3 n=1 o=0 d=1 label=hy |\
sfspray axis=5 n=1 o=0 d=1 label=sy > rfft.rsf
</bash>
The dimensions of the cube thus created are:
<pre>
$ sfin rfft.rsf trail=n
rfft.rsf:
in="/var/tmp/rfft.rsf@"
esize=8 type=complex form=native
n1=200 d1=0.25 o1=1 label1="Frequency" unit1="Hz"
n2=348 d2=0.02286 o2=0 label2="hx" unit2="km"
n3=1 d3=1 o3=0 label3="hy" unit3="km"
n4=20 d4=0.9144 o4=3.78714 label4="sx" unit4="km"
1392000 elements 11136000 bytes
</pre>
Create the source wavelet (limited to the same frequency band as the data) and Fourier transform it:
<bash>
sfspike k1=1 n1=1500 d1=0.008 |\
sfbandpass flo=15 fhi=25 |\
sffft1 |\
sfwindow n1=200 min1=1 j1=3 |\
sfput label1=freq > sfft.rsf
</bash>
This creates a frequency-domain wavelet:
<pre>
$ sfin sfft.rsf
sfft.rsf:
in="/var/tmp/sfft.rsf@"
esize=8 type=complex form=native
n1=200 d1=0.25 o1=1 label1="freq" unit1="Hz"
200 elements 1600 bytes
</pre>
Create "synched" source and receiver wavefields with <tt>srsyn</tt> from wavelet and data frequency slices. Basically both the receiver and shot frequency slices are "placed" at the right location and padded with zeros up to the dimension of the x axis specified below.
<bash>
< rfft.rsf sfsrsyn nx=1067 dx=0.02286 ox=3.05562 wav=sfft.rsf swf=swav.rsf > rwav.rsf
</bash>
This creates frequency slices ready for migration for both source and receiver, only axis 1 (frequency) must become axis 3, for both datasets:
<bash>
< swav.rsf sftransp plane=12 | sftransp plane=23 > stra.rsf
</bash>
<bash>
< rwav.rsf sftransp plane=12 | sftransp plane=23 > rtra.rsf
</bash>
This creates a surface receiver wavefield ready for input to migration. Axis 4 is shot number. The values of axis 4 are arbitrary because each shot has been padded with zeros so that it covers the entire velocity model. Therefore the aperture of the downward continuation for each shot will be as large as the survey.
<pre>
sfin trail=n rtra.rsf
rtra.rsf:
in="/var/tmp/rtra.rsf@"
esize=8 type=complex form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=200 d3=0.25 o3=1 label3="w" unit3="Hz"
n4=20 d4=1 o4=0 label4="e" unit4="km"
4268000 elements 34144000 bytes
</pre>
Convert the velocity model from SEG-Y to RSF, decimate, convert from feet to km, transpose, convert to slowness and insert an additional axis:
<bash>
sfsegyread tape=sigsbee2a_migvel.sgy tfile=/dev/null hfile=/dev/null bfile=/dev/null |\
sfput o1=0 d1=0.00762 label1=z unit1=km o2=3.05562 d2=0.01143 label2=x unit2=km |\
sfwindow j1=4 j2=2 |\
sfscale rscale=0.0003048 |\
sftransp |\
sfmath output="1/input" |\
sfspray axis=2 n=1 d=1 o=0 |\
sfput label2=y > slow.rsf
</bash>
This creates a slowness file ready for input to migration, with an x axis identical to the x axis of the wavefield files:
<pre>
$ sfin slow.rsf
slow.rsf:
in="/var/tmp/slow.rsf@"
esize=4 type=float form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=301 d3=0.03048 o3=0 label3="z" unit3="km"
321167 elements 1284668 bytes
</pre>
Finally, the migration command (for a 4-processor machine, hence the <tt>ompnth</tt> value). We choose not to compute any image gathers (<tt>itype=o</tt>), but due to the construction of the program we still have to explicitly assign the <tt>cig</tt> tag, or else a RSF file with the name of the tag and no rsf extension will be created:
<bash>
< stra.rsf sfsrmig3 nrmax=20 dtmax=5e-05 eps=0.01 verb=y ompnth=4 \
tmx=16 rwf=rtra.rsf slo=slow.rsf itype=o cig=/dev/null > img.rsf
</bash>
The migration of 20 shots takes approximately 3 hours on a 4-processor machine (1 shot=9 minutes). Without the frequency slice decimation by a factor of 3 and the depth axis decimation by a factor of 4, it would have taken twelve times as much. The resulting image has a y axis of length 1:
<pre>
$ sfin img.rsf trail=n
img.rsf:
in="/var/tmp/img.rsf@"
esize=4 type=float form=native
n1=1067 d1=0.02286 o1=3.05562 label1="x" unit1="km"
n2=1 d2=1 o2=0 label2="y" unit2="km"
n3=301 d3=0.03048 o3=0 label3="z" unit3="km"
321167 elements 1284668 bytes
</pre>
To properly visualize the image, we need to eliminate the axis of length 1, then transpose the x and z axes to their natural position:
<bash>
<img.rsf sfwindow squeeze=y | sftransp | sfgrey > img.vpl
</bash>

=References=
<references/>

Guide to madagascar API

2011-08-06T02:05:47Z

Nick: /* Python interfaces to the Madagascar standalone programs */

[[Image:Fotolia_555071_XS.jpg|right|]]
<center>''This page was created from the LaTeX source in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/rsf/api.tex?view=markup book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<c>
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

sf_close();
exit(0);
}
</c>

Let us examine it in detail.
<c>
#include <rsf.h>
</c>

The include preprocessing directive is required to access the RSF interface.
<c>
sf_file in=NULL, out=NULL; /* Input and output files */
</c>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<c>
/* Initialize RSF */
sf_init(argc,argv);
</c>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<c>
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</c>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<c>
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</c>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> 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.
<c>
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</c>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<c>
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</c>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<c>
/* allocate floating point array */
trace = sf_floatalloc (n1);
</c>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<c>
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</c>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<c>
sf_close();
exit(0)
</c>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<cpp>
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</cpp>

Let us examine it line by line.
<cpp>
#include <rsf.hh>
</cpp>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<cpp>
sf_init(argc,argv); // Initialize RSF
</cpp>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<cpp>
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</cpp>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<cpp>
in.get("n1",n1);
n2=in.size(1);
</cpp>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<cpp>
par.get("clip",clip); // parameter from the command line
</cpp>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<cpp>
std::valarray<float> trace(n1);
</cpp>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<cpp>
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</cpp>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<fortran>
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</fortran>

Let us examine it in detail.
<fortran>
call sf_init()
</fortran>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<fortran>
in = sf_input("in")
out = sf_output("out")
</fortran>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<fortran>
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</fortran>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> 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.
<fortran>
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</fortran>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<fortran>
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<fortran>
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<fortran>
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do
end program Clipit
</fortran>

Let us examine it in detail.
<fortran>
use rsf
</fortran>

The program starts with importing the <tt>rsf</tt> module.
<fortran>
call sf_init() ! initialize RSF
</fortran>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<fortran>
in = rsf_input()
out = rsf_output()
</fortran>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<fortran>
if (sf_float /= gettype(in)) call sf_error("Need float type")

</fortran>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<fortran>
n2 = filesize(in,1)
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<fortran>
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==

The Python clip script is listed below.
<python>
#!/usr/bin/env python

import numpy
import rsf.api as rsf

par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type

n1 = input.int("n1")
n2 = input.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</python>

Let us examine it in detail.
<python>
import numpy
import rsf.api as rsf
</python>

The script starts with importing the <tt>numpy</tt> module and the
<tt>rsf</tt> API.
<python>
par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type
</python>

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.
<python>
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</python>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class1. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<python>
clip = par.float("clip")
assert clip
</python>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<python>
for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</python>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=10 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<python>
import numpy, rsf.api

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)
data = data.transpose() # Example of numpy in action

print data
</python>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16. 17.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17. 18.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<python>
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</python>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<python>
show()
</python>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<python>
savefig('myfile.png')
</python>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<python>
#!/usr/bin/env python
import rsf.api, numpy, sys, pylab

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)

pylab.imshow(data)
pylab.savefig('out.png')
</python>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

The <tt>m8r</tt> module has <tt>numpy</tt> and <tt>swig</tt> as dependencies. On systems on which it is not possible to install these dependencies, the <tt>rsf.user.sf</tt> module can be used instead (but with a different syntax and limited functionality).

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Guide to madagascar API

2011-08-06T02:05:16Z

Nick: /* Graphics with Matplotlib */

[[Image:Fotolia_555071_XS.jpg|right|]]
<center>''This page was created from the LaTeX source in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/rsf/api.tex?view=markup book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<c>
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

sf_close();
exit(0);
}
</c>

Let us examine it in detail.
<c>
#include <rsf.h>
</c>

The include preprocessing directive is required to access the RSF interface.
<c>
sf_file in=NULL, out=NULL; /* Input and output files */
</c>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<c>
/* Initialize RSF */
sf_init(argc,argv);
</c>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<c>
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</c>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<c>
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</c>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> 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.
<c>
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</c>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<c>
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</c>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<c>
/* allocate floating point array */
trace = sf_floatalloc (n1);
</c>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<c>
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</c>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<c>
sf_close();
exit(0)
</c>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<cpp>
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</cpp>

Let us examine it line by line.
<cpp>
#include <rsf.hh>
</cpp>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<cpp>
sf_init(argc,argv); // Initialize RSF
</cpp>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<cpp>
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</cpp>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<cpp>
in.get("n1",n1);
n2=in.size(1);
</cpp>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<cpp>
par.get("clip",clip); // parameter from the command line
</cpp>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<cpp>
std::valarray<float> trace(n1);
</cpp>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<cpp>
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</cpp>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<fortran>
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</fortran>

Let us examine it in detail.
<fortran>
call sf_init()
</fortran>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<fortran>
in = sf_input("in")
out = sf_output("out")
</fortran>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<fortran>
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</fortran>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> 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.
<fortran>
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</fortran>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<fortran>
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<fortran>
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<fortran>
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do
end program Clipit
</fortran>

Let us examine it in detail.
<fortran>
use rsf
</fortran>

The program starts with importing the <tt>rsf</tt> module.
<fortran>
call sf_init() ! initialize RSF
</fortran>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<fortran>
in = rsf_input()
out = rsf_output()
</fortran>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<fortran>
if (sf_float /= gettype(in)) call sf_error("Need float type")

</fortran>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<fortran>
n2 = filesize(in,1)
</fortran>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<fortran>
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</fortran>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==

The Python clip script is listed below.
<python>
#!/usr/bin/env python

import numpy
import rsf.api as rsf

par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type

n1 = input.int("n1")
n2 = input.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</python>

Let us examine it in detail.
<python>
import numpy
import rsf.api as rsf
</python>

The script starts with importing the <tt>numpy</tt> module and the
<tt>rsf</tt> API.
<python>
par = rsf.Par()
input = rsf.Input()
output = rsf.Output()
assert 'float' == input.type
</python>

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.
<python>
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</python>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class1. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<python>
clip = par.float("clip")
assert clip
</python>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<python>
for i2 in xrange(n2): # loop over traces
input.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</python>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=10 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<python>
import numpy, rsf.api

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)
data = data.transpose() # Example of numpy in action

print data
</python>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16. 17.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17. 18.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<python>
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</python>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<python>
show()
</python>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<python>
savefig('myfile.png')
</python>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<python>
#!/usr/bin/env python
import rsf.api, numpy, sys, pylab

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)

pylab.imshow(data)
pylab.savefig('out.png')
</python>
===Python interfaces to the Madagascar standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

The <tt>m8r</tt> module has <tt>numpy</tt> and <tt>swig</tt> as dependencies. On systems on which it is not possible to install these dependencies, the <tt>rsf.user.sf</tt> module can be used instead (but with a different syntax and limited functionality).

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Advanced Installation

2011-08-06T01:23:53Z

Nick: /* Compilers */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS, Scientific Linux, openSUSE==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<bash>
pfexec pkg install SUNWxorg-headers
</bash>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2011-08-06T01:23:17Z

Nick: /* Prerequisites */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully at least with the following compilers:
* gcc
* Intel (icc/ifort)
* open64
* clang
==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS, Scientific Linux, openSUSE==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<bash>
pfexec pkg install SUNWxorg-headers
</bash>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Library Reference

2011-07-24T18:54:52Z

Nick: /* Calling standalone madagascar programs from Python */

[[Image:Fotolia_2848987_XS.jpg|right|]]
If you are programming with Madagascar, please use the utilities described below instead of creating your own equivalents. The RSF library is written in C, and all facilities offered by it are available directly to the C API via inclusion of header files and linking with the library. Other APIs only have access to a limited set of functions from the library. The ultimate guide to what the libraries provide is the file <tt>RSFSRC/filt/lib/SConstruct</tt>, which contains the instructions for building the RSF library in C and the interfaces to it for the various APIs.
=C API=
==Macros==
The following useful macros are accessible through the C and C++ APIs:
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|Functions
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_ABS(a) || (a) >= 0 ? (a) : (-(a)) || Absolute value
|-
| SF_MAX(a,b) || (a) < (b) ? (b) : (a) || Maximum of two values
|-
| SF_MIN(a,b) || (a) < (b) ? (a) : (b) || Minimum of two values
|-
| SF_SIG(a) || (a) >= 0 ? 1 : -1 || Sign function
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|General constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_EOL || '\014' || End-of-line ASCII character
|-
| SF_EOT || '\004' || End-of-transmission ASCII character
|-
| SF_EPS || FLT_EPSILON || The smallest X of type float such that 1.0 + X != 1.0. From <tt>float.h</tt>
|-
| SF_HUGE || FLT_MAX || The largest finite representable value of type float. From <tt>float.h</tt>
|-
| SF_MAX_DIM || 9 || Maximum number of dimensions in a RSF file
|-
| SF_PI || 3.141592653589793 || The number pi
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|SEG-Y-related constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_SEGY_FORMAT || 24 || Byte position in SEG-Y binary reel header, where info on encoding of data samples is kept ([[Guide_to_madagascar_programs#SEG-Y_specific_parameters|format parameter in sfsegyread]])
|-
| SF_SEGY_NS || 20 || Byte position in SEG-Y binary reel header, where info on nr of samples in one trace is kept ([[Guide_to_madagascar_programs#Common_parameters|ns parameter in sfsegyread]])
|-
| SF_SEGY_DT || 16 || Byte position in SEG-Y binary reel header, where info on time sampling is kept
|-
| SF_EBCBYTES || 3200 || Bytes in the SEG-Y EBCDIC reel header
|-
| SF_BNYBYTES || 400 || Bytes in the SEG-Y binary reel header
|-
| SF_HDRBYTES || 240 || Bytes in each individual SEG-Y trace header
|-
| SF_NKEYS || 71 || Number of mandated header fields
|-
| SF_BHKEYS || 27 || Number of mandated binary fields
|}
These macros were found with: <bash>grep '# define SF_' $RSFROOT/include/rsf.h</bash>

==Data types==
See the [http://m8r.info/RSF/book/rsf/manual/manual_html/node8.html Data Types section of the Programming Reference Manual]

==Functions==
See the [http://www.reproducibility.org/RSF/book/rsf/manual/manual_html/ Programming Reference Manual].

==Function wrappers==
These programs make the respective function callable from the command line, so that it can be used directly with files/other programs through "metaprograms" (shell/Python scripts). This allows the user to get the best of all worlds -- fast development in Python, all of Madagascar's visualization tools for debugging, and the speed of code written in C. This allows fast prototyping, followed by writing a production version in C calling the functions used.
{| class="wikitable" align="center" cellspacing="0" border="1"
!Library function || Program
|-
| sf_filedims || [http://reproducibility.org/RSF/sffiledims.html filedims]
|-
| sf_leftsize || [http://reproducibility.org/RSF/sfleftsize.html leftsize]
|-
| sf_quantile || [http://reproducibility.org/RSF/sfquantile.html quantile]
|}

=C++ API=
==Macros==
Same as for the C API.

=Fortran 77 API=
=Fortran 90 API=
The interface is accessed by including a <tt>use rsf</tt> statement in your program. The source code for the <tt>rsf</tt> module can be viewed [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/api/f90/rsf.f90?view=markup in the repository]. A ('''G''') means that the entity was featured in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to API]].

==Constants==
For use with <tt>gettype</tt> and <tt>settype</tt>:
* <tt>sf_char</tt>=1
* <tt>sf_complex</tt>=4
* <tt>sf_float</tt>=3 ('''G''')
* <tt>sf_int</tt>=2
* <tt>sf_short</tt>=5
* <tt>sf_uchar</tt>=0

For use with <tt>sf_seek</tt>:
* <tt>sf_seek_set</tt>=0
* <tt>sf_seek_cur</tt>=1
* <tt>sf_seek_end</tt>=2

==Data types==
All procedures in Madagascar's F90 API act upon or take as input one of the following data types:
* <tt>axa</tt>: Holds some info about a hypercube axis (integer::n; real::o,d)
* <tt>file</tt>: Simply an interface to the <tt>sf_file</tt> type described in the C library.

==Functions==
Data types are indicated in ''italics'' and intent in '''''bold italics'''''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''Result''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>axisname</tt> || ''integer'' '''''in''''' <tt>i</tt>, optional ''character'' '''''in''''' <tt>mystring</tt> || ''character'' <tt>mystringi</tt> || Given a string <tt>mystring</tt> and a positive number <tt>i</tt>, this function will return the concatenation of the string and the number converted to string (<tt>mystringi</tt>). In practice, <tt>mystring</tt> will probably be "n", "o", "d", "label" or "unit", in preparation for writing to a header file. Default value for <tt>mystring</tt> is "n". || Verbose string operations in F90 || N
|-
| <tt>dimension</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''out''''' <tt>dims</tt> || ''integer'' <tt>n</tt> || Returns number of dimensions of already-open file handle <tt>tag</tt> in <tt>n</tt>, and the dimension values in <tt>dims</tt> || <tt>sf_filedims</tt> || N
|-
| <tt>filesize</tt> || ''file'' '''''in''''' <tt>tag</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || ''integer'' nr_elements || Computes number of <tt>n</tt>-dimensional subcubes in file hypercube. When <tt>n</tt> is absent, default is zero and the number of elements in file. || <tt>sf_filesize</tt>, <tt>sf_leftsize</tt>. || Y
|-
| <tt>gettype</tt> || ''file'' '''''in''''' <tt>tag</tt> || ''integer'' <tt>type</tt> || Reads the binary data type from the already-open file handle <tt>tag</tt>. The <tt>type</tt> constant should be then compared in the user-written code with one of the six type constants provided by the F90 interface || <tt>sf_gettype</tt> || Y
|-
| <tt>rsf_input</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for reading and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="in", which corresponds to the standard input stream || <tt>sf_input</tt> || Y
|-
| <tt>rsf_output</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for writing and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="out", which corresponds to the standard output stream || <tt>sf_input</tt> || Y
|}

==Subroutines==
Because subroutine names are preceded by a <tt>call</tt> statement, it is easy to find occurrences of them being used by typing: <bash>grep "call subroutine_name" {filt,user}/*/*.f90 user/*/*/*.f90</bash> in RSFSRC.

Below, data types are indicated in ''italics'' and intent in '''''bold italics'''''. The type multi means that multiple data types can be used (subroutine is overloaded). In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>from_either</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || This subroutine looks for the real or integer variable <tt>name</tt> first in the history file, then in the parameter table. If it it is not found and <tt>default</tt> is present, it assigns it to <tt>value</tt>, otherwise it terminates the program. || <tt>sf_histint</tt>, <tt>sf_getint</tt> || N
|-
| <tt>from_par</tt> || optional ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || If already-opened file handle <tt>tag</tt> is supplied, then it reads into <tt>value</tt> a parameter designated by <tt>name</tt> from a history file. Else, it reads it from the parameter table. If the parameter is not found and a <tt>default</tt> is present, then that is used, else ends with failure. It can read from both history files and parameter tables the following types: integer, integer array, real. Strings can be read only from the history file, and not from the parameter table. Real arrays, logicals and logical arrays can be read only from the parameter table. || <tt>sf_histint</tt>, <tt>sf_getint</tt>, <tt>sf_histints</tt>, <tt>sf_getints</tt>, <tt>sf_histfloat</tt>, <tt>sf_getfloat</tt>, <tt>sf_histstring</tt>, <tt>sf_getfloats</tt>, <tt>sf_getbool</tt>, <tt>sf_getbools</tt> || Y
|-
| <tt>iaxa</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''axa'' '''''out''''' <tt>axisname</tt>, ''integer'' '''''in''''' <tt>axisnr</tt> || Read axis with number <tt>axisnr</tt> as axis <tt>axisname</tt> from the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>oaxa</tt> || ''file'' '''''in''''' <tt>tag,</tt> ''axa'' '''''in''''' <tt>axisname,</tt> ''integer'' '''''in''''' <tt>axisnr</tt> || Write axis <tt>axisname</tt> (i.e. its n, o, d) as axis with number <tt>axisnr</tt> to the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>raxa</tt> || ''axa'' '''''in''''' <tt>axisname</tt> || unformatted write to I/O unit nr. 0 (usually stdout, but system-dependent) of the contents of the <tt>axisname</tt> structure (n, o, d) || F90 write statement || N
|-
| <tt>rsf_read</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''out''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, the real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be read into it from an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, reads enough to fill the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D. || <tt>sf_floatread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''in''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be written to an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, writes to file the entire contents of the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|-
| <tt>settype</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''in''''' <tt>file_type</tt> || Write a type for the binary data to the already-open file header indicated by <tt>tag</tt>. Data type constants are also provided by the F90 API. || <tt>sf_settype</tt> || N
|-
| <tt>to_par</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''in''''' <tt>value</tt> || Writes <tt>name=value</tt> to already-opened file specified by <tt>tag</tt>. Value can be integer, integer array, real or character. || <tt>sf_putint</tt>, <tt>sf_putints</tt>, <tt>sf_putfloat</tt>, <tt>sf_putstring</tt> || N
|}

==Functions from the C library==
Functions from the C library for which an interface has been defined at the end of <tt>RSFSRC/api/f90/fortran.c</tt> can be called directly from Madagascar F90 programs. The programmer must know, however, that '''an argument type mismatch will result in a silent failure, with no informative errors.''' There may be other sources of problems as well. Caution therefore must be advised when calling these functions. The reason for these issues is that [http://people.scs.fsu.edu/~burkardt/f_src/mixed/mixed.html if a FORTRAN90 routine needs to pass a scalar parameter to a C routine, there is no standard way to ensure that a value is passed rather than an address]. The success rate of calling C from Fortran [http://w3.pppl.gov/~dmccune/papers-reports/linux_f90.txt is compiler-dependent] and [http://www.cs.sandia.gov/Zoltan/ug_html/ug_fortran.html special types may have to be defined for portability]. If you do have to call a C function from F90, follow the examples of the functions below. Use the C library reference to find argument and output types. A C-to-F90 data type dictionary follows:
{| class="wikitable" align="center" cellspacing="0" border="1"
! style="background:#ffdead;" | C ||! style="background:#ffdead;" | F90
|-
| RSFFILE || type(file)
|-
| INT || integer
|-
| OFFSETT || integer(kind=OFFKIND)
|}
===Void-output functions callable as subroutines===
These can be treated as subroutines, and accessed with a <tt>call</tt> statement. Follow
* <tt>sf_error</tt> ('''G''')
* <tt>sf_init</tt> ('''G''') ('''''Can it also be called in subroutines if we want to isolate I/O operations there?''''')
* <tt>sf_seek</tt>

===Non-void-output functions===
It is a good idea to declare in your program the function output type and use the keyword <tt>external</tt>, i.e.:
<pre>real, external :: sf_dosomething</pre>
Alternately, you may define a F90 <tt>interface</tt> block for the procedure(s).

Several examples can be found in <tt>RSFSRC/filt/lib/rsf.f90</tt>, but they are not enumerated here because F90 wrappers exist for them and they should be used instead of the direct calls to the C library functions.

=Matlab API=
Data types are indicated in ''italics''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means: "Demo-ed in the [[Guide_to_madagascar_API#MATLAB_interface|Guide to the Matlab API]]?"

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>rsf_create</tt> || Arg 1: ''string (row vector)'' <tt>new_file_name</tt>; Arg 2: ''string (row vector)'' <tt>old_file_name</tt>, or ''double (column vector)'' '''in''' <tt>new_file_cube_dims</tt> || Writes to disk RSF header of native_float hypercube of desired dimensions. Takes as input the name of the new file and either the name of another file with a cube of the same size, or a column with cube dimensions || <tt>sf_fileflush</tt>, or <tt>sf_putint</tt> and <tt>sf_setformat</tt> || Y
|-
| <tt>rsf_dim</tt> || Arg1: ''string (row vector)'' <tt>filename</tt> || Returns a 9-element vector [n1, n2, ... n9] with the dimensions of the hypercube as described in the RSF header '''filename'''. Missing dimensions are given the value 1 || <tt>sf_filedims</tt> || Y
|-
| <tt>rsf_par</tt> || Arg 1: ''string (row vector)'' <tt>filename</tt>; Arg 2: ''string (row vector)'' <tt>par_name</tt>; Arg 3: ''string (row vector)'' <tt>par_type</tt>: i[nt], l[ogical], f[loat]; Arg 4: ''double (scalar)'' <tt>default_val</tt> || Returns a scalar parameter read from a RSF header || <tt>sf_histint</tt>, <tt>sf_histbool</tt>, <tt>sf_histfloat</tt> || N
|-
| <tt>rsf_read</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Reads <tt>data_array</tt> from <tt>filename</tt>. Input data should be of SF_FLOAT, SF_INT or SF_COMPLEX type. The <tt>same</tt> parameter is a way to indicate if the data is read from the same file as before or from a newly opened file. If <tt>same</tt> is not given, the data will be read from the beginning of the file. || <tt>sf_floatread</tt>, <tt>sf_intread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Writes <tt>data_array</tt> to <tt>filename</tt>. Data to be written can be integer, float, double or complex. It will get cast to RSF's native_float or native_complex encoding. || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|}

=Octave API=

=Java API=

''There are two APIs available for Java. New programs should be written to use the SWIG API. The Mines JTK API is provided here only for reference for those who may still be using it.''

== SWIG API ==
The SWIG API includes three classes. The methods that each class exposes are as follows:

=== RSF ===
<java>
public RSF(String[] args); // Constructor, pass the command line arguments
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

=== Input ===
<java>
public Input(String name); // Constructor, pass a filename. "in" defaults to stdin
public int getN(int index); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public float getDelta(int index); // Gets the delta for that index. Returns 0.0 if not found.
public float getOrigin(int index); // Gets the origin for that file. Returns 0.0 if not found.
public String getLabel(int index); // Gets the label name for the index. Returns "" if not found.
public String getUnit(int index); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void read(float[] array); // Read data from the open RSF file into the given array. Reads the length of the array only.
public void read(float[][] array); // The following methods all read data from the RSF file in the given shape of the array.
public void read(float[][][] array);
public void read(float[][][][] array);
public void read(float[][][][][] array);
public void read(float[][][][][][] array);
public void read(float[][][][][][][] array);
public void read(float[][][][][][][][] array);
public void read(float[][][][][][][][][] array);
</java>

=== Output ===
<java>
public Output(String name); // Constructor, pass a filename. "out" points to standard out.
public void setN(int index, int n); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public void setDelta(int index, float delta); // Gets the delta for that index. Returns 0.0 if not found.
public void setOrigin(int index, float origin); // Gets the origin for that file. Returns 0.0 if not found.
public void setLabel(int index, String label); // Gets the label name for the index. Returns "" if not found.
public void setUnit(int index, String unit); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void write(float[] array); // Writes data to the RSF file from the given array. Writes the shape of the array only.
public void write(float[][] array); // The following methods all write data using the given shape of the array.
public void write(float[][][] array);
public void write(float[][][][] array);
public void write(float[][][][][] array);
public void write(float[][][][][][] array);
public void write(float[][][][][][][] array);
public void write(float[][][][][][][][] array);
public void write(float[][][][][][][][][] array);
</java>

Additional notes:

Java does not support complex numbers by default. To use complex numbers, you must convert complex valued RSF files to floating point numbers using sfdd .

== MINES JTK API ==
''' THIS API IS DEPRECATED. PLEASE DEVELOP YOUR PROGRAMS TO BE COMPATIBLE WITH THE SWIG API.'''

The following methods are exposed directly at this time:

==Par Class==

<java>
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

==Header Class==

<java>
public void setN(int dim, int n); // Used to set the number of elements in a dimension. For dimension 1, use an index value of 1.
public int getN(int dim);
public void setDelta(int dim, float delta); // Used to set the delta for a dimension. For dimension 1, use an index value of 1, not 0.
public float getDelta(int dim);
public void setOrigin(int dim, float origin); // Used to set the origin for a dimension.
public float getOrigin(int dim);
public void setLabel(int dim, String label); // Sets the label for a dimension.
public String getLabel(int dim);
public void setUnit(int dim, String unit); // Sets the unit for a dimension.
public String getUnit(int dim);
public void setFormat(String format); // Sets the output format information, has no effect on how Java treats the data.
public String getFormat();
public void setPath(String path); /* Sets the location of the binary file that corresponds to this header file.
Not used for writing information to an RSF file. */
public String getPath();
public void setName(String name); /* Change the file name that this header corresponds to. When writing this info to an RSF file,
the API automatically will determine the binary file that goes along with this filename. */
public String getName();
public String toString(); // Can be used to print out information about the header file.
</java>

==Writer Class==

When writing out RSF files, the header file is output in the same directory as the java program was executed. The binary file is placed according to the DATAPATH environment variable. <tt>saveName</tt> is the filename that you want to save your header to. Writing to standard out is not supported. All files must be saved via a name.

<java>
public static void writeRSF(RSFHeader header, float[] data, String saveName); // Writes a 1D array to an RSF Header and binary file
public static void writeRSF(RSFHeader header, float[][] data, String saveName); // Writes a 2D array to an RSF header and binary file.
public static void writeRSF(RSFHeader header, float[][][] data, String saveName); // Writes a 3D array to an RSF header and binary file.
</java>

==Reader Class==

<java>
public static Header readHeader(String headerFileName); // Used to parse the RSF Header file for information.
public static float[] readBinary(RSFHeader header); // Reads the RSF binary data file into a single array.
public static float[][] readBinary2D(RSFHeader header); // Reads the RSF binary data file into a 2D array.
public static float[][][] readBinary3D(RSFHeader header); // Reads the RSF binary data file into a 3D array.
</java>

=Python API=

To use the python api, you need to import the rsf package via: <tt>import rsf.api</tt> .

'''NOTE: Madagascar now has automatic documentation, currently with Epydoc, and more to come. The information in the table below will be merged into it.'''

The rsf package has the following members:

{| border="1"
|+ Overview of the Python RSF API
! Class !! Use !! Constructor !! Example !! Available Methods
|-
|File
|-
|Filter
|-
|Movie
|-
|Input || Provides a basic way to read rsf files. || file = rsf.Input(name) || input = rsf.Input(''name''); n1 = input.int('n1') || read(data), data is a numpy array to be read into.
|-
| || || || || close()
|-
| || || || || float(key, default=None), key is a string to be extracted, e.g. 'n1'.
|-
| || || || || int(key, default=None), key is a string to be extracted.
|-
| || || || || ints(key, num, default=None), key is a string, num is the number of ints.
|-
| || || || || put(key, val), key is a string to set the value for, val is a numerical value (int or float).
|-
| || || || || ... and more, type help(rsf.Input) on a python interactive session for more information.
|-
|Output || Provides a way to output numpy arrays to rsf files. || file = rsf.Output(name) || output=rsf.Output(name); output.write(data)
|-
|OverUnder
|-
|Overlay
|-
|Par || Provides a method for accessing rsf parameters passed from the command line. || par = rsf.Par() || par = rsf.Par(); velname = par.string('vel')
|-
|SideBySide
|-
|Temp
|-
|Vplot || View vplot graphics files from within python. || plot = rsf.Vplot(name) || plot = rsf.Vplot(name); plot.show()
|-
|Vppen
|}

=Calling standalone madagascar programs from Python=
On systems with recent versions of Python (at least 2.4), and with Numpy and Swig installed, use [http://www.reproducibility.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html the m8r module].

On old systems where dependencies cannot be easily installed (i.e. industrial clusters), use the <tt>sf</tt> module (i.e. <tt>import rsf.user.sf as sf</tt>).

=SCons custom methods=
==Custom builders==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''File implemented in''' || '''Function''' || '''What it does'''
|-
| <tt>RSF_Include</tt> || RSFSRC/framework/bldutil.py || Header ||
|-
| <tt>RSF_Place</tt> || RSFSRC/framework/bldutil.py || Place ||
|-
| <tt>RSF_Pycompile</tt> || RSFSRC/framework/bldutil.py ||Pycompile ||
|-
| <tt>RSF_Docmerge</tt> || RSFSRC/framework/bldutil.py || Docmerge ||
|}

Other entities can be found in RSFSRC/framework/rsf/proj.py and tex.py

Library Reference

2011-07-24T18:48:53Z

Nick: /* Calling standalone madagascar programs from Python */

[[Image:Fotolia_2848987_XS.jpg|right|]]
If you are programming with Madagascar, please use the utilities described below instead of creating your own equivalents. The RSF library is written in C, and all facilities offered by it are available directly to the C API via inclusion of header files and linking with the library. Other APIs only have access to a limited set of functions from the library. The ultimate guide to what the libraries provide is the file <tt>RSFSRC/filt/lib/SConstruct</tt>, which contains the instructions for building the RSF library in C and the interfaces to it for the various APIs.
=C API=
==Macros==
The following useful macros are accessible through the C and C++ APIs:
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|Functions
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_ABS(a) || (a) >= 0 ? (a) : (-(a)) || Absolute value
|-
| SF_MAX(a,b) || (a) < (b) ? (b) : (a) || Maximum of two values
|-
| SF_MIN(a,b) || (a) < (b) ? (a) : (b) || Minimum of two values
|-
| SF_SIG(a) || (a) >= 0 ? 1 : -1 || Sign function
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|General constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_EOL || '\014' || End-of-line ASCII character
|-
| SF_EOT || '\004' || End-of-transmission ASCII character
|-
| SF_EPS || FLT_EPSILON || The smallest X of type float such that 1.0 + X != 1.0. From <tt>float.h</tt>
|-
| SF_HUGE || FLT_MAX || The largest finite representable value of type float. From <tt>float.h</tt>
|-
| SF_MAX_DIM || 9 || Maximum number of dimensions in a RSF file
|-
| SF_PI || 3.141592653589793 || The number pi
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|SEG-Y-related constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_SEGY_FORMAT || 24 || Byte position in SEG-Y binary reel header, where info on encoding of data samples is kept ([[Guide_to_madagascar_programs#SEG-Y_specific_parameters|format parameter in sfsegyread]])
|-
| SF_SEGY_NS || 20 || Byte position in SEG-Y binary reel header, where info on nr of samples in one trace is kept ([[Guide_to_madagascar_programs#Common_parameters|ns parameter in sfsegyread]])
|-
| SF_SEGY_DT || 16 || Byte position in SEG-Y binary reel header, where info on time sampling is kept
|-
| SF_EBCBYTES || 3200 || Bytes in the SEG-Y EBCDIC reel header
|-
| SF_BNYBYTES || 400 || Bytes in the SEG-Y binary reel header
|-
| SF_HDRBYTES || 240 || Bytes in each individual SEG-Y trace header
|-
| SF_NKEYS || 71 || Number of mandated header fields
|-
| SF_BHKEYS || 27 || Number of mandated binary fields
|}
These macros were found with: <bash>grep '# define SF_' $RSFROOT/include/rsf.h</bash>

==Data types==
See the [http://m8r.info/RSF/book/rsf/manual/manual_html/node8.html Data Types section of the Programming Reference Manual]

==Functions==
See the [http://www.reproducibility.org/RSF/book/rsf/manual/manual_html/ Programming Reference Manual].

==Function wrappers==
These programs make the respective function callable from the command line, so that it can be used directly with files/other programs through "metaprograms" (shell/Python scripts). This allows the user to get the best of all worlds -- fast development in Python, all of Madagascar's visualization tools for debugging, and the speed of code written in C. This allows fast prototyping, followed by writing a production version in C calling the functions used.
{| class="wikitable" align="center" cellspacing="0" border="1"
!Library function || Program
|-
| sf_filedims || [http://reproducibility.org/RSF/sffiledims.html filedims]
|-
| sf_leftsize || [http://reproducibility.org/RSF/sfleftsize.html leftsize]
|-
| sf_quantile || [http://reproducibility.org/RSF/sfquantile.html quantile]
|}

=C++ API=
==Macros==
Same as for the C API.

=Fortran 77 API=
=Fortran 90 API=
The interface is accessed by including a <tt>use rsf</tt> statement in your program. The source code for the <tt>rsf</tt> module can be viewed [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/api/f90/rsf.f90?view=markup in the repository]. A ('''G''') means that the entity was featured in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to API]].

==Constants==
For use with <tt>gettype</tt> and <tt>settype</tt>:
* <tt>sf_char</tt>=1
* <tt>sf_complex</tt>=4
* <tt>sf_float</tt>=3 ('''G''')
* <tt>sf_int</tt>=2
* <tt>sf_short</tt>=5
* <tt>sf_uchar</tt>=0

For use with <tt>sf_seek</tt>:
* <tt>sf_seek_set</tt>=0
* <tt>sf_seek_cur</tt>=1
* <tt>sf_seek_end</tt>=2

==Data types==
All procedures in Madagascar's F90 API act upon or take as input one of the following data types:
* <tt>axa</tt>: Holds some info about a hypercube axis (integer::n; real::o,d)
* <tt>file</tt>: Simply an interface to the <tt>sf_file</tt> type described in the C library.

==Functions==
Data types are indicated in ''italics'' and intent in '''''bold italics'''''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''Result''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>axisname</tt> || ''integer'' '''''in''''' <tt>i</tt>, optional ''character'' '''''in''''' <tt>mystring</tt> || ''character'' <tt>mystringi</tt> || Given a string <tt>mystring</tt> and a positive number <tt>i</tt>, this function will return the concatenation of the string and the number converted to string (<tt>mystringi</tt>). In practice, <tt>mystring</tt> will probably be "n", "o", "d", "label" or "unit", in preparation for writing to a header file. Default value for <tt>mystring</tt> is "n". || Verbose string operations in F90 || N
|-
| <tt>dimension</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''out''''' <tt>dims</tt> || ''integer'' <tt>n</tt> || Returns number of dimensions of already-open file handle <tt>tag</tt> in <tt>n</tt>, and the dimension values in <tt>dims</tt> || <tt>sf_filedims</tt> || N
|-
| <tt>filesize</tt> || ''file'' '''''in''''' <tt>tag</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || ''integer'' nr_elements || Computes number of <tt>n</tt>-dimensional subcubes in file hypercube. When <tt>n</tt> is absent, default is zero and the number of elements in file. || <tt>sf_filesize</tt>, <tt>sf_leftsize</tt>. || Y
|-
| <tt>gettype</tt> || ''file'' '''''in''''' <tt>tag</tt> || ''integer'' <tt>type</tt> || Reads the binary data type from the already-open file handle <tt>tag</tt>. The <tt>type</tt> constant should be then compared in the user-written code with one of the six type constants provided by the F90 interface || <tt>sf_gettype</tt> || Y
|-
| <tt>rsf_input</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for reading and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="in", which corresponds to the standard input stream || <tt>sf_input</tt> || Y
|-
| <tt>rsf_output</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for writing and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="out", which corresponds to the standard output stream || <tt>sf_input</tt> || Y
|}

==Subroutines==
Because subroutine names are preceded by a <tt>call</tt> statement, it is easy to find occurrences of them being used by typing: <bash>grep "call subroutine_name" {filt,user}/*/*.f90 user/*/*/*.f90</bash> in RSFSRC.

Below, data types are indicated in ''italics'' and intent in '''''bold italics'''''. The type multi means that multiple data types can be used (subroutine is overloaded). In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>from_either</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || This subroutine looks for the real or integer variable <tt>name</tt> first in the history file, then in the parameter table. If it it is not found and <tt>default</tt> is present, it assigns it to <tt>value</tt>, otherwise it terminates the program. || <tt>sf_histint</tt>, <tt>sf_getint</tt> || N
|-
| <tt>from_par</tt> || optional ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || If already-opened file handle <tt>tag</tt> is supplied, then it reads into <tt>value</tt> a parameter designated by <tt>name</tt> from a history file. Else, it reads it from the parameter table. If the parameter is not found and a <tt>default</tt> is present, then that is used, else ends with failure. It can read from both history files and parameter tables the following types: integer, integer array, real. Strings can be read only from the history file, and not from the parameter table. Real arrays, logicals and logical arrays can be read only from the parameter table. || <tt>sf_histint</tt>, <tt>sf_getint</tt>, <tt>sf_histints</tt>, <tt>sf_getints</tt>, <tt>sf_histfloat</tt>, <tt>sf_getfloat</tt>, <tt>sf_histstring</tt>, <tt>sf_getfloats</tt>, <tt>sf_getbool</tt>, <tt>sf_getbools</tt> || Y
|-
| <tt>iaxa</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''axa'' '''''out''''' <tt>axisname</tt>, ''integer'' '''''in''''' <tt>axisnr</tt> || Read axis with number <tt>axisnr</tt> as axis <tt>axisname</tt> from the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>oaxa</tt> || ''file'' '''''in''''' <tt>tag,</tt> ''axa'' '''''in''''' <tt>axisname,</tt> ''integer'' '''''in''''' <tt>axisnr</tt> || Write axis <tt>axisname</tt> (i.e. its n, o, d) as axis with number <tt>axisnr</tt> to the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>raxa</tt> || ''axa'' '''''in''''' <tt>axisname</tt> || unformatted write to I/O unit nr. 0 (usually stdout, but system-dependent) of the contents of the <tt>axisname</tt> structure (n, o, d) || F90 write statement || N
|-
| <tt>rsf_read</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''out''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, the real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be read into it from an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, reads enough to fill the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D. || <tt>sf_floatread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''in''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be written to an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, writes to file the entire contents of the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|-
| <tt>settype</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''in''''' <tt>file_type</tt> || Write a type for the binary data to the already-open file header indicated by <tt>tag</tt>. Data type constants are also provided by the F90 API. || <tt>sf_settype</tt> || N
|-
| <tt>to_par</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''in''''' <tt>value</tt> || Writes <tt>name=value</tt> to already-opened file specified by <tt>tag</tt>. Value can be integer, integer array, real or character. || <tt>sf_putint</tt>, <tt>sf_putints</tt>, <tt>sf_putfloat</tt>, <tt>sf_putstring</tt> || N
|}

==Functions from the C library==
Functions from the C library for which an interface has been defined at the end of <tt>RSFSRC/api/f90/fortran.c</tt> can be called directly from Madagascar F90 programs. The programmer must know, however, that '''an argument type mismatch will result in a silent failure, with no informative errors.''' There may be other sources of problems as well. Caution therefore must be advised when calling these functions. The reason for these issues is that [http://people.scs.fsu.edu/~burkardt/f_src/mixed/mixed.html if a FORTRAN90 routine needs to pass a scalar parameter to a C routine, there is no standard way to ensure that a value is passed rather than an address]. The success rate of calling C from Fortran [http://w3.pppl.gov/~dmccune/papers-reports/linux_f90.txt is compiler-dependent] and [http://www.cs.sandia.gov/Zoltan/ug_html/ug_fortran.html special types may have to be defined for portability]. If you do have to call a C function from F90, follow the examples of the functions below. Use the C library reference to find argument and output types. A C-to-F90 data type dictionary follows:
{| class="wikitable" align="center" cellspacing="0" border="1"
! style="background:#ffdead;" | C ||! style="background:#ffdead;" | F90
|-
| RSFFILE || type(file)
|-
| INT || integer
|-
| OFFSETT || integer(kind=OFFKIND)
|}
===Void-output functions callable as subroutines===
These can be treated as subroutines, and accessed with a <tt>call</tt> statement. Follow
* <tt>sf_error</tt> ('''G''')
* <tt>sf_init</tt> ('''G''') ('''''Can it also be called in subroutines if we want to isolate I/O operations there?''''')
* <tt>sf_seek</tt>

===Non-void-output functions===
It is a good idea to declare in your program the function output type and use the keyword <tt>external</tt>, i.e.:
<pre>real, external :: sf_dosomething</pre>
Alternately, you may define a F90 <tt>interface</tt> block for the procedure(s).

Several examples can be found in <tt>RSFSRC/filt/lib/rsf.f90</tt>, but they are not enumerated here because F90 wrappers exist for them and they should be used instead of the direct calls to the C library functions.

=Matlab API=
Data types are indicated in ''italics''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means: "Demo-ed in the [[Guide_to_madagascar_API#MATLAB_interface|Guide to the Matlab API]]?"

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>rsf_create</tt> || Arg 1: ''string (row vector)'' <tt>new_file_name</tt>; Arg 2: ''string (row vector)'' <tt>old_file_name</tt>, or ''double (column vector)'' '''in''' <tt>new_file_cube_dims</tt> || Writes to disk RSF header of native_float hypercube of desired dimensions. Takes as input the name of the new file and either the name of another file with a cube of the same size, or a column with cube dimensions || <tt>sf_fileflush</tt>, or <tt>sf_putint</tt> and <tt>sf_setformat</tt> || Y
|-
| <tt>rsf_dim</tt> || Arg1: ''string (row vector)'' <tt>filename</tt> || Returns a 9-element vector [n1, n2, ... n9] with the dimensions of the hypercube as described in the RSF header '''filename'''. Missing dimensions are given the value 1 || <tt>sf_filedims</tt> || Y
|-
| <tt>rsf_par</tt> || Arg 1: ''string (row vector)'' <tt>filename</tt>; Arg 2: ''string (row vector)'' <tt>par_name</tt>; Arg 3: ''string (row vector)'' <tt>par_type</tt>: i[nt], l[ogical], f[loat]; Arg 4: ''double (scalar)'' <tt>default_val</tt> || Returns a scalar parameter read from a RSF header || <tt>sf_histint</tt>, <tt>sf_histbool</tt>, <tt>sf_histfloat</tt> || N
|-
| <tt>rsf_read</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Reads <tt>data_array</tt> from <tt>filename</tt>. Input data should be of SF_FLOAT, SF_INT or SF_COMPLEX type. The <tt>same</tt> parameter is a way to indicate if the data is read from the same file as before or from a newly opened file. If <tt>same</tt> is not given, the data will be read from the beginning of the file. || <tt>sf_floatread</tt>, <tt>sf_intread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Writes <tt>data_array</tt> to <tt>filename</tt>. Data to be written can be integer, float, double or complex. It will get cast to RSF's native_float or native_complex encoding. || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|}

=Octave API=

=Java API=

''There are two APIs available for Java. New programs should be written to use the SWIG API. The Mines JTK API is provided here only for reference for those who may still be using it.''

== SWIG API ==
The SWIG API includes three classes. The methods that each class exposes are as follows:

=== RSF ===
<java>
public RSF(String[] args); // Constructor, pass the command line arguments
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

=== Input ===
<java>
public Input(String name); // Constructor, pass a filename. "in" defaults to stdin
public int getN(int index); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public float getDelta(int index); // Gets the delta for that index. Returns 0.0 if not found.
public float getOrigin(int index); // Gets the origin for that file. Returns 0.0 if not found.
public String getLabel(int index); // Gets the label name for the index. Returns "" if not found.
public String getUnit(int index); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void read(float[] array); // Read data from the open RSF file into the given array. Reads the length of the array only.
public void read(float[][] array); // The following methods all read data from the RSF file in the given shape of the array.
public void read(float[][][] array);
public void read(float[][][][] array);
public void read(float[][][][][] array);
public void read(float[][][][][][] array);
public void read(float[][][][][][][] array);
public void read(float[][][][][][][][] array);
public void read(float[][][][][][][][][] array);
</java>

=== Output ===
<java>
public Output(String name); // Constructor, pass a filename. "out" points to standard out.
public void setN(int index, int n); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public void setDelta(int index, float delta); // Gets the delta for that index. Returns 0.0 if not found.
public void setOrigin(int index, float origin); // Gets the origin for that file. Returns 0.0 if not found.
public void setLabel(int index, String label); // Gets the label name for the index. Returns "" if not found.
public void setUnit(int index, String unit); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void write(float[] array); // Writes data to the RSF file from the given array. Writes the shape of the array only.
public void write(float[][] array); // The following methods all write data using the given shape of the array.
public void write(float[][][] array);
public void write(float[][][][] array);
public void write(float[][][][][] array);
public void write(float[][][][][][] array);
public void write(float[][][][][][][] array);
public void write(float[][][][][][][][] array);
public void write(float[][][][][][][][][] array);
</java>

Additional notes:

Java does not support complex numbers by default. To use complex numbers, you must convert complex valued RSF files to floating point numbers using sfdd .

== MINES JTK API ==
''' THIS API IS DEPRECATED. PLEASE DEVELOP YOUR PROGRAMS TO BE COMPATIBLE WITH THE SWIG API.'''

The following methods are exposed directly at this time:

==Par Class==

<java>
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

==Header Class==

<java>
public void setN(int dim, int n); // Used to set the number of elements in a dimension. For dimension 1, use an index value of 1.
public int getN(int dim);
public void setDelta(int dim, float delta); // Used to set the delta for a dimension. For dimension 1, use an index value of 1, not 0.
public float getDelta(int dim);
public void setOrigin(int dim, float origin); // Used to set the origin for a dimension.
public float getOrigin(int dim);
public void setLabel(int dim, String label); // Sets the label for a dimension.
public String getLabel(int dim);
public void setUnit(int dim, String unit); // Sets the unit for a dimension.
public String getUnit(int dim);
public void setFormat(String format); // Sets the output format information, has no effect on how Java treats the data.
public String getFormat();
public void setPath(String path); /* Sets the location of the binary file that corresponds to this header file.
Not used for writing information to an RSF file. */
public String getPath();
public void setName(String name); /* Change the file name that this header corresponds to. When writing this info to an RSF file,
the API automatically will determine the binary file that goes along with this filename. */
public String getName();
public String toString(); // Can be used to print out information about the header file.
</java>

==Writer Class==

When writing out RSF files, the header file is output in the same directory as the java program was executed. The binary file is placed according to the DATAPATH environment variable. <tt>saveName</tt> is the filename that you want to save your header to. Writing to standard out is not supported. All files must be saved via a name.

<java>
public static void writeRSF(RSFHeader header, float[] data, String saveName); // Writes a 1D array to an RSF Header and binary file
public static void writeRSF(RSFHeader header, float[][] data, String saveName); // Writes a 2D array to an RSF header and binary file.
public static void writeRSF(RSFHeader header, float[][][] data, String saveName); // Writes a 3D array to an RSF header and binary file.
</java>

==Reader Class==

<java>
public static Header readHeader(String headerFileName); // Used to parse the RSF Header file for information.
public static float[] readBinary(RSFHeader header); // Reads the RSF binary data file into a single array.
public static float[][] readBinary2D(RSFHeader header); // Reads the RSF binary data file into a 2D array.
public static float[][][] readBinary3D(RSFHeader header); // Reads the RSF binary data file into a 3D array.
</java>

=Python API=

To use the python api, you need to import the rsf package via: <tt>import rsf.api</tt> .

'''NOTE: Madagascar now has automatic documentation, currently with Epydoc, and more to come. The information in the table below will be merged into it.'''

The rsf package has the following members:

{| border="1"
|+ Overview of the Python RSF API
! Class !! Use !! Constructor !! Example !! Available Methods
|-
|File
|-
|Filter
|-
|Movie
|-
|Input || Provides a basic way to read rsf files. || file = rsf.Input(name) || input = rsf.Input(''name''); n1 = input.int('n1') || read(data), data is a numpy array to be read into.
|-
| || || || || close()
|-
| || || || || float(key, default=None), key is a string to be extracted, e.g. 'n1'.
|-
| || || || || int(key, default=None), key is a string to be extracted.
|-
| || || || || ints(key, num, default=None), key is a string, num is the number of ints.
|-
| || || || || put(key, val), key is a string to set the value for, val is a numerical value (int or float).
|-
| || || || || ... and more, type help(rsf.Input) on a python interactive session for more information.
|-
|Output || Provides a way to output numpy arrays to rsf files. || file = rsf.Output(name) || output=rsf.Output(name); output.write(data)
|-
|OverUnder
|-
|Overlay
|-
|Par || Provides a method for accessing rsf parameters passed from the command line. || par = rsf.Par() || par = rsf.Par(); velname = par.string('vel')
|-
|SideBySide
|-
|Temp
|-
|Vplot || View vplot graphics files from within python. || plot = rsf.Vplot(name) || plot = rsf.Vplot(name); plot.show()
|-
|Vppen
|}

=Calling standalone madagascar programs from Python=
On systems with recent versions of Python (at least 2.4), and with Numpy and Swig installed, use [http://www.reproducibility.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html the m8r module].

On old systems where dependencies cannot be easily installed (i.e. industrial clusters), the <tt>sf</tt> module (i.e. <tt>import rsf.user.sf as sf</tt>).

=SCons custom methods=
==Custom builders==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''File implemented in''' || '''Function''' || '''What it does'''
|-
| <tt>RSF_Include</tt> || RSFSRC/framework/bldutil.py || Header ||
|-
| <tt>RSF_Place</tt> || RSFSRC/framework/bldutil.py || Place ||
|-
| <tt>RSF_Pycompile</tt> || RSFSRC/framework/bldutil.py ||Pycompile ||
|-
| <tt>RSF_Docmerge</tt> || RSFSRC/framework/bldutil.py || Docmerge ||
|}

Other entities can be found in RSFSRC/framework/rsf/proj.py and tex.py

Library Reference

2011-07-24T18:48:39Z

Nick: /* SCons custom methods */

[[Image:Fotolia_2848987_XS.jpg|right|]]
If you are programming with Madagascar, please use the utilities described below instead of creating your own equivalents. The RSF library is written in C, and all facilities offered by it are available directly to the C API via inclusion of header files and linking with the library. Other APIs only have access to a limited set of functions from the library. The ultimate guide to what the libraries provide is the file <tt>RSFSRC/filt/lib/SConstruct</tt>, which contains the instructions for building the RSF library in C and the interfaces to it for the various APIs.
=C API=
==Macros==
The following useful macros are accessible through the C and C++ APIs:
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|Functions
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_ABS(a) || (a) >= 0 ? (a) : (-(a)) || Absolute value
|-
| SF_MAX(a,b) || (a) < (b) ? (b) : (a) || Maximum of two values
|-
| SF_MIN(a,b) || (a) < (b) ? (a) : (b) || Minimum of two values
|-
| SF_SIG(a) || (a) >= 0 ? 1 : -1 || Sign function
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|General constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_EOL || '\014' || End-of-line ASCII character
|-
| SF_EOT || '\004' || End-of-transmission ASCII character
|-
| SF_EPS || FLT_EPSILON || The smallest X of type float such that 1.0 + X != 1.0. From <tt>float.h</tt>
|-
| SF_HUGE || FLT_MAX || The largest finite representable value of type float. From <tt>float.h</tt>
|-
| SF_MAX_DIM || 9 || Maximum number of dimensions in a RSF file
|-
| SF_PI || 3.141592653589793 || The number pi
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|SEG-Y-related constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_SEGY_FORMAT || 24 || Byte position in SEG-Y binary reel header, where info on encoding of data samples is kept ([[Guide_to_madagascar_programs#SEG-Y_specific_parameters|format parameter in sfsegyread]])
|-
| SF_SEGY_NS || 20 || Byte position in SEG-Y binary reel header, where info on nr of samples in one trace is kept ([[Guide_to_madagascar_programs#Common_parameters|ns parameter in sfsegyread]])
|-
| SF_SEGY_DT || 16 || Byte position in SEG-Y binary reel header, where info on time sampling is kept
|-
| SF_EBCBYTES || 3200 || Bytes in the SEG-Y EBCDIC reel header
|-
| SF_BNYBYTES || 400 || Bytes in the SEG-Y binary reel header
|-
| SF_HDRBYTES || 240 || Bytes in each individual SEG-Y trace header
|-
| SF_NKEYS || 71 || Number of mandated header fields
|-
| SF_BHKEYS || 27 || Number of mandated binary fields
|}
These macros were found with: <bash>grep '# define SF_' $RSFROOT/include/rsf.h</bash>

==Data types==
See the [http://m8r.info/RSF/book/rsf/manual/manual_html/node8.html Data Types section of the Programming Reference Manual]

==Functions==
See the [http://www.reproducibility.org/RSF/book/rsf/manual/manual_html/ Programming Reference Manual].

==Function wrappers==
These programs make the respective function callable from the command line, so that it can be used directly with files/other programs through "metaprograms" (shell/Python scripts). This allows the user to get the best of all worlds -- fast development in Python, all of Madagascar's visualization tools for debugging, and the speed of code written in C. This allows fast prototyping, followed by writing a production version in C calling the functions used.
{| class="wikitable" align="center" cellspacing="0" border="1"
!Library function || Program
|-
| sf_filedims || [http://reproducibility.org/RSF/sffiledims.html filedims]
|-
| sf_leftsize || [http://reproducibility.org/RSF/sfleftsize.html leftsize]
|-
| sf_quantile || [http://reproducibility.org/RSF/sfquantile.html quantile]
|}

=C++ API=
==Macros==
Same as for the C API.

=Fortran 77 API=
=Fortran 90 API=
The interface is accessed by including a <tt>use rsf</tt> statement in your program. The source code for the <tt>rsf</tt> module can be viewed [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/api/f90/rsf.f90?view=markup in the repository]. A ('''G''') means that the entity was featured in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to API]].

==Constants==
For use with <tt>gettype</tt> and <tt>settype</tt>:
* <tt>sf_char</tt>=1
* <tt>sf_complex</tt>=4
* <tt>sf_float</tt>=3 ('''G''')
* <tt>sf_int</tt>=2
* <tt>sf_short</tt>=5
* <tt>sf_uchar</tt>=0

For use with <tt>sf_seek</tt>:
* <tt>sf_seek_set</tt>=0
* <tt>sf_seek_cur</tt>=1
* <tt>sf_seek_end</tt>=2

==Data types==
All procedures in Madagascar's F90 API act upon or take as input one of the following data types:
* <tt>axa</tt>: Holds some info about a hypercube axis (integer::n; real::o,d)
* <tt>file</tt>: Simply an interface to the <tt>sf_file</tt> type described in the C library.

==Functions==
Data types are indicated in ''italics'' and intent in '''''bold italics'''''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''Result''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>axisname</tt> || ''integer'' '''''in''''' <tt>i</tt>, optional ''character'' '''''in''''' <tt>mystring</tt> || ''character'' <tt>mystringi</tt> || Given a string <tt>mystring</tt> and a positive number <tt>i</tt>, this function will return the concatenation of the string and the number converted to string (<tt>mystringi</tt>). In practice, <tt>mystring</tt> will probably be "n", "o", "d", "label" or "unit", in preparation for writing to a header file. Default value for <tt>mystring</tt> is "n". || Verbose string operations in F90 || N
|-
| <tt>dimension</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''out''''' <tt>dims</tt> || ''integer'' <tt>n</tt> || Returns number of dimensions of already-open file handle <tt>tag</tt> in <tt>n</tt>, and the dimension values in <tt>dims</tt> || <tt>sf_filedims</tt> || N
|-
| <tt>filesize</tt> || ''file'' '''''in''''' <tt>tag</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || ''integer'' nr_elements || Computes number of <tt>n</tt>-dimensional subcubes in file hypercube. When <tt>n</tt> is absent, default is zero and the number of elements in file. || <tt>sf_filesize</tt>, <tt>sf_leftsize</tt>. || Y
|-
| <tt>gettype</tt> || ''file'' '''''in''''' <tt>tag</tt> || ''integer'' <tt>type</tt> || Reads the binary data type from the already-open file handle <tt>tag</tt>. The <tt>type</tt> constant should be then compared in the user-written code with one of the six type constants provided by the F90 interface || <tt>sf_gettype</tt> || Y
|-
| <tt>rsf_input</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for reading and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="in", which corresponds to the standard input stream || <tt>sf_input</tt> || Y
|-
| <tt>rsf_output</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for writing and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="out", which corresponds to the standard output stream || <tt>sf_input</tt> || Y
|}

==Subroutines==
Because subroutine names are preceded by a <tt>call</tt> statement, it is easy to find occurrences of them being used by typing: <bash>grep "call subroutine_name" {filt,user}/*/*.f90 user/*/*/*.f90</bash> in RSFSRC.

Below, data types are indicated in ''italics'' and intent in '''''bold italics'''''. The type multi means that multiple data types can be used (subroutine is overloaded). In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>from_either</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || This subroutine looks for the real or integer variable <tt>name</tt> first in the history file, then in the parameter table. If it it is not found and <tt>default</tt> is present, it assigns it to <tt>value</tt>, otherwise it terminates the program. || <tt>sf_histint</tt>, <tt>sf_getint</tt> || N
|-
| <tt>from_par</tt> || optional ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || If already-opened file handle <tt>tag</tt> is supplied, then it reads into <tt>value</tt> a parameter designated by <tt>name</tt> from a history file. Else, it reads it from the parameter table. If the parameter is not found and a <tt>default</tt> is present, then that is used, else ends with failure. It can read from both history files and parameter tables the following types: integer, integer array, real. Strings can be read only from the history file, and not from the parameter table. Real arrays, logicals and logical arrays can be read only from the parameter table. || <tt>sf_histint</tt>, <tt>sf_getint</tt>, <tt>sf_histints</tt>, <tt>sf_getints</tt>, <tt>sf_histfloat</tt>, <tt>sf_getfloat</tt>, <tt>sf_histstring</tt>, <tt>sf_getfloats</tt>, <tt>sf_getbool</tt>, <tt>sf_getbools</tt> || Y
|-
| <tt>iaxa</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''axa'' '''''out''''' <tt>axisname</tt>, ''integer'' '''''in''''' <tt>axisnr</tt> || Read axis with number <tt>axisnr</tt> as axis <tt>axisname</tt> from the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>oaxa</tt> || ''file'' '''''in''''' <tt>tag,</tt> ''axa'' '''''in''''' <tt>axisname,</tt> ''integer'' '''''in''''' <tt>axisnr</tt> || Write axis <tt>axisname</tt> (i.e. its n, o, d) as axis with number <tt>axisnr</tt> to the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>raxa</tt> || ''axa'' '''''in''''' <tt>axisname</tt> || unformatted write to I/O unit nr. 0 (usually stdout, but system-dependent) of the contents of the <tt>axisname</tt> structure (n, o, d) || F90 write statement || N
|-
| <tt>rsf_read</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''out''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, the real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be read into it from an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, reads enough to fill the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D. || <tt>sf_floatread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''in''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be written to an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, writes to file the entire contents of the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|-
| <tt>settype</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''in''''' <tt>file_type</tt> || Write a type for the binary data to the already-open file header indicated by <tt>tag</tt>. Data type constants are also provided by the F90 API. || <tt>sf_settype</tt> || N
|-
| <tt>to_par</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''in''''' <tt>value</tt> || Writes <tt>name=value</tt> to already-opened file specified by <tt>tag</tt>. Value can be integer, integer array, real or character. || <tt>sf_putint</tt>, <tt>sf_putints</tt>, <tt>sf_putfloat</tt>, <tt>sf_putstring</tt> || N
|}

==Functions from the C library==
Functions from the C library for which an interface has been defined at the end of <tt>RSFSRC/api/f90/fortran.c</tt> can be called directly from Madagascar F90 programs. The programmer must know, however, that '''an argument type mismatch will result in a silent failure, with no informative errors.''' There may be other sources of problems as well. Caution therefore must be advised when calling these functions. The reason for these issues is that [http://people.scs.fsu.edu/~burkardt/f_src/mixed/mixed.html if a FORTRAN90 routine needs to pass a scalar parameter to a C routine, there is no standard way to ensure that a value is passed rather than an address]. The success rate of calling C from Fortran [http://w3.pppl.gov/~dmccune/papers-reports/linux_f90.txt is compiler-dependent] and [http://www.cs.sandia.gov/Zoltan/ug_html/ug_fortran.html special types may have to be defined for portability]. If you do have to call a C function from F90, follow the examples of the functions below. Use the C library reference to find argument and output types. A C-to-F90 data type dictionary follows:
{| class="wikitable" align="center" cellspacing="0" border="1"
! style="background:#ffdead;" | C ||! style="background:#ffdead;" | F90
|-
| RSFFILE || type(file)
|-
| INT || integer
|-
| OFFSETT || integer(kind=OFFKIND)
|}
===Void-output functions callable as subroutines===
These can be treated as subroutines, and accessed with a <tt>call</tt> statement. Follow
* <tt>sf_error</tt> ('''G''')
* <tt>sf_init</tt> ('''G''') ('''''Can it also be called in subroutines if we want to isolate I/O operations there?''''')
* <tt>sf_seek</tt>

===Non-void-output functions===
It is a good idea to declare in your program the function output type and use the keyword <tt>external</tt>, i.e.:
<pre>real, external :: sf_dosomething</pre>
Alternately, you may define a F90 <tt>interface</tt> block for the procedure(s).

Several examples can be found in <tt>RSFSRC/filt/lib/rsf.f90</tt>, but they are not enumerated here because F90 wrappers exist for them and they should be used instead of the direct calls to the C library functions.

=Matlab API=
Data types are indicated in ''italics''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means: "Demo-ed in the [[Guide_to_madagascar_API#MATLAB_interface|Guide to the Matlab API]]?"

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>rsf_create</tt> || Arg 1: ''string (row vector)'' <tt>new_file_name</tt>; Arg 2: ''string (row vector)'' <tt>old_file_name</tt>, or ''double (column vector)'' '''in''' <tt>new_file_cube_dims</tt> || Writes to disk RSF header of native_float hypercube of desired dimensions. Takes as input the name of the new file and either the name of another file with a cube of the same size, or a column with cube dimensions || <tt>sf_fileflush</tt>, or <tt>sf_putint</tt> and <tt>sf_setformat</tt> || Y
|-
| <tt>rsf_dim</tt> || Arg1: ''string (row vector)'' <tt>filename</tt> || Returns a 9-element vector [n1, n2, ... n9] with the dimensions of the hypercube as described in the RSF header '''filename'''. Missing dimensions are given the value 1 || <tt>sf_filedims</tt> || Y
|-
| <tt>rsf_par</tt> || Arg 1: ''string (row vector)'' <tt>filename</tt>; Arg 2: ''string (row vector)'' <tt>par_name</tt>; Arg 3: ''string (row vector)'' <tt>par_type</tt>: i[nt], l[ogical], f[loat]; Arg 4: ''double (scalar)'' <tt>default_val</tt> || Returns a scalar parameter read from a RSF header || <tt>sf_histint</tt>, <tt>sf_histbool</tt>, <tt>sf_histfloat</tt> || N
|-
| <tt>rsf_read</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Reads <tt>data_array</tt> from <tt>filename</tt>. Input data should be of SF_FLOAT, SF_INT or SF_COMPLEX type. The <tt>same</tt> parameter is a way to indicate if the data is read from the same file as before or from a newly opened file. If <tt>same</tt> is not given, the data will be read from the beginning of the file. || <tt>sf_floatread</tt>, <tt>sf_intread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Writes <tt>data_array</tt> to <tt>filename</tt>. Data to be written can be integer, float, double or complex. It will get cast to RSF's native_float or native_complex encoding. || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|}

=Octave API=

=Java API=

''There are two APIs available for Java. New programs should be written to use the SWIG API. The Mines JTK API is provided here only for reference for those who may still be using it.''

== SWIG API ==
The SWIG API includes three classes. The methods that each class exposes are as follows:

=== RSF ===
<java>
public RSF(String[] args); // Constructor, pass the command line arguments
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

=== Input ===
<java>
public Input(String name); // Constructor, pass a filename. "in" defaults to stdin
public int getN(int index); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public float getDelta(int index); // Gets the delta for that index. Returns 0.0 if not found.
public float getOrigin(int index); // Gets the origin for that file. Returns 0.0 if not found.
public String getLabel(int index); // Gets the label name for the index. Returns "" if not found.
public String getUnit(int index); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void read(float[] array); // Read data from the open RSF file into the given array. Reads the length of the array only.
public void read(float[][] array); // The following methods all read data from the RSF file in the given shape of the array.
public void read(float[][][] array);
public void read(float[][][][] array);
public void read(float[][][][][] array);
public void read(float[][][][][][] array);
public void read(float[][][][][][][] array);
public void read(float[][][][][][][][] array);
public void read(float[][][][][][][][][] array);
</java>

=== Output ===
<java>
public Output(String name); // Constructor, pass a filename. "out" points to standard out.
public void setN(int index, int n); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public void setDelta(int index, float delta); // Gets the delta for that index. Returns 0.0 if not found.
public void setOrigin(int index, float origin); // Gets the origin for that file. Returns 0.0 if not found.
public void setLabel(int index, String label); // Gets the label name for the index. Returns "" if not found.
public void setUnit(int index, String unit); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void write(float[] array); // Writes data to the RSF file from the given array. Writes the shape of the array only.
public void write(float[][] array); // The following methods all write data using the given shape of the array.
public void write(float[][][] array);
public void write(float[][][][] array);
public void write(float[][][][][] array);
public void write(float[][][][][][] array);
public void write(float[][][][][][][] array);
public void write(float[][][][][][][][] array);
public void write(float[][][][][][][][][] array);
</java>

Additional notes:

Java does not support complex numbers by default. To use complex numbers, you must convert complex valued RSF files to floating point numbers using sfdd .

== MINES JTK API ==
''' THIS API IS DEPRECATED. PLEASE DEVELOP YOUR PROGRAMS TO BE COMPATIBLE WITH THE SWIG API.'''

The following methods are exposed directly at this time:

==Par Class==

<java>
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

==Header Class==

<java>
public void setN(int dim, int n); // Used to set the number of elements in a dimension. For dimension 1, use an index value of 1.
public int getN(int dim);
public void setDelta(int dim, float delta); // Used to set the delta for a dimension. For dimension 1, use an index value of 1, not 0.
public float getDelta(int dim);
public void setOrigin(int dim, float origin); // Used to set the origin for a dimension.
public float getOrigin(int dim);
public void setLabel(int dim, String label); // Sets the label for a dimension.
public String getLabel(int dim);
public void setUnit(int dim, String unit); // Sets the unit for a dimension.
public String getUnit(int dim);
public void setFormat(String format); // Sets the output format information, has no effect on how Java treats the data.
public String getFormat();
public void setPath(String path); /* Sets the location of the binary file that corresponds to this header file.
Not used for writing information to an RSF file. */
public String getPath();
public void setName(String name); /* Change the file name that this header corresponds to. When writing this info to an RSF file,
the API automatically will determine the binary file that goes along with this filename. */
public String getName();
public String toString(); // Can be used to print out information about the header file.
</java>

==Writer Class==

When writing out RSF files, the header file is output in the same directory as the java program was executed. The binary file is placed according to the DATAPATH environment variable. <tt>saveName</tt> is the filename that you want to save your header to. Writing to standard out is not supported. All files must be saved via a name.

<java>
public static void writeRSF(RSFHeader header, float[] data, String saveName); // Writes a 1D array to an RSF Header and binary file
public static void writeRSF(RSFHeader header, float[][] data, String saveName); // Writes a 2D array to an RSF header and binary file.
public static void writeRSF(RSFHeader header, float[][][] data, String saveName); // Writes a 3D array to an RSF header and binary file.
</java>

==Reader Class==

<java>
public static Header readHeader(String headerFileName); // Used to parse the RSF Header file for information.
public static float[] readBinary(RSFHeader header); // Reads the RSF binary data file into a single array.
public static float[][] readBinary2D(RSFHeader header); // Reads the RSF binary data file into a 2D array.
public static float[][][] readBinary3D(RSFHeader header); // Reads the RSF binary data file into a 3D array.
</java>

=Python API=

To use the python api, you need to import the rsf package via: <tt>import rsf.api</tt> .

'''NOTE: Madagascar now has automatic documentation, currently with Epydoc, and more to come. The information in the table below will be merged into it.'''

The rsf package has the following members:

{| border="1"
|+ Overview of the Python RSF API
! Class !! Use !! Constructor !! Example !! Available Methods
|-
|File
|-
|Filter
|-
|Movie
|-
|Input || Provides a basic way to read rsf files. || file = rsf.Input(name) || input = rsf.Input(''name''); n1 = input.int('n1') || read(data), data is a numpy array to be read into.
|-
| || || || || close()
|-
| || || || || float(key, default=None), key is a string to be extracted, e.g. 'n1'.
|-
| || || || || int(key, default=None), key is a string to be extracted.
|-
| || || || || ints(key, num, default=None), key is a string, num is the number of ints.
|-
| || || || || put(key, val), key is a string to set the value for, val is a numerical value (int or float).
|-
| || || || || ... and more, type help(rsf.Input) on a python interactive session for more information.
|-
|Output || Provides a way to output numpy arrays to rsf files. || file = rsf.Output(name) || output=rsf.Output(name); output.write(data)
|-
|OverUnder
|-
|Overlay
|-
|Par || Provides a method for accessing rsf parameters passed from the command line. || par = rsf.Par() || par = rsf.Par(); velname = par.string('vel')
|-
|SideBySide
|-
|Temp
|-
|Vplot || View vplot graphics files from within python. || plot = rsf.Vplot(name) || plot = rsf.Vplot(name); plot.show()
|-
|Vppen
|}

=Calling standalone madagascar programs from Python=
On systems with recent versions of Python (at least 2.4), and with Numpy and Swig installed, use [http://www.reproducibility.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html the m8r module.

On old systems where dependencies cannot be easily installed (i.e. industrial clusters), the <tt>sf</tt> module (i.e. <tt>import rsf.user.sf as sf</tt>).

=SCons custom methods=
==Custom builders==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''File implemented in''' || '''Function''' || '''What it does'''
|-
| <tt>RSF_Include</tt> || RSFSRC/framework/bldutil.py || Header ||
|-
| <tt>RSF_Place</tt> || RSFSRC/framework/bldutil.py || Place ||
|-
| <tt>RSF_Pycompile</tt> || RSFSRC/framework/bldutil.py ||Pycompile ||
|-
| <tt>RSF_Docmerge</tt> || RSFSRC/framework/bldutil.py || Docmerge ||
|}

Other entities can be found in RSFSRC/framework/rsf/proj.py and tex.py

Library Reference

2011-07-24T18:39:04Z

Nick: /* Python API */

[[Image:Fotolia_2848987_XS.jpg|right|]]
If you are programming with Madagascar, please use the utilities described below instead of creating your own equivalents. The RSF library is written in C, and all facilities offered by it are available directly to the C API via inclusion of header files and linking with the library. Other APIs only have access to a limited set of functions from the library. The ultimate guide to what the libraries provide is the file <tt>RSFSRC/filt/lib/SConstruct</tt>, which contains the instructions for building the RSF library in C and the interfaces to it for the various APIs.
=C API=
==Macros==
The following useful macros are accessible through the C and C++ APIs:
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|Functions
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_ABS(a) || (a) >= 0 ? (a) : (-(a)) || Absolute value
|-
| SF_MAX(a,b) || (a) < (b) ? (b) : (a) || Maximum of two values
|-
| SF_MIN(a,b) || (a) < (b) ? (a) : (b) || Minimum of two values
|-
| SF_SIG(a) || (a) >= 0 ? 1 : -1 || Sign function
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|General constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_EOL || '\014' || End-of-line ASCII character
|-
| SF_EOT || '\004' || End-of-transmission ASCII character
|-
| SF_EPS || FLT_EPSILON || The smallest X of type float such that 1.0 + X != 1.0. From <tt>float.h</tt>
|-
| SF_HUGE || FLT_MAX || The largest finite representable value of type float. From <tt>float.h</tt>
|-
| SF_MAX_DIM || 9 || Maximum number of dimensions in a RSF file
|-
| SF_PI || 3.141592653589793 || The number pi
|}
{|class="wikitable"
|-
! colspan="3" style="background:#ffdead;"|SEG-Y-related constants
|-
| '''Name''' || '''Value''' || '''Meaning'''
|-
| SF_SEGY_FORMAT || 24 || Byte position in SEG-Y binary reel header, where info on encoding of data samples is kept ([[Guide_to_madagascar_programs#SEG-Y_specific_parameters|format parameter in sfsegyread]])
|-
| SF_SEGY_NS || 20 || Byte position in SEG-Y binary reel header, where info on nr of samples in one trace is kept ([[Guide_to_madagascar_programs#Common_parameters|ns parameter in sfsegyread]])
|-
| SF_SEGY_DT || 16 || Byte position in SEG-Y binary reel header, where info on time sampling is kept
|-
| SF_EBCBYTES || 3200 || Bytes in the SEG-Y EBCDIC reel header
|-
| SF_BNYBYTES || 400 || Bytes in the SEG-Y binary reel header
|-
| SF_HDRBYTES || 240 || Bytes in each individual SEG-Y trace header
|-
| SF_NKEYS || 71 || Number of mandated header fields
|-
| SF_BHKEYS || 27 || Number of mandated binary fields
|}
These macros were found with: <bash>grep '# define SF_' $RSFROOT/include/rsf.h</bash>

==Data types==
See the [http://m8r.info/RSF/book/rsf/manual/manual_html/node8.html Data Types section of the Programming Reference Manual]

==Functions==
See the [http://www.reproducibility.org/RSF/book/rsf/manual/manual_html/ Programming Reference Manual].

==Function wrappers==
These programs make the respective function callable from the command line, so that it can be used directly with files/other programs through "metaprograms" (shell/Python scripts). This allows the user to get the best of all worlds -- fast development in Python, all of Madagascar's visualization tools for debugging, and the speed of code written in C. This allows fast prototyping, followed by writing a production version in C calling the functions used.
{| class="wikitable" align="center" cellspacing="0" border="1"
!Library function || Program
|-
| sf_filedims || [http://reproducibility.org/RSF/sffiledims.html filedims]
|-
| sf_leftsize || [http://reproducibility.org/RSF/sfleftsize.html leftsize]
|-
| sf_quantile || [http://reproducibility.org/RSF/sfquantile.html quantile]
|}

=C++ API=
==Macros==
Same as for the C API.

=Fortran 77 API=
=Fortran 90 API=
The interface is accessed by including a <tt>use rsf</tt> statement in your program. The source code for the <tt>rsf</tt> module can be viewed [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/api/f90/rsf.f90?view=markup in the repository]. A ('''G''') means that the entity was featured in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to API]].

==Constants==
For use with <tt>gettype</tt> and <tt>settype</tt>:
* <tt>sf_char</tt>=1
* <tt>sf_complex</tt>=4
* <tt>sf_float</tt>=3 ('''G''')
* <tt>sf_int</tt>=2
* <tt>sf_short</tt>=5
* <tt>sf_uchar</tt>=0

For use with <tt>sf_seek</tt>:
* <tt>sf_seek_set</tt>=0
* <tt>sf_seek_cur</tt>=1
* <tt>sf_seek_end</tt>=2

==Data types==
All procedures in Madagascar's F90 API act upon or take as input one of the following data types:
* <tt>axa</tt>: Holds some info about a hypercube axis (integer::n; real::o,d)
* <tt>file</tt>: Simply an interface to the <tt>sf_file</tt> type described in the C library.

==Functions==
Data types are indicated in ''italics'' and intent in '''''bold italics'''''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''Result''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>axisname</tt> || ''integer'' '''''in''''' <tt>i</tt>, optional ''character'' '''''in''''' <tt>mystring</tt> || ''character'' <tt>mystringi</tt> || Given a string <tt>mystring</tt> and a positive number <tt>i</tt>, this function will return the concatenation of the string and the number converted to string (<tt>mystringi</tt>). In practice, <tt>mystring</tt> will probably be "n", "o", "d", "label" or "unit", in preparation for writing to a header file. Default value for <tt>mystring</tt> is "n". || Verbose string operations in F90 || N
|-
| <tt>dimension</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''out''''' <tt>dims</tt> || ''integer'' <tt>n</tt> || Returns number of dimensions of already-open file handle <tt>tag</tt> in <tt>n</tt>, and the dimension values in <tt>dims</tt> || <tt>sf_filedims</tt> || N
|-
| <tt>filesize</tt> || ''file'' '''''in''''' <tt>tag</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || ''integer'' nr_elements || Computes number of <tt>n</tt>-dimensional subcubes in file hypercube. When <tt>n</tt> is absent, default is zero and the number of elements in file. || <tt>sf_filesize</tt>, <tt>sf_leftsize</tt>. || Y
|-
| <tt>gettype</tt> || ''file'' '''''in''''' <tt>tag</tt> || ''integer'' <tt>type</tt> || Reads the binary data type from the already-open file handle <tt>tag</tt>. The <tt>type</tt> constant should be then compared in the user-written code with one of the six type constants provided by the F90 interface || <tt>sf_gettype</tt> || Y
|-
| <tt>rsf_input</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for reading and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="in", which corresponds to the standard input stream || <tt>sf_input</tt> || Y
|-
| <tt>rsf_output</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for writing and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="out", which corresponds to the standard output stream || <tt>sf_input</tt> || Y
|}

==Subroutines==
Because subroutine names are preceded by a <tt>call</tt> statement, it is easy to find occurrences of them being used by typing: <bash>grep "call subroutine_name" {filt,user}/*/*.f90 user/*/*/*.f90</bash> in RSFSRC.

Below, data types are indicated in ''italics'' and intent in '''''bold italics'''''. The type multi means that multiple data types can be used (subroutine is overloaded). In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>from_either</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || This subroutine looks for the real or integer variable <tt>name</tt> first in the history file, then in the parameter table. If it it is not found and <tt>default</tt> is present, it assigns it to <tt>value</tt>, otherwise it terminates the program. || <tt>sf_histint</tt>, <tt>sf_getint</tt> || N
|-
| <tt>from_par</tt> || optional ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || If already-opened file handle <tt>tag</tt> is supplied, then it reads into <tt>value</tt> a parameter designated by <tt>name</tt> from a history file. Else, it reads it from the parameter table. If the parameter is not found and a <tt>default</tt> is present, then that is used, else ends with failure. It can read from both history files and parameter tables the following types: integer, integer array, real. Strings can be read only from the history file, and not from the parameter table. Real arrays, logicals and logical arrays can be read only from the parameter table. || <tt>sf_histint</tt>, <tt>sf_getint</tt>, <tt>sf_histints</tt>, <tt>sf_getints</tt>, <tt>sf_histfloat</tt>, <tt>sf_getfloat</tt>, <tt>sf_histstring</tt>, <tt>sf_getfloats</tt>, <tt>sf_getbool</tt>, <tt>sf_getbools</tt> || Y
|-
| <tt>iaxa</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''axa'' '''''out''''' <tt>axisname</tt>, ''integer'' '''''in''''' <tt>axisnr</tt> || Read axis with number <tt>axisnr</tt> as axis <tt>axisname</tt> from the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>oaxa</tt> || ''file'' '''''in''''' <tt>tag,</tt> ''axa'' '''''in''''' <tt>axisname,</tt> ''integer'' '''''in''''' <tt>axisnr</tt> || Write axis <tt>axisname</tt> (i.e. its n, o, d) as axis with number <tt>axisnr</tt> to the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>raxa</tt> || ''axa'' '''''in''''' <tt>axisname</tt> || unformatted write to I/O unit nr. 0 (usually stdout, but system-dependent) of the contents of the <tt>axisname</tt> structure (n, o, d) || F90 write statement || N
|-
| <tt>rsf_read</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''out''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, the real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be read into it from an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, reads enough to fill the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D. || <tt>sf_floatread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''in''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be written to an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, writes to file the entire contents of the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|-
| <tt>settype</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''in''''' <tt>file_type</tt> || Write a type for the binary data to the already-open file header indicated by <tt>tag</tt>. Data type constants are also provided by the F90 API. || <tt>sf_settype</tt> || N
|-
| <tt>to_par</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''in''''' <tt>value</tt> || Writes <tt>name=value</tt> to already-opened file specified by <tt>tag</tt>. Value can be integer, integer array, real or character. || <tt>sf_putint</tt>, <tt>sf_putints</tt>, <tt>sf_putfloat</tt>, <tt>sf_putstring</tt> || N
|}

==Functions from the C library==
Functions from the C library for which an interface has been defined at the end of <tt>RSFSRC/api/f90/fortran.c</tt> can be called directly from Madagascar F90 programs. The programmer must know, however, that '''an argument type mismatch will result in a silent failure, with no informative errors.''' There may be other sources of problems as well. Caution therefore must be advised when calling these functions. The reason for these issues is that [http://people.scs.fsu.edu/~burkardt/f_src/mixed/mixed.html if a FORTRAN90 routine needs to pass a scalar parameter to a C routine, there is no standard way to ensure that a value is passed rather than an address]. The success rate of calling C from Fortran [http://w3.pppl.gov/~dmccune/papers-reports/linux_f90.txt is compiler-dependent] and [http://www.cs.sandia.gov/Zoltan/ug_html/ug_fortran.html special types may have to be defined for portability]. If you do have to call a C function from F90, follow the examples of the functions below. Use the C library reference to find argument and output types. A C-to-F90 data type dictionary follows:
{| class="wikitable" align="center" cellspacing="0" border="1"
! style="background:#ffdead;" | C ||! style="background:#ffdead;" | F90
|-
| RSFFILE || type(file)
|-
| INT || integer
|-
| OFFSETT || integer(kind=OFFKIND)
|}
===Void-output functions callable as subroutines===
These can be treated as subroutines, and accessed with a <tt>call</tt> statement. Follow
* <tt>sf_error</tt> ('''G''')
* <tt>sf_init</tt> ('''G''') ('''''Can it also be called in subroutines if we want to isolate I/O operations there?''''')
* <tt>sf_seek</tt>

===Non-void-output functions===
It is a good idea to declare in your program the function output type and use the keyword <tt>external</tt>, i.e.:
<pre>real, external :: sf_dosomething</pre>
Alternately, you may define a F90 <tt>interface</tt> block for the procedure(s).

Several examples can be found in <tt>RSFSRC/filt/lib/rsf.f90</tt>, but they are not enumerated here because F90 wrappers exist for them and they should be used instead of the direct calls to the C library functions.

=Matlab API=
Data types are indicated in ''italics''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means: "Demo-ed in the [[Guide_to_madagascar_API#MATLAB_interface|Guide to the Matlab API]]?"

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?'''
|-
| <tt>rsf_create</tt> || Arg 1: ''string (row vector)'' <tt>new_file_name</tt>; Arg 2: ''string (row vector)'' <tt>old_file_name</tt>, or ''double (column vector)'' '''in''' <tt>new_file_cube_dims</tt> || Writes to disk RSF header of native_float hypercube of desired dimensions. Takes as input the name of the new file and either the name of another file with a cube of the same size, or a column with cube dimensions || <tt>sf_fileflush</tt>, or <tt>sf_putint</tt> and <tt>sf_setformat</tt> || Y
|-
| <tt>rsf_dim</tt> || Arg1: ''string (row vector)'' <tt>filename</tt> || Returns a 9-element vector [n1, n2, ... n9] with the dimensions of the hypercube as described in the RSF header '''filename'''. Missing dimensions are given the value 1 || <tt>sf_filedims</tt> || Y
|-
| <tt>rsf_par</tt> || Arg 1: ''string (row vector)'' <tt>filename</tt>; Arg 2: ''string (row vector)'' <tt>par_name</tt>; Arg 3: ''string (row vector)'' <tt>par_type</tt>: i[nt], l[ogical], f[loat]; Arg 4: ''double (scalar)'' <tt>default_val</tt> || Returns a scalar parameter read from a RSF header || <tt>sf_histint</tt>, <tt>sf_histbool</tt>, <tt>sf_histfloat</tt> || N
|-
| <tt>rsf_read</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Reads <tt>data_array</tt> from <tt>filename</tt>. Input data should be of SF_FLOAT, SF_INT or SF_COMPLEX type. The <tt>same</tt> parameter is a way to indicate if the data is read from the same file as before or from a newly opened file. If <tt>same</tt> is not given, the data will be read from the beginning of the file. || <tt>sf_floatread</tt>, <tt>sf_intread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || Arg 1: ''double'' <tt>data_array</tt>; Arg 2: ''string (row vector)'' <tt>filename</tt>; Arg 3 (optional): ''string (row vector)'' <tt>same</tt>. If Arg 3 is given, value should be "same" || Writes <tt>data_array</tt> to <tt>filename</tt>. Data to be written can be integer, float, double or complex. It will get cast to RSF's native_float or native_complex encoding. || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|}

=Octave API=

=Java API=

''There are two APIs available for Java. New programs should be written to use the SWIG API. The Mines JTK API is provided here only for reference for those who may still be using it.''

== SWIG API ==
The SWIG API includes three classes. The methods that each class exposes are as follows:

=== RSF ===
<java>
public RSF(String[] args); // Constructor, pass the command line arguments
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

=== Input ===
<java>
public Input(String name); // Constructor, pass a filename. "in" defaults to stdin
public int getN(int index); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public float getDelta(int index); // Gets the delta for that index. Returns 0.0 if not found.
public float getOrigin(int index); // Gets the origin for that file. Returns 0.0 if not found.
public String getLabel(int index); // Gets the label name for the index. Returns "" if not found.
public String getUnit(int index); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void read(float[] array); // Read data from the open RSF file into the given array. Reads the length of the array only.
public void read(float[][] array); // The following methods all read data from the RSF file in the given shape of the array.
public void read(float[][][] array);
public void read(float[][][][] array);
public void read(float[][][][][] array);
public void read(float[][][][][][] array);
public void read(float[][][][][][][] array);
public void read(float[][][][][][][][] array);
public void read(float[][][][][][][][][] array);
</java>

=== Output ===
<java>
public Output(String name); // Constructor, pass a filename. "out" points to standard out.
public void setN(int index, int n); // Gets the number of elements in the file for that index. Counting starts at 1. Returns 1 if not found.
public void setDelta(int index, float delta); // Gets the delta for that index. Returns 0.0 if not found.
public void setOrigin(int index, float origin); // Gets the origin for that file. Returns 0.0 if not found.
public void setLabel(int index, String label); // Gets the label name for the index. Returns "" if not found.
public void setUnit(int index, String unit); // Gets the unit for the index. Returns "" if not found.
public void close(); // Close the file.
public void write(float[] array); // Writes data to the RSF file from the given array. Writes the shape of the array only.
public void write(float[][] array); // The following methods all write data using the given shape of the array.
public void write(float[][][] array);
public void write(float[][][][] array);
public void write(float[][][][][] array);
public void write(float[][][][][][] array);
public void write(float[][][][][][][] array);
public void write(float[][][][][][][][] array);
public void write(float[][][][][][][][][] array);
</java>

Additional notes:

Java does not support complex numbers by default. To use complex numbers, you must convert complex valued RSF files to floating point numbers using sfdd .

== MINES JTK API ==
''' THIS API IS DEPRECATED. PLEASE DEVELOP YOUR PROGRAMS TO BE COMPATIBLE WITH THE SWIG API.'''

The following methods are exposed directly at this time:

==Par Class==

<java>
public float getFloat(String key, float default); // Gets the command line argument associated with this key.
public int getInt(String key, int default); // Gets an int from the command line associated with this key.
public boolean getBool(String key, boolean default); // Gets a boolean from the command line associated with this key.
public String getString(String key, String default); // Gets a string corresponding to this key.
</java>

==Header Class==

<java>
public void setN(int dim, int n); // Used to set the number of elements in a dimension. For dimension 1, use an index value of 1.
public int getN(int dim);
public void setDelta(int dim, float delta); // Used to set the delta for a dimension. For dimension 1, use an index value of 1, not 0.
public float getDelta(int dim);
public void setOrigin(int dim, float origin); // Used to set the origin for a dimension.
public float getOrigin(int dim);
public void setLabel(int dim, String label); // Sets the label for a dimension.
public String getLabel(int dim);
public void setUnit(int dim, String unit); // Sets the unit for a dimension.
public String getUnit(int dim);
public void setFormat(String format); // Sets the output format information, has no effect on how Java treats the data.
public String getFormat();
public void setPath(String path); /* Sets the location of the binary file that corresponds to this header file.
Not used for writing information to an RSF file. */
public String getPath();
public void setName(String name); /* Change the file name that this header corresponds to. When writing this info to an RSF file,
the API automatically will determine the binary file that goes along with this filename. */
public String getName();
public String toString(); // Can be used to print out information about the header file.
</java>

==Writer Class==

When writing out RSF files, the header file is output in the same directory as the java program was executed. The binary file is placed according to the DATAPATH environment variable. <tt>saveName</tt> is the filename that you want to save your header to. Writing to standard out is not supported. All files must be saved via a name.

<java>
public static void writeRSF(RSFHeader header, float[] data, String saveName); // Writes a 1D array to an RSF Header and binary file
public static void writeRSF(RSFHeader header, float[][] data, String saveName); // Writes a 2D array to an RSF header and binary file.
public static void writeRSF(RSFHeader header, float[][][] data, String saveName); // Writes a 3D array to an RSF header and binary file.
</java>

==Reader Class==

<java>
public static Header readHeader(String headerFileName); // Used to parse the RSF Header file for information.
public static float[] readBinary(RSFHeader header); // Reads the RSF binary data file into a single array.
public static float[][] readBinary2D(RSFHeader header); // Reads the RSF binary data file into a 2D array.
public static float[][][] readBinary3D(RSFHeader header); // Reads the RSF binary data file into a 3D array.
</java>

=Python API=

To use the python api, you need to import the rsf package via: <tt>import rsf.api</tt> .

'''NOTE: Madagascar now has automatic documentation, currently with Epydoc, and more to come. The information in the table below will be merged into it.'''

The rsf package has the following members:

{| border="1"
|+ Overview of the Python RSF API
! Class !! Use !! Constructor !! Example !! Available Methods
|-
|File
|-
|Filter
|-
|Movie
|-
|Input || Provides a basic way to read rsf files. || file = rsf.Input(name) || input = rsf.Input(''name''); n1 = input.int('n1') || read(data), data is a numpy array to be read into.
|-
| || || || || close()
|-
| || || || || float(key, default=None), key is a string to be extracted, e.g. 'n1'.
|-
| || || || || int(key, default=None), key is a string to be extracted.
|-
| || || || || ints(key, num, default=None), key is a string, num is the number of ints.
|-
| || || || || put(key, val), key is a string to set the value for, val is a numerical value (int or float).
|-
| || || || || ... and more, type help(rsf.Input) on a python interactive session for more information.
|-
|Output || Provides a way to output numpy arrays to rsf files. || file = rsf.Output(name) || output=rsf.Output(name); output.write(data)
|-
|OverUnder
|-
|Overlay
|-
|Par || Provides a method for accessing rsf parameters passed from the command line. || par = rsf.Par() || par = rsf.Par(); velname = par.string('vel')
|-
|SideBySide
|-
|Temp
|-
|Vplot || View vplot graphics files from within python. || plot = rsf.Vplot(name) || plot = rsf.Vplot(name); plot.show()
|-
|Vppen
|}

=SCons custom methods=
==Custom builders==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''File implemented in''' || '''Function''' || '''What it does'''
|-
| <tt>RSF_Include</tt> || RSFSRC/framework/bldutil.py || Header ||
|-
| <tt>RSF_Place</tt> || RSFSRC/framework/bldutil.py || Place ||
|-
| <tt>RSF_Pycompile</tt> || RSFSRC/framework/bldutil.py ||Pycompile ||
|-
| <tt>RSF_Docmerge</tt> || RSFSRC/framework/bldutil.py || Docmerge ||
|}

Other entities can be found in RSFSRC/framework/rsf/proj.py and tex.py

Advanced Installation

2011-07-24T15:57:47Z

Nick: /* Fedora, CentOS, Scientific Linux, openSUSE */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS, Scientific Linux, openSUSE==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2011-07-24T15:50:05Z

Nick: /* Fedora, CentOS */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS, Scientific Linux, openSUSE==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

''Note: In the future, we should distinguish the subset of runtime dependencies (necessary to run already-compiled binaries installed through a package manager)''

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2011-07-24T15:49:33Z

Nick: /* openSUSE 11.* */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

''Note: In the future, we should distinguish the subset of runtime dependencies (necessary to run already-compiled binaries installed through a package manager)''

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2011-07-24T15:48:24Z

Nick: /* Fedora, CentOS, Scientific Linux, openSUSE */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<bash>
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</bash>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<bash>
python setup.py install
</bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash>
python setup.py install --prefix=$RSFROOT
</bash>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<bash>
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</bash>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt>

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<bash>
octave -v | head -1
</bash>
If your version is lower than 2.9.6, type at a Unix command line:
<bash>
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</bash>
For later versions, use:
<bash>
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</bash>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<bash>
export MINESJTK=/home/user/edu_mines_jtk.jar
</bash>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<bash>
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</bash>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<bash>
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</bash>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
* 4 until 2012-02-29
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs
|
* 11.10 until end of April 2013
* 11.04 until end of October 2012
* 10.10 until end of April 2012
* 10.04 until end of October 2011
* 8.04 LTS Server until end of April 2013
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==

In '''Ubuntu 10.10 ''Maverick Meerkat''''', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev libx11-dev \
libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units libblas-dev \
libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In 9.04 version, the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>subversion</tt>.

==Fedora, CentOS==

Dependency package names, sorted by Linux distribution and m8r feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

''Note: In the future, we should distinguish the subset of runtime dependencies (necessary to run already-compiled binaries installed through a package manager)''

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given m8r version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python, scons (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python, scons
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Graphics and visualization'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| libXaw-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| xorg-x11-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==openSUSE 11.*==
The development version of m8r has dependencies beyond the packages installed by the default openSUSE 11.0 DVD install:
* To download the development version, you need <tt>subversion</tt>
* To compile the package, you need <tt>scons</tt> and <tt>gcc</tt>
* To install the C++ API, you need <tt>gcc-c++</tt>
* To install the F90 API, you need <tt>gcc-fortran</tt>
* To install the Octave API, you need <tt>octave</tt>
* To install <tt>sfbyte2jpg</tt> and <tt>sfjpg2byte</tt> you need <tt>libjpeg-devel</tt>
* To install the vplot graphics, you need <tt>xorg-x11-devel</tt>
* To install LaTeX for building papers and books, you need <tt>texlive-latex</tt>
* To install some graphics programs, you need <tt>cairo-devel</tt>, <tt>gd-devel</tt>, <tt>glew-devel</tt> and <tt>libtiff-devel</tt>

Packages can be installed by running as root <tt>zypper install <package name></tt>. The graphical front-end to Zypper integrated with YaST2 can of course be used as well (Geeko button... Applications... System... Configuration... Install Software)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt W. Burnett's guide (PowerPoint)]

==Mac OS X==
First of all, a [https://sourceforge.net/project/showfiles.php?group_id=162909 Mac OS X precompiled binary package] of the latest Madagascar stable release is available for download from SourceForge.

If you want to install a development version of Madagascar, the following might help.
# C compiler for Mac OS X. You can download the precompiled binary package of Xcode tools, including the gcc compiler, from [http://developer.apple.com/tools/xcode/ Apple]. Other sources are:
#* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
#* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.
# [http://subversion.tigris.org/ Subversion] client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use MacPorts or Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the [http://www.wikihow.com/Install-Subversion-on-Mac-OS-X Wikihow website] and [http://downloads.open.collab.net/binaries.html Collab]. You can use Subversion to [[Download#Current_development_version|download the development version]] of the <tt>Madagascar</tt> source code. Next, follow [[Installation|Installation instructions]] to install.
# [[SEGTeX]], a LaTeX package for geophysical publications. To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <tt>sudo port install texlive</tt> or <tt>sudo fink install texlive</tt>.

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<python>
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</python>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<bash>
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</bash>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<python>
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</python>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<bash>
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>
Or like this (csh):
<bash>
setenv PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</bash>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</python>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<python>
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</python>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<bash>
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</bash>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<bash>
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</bash>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].