Madagascar - User contributions [en]

Conferences

2024-11-26T15:41:48Z

Fomels: links

[[Image:Conferences.png|right|]]
In reverse chronological order.

==Schools, Workshops, and Working Workshops==
[[PuertoVallarta_2023|Madagascar Workshop at RAUGM, Puerto Vallarta 2023]]

[[Hefei_2020|Madagascar School on Open-Source Geophysics in Hefei 2020]]

[[HoustonWW2018|SEG Working Workshop - Python and Julia for Geophysics, Houston August 8-11, 2018]]

[[HoustonWW2017|SEG Working Workshop in Houston 2017]]

[[Shanghai_2017|Madagascar School of Reproducible Computational Geophysics Shanghai 2017]]

[[Houston_2017|Madagascar School at the University of Houston 2017]]

[[SEG_3D_Seismic_Processing_Working_Workshop_Houston_2016-_Land_3D|SEG Land 3D Seismic Processing Working Workshop Houston 2016]]

[[Zurich 2016|Madagascar School on Reproducible Computational Geophysics in Zürich 2016]]

[[Vienna_2016|Workshop - Open-source Software in Applied Geosciences Vienna 2016]]

[[Qingdao_2015|Madagascar School for Advanced Users in Qingdao 2015]]

[[SEG 3D Seismic Processing Working Workshop Houston 2015- Land 3D|SEG 3D Land Seismic Processing Working Workshop Houston 2015]]

[[Harbin_2015|School in Harbin 2015]]

[[Houston_2014|Second Madagascar Working Workshop Houston 2014]]

[[Petersburg_2014|Workshop at EAGE/St. Petersburg 2014]]

[[Melbourne_2013|Workshop at ASEG 2013]]

[[Austin_2013|First Madagascar Working Workshop Austin 2013]]

[[Austin_2012|Madagascar School and Workshop on Reproducible Computational Geophysics Austin 2012]]

[[Copenhagen_2012|Workshop - Open-source E&P Software - Six Years Later Copenhagen 2012]]

[[Beijing_2011|Madagascar School of Reproducible Computational Geophysics Beijing 2011]]

[[Houston_2011|Workshop - Open Software Tools for Reproducible Computational Geophysics Houston 2011]]

[[Houston_2010|Madagascar School of Reproducible Computational Geophysics and Hands-On School Houston 2010]]

[[Salvador_2009|Madagascar School on Reproducible Computational Geophysics Salvador 2009]]

[[Delft_2009|Madagascar School on Reproducible Computational Geophysics Delft 2009]]

[[2008_Implementation_Workshop|Towards full automation and better robustness Coding Sprint Golden 2008]]

[[RSF_Austin_School_2007|Using and Extending RSF/Madagascar School Austin 2007]].

[[RSF_School_and_Workshop%2C_Vancouver_2006|Reproducible Research in Computational Geophysics School and Workshop Vancouver 2006]].

==Conference presentations==

===Online 2021 (SPE)===

<tt>Madagascar</tt> was presented in the session on '''Open Source - Geomodelling and Reservoir Characterization''' at the [https://www.spe.org/events/en/2021/workshop/21av01/open-subsurface.html SPE Virtual Workshop: Open Subsurface] on May 19, 2021. See presentation [https://ahay.org/wikilocal/docs/Madagascar-SPE.pdf slides] and the [https://www.spe.org/events/en/2021/workshop/21av01/schedule-overview.html workshop program].

===Lausanne 2016 (PASC)===

Two presentations about <tt>Madagascar</tt> were presented in the mini-symposium on '''Open Source Software (OSS) and High-Performance Computing (HPC)''' at the [http://www.pasc16.org/ Platform for Advanced Scientific Computing] conference in Lausanne, Switzerland, on June 9, 2016. See presentation slides:
* [http://ahay.org/wikilocal/docs/FOMEL-PASC2016.pdf Data-Parallel Processing Using Madagascar Open-Source Software Package]
* [http://ahay.org/wikilocal/docs/POTTER-SHRAGGE-PASC2016.pdf Leveraging the Madagascar Framework for Reproducible Large-scale Cluster and Cloud Computing]

===San Francisco 2015 (AGU)===

<tt>Madagascar</tt> was presented in the session on '''Informatics and Intelligent Systems in Reproducible Geoscience Research''' at the [http://fallmeeting.agu.org/2015/ AGU Fall Meeting] in San Francisco, California, on December 17, 2015. See presentation [http://ahay.org/wikilocal/docs/Madagascar-AGU-2015.pdf slides] and the [https://agu.confex.com/agu/fm15/meetingapp.cgi/Session/10540 session program].

===Stanford 2015 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the mini-symposium on '''Advances in Software for Computational Geosciences''' at the [http://www.siam.org/meetings/gs15/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Stanford, California, on June 30, 2015. See presentation [http://ahay.org/wikilocal/docs/Fomel-SIAM-Geosciences-2015.pdf slides] and the [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=21097 mini-symposium program].

===New York 2013 (NYU Poly)===

<tt>Madagascar</tt> was presented at the workshop on [http://www.reproduciblescience.org/index.php/Workshop_on_Software_Infrastructure_for_Reproducibility_in_Science_--_May_30th-31st,_2013 Software Infrastructure for Reproducibility in Science] at the Polytechnic Institute of New York University in Brooklyn, New York, on May 30, 2013. See presentation [http://ahay.org/wikilocal/docs/Madagascar-NYC.pdf slides].

The workshop was supported by the [http://www.sloan.org/ Alfred P. Sloan Foundation]. Juliana Freire provides the complete [http://vgc.poly.edu/~juliana/ReproducibleScience/SoftwareInfrastructure/agenda.pdf workshop program].

===Providence 2012 (ICERM)===

<tt>Madagascar</tt> was presented at the [http://icerm.brown.edu/tw12-5-rcem Reproducibility in Computational and Experimental Mathematics] Workshop at the Institute for Computational and Experimental Research in Mathematics (ICERM) in Providence, Rhode Island, on December 13, 2012.

See presentation [http://ahay.org/wikilocal/docs/ICERM.pptx slides], the complete [http://icerm.brown.edu/tw12-5-rcem workshop program], and Victoria Stodden's [http://wiki.stodden.net/ICERM_Reproducibility_in_Computational_and_Experimental_Mathematics:_Readings_and_References wiki page].

===Austin 2012 (SciPy)===

The Python interface to <tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2012/ Scientific Computing with Python Conference] in Austin, Texas, on July 19, 2012. See the poster by clicking on the image below
. 

[[Image:SciPy2012Poster.png|link=http://www.ahay.org/wikilocal/docs/SciPy2012Poster.pdf]]

===Cary 2011 (Interface)===
<tt>Madagascar</tt> was presented in the special session on '''Reproducible Research''' at the [http://www.interfacesymposia.org/Interface2011/ 42nd Symposium on the Interface] (Statistical, Machine Learning, and Visualization Algorithms) in Cary, North Carolina, on June 1, 2011. See the [http://www.interfacesymposia.org/Interface2011/Program.pdf symposium program].

===Long Beach 2011 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the mini-symposium on '''Reproducible Science and Open-Source Software in the Geosciences''' at the [http://www.siam.org/meetings/gs11/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Long Beach, California, on March 23, 2011. See presentation [https://ahay.org/wikilocal/docs/longbeach2011.pdf slides] and the mini-symposium program: [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11822 Part 1] and [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11823 Part 2].

===Reno 2011 (SIAM CS&E)===

<tt>Madagascar</tt> was presented in the mini-symposium on '''Verifiable, Reproducible Research and Computational Science''' at the [http://www.siam.org/meetings/cse11/ SIAM Conference on Computational Science and Engineering] in Reno, Nevada, on March 4, 2011. See presentation [http://ahay.org/wikilocal/docs/reno2011.pdf slides].

Jarrod Millman provides a complete [http://jarrodmillman.com/events/siam2011.html session program].

===Austin 2010 (SciPy)===

<tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2010/ Python in Scientific Computing Conference] in Austin, Texas, on July 1, 2010. See the presentation [http://ahay.org/wikilocal/docs/scipy2010.pdf slides] and [http://conference.scipy.org/scipy2010/schedule.html complete program].

===Salt Lake City 2010 (NSF Archive Workshop)===

<tt>Madagascar</tt> was presented at the [http://users.emulab.net/trac/archive10/ NSF Workshop on Archiving Experiments to Raise Scientific Standards] in Salt Lake City on May 25, 2010. See the presentation [http://ahay.org/wikilocal/docs/slc.pdf slides] and [http://users.emulab.net/trac/archive10/wiki/WorkshopSchedule complete program].

===Düsseldorf 2008 (Berlin 6) ===

<tt>Madagascar</tt> was mentioned in the special session on '''Open Data and Reproducible Research''' at the [http://www.berlin6.org/ Berlin 6 Open Access Conference] in Düsseldorf, Germany, on November 12, 2008. See presentation [https://ahay.org/wikilocal/docs/Berlin-6.ppt slides].

Mark Liberman provides a complete [http://ldc.upenn.edu/myl/Berlin6Session5/Overview.html session program].

===Austin 2008 (Texas Python Unconference)===

''New Directions in Literate Programming with Madagascar'' was presented at the Second Annual Texas Python Unconference hosted by Enthought Corporation on the UT campus on October 4, 2008. See presentation [http://www.ig.utexas.edu/people/staff/tobis/MadLiter/madliter.html slides].

===Austin 2008 (Scientific Software Days)===

<tt>Madagascar</tt> was presented at the Second Annual Scientific Software Days at the University of Texas at Austin on May 15, 2008. See the presentation [http://ahay.org/wikilocal/docs/ssd2.pdf slides] and [http://www.tacc.utexas.edu/softwareday/ complete program].

===Rio de Janeiro 2007 (SBGf)===

<tt>Madagascar</tt> and reproducible scientific computing were presented at the 2007 [http://www.sbgf.org.br Congress of the Brazilian Geophysical Society] in Rio de Janeiro. See presentation [https://ahay.org/wikilocal/docs/2007_SBGf_ReproducibleScientificComputingUsingMadagascar.pdf slides].

===Vancouver 2007 (AIP)===

<tt>Madagascar</tt> was presented at a mini-symposium on '''Software for Inverse Problems''' at the [http://www.pims.math.ca/science/2007/07aip/ Conference on Applied Inverse Problems] in Vancouver on June 29, 2007. See presentation [https://ahay.org/wikilocal/docs/Fomel-AIP.ppt slides].

===Honolulu 2007 (ICASSP)===

The paper [https://ahay.org/wikilocal/docs/scons.pdf Reproducible computational experiments using SCons] was presented in the [http://www.icassp2007.org/Papers/PublicSessionIndex3.asp?Sessionid=1168 special session] on '''Reproducible Signal Processing Research''' at the [http://www.icassp2007.org/ International Conference on Acoustics, Speech, and Signal Processing] in Honolulu on April 18, 2007. See presentation [http://ahay.org/wikilocal/docs/SCons.ppt slides].

Patrick Vandewalle provides a complete [http://lcavwww.epfl.ch/reproducible_research/ICASSP07/ session program].

===Austin 2007 (Scientific Software Day)===

<tt>Madagascar</tt> was presented at the First Annual Scientific Software Day at the University of Texas at Austin on April 2, 2007. See presentation [http://ahay.org/wikilocal/docs/Madagascar-SSD.ppt slides].

===New Orleans 2006 (SEG)===

These advertising posters were prepared for the SEG Annual Meeting in New Orleans. Gilles Hennenfent had the idea, and Scott Rodgers implemented it.

[[Image:Poker_comp_BEG.png]] [[Image:Poker_comp_CSM.png]] [[Image:Poker_comp_UBC.png]]

===Vienna 2006 (EAGE)===

RSF/Madagascar was first presented at the EAGE Workshop [http://www.eage.org/events/index.php?evp=274&eventid=1&ActiveMenu=16&Opendivs=s2,s11,s13 Open Source E&P Software – Putting the Pieces Together] in Vienna on June 11, 2006. See presentation [http://ahay.org/wikilocal/docs/vienna.pdf slides].

Joe Dellinger provides a complete [http://sepwww.stanford.edu/oldsep/joe/Vienna/ workshop program with abstracts].

Guide to programming with madagascar

2024-11-26T15:34:35Z

Fomels: typos

<center>''This page was created from the LaTeX source in [https://github.com/ahay/src/blob/master/book/rsf/rsf/demo.tex book/rsf/rsf/demo.tex] using [[latex2wiki]]''</center>

This guide demonstrates a simple time-domain
finite-differences modeling code in RSF.

==Introduction==

This section presents time-domain
finite-difference modeling <ref>"Hello world" of seismic imaging.</ref>
written with the RSF library.
The C, C++, and Fortran 90 interfaces demonstrate the program.
The acoustic wave-equation
<center><math>
\Delta U - \frac{1}{v^2} \frac{\partial^2 U}{\partial t^2} = f(t)
</math></center>
can be written as
<center><math>
\left[ \Delta U - f(t) \right] v^2 =
\frac{\partial^2 U}{\partial t^2} \;.
</math></center>
<math>\Delta</math> is the Laplacian symbol,
<math>f(t)</math> is the source wavelet,
<math>v</math> is the velocity, and
<math>U</math> is a scalar wavefield.
A discrete-time step involves the following computations:
<center><math>
U_{i+1} = \left[ \Delta U -f(t) \right] v^2 \Delta t^2 + 2 U_{i} - U_{i-1} \;,
</math></center>
where <math>U_{i-1}</math>, <math>U_{i}</math> and <math>U_{i+1}</math>
represent the propagating wavefield at various time steps.

==C program==

[[Image:wavec.png|frame|center|Wave propagation snapshot.]]

==C program==

<syntaxhighlight lang="c">
/* time-domain acoustic FD modeling */
#include <rsf.h>
int main(int argc, char* argv[])
{
/* Laplacian coefficients */
float c0=-30./12.,c1=+16./12.,c2=- 1./12.;

bool verb; /* verbose flag */
sf_file Fw=NULL,Fv=NULL,Fr=NULL,Fo=NULL; /* I/O files */
sf_axis at,az,ax; /* cube axes */
int it,iz,ix; /* index variables */
int nt,nz,nx;
float dt,dz,dx,idx,idz,dt2;

float *ww,**vv,**rr; /* I/O arrays*/
float **um,**uo,**up,**ud;/* tmp arrays */

sf_init(argc,argv);
if(! sf_getbool("verb",&verb)) verb=0; /* verbose flag */

/* setup I/O files */
Fw = sf_input ("in" );
Fo = sf_output("out");
Fv = sf_input ("vel");
Fr = sf_input ("ref");

/* Read/Write axes */
at = sf_iaxa(Fw,1); nt = sf_n(at); dt = sf_d(at);
az = sf_iaxa(Fv,1); nz = sf_n(az); dz = sf_d(az);
ax = sf_iaxa(Fv,2); nx = sf_n(ax); dx = sf_d(ax);

sf_oaxa(Fo,az,1);
sf_oaxa(Fo,ax,2);
sf_oaxa(Fo,at,3);

dt2 = dt*dt;
idz = 1/(dz*dz);
idx = 1/(dx*dx);

/* read wavelet, velocity & reflectivity */
ww=sf_floatalloc(nt); sf_floatread(ww ,nt ,Fw);
vv=sf_floatalloc2(nz,nx); sf_floatread(vv[0],nz*nx,Fv);
rr=sf_floatalloc2(nz,nx); sf_floatread(rr[0],nz*nx,Fr);

/* allocate temporary arrays */
um=sf_floatalloc2(nz,nx);
uo=sf_floatalloc2(nz,nx);
up=sf_floatalloc2(nz,nx);
ud=sf_floatalloc2(nz,nx);

for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
um[ix][iz]=0;
uo[ix][iz]=0;
up[ix][iz]=0;
ud[ix][iz]=0;
}
}

/* MAIN LOOP */
if(verb) fprintf(stderr,"
");
for (it=0; it<nt; it++) {
if(verb) fprintf(stderr,"\b\b\b\b\b %d",it);

/* 4th order laplacian */
for (ix=2; ix<nx-2; ix++) {
for (iz=2; iz<nz-2; iz++) {
ud[ix][iz] =
c0* uo[ix ][iz ] * (idx+idz) +
c1*(uo[ix-1][iz ] + uo[ix+1][iz ])*idx +
c2*(uo[ix-2][iz ] + uo[ix+2][iz ])*idx +
c1*(uo[ix ][iz-1] + uo[ix ][iz+1])*idz +
c2*(uo[ix ][iz-2] + uo[ix ][iz+2])*idz;
}
}

/* inject wavelet */
for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
ud[ix][iz] -= ww[it] * rr[ix][iz];
}
}

/* scale by velocity */
for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
ud[ix][iz] *= vv[ix][iz]*vv[ix][iz];
}
}

/* time step */
for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
up[ix][iz] =
2*uo[ix][iz]
- um[ix][iz]
+ ud[ix][iz] * dt2;

um[ix][iz] = uo[ix][iz];
uo[ix][iz] = up[ix][iz];
}
}

/* write wavefield to output */
sf_floatwrite(uo[0],nz*nx,Fo);
}
if(verb) fprintf(stderr,"\n");

exit (0);
}
</syntaxhighlight>

#Declare input, output and auxiliary file tags: <tt>Fw</tt> for input wavelet, <tt>Fv</tt> for velocity, <tt>Fr</tt> for reflectivity, and <tt>Fo</tt> for output wavefield. <syntaxhighlight lang="c">
sf_file Fw=NULL,Fv=NULL,Fr=NULL,Fo=NULL; /* I/O files */
</syntaxhighlight>
#Declare RSF cube axes: <tt>at</tt> time axis, <tt>ax</tt> space axis, <tt>az</tt> depth axis. \tiny <syntaxhighlight lang="c">
sf_axis at,az,ax; /* cube axes */
</syntaxhighlight>
#Declare multi-dimensional arrays for input, output, and computations. <syntaxhighlight lang="c">

float *ww,**vv,**rr; /* I/O arrays*/
</syntaxhighlight>
#Open files for input/output. <syntaxhighlight lang="c">
Fw = sf_input ("in" );
Fo = sf_output("out");
Fv = sf_input ("vel");
Fr = sf_input ("ref");
</syntaxhighlight>
#Read axes from input files; write axes to output file. <syntaxhighlight lang="c">
at = sf_iaxa(Fw,1); nt = sf_n(at); dt = sf_d(at);
az = sf_iaxa(Fv,1); nz = sf_n(az); dz = sf_d(az);
ax = sf_iaxa(Fv,2); nx = sf_n(ax); dx = sf_d(ax);

sf_oaxa(Fo,az,1);
sf_oaxa(Fo,ax,2);
sf_oaxa(Fo,at,3);
</syntaxhighlight>
#Allocate arrays and read wavelet, velocity, and reflectivity. <syntaxhighlight lang="c">
ww=sf_floatalloc(nt); sf_floatread(ww ,nt ,Fw);
vv=sf_floatalloc2(nz,nx); sf_floatread(vv[0],nz*nx,Fv);
rr=sf_floatalloc2(nz,nx); sf_floatread(rr[0],nz*nx,Fr);
</syntaxhighlight>
#Allocate temporary arrays. <syntaxhighlight lang="c">
um=sf_floatalloc2(nz,nx);
uo=sf_floatalloc2(nz,nx);
up=sf_floatalloc2(nz,nx);
ud=sf_floatalloc2(nz,nx);
</syntaxhighlight>
#Loop over time. <syntaxhighlight lang="c">
for (it=0; it<nt; it++) {
</syntaxhighlight>
#Compute Laplacian: <math>\Delta U</math>. <syntaxhighlight lang="c">
for (ix=2; ix<nx-2; ix++) {
for (iz=2; iz<nz-2; iz++) {
ud[ix][iz] =
c0* uo[ix ][iz ] * (idx+idz) +
c1*(uo[ix-1][iz ] + uo[ix+1][iz ])*idx +
c2*(uo[ix-2][iz ] + uo[ix+2][iz ])*idx +
c1*(uo[ix ][iz-1] + uo[ix ][iz+1])*idz +
c2*(uo[ix ][iz-2] + uo[ix ][iz+2])*idz;
}
}
</syntaxhighlight>
#Inject source wavelet: <math>\left[ \Delta U - f(t) \right]</math> <syntaxhighlight lang="c">
for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
ud[ix][iz] -= ww[it] * rr[ix][iz];
}
}
</syntaxhighlight>
#Scale by velocity: <math>\left[ \Delta U - f(t) \right] v^2</math> <syntaxhighlight lang="c">
for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
ud[ix][iz] *= vv[ix][iz]*vv[ix][iz];
}
}
</syntaxhighlight>
#Time step: <math>U_{i+1} = \left[ \Delta U -f(t) \right] v^2 \Delta t^2 + 2 U_{i} - U_{i-1}</math> <syntaxhighlight lang="c">
for (ix=0; ix<nx; ix++) {
for (iz=0; iz<nz; iz++) {
up[ix][iz] =
2*uo[ix][iz]
- um[ix][iz]
+ ud[ix][iz] * dt2;

um[ix][iz] = uo[ix][iz];
uo[ix][iz] = up[ix][iz];
}
}
</syntaxhighlight>

\newpage
==C++ program==

<syntaxhighlight lang="cpp">
// time-domain acoustic FD modeling
#include <valarray>
#include <iostream>
#include <rsf.hh>
#include <cub.hh>

#include "vai.hh"

using namespace std;

int main(int argc, char* argv[])
{
// Laplacian coefficients
float c0=-30./12.,c1=+16./12.,c2=- 1./12.;

sf_init(argc,argv);// init RSF
bool verb; // vebose flag
if(! sf_getbool("verb",&verb)) verb=0;

// setup I/O files
CUB Fw("in", "i"); Fw.headin(); //Fw.report();
CUB Fv("vel","i"); Fv.headin(); //Fv.report();
CUB Fr("ref","i"); Fr.headin(); //Fr.report();
CUB Fo("out","o"); Fo.setup(3);

// Read/Write axes
sf_axis at = Fw.getax(0); int nt = sf_n(at); float dt = sf_d(at);
sf_axis az = Fv.getax(0); int nz = sf_n(az); float dz = sf_d(az);
sf_axis ax = Fv.getax(1); int nx = sf_n(ax); float dx = sf_d(ax);

Fo.putax(0,az);
Fo.putax(1,ax);
Fo.putax(2,at);
Fo.headou();

float dt2 = dt*dt;
float idz = 1/(dz*dz);
float idx = 1/(dx*dx);

// read wavelet, velocity and reflectivity
valarray<float> ww( nt ); ww=0; Fw >> ww;
valarray<float> vv( nz*nx ); vv=0; Fv >> vv;
valarray<float> rr( nz*nx ); rr=0; Fr >> rr;

// allocate temporary arrays
valarray<float> um(nz*nx); um=0;
valarray<float> uo(nz*nx); uo=0;
valarray<float> up(nz*nx); up=0;
valarray<float> ud(nz*nx); ud=0;

// init ValArray Index counter
VAI k(nz,nx);

// MAIN LOOP
if(verb) cerr << endl;
for (int it=0; it<nt; it++) {
if(verb) cerr << "\b\b\b\b\b" << it;

// 4th order laplacian
for (int ix=2; ix<nx-2; ix++) {
for (int iz=2; iz<nz-2; iz++) {
ud[k(iz,ix)] =
c0* uo[ k(iz ,ix )] * (idx+idz) +
c1*(uo[ k(iz ,ix-1)]+uo[ k(iz ,ix+1)]) * idx +
c1*(uo[ k(iz-1,ix )]+uo[ k(iz+1,ix )]) * idz +
c2*(uo[ k(iz ,ix-2)]+uo[ k(iz ,ix+2)]) * idx +
c2*(uo[ k(iz-2,ix )]+uo[ k(iz+2,ix )]) * idz;
}
}

// inject wavelet
ud -= ww[it] * rr;

// scale by velocity
ud *= vv*vv;

// time step
up=(float)2 * uo - um + ud * dt2;
um = uo;
uo = up;

// write wavefield to output output
Fo << uo;
}
if(verb) cerr << endl;

exit(0);
}

</syntaxhighlight>

#Declare input, output, and auxiliary file cubes (of type <tt>CUB</tt>). <syntaxhighlight lang="cpp">
CUB Fw("in", "i"); Fw.headin(); //Fw.report();
CUB Fv("vel","i"); Fv.headin(); //Fv.report();
CUB Fr("ref","i"); Fr.headin(); //Fr.report();
CUB Fo("out","o"); Fo.setup(3);
</syntaxhighlight>
#Declare, read and write RSF cube axes: <tt>at</tt> time axis, <tt>ax</tt> space axis, <tt>az</tt> depth axis. <syntaxhighlight lang="cpp">
sf_axis at = Fw.getax(0); int nt = sf_n(at); float dt = sf_d(at);
sf_axis az = Fv.getax(0); int nz = sf_n(az); float dz = sf_d(az);
sf_axis ax = Fv.getax(1); int nx = sf_n(ax); float dx = sf_d(ax);
</syntaxhighlight>
#Declare multi-dimensional <tt>valarrays</tt> for input, output and read data. <syntaxhighlight lang="cpp">
valarray<float> ww( nt ); ww=0; Fw >> ww;
valarray<float> vv( nz*nx ); vv=0; Fv >> vv;
valarray<float> rr( nz*nx ); rr=0; Fr >> rr;
</syntaxhighlight>
#Declare multi-dimensional <tt>valarrays</tt> for temporary storage. <syntaxhighlight lang="cpp">
valarray<float> um(nz*nx); um=0;
valarray<float> uo(nz*nx); uo=0;
valarray<float> up(nz*nx); up=0;
valarray<float> ud(nz*nx); ud=0;
</syntaxhighlight>
#Initialize multidimensional <tt>valarray</tt> index counter (of type <tt>VAI</tt>). <syntaxhighlight lang="cpp">
VAI k(nz,nx);
</syntaxhighlight>
#Loop over time. <syntaxhighlight lang="cpp">
for (int it=0; it<nt; it++) {
</syntaxhighlight>
#Compute Laplacian: <math>\Delta U</math>. <syntaxhighlight lang="cpp">
for (int ix=2; ix<nx-2; ix++) {
for (int iz=2; iz<nz-2; iz++) {
ud[k(iz,ix)] =
c0* uo[ k(iz ,ix )] * (idx+idz) +
c1*(uo[ k(iz ,ix-1)]+uo[ k(iz ,ix+1)]) * idx +
c1*(uo[ k(iz-1,ix )]+uo[ k(iz+1,ix )]) * idz +
c2*(uo[ k(iz ,ix-2)]+uo[ k(iz ,ix+2)]) * idx +
c2*(uo[ k(iz-2,ix )]+uo[ k(iz+2,ix )]) * idz;
}
}
</syntaxhighlight>
#Inject source wavelet: <math>\left[ \Delta U - f(t) \right]</math> <syntaxhighlight lang="cpp">
ud -= ww[it] * rr;
</syntaxhighlight>
#Scale by velocity: <math>\left[ \Delta U - f(t) \right] v^2</math> <syntaxhighlight lang="cpp">
ud *= vv*vv;
</syntaxhighlight>
#Time step: <math>U_{i+1} = \left[ \Delta U -f(t) \right] v^2 \Delta t^2 + 2 U_{i} - U_{i-1}</math> <syntaxhighlight lang="cpp">
up=(float)2 * uo - um + ud * dt2;
um = uo;
uo = up;
</syntaxhighlight>

==Fortran 90 program==

<syntaxhighlight lang="fortran">
! time-domain acoustic FD modeling
program AFDMf90
use rsf

implicit none

! Laplacian coefficients
real :: c0=-30./12.,c1=+16./12.,c2=- 1./12.

logical :: verb ! verbose flag
type(file) :: Fw,Fv,Fr,Fo ! I/O files
type(axa) :: at,az,ax ! cube axes
integer :: it,iz,ix ! index variables
integer :: nt,nz,nx
real :: dt,dz,dx
real :: idx,idz,dt2

real, allocatable :: vv(:,:),rr(:,:),ww(:) ! I/O arrays
real, allocatable :: um(:,:),uo(:,:),up(:,:),ud(:,:) ! tmp arrays

call sf_init() ! init RSF
call from_par("verb",verb,.false.)

! Setup I/O files
Fw=rsf_input ("in")
Fv=rsf_input ("vel")
Fr=rsf_input ("ref")
Fo=rsf_output("out")

! Read/Write axes
call iaxa(Fw,at,1); nt = at%n; dt = at%d
call iaxa(Fv,az,1); nz = az%n; dz = az%d
call iaxa(Fv,ax,2); nx = ax%n; dx = ax%d

call oaxa(Fo,az,1)
call oaxa(Fo,ax,2)
call oaxa(Fo,at,3)

dt2 = dt*dt
idz = 1/(dz*dz)
idx = 1/(dx*dx)

! read wavelet, velocity & reflectivity
allocate(ww(nt)); call rsf_read(Fw,ww)
allocate(vv(nz,nx)); call rsf_read(Fv,vv)
allocate(rr(nz,nx)); call rsf_read(Fr,rr)

! allocate temporary arrays
allocate(um(nz,nx)); um=0.
allocate(uo(nz,nx)); uo=0.
allocate(up(nz,nx)); up=0.
allocate(ud(nz,nx)); ud=0.

! MAIN LOOP
do it=1,nt
if(verb) write (0,*) it

ud(3:nz-2,3:nx-2) = &
c0* uo(3:nz-2,3:nx-2) * (idx + idz) + &
c1*(uo(3:nz-2,2:nx-3) + uo(3:nz-2,4:nx-1))*idx + &
c2*(uo(3:nz-2,1:nx-4) + uo(3:nz-2,5:nx ))*idx + &
c1*(uo(2:nz-3,3:nx-2) + uo(4:nz-1,3:nx-2))*idz + &
c2*(uo(1:nz-4,3:nx-2) + uo(5:nz ,3:nx-2))*idz

! inject wavelet
ud = ud - ww(it) * rr

! scale by velocity
ud= ud *vv*vv

! time step
up = 2*uo - um + ud * dt2
um = uo
uo = up

! write wavefield to output
call rsf_write(Fo,uo)
end do

call exit(0)
end program AFDMf90
</syntaxhighlight>

#Declare input, output, and auxiliary file tags. <syntaxhighlight lang="fortran">
type(file) :: Fw,Fv,Fr,Fo ! I/O files
</syntaxhighlight>
#Declare RSF cube axes: <tt>at</tt> time axis, <tt>ax</tt> space axis, <tt>az</tt> depth axis. <syntaxhighlight lang="fortran">
type(axa) :: at,az,ax ! cube axes
</syntaxhighlight>
#Declare multi-dimensional arrays for input, output, and computations. <syntaxhighlight lang="fortran">
real, allocatable :: vv(:,:),rr(:,:),ww(:) ! I/O arrays
real, allocatable :: um(:,:),uo(:,:),up(:,:),ud(:,:) ! tmp arrays
</syntaxhighlight>
#Open files for input/output. <syntaxhighlight lang="fortran">
Fw=rsf_input ("in")
Fv=rsf_input ("vel")
Fr=rsf_input ("ref")
Fo=rsf_output("out")
</syntaxhighlight>
#Read axes from input files; write axes to output file. <syntaxhighlight lang="fortran">
call iaxa(Fw,at,1); nt = at%n; dt = at%d
call iaxa(Fv,az,1); nz = az%n; dz = az%d
call iaxa(Fv,ax,2); nx = ax%n; dx = ax%d

call oaxa(Fo,az,1)
call oaxa(Fo,ax,2)
call oaxa(Fo,at,3)
</syntaxhighlight>
#Allocate arrays and read wavelet, velocity, and reflectivity. <syntaxhighlight lang="fortran">
allocate(ww(nt)); call rsf_read(Fw,ww)
allocate(vv(nz,nx)); call rsf_read(Fv,vv)
allocate(rr(nz,nx)); call rsf_read(Fr,rr)
</syntaxhighlight>
#Allocate temporary arrays. <syntaxhighlight lang="fortran">
allocate(um(nz,nx)); um=0.
allocate(uo(nz,nx)); uo=0.
allocate(up(nz,nx)); up=0.
allocate(ud(nz,nx)); ud=0.
</syntaxhighlight>
#Loop over time. <syntaxhighlight lang="fortran">
do it=1,nt
</syntaxhighlight>
#Compute Laplacian: <math>\Delta U</math>. <syntaxhighlight lang="fortran">
ud(3:nz-2,3:nx-2) = &
c0* uo(3:nz-2,3:nx-2) * (idx + idz) + &
c1*(uo(3:nz-2,2:nx-3) + uo(3:nz-2,4:nx-1))*idx + &
c2*(uo(3:nz-2,1:nx-4) + uo(3:nz-2,5:nx ))*idx + &
c1*(uo(2:nz-3,3:nx-2) + uo(4:nz-1,3:nx-2))*idz + &
c2*(uo(1:nz-4,3:nx-2) + uo(5:nz ,3:nx-2))*idz
</syntaxhighlight>
#Inject source wavelet: <math>\left[ \Delta U - f(t) \right]</math> <syntaxhighlight lang="fortran">
ud = ud - ww(it) * rr
</syntaxhighlight>
#Scale by velocity: <math>\left[ \Delta U - f(t) \right] v^2</math> <syntaxhighlight lang="fortran">
ud= ud *vv*vv
</syntaxhighlight>
#Time step: <math>U_{i+1} = \left[ \Delta U -f(t) \right] v^2 \Delta t^2 + 2 U_{i} - U_{i-1}</math> <syntaxhighlight lang="fortran">
up = 2*uo - um + ud * dt2
um = uo
uo = up
</syntaxhighlight>

==Python program==

<syntaxhighlight lang="python">
#!/usr/bin/env python

import sys
import numpy
import m8r

c0=-30./12.
c1=+16./12.
c2=- 1./12.

par = m8r.Par()
verb = par.bool("verb",False) # verbosity

# setup I/O files
Fw=m8r.Input()
Fv=m8r.Input ("vel")
Fr=m8r.Input ("ref")
Fo=m8r.Output()

# Read/Write axes
at = Fw.axis(1); nt = at['n']; dt = at['d']
az = Fv.axis(1); nz = az['n']; dz = az['d']
ax = Fv.axis(2); nx = ax['n']; dx = ax['d']

Fo.putaxis(az,1)
Fo.putaxis(ax,2)
Fo.putaxis(at,3)

dt2 = dt*dt
idz = 1/(dz*dz)
idx = 1/(dx*dx)

# read wavelet, velocity & reflectivity
ww = numpy.zeros(nt,'f'); Fw.read(ww)
vv = numpy.zeros([nz,nx],'f'); Fv.read(vv)
rr = numpy.zeros([nz,nx],'f'); Fr.read(rr)

# allocate temporary arrays
um = numpy.zeros([nz,nx],'f')
uo = numpy.zeros([nz,nx],'f')
up = numpy.zeros([nz,nx],'f')
ud = numpy.zeros([nz,nx],'f')

# MAIN LOOP
for it in range(nt):
if verb:
sys.stderr.write("\b\b\b\b\b %d" % it)

ud[2:-2,2:-2] = \
c0* uo[2:-2,2:-2] * (idx + idz) + \
c1*(uo[2:-2,1:-3] + uo[2:-2,3:-1])*idx + \
c2*(uo[2:-2, :-4] + uo[2:-2,4: ])*idx + \
c1*(uo[1:-3,2:-2] + uo[3:-1,2:-2])*idz + \
c2*(uo[ :-4,2:-2] + uo[4: ,2:-2])*idz

# inject wavelet
ud = ud - ww[it] * rr

# scale by velocity
ud= ud *vv*vv

# time step
up = 2*uo - um + ud * dt2
um = uo
uo = up

if verb:
sys.stderr.write("\n")
Fo.write(uo)

sys.exit(0)
</syntaxhighlight>

[[Image:wavepython.png|frame|center|Wave propagation snapshot.]]

#Open files for input/output. <syntaxhighlight lang="python">
Fw=m8r.Input()
Fv=m8r.Input ("vel")
Fr=m8r.Input ("ref")
Fo=m8r.Output()
</syntaxhighlight>
#Read axes from input files; write axes to output file. <syntaxhighlight lang="python">
at = Fw.axis(1); nt = at['n']; dt = at['d']
az = Fv.axis(1); nz = az['n']; dz = az['d']
ax = Fv.axis(2); nx = ax['n']; dx = ax['d']

Fo.putaxis(az,1)
Fo.putaxis(ax,2)
Fo.putaxis(at,3)
</syntaxhighlight>
#Allocate arrays and read wavelet, velocity, and reflectivity. <syntaxhighlight lang="python">
ww = numpy.zeros(nt,'f'); Fw.read(ww)
vv = numpy.zeros([nz,nx],'f'); Fv.read(vv)
rr = numpy.zeros([nz,nx],'f'); Fr.read(rr)
</syntaxhighlight>
#Allocate temporary arrays. <syntaxhighlight lang="python">
um = numpy.zeros([nz,nx],'f')
uo = numpy.zeros([nz,nx],'f')
up = numpy.zeros([nz,nx],'f')
ud = numpy.zeros([nz,nx],'f')
</syntaxhighlight>
#Loop over time. <syntaxhighlight lang="python">
for it in range(nt):
</syntaxhighlight>
#Compute Laplacian: <math>\Delta U</math>. <syntaxhighlight lang="python">
ud[2:-2,2:-2] = \
c0* uo[2:-2,2:-2] * (idx + idz) + \
c1*(uo[2:-2,1:-3] + uo[2:-2,3:-1])*idx + \
c2*(uo[2:-2, :-4] + uo[2:-2,4: ])*idx + \
c1*(uo[1:-3,2:-2] + uo[3:-1,2:-2])*idz + \
c2*(uo[ :-4,2:-2] + uo[4: ,2:-2])*idz
</syntaxhighlight>
#Inject source wavelet: <math>\left[ \Delta U - f(t) \right]</math> <syntaxhighlight lang="python">
ud = ud - ww[it] * rr
</syntaxhighlight>
#Scale by velocity: <math>\left[ \Delta U - f(t) \right] v^2</math> <syntaxhighlight lang="python">
ud= ud *vv*vv
</syntaxhighlight>
#Time step: <math>U_{i+1} = \left[ \Delta U -f(t) \right] v^2 \Delta t^2 + 2 U_{i} - U_{i-1}</math> <syntaxhighlight lang="python">
up = 2*uo - um + ud * dt2
um = uo
uo = up
</syntaxhighlight>

==References==
<references/>

Guide to madagascar API

2024-11-26T04:05:20Z

Fomels: typos

<center>''This page was created from the LaTeX source in [https://github.com/ahay/src/blob/master/book/m8r/api/paper.tex book/m8r/api/paper.tex] using [[latex2wiki]]''</center>

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

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

==Introduction==
You may need to use an appropriate programming interface to work with RSF files in your own programs. We will demonstrate the interface in
different languages using a simple example. Our 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 [https://github.com/ahay/src/blob/master/system/generic/Mclip.c 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.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

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

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>).
<syntaxhighlight lang="c">
/* Initialize RSF */
sf_init(argc,argv);
</syntaxhighlight>

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.
<syntaxhighlight lang="c">
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</syntaxhighlight>

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.
<syntaxhighlight lang="c">
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</syntaxhighlight>

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.
<syntaxhighlight lang="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);
</syntaxhighlight>

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 similarly, 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.
<syntaxhighlight lang="c">
/* parameter from the command line (i.e., clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>

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.
<syntaxhighlight lang="c">
/* allocate floating point array */
trace = sf_floatalloc (n1);
</syntaxhighlight>

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.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it, and write the output. 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>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

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. RSF typically uses flags
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

Let us examine it line by line.
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

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

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

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.
<syntaxhighlight lang="cpp">
in.get("n1",n1);
n2=in.size(1);
</syntaxhighlight>

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.
<syntaxhighlight lang="cpp">
par.get("clip",clip); // parameter from the command line
</syntaxhighlight>

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.
<syntaxhighlight lang="cpp">
std::valarray<float> trace(n1);
</syntaxhighlight>

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.
<syntaxhighlight lang="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
}
</syntaxhighlight>

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. RSF typically uses flags in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="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
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
call sf_init()
</syntaxhighlight>

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

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.
<syntaxhighlight lang="fortran">
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</syntaxhighlight>

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.
<syntaxhighlight lang="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)
</syntaxhighlight>

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 similarly, 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.
<syntaxhighlight lang="fortran">
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</syntaxhighlight>

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.
<syntaxhighlight lang="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
</syntaxhighlight>

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. RSF typically uses flags in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="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
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
use rsf
</syntaxhighlight>

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

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

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.
<syntaxhighlight lang="fortran">
if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

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 similarly, 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.
<syntaxhighlight lang="fortran">
n2 = filesize(in,1)
</syntaxhighlight>

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>.
<syntaxhighlight lang="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

</syntaxhighlight>

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. RSF typically uses flags 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 interface examples are in the directory $RSFSRC/API/python/test.

The Python script clip.py is:

<syntaxhighlight lang="python">
#!/usr/bin/env python

import numpy
import m8r

par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type

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

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

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

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

</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="python">
import numpy
import m8r
</syntaxhighlight>

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

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

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 similarly, 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> class. 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.
<syntaxhighlight lang="python">
clip = par.float("clip")
assert clip
</syntaxhighlight>

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

Finally, we do the actual work: allocate an array to hold a trace and loop
over input traces, reading, clipping, and writing out each trace.

Alternative code uses inp.trace to allocate an array and read
the whole file into memory. The loop is no longer needed:
<syntaxhighlight lang="python">
alltraces=inp.read()
alltraces = numpy.clip(alltraces,-clip,clip)
output.write(alltraces)
</syntaxhighlight>

===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>.

===Using the Python API for interactive development in Jupyter notebooks===
Jupyter notebooks are an excellent way to prototype Python code, explore data, and
integrate rich text to describe your code. There are four example notebooks in
$RSFSRC/api/python/test that demonstrate how to use Jupyter notebooks. These are:
{|class="wikitable"
|-
| clip.ipynb || clip.py converted to a Jupyter notebook
|-
|simple_m8r_create_write_filter_read.ipynb || numpy, write rsf, Madagascar commands, read rsf, plot
|-
| tle_edge_preserve.ipynb || reproduces a paper from TLE with numpy and matplotlib
|-
| file_filter_scons_example.ipynb || advanced m8r options; File, filter, and scons from python
|}
They can be started from the command line with the commands:
<pre>
cd $RSFSRC/api/python/test
jupyter notebook clip.ipynb
</pre>

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

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

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

<syntaxhighlight lang="python">
import numpy, m8r

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data =inp.read(shape=(n2,n1))
data = data.transpose() # Example of numpy in action

print data
</syntaxhighlight>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17.]]
</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 first writing a file to disk. [https://matplotlib.org/ 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:

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

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:

<syntaxhighlight lang="python">
show()
</syntaxhighlight>

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 to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<syntaxhighlight lang="python">
savefig('myfile.png')
</syntaxhighlight>

[[Image:matplotlib_imshow.png]]

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

<syntaxhighlight lang="python">
#!/usr/bin/env python
import m8r, numpy, sys, pylab

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data=input.read()

pylab.imshow(data)
pylab.savefig('out.png')
</syntaxhighlight>
===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.
<syntaxhighlight lang="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
</syntaxhighlight>

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

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

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

Next, we allocate the trace array and create an output file.
<syntaxhighlight lang="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
</syntaxhighlight>

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>. The example above illustrates all these functions except <tt>rsf_par</tt>.
===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==
Two Java interfaces 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):
<syntaxhighlight lang="bash">
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</syntaxhighlight>

3. Reconfigure Madagascar:
<syntaxhighlight lang="bash">
./configure API=java
</syntaxhighlight>

4. Reinstall Madagascar (Ignore the compilation warnings for Java files):
<syntaxhighlight lang="bash">
scons; scons install
</syntaxhighlight>

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

Ensure you set your LD_LIBRARY_PATH to include <tt>$RSFROOT/lib</tt>.

A short demonstration of the interface follows:

<syntaxhighlight lang="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();
}
}
</syntaxhighlight>

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:
<syntaxhighlight lang="bash">
javac -cp $RSFROOT/lib Clip.java
</syntaxhighlight>

To include this as part of a SCons script (SConstruct):
<syntaxhighlight lang="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')
</syntaxhighlight>

Note that we compile <tt>Clip.java</tt> using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using <tt>WhereIs('java')</tt>. 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. It only allows you to read RSF files with fewer than four 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.''' Currently, The Java interface treats all values as floats and does not support 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.
<syntaxhighlight lang="bash">
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</syntaxhighlight>

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 classes already in the CLASSPATH environmental variable in the shell 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.

<syntaxhighlight lang="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()
</syntaxhighlight>

The interface itself is fairly straightforward. The [[Library_Reference#Java_API | Library Reference]] provides more details on the methods exposed by the API.

Data clipping, argument parsing, and IO example:

<syntaxhighlight lang="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 as the file
//located at output.
Writer.writeRSF(header,data,output);
}
}
</syntaxhighlight>

How to read a file:

<syntaxhighlight lang="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
}
}
</syntaxhighlight>

How to write a file:

<syntaxhighlight lang="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!
}
}
</syntaxhighlight>

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:

<syntaxhighlight lang="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!
}
}
</syntaxhighlight>

==References==
<references/>

Contributing new programs to Madagascar

2024-11-26T03:32:27Z

Fomels: /* Static code checks */ links

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 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.
# [https://github.com/ Sign up at GitHub].
# Upload your directory to the [https://github.com/ahay/src Github repository] by making a pull request.
# Announce your changes in the release notes for the upcoming stable version ([https://github.com/ahay/src/blob/master/NEWS.txt $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, the release version does not include programs without examples.

Some additional helpful information is included below.

==Repository procedure suggestions==

Please try to do [http://en.wikipedia.org/wiki/Atomic_commit atomic commits]. 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 backward 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 backward 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 sync with the codebase.</ref>.

==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."
==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> to:
* Register them in SCons' dependency tree so that <tt> scons remove them -c install</tt>
* Avoid a situation where a user tries to execute a Madagascar Python program but creates 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 original author's website. 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 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. Plans include dynamic checking by [http://valgrind.org/ Valgrind] or IBM's [http://www-306.ibm.com/software/awdtools/purify/ Rational Purify]. Madagascar code metrics are [https://openhub.net/p/m8r assessed periodically by Open Hub].

==Maintaining the maintenance tools==
Please document scripts that 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==
In a contractual work relationship, you may find it handy to reuse some of your 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 release 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 the following:
* 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 before 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.

Ensure that proper copyright and licensing statements are in place in case of dual licensing, even if you are on excellent terms with your client and are confident 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.

Contributing new programs to Madagascar

2024-11-26T03:30:19Z

Fomels: /* Repository procedure suggestions */

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 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.
# [https://github.com/ Sign up at GitHub].
# Upload your directory to the [https://github.com/ahay/src Github repository] by making a pull request.
# Announce your changes in the release notes for the upcoming stable version ([https://github.com/ahay/src/blob/master/NEWS.txt $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, the release version does not include programs without examples.

Some additional helpful information is included below.

==Repository procedure suggestions==

Please try to do [http://en.wikipedia.org/wiki/Atomic_commit atomic commits]. 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 backward 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 backward 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 sync with the codebase.</ref>.

==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."
==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> to:
* Register them in SCons' dependency tree so that <tt> scons remove them -c install</tt>
* Avoid a situation where a user tries to execute a Madagascar Python program but creates 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 original author's website. 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 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. Plans include 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 that 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==
In a contractual work relationship, you may find it handy to reuse some of your 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 release 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 the following:
* 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 before 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.

Ensure that proper copyright and licensing statements are in place in case of dual licensing, even if you are on excellent terms with your client and are confident 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.

Contributing new programs to Madagascar

2024-11-26T03:29:32Z

Fomels: typos

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 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.
# [https://github.com/ Sign up at GitHub].
# Upload your directory to the [https://github.com/ahay/src Github repository] by making a pull request.
# Announce your changes in the release notes for the upcoming stable version ([https://github.com/ahay/src/blob/master/NEWS.txt $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, the release version does not include programs without examples.

Some additional helpful information is included below.

==Repository procedure suggestions==
Please try to:
* Do [http://en.wikipedia.org/wiki/Atomic_commit atomic commits].
* If you use Subversion, run <pre>svn commit -m "your message here"</pre> 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.

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 backward 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 backward 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 sync with the codebase.</ref>.

==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."
==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> to:
* Register them in SCons' dependency tree so that <tt> scons remove them -c install</tt>
* Avoid a situation where a user tries to execute a Madagascar Python program but creates 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 original author's website. 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 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. Plans include 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 that 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==
In a contractual work relationship, you may find it handy to reuse some of your 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 release 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 the following:
* 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 before 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.

Ensure that proper copyright and licensing statements are in place in case of dual licensing, even if you are on excellent terms with your client and are confident 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.

Adding new programs to Madagascar

2024-11-25T02:28:59Z

Fomels: typos

[[Image:Fotolia_800161_XS.jpg|right|]]
Madagascar is fully extensible, so you can share your work with the world or keep it for yourself. 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 them.
#Note that running <tt>scons</tt> inside your <tt>user</tt> directory compiles programs with debugging flags to make them suitable for debugging with standard debuggers such as [http://www.gnu.org/software/gdb/ gdb], dbx, or [http://www.etnus.com/ TotalView]. Running <tt>scons install</tt> inside <tt>$RSFSRC</tt> 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: in-code documentation, the Wiki, and reproducible papers.
===In-code documentation===
Of course, comment your code, focusing on "why" (the code itself describes the "how"). Keep comments sparse so the human reader can simultaneously absorb as much code as possible. 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 produce a self-doc page for your program automatically. This page will be displayed in the terminal (using basic text-mode formatting) when the program is invoked without any arguments, and an 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:
<syntaxhighlight lang="c">
/* Short description line
Comments here blablabla lorem ipsum dolores sit amet...

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

/* Copyright notice */
</syntaxhighlight>
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:
<syntaxhighlight lang="c">
if (!sf_getbool("su",&su)) su=false;
/* y if input is SU, n if input is SEGY */
</syntaxhighlight>
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:
<syntaxhighlight lang="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...
</syntaxhighlight>
Then, make sure to
<syntaxhighlight lang="python">
import rsfprog
</syntaxhighlight>
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>:
<syntaxhighlight lang="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
</syntaxhighlight>

====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 the same line or first line after
</pre>

===Wiki documentation===
The self-doc is good as a reminder of what the parameters mean and their default values, but more is usually needed for someone who has never used the tool. This is what the [[Guide to Madagascar programs|Guide to programs]] is for. Whenever you change or create a program, add a section for it, 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 with 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 because it is already in MediaWiki format. Another directory can be used instead of $HOME.

If your program/script reads an environment variable, 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 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 users who do not already know they need it can find 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 a reproducible paper and how to produce one.

==Style guide==
* Use components (macros, types, functions) from the Madagascar library to maximize component reuse and ensure 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 code comments but to commenting out actual code. You can always use the version control system to retrieve the older version
* Use standard C: declare all variables at the beginning of the program, use C-style comments <tt>/* */</tt>. Some compilers do not allow C++-style variable declarations and comments in C programs.

==How to test your program==
The testing mechanism is semi-automatic. Testing can be done for any program 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 out where the 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 the 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 quickly alternates between the stored figure and your figure.
#* If the figures look identical, then 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, 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 must 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
<syntaxhighlight lang="python">
RSF_src_root = '/path/to/madagascar/source/root/'
</syntaxhighlight>
Then, replace <tt>../..</tt> throughout the SConstruct with
<syntaxhighlight lang="python">
os.path.join(RSF_src_root,'whatever_followed_after_dotdots')
</syntaxhighlight>

===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
<syntaxhighlight lang="lisp">
(setq auto-mode-alist
(cons '("SConstruct" . python-mode) auto-mode-alist))
</syntaxhighlight>
:in your <tt>.emacs</tt> file to enable it on <tt>SConstruct</tt> files.

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

* Use
<syntaxhighlight lang="lisp">
(add-hook 'c-mode-common-hook
'(lambda () (c-set-style "linux")
(c-set-offset 'case-label 4)
(setq c-basic-offset 4)))
</syntaxhighlight>
:to ensure that the indentation 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:

<syntaxhighlight lang="bash">
au BufRead,BufNewFile SConstruct set filetype=python

syntax enable
</syntaxhighlight>

Reproducible computational experiments using SCons

2024-11-20T23:42:00Z

Fomels: typos

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

SCons (from Software Construction) is a well-known open-source
program designed primarily for building software. This paper describes our method of extending SCons for managing data processing
flows and reproducible computational experiments. We demonstrate our
usage of SCons with a couple of simple examples.

==Introduction==
This paper introduces an environment for reproducible computational
experiments developed as part of the "Madagascar" software package.
To reproduce the example experiments in this paper, you can download
Madagascar from https://www.ahay.org . At the moment, the
main Madagascar interface is the Unix shell command line so that you
will need a Unix/POSIX system (Linux, Mac OS X, Solaris, etc.) or Unix
emulation under Windows (Cygwin, SFU, etc.)
Our focus, however, is not only on particular tools we use in our research but also on the general philosophy of
reproducible computations.
===Reproducible research philosophy===
Peer review is the backbone of scientific progress. From the ancient
alchemists who worked secretly on magic solutions to insolvable
problems, modern science has come a long way to become a social
enterprise where the community openly publishes and verifies hypotheses, theories, and experimental results. By reproducing and
verifying previously published research, a researcher can take new
steps to advance the progress of science.
Traditionally, scientific disciplines are divided into theoretical and
experimental studies. The reproduction and verification of theoretical
results usually require only imagination (apart from pencils and
paper), and experimental results are verified in laboratories using
equipment and materials similar to those described in the publication.
During the last century, computational studies emerged as a new
scientific discipline. Computational experiments are carried out on a
computer by applying numerical algorithms to digital data. How
reproducible are such experiments? On one hand, reproducing the result
of a numerical experiment is difficult. The reader needs
to have access to precisely the same kind of input data, software, and
hardware as the publication's author to reproduce the
published result. It is often difficult or impossible to provide
detailed specifications for these components. On the other hand, essential
computational system components such as operating systems and
file formats are getting increasingly standardized. New components
can be shared in principle because they represent digital
information transferable over the Internet.
The practice of software sharing has fueled the miraculously efficient
development of Linux, Apache, and many other open-source software
projects. Its proponents often refer to this ideology as an analog of
the scientific peer review tradition. Eric Raymond, a well-known
open-source advocate writes (Raymond, 2004<ref>Raymond, E. S., 2004, The art of UNIX programming: Addison-Wesley.</ref>):
<blockquote>
Abandoning the habit of secrecy in favor of process transparency and
peer review was the crucial step by which alchemy became chemistry.
In the same way, it is beginning to appear that open-source
development may signal the long-awaited maturation of software
development as a discipline.
</blockquote>
While software development tries to imitate science, computational
science must borrow from the open-source model to sustain
itself as a fully scientific discipline. In the words of Randy LeVeque, a
prominent mathematician (LeVeque, 2006<ref>LeVeque, R. J., to appear, 2006, Wave propagation software, computational science, and reproducible research: Presented at the Proc. International Congress of Mathematicians.</ref>),
<blockquote>
Within the world of science, computation is now rightly seen as a
third vertex of a triangle, complementing experiment and
theory. However, as it is now often practiced, one can make a good case that computing is the last refuge of the scientific scoundrel
[...] Where else in science can one get away with publishing
observations that are claimed to prove a theory or illustrate the
success of a technique without having to give a careful description of
the methods used in sufficient detail that others can attempt to
repeat the experiment? [...] Scientific and mathematical journals are
filled with pretty pictures these days of computational experiments
that the reader has no hope of repeating. Even brilliant and well-intentioned computational scientists often do a poor job of presenting
their work in a reproducible manner. The methods are often very
vaguely defined, and even if they are carefully defined, they would
normally have to be implemented from scratch by the reader in order to
test them.
</blockquote>
In computer science, the concept of publishing and explaining computer programs goes back to the idea of ''literate programming'' promoted
by Knuth (1984<ref>Knuth, D. E., 1984, Literate programming: Computer Journal, '''27''', 97--111.</ref>) and expended by many other researchers
(Thimbleby, 2003<ref>Thimbleby, H., 2003, Explaining code for publication: Software - Practice & Experience, '''33''', 975--908.</ref>). In his 2004 lecture on "Better Programming,"
Harold Thimbleby notes<ref>http://www.uclic.ucl.ac.uk/harold/</ref>
<blockquote>
We want ideas, and in particular programs, that work in one place to
work elsewhere. One form of objectivity is that published science
must work elsewhere than just in the author's laboratory or even
just in the author's imagination; this requirement is called
''reproducibility'' .
</blockquote>

Nearly ten years ago, the technology of reproducible research in
geophysics was pioneered by Jon Claerbout and his students at the
Stanford Exploration Project (SEP). SEP's system of reproducible
research requires the author of a publication to document the creation of
numerical results from the input data and software sources to let
others test and verify the reproducibility of the results
(Claerbout, 1992a<ref>Claerbout, J., 1992a, Electronic documents give reproducible research a new meaning: 62nd Ann. Internat. Mtg, 601--604, Soc. of Expl. Geophys.</ref>;Schwab et al., 2000<ref>Schwab, M., M. Karrenbach, and J. Claerbout, 2000, Making scientific computations reproducible: Computing in Science & Engineering, '''2''', 61--67.</ref>).

The discipline of reproducible research was also adopted and
popularized in the statistics and wavelet theory community by
Buckheit and Donoho (1995<ref>Buckheit, J. and D. L. Donoho, 1995, Wavelab and reproducible research, ''in'' Wavelets and Statistics, volume '''103''', 55--81. Springer-Verlag.</ref>). It is referenced in several popular wavelet theory
books (Hubbard, 1998<ref>Hubbard, B. B., 1998, The world according to wavelets: The story of a mathematical technique in the making: AK Peters.</ref>;Mallat, 1999<ref>Mallat, S., 1999, A wavelet tour of signal processing: Academic Press.</ref>). Pledges for reproducible research
appear nowadays in fields as diverse as
bioinformatics
(Gentleman et al., 2004<ref>Gentleman, R. C., V. J. Carey, D. M. Bates, B. Bolstad, M. Dettling, S. Dudoit, B. Ellis, L. Gautier, Y. Ge, J. Gentry, K. Hornik, T. Hothorn, W. Huber, S. Iacus, R. Irizarry, F. Leisch, C. Li, M. Maechler, A. J. Rossini, G. Sawitzki, C. Smith, G. Smyth, L. Tierney, J. Y. Yang, and J. Zhang, 2004, Bioconductor: open software development for computational biology and bioinformatics: Genome Biology, '''5''', R80.</ref>),
geoinformatics (Bivand, 2006<ref>Bivand, R., 2006, Implementing spatial data analysis software tools in r: Geographical Analysis, '''38''', 23--40.</ref>), and computational wave propagation (LeVeque, 2006<ref>LeVeque, R. J., to appear, 2006, Wave propagation software, computational science, and reproducible research: Presented at the Proc. International Congress of Mathematicians.</ref>). However, computational scientists' adoption of reproducible research practice has been slow.
Partially, this is caused by complicated and inadequate tools.

===Tools for reproducible research===
The reproducible research system developed at Stanford is based on
"make" (Stallman et al., 2004<ref>Stallman, R. M., R. McGrath, and P. D. Smith, 2004, GNU make: A program for directing recompilation: GNU Press.</ref>), a Unix software construction utility.
Initially, SEP used "cake," a dialect of "make"
(Nichols and Cole, 1989<ref>Nichols, D. and S. Cole, 1989, Device independent software installation with CAKE, ''in'' SEP-61, 341--344. Stanford Exploration Project.</ref>;Claerbout and Nichols, 1990<ref>Claerbout, J. F. and D. Nichols, 1990, Why active documents need cake, ''in'' SEP-67, 145--148. Stanford Exploration Project.</ref>;Claerbout, 1992b<ref>-------- 1992b, How to use Cake with interactive documents, ''in'' SEP-73, 451--460. Stanford Exploration Project.</ref>;Claerbout and Karrenbach, 1993<ref>Claerbout, J. F. and M. Karrenbach, 1993, How to use cake with interactive documents, ''in'' SEP-77, 427--444. Stanford Exploration Project.</ref>).
The system was converted to "GNU make," a more standard dialect, by
Schwab and Schroeder (1995<ref>Schwab, M. and J. Schroeder, 1995, Reproducible research documents using GNUmake, ''in'' SEP-89, 217--226. Stanford Exploration Project.</ref>). The "make" program keeps track of dependencies between different
components of the system and the software construction targets, which,
in the case of a reproducible research system, turn into figures and
manuscripts. The author specifies the targets and commands for their construction in "makefiles," which serve as databases for
defining source and target dependencies. A dependency-based system
leads to rapid development because when one of the sources changes,
only parts that depend on this source get recomputed. Buckheit and Donoho (1995<ref>Buckheit, J. and D. L. Donoho, 1995, Wavelab and reproducible research, ''in'' Wavelets and Statistics, volume '''103''', 55--81. Springer-Verlag.</ref>)
based their system on MATLAB, a popular integrated development
environment produced by MathWorks (Sigmon and Davis, 2001<ref>Sigmon, K. and T. A. Davis, 2001, MATLAB primer, sixth edition: Chapman & Hall.</ref>). While MATLAB is an adequate tool for prototyping numerical algorithms, it may not be
sufficient for large-scale computations typical for many applications
in computational geophysics.
"Make" is a handy utility employed by thousands of
software development projects. Unfortunately, it is not
well designed from the perspective of user experience. "Make" employs
an obscure and limited special language (a mixture of Unix shell
and special-purpose commands), which often appears confusing
to inexperienced users. According to Peter van der Linden, a software
expert from Sun Microsystems (van der Linden, 1994<ref>van der Linden, P., 1994, Expert C programming: Prentice Hall.</ref>),
<blockquote>
"Sendmail" and "make" are two well-known programs that are
pretty widely regarded as originally being debugged into existence.
That's why their command languages are so poorly thought out and
difficult to learn. It's not just you -- everyone finds them
troublesome.
</blockquote>
The inconvenience of the "make" command language is also in its limited
capabilities. The reproducible research system developed by
Schwab et al. (2000<ref>Schwab, M., M. Karrenbach, and J. Claerbout, 2000, Making scientific computations reproducible: Computing in Science & Engineering, '''2''', 61--67.</ref>) includes not only custom "make" rules but also an obscure and hardly portable agglomeration of shell and Perl scripts that extend "make" (Fomel et al., 1997<ref>Fomel, S., M. Schwab, and J. Schroeder, 1997, Empowering SEP's documents, ''in'' SEP-94, 339--361. Stanford Exploration Project.</ref>).
Several alternative systems for dependency-checking software
construction have been developed in recent years. One of the most
promising new tools is SCons, enthusiastically endorsed by
Dubois (2003<ref>Dubois, P. F., 2003, Why Johnny can't build: Computing in Science & Engineering, '''5''', 83--88.</ref>). The SCons initial design won the Software Carpentry competition sponsored by Los Alamos National Laboratory in 2000 in the category of "a dependency management tool to replace make." Some of the main advantages of SCons are:

*SCons configuration files are Python scripts. Python is a modern programming language praised for its readability, elegance, simplicity, and power (Rossum, 2000a<ref>Rossum, G. V., 2000a, Python reference manual: Iuniverse Inc.</ref>;Rossum, 2000b<ref>-------- 2000b, Python tutorial: Iuniverse Inc.</ref>). Scales and Ecke (2002<ref>Scales, J. A. and H. Ecke, 2002, What programming languages should we teach our undergraduates?: The Leading Edge, '''21''', 260--267.</ref>) recommend Python as the first programming language for geophysics students.
*SCons offers reliable, automatic, and extensible dependency analysis and creates a global view of all dependencies—no more "make depend," "make clean," or multiple build passes of touching and reordering targets to get all the dependencies.
*SCons has built-in support for many programming languages and systems, including C, C++, Fortran, Java, and LaTeX.
*While "make" relies on timestamps to detect file changes (creating numerous problems on platforms with different system clocks), SCons uses a more reliable detection mechanism, employing MD5 signatures by default. It can detect changes not only in files but also in commands used to build them.
*SCons provides integrated support for parallel builds.
*SCons provides configuration support analogous to the "autoconf" utility for testing the environment on different platforms.
*SCons is designed from the ground up as a cross-platform tool. It works equally well on POSIX systems (Linux, Mac OS X, Solaris, etc.) and Windows.
*The stability of SCons is assured by an incremental development methodology utilizing comprehensive regression tests.
*SCons is publicly released under a liberal open-source license<ref>As of this writing, SCons is in a beta version of 0.96, approaching the 1.0 official release. See http://www.scons.org/.</ref>.
In this paper, we propose to adopt SCons as a new platform for
reproducible research in scientific computing.

===Paper organization===
To demonstrate our adoption of SCons for reproducible research, we first describe a couple of simple examples of computational
experiments and then show how SCons helps us document our
computational results.


==Example experiments==

The main <tt>SConstruct</tt> commands defined in our reproducible research environment are collected in the table.

<center>
{| class="wikitable"
|+Basic methods of an <tt>rsf.proj</tt> object.
|-
|style="background-color:#ffdead;"| '''<tt>Fetch(data_file,dir[,ftp_server_info])</tt>'''
|-
| A rule to download <tt><math><</math>data_file<math>></math></tt> from a specific directory <tt><math><</math>dir<math>></math></tt> of an FTP server
|-
|style="background-color:#ffdead;"| '''<tt>Flow(target[s],source[s],command[s][,stdin][,stdout])</tt> '''
|-
| A rule to generate <tt><math><</math>target[s]<math>></math></tt> from <tt><math><</math>source[s]<math>></math></tt> using <tt><math><</math>command[s]<math>></math></tt>
|-
|style="background-color:#ffdead;"| '''<tt>Plot(intermediate_plot[,source],plot_command)</tt>''' or
'''<tt>Plot(intermediate_plot,intermediate_plots,combination)</tt>'''
|-
| A rule to generate <tt><math><</math>intermediate_plot<math>></math></tt> in the working directory.
|-
|style="background-color:#ffdead;"| '''<tt>Result(plot[,source],plot_command)</tt>''' or
'''<tt>Result(plot,intermediate_plots,combination)</tt>'''
|-
| A rule to generate a final <tt><math><</math>plot<math>></math></tt> in the special <tt>Fig</tt> folder of the working directory.
|-
|style="background-color:#ffdead;"| '''<tt>End()</tt>'''
|-
| A rule to collect default targets.
|}
</center>

These commands are defined in <tt>$PYTHONPATH/rsf/proj.py</tt> where
<tt>RSFROOT</tt> is the environmental variable to the Madagascar
installation directory. The source of this file is in
[http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/framework/rsf/proj.py framework/rsf/proj.py].

===Example 1===

To follow the first example, select a working project directory and
copy the following code
to a file named <tt>SConstruct</tt><ref>The source of this file is also accessible at [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/scons/easystart/SConstruct $RSFSRC/book/rsf/scons/easystart/SConstruct].</ref>.

<syntaxhighlight lang="python">
from rsf.proj import *

# Download the input data file
Fetch('lena.img','imgs')

# Create RSF header
Flow('lena.hdr','lena.img',
'echo n1=512 n2=513 in=$SOURCE data_format=native_uchar',
stdin=0)

# Convert to floating point and window out the first trace
Flow('lena','lena.hdr','dd type=float | window f2=1')

# Display
Result('lena',
'''
sfgrey title="Hello, World!" transp=n color=b bias=128
clip=100 screenratio=1
''')

# Wrap up
End()
</syntaxhighlight>

This is our "hello world" example that illustrates the basic use of
some of the commands presented in Table~(tbl:commands). The plan
for this experiment is to download data from a public data
server, convert it to an appropriate file format, and generate a
figure for publication. But let us look at the
<tt>SConstruct</tt> script and try to decorticate it.

<syntaxhighlight lang="python">
from rsf.proj import *
</syntaxhighlight>

is a standard Python command that loads the Madagascar project
management module <tt>rsf/proj.py</tt> which provides our extension to
SCons.

<syntaxhighlight lang="python">
Fetch('lena.img','imgs')
</syntaxhighlight>

instructs SCons to connect to a public data server (the default server
if no FTP server information is provided) and to fetch the data file
<tt>lena.img</tt> from the <tt>data/imgs</tt> directory.


Try running "<tt>scons lena.img</tt>" on the command line. The successful output should look like
<pre>
bash$ scons lena.img
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
retrieve(["lena.img"], [])
scons: done building targets.
</pre>
with the target file <tt>lena.img</tt> appearing in your directory.
In the following examples, we will use <tt>-Q</tt> (quiet) option of
<tt>scons</tt> to suppress the verbose output.
<syntaxhighlight lang="python">
Flow('lena.hdr','lena.img',
'echo n1=512 n2=513 in=$SOURCE data_format=native_uchar',
stdin=0)
</syntaxhighlight>

prepares the Madagascar header file <tt>lena.hdr</tt> using the
standard Unix command <tt>echo</tt>.

<pre>
bash$ scons -Q lena.hdr
echo n1=512 n2=513 in=lena.img data_format=native_uchar > lena.hdr
</pre>

Since <tt>echo</tt> does not take a standard input, stdin is set to 0
in the Flow command; otherwise, the first source is the standard input.
Likewise, the first target is the standard output unless otherwise
specified.

Note that
<tt>lena.img</tt> is referred as <tt>$SOURCE</tt> in the command. This
allows us to change the source file's name without changing the command.
The data format of the <tt>lena.img</tt> image file is <tt>uchar</tt>
(unsigned character), the image consists of 513 traces with 512
samples per trace. Our next step is to convert the image
representation to floating point numbers and to window out the first
trace so that the final image is 512 by 512 square. The two
transformations are conveniently combined into one with the help of a Unix pipe.
<syntaxhighlight lang="python">
Flow('lena','lena.hdr','dd type=float | window f2=1')
</syntaxhighlight>

<pre>
bash$ scons -Q lena
scons: *** Do not know how to make target `lena'. Stop.
</pre>
What happened? In the absence of the file suffix, the <tt>Flow</tt>
command assumes that the target file suffix is "<tt>.rsf</tt>". Let us try again.
<pre>
scons -Q lena.rsf
< lena.hdr /RSF/bin/sfdd type=float | /RSF/bin/sfwindow f2=1 > lena.rsf
</pre>
Notice that Madagascar modules <tt>sfdd</tt> and <tt>sfwindow</tt> get
substituted for the corresponding short names in the
<tt>SConstruct</tt> file. The file <tt>lena.rsf</tt> is in a regularly
sampled format<ref>See [[Guide to RSF file format]]</ref> and can be examined, for example, with <tt>sfin lena.rsf</tt><ref>See [[Guide_to_madagascar_programs#sfin]].</ref>.
<pre>
bash$ sfin lena.rsf
lena.rsf:
in="/datapath/lena.rsf@"
esize=4 type=float form=native
n1=512 d1=1 o1=0
n2=512 d2=1 o2=1
262144 elements 1048576 bytes
</pre>
In the last step, we will create a plot file to display the image
on the screen and for including it in the publication.

<syntaxhighlight lang="python">
Result('lena',
'''
sfgrey title="Hello, World!" transp=n color=b bias=128
clip=100 screenratio=1
''')
</syntaxhighlight>

Notice that we broke the long command string into multiple lines by
using Python's triple quote syntax. All the extra white space will be
ignored when the multiple-line string gets translated into the command
line. The <tt>Result</tt> command has special targets associated with
it. Try, for example, "<tt>scons lena.view</tt>" to observe the
figure <tt>Fig/lena.vpl</tt> generated in a specially created
<tt>Fig</tt> directory and displayed on the screen. The output should
look like this figure.

[[Image:lena.png|frame|center|The output of the first numerical experiment.]]

The reproducible script ends with

<syntaxhighlight lang="python">
End()
</syntaxhighlight>

Ready to experiment? Try some of the following:

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

{| class="wikitable"
|+SCons commands and options defined in <tt>rsfproj</tt>.
|-
|style="background-color:#ffdead;"| '''<tt>scons <math><</math>file<math>></math></tt>'''
|-
| Generate <tt><math><</math>file<math>></math></tt> (usually requires <tt>.rsf</tt> suffix for <tt>Flow</tt> targets and <tt>.vpl</tt> suffix for <tt>Plot</tt> targets.)
|-
|style="background-color:#ffdead;"| '''<tt>scons</tt>'''
|-
| Generate default targets (usually figures specified in <tt>Result</tt>.)
|-
|style="background-color:#ffdead;"| '''<tt>scons view</tt>''' or '''<tt>scons <math><</math>result<math>></math>.view</tt> '''
|-
| Generate <tt>Result</tt> figures and display them on the screen.
|-
|style="background-color:#ffdead;"| '''<tt>scons print</tt>''' or '''<tt>scons <math><</math>result<math>></math>.print</tt>'''
|-
| Generate <tt>Result</tt> figures and print them.
|-
|style="background-color:#ffdead;"| '''<tt>scons lock</tt>''' or '''<tt>scons <math><</math>result<math>></math>.lock</tt> '''
|-
| Generate <tt>Result</tt> figures and install them in a separate location.
|-
|style="background-color:#ffdead;"| '''<tt>scons test</tt>''' or '''<tt>scons <math><</math>result<math>></math>.test</tt>'''
|-
| Generate <tt>Result</tt> figures and compare them with the corresponding "locked" figures stored in a separate location (regression testing).
|-
|style="background-color:#ffdead;"| '''<tt>scons <math><</math>result<math>></math>.flip</tt>'''
|-
| Generate the <tt><math><</math>result<math>></math></tt> figure and compare it with the corresponding "locked" figure stored in a separate location by flipping between the two figures on the screen.
|-
|style="background-color:#ffdead;"| '''<tt>scons TIMER=y ...</tt> '''
|-
| Time the execution of each step in the processing flow (using the Unix <tt>time</tt> utility.)
|-
|style="background-color:#ffdead;"| '''<tt>scons CHECKPAR=y ...</tt> '''
|-
| Check the names and values of all parameters supplied to Madagascar modules in the processing flow before executing anything (guards against incorrect input.) This option is new and experimental.
|}

===Example 2===

The plan for this experiment is to add random noise to the test
"Lena" image and then attempt removing it by low-pass filtering
and hard thresholding of coefficients in the Fourier domain. The
resultant images are shown in the figures.

[[Image:panel1.png|frame|center|Top left: original image. Top right: random noise added. Bottom left: original image spectrum in the Fourier (<math>F</math>-<math>X</math>) domain. Bottom right: noisy image spectrum in the Fourier (<math>F</math>-<math>X</math>) domain.]]

[[Image:panel2.png|frame|center|Left: denoising by low-pass filtering. Right: denoising by hard thresholding in the Fourier domain.]]

Since the <tt>SConstruct|</tt> file is a Python script, we can also use all the
flexibility and power of the Python language in our Madagascar
reproducible scripts. A demo script is available in the
<tt>rsf/scons/rsfpy</tt> subdirectory of the Madagascar <tt>book</tt>
directory. Rather than commenting on it line-by-line, we select some
parts of interest.
In the <tt>SConstruct</tt> script, we can declare
Python variables
<syntaxhighlight lang="python">
bias = 128
</syntaxhighlight>

and use them later, for example, to define our customized plot
command as a Python function
<syntaxhighlight lang="python">
def grey(title,transp='n',bias=bias):
return '''
sfgrey title="%s" transp=%s bias=%g clip=100
screenht=10 screenwd=10 crowd2=0.85 crowd1=0.8
label1= label2=
''' % (title,transp,bias)
</syntaxhighlight>

This Python function, named <tt>grey()</tt>, can then be called in Plot or Result
commands, e.g.
<syntaxhighlight lang="python">
Plot('lplena',grey('Noisy Lena LP filtered'))
</syntaxhighlight>

We can define a Python dictionary, e.g.
<syntaxhighlight lang="python">
titles = {'lena':'Lena',
'nlena':'Noisy Lena'}
</syntaxhighlight>
and loop over its entries, e.g.
<syntaxhighlight lang="python">
for name in titles.keys():
Plot(name,grey(titles[name]) )
cftitle = titles[name]+' in FX domain'
Flow('fx'+name,name,'sfspectra')
Plot('fx'+name,grey(cftitle,'y',100))
</syntaxhighlight>
Note that the title of the plots is obtained by concatenating Python
strings.
Python strings can also be used to define sequences of commands used
in several Flows, e.g.
<syntaxhighlight lang="python">
# 2-D FFT
fft2 = 'sffft1 sym=y | sffft3 sym=y'
Flow('fnlena','nlena',fft2)
</syntaxhighlight>

Finally, in our Madagascar reproducible script, we may want the option
to pass command line arguments when running SCons or use default
values otherwise, e.g.
<syntaxhighlight lang="python">
# denoising using thresholding in the Fourier domain
fthr = float(ARGUMENTS.get('fthr', 70))
Flow('fthrlena','fnlena','sfthr thr=%f mode="hard"' % fthr)
</syntaxhighlight>

Running <tt>scons</tt> only, the default value set for fthr (i.e. 70)
is used whereas running <tt>scons fthr=68</tt> set fthr to a command
line specified value.
This is by no means an exhaustive list of options, but hopefully, it
will give you a flavor of the powerful tool you have in your hands. Enjoy!


==Creating reproducible documentation==

You are done with computational experiments and want to communicate
them in a paper. SCons helps us create high-quality papers where
computational results (figures) are integrated with papers written in
LATEX\.
The corresponding SCons extension is defined in <tt>$PYTHONPATH/rsf/tex.py</tt> where
<tt>RSFROOT</tt> is the environmental variable to the Madagascar
installation directory. The source of this file is in
[http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/framework/rsf/tex.py framework/rsf/tex.py].
We summarize the basic methods and commands in the tables.

{| class="wikitable"
|+Basic methods of an <tt>rsf.tex</tt> object.
|-
|style="background-color:#ffdead;"| '''<tt>Paper(paper_name,[,lclass][,use][,include][,options])</tt>'''
|-
| A rule to compile <tt><math><</math>paper_name<math>></math>.tex</tt> LATEX\ document using the LATEX2e class specified in <tt>lclass</tt> (default is <tt>geophysics.cls</tt> from the [[SEGTeX]] package) with additional options specified in <tt>options</tt>, additional packages specified in <tt>use</tt>, and additional preamble specified in <tt>include</tt>.
|-
|style="background-color:#ffdead;"| '''<tt>End()</tt> '''
|-
| A rule to collect default targets (referring to <tt>paper.tex</tt> document).
|}

{| class="wikitable"
|+SCons commands defined in <tt>rsftex</tt>.
|-
|style="background-color:#ffdead;"| '''<tt>scons</tt>'''
|-
| Generate the default target (usually the PDF file <tt>paper.pdf</tt> from the source LATEX file <tt>paper.tex</tt>.)
|-
|style="background-color:#ffdead;"| '''<tt>scons pdf</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.pdf</tt> '''
|-
| Generate PDF files from LATEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt>.
|-
|style="background-color:#ffdead;"| '''<tt>scons read</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.read</tt> '''
|-
| Generate PDF files from LATEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> and display them on the screen.
|-
|style="background-color:#ffdead;"| '''<tt>scons print</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.print</tt> '''
|-
| Generate PDF files from LATEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> and print them.
|-
|style="background-color:#ffdead;"| '''<tt>scons html</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.html</tt> '''
|-
| Generate HTML files from LATEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> using LATEXtoHTML. The directory <tt><math><</math>paper_name<math>></math>_html</tt> gets created.
|-
|style="background-color:#ffdead;"| '''<tt>scons install</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.install</tt> '''
|-
| Generate PDF and HTML files from LATEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> and install them in a separate location (used for publishing on a web site).
|-
|style="background-color:#ffdead;"| '''<tt>scons wiki</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.wiki</tt> '''
|-
| Convert LATEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> to the <tt>MediaWiki</tt> format (used for publishing on a Wiki web site).
|}



===Example===

This paper by itself is an example of a reproducible document. It is
generated using the following <tt>SConstruct</tt> file which is place
in the directory above the projects directories.

<syntaxhighlight lang="python">
from rsf.tex import *
Paper('velan',use='hyperref,listings,color')
End(use='hyperref,listings,color')
</syntaxhighlight>

This <tt>SConstruct</tt> generates this paper, but it can also compile
<tt>velan.tex</tt> in the same directory. Note that there is no
<tt>Paper</tt> command for <tt>paper.tex</tt> since it is the default
documentation name. Optional LATEX packages and style used in
<tt>paper.tex</tt> are passed in the End command.

Let's now take a closer look at <tt>paper.tex</tt> to understand how
the figures of the documentation are linked to the reproducible
scripts that created them. First of all, note that <tt>paper.tex</tt>
is not a regular LATEX document but only its body (no
<math>\backslash</math>documentclass, <math>\backslash</math>usepackage, etc.). In our
paper, the first figure was created in the project folder
<tt>easystart</tt> (sub-folder of our documentation folder) by the
resulting plot <tt>lena.vpl</tt>. In the LATEX source code, it
translates as

<syntaxhighlight lang="latex">
\inputdir{easystart}
\sideplot{lena}{height=.25\textheight}{The output of the first numerical experiment.}
</syntaxhighlight>

The <math>\backslash</math>inputdir command points to the project directory and
the <math>\backslash</math>sideplot command calls <tt><math><</math>result_name<math>></math></tt>. The
LATEX tag of the figure is <tt>fig:<math><</math>result_name<math>></math></tt>. The
first time the paper is compiled, the result file is automatically
converted to PDF format.



==References==
<references/>

Guide to RSF file format

2024-11-20T19:58:19Z

Fomels: typos

<center>''This page was created from the LaTeX source in [https://github.com/ahay/src/blob/master/book/rsf/rsf/format.tex book/rsf/rsf/format.tex] using [[latex2wiki]]''</center>

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

==Principles==
The main design principle behind the RSF data format is [http://en.wikipedia.org/wiki/KISS_principle KISS] ("Keep It
Short and Simple"). The RSF format is borrowed from the SEPlib data format
initially designed at the Stanford Exploration Project
(Claerbout, 1991<ref>Claerbout, J. F., 1991, Introduction to Seplib and SEP utility software, ''in'' SEP-70, 413--436. Stanford Exploration Project.</ref>). The format is made as simple as possible for maximum convenience, transparency, and flexibility.
According to the Unix tradition, standard file formats should be in a readable
textual form to be easily examined and processed with universal
tools. Raymond (2004<ref>Raymond, E. S., 2004, The art of UNIX programming: Addison-Wesley.</ref>) writes:
<blockquote>
To design a perfect anti-Unix, make all file formats binary and opaque and
require heavyweight tools to read and edit them.
</blockquote>
<blockquote>
If you feel an urge to design a complex binary file format or a complex
binary application protocol, it is generally wise to lie down until the
feeling passes.
</blockquote>
Storing large-scale datasets in a text format may not be economical. RSF
chooses the next best thing: it allows data values to be stored in a binary
format but puts all data attributes in text files that humans can read
and processed with universal text-processing utilities.
===Example===
Let us first create some synthetic RSF data.
<pre>
bash$ sfmath n1=1000 output='sin(0.5*x1)' > sin.rsf
</pre>
Open and read the file <tt>sin.rsf</tt>.
<pre>
bash$ cat sin.rsf
sfmath rsf/rsf/rsftour: fomels@egl Sun Jul 31 07:18:48 2005

o1=0
data_format="native_float"
esize=4
in="/tmp/sin.rsf@"
x1=0
d1=1
n1=1000
</pre>
The file contains nine lines with simple, readable text. The first line
shows the name of the program, the working directory, the user, and
computer that created the file and the time it was created (that
information is recorded for accounting purposes). Other lines contain
parameter-value pairs separated by the "=" sign. The "in"
parameter points to the location of the binary data. Before we discuss the meaning of parameters in more detail, let us plot the data.
<pre>
bash$ < sin.rsf sfwiggle title='One Trace' | sfpen
</pre>
You should see a plot similar to the figure below on your screen.
[[Image:sin1.png|frame|center|An example sinusoid plot.]]
Suppose you want to reformat the data so that instead of one trace of a thousand samples, it contains twenty traces with fifty samples each. Try
running
<pre>
bash$ < sin.rsf sed 's/n1=1000/n1=50 n2=20/' > sin10.rsf
bash$ < sin10.rsf sfwiggle title=Traces | sfpen
</pre>
or (using pipes)
<pre>
bash$ < sin.rsf sed 's/n1=1000/n1=50 n2=20/' | sfwiggle title=Traces | sfpen
</pre>
On your screen, you should see a plot similar to the figure below:
[[Image:sin2.png|frame|center|An example sinusoid plot, with data reformatted to twenty traces.]]
What happened? We used <tt>sed</tt>, a standard Unix line editing utility, to
change the parameters describing the data dimensions. Because of the
simplicity of this operation, there is no need to create specialized data
formatting tools or to make the <tt>sfwiggle</tt> program accept additional
formatting parameters. Other general-purpose Unix tools that can be applied on
RSF files include <tt>cat</tt>, <tt>echo</tt>, <tt>grep</tt>, etc.
An alternative way to obtain the previous result is to run
<pre>
bash$ ( cat sin.rsf; echo n1=50 n2=20 ) > sin10.rsf
bash$ < sin10.rsf sfwiggle title=Traces | sfpen
</pre>
In this case, the <tt>cat</tt> utility copies the contents of the
previous file, and the <tt>echo</tt> utility appends a new line "<tt>n1=50
n2=20</tt>". A new value of the <tt>n1</tt> parameter overwrites the old value
of <tt>n1=1000</tt>, and we achieve the same result as before.
Of course, one could also edit the file by hand with one of the general-purpose text editors. For recording the history of data processing, it is
usually preferable to be able to process files with non-interactive tools.

==Header and Data files==
A simple way to check the layout of an RSF file is with the <tt>sfin</tt>
program.
<pre>
bash$ sfin sin10.rsf
sin10.rsf:
in="/tmp/sin.rsf@"
esize=4 type=float form=native
n1=50 d1=1 o1=0
n2=20 d2=? o2=?
1000 elements 4000 bytes
</pre>
The program reports the following information: the location of the data file
(<tt>/tmp/sin.rsf\@</tt>), the element size (4 bytes), the element
type (floating point), the element form (native), the hypercube dimensions
(<math>50 \times 20</math>), axis scaling (1 and unspecified), and axis origin (0 and
unspecified). It also checks the total number of elements and bytes in the
data file.
Let us examine this information in detail. First, we can verify that the data
file exists and contains the specified number of bytes:
<pre>
bash$ ls -l /tmp/sin.rsf@
-rw-r--r-- 1 sergey users 4000 2004-10-04 00:35 /tmp/sin.rsf@
</pre>
4000 bytes in this file are required to store <math>50 \times 20</math> floating-point
4-byte numbers in a binary form. Thus, the data file contains only the
raw data in a contiguous binary form.
===Datapath===
How did the RSF program (<tt>sfmath</tt>) decide where to put the data file?
In the order of priority, the rules for selecting the data file name and the
data file directory are as follows:

#Check <tt>--out=</tt> parameter on the command line. The parameter specifies the output data file location explicitly.
#Specify the path and the file name separately.
#*The rules for the path selection are:
#*#Check <tt>datapath=</tt> parameter on the command line. The parameter specifies a string to prepend to the file name. The string may contain the file directory.
#*#Check <tt>DATAPATH</tt> environmental variable. It has the same meaning as the parameter specified with <tt>datapath=</tt>.
#*#Check for <tt>.datapath</tt> file in the current directory. The file may contain a line <pre> datapath=/path/to_file/ </pre> or <pre> machine_name datapath=/path/to_file/ </pre> if you intend to use different paths on different platforms.
#*#Check for <tt>.datapath</tt> file in the user's home directory.
#*#Put the data file in the current directory (similar to <tt>datapath=./</tt>).
#*:
#*The rules for the filename selection are:
#*#If the output RSF file is in the current directory, the name of the data file is made by appending \@.
#*#If the output file is not in the current directory or is created temporarily by a program, the name is made by appending random characters to the program's name and selected to be unique.

Examples:

<pre>
bash$ sfspike n1=10 --out=test1 > spike.rsf
bash$ grep in spike.rsf
in="test1"
</pre>

<pre>
bash$ sfspike n1=10 datapath=/tmp/ > spike.rsf
bash$ grep in spike.rsf
in="/tmp/spike.rsf@"
</pre>

<pre>
bash$ DATAPATH=/tmp/ sfspike n1=10 > spike.rsf
bash$ grep in spike.rsf
in="/tmp/spike.rsf@"
</pre>

<pre>
bash$ sfspike n1=10 datapath=/tmp/ > /tmp/spike.rsf
bash$ grep in /tmp/spike.rsf
in="/tmp/sfspikejcARVf"
</pre>

====Packing header and data together====
While the header and data files are separated by default, it is also possible
to pack them together into one file. To do that, specify the program's
"<tt>--out</tt>" parameter as <tt>--out=stdout</tt>. Example:
<pre>
bash$ sfspike n1=10 --out=stdout > spike.rsf
bash$ grep in spike.rsf
Binary file spike.rsf matches
bash$ sfin spike.rsf
spike.rsf:
in="stdin"
esize=4 type=float form=native
n1=10 d1=0.004 o1=0 label1="Time" unit1="s"
10 elements 40 bytes
bash$ ls -l spike.rsf
-rw-r--r-- 1 sergey users 196 2004-11-10 21:39 spike.rsf
</pre>
If you examine the contents of <tt>spike.rsf</tt>, you will find that it
starts with the text header information, followed by special
symbols, followed by binary data.
Packing headers and data together may not be a good idea for data processing, but it works well for storing data: it is easier to move the packed file
around than to move two different files (header and binary) together while
remembering to preserve their connection. Packing the header and data together is also the current mechanism used to push RSF files through Unix pipes.

===Type===
The data stored with RSF can have different types: character, unsigned
character, integer, floating point, or complex. By default, single precision
is used for numbers (<tt>int</tt> and <tt>float</tt> data types in the C
programming language), but double precision and other
integer types (<tt>short</tt> and <tt>long</tt>) are also
supported. The number of bytes required to represent these
numbers may depend on the platform.
===Form===
The data stored with RSF can also be in different forms: ASCII, native
binary, and XDR binary. Native binary is often used by default. It is the
binary format employed by the machine running the application. On
Linux-running PC, the native binary format will typically correspond to the
so-called little-endian byte ordering. On some other platforms, it might be
big-endian ordering. XDR is a binary format designed by Sun for exchanging
files over the network. It typically corresponds to big-endian byte ordering. It
is more efficient to process RSF files in the native binary format, but storing the corresponding file in an XDR format might be a good idea if you intend to access data from different platforms. RSF also allows for an ASCII
(plain text) form of data files.
Conversion between different types and forms is accomplished with
<tt>sfdd</tt> program. Here are some examples. First, let us create synthetic data.
<pre>
bash$ sfmath n1=10 output='10*sin(0.5*x1)' > sin.rsf
bash$ sfin sin.rsf
sin.rsf:
in="/tmp/sin.rsf@"
esize=4 type=float form=native
n1=10 d1=1 o1=0
10 elements 40 bytes
bash$ < sin.rsf sfdisfil
0: 0 4.794 8.415 9.975 9.093
5: 5.985 1.411 -3.508 -7.568 -9.775
</pre>
Converting the data to the integer type:
<pre>
bash$ < sin.rsf sfdd type=int > isin.rsf
bash$ sfin isin.rsf
isin.rsf:
in="/tmp/isin.rsf@"
esize=4 type=int form=native
n1=10 d1=1 o1=0
10 elements 40 bytes
bash$ < isin.rsf sfdisfil
0: 0 4 8 9 9 5 1 -3 -7 -9
</pre>
Converting the data to the ASCII form:
<pre>
bash$ < sin.rsf sfdd form=ascii > asin.rsf
bash$ < asin.rsf sfdisfil
0: 0 4.794 8.415 9.975 9.093
5: 5.985 1.411 -3.508 -7.568 -9.775
bash$ sfin asin.rsf
asin.rsf:
in="/tmp/asin.rsf@"
esize=0 type=float form=ascii
n1=10 d1=1 o1=0
10 elements
bash$ cat /tmp/asin.rsf@
0 4.79426 8.41471 9.97495 9.09297 5.98472 1.4112 -3.50783
-7.56803 -9.7753
</pre>

===Hypercube===
While RSF stores binary data in a contiguous 1-D array, the conceptual
data model is a multidimensional hypercube. By convention, the
dimensions of the cube are defined with parameters <tt>n1</tt>,
<tt>n2</tt>, <tt>n3</tt>, etc. The fastest axis is <tt>n1</tt>.
Additionally, the grid sampling can be given by parameters
<tt>d1</tt>, <tt>d2</tt>, <tt>d3</tt>, etc. The axes origins are given
by parameters <tt>o1</tt>, <tt>o2</tt>, <tt>o3</tt>, etc. Optionally,
you can also supply the axis label strings: <tt>label1</tt>,
<tt>label2</tt>, <tt>label3</tt>, etc., and axis units strings:
<tt>unit1</tt>, <tt>unit2</tt>, <tt>unit3</tt>, etc.
==Compatibility with other file formats==
It is possible to exchange RSF-formatted data with several other popular data formats.
===Compatibility with SEPlib===
RSF is mostly compatible with its predecessor, the SEPlib file format.
However, there are several significant differences:

#SEPlib programs typically use the element size (<tt>esize=</tt> parameter) to distinguish between different data types: <tt>esize=4</tt> corresponds to floating point data, while <tt>esize=8</tt> corresponds to complex data. The RSF type handling mechanism is different: data types are determined from the value of the <tt>data_format</tt> parameter. Madagascar computational programs typically output files with <tt>data_format="native_float"</tt> or <tt>native_complex</tt>.
#The default data form in SEPlib programs is typically XDR and not native as it is in RSF. Thus, to make a dataset created with SEPlib readable by Madagascar programs, you would typically need to add to the history file <tt>data_format="xdr_float"</tt> or <tt>data_format="xdr_complex"</tt> . <ref group="note">For SEPlib 6.5.3 and older: Note that xdr_complex is not a valid SEPlib value, so for datasets of complex numbers encoded as pairs of floats, a dataset cannot be at the same time valid in both SEPlib and Madagascar. A valid SEPlib dataset will have esize=8 and data_format="xdr_float", but sfin will show it as having "200% of expected" data. Adding data_format="xdr_complex" to such a dataset will make sfin work as expected, but SEPlib's In or In3d will give a segmentation fault because of an unknown data type. To patch SEPlib to accept <tt>native_complex</tt> and <tt>xdr_complex</tt> data, the following changes must be made:
* In <tt>$SEPSRC/seplib_base/lib/corelibs/sep/strformats.c</tt>:
** Add "xdr_complex" and "native_complex" to the str_fmt_names structure
** Set FMT_LENGTH to 15
* In <tt>$SEPSRC/seplib_base/lib/corelibs/include/strformats.h</tt>:
** Add preprocessor directives to define FMT_XDR_COMPLEX as 8 and FMT_NATIVE_COMPLEX as 9
** Set NUM_FMT to 10
</ref>
#It is possible to pipe the output of Madagascar programs to SEPlib: <pre>bash$ sfspike n1=1 | Attr want=min</pre> (output should be: <tt>minimum value = 1 at 1</tt>). However, piping the output of SEPlib programs to RSF (or, for that matter, any other non-SEPlib programs) will result in an unterminated process. For example, the command <pre> bash$ Spike n1=1 | sfattr want=min </pre> will hang. This is because SEPlib uses sockets for piping and expects a socket connection from the receiving program, while Madagascar passes data through regular Unix pipes.
#SEP3D is an extension of SEPlib for operating with irregularly sampled data (Biondi et al., 1996<ref>Biondi, B., R. Clapp, and S. Crawley, 1996, SEPlib90: SEPlib for 3-D prestack data, ''in'' SEP-92, 343--364. Stanford Exploration Project.</ref>). There is no equivalent of it in RSF for the reasons explained at the beginning of this guide. Operations with irregular datasets are supported using auxiliary input files representing the geometry information.

;Notes
<references group="note" />

===Reading and writing SEG-Y and SU files===
The SEG-Y format is based on the proposal of Barry et al. (1975<ref>[http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev0.pdf Barry, K. M., D. A. Cavers, and C. W. Kneale, 1975, Report on recommended standards for digital tape formats: Geophysics, '''40''', 344--352]</ref>).
It was revised in 2002<ref>See http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev1.pdf</ref>. The
SU format is a modification of SEG-Y used in Seismic Unix
(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>).
To convert files from SEG-Y or SU format to RSF, use the <tt>sfsegyread</tt>
program. Let us first manufacture an example file using SU utilities
(Stockwell, 1999<ref>-------- 1999, The CWP/SU: Seismic Un*x package: Computers and Geosciences, '''25''', 415--419.</ref>):
<pre>
bash$ suplane > plane.su
bash$ segyhdrs < plane.su | segywrite tape=plane.segy
</pre>
To convert it to RSF, use either
<pre>
bash$ sfsuread < plane.su tfile=tfile.rsf endian=0 > plane.rsf
</pre>
or
<pre>
bash$ sfsegyread < plane.segy tfile=tfile.rsf \
hfile=file.asc bfile=file.bin > plane.rsf
</pre>
The endian flag is needed if the SU file originated from a little-endian machine like a Linux PC.
Several files are generated. The standard output contains an RSF file with the
data (32 traces with 64 samples each):
<pre>
bash$ sfin plane.rsf
plane.rsf:
in="/tmp/plane.rsf@"
esize=4 type=float form=native
n1=64 d1=0.004 o1=0
n2=32 d2=? o2=?
2048 elements 8192 bytes
</pre>
The contents of this file are displayed in the figure.
[[Image:plane.png|frame|center|The output of suplane, converted to RSF and
displayed with <tt>sfwiggle</tt>.]]
The <tt>tfile</tt> is an RSF integer-type file with the trace headers (32
headers with 71 traces each):
<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>
The contents of trace headers can be quickly examined with the
<tt>sfheaderattr</tt> program.
The <tt>file.asc</tt> is the ASCII header file for the whole record.
<pre>
bash$ head -c 242 file.asc
C This tape was made at the
C
C Center for Wave Phenomena
</pre>
The <tt>file.bin</tt> is the binary header file.

To convert files back from RSF to SEG-Y or SU, use the <tt>sfsegywrite</tt>
program and reverse the input and output:
<pre>
bash$ sfsuwrite > plane.su tfile=tfile.rsf endian=0 < plane.rsf
</pre>
or
<pre>
bash$ sfsegywrite > plane.segy tfile=tfile.rsf \
hfile=file.asc bfile=file.bin < plane.rsf
</pre>

If <tt>hfile=</tt> and <tt>bfile=</tt> are not supplied to <tt>sfsegywrite</tt>, the corresponding headers will be generated on the fly. The trace header file can be generated with <tt>sfsegyheader</tt>. Here is an example:
<pre>
bash$ sfheadermath < plane.rsf output=N+1 | sfdd type=int > tracl.rsf
bash$ sfsegyheader < plane.rsf tracl=tracl.rsf > tfile.rsf
bash$ sfsegywrite < plane.rsf tfile=tfile.rsf > plane.segy
</pre>

====Unusual trace header keys====
Sometimes, SEG-Y files deviate from the standard by creating additional
trace header keys. If, for example, you find out that the SEG-Y file
contains an additional trace header key stored in bytes 225-226, you can either remap one of the standard two-byte keys
<pre>
bash$ sfsegyread < file.segy tfile=tfile.rsf gut=224 > file.rsf
</pre>
or create a new key
<pre>
bash$ sfsegyread < file.segy tfile=tfile.rsf \
key1=mykey key1_len=2 mykey=224 > file.rsf
</pre>
Any number of additional keys can be created this way.

===Reading and writing ASCII files===
Reading and writing ASCII files can be accomplished with the <tt>sfdd</tt>
program. For example, let us take an ASCII file with numbers
<pre>
bash$ cat file.asc
1.0 1.5 3.0
4.8 9.1 7.3
</pre>
Converting it to RSF is as simple as
<pre>
bash$ echo in=file.asc n1=3 n2=2 data_format=ascii_float > file.rsf
bash$ sfin file.rsf
file.rsf:
in="file.asc"
esize=0 type=float form=ascii
n1=3 d1=? o1=?
n2=2 d2=? o2=?
6 elements
</pre>
For more efficient input/output operations, it might be advantageous to
convert the data type to native binary, as follows:
<pre>
bash$ echo in=file.asc n1=3 n2=2 data_format=ascii_float | \
sfdd form=native > file.rsf
bash$ sfin file.rsf
file.rsf:
in="/tmp/file.rsf@"
esize=4 type=float form=native
n1=3 d1=? o1=?
n2=2 d2=? o2=?
6 elements 24 bytes
</pre>
Converting from RSF to ASCII is equally simple:
<pre>
bash$ sfdd form=ascii --out=file.asc < file.rsf > /dev/null
bash$ cat file.asc
1 1.5 3 4.8 9.1 7.3
</pre>
You can use the <tt>line=</tt> and <tt>format=</tt> parameters in
<tt>sfdd</tt> to control the ASCII formatting:
<pre>
bash$ sfdd form=ascii --out=file.asc \
line=3 format="%3.1f " < file.rsf > /dev/null
bash$ cat file.asc
1.0 1.5 3.0
4.8 9.1 7.3
</pre>
An alternative is to use <tt>sfdisfil</tt>.
<pre>
bash$ sfdisfil > file.asc col=3 format="%3.1f " number=n < file.rsf
bash$ cat file.asc
1.0 1.5 3.0
4.8 9.1 7.3
</pre>

===Reading and writing CSV files===
CSV (Comma-separated values) is a particular example of an ASCII
format, where commas separate values on different rows or
other symbols. To convert from CSV to RSF, you can use the
<tt>sfcsv2rsf</tt> utility.
For example, let us take an ASCII file with numbers separated by commas
<pre>
bash$ cat file.csv
1.0,1.5,3.0
4.8,9.1,7.3
</pre>
Converting it to RSF:
<pre>
bash$ sfcsv2rsf < file.csv > file.rsf
bash$ sfin file.rsf
file.rsf:
in="/tmp/file.rsf@"
esize=4 type=float form=native
n1=3 d1=1 o1=0 label1="unknown" unit1="unknown"
n2=2 d2=1 o2=0 label2="unknown" unit2="unknown"
6 elements 24 bytes
</pre>
To convert from RSF to CSV, we can use formatting parameters in <tt>sfdd</tt>:
<pre>
bash$ sfdd form=ascii --out=file.csv \
line=3 strip=1 format="%3.1f," < file.rsf >/dev/null
bash$ cat file.csv
1.0,1.5,3.0
4.8,9.1,7.3
</pre>
Some CSV files contain headers with definitions for different columns.
<pre>
bash$ cat file.csv
height,width,weight
1.0,1.5,3.0
4.8,9.1,7.3
</pre>
To read a file like that, use <tt>header=</tt> parameter in <tt>sfcsv2rsf</tt>, as follows:
<pre>
bash$ sfcsv2rsf < file.csv header=y > file.rsf
</pre>
After that, different columns can be accessed by keywords.
<pre>
bash$ < file.rsf sfheaderattr segy=n
3 headers, 2 traces
*******************************************************************************
key min max mean
-------------------------------------------------------------------------------
height 0 1 @ 0 4.8 @ 1 2.9
width 1 1.5 @ 0 9.1 @ 1 5.3
weight 2 3 @ 0 7.3 @ 1 5.15
*******************************************************************************
</pre>

===Reading LAS files===
LAS (Log ASCII Standard) is a text format used for storing
well-logging data (Heslop et al., 1999<ref>Heslop, K., J. Karst, S. Prensky, D. Schmitt, et al., 1999, Log ASCII standard LAS version 3.0: The Log Analyst, 40.</ref>). LAS files can be converted to the RSF format using
<tt>sflas2rsf</tt> utility.
Let us try an example file from one of the SEG tutorials:
<pre>
bash$ tutorials=https://raw.githubusercontent.com/seg/tutorials-2014/master
bash$ wget $tutorials/1406_Make_a_synthetic/L-30.las
</pre>
Converting to RSF, we can detect 15 different logs:
<pre>
bash$ sflas2rsf L-30.las L-30.rsf
(base) sergey@DESKTOP-80QRDA0:~/all/fomels/nnint$ sfin L-30.rsf
L-30.rsf:
in="/home/sergey/RSFROOT/data/L-30.rsf@"
esize=4 type=float form=native
n1=15 d1=? o1=?
n2=25621 d2=0.5 o2=1140
384315 elements 1537260 bytes
</pre>
Individual logs are accessible by their keys and can be used in programs like <tt>sfheadermath</tt>.
<pre>
bash$ < L-30.rsf sfheaderattr segy=n desc=y
15 headers, 25621 traces
*******************************************************************************
key min max mean
-------------------------------------------------------------------------------
DEPTH 0 1140 @ 0 13950 @ 25620 7545
[Depth]
CALD 1 -999 @ 0 19.811 @ 3909 -140.356
[Caliper Caliper - Density]
CALS 2 -999 @ 0 14.84 @ 23096 7.43849
[Caliper Caliper - Sonic]
DEPT 3 1140 @ 0 13950 @ 25620 7545
[Depth]
DRHO 4 -999 @ 0 0.254 @ 23667 -149.67
[Drho Delta Rho]
DT 5 -999 @ 0 199.263 @ 1462 90.0167
[Sonic Delta-T]
GRD 6 -999 @ 0 178.416 @ 21788 -100.952
[GammaRay Gamma Ray - Density]
GRS 7 -999 @ 0 140.148 @ 23376 53.8002
[GammaRay Gamma Ray - Sonic]
ILD 8 -999 @ 0 2022.95 @ 20 34.5917
[DeepRes Deep Induction Standard Processed Resistivity]
ILM 9 -999 @ 0 2196.26 @ 20661 40.5595
[MedRes Medium Induction Standard Processed Resistivity]
LL8 10 -999 @ 0 2097.76 @ 20213 35.6343
[ShalRes Latero-Log 8]
NPHILS 11 -999 @ 0 0.45 @ 23039 -776.522
[Neutron Neutron Porosity - Ls Mtx]
NPHISS 12 -999 @ 0 0.615 @ 5215 -373.244
[Neutron Neutron Porosity - Ss Mtx]
RHOB 13 -999 @ 0 2.811 @ 23941 -147.773
[Density Bulk Density]
SP 14 -999 @ 0 -19.065 @ 20570 -105.029
[SP Spontaneous Potential]
*******************************************************************************
bash$ < L-30.rsf sfheadermath output=RHOB segy=n > RHOB.rsf
bash$ < RHOB.rsf sfwindow min2=4000 max2=13000 | sfgraph title=Density
</pre>

[[Image:rhob.png|frame|center|Density log.]]

==Other documentation==
This note should give you a general understanding of the RSF file format. See the [[RSF Comprehensive Description]] if you want minutia. Other relevant documentation is:

*[[Why Madagascar]]
*[[Installation|Installation instructions]]
*[https://ahay.org/RSF/ Madagascar self-documentation]
*[[Guide to madagascar programs]]
*[[Guide to madagascar API|Guide to the Madagascar programming interface]]
*[[Guide to programming with madagascar]]
*[[Revisiting SEP tour with Madagascar and SCons]]
*[[Reproducible computational experiments using SCons]]

==About this document==
This page was created from the LaTeX source in [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/book/rsf/rsf/format.tex?view=markup book/rsf/rsf/format.tex] using [[latex2wiki]].

==References==
<references/>

Programs of the Month

2024-11-20T18:53:37Z

Fomels: https

Randomly-selected Madagascar programs get featured every month on the [https://ahay.org/blog/ Madagascar blog]. This page provides a summary list with links.

==2019==

{| class="wikitable" style="border:1px"
| August
| [https://ahay.org/blog/2019/08/10/program-of-the-month-sfsnr2/ sfsnr2]
| Compute signal-noise-ratio.
|-
| July
| [https://ahay.org/blog/2019/07/09/program-of-the-month-sflpf/ sflpf]
| Local prediction filter (n-dimensional).
|-
| June
| [https://ahay.org/blog/2019/06/12/program-of-the-month-sfslice/ sfslice]
| Extract a slice using picked surface.
|-
| May
| [https://ahay.org/blog/2019/05/06/program-of-the-month-sfzomig3/ sfzomig3]
| 3-D zero-offset modeling/migration with extended SSF.
|}

==2017==

{| class="wikitable" style="border:1px"
| April
| [https://ahay.org/blog/2017/04/19/program-of-the-month-sfseislet/ sfseislet]
| Seislet transform.
|}

==2016==

{| class="wikitable" style="border:1px"
| March
| [https://ahay.org/blog/2016/03/23/program-of-the-month-sflinear/ sflinear]
| 1-D linear interpolation.
|-
| February
| [https://ahay.org/blog/2016/02/18/program-of-the-month-sfmig2/ sfmig2]
| 2-D prestack Kirchhoff time migration with antialiasing.
|-
| January
| [https://ahay.org/blog/2016/01/16/program-of-the-month-sfsort/ sfsort]
| Sort a float/complex vector by absolute values.
|}

==2015==

{| class="wikitable" style="border:1px"
| December
| [https://ahay.org/blog/2015/12/22/program-of-the-month-sfdivn/ sfdivn]
| Smooth division.
|-
| November
| [https://ahay.org/blog/2015/11/16/program-of-the-month-sfpldb-and-sfplas/ sfpldb and sfplas]
| Convert Vplot to ASCII; convert ASCII to Vplot
|-
| October
| [https://ahay.org/blog/2015/10/15/program-of-the-month-sfisolr2/ sfisolr2]
| Lowrank decomposition for 2-D isotropic wave propagation.
|-
| September
| [https://ahay.org/blog/2015/09/14/program-of-the-month-sfsimilarity/ sfsimilarity]
| Local similarity measure between two datasets.
|-
| July
| [https://ahay.org/blog/2015/07/10/program-of-the-month-sfmutter/ sfmutter]
| Muting.
|-
| June
| [https://ahay.org/blog/2015/06/10/program-of-the-month-sfintbin/ sfintbin]
| Data binning by trace sorting.
|-
| May
| [https://ahay.org/blog/2015/05/01/program-of-the-month-sfbox/ sfbox]
| Draw a balloon-style label.
|-
| April
| [https://ahay.org/blog/2015/04/21/program-of-the-month-sfslant/ sfslant]
| Time-space-domain Radon transform (slant stack).
|-
| March
| [https://ahay.org/blog/2015/03/04/program-of-the-month-sfgrey/ sfgrey]
| Generate raster plot.
|-
| February
| [https://ahay.org/blog/2015/03/01/program-of-the-month-sfhistogram/ sfhistogram]
| Compute a histogram of integer- or float-valued input data.
|-
| January
| [https://ahay.org/blog/2015/01/30/program-of-the-month-sfmf/ sfmf]
| 1D median filtering.
|}

==2014==

{| class="wikitable" style="border:1px"
| December
| [https://ahay.org/blog/2014/12/01/program-of-the-month-sfbin/ sfbin]
| Data binning in 2-D slices.
|-
| November
| [https://ahay.org/blog/2014/11/12/program-of-the-month-sfthreshold/ sfthreshold]
| Soft thresholding.
|-
| October
| [https://ahay.org/blog/2014/10/08/program-of-the-month-sfsigmoid/ sfsigmoid]
| 2-D synthetic model from J.F.Claerbout.
|-
| September
| [https://ahay.org/blog/2014/09/24/program-of-the-month-sfmax1/ sfmax1]
| Picking local maxima on the first axis.
|-
| August
| [https://ahay.org/blog/2014/08/03/program-of-the-month-sfstolt/ sfstolt]
| Post-stack Stolt modeling/migration.
|-
| July
| [https://ahay.org/blog/2014/07/13/program-of-the-month-sfltft/ sfltft]
| Local time-frequency transform (LTFT).
|-
| June
| [https://ahay.org/blog/2014/06/11/program-of-the-month-sfeikonal/ sfeikonal]
| Fast marching eikonal solver (3-D).
|-
| May
| [https://ahay.org/blog/2014/05/13/program-of-the-month-sfhelicon/ sfhelicon]
| Multidimensional convolution and deconvolution by helix transform.
|-
| April
| [https://ahay.org/blog/2014/04/02/program-of-the-month-sfcostaper/ sfcostaper]
| Cosine taper around the borders (N-D).
|-
| March
| [https://ahay.org/blog/2014/03/11/program-of-the-month-sflpad/ sflpad]
| Pad and interleave traces.
|-
| February
| [https://ahay.org/blog/2014/02/06/program-of-the-month-sfdipfilter/ sfdipfilter]
| Filter data based on dip in 2-D or 3-D.
|-
| January
| [https://ahay.org/blog/2014/01/09/program-of-the-month-sfinttest1/ sfinttest1]
| Interpolation from a regular grid in 1-D.
|}

==2013==

{| class="wikitable" style="border:1px"
| December
| [https://ahay.org/blog/2013/12/01/program-of-the-month-sfcausint/ sfcausint]
| Causal integration on the first axis.
|-
| November
| [https://ahay.org/blog/2013/11/03/program-of-the-month-sfremap1/ sfremap1]
| 1-D ENO interpolation.
|-
| October
| [https://ahay.org/blog/2013/10/03/program-of-the-month-sfunif2/ sfunif2]
| Generate 2-D layered velocity model from specified interfaces.
|-
| September
| [https://ahay.org/blog/2013/09/14/program-of-the-month-sfpatch/ sfpatch]
| Patching (N-dimensional).
|-
| August
| [https://www.ahay.org/blog/2013/08/02/program-of-the-month-sfai2refl/ sfai2refl]
| Convert acoustic impedance to reflectivity.
|-
| July
| [https://www.ahay.org/blog/2013/07/01/program-of-the-month-sftime2depth/ sftime2depth]
| Time-to-depth conversion in V(z).
|-
| June
| [https://www.ahay.org/blog/2013/06/12/program-of-the-month-sfwiggle/ sfwiggle]
| Plot data with wiggly traces.
|-
| May
| [https://www.ahay.org/blog/2013/05/04/program-of-the-month-sfvscan/ sfvscan]
| Velocity analysis.
|-
| April
| [https://ahay.org/blog/2013/04/08/program-of-the-month-sfnmo/ sfnmo]
| Normal moveout.
|-
| March
| [https://www.ahay.org/blog/2013/03/10/program-of-the-month-sfpow/ sfpow]
| Apply power gain.
|-
| February
| [https://ahay.org/blog/2013/02/09/program-of-the-month-sfpwd/ sfpwd]
| 3-D plane wave destruction.
|-
| January
| [https://ahay.org/blog/2013/01/08/program-of-the-month-sfricker1/ sfricker1]
| Convolution with a Ricker wavelet.
|}

==2012==

{| class="wikitable" style="border:1px"
| December
| [https://ahay.org/blog/2012/12/23/program-of-the-month-sfhalfint/ sfhalfint]
| Half-order integration or differentiation.
|-
| November
| [https://ahay.org/blog/2012/11/03/program-of-the-month-sfbandpass/ sfbandpass]
| Bandpass filtering.
|-
| October
| [https://ahay.org/blog/2012/10/03/program-of-the-month-sfkirmod/ sfkirmod]
| Kirchhoff 2-D/2.5-D modeling with analytical Green's functions.
|-
| September
| [https://ahay.org/blog/2012/09/03/program-of-the-month-sfiwarp/ sfiwarp]
| Inverse 1-D warping.
|-
| August
| [https://ahay.org/blog/2012/08/01/program-of-the-month-sfpick/ sfpick]
| Automatic picking from semblance-like panels.
|-
| July
| [https://ahay.org/blog/2012/07/02/program-of-the-month-sffft3/ sffft3]
| FFT transform on extra axis.
|-
| June
| [https://ahay.org/blog/2012/06/02/program-of-the-month-sfdip/ sfdip]
| 3-D dip estimation by plane wave destruction.
|-
| May
| [https://ahay.org/blog/2012/05/01/program-of-the-month-sfderiv/ sfderiv]
| First derivative with a maximally linear FIR differentiator.
|-
| April
| [https://ahay.org/blog/2012/04/01/program-of-the-month-sfgrey3/ sfgrey3]
| Generate 3-D cube plot.
|-
| March
| [https://ahay.org/blog/2012/03/18/program-of-the-month-sfspectra/ sfspectra]
| Frequency spectra.
|-
| January
| [https://ahay.org/blog/2012/01/01/program-of-the-month-sfsmooth/ sfsmooth]
| Multi-dimensional triangle smoothing.
|}

==2011==

{| class="wikitable" style="border:1px"
| December
| [https://ahay.org/blog/2011/12/03/programs-of-the-month-sfcontour/ sfcontour]
| Contour plot.
|-
| November
| [https://ahay.org/blog/2011/11/05/program-of-the-month-sfenvelope/ sfenvelope]
| Compute data envelope or phase rotation.
|-
| October
| [https://ahay.org/blog/2011/10/01/program-of-the-month-sfagc/ sfagc]
| Automatic gain control.
|-
| September
| [https://ahay.org/blog/2011/09/03/program-of-the-month-sfclip/ sfclip]
| Clip the data.
|-
| August
| [https://ahay.org/blog/2011/08/09/program-of-the-month-sfgraph/ sfgraph]
| Graph plot.
|-
| July
| [https://ahay.org/blog/2011/07/03/program-of-the-month-sfnoise/ sfnoise]
| Add random noise to the data.
|}

Guide to madagascar programs

2024-11-19T00:13:20Z

Fomels: ahay.org

<center>''This page was created from the LaTeX source in [https://github.com/ahay/src/blob/master/book/rsf/rsf/prog.tex 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 [https://github.com/ahay/src/blob/master/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 axis sampling parameters (such as
<tt>o1</tt> or <tt>d1</tt>) in these files are different.
====Implementation: [https://github.com/ahay/src/blob/master/system/main/add.c system/main/add.c]====
The first input file is either in the list or in the standard input.
<syntaxhighlight lang="c">
/* find number of input files */
if (isatty(fileno(stdin))) {
/* no input file in stdin */
nin=0;
} else {
filename[0] = "in";
nin=1;
}
</syntaxhighlight>

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 is <tt>nin</tt>.
<syntaxhighlight lang="c">
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'=')) continue; /* not a file */
filename[nin] = argv[i];
nin++;
}
if (0==nin) sf_error ("no input");
/* nin = no of input files*/
</syntaxhighlight>

A helper function <tt>check_compat</tt> checks the compatibility of
input files.
<syntaxhighlight lang="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);
}
}
}
</syntaxhighlight>

Finally, we enter the main loop, where the input data are getting read
buffer by buffer and combined in the total product depending on the
data type.
<syntaxhighlight lang="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;
</syntaxhighlight>

The data combination program for floating point numbers is
<tt>add_float</tt>.
<syntaxhighlight lang="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;
}
}
}
</syntaxhighlight>

==sfattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display dataset attributes.
|-
! colspan="4" | sfattr < in.rsf lval=2 want=
|-
| colspan="4" | Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr" ******************************************* rms = 0.992354 mean = 0.987576 2-norm = 9.92354 variance = 0.00955481 std dev = 0.0977487 max = 1.12735 at 97 min = 0.151392 at 100 nonzero samples = 100 total 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:
<syntaxhighlight lang="bash">
sfgrey <vel.rsf allpos=y bias=`sfattr <vel.rsf want=min | awk '{print $4}'` | sfpen
</syntaxhighlight>

====Implementation: [https://github.com/ahay/src/blob/master/system/main/attr.c system/main/attr.c]====

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

In the main loop, we read the input data buffer by buffer.
<syntaxhighlight lang="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_SHORT:
sf_shortread((short*) 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;
}
</syntaxhighlight>

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

Finally, the attributes are reduced and printed out.
<syntaxhighlight lang="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 = fabs(fsqr-nsiz*fmean*fmean)/(nsiz-1);
else fvar = 0.0;
fstd = sqrt(fvar);
</syntaxhighlight>

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

==sfcat==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Concatenate datasets.
|-
! colspan="4" | sfcat > out.rsf order= space= axis=3 nspace=(int) (ni/(20*nin) + 1) o= d= [<file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | sfmerge inserts additional space between merged data.
|-
| ''int '' || '''axis=3''' || || Axis being merged
|-
| ''float '' || '''d=''' || || axis sampling
|-
| ''int '' || '''nspace=(int) (ni/(20*nin) + 1)''' || || if space=y, number of traces to insert
|-
| ''float '' || '''o=''' || || axis origin
|-
| ''ints '' || '''order=''' || || concatenation order [nin]
|-
| ''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: [https://github.com/ahay/src/blob/master/system/main/cat.c system/main/cat.c]====
The first input file is either in the list or in the standard input.
<syntaxhighlight lang="c">
in = (sf_file*) sf_alloc ((size_t) argc,sizeof(sf_file));

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

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.
<syntaxhighlight lang="c">
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'='))
continue; /* not a file */
filename[nin] = argv[i];
nin++;
}
if (0==nin) sf_error ("no input");
</syntaxhighlight>

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>.
<syntaxhighlight lang="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;
}
}
</syntaxhighlight>

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.
<syntaxhighlight lang="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];
}
</syntaxhighlight>

In the output, the selected axis will get extended.
<syntaxhighlight lang="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);
</syntaxhighlight>

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>.
<syntaxhighlight lang="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);
}
}
}
</syntaxhighlight>

==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 by taking advantage that the complex-to-complex FFT is a linear operator:

<syntaxhighlight lang="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
</syntaxhighlight>

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 < real.rsf > 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: [https://github.com/ahay/src/blob/master/system/main/cmplx.c system/main/cmplx.c]====
The program flow is simple. First, get the names of the input files.
<syntaxhighlight lang="c">
/* the first two non-parameters are real and imag 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");
}
</syntaxhighlight>

The main part of the program reads the real and imaginary parts buffer by buffer and assembles and writes out the complex input.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

==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 mwt=mwt.rsf known=known.rsf x0=x0.rsf > to.rsf < from.rsf > out.rsf niter=1
|-
| ''string '' || '''known=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|-
| ''string '' || '''mwt=''' || || auxiliary input file name
|-
| ''int '' || '''niter=1''' || || number of iterations
|-
| ''string '' || '''x0=''' || || auxiliary input file name
|}

<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 [https://ahay.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 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 at all. The program [https://ahay.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>
The misfit decreased by an order of magnitude in 10 iterations. Running the program for more iterations can improve the result.

An equivalent implementation for complex-valued inputs is [https://ahay.org/RSF/sfcconjgrad.html sfcconjgrad]. A lightweight Python implementation can be found in [https://github.com/ahay/src/blob/master/user/fomels/conjgrad.py $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 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: [https://github.com/ahay/src/blob/master/system/main/cp.c 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.
<syntaxhighlight lang="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");
</syntaxhighlight>

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

==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 j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
|-
| colspan="4" | Reverse of window.
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''largeint'' || '''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 '' || '''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 trunc=n line=8 ibm=n form= type= format=
|-
| ''string '' || '''form=''' || || ascii, native, xdr
|-
| ''string '' || '''format=''' || || Element format (for conversion to ASCII)
|-
| ''bool '' || '''ibm=n''' || [y/n] || Special case - assume integers actually represent IBM floats
|-
| ''int '' || '''line=8''' || || Number of numbers per line (for conversion to ASCII)
|-
| ''bool '' || '''trunc=n''' || [y/n] || Truncate or round to nearest when converting from float to int/short
|-
| ''string '' || '''type=''' || || int, float, complex, short, long
|}

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 examine RSF files quickly. 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
|-
| ''file '' || '''dat=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|}

<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
dimensions and size of these vectors! If the program does not respond
for a very long time, the dimension and size
of the vectors may be inconsistent with the requirement of the program to be
tested. <tt>sfdottest</tt>
does not create any temporary files and has no restrictive
limitations on the size of the vectors.
Here is an example. We first create 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 parform=y all=n par1 par2 ...
|-
| ''bool '' || '''all=n''' || [y/n] || If output all values.
|-
| ''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: [https://github.com/ahay/src/blob/master/system/main/get.c system/main/get.c]====
The implementation is trivial. Loop through all command-line parameters that contain
the "=" character.
<syntaxhighlight lang="c">
for (i = 1; i < argc; i++) {
key = argv[i];
if (NULL != strchr(key,'=')) continue;
</syntaxhighlight>

Get the parameter value (as a string) and output it as either
<tt>key=value</tt> or <tt>value</tt>, depending on the
<tt>parform</tt> parameter.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

==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.
|-
| ''file '' || '''mask=''' || || auxiliary input file name
|}

<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 inv=n
|-
| 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.
|-
| ''bool '' || '''inv=n''' || [y/n] || inversion flag
|-
| ''file '' || '''mask=''' || || auxiliary input file name
|}

<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 [<file0.rsf] 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:
<syntaxhighlight lang="bash">
sed -i 's/n6=1//g' file.rsf
</syntaxhighlight>

==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= 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=''' || || maximum header value
|-
| ''float '' || '''min=''' || || 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 nostdin=n 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, sign (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
|-
| ''bool '' || '''nostdin=n''' || [y/n] || y - ignore stdin
|-
| ''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 with the
same dimensions and data type. The data type can be real (floating
point) or complex. The following example 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 <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:
<syntaxhighlight lang="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
</syntaxhighlight>

==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#. Other parameters from the command line are passed to the output (similar to sfput).
|-
| ''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 by 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>, and 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=n 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 pair=n
|-
| colspan="4" | See also: sfcmplx
|-
| ''bool '' || '''pair=n''' || [y/n] || y - use odd elements for the real part and even ones for the imaginary part
|}

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. pclip=100. dscale=1.
|-
| colspan="4" | To scale by a constant factor, you can also use sfmath.
|-
| ''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 '' || '''pclip=100.''' || || data clip percentile
|-
| ''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 with <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 < in.rsf > 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 axes:
<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 scale= axis=2 rms=n norm=y min=n max=n prod=n
|-
| colspan="4" | This operation is adjoint to sfspray.
|-
| ''int '' || '''axis=2''' || || which axis to stack. If axis=0, stack over all dimensions
|-
| ''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 '' || '''prod=n''' || [y/n] || If y, find product instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''rms=n''' || [y/n] || If y, compute the root-mean-square instead of stack.
|-
| ''floats '' || '''scale=''' || || optionally scale before stacking [n2]
|}

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 <tt>plane=</tt> 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 <tt>memsize=</tt> parameter or
the <tt>RSFMEMSIZE</tt> environmental variable.

==sfwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a portion of a 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,,...)
|-
| colspan="4" | Other parameters from the command line are passed to the output (similar to sfput).
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''largeint'' || '''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
|-
| ''largeint'' || '''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 select a window from the minimum and maximum
parameters. 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://www.ahay.org/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:
<syntaxhighlight lang="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
</syntaxhighlight>

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

Compute the 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:
<syntaxhighlight lang="bash">
<spikefft3.rsf sffkamo h2=2 f2=10 h1=1.8 f1=30 >oper.rsf
</syntaxhighlight>

Apply the operator by multiplication and fft back to (t, mx, my):
<syntaxhighlight lang="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
</syntaxhighlight>

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

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

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

Apply the f-k filter and (in this case) visualize:
<syntaxhighlight lang="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 &
</syntaxhighlight>

==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 identify meaningful keywords 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 helpful in
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 "header" 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).

An 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 their 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>tfile=</tt> option. The user may remap these predefined keywords to different byte offsets.

===SU File Format===
An [http://www.cwp.mines.edu/sututor/node22.html SU file] is nothing more than an 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 the name of the file in which the binary reel header (the 400-byte thing following the 3600-byte 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 an 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. The default is <tt>su=n</tt> (SEG-Y file).
*<tt>read=</tt> specifies what parts of the "Trace Blocks" will be read. It can be <tt>read=d</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 mask samples is the same as the number of traces in the unmasked SEG-Y. There should be zeros in the mask in places corresponding to unwanted traces.
*<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 estimate automatically 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 <tt>tape=</tt> tag specifies the output file.
=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 [https://ahay.org/blog/2005/03/28/color-schemes/ color schemes] are available
for sfgrey and sfgrey3. Examples are in the book at [https://ahay.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 [https://ahay.org/blog/2005/03/28/color-schemes/ color schemes] are available, and examples are in the book at [https://ahay.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 like <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 [https://ahay.org/wikilocal/movies/sfplsurf_membrane.mpg movie of the output] is available as well.

<syntaxhighlight lang="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()
</syntaxhighlight>

=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 aperture (gate= parameter in sfpick) limits the search radius.
# 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.

Many people have discovered and rediscovered the algorithm. 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 the 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 follows below. First, create an input file:

<syntaxhighlight lang="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
</syntaxhighlight>

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 in length:

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

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 transposed on disk:

<syntaxhighlight lang="bash">
$ 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
</syntaxhighlight>

Depending on your needs, you may want to run the output through <tt>sftransp</tt>. 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:

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

Note that since this program does not need any arguments (just stdin and stdout), it will not display the man page when called with no arguments. 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 the "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
|}

Below, we will demonstrate an example of a model with nx=nz=200 and dx=dz=4m (size: 800x800m). There are two layers: the first 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. The 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.

<ol>
<li>Velocity model:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</li>

<li>Density model:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</li>

<li>Source position (x,z):
<syntaxhighlight lang="bash">
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 > Fsou.rsf
</syntaxhighlight>
</li>

<li>Receiver position (x,z):
<syntaxhighlight lang="bash">
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 > Frec.rsf
</syntaxhighlight>
</li>

<li>Source wavelet:
<syntaxhighlight lang="bash">
sfspike nsp=1 n1=2000 d1=0.0005 k1=200 | sfricker1 frequency=20 |\
sftransp > Fwav.rsf
</syntaxhighlight>
</li>

<li>Creating data at specified receiver + saving full wavefield every 10th step:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</li>

<li>View the wavefield movie:
<syntaxhighlight lang="bash">
< Fwfl.rsf sfgrey gainpanel=a pclip=99 color=j scalebar=y | sfpen
</syntaxhighlight>
</li>

<li>View a wavefield snapshot:
<syntaxhighlight lang="bash">
< Fwfl.rsf sfwindow f3=80 n3=1 |\
sfgrey pclip=99 color=j title='snapshot at t=0.4s' |\
sfpen
</syntaxhighlight>
</li>

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

[[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 it should be 5 or so for reasonable results. 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 [https://ahay.org/RSF/book/data/sigsbee Sigsbee 2A] data and velocity for migration.

Convert input data (shots) from SEG-Y to RSF:
<syntaxhighlight lang="bash">
sfsegyread tape=sigsbee2a_nfs.segy tfile=tdata.rsf hfile=/dev/null bfile=/dev/null > ddata.rsf
</syntaxhighlight>
Convert trace headers to float (required by <tt>sfheadermath</tt>):
<syntaxhighlight lang="bash">
< tdata.rsf sfdd type=float > trchdr.rsf
</syntaxhighlight>
Shot positions:
<syntaxhighlight lang="bash">
< trchdr.rsf sfheadermath output="fldr + 10925/150" | sfwindow squeeze=y > tsi.rsf
</syntaxhighlight>
Extract offset positions from the trace header files, eliminate length-1 axis, scale, and create a header for binning (required by <tt>sfintbin</tt>):
<syntaxhighlight lang="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
</syntaxhighlight>
Binning and muting:
<syntaxhighlight lang="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
</syntaxhighlight>
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:
<syntaxhighlight lang="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
</syntaxhighlight>
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:
<syntaxhighlight lang="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
</syntaxhighlight>
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. The receiver and shot frequency slices are "placed" at the right location and padded with zeros up to the x-axis dimension specified below.
<syntaxhighlight lang="bash">
< rfft.rsf sfsrsyn nx=1067 dx=0.02286 ox=3.05562 wav=sfft.rsf swf=swav.rsf > rwav.rsf
</syntaxhighlight>
This creates frequency slices ready for migration for both source and receiver, only axis 1 (frequency) must become axis 3, for both datasets:
<syntaxhighlight lang="bash">
< swav.rsf sftransp plane=12 | sftransp plane=23 > stra.rsf
</syntaxhighlight>
<syntaxhighlight lang="bash">
< rwav.rsf sftransp plane=12 | sftransp plane=23 > rtra.rsf
</syntaxhighlight>
This creates a surface receiver wavefield ready for input to migration. Axis 4 is the 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 that of the whole 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:
<syntaxhighlight lang="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
</syntaxhighlight>
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 an RSF file with the name of the tag and no rsf extension will be created:
<syntaxhighlight lang="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
</syntaxhighlight>
The migration of 20 shots takes approximately three 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:
<syntaxhighlight lang="bash">
<img.rsf sfwindow squeeze=y | sftransp | sfgrey > img.vpl
</syntaxhighlight>

=References=
<references/>

Guide to madagascar programs

2024-11-13T23:35:42Z

Fomels: typos

<center>''This page was created from the LaTeX source in [https://github.com/ahay/src/blob/master/book/rsf/rsf/prog.tex 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 [https://github.com/ahay/src/blob/master/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 axis sampling parameters (such as
<tt>o1</tt> or <tt>d1</tt>) in these files are different.
====Implementation: [https://github.com/ahay/src/blob/master/system/main/add.c system/main/add.c]====
The first input file is either in the list or in the standard input.
<syntaxhighlight lang="c">
/* find number of input files */
if (isatty(fileno(stdin))) {
/* no input file in stdin */
nin=0;
} else {
filename[0] = "in";
nin=1;
}
</syntaxhighlight>

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 is <tt>nin</tt>.
<syntaxhighlight lang="c">
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'=')) continue; /* not a file */
filename[nin] = argv[i];
nin++;
}
if (0==nin) sf_error ("no input");
/* nin = no of input files*/
</syntaxhighlight>

A helper function <tt>check_compat</tt> checks the compatibility of
input files.
<syntaxhighlight lang="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);
}
}
}
</syntaxhighlight>

Finally, we enter the main loop, where the input data are getting read
buffer by buffer and combined in the total product depending on the
data type.
<syntaxhighlight lang="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;
</syntaxhighlight>

The data combination program for floating point numbers is
<tt>add_float</tt>.
<syntaxhighlight lang="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;
}
}
}
</syntaxhighlight>

==sfattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display dataset attributes.
|-
! colspan="4" | sfattr < in.rsf lval=2 want=
|-
| colspan="4" | Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr" ******************************************* rms = 0.992354 mean = 0.987576 2-norm = 9.92354 variance = 0.00955481 std dev = 0.0977487 max = 1.12735 at 97 min = 0.151392 at 100 nonzero samples = 100 total 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:
<syntaxhighlight lang="bash">
sfgrey <vel.rsf allpos=y bias=`sfattr <vel.rsf want=min | awk '{print $4}'` | sfpen
</syntaxhighlight>

====Implementation: [https://github.com/ahay/src/blob/master/system/main/attr.c system/main/attr.c]====

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

In the main loop, we read the input data buffer by buffer.
<syntaxhighlight lang="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_SHORT:
sf_shortread((short*) 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;
}
</syntaxhighlight>

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

Finally, the attributes are reduced and printed out.
<syntaxhighlight lang="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 = fabs(fsqr-nsiz*fmean*fmean)/(nsiz-1);
else fvar = 0.0;
fstd = sqrt(fvar);
</syntaxhighlight>

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

==sfcat==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Concatenate datasets.
|-
! colspan="4" | sfcat > out.rsf order= space= axis=3 nspace=(int) (ni/(20*nin) + 1) o= d= [<file0.rsf] file1.rsf file2.rsf ...
|-
| colspan="4" | sfmerge inserts additional space between merged data.
|-
| ''int '' || '''axis=3''' || || Axis being merged
|-
| ''float '' || '''d=''' || || axis sampling
|-
| ''int '' || '''nspace=(int) (ni/(20*nin) + 1)''' || || if space=y, number of traces to insert
|-
| ''float '' || '''o=''' || || axis origin
|-
| ''ints '' || '''order=''' || || concatenation order [nin]
|-
| ''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: [https://github.com/ahay/src/blob/master/system/main/cat.c system/main/cat.c]====
The first input file is either in the list or in the standard input.
<syntaxhighlight lang="c">
in = (sf_file*) sf_alloc ((size_t) argc,sizeof(sf_file));

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

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.
<syntaxhighlight lang="c">
for (i=1; i< argc; i++) { /* collect inputs */
if (NULL != strchr(argv[i],'='))
continue; /* not a file */
filename[nin] = argv[i];
nin++;
}
if (0==nin) sf_error ("no input");
</syntaxhighlight>

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>.
<syntaxhighlight lang="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;
}
}
</syntaxhighlight>

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.
<syntaxhighlight lang="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];
}
</syntaxhighlight>

In the output, the selected axis will get extended.
<syntaxhighlight lang="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);
</syntaxhighlight>

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>.
<syntaxhighlight lang="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);
}
}
}
</syntaxhighlight>

==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 by taking advantage that the complex-to-complex FFT is a linear operator:

<syntaxhighlight lang="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
</syntaxhighlight>

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 < real.rsf > 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: [https://github.com/ahay/src/blob/master/system/main/cmplx.c system/main/cmplx.c]====
The program flow is simple. First, get the names of the input files.
<syntaxhighlight lang="c">
/* the first two non-parameters are real and imag 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");
}
</syntaxhighlight>

The main part of the program reads the real and imaginary parts buffer by buffer and assembles and writes out the complex input.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

==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 mwt=mwt.rsf known=known.rsf x0=x0.rsf > to.rsf < from.rsf > out.rsf niter=1
|-
| ''string '' || '''known=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|-
| ''string '' || '''mwt=''' || || auxiliary input file name
|-
| ''int '' || '''niter=1''' || || number of iterations
|-
| ''string '' || '''x0=''' || || auxiliary input file name
|}

<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 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 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>
The misfit decreased by an order of magnitude in 10 iterations. Running the program for more iterations can improve the result.

An equivalent implementation for complex-valued inputs is [http://www.reproducibility.org/RSF/sfcconjgrad.html sfcconjgrad]. A lightweight Python implementation can be found in [https://github.com/ahay/src/blob/master/user/fomels/conjgrad.py $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 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: [https://github.com/ahay/src/blob/master/system/main/cp.c 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.
<syntaxhighlight lang="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");
</syntaxhighlight>

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

==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 j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
|-
| colspan="4" | Reverse of window.
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''largeint'' || '''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 '' || '''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 trunc=n line=8 ibm=n form= type= format=
|-
| ''string '' || '''form=''' || || ascii, native, xdr
|-
| ''string '' || '''format=''' || || Element format (for conversion to ASCII)
|-
| ''bool '' || '''ibm=n''' || [y/n] || Special case - assume integers actually represent IBM floats
|-
| ''int '' || '''line=8''' || || Number of numbers per line (for conversion to ASCII)
|-
| ''bool '' || '''trunc=n''' || [y/n] || Truncate or round to nearest when converting from float to int/short
|-
| ''string '' || '''type=''' || || int, float, complex, short, long
|}

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 examine RSF files quickly. 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
|-
| ''file '' || '''dat=''' || || auxiliary input file name
|-
| ''file '' || '''mod=''' || || auxiliary input file name
|}

<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
dimensions and size of these vectors! If the program does not respond
for a very long time, the dimension and size
of the vectors may be inconsistent with the requirement of the program to be
tested. <tt>sfdottest</tt>
does not create any temporary files and has no restrictive
limitations on the size of the vectors.
Here is an example. We first create 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 parform=y all=n par1 par2 ...
|-
| ''bool '' || '''all=n''' || [y/n] || If output all values.
|-
| ''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: [https://github.com/ahay/src/blob/master/system/main/get.c system/main/get.c]====
The implementation is trivial. Loop through all command-line parameters that contain
the "=" character.
<syntaxhighlight lang="c">
for (i = 1; i < argc; i++) {
key = argv[i];
if (NULL != strchr(key,'=')) continue;
</syntaxhighlight>

Get the parameter value (as a string) and output it as either
<tt>key=value</tt> or <tt>value</tt>, depending on the
<tt>parform</tt> parameter.
<syntaxhighlight lang="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);
}
</syntaxhighlight>

==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.
|-
| ''file '' || '''mask=''' || || auxiliary input file name
|}

<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 inv=n
|-
| 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.
|-
| ''bool '' || '''inv=n''' || [y/n] || inversion flag
|-
| ''file '' || '''mask=''' || || auxiliary input file name
|}

<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 [<file0.rsf] 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:
<syntaxhighlight lang="bash">
sed -i 's/n6=1//g' file.rsf
</syntaxhighlight>

==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= 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=''' || || maximum header value
|-
| ''float '' || '''min=''' || || 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 nostdin=n 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, sign (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
|-
| ''bool '' || '''nostdin=n''' || [y/n] || y - ignore stdin
|-
| ''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 with the
same dimensions and data type. The data type can be real (floating
point) or complex. The following example 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 <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:
<syntaxhighlight lang="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
</syntaxhighlight>

==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#. Other parameters from the command line are passed to the output (similar to sfput).
|-
| ''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 by 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>, and 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=n 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 pair=n
|-
| colspan="4" | See also: sfcmplx
|-
| ''bool '' || '''pair=n''' || [y/n] || y - use odd elements for the real part and even ones for the imaginary part
|}

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. pclip=100. dscale=1.
|-
| colspan="4" | To scale by a constant factor, you can also use sfmath.
|-
| ''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 '' || '''pclip=100.''' || || data clip percentile
|-
| ''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 with <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 < in.rsf > 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 axes:
<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 scale= axis=2 rms=n norm=y min=n max=n prod=n
|-
| colspan="4" | This operation is adjoint to sfspray.
|-
| ''int '' || '''axis=2''' || || which axis to stack. If axis=0, stack over all dimensions
|-
| ''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 '' || '''prod=n''' || [y/n] || If y, find product instead of stack. Ignores rms and norm.
|-
| ''bool '' || '''rms=n''' || [y/n] || If y, compute the root-mean-square instead of stack.
|-
| ''floats '' || '''scale=''' || || optionally scale before stacking [n2]
|}

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 <tt>plane=</tt> 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 <tt>memsize=</tt> parameter or
the <tt>RSFMEMSIZE</tt> environmental variable.

==sfwindow==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Window a portion of a 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,,...)
|-
| colspan="4" | Other parameters from the command line are passed to the output (similar to sfput).
|-
| ''float '' || '''d#=(d1,d2,...)''' || || sampling in #-th dimension
|-
| ''largeint'' || '''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
|-
| ''largeint'' || '''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 select a window from the minimum and maximum
parameters. 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://www.ahay.org/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:
<syntaxhighlight lang="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
</syntaxhighlight>

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

Compute the 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:
<syntaxhighlight lang="bash">
<spikefft3.rsf sffkamo h2=2 f2=10 h1=1.8 f1=30 >oper.rsf
</syntaxhighlight>

Apply the operator by multiplication and fft back to (t, mx, my):
<syntaxhighlight lang="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
</syntaxhighlight>

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

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

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

Apply the f-k filter and (in this case) visualize:
<syntaxhighlight lang="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 &
</syntaxhighlight>

==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 identify meaningful keywords 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 helpful in
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 "header" 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).

An 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 their 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>tfile=</tt> option. The user may remap these predefined keywords to different byte offsets.

===SU File Format===
An [http://www.cwp.mines.edu/sututor/node22.html SU file] is nothing more than an 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 the name of the file in which the binary reel header (the 400-byte thing following the 3600-byte 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 an 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. The default is <tt>su=n</tt> (SEG-Y file).
*<tt>read=</tt> specifies what parts of the "Trace Blocks" will be read. It can be <tt>read=d</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 mask samples is the same as the number of traces in the unmasked SEG-Y. There should be zeros in the mask in places corresponding to unwanted traces.
*<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 estimate automatically 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 <tt>tape=</tt> tag specifies the output file.
=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 like <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.

<syntaxhighlight lang="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()
</syntaxhighlight>

=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 aperture (gate= parameter in sfpick) limits the search radius.
# 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.

Many people have discovered and rediscovered the algorithm. 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 the 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 follows below. First, create an input file:

<syntaxhighlight lang="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
</syntaxhighlight>

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 in length:

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

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 transposed on disk:

<syntaxhighlight lang="bash">
$ 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
</syntaxhighlight>

Depending on your needs, you may want to run the output through <tt>sftransp</tt>. 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:

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

Note that since this program does not need any arguments (just stdin and stdout), it will not display the man page when called with no arguments. 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 the "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
|}

Below, we will demonstrate an example of a model with nx=nz=200 and dx=dz=4m (size: 800x800m). There are two layers: the first 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. The 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.

<ol>
<li>Velocity model:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</li>

<li>Density model:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</li>

<li>Source position (x,z):
<syntaxhighlight lang="bash">
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 > Fsou.rsf
</syntaxhighlight>
</li>

<li>Receiver position (x,z):
<syntaxhighlight lang="bash">
sfspike n1=2 nsp=2 k1=1,2 mag=400,100 o1=0 o2=0 > Frec.rsf
</syntaxhighlight>
</li>

<li>Source wavelet:
<syntaxhighlight lang="bash">
sfspike nsp=1 n1=2000 d1=0.0005 k1=200 | sfricker1 frequency=20 |\
sftransp > Fwav.rsf
</syntaxhighlight>
</li>

<li>Creating data at specified receiver + saving full wavefield every 10th step:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</li>

<li>View the wavefield movie:
<syntaxhighlight lang="bash">
< Fwfl.rsf sfgrey gainpanel=a pclip=99 color=j scalebar=y | sfpen
</syntaxhighlight>
</li>

<li>View a wavefield snapshot:
<syntaxhighlight lang="bash">
< Fwfl.rsf sfwindow f3=80 n3=1 |\
sfgrey pclip=99 color=j title='snapshot at t=0.4s' |\
sfpen
</syntaxhighlight>
</li>

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

[[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 it should be 5 or so for reasonable results. 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:
<syntaxhighlight lang="bash">
sfsegyread tape=sigsbee2a_nfs.segy tfile=tdata.rsf hfile=/dev/null bfile=/dev/null > ddata.rsf
</syntaxhighlight>
Convert trace headers to float (required by <tt>sfheadermath</tt>):
<syntaxhighlight lang="bash">
< tdata.rsf sfdd type=float > trchdr.rsf
</syntaxhighlight>
Shot positions:
<syntaxhighlight lang="bash">
< trchdr.rsf sfheadermath output="fldr + 10925/150" | sfwindow squeeze=y > tsi.rsf
</syntaxhighlight>
Extract offset positions from the trace header files, eliminate length-1 axis, scale, and create a header for binning (required by <tt>sfintbin</tt>):
<syntaxhighlight lang="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
</syntaxhighlight>
Binning and muting:
<syntaxhighlight lang="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
</syntaxhighlight>
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:
<syntaxhighlight lang="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
</syntaxhighlight>
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:
<syntaxhighlight lang="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
</syntaxhighlight>
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. The receiver and shot frequency slices are "placed" at the right location and padded with zeros up to the x-axis dimension specified below.
<syntaxhighlight lang="bash">
< rfft.rsf sfsrsyn nx=1067 dx=0.02286 ox=3.05562 wav=sfft.rsf swf=swav.rsf > rwav.rsf
</syntaxhighlight>
This creates frequency slices ready for migration for both source and receiver, only axis 1 (frequency) must become axis 3, for both datasets:
<syntaxhighlight lang="bash">
< swav.rsf sftransp plane=12 | sftransp plane=23 > stra.rsf
</syntaxhighlight>
<syntaxhighlight lang="bash">
< rwav.rsf sftransp plane=12 | sftransp plane=23 > rtra.rsf
</syntaxhighlight>
This creates a surface receiver wavefield ready for input to migration. Axis 4 is the 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 that of the whole 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:
<syntaxhighlight lang="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
</syntaxhighlight>
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 an RSF file with the name of the tag and no rsf extension will be created:
<syntaxhighlight lang="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
</syntaxhighlight>
The migration of 20 shots takes approximately three 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:
<syntaxhighlight lang="bash">
<img.rsf sfwindow squeeze=y | sftransp | sfgrey > img.vpl
</syntaxhighlight>

=References=
<references/>

Hall of Fame

2024-11-04T23:29:19Z

Fomels:

[[Image:Laurel.png|right|]]
This page honors individuals who made crucial contributions to Madagascar's development and to the Madagascar community. You can read their stories by following the links below.

==Ioan "Nick" Vlad==

[[Nick Vlad]] enhanced Madagascar installation by improving directory structures and configuration scripts. He maintained the Madagascar wiki pages and generated much of their content. He actively participated in community discussions and created the [https://www.linkedin.com/groups/1847746/ LinkedIn group] for Madagascar users.

==Pengliang Yang==

[[Pengliang Yang]] developed efficient CUDA codes for fast execution on GPU devices and provided examples of their usage in geophysical tasks, from forward wave modeling to full waveform inversion. He served as an instructor at Madagascar schools, including [[Harbin 2015|Harbin-2015]] and [[Zurich 2016|Zurich-2016]].

==Vladimir Bashkardin==

[[Vladimir Bashkardin]] wrote [https://reproducibility.org/RSF/sfoglpen.html oglpen], a Vplot visualization program based on [https://en.wikipedia.org/wiki/OpenGL OpenGL]. He also developed new tools for parallel computing and handling large-scale datasets. Vladimir actively participated in the Madagascar community and taught at Madagascar schools, including [[Houston 2010|Houston-2010]].

==Yang Liu==

[[Yang Liu]] contributed code, reproducible examples, and research papers. He taught at numerous Madagascar schools, including [[Houston 2010|Houston-2010]], [[Beijing 2011|Beijing-2011]], [[Melbourne 2013|Melbourne-2013]], and [[Shanghai 2017|Shanghai-2017]]. Yang played a critical role in promoting Madagascar in China and hosted [[Hefei 2020|Hefei-2020]] at the 1st Asia-Pacific Geophysics Student Conference. He currently maintains the Madagascar webserver.

==Jeff Godwin==

[[Jeff Godwin]] wrote a [[Tutorial|Madagascar Tutorial]] and useful Python scripts, including [[tkMadagascar|TkMadagascar]], an example of a complete interactive environment. He also helped many other users and taught at the Madagascar school in [[Houston 2010|Houston-2010]].

==Jim Jennings==

[[Jim Jennings]] was the first active Madagascar user outside the geophysics community. He contributed [https://github.com/ahay/src/tree/master/book/geostats Python packages for geostatistical modeling] and improved the Madagascar infrastructure by writing [[Automatic_Testing|scripts for reproducibility testing]]. Jim actively participated in the Madagascar community and served as an instructor at Madagascar schools, including [[RSF_Austin_School_2007|Austin-2007]] and [[Houston 2010|Houston-2010]].

==Joe Dellinger==

[[Joe Dellinger]] is the primary author of [[Graphics_development_with_vplot|Vplot]]. Originally developed at Stanford in the 1980s, Vplot serves as Madagascar's plotting library today. During the [[2008_Implementation_Workshop|Golden-2008]] workshop, Joe developed the *sfvplotdiff* program for comparing Vplot files, the cornerstone for reproducibility testing. Joe taught at multiple Madagascar schools and workshops, including [[RSF_School_and_Workshop,_Vancouver_2006|Vancouver-2006]], [[RSF_Austin_School_2007|Austin-2007]], and [[Houston 2010|Houston-2010]].

==Zicheng Geng==

[[Zicheng Geng]] played a leading role in maintaining and developing Madagascar in the 2010s. Among other contributions, he converted the Python code to version 3, introduced unit testing, and enhanced [https://reproducibility.org/blog/2016/02/20/continuous-reproducibility-using-circleci/ continuous integration] using CircleCI.

Tutorial

2024-10-31T23:12:42Z

Fomels:

<center>''This page was created from the LaTeX source in [https://github.com/ahay/src/tree/master/book/tutorial book/tutorial/] using [[latex2wiki]]''</center>

=Introduction=
Welcome to a brief introduction to Madagascar. The purpose of this
document is to teach new users how to use the powerful tools in
Madagascar to: process data, produce documents and build your own
Madagascar programs.
To gradually introduce you to Madagascar, we have created a series of
tutorials that are targeted to distinct audiences and designed to make
you an experienced Madagascar user in a short-time period. The
tutorials are divided by interest into three main categories:
* '''Users''' learn about Madagascar, how to use the processing programs, and build scripts.
* '''Authors''' learn how to build reproducible documents using Madagascar.
* '''Developers''' build new Madagascar programs that add additional functionality to Madagascar.
Each tutorial is designed to be completed in a short period of time.
Additionally, each tutorial has hands-on examples that you should be
able to reproduce on your computer as you go along with the tutorials.
Most tutorials will use scripts that you can edit, modify, or play
with to further gain experience and understanding. By the end of the
tutorial series, you should be able to use all of the tools inside of
Madagascar. Please note that this tutorial series does not explicitly
show you how to process certain types of data, or how to perform common data
processing operations (e.g. CMP semblance picking,
time migration,etc.). Additional tutorials on those specific subjects
will be added over time. The purpose of this document is simply to
familiarize you with the Madagascar framework in a general sense.
Before you go on, here are some notes on notation:
*important names, or program names are usually bold in the text. For example: '''sfwindow'''
*code snippets are always in the following formatting: <pre> sfwindow </pre>

=Users=
The Users tutorials demonstrate how to use the Madagascar framework to create, process, and visualize data and to create reproducible scripts for processing data. The main goals of the Users tutorials are to learn about:

*the Madagascar framework,
*the RSF file format,
*the command line interface,
*how to interact with files on the command line,
*commonly used programs,
*how to make plots in Madagascar,
*how to make reproducible scripts,
*how to use SCons and Python,
*how to visualize your data.
By the end of this tutorial group, you should be able to fully use all of Madagascar's built-in tools for data processing and scripting. These tools will allow you to process data ranging from tens of megabytes to tens of terabytes in a reproducible fashion.
==Introduction to Madagascar==
To begin, let's talk about the core principles of Madagascar and the RSF file format.
[[Image:scheme.png|frame|center|The hierarchy of Madagascar. Fundamentally, everything builds off of the RSF file format. As you go up the chain the complexity level may increase, but the capabilities of the processing package increase as well.]]
===Madagascar's design===
There are a few layers to Madagascar. At the bottom-most layer is the RSF file format, a common exchange format used by all Madagascar programs. Non-Madagascar programs can also read/write to and from RSF because it is an open exchange format. The next level of Madagascar contains the actual Madagascar programs that manipulate RSF files to process data. Concurrent to this level is the VPLOT graphics library which allows users to plot and visualize RSF files. The scripting utilities in Python and SCons are up another level from the core programs. These scripting utilities enable users to make powerful scripts that can perform even the most advanced data processing tasks. The last level includes support for LaTeX, which allows you to create documents combining the features of Madagascar with LaTeX's powerful typesetting. Throughout the course of these tutorials, we will examine all of these components and demonstrate how they can be used individually and together. When combined, the individual components of Madagascar allow us to: conduct experiments, process data, visualize our results, make reproducible scripts that can be shared with others, and write papers to document our experiments. Thus, Madagascar provides a fully integrated research environment.

===RSF file format===
As previously mentioned, the lowest level of Madagascar is the RSF file format, which is the format used to exchange information between Madagascar programs. Conceptually, the RSF file format is one of the easiest to understand, as RSF files are simply regularly sampled hypercubes of information. For reference, a hypercube is a hyperdimensional cube (or array) that can best be visualized as an <math>N</math>-dimensional array, where <math>N</math> is between 1 and 9 in Madagascar.

RSF hypercubes are defined by two files, the header file and the binary file. The header file contains information about the dimensionality of the hypercube as well as the data contained within the hypercube. Information contained in the header file may include the following:

*number of elements on all axes,
*the origin of the axes,
*the sampling interval of elements on the axes,
*the type of elements in the axes (i.e., float, integer),
*the size of the elements (e.g. single or double precision),
*and the location of the actual binary file.
Since we often want to view this information about files without deciphering it, we store the header file as an ASCII text file in the local directory, usually with the suffix '''.rsf''' . At any time, you can view or edit the contents of the header files using a text editor such as gedit, VIM, or Emacs.

The binary file is stored remotely (i.e., in a separate directory) containing the actual hypercube data. Because the hypercube data can be very large (<math>10s</math> of GB or TB), we usually store the binary files in a remote directory with the suffix '''.rsf@''' . The user can specify the remote directory using the '''DATAPATH''' environmental variable. The advantage of doing this is that we can store large binary data files on a fast remote filesystem if we want, and we can avoid working in local directories.
[[Image:format.png|frame|center|Cartoon of the RSF file format. The header file points to the binary file, which can be separate from each other. The header file, which is text, is tiny compared to the binary file.]]

Because the header and binary are separated from one another, it is possible that we can lose either the header or binary for a particular RSF file. If the header is lost, then we can simply reconstruct the header using our previous knowledge of the data and a text editor. However, if we lose the binary file, then we cannot reconstruct the data regardless of what we do. Therefore, you should try and avoid losing either the header or binary data. The best way to prevent data loss is to make your research reproducible so that your results can be replicated later.
Sometimes, we need to store RSF files for archiving or transfer to other machines. Fortunately, we can avoid transferring the header and binary separately by using the combined header/binary format for RSF files. Files can be constructed using the combined header/binary format by specifying additional parameters on the command line, in particular '''--out=stdout''' , for any Madagascar program. The output file will then be header/binary combined, which allows you to transfer the file without fear of losing either the header or binary. Be careful, though: header/binary combined files can be very large and might slow down your local filesystem. A best practice is only to use combined header/binary files when absolutely necessary for file transfers. Note: header/binary combined files are usually automatically converted to header/binary separate files when processed by a Madagascar program.

===Additional documentation===

For more complete documentation on the RSF file format see the following links:

A [[Guide_to_RSF_file_format|gentle guide to the RSF file format]]

A [[RSF_Comprehensive_Description|detailed guide to the RSF file format]]

==Command line interface==
Madagascar was designed initially to be used from the command
line. Programmers create Madagascar programs (prefixed with the sf
designation) that read and write Madagascar files. These programs are
designed to be as general as possible so that each could operate
on any dataset in RSF format, provided you also supply the correct
parameters and have the right data type for the program.

===Using programs===
Madagascar programs follow the standard UNIX conventions for reading and writing RSF files to and from '''stdin''' and '''stdout'''. This is also the convention that Seismic Unix uses, so it should be familiar to SU users.
For example: the program '''sfattr''' allows us to get attributes about an RSF file (mean, standard deviation, min, max, etc.) To get the attributes for a pre-computed file, we might use
<pre>
sfattr < file.rsf
rms = 1.41316
mean = 0.999667
2-norm = 357.503
variance = 0.997693
std dev = 0.998846
max = 5.05567 at 36 8 27
min = -3.59936 at 18 9 6
nonzero samples = 64000
total samples = 64000
</pre>
We demonstrate how to read and write RSF files using '''sfwindow''' which is a program that allows us to select portions of an RSF file. When '''sfwindow''' is used without any additional parameters, we are able to make a copy of a file with a different filename. For example:
<pre>
sfwindow < file.rsf > file2.rsf
</pre>
gives us two files, file.rsf and file2.rsf which are identical but not the same file. If your intention is simply to copy a file, you can also use '''sfcp''' .
In addition to specifying files to read in and out on the command line we can specify the parameters for each program that are necessary for it to run, or to produce the desired result. The general format for specifying parameters on the command line is '''key=val''' , where '''key''' is the name of the parameter that you want to set, and '''val''' is the value of the parameter. There are four (4) types of values that are acceptable: integers, floating point numbers, booleans, or strings. Going back to the window program, we can specify the number of traces or pieces of the file that we want to keep like:
<pre>
sfwindow < file.rsf n1=10 > file-win.rsf
</pre>
===Self-documentation===
Of course, we can specify as many parameters as we'd like on the command line. To figure out which parameters are needed for a specific program, just type the name of the program with no input files our output files on the command line to bring up a program's self-documentation. For example, '''sfwindow''' 's self documentation is:
<pre>
NAME
sfwindow
DESCRIPTION
Window a portion of a dataset.
SYNOPSIS
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,,...)
PARAMETERS
float d#=(d1,d2,...) sampling in #-th dimension
largeint 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
largeint 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
USED IN
bei/dpmv/krchdmo
bei/dpmv/matt
bei/dwnc/sigmoid
bei/fdm/kjartjac
bei/fld/cube
bei/fld/shotmovie
bei/fld/synmarine
bei/fld/yc
bei/ft1/autocor
bei/ft1/brad
bei/ft1/ft2d
bei/krch/sep73
bei/sg/denmark
bei/sg/toldi
bei/trimo/mod
bei/trimo/subsamp
bei/vela/stretch
bei/vela/vscan
bei/wvs/head
bei/wvs/vscan
cwp/geo2006TimeShiftImagingCondition/flat
cwp/geo2006TimeShiftImagingCondition/icomp
cwp/geo2006TimeShiftImagingCondition/zicig
cwp/geo2007StereographicImagingCondition/flat4
cwp/geo2007StereographicImagingCondition/gaus1
167 more examples listed in:
/usr/local/RSFROOT/share/doc/madagascar/html/sfwindow.html
SOURCE
system/main/window.c
DOCUMENTATION
http://ahay.org/wiki/Guide_to_madagascar_programs#sfwindow
VERSION
1.3-svn
</pre>
The self-documentation tells us the function of the program, as well as the parameters that are available to be specified. The parameter format is type - name=default value [options] and then a short description of the parameter. File parameters request a name of a file. For example:
<pre>
file=file.rsf
</pre>
Note: strings with spaces must be enclosed in quotation marks
(e.g. 'my value') so that the Unix shell could interpret them correctly.

===Piping===
Sometimes we want to chain multiple commands together without writing intermediate Madagascar RSF files in the process. We can avoid making intermediate files by using another standard UNIX construct, pipes. Pipes allow us to connect the standard output from one Madagascar program to the standard input to another program without first writing to a file. For example we could do the following without pipes:
<pre>
sfwindow < file.rsf > file-win.rsf
sftransp < file-win.rsf > file2.rsf
</pre>
Or we could do the equivalent using pipes on one line:
<pre>
sfwindow < file.rsf | sftransp > file2.rsf
</pre>
Pipes simply make these statements more compact, and allow us to reduce the number of files that we need to save to disk. Piping is very powerful, because there is no limit to the number of statements that you can pipe together. For example:
<pre>
sfwindow < file.rsf | sftransp | sfnoise var=1 > file2.rsf
</pre>
If you're using multiple programs, and do not want to save the intermediate files, then pipes will greatly reduce the number of files that you have to keep track of.

===Interacting with files from the command line===
Ultimately though, 95% of your time using Madagascar on the command line will be to inspect and view files that are output by your scripts. Some of the key commands that are used to interact with files on the command line are:
*'''sfin''' , used to get header information,
*'''sfattr''' , used to get file attributes,
*'''sfwindow''' , used to select portions of RSF files,
*and '''sftransp''' , used to reorder files.
Here are detailed usage examples and explanations of what the above programs do:
'''sfin''' is one of the most used program on the command line, because most often we simply need to check the dimensionality of our files to make sure that we have them in the correct order.
<pre>
sfin file.rsf

file.rsf:
in="/var/tmp/file.rsf@"
esize=4 type=float form=native
n1=100 d1=0.004 o1=0 label1="Time" unit1="s"
n2=34 d2=0.1 o2=0 label2="Distance" unit2="km"
3400 elements 13600 bytes
</pre>
'''sfattr''' is also commonly used from the command line to check files for correct values. Most often, we use sfattr to ensure that files are not filled with zeros, or with NaN's after a long computation, or to make sure that the values are reasonable. sfattr can be used to obtain basic statistics about the files as well.
<pre>
sfattr < file.rsf

*******************************************
rms = 1
mean = 1
2-norm = 58.3095
variance = 0
std dev = 0
max = 1 at 1 1
min = 1 at 1 1
nonzero samples = 3400
total samples = 3400
*******************************************
</pre>
'''sfwindow''' is used to select subsets of the data contained in an RSF file for computation elsewhere. Typically, you specify the data subset you want to keep using, the n, j, and f parameters which specify the number of indices in the arrays to keep, the jump in indices, and the first index to keep from the file in the respective dimension. For example if we want to keep the 15th-30th time samples from the first axis in <tt>file.rsf</tt>, we might use the following command:
<pre>
sfwindow < file.rsf f1=15 n1=15 j1=1 > file-win.rsf
</pre>
'''sftransp''' is used to reorder RSF files for other programs to be used. For example:
<pre>
sftransp < file.rsf plane=12 > file-transposed.rsf
</pre>
swaps the first and second axes, so that now the first axis is distance and the second axis is time.
For more information about commonly used Madagascar programs please see the [[Guide_to_madagascar_programs|guide to Madagascar programs]].

==Plotting==

VPLOT provides a method for making plots that are small in size, aesthetically pleasing, and easily compatible with Latex for rapid creation of productio-quality images in Madagascar.
===VPLOT===
The VPLOT file format (.vpl suffix) is a self-contained binary data
format that describes in vector format how to draw a plot on the
screen or a page using an interpreter. Since VPLOT is not a standard
imaging format, VPLOT files must be viewed with
interpreter programs which, for historical reasons, are called pens. Each pen interfaces VPLOT with a
third-party graphing library such as X11, plplot, opengl, and
others. This flexibility makes VPLOT files almost as portable as
standard image formats such as: EPS, GIF, JPEG, PDF, PNG, SVG, and TIFF. Unlike rasterized
formats, VPLOT files can be scaled to any size without losing image
quality.
===Creating plots===
To generate VPLOT files, we need to pass our computed RSF files through VPLOT filters, that convert RSF data files to VPLOT files. The VPLOT filters are named by the type of plot that they produce. The following table lists all of the available VPLOT filters.
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="2" style="background:#ffdead;" | List of available plotting programs in Madagascar.
|-
| '''sfbox''' || make box-line plots
|-
| '''sfcontour''' || make contour plots
|-
| '''sfcontour3''' || make contour plots of 3D surfaces
|-
| '''sfdots''' || plot signal with lollipops
|-
| '''sfgraph''' || create line plots, or scatter plots
|-
| '''sfgraph3''' || generate 3-D cube plots for surfaces.
|-
| '''sfgrey''' || create raster plots or 2D image plots
|-
| '''sfgrey3''' || create 3D image plots of panels (or slices) of a 3D cube
|-
| '''sfgrey4''' || generate movies of 3-D cube plots
|-
| '''sfplotrays''' || make plots of rays
|-
| '''sfthplot''' || make hidden-line surface plots
|-
| '''sfwiggle''' || plot data with wiggly traces
|}

To actually create a plot, we can use the plotting programs on the command line in the same fashion that we would use a Madagascar program:
<pre>
sfspike n1=100 | sfnoise > file.rsf
sfgraph < file.rsf title="noise" > file.vpl
</pre>
===Visualizing plots===
In this example, we create a single trace full of noise and then send
it to sfgraph to produce a single VPLOT file, <tt>file.vpl</tt>. As
you may have noticed, this only creates the file which is useful for
saving the plot, does not allow us to visualize the data. To visualize
the data we need to use a '''pen''' , which tells your machine how
to actually draw the plot. A typical Madagascar installation will
have multiple pens available for you to use. By default, you should
use '''sfpen''' which will pick the best pen available for you.
You can use '''sfpen''' to visualize your plots in the following
manner:
<pre>
sfpen < file.vpl
</pre>
This will pop up a screen on your window with the plot shown. Depending on which pen you are using you may be able to interact with the pen interface to control various parameters of the plot as shown by the buttons at the top of the screen. Depending on the pen that you are using, there may be keyboard shortcuts to many of the buttons. NOTE: '''oglpen''' uses a mouse interface that can be accessed by right-clicking on the plot.

===Converting VPLOT to other formats===
If you want to build reports or documents using other programs, or want to send your images to someone who does not have Madagascar you will need to convert your VPLOT files to other image formats for transfer. To convert a VPLOT plot to another format use the tool '''vpconvert''' .
'''vpconvert''' allows you to convert VPLOT files to any of the following formats, provided that you have the appropriate third-party libraries installed:

*avi,
*eps,
*gif,
*jpeg/jpg,
*mpeg/mpg (movie format),
*pdf,
*png,
*ppm,
*ps,
*svg,
*and tif.
Here's an example of how to use '''vpconvert''' :
<pre>
vpconvert file.vpl format=jpeg
</pre>
NOTE: details on how to install these third-party libraries are not
included with the Madagascar library, and we provide no support on
installing them. Most users will be able to install them using either
package management software (on Linux, Windows, and Mac) or
pre-compiled binaries. The PS and EPS support is provided by default.

==Scripting Madagascar==
Madagascar's command line interface allows us to create, manipulate and plot data. Often though, we want to create scripts that will perform these operations automatically for us. Scripting is especially important when processing large amounts of data, or performing a complex chain of file manipulations in order to ensure that operations are completed in the right order or with proper parameters.
In Madagascar, there are two main ways of creating scripts: shell scripts, and Python scripts using SCons.
===Shell scripting===
Shell scripting is the first option for creating scripts. In shell scripting we simply copy the command lines that we would use and paste them into a file that is recognized by either BASH, C-shell or another shell of your choosing. Shell scripting may be familiar to users of other packages such as SU, because it is the primary method of scripting there. An example of a Madagascar shell script is shown below:
<syntaxhighlight lang="bash">
#!/bin/bash
sfspike n1=100 > file.rsf
< file.rsf sfgraph > file.vpl
</syntaxhighlight>
For simple processing flows, shell scripting is a quick and easy approach to saving your processing flow. However, shell scripts quickly become unmanageable when more complicated processing flows are used. Additionally, shell scripts have no way to avoid repeating commands that have already been successfully run, which causes shell scripts to spend a significant amount of time duplicating already completed work. Because of these issues, Madagascar's main scripting option is to use a build manager called SCons for scripting instead of shell scripts.

===SCons===
SCons is a build manager written in 100% Python. As a build manager, SCons keeps track of three items for each file built in the script: the name of the output file(s), the name of the input file(s), and the rule (Madagascar program(s) with options) used to build the output file(s) from the input file(s). The advantage to keeping track of these items is that SCons can then check to see if any of those items have changed and if so mark the output file to be rebuilt. If no changes are detected, and the output file already exists, then SCons ''skips'' the output file and goes onto building other files. This gives the user the ability to avoid re-running portions of their scripts that previously completed without issue, which is very important when working on processing flows with large datasets where individual commands may take hours to execute. SCons also tracks dependencies between various processing commands. For example, if command 2 depends on the ouptut of command 1, and the input to command 1 changes, then SCons will automatically know that the input to command 2 has changed and will re-run command 2 as well. Furthermore, SCons allows us to run multiple processing commands at the same time on computers with sufficient capabilities, further reducing the amount of time that it takes for us to process data in Madagascar. Now, we'll discuss how to create SCons scripts and use SCons on the command line.
===SConstructs and commands===
SCons scripts are called SConstructs. In order to use SCons, you must create an SConstruct in the local directory where you want to work. Since SCons is written in Python, an SConstruct is simply a text file written using Python syntax. If you don't know Python, you can still use SCons, because the syntax is simple.
First, a primer on Python syntax. In SConstructs we are going to deal with Python functions and strings. Python functions are simple, and should be familiar to anyone who has used a programming language. For example, calling a Python function, foo, looks like:
<pre>
One argument - foo(1).
Many arguments - foo(1,2,3,4,5,123)
</pre>
Python functions can take many arguments, and arguments of different types, but the syntax is the same. Python strings are also very similar to other programming languages. In Python anything inside double quotes is automatically considered to be a string, and not a variable declaration. However, Python also supports a few notations to indicate strings (or long strings) as shown below:
<syntaxhighlight lang="python">
"this is a string"
'this is a string'
"""this is a string"""
"'this is a string"'
</syntaxhighlight>
Somtimes in Python you will need to nest a string within a string. To do use one of the string representations for the outer string, and use a different one for the inner string. For example:
<syntaxhighlight lang="python">
"""sfgraph title="my plot" """ OR
''' sfgraph title="my plot" ''' OR
' sfgraph title="my plot" '
</syntaxhighlight>
Fundamentally, Madagascar's data-processing SConstructs are composed of only four commands: '''Fetch''' , '''Flow''' , '''Plot''' and '''Result''' . The main command is '''Flow''' . A '''Flow''' creates a relationship between the input file, the output file, and the processing command used to create the output file from the input file. The syntax for a '''Flow''' is:
<pre>
Flow(output file,input file,command)
</pre>
where, target and source are file names (strings), and command is a string that contains the Madagascar program to be used, along with the command line parameters needed for that program to run. For example:
<syntaxhighlight lang="python">
Flow("spike1","spike","scale dscale=4.0")
</syntaxhighlight>
creates a dependency relationship between the output file 'spike1' and the input file 'spike'. The dependency indicates that 'spike1' cannot be created without 'spike' and that if 'spike' changes then 'spike1' also changes. The relationship in this case is that 'spike1' should be 'spike' scaled by four times. The equivalent command on the command line would be:
<pre>
< spike.rsf sfscale dscale=4.0 > spike1.rsf
</pre>
'''Note: the file names of the input and output files do not need to include '.rsf' on the end of the files as SCons automatically adds the suffix to all of our file names.'''
Now that we can create relationships between files using '''Flow''' s, we can create an SConstruct to do all of our data processing using SCons. However, we often want to visualize the results of our processing in order to quality control the results. In order to create '''Plot''' s (or other visualizations) in Madagascar we have two additional SCons commands: '''Plot''' and '''Result''' . '''Plot''' and '''Result''' tell SCons how to use Madagascar's plotting programs to create visualizations of files on the fly after they have been computed. The syntax for both '''Plot''' and '''Result''' is as follows:
<pre>
Plot(input file, command)
</pre>
OR
<pre>
Result(input file, command)
</pre>
In both cases, the '''Plot''' or '''Result''' command tells SCons to build a VPLOT file with same file name as the input file (with the .vpl suffix instead) from the input file using the command provided. For example, if we want to make a graph of a file we could use:
<syntaxhighlight lang="python">
Plot("spike1","sfgraph pclip=100")
</syntaxhighlight>
Behind the scenes, SCons establishes that we want to use "spike1.rsf" to create a '''Plot''' called "spike1.vpl" using sfgraph. The equivalent command line operation is:
<pre>
< spike1.rsf sfgraph pclip=100 > spike1.vpl
</pre>
'''Result''' can be used in the same way as '''Plot''' , illustrated above.
At this point, you might be asking yourself, what's the difference between '''Plot''' and '''Result''' ? The answer is that '''Plot''' creates all VPLOT files in the local directory, whereas '''Result''' creates its VPLOT files in a subdirectory called <tt>Fig</tt>. <tt>Fig</tt> is a location used to store '''Plot''' s that we want to later use when creating papers using LATEX. By default, you should use '''Plot''' when creating visualizations. Only use '''Result''' when you want to save something to be used in a paper. Note: since the VPLOTs from '''Plot''' and '''Result''' are placed in different locations you can use both '''Plot''' and '''Result''' for a single RSF file, but create two different plots for the same file.

===Creating an SConstruct===
Now that we have the three SConstruct commands, we can write our first SConstruct. To do so, open the SConstruct file in your favorite text editor. Before we can create any '''Flow''' , '''Plot''' or '''Result''' statements we have to add a first statement to the SConstruct. Enter the following statement (verbatim) into your new SConstruct:
<pre>
from rsf.proj import *
</pre>
This statement tells SCons where to find the '''Flow''' , '''Plot''' and '''Result''' commands, and must be included in '''every''' SConstruct.
After that statement has been entered, you can enter as many '''Flow''' , '''Plot''' and '''Result''' commands as you wish making sure to use proper syntax. It's helpful to use a text editor that has Python syntax highlighting, as that will help you find and remedy strings that are not closed. You can also create Python comments using the <math>\#</math> mark to indicate the beginning of a comment to help document your SConstructs.

Lastly, you must include the following statement at the end of your SConstruct:
<syntaxhighlight lang="python">
End()
</syntaxhighlight>
This statement tells SCons that the script is done and that it should not look for anything else in the script. Make sure to include this statement as the very last item in every SConstruct.
Here's a sample SConstruct:

<syntaxhighlight lang="python">
from rsf.proj import * # Remember, this statement comes first... ALWAYS
Flow("spike",None,"sfspike n1=100 k1=50")
# None is a trick, see Advanced SCons for more information
Flow("spike1","spike","sfadd scale=4.0")
Flow("noise","spike1","sfnoise")
Plot("spike",'sfgraph title="spike" ' ) # Note string nesting
Plot("spike1",'sfgraph title="spike1" ')
Plot("noise",'sfgraph title="noisy" ')
Result("noise",'sfgraph title="noisy" pclip=75 ')
End() # Remember, this always ends the script.
</syntaxhighlight>
Note: you do not have to order your '''Flow''' , '''Plot''' and '''Result''' commands as shown above. You can mix '''Flow''' , '''Plot''' and '''Result''' in any order. SCons automatically establishes the relationships between related files and commands.

===Executing SCons===
Now that you have an SConstruct, you can start processing data the Madagascar way. To do so open a terminal and navigate to the local directory where your SConstruct is located. To execute your SConstruct simply run: '''scons''' . When you run SCons, it will check to make sure that all necessary dependencies are found and that all of your commands inside the SConstruct are valid. If not, SCons will return an error message showing you where you made a mistake. If everything is OK, then SCons will begin creating your files in the local directory and will output its progress as it executes the Madagascar programs on the command line. For example, running the sample SConstruct from above should show something similar to the following output:
<pre>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
/opt/rsf/bin/sfspike n1=100 k1=50 > spike.rsf
< spike.rsf /opt/rsf/bin/sfadd scale=4.0 > spike1.rsf
< spike1.rsf /opt/rsf/bin/sfnoise > noise.rsf
< spike.rsf /opt/rsf/bin/sfgraph title="spike" > spike.vpl
< spike1.rsf /opt/rsf/bin/sfgraph title="spike1" > spike1.vpl
< noise.rsf /opt/rsf/bin/sfgraph title="noisy" > noise.vpl
< noise.rsf /opt/rsf/bin/sfgraph title="noisy" pclip=75 > Fig/noise.vpl
scons: done building targets.
</pre>
If the execution of scons ends with, "scons: done building targets" then the script completed successfully. Check your local directory for your output files.

===Common errors in SConstructs===
There are two common errors that most users will experience when executing SConstructs: missing dependency errors, and misconfiguration errors. We'll demonstrate both of these errors to help new users troubleshoot them below.
The first error is caused by missing a dependency in the SConstruct. To introduce this error into your SConstruct modify the sample SConstruct from above to the following:
<syntaxhighlight lang="python">
from rsf.proj import * # Remember, this statement comes first... ALWAYS
Flow("spike1","spike","sfadd scale=4.0")
Flow("noise","spike1","sfnoise")
Plot("spike",'sfgraph title="spike" ' ) # Note string nesting
Plot("spike1",'sfgraph title="spike1" ')
Plot("noise",'sfgraph title="noisy" ')
Result("noise",'sfgraph title="noisy" pclip=75 ')
End() # Remember, this always ends the script.
</syntaxhighlight>
Now when you run '''scons''' , you should get an error message:
<pre>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
scons: *** [spike1.rsf] Source `spike.rsf' not found, needed by target `spike1.rsf'.
scons: building terminated because of errors.
</pre>
In this case, SCons tells you exactly which file is missing and which output file is missing one of its dependencies. To solve this problem, add the '''Flow''' to create 'spike' to the SConstruct. If your SConstruct uses a file that is not created inside the SConstruct, and is complaining about a missing dependency, then make sure the file you are looking for is in a location that the SConstruct can access.
The second error, is caused by having a misconfigured command. To demonstrate this type of error change your SConstruct to:
<syntaxhighlight lang="python">
from rsf.proj import * # Remember, this statement comes first... ALWAYS

'''Flow''' ("spike",None,"sfspike n1=100 k1=50")
# None is a trick, see Users 4 for more information
'''Flow''' ("spike1","spike","sfasd scale=4.0")
# HERE IS THE ERROR, NOTE sfasd instead of sfadd
'''Flow''' ("noise","spike1","sfnoise")

'''Plot''' ("spike",'sfgraph title="spike" ' ) # Note string nesting
'''Plot''' ("spike1",'sfgraph title="spike1" ')
'''Plot''' ("noise",'sfgraph title="noisy" ')

'''Result''' ("noise",'sfgraph title="noisy" pclip=75 ')

End() # Remember, this always ends the script.
</syntaxhighlight>
In this case, we've introduced a typo into one of our commands. When running scons, the result is:
<pre>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
/opt/rsf/bin/sfspike n1=100 k1=50 > spike.rsf
< spike.rsf sfasd scale=4.0 > spike1.rsf
sh: sfasd: command not found
scons: *** [spike1.rsf] Error 127
scons: building terminated because of errors.
</pre>
Again, the error message is pretty descriptive and could help you track down the error relatively quickly. It's important to note that in this case, the error was caught after SCons tried to execute the command and failed to do so, whereas the dependency error was caught before any commands were executed. This means that this typo error would kill a script that's been running a long time without any issues up till that point. Fortunately, SCons would restart the script at the point of failure thereby saving you all the additional time to recompute everything before this point in the script.
These are only two of the most common errors that novice users will see. For additional information about debugging SConstructs, or for exceptionally strange errors please consult the [[SCons|online documentation]] or the RSF users mailing list.

===Additional SCons commands===
Here are some additional SCons commands that are useful to know.
====Viewing Plots====
If you're running an SConstruct and want to view the plots that it generates as it creates them, then you can use: '''scons view''' to force SCons to show the plots interactively. Doing so allows you to view your output at runtime and to stop the SConstruct as it's running if you don't like what you see.
====Viewing only one plot====
If you want to view the plot associated with only a single file you can tell SCons to view that plot by using the command: '''scons file.view''' where file is the filename of the item that you want to view. For example: scons spike.view would show the plot of the spike.rsf file. The advantage to using this command is that SCons will only build the dependencies needed to view that specific plot, which can save you a lot of time in longer processing scripts.
====Building specific targets====
If you want to build a specific RSF file, or a few specific RSF files you can simply specify them on the command line when you execute SCons as follows: '''scons file.rsf file2.rsf file3.rsf ...''' . The advantage to doing this, is that SCons will only build those files and their dependencies instead of running through the entire script.
====Cleaning up====
After we've executed our SConstruct and viewed the results of the processings flow, we might decide that we want to clean up our project and go work on something else. Normally, one would have to delete all of the files and then move on, but SCons automates this process using the command: '''scons -c''' . Simply execute it in the local directory and SCons will remove all of the built RSF files, and VPLOT files. SCons will not remove files that it does not have rules for.
====Dry-runs====
Sometimes we want to test an SConstruct through the end of the script without waiting for it to run completely. To do so, we can use '''scons -n''' which tells SCons to simulate an actual execution. During a dry-run SCons will check all of the commands, and dependencies to ensure that they exist and are properly configured. If not, then SCons will tell you which commands are misconfigured. This command can save you hours of debugging! Use it liberally.
====Parallel executions====
For long scripts we can use parallel execution to run multiple processing commands at the same time. Parallel execution requires that the commands can function independently of one another (i.e. there are commands that do not depend on each other's output). To use parallel execution use: '''pscons''' which launches the maximum number of parallel jobs that your computer can handle at once. Parallel execution can greatly speed up your processing flows if SCons can parallelize it. In the worst case, SCons won't be able to parallelize your script and it will run at the same speed as if you just used '''scons'''.

===Final thoughts===
At this point you should have a solid understanding of how to use SCons and create SConstructs to script your Madagascar processing flows. Admittedly, SCons is somewhat complicated and difficult to understand at first, but don't give up. By using SCons, you are able to create powerful Madagascar scripts that are completely reproducible and enjoy the benefits of using a powerful build management system. However, we have not shown you the most useful aspects of SCons, which are demonstrated in the next tutorial, where we show how to integrate Python with SCons, thereby making processing flows that are even more powerful.

==Advanced SCons==
Now that you have a grasp of how to use SCons to put together simple processing flows, we're going to show you how to abuse SCons to make more advanced processing flows that can handle multiple input and output files properly. Additionally, we're going to demonstrate some SCons tricks that make your life easier, and allow you to work faster, and smarter.
===Multiple input files===
Many Madagascar programs require multiple input files and/or output multiple files. In order for SCons to properly recognize that these additional files are dependencies for a specific output file we have to change the syntax that we use for '''Flow''' , '''Plot''' and '''Result''' statements. To do so, we'll need to use Python lists to help us keep everything together when using our SCons commands. We first discuss the case where we need multiple input files.
An example of a Madagascar program that requires multiple input files is '''sfcat''' . For reference, sfcat is used to concatenate multiple files together, essentially a file manipulation program. For example, we might use sfcat on the command line in the following fashion:
<pre>
< file.rsf sfcat axis=2
file1.rsf file2.rsf file3.rsf file4.rsf > catted.rsf
</pre>
To replicate this behavior using SCons we need to tell our '''Flow''' statements about the presence of multiple input files. '''Important: if we do not indicate to SCons that we have multiple input files then the dependency chain will not be correct and we cannot guarantee our results are correct''' . We can easily tell SCons of the presence of multiple input files by using a Python list as our input file, instead of a string:
<syntaxhighlight lang="python">
Flow('catted',['file','file1','file2','file3','file4'],'sfcat axis=2 ${SOURCES[1:-1]}')
</syntaxhighlight>
or, equivalently,
<syntaxhighlight lang="python">
Flow('catted','file file1 file2 file3 file4','sfcat axis=2 ${SOURCES[1:-1]}')
</syntaxhighlight>
As you may have noticed, there are two new items in this '''Flow''' statement, but let's start by discussing only the list of file names: '''['file','file1','file2','file3','file4']''' . The list of file names is simply a Python list of strings that contains each of the names of the files that we want to use in this Flow command. As usual, we don't have to append the '.rsf' suffix to the end of these names because SCons adds it for us.
The second new part to the '''Flow''' command is:
'''${SOURCES[1:-1]''' }, referred to as the SCons source list,
which tells SCons about the presence of additional input files in the
command, and to substitute the names into the command automatically.
Without this command, SCons would not include the files in the final
command. As an example of what the SCons source list does, compare
the two SConstructs below against one another. The top is correct,
the bottom is incorrectly configured:
<syntaxhighlight lang="python">
# Correct
from rsf.proj import *
Flow('file',None,'spike n1=100')
Flow('file1',None,'spike n1=100 mag=2')
Flow('file2',None,'spike n1=100 mag=3')
Flow('file3',None,'spike n1=100 mag=4')
Flow('file4',None,'spike n1=100 mag=5')
Flow('catted',['file','file1','file2','file3','file4'],
'sfcat axis=2 ${SOURCES[1:-1]}')
End()
</syntaxhighlight>
<syntaxhighlight lang="python">
# Wrong
from rsf.proj import *
Flow('file',None,'spike n1=100')
Flow('file1',None,'spike n1=100')
Flow('file2',None,'spike n1=100')
Flow('file3',None,'spike n1=100')
Flow('file4',None,'spike n1=100')
Flow('catted',['file','file1','file2','file3','file4'],'sfcat axis=2')
End()
</syntaxhighlight>
If you noticed the command line output from SCons, you would find that for the incorrect SConstruct, SCons ran the following command:
<pre>
< file.rsf sfcat axis=2 > catted.rsf
</pre>
which is not correct. This is because SCons was not informed that the additional sources actually are used inside the command and did not substitute them in.
The SCons source list contains a reference to all of the file names that we passed in our Python list earlier. In order to access those names we have to use a specific notation, but it is essentially a Python list enclosed in curly brackets that begins with a $. Since the source list is a Python list, we can get the file names in a few ways if we follow standard Python list conventions. Standard Python list conventions are:
*List indexing starts with index 0,
*Lists may be negatively indexed, which returns the items from the end (e.g. LIST[-1]),
*Lists may be sliced using the LIST[start:end] notation, where start and end are indices,
*List slicing indices are inclusive for the starting index, and exclusive for the ending index (e.g. LIST[0:4] returns LIST[0],LIST[1],LIST[2],LIST[3] but NOT LIST[4],
*Open slicing indices may be used (e.g. LIST[2:] gets everything from index 2 to the end, and LIST[:4] returns everything from 0 to but not including 4).
*Negative and positive indices may be used together (e.g. LIST[1:-1] returns all elements but the first and last).
These are the most useful conventions to remember, and the ones you will most frequently see. Please see the Python documentation (freely available online) for more information about dealing with Lists.
Using the above conventions the following '''Flow''' statements are all equivalent for lettings SCons know about the presence of multiple input files:
<syntaxhighlight lang="python">
Flow('catted',['file','file1','file2','file3','file4'],
'''
sfcat axis=2 ${SOURCES[1]} ${SOURCES[2]}
${SOURCES[3]} ${SOURCES[4]}
''')
Flow('catted',['file','file1','file2','file3','file4'],
'''
sfcat axis=2 ${SOURCES[1:5]}
''')
Flow('catted',['file','file1','file2','file3','file4'],
'''
sfcat axis=2 ${SOURCES[1:-1]}
''')
</syntaxhighlight>
Note: never use SOURCES[0] because SOURCES[0] corresponds to 'file' which is already used by SCons for standard input. Also, never use open slicing on the SOURCES list, because at the end of the SOURCES list are extra items added by SCons for safe keeping that will break the command if accidentally used.

===Multiple outputs===
For multiple outputs, we can use the same conventions as before, except we specify a list of output files instead of input files, and we use the TARGETS SCons list, instead of SOURCES. For example:
<syntaxhighlight lang="python">
Flow(['pef','lag'], 'dat', 'sflpef lag=${TARGETS[1]}').
</syntaxhighlight>

===None inputs===
Sometimes, '''Flow''' s are created that don't have an input file. For example, files created using '''sfspike''' do not require input files. To get around the need for an input file, we can use the Python keyword '''None''' , equivalent to NULL in C or Java, to indicate to SCons that no input file is needed. For example:
<syntaxhighlight lang="python">
Flow('spike',None,'sfspike n1=100')
</syntaxhighlight>

===Toggling standard input and standard output===
When None inputs are used, then standard input is no longer needed and can be disabled. To turn off standard input on a '''Flow''' , add another argument to the '''Flow''' statement:
<syntaxhighlight lang="python">
Flow('spike',None,'sfspike n1=100',stdin=0)
</syntaxhighlight>
When SCons runs this '''Flow''' , the output command line will be:
<pre>
sfspike n1=100 > spike.rsf
</pre>
Likewise, we can toggle output to standard output as well. Standard output has two options, redirect to null or completely off. For some programs we need to redirect standard output to null, and others will require standard output to be completely off. To toggle standard output off use the following syntax:
<syntaxhighlight lang="python">
Flow('spike',None,'sfspike n1=100',stdout=-1)
</syntaxhighlight>
OR to redirect to <tt>/dev/null</tt>:
<syntaxhighlight lang="python">
Flow('spike',None,'sfspike n1=100',stdout=0)
</syntaxhighlight>

===Plots with a different output name===
Occasionally, you might want to create a plot with a different name than the input file. For example, a file might have multiple axes, and you could window along one of the axes, to create multiple graphs from a single input file. To distinguish between the different plots, you can rename the output files from Plot and Result commands using a syntax similar to Flow:
<syntaxhighlight lang="python">
Plot('output','input','sfgraph')
</syntaxhighlight>
This Plot command will produce output.vpl instead of input.vpl. In this way, you can create multiple visualizations of the same file. This applies to Result commands as well.

==Integrating Python with SCons==
Because SCons is written in Python, we can take advantage of all the features of the Python programming language. By doing so, we are able to make our life a lot easier by: compartmentalizing build commands, creating functions for commonly used scripts, organizing our scripts to make them easier to understand. Instead of giving an exhaustive tutorial of the combination of SCons and Python, we're going to demonstrate a few of the more commonly features of Python inside of SConstructs. We leave it to the end user to develop additional techniques that further exploit the power of Python.
===A forewarning===
While Python and SCons are compatible with one another they are not completely interchangeable. To understand why that is the case, you need to understand the underlying design of SCons. SCons is a ''declarative'' language, which means that you tell SCons what to do through the: Flow, Plot, and Result commands, and then SCons decides how and when to execute those commands. Python on the other hand is ''imperative'' , which means that as Python reads a Python script, it executes the commands immediately. Python does not take time to decide how or when to execute your commands. This point causes a bit of confusion to users who start to combine Python and SCons together because they expect SCons commands to execute in the order that they place them, which is not the case. Because of this, you may not be able to use certain Python features in their native Python way. For example, loops which require repeated computation, and whose results depend on the result of the last iteration are not possible using SCons. It is also not usually possible to use Python variables that change during execution with SCons because the variable value that SCons will use is ''always'' the last value of the variable. Typically, you cannot use conditional statements in SCons, where the choice depends on a file that SCons will build.
To be safe, you should always assume that whatever Python does happens ''before'' SCons starts running commands.
===Variables===
The most effective way to combine SCons and Python is to use Python to manage important variables for your scripts. For example, if you want to test a variety of values for a certain processing Flow, then you might save the value to a variable and then let Python format it correctly for you, instead of changing the string each time you want to run a new test. You can also save all your variables in a convenient location and then easily change them to test different parameters as well. For example:
<syntaxhighlight lang="python">
nx = 100
nz = 100
Flow('model',None,'sfspike n1='+str(nx)+'n2='+str(nz))
</syntaxhighlight>
Note: variables must be converted to strings in order to be combined into the command statements. Because these variables are converted using string concatenation, there is a possibility that a user could give a value of a wrong type.

===String substitution===
While using variables is convenient, formatting them in the fashion shown above is not convenient. An easier way to format variables for strings is to use string substitution. String substitution works in the same way as the C - printf function works, i.e. we place markers that indicate where values should be substituted and what format they should be in. The above example using string substitution is:
<syntaxhighlight lang="python">
nx = 100
nz = 100
Flow('model',None,
'''
sfspike n1=%d n2=%d
''' % (nx,nz) )
</syntaxhighlight>
In this statement, both nx, and nz are formatted as integers, and contained inside a tuple. All variables to be used for string substitution must be contained within the tuple at the end of the string statement. For reference, all C-printf like formatting choices are available in Python as well. Note: treat booleans as integers in Python.

===Dictionaries===
When scripts have a large number of variables, it is often easier to contain them within a Python dictionary instead of letting them float around the script. Dictionaries are declared in key=value format in Python using the '''dict''' keyword. For example:
<syntaxhighlight lang="python">
parameters = dict(nx=100,nz=100,verb=True,final_file='output123')
</syntaxhighlight>
To access variables from within the dictionary, we use list-like indexing where the index given is the name of the variable that we want to access:
<syntaxhighlight lang="python">
nx = parameters['nx'] # Returns 100
</syntaxhighlight>
We can also set variables within the dictionary, or modify their values after the initial declaration:
<syntaxhighlight lang="python">
parameters['nx'] = 200 # Sets nx to 200
parameters['ny'] = 150 # Adds ny, and sets it to 150
</syntaxhighlight>
To use the dictionary for string substitution, we only need to modify our formatters to include the key names of the variables that we wish to access from the dictionary. For example:
<syntaxhighlight lang="python">
Flow('model',None,
'''
sfspike n1=%(nx)d n2=%(nz)d
''' % parameters )
</syntaxhighlight>
Notice that the formatters now have the name of the variable inside parentheses: %(nx)d before the formatting expression. Then, the entire dictionary is passed to the string for substitution. At runtime, Python places the values for the keys from the dictionary into the string. If the values are the wrong type, or the key does not exist in the dictionary, then Python will throw an error at runtime, and prevent you from running with a bad value.

By using dictionaries with string substitution, we can add flexibility to our scripts, and improve their readability, which ultimately improves the ability of others to reproduce our work. Thus, you should strive to use dictionaries wherever possible in your SConstructs.

===Loops===
Perhaps the most useful construct from Python that can be added to SConstructs are loops. By using loops, we can automate many redundant processes. To use a Python loop we just use the standard Python syntax in the following fashion:
<syntaxhighlight lang="python">
from rsf.proj import *
for i in range(10):
count = str(i) # Convert integer to string
Flow('spike-'+count,None,'sfspike n1=100 mag='+count)
Plot('spike-'+count,'sfgraph')
End()
</syntaxhighlight>
In order for the loop to work, you need to make sure that all the files that are created have a unique file name. The easiest way to do so is to use the loop index in the filename, the count variable in this case. The count variable must be a string, because only strings can be concatenated together in Python. If you want to make more complicated file names (from nested loops) then examine the printf like syntax for Python strings.
All the usual Python rules apply to these loops. Typically, for loops are easier to understand than while loops in Python, and so we recommend using for loops for most purposes.

===Functions===
Python functions are incredibly useful because you can compartmentalize repeated uses of commonly used '''Flow''' s, and then use them in multiple SConstructs. For the best use of Python functions you should use the following conventions:
*always use keyword=value arguments to help document your code,
*list file names for input and output first, then other arguments,
*use default values for all arguments, even if they are None,
*use the locals() dictionary to get the values of the arguments,
*always perform an action inside the function (i.e. create a Flow, Plot or Result),
*do not return anything from the function,
*and always accept **kwargs as the last argument to allow for dictionary substitution.
Here's an example of a well-defined function to create a Ricker wavelet with a peak frequency specified by the user:
<syntaxhighlight lang="python">
def ricker(out='wave',freq=20.0,kt=100,nt=1001,dt=0.01,ot=0.0,**kwargs):
Flow(out,None,
'''
spike n1=%(nt)d o1=%(ot)f d1=%(d1)f
nsp=1 mag=1.0 k1=%(kt)d l1=%(kt)d |
ricker1 frequency=%(freq)f
''' % locals())
</syntaxhighlight>
Notice that we use the python function '''locals()''' for string substitution. This function returns a dictionary that contains only the names and values of the named arguments for the function.
To call this function, you can use it as a normal Python function. Since there are default arguments, not all arguments need to be passed as long as you are OK with the default value.
<syntaxhighlight lang="python">
ricker('wave',freq=30,kt=50)
</syntaxhighlight>
If you are using a dictionary that has all of your variables in it, then you can call the function using explicit parameter fetching:
<syntaxhighlight lang="python">
ricker('wave',parameters['freq'],parameters['kt'],...)
</syntaxhighlight>
where you have to explicitly grab certain variables from the parameter dictionary. Conversely, you can use automatic parameter fetching:
<syntaxhighlight lang="python">
ricker('wave',**parameters)
</syntaxhighlight>
which will look for all the named arguments to the ricker function in the parameter dictionary, and send their values to the function. When there are many parameters, and you have already set them in the dictionary, then automatic parameter fetching is the best way to go.

===Modules===
Of course, functions can be compiled into groups and then placed into Python modules for widespread re-use throughout your SConstructs. Commonly used Python modules are currently located in <tt>$RSFROOT/book/Recipes</tt>, which is where you should place your modules as well. As usual, you must use correct Python syntax to access functions contained within modules. For example, if you create a module called myutil.py, then you can access your functions in the following manner:
<syntaxhighlight lang="python">
import myutil
myutil.ricker(...)
</syntaxhighlight>

===Classes===
The least used, but most powerful part of Python that you can bring into your SConstructs are Python classes. For example, if you are writing a script to process multiple models in the exact same way, but that have different parameters you would have to write separate Flow statements to process each of them, OR you could write a Python class that takes the model parameters and uses those parameters to generate Flow statements automatically, similar to functions. However, a class can allow you to group functions together into a single coherent body and allow you to drastically reduce the amount of code that must be reused.
We refer the reader to the Python documentation for more information on creating and using classes.

===Final thoughts===
Congratulations on completing the Madagascar User tutorial series. Now, you should have all the tools to: use Madagascar programs, write SConstructs to script your processing flows, and combine Python with SCons to make powerful scripts that can process data in ways not previously possible. From here, you can continue learning about how to write your own Madagascar programs, or learn about how to make reproducible documents using the Madagascar framework.

=Authors=
The Authors tutorials demonstrate how one can create reproducible documents using the Madagascar processing package and LATEX together. By the end of the Authors tutorials, you should be able to:

*build papers, including: SEG and EAGE abstracts, manuscripts for Geophysics, and handouts,
*build a CSM thesis,
*build a CWP report,
*build slides,
*and add/modify Latex class files to add your custom document formats to Madagascar.
After completing this tutorial series, you will be able to maximize your research productivity using Madagascar.

==Getting started==
Before you can get started writing reproducible documents, you need to ensure that your system is properly setup. This section of the tutorial will walk you through the setup process, which can be somewhat difficult and laborious depending on which operating system you are on, as you will need a full installation of LATEX and additional LATEX class files that Madagascar makes available to you. The good news is that this configuration only happens once.
===Downloading LATEX===
To begin, you need to download a full installation of LATEX for your operating system. To do so, you may need to contact your system administrator. If you have administrative rights, then you can download a full install for your platform from the following locations:

*Linux - use your package management software to install a full texlive (you may need additional packages depending on your distribution).
*Mac - install MacTex http://www.tug.org/mactex/2011/.
*Windows - install MikTex http://miktex.org/.
The respective downloads typically are quite large and take a substantial amount of time to complete, so start the download and come back later. Once your download is done, test your installation by executing '''pdflatex''' at the command line. If everything works fine then continue onwards. For Mac users, you may need "sudo port install texlive-latex-extra".

===Downloading SEGTeX===
The next step is to download the SEG\TeX class files, which tells LATEX how to build certain documents that we commonly use. To download SEG\TeX first '''cd''' to a directory where LATEX can find additional class files. This directory is typically operating system dependent, and may be distribution dependent for Linux. Typically, you can place these files in '''$HOME/texmf''' . Otherwise, you will need to place them in the root installation for Latex which can be found by searching for the basic class files, such as article.cls. On a Mac the typical place to put these files is '''$HOME/Library/texmf''' . In any case, once you are in the proper location, then use the following command to download the class files (using subversion):
<pre>
svn co https://segtex.svn.sourceforge.net/svnroot/segtex/trunk texmf
</pre>
or download a stable release from http://sourceforge.net/projects/segtex/files/ and unpack it into the <tt>texmf</tt> directory.
===Updating your LATEX install===
Once the class files are successfully downloaded, you will need to run '''texhash''' or '''texconfig rehash''' to update LATEX about the new class files. For reference, a successful run of '''texhash''' produces the following output:
<pre>
jgodwin$ texhash
texhash: Updating /usr/local/texlive/2010/../texmf-local/ls-R...
texhash: Updating /usr/local/texlive/2010/texmf/ls-R...
texhash: Updating /usr/local/texlive/2010/texmf-config/ls-R...
texhash: Updating /usr/local/texlive/2010/texmf-dist/ls-R...
texhash: Updating /usr/local/texlive/2010/texmf-var/ls-R...
texhash: Done.
</pre>
To determine if these files are found successfully, go into $RSFROOT/book/rsf/manual and run '''scons manual.read''' . If LATEX complains about being unable to find the class files then you should re-run texhash, or make sure that your class files are in the proper location. If you are still having difficulties, then contact the [[SEGTeX|SEGTeX webpage]] or the user mailing list for further information.

==Papers==
With LATEX installed, we can now create reproducible documents using Madagascar. First, we will demonstrate how to build shorter, less complicated documents using Madagascar, such as SEG/EAGE abstracts, Geophysics articles, and handouts. All of these papers have similar build styles, so the rules for building each respective paper have only slight differences from one another. Instead of talking in detail about each of these documents, we illustrate the basic idea for each of the documents, and provide examples that demonstrate the particulars for each type of document.
===Paper organization===
All Madagascar papers expect a specific organization to your directories. In particular, you are expected to have a paper-level directory where your '''tex''' files and main SConstruct will exist. These files will tell Madagascar how to build your documents for a particular project. You can have multiple documents built from the same location, using the same SConstruct as we will demonstrate later.
Below the paper directory, are the individual "chapters" that contain the processing flows used to generate the plots or process the data that you wish to use in your reproducible documents. Ideally, each "chapter" directory correlates to the processing flows or examples in each chapter or section for your paper. Additionally, each "chapter" contains its own SConstruct that operates independently of the paper SConstruct one level above it. Furthermore, inside the "chapter" folder, Madagascar needs to have a '''Fig''' folder that contains all of the VPLOT files that were created using Result commands during processing. This folder is automatically created during processing using SCons, so you don't need to manually create it. It is important to note that Madagascar can only locate VPLOT files that are in this file hierarchy for use in your papers. The figure below illustrates the folder hierarchy as well.
Note: "chapter" folders may be symbolic links that point to folders elsewhere on the file system. This trick can be useful to reuse figures without copying files and folders around to various folders. If you use symlinks, make sure to avoid editing files that are symbolically linked, as your changes may propagate in unintended ways to other projects and papers.
[[Image:dir.png|frame|center|The organizational hierarchy for Madagascar paper directories.]]

===Locking figures===
Once you have created the necessary folder hierarchy with your "chapters" and processing flows, then go ahead and run your processing SConstructs. After those are finished, you need to lock your figures using '''scons lock''' . '''scons lock''' tells Madagascar that the figures you have generated are ready to go into a publication, and will store them in a subfolder of the '''$RSFFIGS''' directory for safe keeping. Locked figures are used for document figures instead of the figures in your local directory, because they are locked and not still changing. If you change your plots but do not lock your figures, you will not see your figures change. Always make sure to lock your figures before building a document.
===TeX files===
Now that your figures are locked, you can create your first reproducible document in Madagascar. To do so, you will need to:
*make your TeX files, and
*make a paper SConstruct,
Before making a document, you need to create your TeX files in the paper level directory. For example, to create an EAGE abstract, you would create a main TeX file called: '''eageabs.tex''' which contains the content and TeX commands to build your abstract. Your TeX file can use all of the standard and expanded LATEX commands provided by any available packages on your system. It's important to remember that you should try and break apart your TeX files into manageable chunks, so that you can modify them independently, or reuse the content in other documents. For example, instead of having a single TeX file for your EAGE abstract, you could have a separate TeX file that contains: '''\input{...}''' statements that include additional TeX files for each section, such as the abstract, theory, discussion, conclusions, etc.
Additionally, Madagascar provides some convenience commands for often used LATEX functions. Here is a short description of some of those convenience commands that you may run across. Here's a brief list of these convenience functions:
*\plot,
*\multiplot,
*\sideplot,
*and more.
These convenience functions are not available for every type of document, but are demonstrated in documents where they are available. The definition for the convenience functions may be found in the LATEX class definitions listed at the end of this tutorial.

===Paper SConstructs===
One of Madagascar's aims is to make TeX files as layout-agnostic as possible. To do so, Madagascar automatically adds the TeX document preamble (including the LATEX document class information), the LATEX package inclusions, and end of document information at runtime. This allows you to generate multiple documents from a single TeX file by simply changing the SConstruct, instead of the TeX file.
Note: the paper SConstruct is only used to build papers. It contains no other information, and cannot be used to process data in the same SConstruct. This is why the paper SConstruct must exist in a separate directory from any processing SConstructs.
The paper SConstruct is very simple compared to most processing SConstructs, in that it contains only a few lines as shown below (in an example for an EAGE abstract):
<syntaxhighlight lang="python">
from rsf.tex import *
Paper('eageabs',
lclass='eageabs',
options='11pt',
use='times,natbib,color,amssymb,amsmath,amsbsy,graphicx,fancyhdr')
</syntaxhighlight>
The first section, '''from rsf.tex import *''' tells Madagascar to import Python packages for processing TeX files instead of the usual processing packages. Next, we call a '''Paper''' object, which takes the following parameters:
<pre>
Paper(name,lclass,options,use)
name - name of the root tex file to build.
lclass - name of the LaTeX class file to use.
options - document options for LaTeX class file.
use - names of LaTeX packages to import during compilation.
</pre>
All of the parameters are passed as strings to the Paper object. Parameters with more that one possible value (e.g. options and use) accept comma delimited strings as shown above.
To generate different types of documents, you simply change the '''lclass''' and options sent to the Paper object in the SConstruct for the respective document type. Since the documents that we are creating use custom LATEX document classes that require additional TeX commands to function properly, it is easier for us to provide you with a template instead of discussing the details of each document class. The templates for the documents can be found in the following directory: '''$RSFSRC/book/tutorial/authors'''.

===Templates===
To run the templates, you first need to generate the data used for them in the '''data''' directory inside of the '''$RSFSRC/book/tutorial/authors''' . To do so, run '''scons lock''' which will produce and lock the figures necessary. Then go into the template directory that you are interested in, and make a symbolic link to the data directory: '''ln -s ../data''' and a symbolic link to the BibTeX file: '''ln -s ../demobib.bib''' in the template directory. After those steps are made you can build and view the paper using '''scons''' or '''scons paper.read''' where paper is the name of the root tex file. Of course, if you want to remove all the generated files, then you can use '''scons -c''' to clean the directory.

===Handouts===
Handouts are informal documents that are loosely formatted, and very flexible. The handout example is located in: '''$RSFSRC/book/tutorial/authors/handout''' . Handouts do not require many additional arguments and are the most flexible of the documents discussed here.

===EAGE abstracts===
EAGE abstracts are short documents, with a few particular formatting tricks. In particular, EAGE requires the logo of the current year's convention to appear in the abstract. A template is available in: '''$RSFSRC/book/tutorial/authors/eage''' .

===SEG abstracts===
SEG abstracts are different from EAGE abstracts in that they require two-column formatting and are strictly limited to four pages not including references. To build an SEG abstract, we first build the abstract, and then build another document using the segcut.tex file that removes the references from the final pdf. An example is found in: '''$RSFSRC/book/tutorial/authors/seg''' .

===Geophysics manuscripts===
Geophysics manuscripts come in two flavors: the first is the manuscript prepared for peer review, and the second is the final document that would appear in a print version of Geophysics. The example shows how to build both from the same TeX files, which makes it painless to transition the formatting between the two documents. An example is located in: '''$RSFSRC/book/tutorial/authors/geophys''' . Make sure to use the template as there are quite a few additional TeX commands that have to be used to get the correct formatting.

===CWP reports===
CWP reports are slightly more complicated then most documents in that they require substantial modification to get the proper formatting. The CWP template is available in '''$RSFSRC/book/tutorial/authors/cwp''' .

==Slides==
Additionally, one can create presentation slides using LATEX and Madagascar together. To create slides, we use the Beamer class files that have been customized for the CWP. Slides have distinctly different commands then regular documents, so be sure to examine the template before diving in. The template is in: '''$RSFSRC/book/tutorial/authors/slides''' .

==Theses==
One can also create very complex documents using Madagascar in a reproducible way. To iillustrate this point we provide a template for building a thesis for the Colorado School of Mines. This template is quite heavily modified, and requires substantial modification due to all the formatting requirements. If you want to include a thesis template for another institution then you can do so by examining this template along with the CSM class files. The template is located in: '''$RSFSRC/book/tutorial/authors/thesis''' .

==Books==
You can make whole books using Madagascar. The advantage to doing so, is that you can make individual chapters with examples of processing or workflows that can be run independently of one another. Then Madagascar will stitch the chapters together into a cohesive package seamlessly. The example for a book is this document itself, which is located in: '''$RSFSRC/book/tutorial/''' . Note: creating a book is significantly different from creating a paper.

==Adding/modifying LATEX class files==
The LATEX class files made available from SEGtex are found in '''texmf/tex/latex''' . You can modify these files locally by changing the files inside this location.
To add your own LATEX class files, place them in this same directory, and then request SEG\TeX access to commit them to the main repository.
==Using the default LATEX class files==
Lastly, you can use any of the default LATEX class files just by changing the options to the Paper object to the appropriate lclass and options. For example:
<syntaxhighlight lang="python">
Paper('article',
lclass='article',
options='11pt',
use='times,natbib,color,amssymb,amsmath,amsbsy,graphicx,fancyhdr')
</syntaxhighlight>

=Developers=
The goal of this brief tutorial is to demonstrate the key concepts
behind writing programs for Madagascar. Since the Madagascar API is
well documented, we focus on a high level view of the development
process and the core design functionality. For technical details of
how to interface with the Madagascar API for a specific programming
language, we refer the reader to the current online documentation
mentioned at the end of this tutorial.
By the end of this tutorial, you should understand the basic design of
Madagascar programs, and where to find more information about how to
develop programs using your programming language of choice.
==Core design==
As previously mentioned, the main way for programs to communicate in
Madagascar is through RSF files. Thus, Madagascar programs are
expected to read RSF files, process them, and then write RSF files as
outputs that can be then used in other RSF programs. At the highest
level of abstraction, we can consider RSF programs as black boxes that
simply input and output RSF files and do something to them in between.
From a practical standpoint, your programs will first read RSF files
from disk into memory (or progressively do so) as hypercubes. Once
the file is read,the program processes the hypercubes using routines
that you design or external libraries. After processing, you then
write the hypercubes to RSF files on disk.
In pseudocode this process looks something like:
<pre>
data = make_array()

input = rsf_input()

rsf_read(input,data)

. . . process data . . .

output = rsf_output()

rsf_write(output,data)
</pre>
==Core API==
Madagascar provides core APIs for each language to ease the process of
reading/writing files. Additionally, the core API provides functions
to parse command line variables that can be used to control the
execution of your programs.
In some languages, the API is extended to allow you to access commonly
used functions from the RSF main library. For example, you can
use the FFT library that is contained in Madagascar.
==Program design philosophy==
While Madagascar does not strictly have a design requirement for
programs to enter the main distribution, there are some general
guidelines to programs that we would like developers to follow. In
particular, we would like developers to: design programs that have
error handling and parameter checking, that accept command line
arguments to control important parameters in the program, and write
programs that are limited in scope. For example, a program that is
limited in scope is a program that computes the Fourier transform of a
real-valued signal and outputs a complex-valued RSF file. Conversely,
a program that overreaches in its scope, would be a program that
conducts a long series of processing completely in another language
(say C or Fortran). You should avoid designing programs with too much
scope, because you cannot fully leverage the advantages of SCons and
Python, if everything is happening inside a C or Fortran program.
[[Image:pipe.png|frame|center|A Madagascar program reads RSF files, processes them, and then outputs them at the most fundamental level.]]

==Final thoughts==
With this background, and some additional information provided below,
you should be able to start writing your own Madagascar programs to
process data and implement algorithms that are not provided with
Madagascar by default. We welcome you to the developer community, and
would greatly appreciate it if you would consider releasing your
programs to the community as a whole.
If you have further questions, please feel free to ask the RSF mailing lists.
==Further information==
* For more information about using the API for a particular language, please see [[Guide to madagascar API]]
* For more information about developing Madagascar programs in general see [[Adding new programs to Madagascar]]
* For more information about contributing your programs see [[Contributing new programs to Madagascar]]
* For a full reference of the C API see [http://www.ahay.org/RSF/book/rsf/manual/manual_html/ Manual]

=Quick reference=
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="2" style="background:#ffdead;" | Environmental variables that are used in Madagascar programs
|-
| '''RSFROOT''' || location of the main Madagascar installation
|-
| '''RSFSRC''' || location of the source for Madagascar
|-
| '''DATAPATH''' || location where to put the binary RSF files
|-
| '''RSF_MEMSIZE''' || maximum memory size for some programs to use
|-
| '''PYTHONPATH''' || set to point to Python libraries
|-
| '''LD_LIBRARY_PATH || set to point to RSF dynamic libraries
|}

{| class="wikitable" align="center" cellspacing="0" border="1"
! style="background:#ffdead;" | Using programs on the command line
|-
|<tt>sfprogram < input.rsf arg1=val1 arg2=val2 ... > output.rsf</tt>
|-
|<tt>sftransp < file.rsf plane=12 > file2.rsf</tt>
|-
|<tt>sftransp < file.rsf plane=12 <math>|</math> sftransp plane=23 <math>|</math> sftransp plane=34 > file2.rsf</tt>
|}

{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="2" style="background:#ffdead;" | Some useful programs
|-
| '''sfdoc -k . <math>|</math> less''' || show program descriptions
|-
| '''sfbrowser''' || show program browser
|-
| '''sfgui''' || show tkMadagascar GUI
|-
| '''sfspike''' || create RSF files
|-
| '''sfmath''' || create and manipulate RSF files
|-
| '''sftransp''' || change the order of axes in RSF files
|-
| '''sfwindow''' || window out portions of RSF files
|-
| '''sfricker1''' || create a Ricker wavelet
|-
| '''sfft1''' || FFT on the first axis (real to complex)
|-
| '''sffft3''' || FFT on other axes (complex)
|-
| '''sfnoise''' || add noise
|-
| '''sfdd''' || convert datasets
|-
| '''sfgrey''' || make raster plots
|-
| '''sfcat'' || concatenate datasets together
|-
| '''sfput''' || modify header values
|-
| '''sfsegyread''' || read SEGY/SU files
|-
| '''sfsegywrite''' || write SEGY/SU files
|}

{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="2" style="background:#ffdead;" | SCons commands
|-
| '''scons''' || run an SConstruct
|-
| '''scons view''' || view the results from an SConstruct, run if necessary
|-
| '''scons lock''' || lock the results from an SConstruct

|-
| '''scons -c''' || clean the local directory, delete all target files
|-
| '''scons -n''' || dry-run of an SConstruct
|-
| '''scons --debug=explain''' || explain why SCons is doing what it does
|-
| '''pscons''' || parallel execution of an SConstruct
|}

Package overview

2024-10-29T22:11:51Z

Fomels: typos

[[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 to 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 Microsoft Windows. Its installation requires 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 look 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).
<syntaxhighlight lang="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()
</syntaxhighlight>
You can copy this recipe to your computer or find it already in the "book" subtree under the Madagascar source directory. For example, the recipe at https://ahay.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 modify 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, follow the links from the bottom of the web page: https://ahay.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
https://ahay.org/wiki/Guide_to_madagascar_programs#sfrtoc
</pre>

The DOCUMENTATION section links to more detailed documentation on the web. The most helpful part is the USED IN section, which points to more examples of using the program. As an exercise, change the 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 https://ahay.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 datasets.
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 detail below.

==Madagascar components==

===Standalone programs===
The list of all standalone programs is available [https://ahay.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 explaining the program's 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. The programs in actual use can be found in [[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, 2D to a raster image, and 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 an 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.

Madagascar currently uses the Vplot vector graphics format for graphics. 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 document. These rules are expressed in terms of SCons extensions provided as part of Madagascar.

This is the key to Madagascar's reproducibility. 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). Several output devices can interpret Vplot files. The 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

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

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

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

More extensive examples are in [[Guide to Madagascar programs]]. The novice reader should 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
help understand SCons. SCons statements, as Python statements, are invoked in the sequence in which they are
written, but as such, they only define rules. The rules are invoked by 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 analogous to building a
software package based on a software toolchain. The calculation is seen simply as a build with dependencies.
This setup greatly benefits 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, 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() invokes the default rules for multiple results.

Finally, Madagascar enables a collection of reproducible documents to be organized into 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
a dual purpose concerning Madagascar maintenance. They provide demos to introduce new users to the
functionality of the package and, at the same time, [[Automatic Testing|regression tests]] to assure the system's stability
under change.

==Madagascar Trivia==

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

[http://ahay.org/blog/2006/04/19/madagascar/ Whimsy, really]. It seems easier to remember than the previous name "RSF", and it provides us interesting [http://ahay.org/blog/2008/10/21/ahay/ mascots].

===License===

The Madagascar package is released open-source 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://ahay.org/blog/ 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]
* [http://www.linkedin.com/e/vgh/1847746 LinkedIn group]
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 [https://github.com/ahay/src/blob/master/AUTHORS.txt AUTHORS.txt] for an incomplete list.

While being written primarily 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. The most significant 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/>

===Estimated Cost===

The Project Cost Calculator on Madagascar's [https://www.openhub.net/p/m8r Open Hub (formerly Ohloh) metrics page] shows the estimated cost of the project, using the Basic COCOMO Model, to be about $22 million by October 29, 2024.

Package overview

2024-10-29T22:10:53Z

Fomels: typos

[[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 to 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 Microsoft Windows. Its installation requires 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 look 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).
<syntaxhighlight lang="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()
</syntaxhighlight>
You can copy this recipe to your computer or find it already 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 modify 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, follow the links from the bottom of the web page: https://ahay.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 links to more detailed documentation on the web. The most helpful part is the USED IN section, which points to more examples of using the program. As an exercise, change the 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 https://ahay.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 datasets.
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 detail below.

==Madagascar components==

===Standalone programs===
The list of all standalone programs is available [https://ahay.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 explaining the program's 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. The programs in actual use can be found in [[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, 2D to a raster image, and 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 an 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.

Madagascar currently uses the Vplot vector graphics format for graphics. 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 document. These rules are expressed in terms of SCons extensions provided as part of Madagascar.

This is the key to Madagascar's reproducibility. 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). Several output devices can interpret Vplot files. The 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

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

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

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

More extensive examples are in [[Guide to Madagascar programs]]. The novice reader should 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
help understand SCons. SCons statements, as Python statements, are invoked in the sequence in which they are
written, but as such, they only define rules. The rules are invoked by 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 analogous to building a
software package based on a software toolchain. The calculation is seen simply as a build with dependencies.
This setup greatly benefits 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, 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() invokes the default rules for multiple results.

Finally, Madagascar enables a collection of reproducible documents to be organized into 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
a dual purpose concerning Madagascar maintenance. They provide demos to introduce new users to the
functionality of the package and, at the same time, [[Automatic Testing|regression tests]] to assure the system's stability
under change.

==Madagascar Trivia==

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

[http://ahay.org/blog/2006/04/19/madagascar/ Whimsy, really]. It seems easier to remember than the previous name "RSF", and it provides us interesting [http://ahay.org/blog/2008/10/21/ahay/ mascots].

===License===

The Madagascar package is released open-source 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://ahay.org/blog/ 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]
* [http://www.linkedin.com/e/vgh/1847746 LinkedIn group]
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 [https://github.com/ahay/src/blob/master/AUTHORS.txt AUTHORS.txt] for an incomplete list.

While being written primarily 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. The most significant 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/>

===Estimated Cost===

The Project Cost Calculator on Madagascar's [https://www.openhub.net/p/m8r Open Hub (formerly Ohloh) metrics page] shows the estimated cost of the project, using the Basic COCOMO Model, to be about $22 million by October 29, 2024.

Main Page

2024-10-29T21:55:15Z

Fomels: /* Latest News */

<big>'''Madagascar'''</big> is an open-source software package for multidimensional data analysis and [[Reproducibility|reproducible]] computational experiments. Its mission is to provide
* a convenient and powerful environment
* a convenient technology transfer tool
for researchers working with digital image and data processing in geophysics and related fields. Technology developed using the Madagascar project management system is transferred in the form of recorded processing histories, which become "computational recipes" to be verified, exchanged, and modified by the users.

== Features ==

[[Image:Crystal_Clear_app_katomic.png|left|30px|Modern]]
Madagascar is a modern package. It started in 2003 and was publicly released in 2006. It was developed almost entirely from scratch. It is a relatively new package that follows modern software engineering practices such as module encapsulation and test-driven development. The rapid growth of a project of this scope (more than 1,000 main programs and more than 5,000 tests) would not be possible without standing on the shoulders of giants and learning from the 30 years of previous experience in open packages such as SEPlib and Seismic Unix. We have borrowed and reimplemented functionality and ideas from these other packages.

[[Image:Crystal_Clear_app_vcalendar.png|left|30px|Test-driven]]
Madagascar is a test-driven package. Test-driven development is not only an agile software programming practice but also a way of bringing a scientific foundation to geophysical research that involves numerical experiments. Bringing reproducibility and peer review, the backbone of any real science, to computational geophysics is the primary motivation for Madagascar's development. The package consists of two levels: low-level main programs (typically developed in the C programming language and working as data filters) and high-level processing flows (described using the Python programming language) that combine main programs and unambiguously document data processing histories for testing and reproducibility. Experience shows that high-level programming is easily mastered even by beginning students without any previous programming experience.

[[Image:Crystal_Clear_app_gadu.png|left|30px|Open]]
Madagascar is an open-source package. It is distributed under the standard GPL open-source license, which does not restrict the usage and modification of the code. Moreover, access to modifying the source repository is not controlled by one organization but shared equally among developers. Sharing the responsibility enables an open collaboration among different groups spread worldwide, in the true spirit of the open-source movement.

[[Image:Crystal_Clear_filesystem_blockdevice.png|left|30px|Simple,flexible]]
Madagascar uses a simple, flexible, and universal data format that can handle very large datasets but is not tied specifically to seismic data or any other particular kind. This "regularly sampled" format is borrowed from the traditional SEPlib. A universal data format allows us to share general-purpose data processing tools with scientists and engineers from other disciplines.

== Latest News ==

<rss max=7>https://ahay.org/blog/feed/</rss>

SEGTeX

2024-10-24T23:34:19Z

Fomels: get rid of svn

[[Image:SEG-Logo Final SM.png|thumb|[https://seg.org Society of Exploration Geophysicists]]]

'''SEGTeX''' is a LaTeX package for geophysical publications. It consists of
* LaTeX2e class files for [https://library.seg.org/journal/gpysa7/ Geophysics] papers, SEG expanded abstracts, etc
* BibTeX style files [https://github.com/SEGTeX/texmf/blob/master/bibtex/bst/seg/seg.bst seg.bst]
* BibTeX cumulative bibliography of geophysical publications [https://github.com/SEGTeX/texmf/blob/master/bibtex/bib/seg/SEG.bib SEG.bib]
* [http://www.latex2html.org/ latex2html] customizations

== Downloading ==

Access SEGTeX through its [http://sourceforge.net/projects/segtex/ SourceForge project] by downloading [http://sourceforge.net/projects/segtex/files/ the latest stable release].

Alternatively, access the current working version by using [https://git-scm.com/ Git] and running
<pre>
git clone <nowiki>https://github.com/SEGTeX/texmf</nowiki>
</pre>

You can also [https://github.com/SEGTeX/texmf browse the GitHub repository].

== Installation ==
If your LaTeX installation is missing/incomplete, try installing [http://www.tug.org/texlive/ TeX Live] first.

To install, put the contents of the <tt>texmf</tt> folder where LaTeX can find it. Most systems recognize <tt>$HOME/texmf</tt> as one of the default places. On MacOS X, it can be <tt>$HOME/Library/texmf</tt>. You may need to run <tt>texhash</tt> to tell LaTeX about the new files. For more help on <tt>texmf</tt>, see [http://www.tex.ac.uk/cgi-bin/texfaq2html?label=privinst “Private” installations of files].

=== Prerequisites ===

Some of the required additional LaTeX packages are:

* [http://www.ctan.org/pkg/natbib natbib] support for (author,year) bibliography style of natural sciences

== Download and Install SEGTEX on Mac ==
cd $HOME/Library
git clone https://github.com/SEGTEX/texmf
sudo port install texlive-latex-extra

== SEG expanded abstracts ==

'''SEGTeX''' includes '''segabs.cls''' -- a LaTeX class for generating SEG expanded abstracts. Alternatively, you can
[https://sourceforge.net/projects/segtex/files/segabs/segabs-2015.1/ download '''segabs-2015'''] -- a packaged expanded abstract template.

To generate an expanded abstract without references, as SEG requires, use two LaTeX files: one for the abstract itself and the other for separating pages without references. Examples are [http://sourceforge.net/p/segtex/code/HEAD/tree/trunk/tex/latex/seg/segabs_example.ltx segabs_example.ltx] and [http://sourceforge.net/p/segtex/code/HEAD/tree/trunk/tex/latex/seg/segabs_final.ltx segabs_final.ltx]
<syntaxhighlight lang="latex">
\documentclass{article}
\usepackage{pdfpages}
\begin{document}
\includepdf[pages={1-4}]{segabs_example}
\end{document}
</syntaxhighlight>
This solution only works with '''pdflatex'''.

Alternatively, you can separate pages using an external program.
* In [http://www.adobe.com/products/acrobatpro/ Acrobat Pro], open the PDF file with references, select <tt>Document -> Pages -> Extract</tt>, and extract the reference page with the delete option (''thanks to Norm Bleistein for the tip''.)
* Another helpful program is [http://www.accesspdf.com/pdftk/ pdftk] (PDF toolkit.)

== Documentation ==

The [https://github.com/SEGTeX/texmf/tree/master/tex/latex/seg tex/latex/seg] directory contains several example files.

Use the manuscript style to submit papers to '''Geophysics'''.

* Manuscript style '''Geophysics''' paper [http://reproducibility.org/wikilocal/docs/geophysics_example.pdf geophysics_example] [http://reproducibility.org/wikilocal/docs/geophysics_titlepage.pdf geophysics_titlepage] [http://reproducibility.org/wikilocal/docs/geophysics_notitlepage.pdf geophysics_notitlepage]
* Manuscript style '''Geophysics''' paper using <tt>endfloat</tt> [http://reproducibility.org/wikilocal/docs/geophysics_endfloat.pdf geophysics_endfloat]
* Manuscript style '''Geophysics''' with author information (no double-blind review) [http://reproducibility.org/wikilocal/docs/geophysics_noblind.pdf geophysics_noblind]
* Publication style two-column '''Geophysics''' paper [http://reproducibility.org/wikilocal/docs/geophysics_twocolumn.pdf geophysics_twolumn]
* '''SEG''' expanded abstract (with references) [http://reproducibility.org/wikilocal/docs/segabs_example.pdf segabs_example]
* '''SEG''' expanded abstract (without references) [http://reproducibility.org/wikilocal/docs/segabs_final.pdf segabs_final]
* Report style paper [http://reproducibility.org/wikilocal/docs/geophysics_paper.pdf geophysics_paper]

== Tips and tricks ==

* '''Equations, citation commands, etc. don't work inside \old.'''

Enclose citations in <tt>\mbox</tt>: Instead of <tt>\old{wrong citation \cite{wrong}}</tt>, use <tt>\old{wrong citation \mbox{\cite{wrong}}}</tt>.

Enclose equations in <tt>\parbox</tt> or <tt>minipage</tt>: Instead of
<syntaxhighlight lang="latex">
\old{wrong equation
\begin{equation}
2*2 = 5
\end{equation}}
</syntaxhighlight>
use
<syntaxhighlight lang="latex">
\old{wrong equation \\
\begin{minipage}{\textwidth}
\begin{equation}
2*2 = 5
\end{equation}
\end{minipage}}
</syntaxhighlight>
or
<syntaxhighlight lang="latex">
\old{wrong equation \\
\parbox{\textwidth}{
\begin{equation}
2*2 = 5
\end{equation}
}}
</syntaxhighlight>
<tt>\parbox</tt> seems to work better with <tt>\eqnarray</tt>.

''Thanks to Brad Artman and James Gunning for reporting this problem.''

== Communication ==

The SEGTeX development is discussed at the [http://listserver.seg.org/cgi-bin/mailman/listinfo/segtex SEGTeX mailing list] maintained by Joe Dellinger.

== Reproducible papers ==

SEGTeX is used in the [[Main Page|Madagascar]] package to produce [[Reproducible Documents|reproducible research papers]].

See a [http://reproducibility.org/wikilocal/docs/vancouver06/fomel_latex.pdf presentation on LaTeX and Web tools] from the [[RSF School and Workshop%2C Vancouver 2006]].

== LaTeX references ==

* LaTeX [http://www.latex-project.org/ open project]

* LaTeX [http://en.wikipedia.org/wiki/LaTeX Wikipedia page]

* LaTeX [http://www.latex-project.org/guides/books.html books]

== News ==
[[Image:image21.png|frame|right|[https://imageevent.org/2021 SEG/AAPG Image Conference]]]

* 07/04/2006 SEGTeX moved to [http://sourceforge.net/projects/segtex SourceForge]
* 07/07/2006 version 0.8 released
* 10/26/2006 version 0.8.1 released
* 10/27/2006 version 0.8.2 released
* 12/11/2006 version 0.8.3 and segabs-2007.1 released
* 03/15/2007 version 0.8.4 and segabs-2007.2 released
* 04/03/2007 version 0.8.5 and segabs-2007.3 released
* 04/20/2008 version 0.8.6 and segabs-2008.1 released
* 04/27/2008 version 0.8.7 and segabs-2008.2 released
* 05/16/2008 version 0.8.8 released
* 06/07/2009 version 0.8.9 and segabs-2009.1 released
* 03/09/2011 version 0.9 and segabs-2011.1 released
* 03/23/2013 version 0.9.1 and segabs-2013.1 released
* 03/11/2014 version 0.9.2 and segabs-2014.1 released
* 03/06/2015 version 0.9.3 and segabs-2015.1 released
* 07/28/2015 SEGTeX repository moved to [https://github.com/SEGTeX/texmf GitHub]
* 03/07/2016 version 0.9.5 and segabs-2016.1 released
* 09/05/2018 version 0.9.6 released
* 08/31/2021 version 0.9.7 and segabs-2021.1 released
* 10/12/2021 version 0.9.8 released

SEGTeX

2024-10-24T23:33:08Z

Fomels: typos

[[Image:SEG-Logo Final SM.png|thumb|[https://seg.org Society of Exploration Geophysicists]]]

'''SEGTeX''' is a LaTeX package for geophysical publications. It consists of
* LaTeX2e class files for [https://library.seg.org/journal/gpysa7/ Geophysics] papers, SEG expanded abstracts, etc
* BibTeX style files [https://github.com/SEGTeX/texmf/blob/master/bibtex/bst/seg/seg.bst seg.bst]
* BibTeX cumulative bibliography of geophysical publications [https://github.com/SEGTeX/texmf/blob/master/bibtex/bib/seg/SEG.bib SEG.bib]
* [http://www.latex2html.org/ latex2html] customizations

== Downloading ==

Access SEGTeX through its [http://sourceforge.net/projects/segtex/ SourceForge project] by downloading [http://sourceforge.net/projects/segtex/files/ the latest stable release].

Alternatively, access the current working version by either using [https://git-scm.com/ Git] and running
<pre>
git clone <nowiki>https://github.com/SEGTeX/texmf</nowiki>
</pre>
or using [http://subversion.tigris.org/ Subversion] and running
<pre>
svn co <nowiki>https://github.com/SEGTeX/texmf/trunk</nowiki> texmf
</pre>
You can also [https://github.com/SEGTeX/texmf browse the GitHub repository].

== Installation ==
If your LaTeX installation is missing/incomplete, try installing [http://www.tug.org/texlive/ TeX Live] first.

To install, put the contents of the <tt>texmf</tt> folder where LaTeX can find it. Most systems recognize <tt>$HOME/texmf</tt> as one of the default places. On MacOS X, it can be <tt>$HOME/Library/texmf</tt>. You may need to run <tt>texhash</tt> to tell LaTeX about the new files. For more help on <tt>texmf</tt>, see [http://www.tex.ac.uk/cgi-bin/texfaq2html?label=privinst “Private” installations of files].

=== Prerequisites ===

Some of the required additional LaTeX packages are:

* [http://www.ctan.org/pkg/natbib natbib] support for (author,year) bibliography style of natural sciences

== Download and Install SEGTEX on Mac ==
cd $HOME/Library
git clone https://github.com/SEGTEX/texmf
sudo port install texlive-latex-extra

== SEG expanded abstracts ==

'''SEGTeX''' includes '''segabs.cls''' -- a LaTeX class for generating SEG expanded abstracts. Alternatively, you can
[https://sourceforge.net/projects/segtex/files/segabs/segabs-2015.1/ download '''segabs-2015'''] -- a packaged expanded abstract template.

To generate an expanded abstract without references, as SEG requires, use two LaTeX files: one for the abstract itself and the other for separating pages without references. Examples are [http://sourceforge.net/p/segtex/code/HEAD/tree/trunk/tex/latex/seg/segabs_example.ltx segabs_example.ltx] and [http://sourceforge.net/p/segtex/code/HEAD/tree/trunk/tex/latex/seg/segabs_final.ltx segabs_final.ltx]
<syntaxhighlight lang="latex">
\documentclass{article}
\usepackage{pdfpages}
\begin{document}
\includepdf[pages={1-4}]{segabs_example}
\end{document}
</syntaxhighlight>
This solution only works with '''pdflatex'''.

Alternatively, you can separate pages using an external program.
* In [http://www.adobe.com/products/acrobatpro/ Acrobat Pro], open the PDF file with references, select <tt>Document -> Pages -> Extract</tt>, and extract the reference page with the delete option (''thanks to Norm Bleistein for the tip''.)
* Another helpful program is [http://www.accesspdf.com/pdftk/ pdftk] (PDF toolkit.)

== Documentation ==

The [https://github.com/SEGTeX/texmf/tree/master/tex/latex/seg tex/latex/seg] directory contains several example files.

Use the manuscript style to submit papers to '''Geophysics'''.

* Manuscript style '''Geophysics''' paper [http://reproducibility.org/wikilocal/docs/geophysics_example.pdf geophysics_example] [http://reproducibility.org/wikilocal/docs/geophysics_titlepage.pdf geophysics_titlepage] [http://reproducibility.org/wikilocal/docs/geophysics_notitlepage.pdf geophysics_notitlepage]
* Manuscript style '''Geophysics''' paper using <tt>endfloat</tt> [http://reproducibility.org/wikilocal/docs/geophysics_endfloat.pdf geophysics_endfloat]
* Manuscript style '''Geophysics''' with author information (no double-blind review) [http://reproducibility.org/wikilocal/docs/geophysics_noblind.pdf geophysics_noblind]
* Publication style two-column '''Geophysics''' paper [http://reproducibility.org/wikilocal/docs/geophysics_twocolumn.pdf geophysics_twolumn]
* '''SEG''' expanded abstract (with references) [http://reproducibility.org/wikilocal/docs/segabs_example.pdf segabs_example]
* '''SEG''' expanded abstract (without references) [http://reproducibility.org/wikilocal/docs/segabs_final.pdf segabs_final]
* Report style paper [http://reproducibility.org/wikilocal/docs/geophysics_paper.pdf geophysics_paper]

== Tips and tricks ==

* '''Equations, citation commands, etc. don't work inside \old.'''

Enclose citations in <tt>\mbox</tt>: Instead of <tt>\old{wrong citation \cite{wrong}}</tt>, use <tt>\old{wrong citation \mbox{\cite{wrong}}}</tt>.

Enclose equations in <tt>\parbox</tt> or <tt>minipage</tt>: Instead of
<syntaxhighlight lang="latex">
\old{wrong equation
\begin{equation}
2*2 = 5
\end{equation}}
</syntaxhighlight>
use
<syntaxhighlight lang="latex">
\old{wrong equation \\
\begin{minipage}{\textwidth}
\begin{equation}
2*2 = 5
\end{equation}
\end{minipage}}
</syntaxhighlight>
or
<syntaxhighlight lang="latex">
\old{wrong equation \\
\parbox{\textwidth}{
\begin{equation}
2*2 = 5
\end{equation}
}}
</syntaxhighlight>
<tt>\parbox</tt> seems to work better with <tt>\eqnarray</tt>.

''Thanks to Brad Artman and James Gunning for reporting this problem.''

== Communication ==

The SEGTeX development is discussed at the [http://listserver.seg.org/cgi-bin/mailman/listinfo/segtex SEGTeX mailing list] maintained by Joe Dellinger.

== Reproducible papers ==

SEGTeX is used in the [[Main Page|Madagascar]] package to produce [[Reproducible Documents|reproducible research papers]].

See a [http://reproducibility.org/wikilocal/docs/vancouver06/fomel_latex.pdf presentation on LaTeX and Web tools] from the [[RSF School and Workshop%2C Vancouver 2006]].

== LaTeX references ==

* LaTeX [http://www.latex-project.org/ open project]

* LaTeX [http://en.wikipedia.org/wiki/LaTeX Wikipedia page]

* LaTeX [http://www.latex-project.org/guides/books.html books]

== News ==
[[Image:image21.png|frame|right|[https://imageevent.org/2021 SEG/AAPG Image Conference]]]

* 07/04/2006 SEGTeX moved to [http://sourceforge.net/projects/segtex SourceForge]
* 07/07/2006 version 0.8 released
* 10/26/2006 version 0.8.1 released
* 10/27/2006 version 0.8.2 released
* 12/11/2006 version 0.8.3 and segabs-2007.1 released
* 03/15/2007 version 0.8.4 and segabs-2007.2 released
* 04/03/2007 version 0.8.5 and segabs-2007.3 released
* 04/20/2008 version 0.8.6 and segabs-2008.1 released
* 04/27/2008 version 0.8.7 and segabs-2008.2 released
* 05/16/2008 version 0.8.8 released
* 06/07/2009 version 0.8.9 and segabs-2009.1 released
* 03/09/2011 version 0.9 and segabs-2011.1 released
* 03/23/2013 version 0.9.1 and segabs-2013.1 released
* 03/11/2014 version 0.9.2 and segabs-2014.1 released
* 03/06/2015 version 0.9.3 and segabs-2015.1 released
* 07/28/2015 SEGTeX repository moved to [https://github.com/SEGTeX/texmf GitHub]
* 03/07/2016 version 0.9.5 and segabs-2016.1 released
* 09/05/2018 version 0.9.6 released
* 08/31/2021 version 0.9.7 and segabs-2021.1 released
* 10/12/2021 version 0.9.8 released

Reproducible Documents

2024-10-17T23:01:17Z

Fomels: reproducibility.org -> ahay.org

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

== [https://ahay.org/RSF/book/bei/ Basic Earth Imaging] ==
* [https://ahay.org/RSF/book/bei/sg/paper_html/ Imaging in shot-geophone space] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/dwnc/paper_html/ Downward continuation] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/ft1/paper_html/ Waves and Fourier sums] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/krch/paper_html/ Zero-offset migration] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/vela/paper_html/ Moveout, velocity, and stacking] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/wvs/paper_html/ Waves in strata] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/conj/paper_html/ Adjoint operators] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/bei/fld/paper_html/ Field recording geometry] by ''Jon F. Claerbout''

== [https://ahay.org/RSF/book/cwp/ Center for Wave Phenomena] ==
* [https://ahay.org/RSF/book/cwp/geo2011WideAzimuthAngleDecomposition/paper_html/ Wide-azimuth angle gathers for wave-equation migration] by ''Paul Sava and Ioan Vlad'': '''Geophysics''', 76, no. 3, S131-S141, (2011)
* [https://ahay.org/RSF/book/cwp/pept2011MicroearthquakeMonitoring/paper_html/ Micro-earthquake monitoring with sparsely-sampled data] by ''Paul Sava'': '''Journal of Petroleum Exploration and Production Technology''', 1, no. 1, 43-49, (2011)
* [https://ahay.org/RSF/book/cwp/geo2008IsotropicAngleDomainElasticRTM/paper_html/ Isotropic angle-domain elastic reverse-time migration] by ''Jia Yan and Paul Sava'': '''Geophysics''', 73 , no. 6, S229-S239, (2008)
* [https://ahay.org/RSF/book/cwp/geo2009VTIModeSeparation/paper_html/ Elastic wave-mode separation for VTI media] by ''Jia Yan and Paul Sava'': '''Geophysics''', 74 , no. 5, WB19-WB32, (2009)
* [https://ahay.org/RSF/book/cwp/geo2009TTIModeSeparation/paper_html/ Elastic wave-mode separation for TTI media] by ''Jia Yan and Paul Sava'': '''Geophysics''', 76, no. 4, T65-T78, (2011)
* [https://ahay.org/RSF/book/cwp/geo2008InterferometricImagingCondition/paper_html/ Interferometric imaging condition for wave-equation migration] by ''Paul Sava and Oleg Poliannikov'': '''Geophysics''', 73 , no. 2, S47-S61, (2008)
* [https://ahay.org/RSF/book/cwp/geo2008NumericWEMVAoperators/paper_html/ Numeric implementation of wave-equation migration velocity analysis operators] by ''Paul Sava and Ioan Vlad'': '''Geophysics''', 73 , no. 5, VE145-VE159, (2008)
* [https://ahay.org/RSF/book/cwp/geo2007StereographicImagingCondition/paper_html/ Stereographic imaging condition for wave-equation migration] by ''Paul Sava'': '''Geophysics''', 72 , no. 6, A87-A91, (2007)
* [https://ahay.org/RSF/book/cwp/jse2006RWEImagingOverturningReflections/paper_html/ Imaging overturning reflections by Riemannian Wavefield Extrapolation] by ''Paul Sava'': '''Journal of Seismic Exploration''', 15, no 3, 209-223 (2006)
* [https://ahay.org/RSF/book/cwp/geo2006TimeShiftImagingCondition/paper_html/ Time-shift imaging condition in seismic migration] by ''Paul Sava and Sergey Fomel'': '''Geophysics''', 71 , no. 6, S209-S217, (2006)
* [https://ahay.org/RSF/book/cwp/aniso/paper_html/ Nonhyperbolic reflection moveout of P-waves: An overview and comparison of reasons] by ''Sergey Fomel and Vladimir Grechka'': '''Center for Wave Phenomena''', CWP-372 (2001)

== [https://ahay.org/RSF/book/cup/ China University of Petroleum] ==
* [https://ahay.org/RSF/book/cup/rna2d/paper_html/ Random noise attenuation using f-x regularized nonstationary autoregression] by ''Guochang Liu, Xiaohong Chen, Jing Du, and Kailong Wu'': '''Geophysics''', 77 , no. 2, V61-V69, (2012)
* [https://ahay.org/RSF/book/cup/rna3d/paper_html/ Noncausal f-x-y regularized nonstationary prediction filtering for random noise attenuation on 3D seismic data] by ''Guochang Liu and Xiaohong Chen '': '''Journal of Applied Geophysics''', 93, 60-66, (2013)

== [https://ahay.org/RSF/book/hansung/ Hansung University] ==
* [https://ahay.org/RSF/book/hansung/cgg/paper_html/ Conjugate guided gradient (CGG) method for robust inversion and its application to velocity-stack inversion] by ''Jun Ji'': '''Geophysics''', 71 , no. 4, R59-R67, (2006)

== [https://ahay.org/RSF/book/gee/ Image Estimation by Example] ==
* [https://ahay.org/RSF/book/gee/lmn/paper_html/ Plane waves in three dimensions] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/pch/paper_html/ Nonstationarity: patching] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/lal/paper_html/ Spatial aliasing and scale invariance] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/mda/paper_html/ Multidimensional autoregression] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/prc/paper_html/ Preconditioning] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/hlx/paper_html/ The helical coordinate] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/iin/paper_html/ Empty bins and inverse interpolation] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/lsq/paper_html/ Model fitting by least squares] by ''Jon F. Claerbout''
* [https://ahay.org/RSF/book/gee/ajt/paper_html/ Basic operators and adjoints] by ''Jon F. Claerbout''

== [https://ahay.org/RSF/book/data/ Madagascar Datasets] ==
* [https://ahay.org/RSF/book/data/marmousi2mp/paper_html/ 2D modeling and basic processing with Madagascar] by ''Pongthep Thongsang, Lian Jiang, Hao Li, and Karl Schleicher''
* [https://ahay.org/RSF/book/data/marmousi2/paper_html/ Marmousi2 model] by ''Trevor Irons''
* [https://ahay.org/RSF/book/data/alaska/paper_html/ Open Data/Open Source: Seismic Unix scripts to process a 2D land line] by ''Karl Schleicher''
* [https://ahay.org/RSF/book/data/teapotdome/paper_html/ Processing the Teapot Dome Land 3D Survey with Madagascar] by ''Karl Schleicher''
* [https://ahay.org/RSF/book/data/sigsbee/paper_html/ Sigsbee2 models] by ''Trevor Irons''
* [https://ahay.org/RSF/book/data/pluto/paper_html/ Pluto model] by ''Trevor Irons''
* [https://ahay.org/RSF/book/data/marmousi/paper_html/ Marmousi model] by ''Trevor Irons''
* [https://ahay.org/RSF/book/data/amoco/paper_html/ Amoco model] by ''Trevor Irons''

== [https://ahay.org/RSF/book/icp/ ICP-Ecopetrol] ==
* [https://ahay.org/RSF/book/icp/sam2013gpushortestpath/segabs_graphrayt_html/ Shortest path ray tracing on parallel GPU devices] by ''Jorge Monsegny and William Agudelo'': '''SEG Expanded Abstracts''', 3470-3474, (2013)

== [https://ahay.org/RSF/book/jlu/ Jilin University] ==

* [https://ahay.org/RSF/book/jlu/fxyspfdenoi/paper_html/ Noniterative f-x-y streaming prediction filtering for random noise attenuation on seismic data] by ''Yang Liu and Zhisheng Zhen'': '''IEEE Transactions on Geoscience and Remote Sensing''', 60, 1-9, Early Access, (2022)
* [https://ahay.org/RSF/book/jlu/fspfint/paper_html/ Seismic data interpolation using streaming prediction filter in the frequency domain] by ''Zhisheng Zheng, Yang Liu, and Geng Wu'': '''Geophysical Journal International''', 229, 370-389, (2022)
* [https://ahay.org/RSF/book/jlu/txyspfint/paper_html/ Seismic data interpolation without iteration using a t-x-y streaming prediction filter with varying smoothness] by ''Yang Liu, Geng Wu, and Zhisheng Zheng'': '''Geophysics''', 87, V29-V38, (2022)
* [https://ahay.org/RSF/book/jlu/apefsnsep/paper_html/ Nonstationary pattern-based signal-noise separation using adaptive prediction-error filter] by ''Zhisheng Zheng, Yang Liu, and Cai Liu'': '''Journal of Geophysics and Engineering''', 19, 14-27, (2022)
* [https://ahay.org/RSF/book/jlu/spefdecon/paper_html/ Multichannel adaptive deconvolution based on streaming prediction-error filter] by ''Qinghan Wang, Yang Liu, Cai Liu, and Zhisheng Zheng'': '''Journal of Geophysics and Engineering''', 18, 825-833, (2021)
* [https://ahay.org/RSF/book/jlu/lcfs/paper_html/ Continuous time-varying Q-factor estimation method in the time-frequency domain] by ''Qinghan Wang, Yang Liu, Cai Liu, and Zhisheng Zheng'': '''Applied Geophysics''', 17, 844-856, (2020)
* [https://ahay.org/RSF/book/jlu/txsopf/paper_html/ Streaming orthogonal prediction filter in t-x domain for random noise attenuation] by ''Yang Liu and Bingxiu Li'': '''Geophysics''', 83, F41-F48, (2018)
* [https://ahay.org/RSF/book/jlu/gvdseisint/paper_html/ Seismic data interpolation using generalised velocity-dependent seislet transform] by ''Yang Liu, Peng Zhang, and Cai Liu'': '''Geophysical Prospecting''', 65, 82-93, (2017)
* [https://ahay.org/RSF/book/jlu/vdseislet/paper_html/ Signal and noise separation in prestack seismic data using velocity-dependent seislet transform] by ''Yang Liu, Sergey Fomel, and Cai Liu'': '''Geophysics''', 80, WD117-WD128, (2015)
* [https://ahay.org/RSF/book/jlu/riesz/paper_html/ Seismic dip estimation based on the two-dimensional Hilbert transform and its application in random noise attenuation] by ''Cai Liu, Changle Chen, Dian Wang, Yang Liu, Shiyu Wang, and Liang Zhang'': '''Applied Geophysics''', 12, 55-63, (March 2015)
* [https://ahay.org/RSF/book/jlu/txyapf/paper_html/ Adaptive prediction filtering in t -x-y domain for random noise attenuation using regularized nonstationary autoregression] by ''Yang Liu, Ning Liu, and Cai Liu'': '''Geophysics''', 80, V13-V21, (2015)

== [https://ahay.org/RSF/book/rsf/ Madagascar Documentation] ==
* [https://ahay.org/RSF/book/rsf/school2012/tutorial_html/ Madagascar tutorial: Field data processing] by ''Maurice the Aye-Aye''
* [https://ahay.org/RSF/book/rsf/school/articleWSI_html/ Seismic Imaging Tutorial: "exploding reflector" modeling/migration] by ''Paul Sava''
* [https://ahay.org/RSF/book/tutorial A brief introduction to Madagascar] by ''Jeff Godwin''
* [https://ahay.org/RSF/book/rsf/manual/manual_html/ Madagascar Programming Reference Manual] by ''Mohammad Akbar Zuberi, Tariq Alkhalifah, and Christos Saragoitis''
* [https://ahay.org/RSF/book/rsf/school2009/paper_html/ Madagascar tutorial] by ''Maurice the Aye-Aye''
* [https://ahay.org/RSF/book/rsf/rsf/prog_html/ Guide to Madagascar programs] by ''Sergey Fomel''
* [https://ahay.org/RSF/book/rsf/rsf/tour_html/ Revisiting SEP tour with RSF and SCons] by ''Sergey Fomel''
* [https://ahay.org/RSF/book/rsf/rsf/api_html/ Guide to RSF API] by ''Sergey Fomel''
* [https://ahay.org/RSF/book/rsf/rsf/demo_html/ Guide to programming using RSF] by ''Paul Sava''
* [https://ahay.org/RSF/book/rsf/scons/paper_html/ Reproducible computational experiments using SCons] by ''Sergey Fomel and Gilles Hennenfent''

== [https://ahay.org/RSF/book/milano/ Politecnico di Milano] ==
* [https://ahay.org/RSF/book/milano/taupvel/paper_html/ Velocity-independent tau-p moveout in a horizontally-layered VTI medium ] by ''Lorenzo Casasanta and Sergey Fomel'': '''Geophysics''', 76, no. 4, U45-U57, (2011)

== [https://ahay.org/RSF/book/slim/ Seismic Laboratory for Imaging and Modeling] ==
* [https://ahay.org/RSF/book/slim/geo2008NewInsightsPareto/paper_html/ New insights into one-norm solvers from the Pareto curve] by ''Gilles Hennenfent, Ewout van den Berg, Michael P. Friedlander, and Felix J. Herrmann'': '''Geophysics''', 73, no. 4, A23-A26, (2008)
* [https://ahay.org/RSF/book/slim/slimUserManual/paper_html/ User's manual for SLIM programs in Madagascar] by ''Gilles Hennenfent''

== [https://ahay.org/RSF/book/sep/ Stanford Exploration Project] ==
* [https://ahay.org/RSF/book/sep/geostat/paper_html/ Multiple realizations using standard inversion techniques] by ''Robert Clapp'': '''SEP Report''', 105, 67-78 (2000)
* [https://ahay.org/RSF/book/sep/sparse2/paper_html/ Test case for PEF estimation with sparse data II] by ''Morgan Brown, Jon Claerbout, and Sergey Fomel'': '''SEP Report''', 105, 117-122 (2000)
* [https://ahay.org/RSF/book/sep/elliptic2/paper_html/ The double-elliptic approximation in the group and phase domains] by ''Joe Dellinger and Francis Muir'': '''SEP Report''', 70, 361-366 (1991)
* [https://ahay.org/RSF/book/sep/balance/paper_html/ Iterative least-square inversion for amplitude balancing] by ''Arnaud Berlioux and William Harlan'': '''SEP Report''', 89, 167-178 (1995)
* [https://ahay.org/RSF/book/sep/pefmult/paper_html/ Multiple suppression using prediction-error filter] by ''Yalei Sun'': '''SEP Report''', 94, 205-212 (1997)
* [https://ahay.org/RSF/book/sep/aal/paper_html/ When is anti-aliasing needed in Kirchhoff migration?] by ''Dimitri Bevc and David Lumley'': '''SEP Report''', 80, 467-476 (1994)
* [https://ahay.org/RSF/book/sep/passive/paper_html/ Passive seismic imaging applied to synthetic data] by ''James Rickett and Jon Claerbout'': '''SEP Report''', 92, 83-90 (1996)
* [https://ahay.org/RSF/book/sep/avo/paper_html/ Seismic AVO analysis of methane hydrate structures] by ''Christine Ecker and David Lumley'': '''SEP Report''', 80, 277-292 (1994)
* [https://ahay.org/RSF/book/sep/super/paper_html/ A prospect for super resolution] by ''Jon Claerbout'': '''SEP Report''', 93, 133-136 (1996)
* [https://ahay.org/RSF/book/sep/shearer/paper_html/ Earthquake stacks at constant offset] by ''Jon Claerbout'': '''SEP Report''', 77, 361-366 (1993)
* [https://ahay.org/RSF/book/sep/txamo/paper_html/ The time and space formulation of azimuth moveout] by ''Sergey Fomel and Biondo Biondi'': '''SEP Report''', 84, 25-37 (1995)
* [https://ahay.org/RSF/book/sep/waverays/paper_html/ Wavefront construction using waverays] by ''Hector Urdaneta'': '''SEP Report''', 80, 85-100 (1994)
* [https://ahay.org/RSF/book/sep/helft/paper_html/ Multi-dimensional Fourier transforms in the helical coordinate system] by ''James Rickett and Antoine Guitton'': '''SEP Report''', 105, 167-176 (2000)
* [https://ahay.org/RSF/book/sep/fat/paper_html/ Imaging complex structures with first-arrival traveltimes] by ''Dimitri Bevc'': '''SEP Report''', 84, 1-10 (1995)
* [https://ahay.org/RSF/book/sep/texture/paper_html/ Texture synthesis and prediction error filtering] by ''Morgan Brown'': '''SEP report''', 100, 211-222 (1999)
* [https://ahay.org/RSF/book/sep/lines/paper_html/ Random lines in a plane] by ''Jon Claerbout'': '''SEP report''', 103, 325-328 (2000)
* [https://ahay.org/RSF/book/sep/fractal/paper_html/ Modeling 3-D anisotropic fractal media] by ''Nizar Chemingui'': '''SEP report''', 80, 603-616 (1994)
* [https://ahay.org/RSF/book/sep/banana/paper_html/ Traveltime sensitivity kernels: Banana-doughnuts or just plain bananas?] by ''James Rickett'': '''SEP report''', 103, 61-68 (2000)
* [https://ahay.org/RSF/book/sep/steer/paper_html/ Solution steering with space-variant filters] by ''Robert G. Clapp, Sergey Fomel, and Jon Claerbout'': '''SEP report''', 95, 27-42 (1997)
* [https://ahay.org/RSF/book/sep/lineiko/paper_html/ Traveltime computation with the linearized eikonal equation] by ''Sergey Fomel'': '''SEP report''', 94, 123-131 (1997)
* [https://ahay.org/RSF/book/sep/bspl/paper_html/ Inverse B-spline interpolation] by ''Sergey Fomel'': '''SEP report''', 105, 79-108 (2000)
* [https://ahay.org/RSF/book/sep/plane/paper_html/ Plane wave prediction in 3-D] by ''Sergey Fomel'': '''SEP report''', 102, 101-110 (1999)
* [https://ahay.org/RSF/book/sep/stoltst/paper_html/ Evaluating the Stolt-stretch parameter] by ''Sergey Fomel and Louis Vaillant'': '''Journal of Seismic Exploration''', v. 9, 319-335, (2001)
* [https://ahay.org/RSF/book/sep/huygens/paper_html/ Huygens wavefront tracing: A robust alternative to conventional ray tracing] by ''Paul Sava and Sergey Fomel'': '''SEP Report''', 95, 101-113 (1997)
* [https://ahay.org/RSF/book/sep/fkamo/paper_html/ Effective AMO implementation in the log-stretch, frequency-wavenumber domain] by ''Ioan Vlad and Biondo Biondi'': '''SEP Report''', 110, 63-70 (2001)
* [https://ahay.org/RSF/book/sep/antial/paper_html/ Antialiasing of Kirchhoff operators by reciprocal parameterization] by ''Sergey Fomel'': '''Journal of Seismic Exploration''', v. 10, 293-310 (2002)
* [https://ahay.org/RSF/book/sep/norm/paper_html/ Amplitude preservation for offset continuation: Confirmation for Kirchhoff data] by ''Sergey Fomel and Norman Bleistein'': '''Journal of Seismic Exploration''', v. 9, 121-130 (2001)
* [https://ahay.org/RSF/book/sep/angle/paper_html/ Angle-gather time migration] by ''Sergey Fomel and Marie Prucha'': '''SEP report''', 100, 141-150 (1999)
* [https://ahay.org/RSF/book/sep/spitz/paper_html/ Spitz makes a better assumption for the signal PEF] by ''Jon F. Claerbout and Sergey Fomel'': '''SEP report''', 103, 211-219 (2000)
* [https://ahay.org/RSF/book/sep/findif/paper_html/ Exploring three-dimensional implicit wavefield extrapolation with the helix transform] by ''Sergey Fomel and Jon F. Claerbout'': '''SEP report''', 95, 43-60 (1997)
* [https://ahay.org/RSF/book/sep/vc2/paper_html/ Time-migration velocity analysis by velocity continuation] by ''Sergey Fomel'': '''Geophysics''', 68, 1662-1672 (2003)
* [https://ahay.org/RSF/book/sep/burg/paper_html/ The Wilson-Burg method of spectral factorization with application to helical filtering] by ''Sergey Fomel, Paul Sava, James Rickett, and Jon F. Claerbout'': '''Geophysical Prospecting''', 51, 409-420 (2003)
* [https://ahay.org/RSF/book/sep/velspec/paper_html/ Velocity continuation by spectral methods] by ''Sergey Fomel'': '''SEP Report''', 97, 157-172 (1998)
* [https://ahay.org/RSF/book/sep/specfac/paper_html/ Spectral factorization revisited] by ''Paul Sava and Sergey Fomel'': '''SEP Report''', 100, 227-234 (1999)
* [https://ahay.org/RSF/book/sep/oc2/paper_html/ Seismic reflection data interpolation with differential offset and shot continuation] by ''Sergey Fomel'': '''Geophysics''', 68, 733-744 (2003)
* [https://ahay.org/RSF/book/sep/oc1/paper_html/ Theory of differential offset continuation] by ''Sergey Fomel'': '''Geophysics''', 68, 718-732 (2003)
* [https://ahay.org/RSF/book/sep/vc1/paper_html/ Velocity continuation and the anatomy of residual prestack time migration] by ''Sergey Fomel'': '''Geophysics''', 68, 1650-1661 (2003)
* [https://ahay.org/RSF/book/sep/fmsec/paper_html/ A second-order fast marching eikonal solver] by ''James Rickett and Sergey Fomel'': '''SEP Report''', 100, 287-292 (1999)
* [https://ahay.org/RSF/book/sep/stack/paper_html/ Asymptotic pseudounitary stacking operators] by ''Sergey Fomel'': '''Geophysics''', 68, 1032-1042(2003)
* [https://ahay.org/RSF/book/sep/cdstep/paper_html/ Least-square inversion with inexact adjoints. Method of conjugate directions: A tutorial] by ''Sergey Fomel'': '''SEP Report''', 92, 253-365 (1996)
* [https://ahay.org/RSF/book/sep/fmeiko/paper_html/ A variational formulation of the fast marching eikonal solver] by ''Sergey Fomel'': '''SEP Report''', 95, 127-147 (1997)
* [https://ahay.org/RSF/book/sep/forwd/paper_html/ Forward interpolation] by ''Sergey Fomel'': '''SEP Report''' (Ph.D. Thesis Chapter), 107 (2001)
* [https://ahay.org/RSF/book/sep/precon/paper_html/ Multidimensional recursive filter preconditioning in geophysical estimation problems] by ''Sergey Fomel and Jon Claerbout'': '''Geophysics''', 68, 577-588 (2003)
* [https://ahay.org/RSF/book/sep/pwd/paper_html/ Applications of plane-wave destruction filters] by ''Sergey Fomel'': '''Geophysics''', 67, 1946-1960 (2002)

== [https://ahay.org/RSF/book/swag/ Seismic Wave Analysis Group] ==
* [https://ahay.org/RSF/book/swag/itime/paper_html/ Automatic traveltime picking using the instantaneous traveltime] by ''Christos Saragiotis, Tariq Alkhalifah, and Sergey Fomel'': '''Geophysics''', 78, T53-T58, (2013)
* [https://ahay.org/RSF/book/swag/tau/paper_html/ Wavefield extrapolation in pseudodepth domain] by ''Xuxin Ma and Tariq Alkhalifah'': '''Geophysics''', 78, S81-S91, (2013)
* [https://ahay.org/RSF/book/swag/thetaScan/article_html/ Traveltime approximations for transversely isotropic media with an inhomogeneous background] by ''Tariq Alkhalifah'': '''Geophysics''', 76, WA31-WA42, (2011)
* [https://ahay.org/RSF/book/swag/anisogath/article_html/ Angle gathers in wave-equation imaging for transversely isotropic media] by ''Tariq Alkhalifah and Sergey Fomel'': '''Geophysical Prospecting''', 59, 422-431 (2011)
* [https://ahay.org/RSF/book/swag/eikds/paper_html/ An eikonal based formulation for traveltime perturbation with respect to the source location] by ''Tariq Alkhalifah and Sergey Fomel'': '''Geophysics''', 75, T175-T183 (2010)
* [https://ahay.org/RSF/book/swag/waveds/paper_html/ Acoustic wavefield evolution as function of source location perturbation] by ''Tariq Alkhalifah'': '''Geophysical Journal International''', 183, 1324-1331 (2010)
* [https://ahay.org/RSF/book/swag/introDTI/article_html/ A transversely isotropic medium with a tilted symmetry axis normal to the reflector] by ''Tariq Alkhalifah and Paul Sava'': '''Geophysics''' (Letters), 75, A19-A24 (2010)

== [https://ahay.org/RSF/book/tccs/ Texas Consortium for Computational Seismology] ==
* [https://ahay.org/RSF/book/tccs/timewarp/paper_html/ Probabilistic moveout analysis by time warping] by ''Yanadet Sripanich, Sergey Fomel, Jeannot Trampert, William Burnett, and Thomas Hess'', '''Geophysics''', v. 85, U1–U20, (2020)
* [https://ahay.org/RSF/book/tccs/rtseis/paper_html/ Relative time seislet transform] by ''Zhicheng Geng, Xinming Wu, Sergey Fomel, and Yangkang Chen'', '''Geophysics''', v. 85, V223–V232, (2020)
* [https://ahay.org/RSF/book/tccs/pwstack/paper_html/ High-resolution recursive stacking using plane-wave construction] by ''Kelly Regimbal and Sergey Fomel'', '''SEG Expanded Abstracts''', 4069-4074, (2016)
* [https://ahay.org/RSF/book/tccs/pimicro/paper_html/ Microseismic source localization using time-domain path-integral migration] by ''Yunzhi Shi, Dmitrii Merzlikin, and Sergey Fomel'', '''SEG Expanded Abstracts''', 2601-2606, (2016)
* [https://ahay.org/RSF/book/tccs/pfwi/paper_html/ Full waveform inversion of passive seismic data for sources and velocities] by ''Junzhe Sun, Zhiguang Xue, Sergey Fomel, Tieyuan Zhu, and Nori Nakata'', '''SEG Expanded Abstracts''', 1405-1410, (2016)
* [https://ahay.org/RSF/book/tccs/mistie/paper_html/ Using well-seismic mistie to update the velocity model] by ''Sean Bader, Sergey Fomel, and Zhiguang Xue'', '''SEG Expanded Abstracts''', 5218-5222, (2018)
* [https://ahay.org/RSF/book/tccs/micro/paper_html/ Investigating the possibility of locating microseismic sources using distributed sensor networks] by ''Junzhe Sun, Tieyuan Zhu, Sergey Fomel, and Wen-Zhan Song'', '''SEG Expanded Abstracts''', 2485-2490, (2015)
* [https://ahay.org/RSF/book/tccs/match/paper_html/ Least-squares non-stationary triangle smoothing] by ''Reem Alomar and Sergey Fomel'', '''IMAGE Expanded Abstracts''', 2847-2851, (2022)
* [https://ahay.org/RSF/book/tccs/ltftapwd/paper_html/ Estimation of timeshifts in time-lapse seismic images using spectral decomposition] by ''Mason Phillips and Sergey Fomel'', '''SEG Expanded Abstracts''', 5839-5844, (2017)
* [https://ahay.org/RSF/book/tccs/interpfault/paper_html/ Well log interpolation guided by geologic distance] by ''Yunzhi Shi, Xinming Wu, and Sergey Fomel'', '''SEG Expanded Abstracts''', 1939-1944, (2017)
* [https://ahay.org/RSF/book/tccs/beyond1d/paper_html/ Effects of lateral heterogeneity on time-domain processing parameters] by ''Yanadet Sripanich, Sergey Fomel, and Alexey Stovas'', '''Geophysical Journal International''', v. 219, 1181–1201, (2019)
* [https://ahay.org/RSF/book/tccs/apwd/paper_html/ Seismic time-lapse image registration using amplitude-adjusted plane-wave destruction] by ''Mason Phillips and Sergey Fomel'', '''SEG Expanded Abstracts''', 5473-5478, (2016)
* [https://ahay.org/RSF/book/tccs/pwshape/paper_html/ Seismic data interpolation using plane-wave shaping regularization] by ''Ryan Swindeman and Sergey Fomel'', '''SEG Expanded Abstracts''', 3853-3858, (2015)
* [https://ahay.org/RSF/book/tccs/varipick/paper_html/ A variational approach for picking optimal surfaces from semblance-like panels] by ''Luke Decker and Sergey Fomel'', '''Geophysics''', v. 87, U93-U108, (2022)
* [https://ahay.org/RSF/book/tccs/wetm/paper_html/ Wave-equation time migration] by ''Sergey Fomel and Harpreet Kaur'', '''Geophysics''', v. 86, S103-S111, (2021)
* [https://ahay.org/RSF/book/tccs/probdif/paper_html/ A probabilistic approach to seismic diffraction imaging] by ''Luke Decker and Sergey Fomel'', '''Lithosphere''', v. 2021, 6650633, (2021)
* [https://ahay.org/RSF/book/tccs/dlchan/paper_html/ Automatic channel detection using deep learning] by ''Nam Pham, Sergey Fomel, and Dallas Dunlap'', '''Interpretation''', v. 7, SE43-SE50, (2019)
* [https://ahay.org/RSF/book/tccs/dtwaniso/paper_html/ Quantifying and correcting residual azimuthal anisotropic moveout in image gathers using dynamic time warping] by ''Luke Decker and Qunshan Zhang'', '''Geophysics''', v. 85, O71-O82, (2020)
* [https://ahay.org/RSF/book/tccs/anisodiff/paper_html/ Least-squares diffraction imaging using shaping regularization by anisotropic smoothing] by ''Dmitrii Merzlikin, Sergey Fomel, and Xinming Wu'', '''Geophysics''', v. 85, S313-S325, (2020)
* [https://ahay.org/RSF/book/tccs/drr5d/paper_html/ Simultaneous denoising and reconstruction of 5D seismic data via damped rank-reduction method] by ''Yangkang Chen, Dong Zhang, Zhaoyu Jin, Xiaohong Chen, Shaohuan Zu, Weilin Huang, and Shuwei Gan'', '''Geophysical Journal International''', 206, 1695-1717, (2016)
* [https://ahay.org/RSF/book/tccs/npm/paper_html/ Data-driven time-frequency analysis of seismic data using non-stationary Prony method] by ''Guoning Wu, Sergey Fomel, and Yangkang Chen'', '''Geophysical Prospecting''', 66, 85-97, (2018)
* [https://ahay.org/RSF/book/tccs/enhemd/paper_html/ Enhancing seismic reflections using empirical mode decomposition in the flattened domain] by ''Yangkang Chen, Guoyin Zhang, Shuwei Gan, and Chenglin Zhang'', '''Journal of Applied Geophysics''', 119, 99-105, (2015)
* [https://ahay.org/RSF/book/tccs/pcastack/paper_html/ Application of principal component analysis in weighted stacking of seismic data] by ''Jianyong Xie, Wei Chen, Dong Zhang, Shaohuan Zu, and Yangkang Chen'', '''IEEE Geoscience and Remote Sensing Letters''', 14, 1213-1217, (2017)
* [https://ahay.org/RSF/book/tccs/svscan/paper_html/ Velocity analysis of simultaneous-source data using high-resolution semblance - coping with the strong noise] by ''Shuwei Gan, Shoudong Wang, Yangkang Chen, Shan Qu, and Shaohuan Zu'', '''Geophysical Journal International''', 204, 768-779, (2016)
* [https://ahay.org/RSF/book/tccs/cs/paper_html/ Compressive sensing for seismic data reconstruction via fast projection onto convex sets based on seislet transform] by ''Shuwei Gan, Shoudong Wang, Yangkang Chen, Xiaohong Chen, Weiling Huang, and Hanming Chen'', '''Journal of Applied Geophysics''', 130, 194-208, (2016)
* [https://ahay.org/RSF/book/tccs/sgk/paper_html/ Fast dictionary learning for noise attenuation of multidimensional seismic data] by ''Yangkang Chen'', '''Geophysical Journal International''', 209, 21-31, (2017)
* [https://ahay.org/RSF/book/tccs/sswtapp/paper_html/ Probing the subsurface karst features using time-frequency decomposition] by ''Yangkang Chen'', '''Interpretation''', 4, T541-T550, (2016)
* [https://ahay.org/RSF/book/tccs/asa/paper_html/ Application of spectral decomposition using regularized non-stationary autoregression to random noise attenuation] by ''Wencheng Yang, Runqiu Wang, Yangkang Chen, Jian Wu, Jiang Yuan, and Shuwei Gan'', '''Journal of Geophysics and Engineering''', 12, 175-187, (2015)
* [https://ahay.org/RSF/book/tccs/drr3d/paper_html/ An open-source Matlab code package for improved rank-reduction 3D seismic data denoising and reconstruction] by ''Yangkang Chen, Weilin Huang, Dong Zhang, and Wei Chen'', '''Computers & Geosciences''', 95, 59-66, (2016)
* [https://ahay.org/RSF/book/tccs/strsvd/paper_html/ Structure-oriented singular value decomposition for random noise attenuation of seismic data] by ''Shuwei Gan, Yangkang Chen, Shaohuan Zu, Shan Qu, and Wei Zhong'', '''Journal of Geophysics and Engineering''', 12, 262-272, (2015)
* [https://ahay.org/RSF/book/tccs/dealiase2/paper_html/ One-step slope estimation for dealiased seismic data reconstruction via iterative seislet thresholding] by ''Wei Liu, Siyuan Cao, Shuwei Gan, Yangkang Chen, Shaohuan Zu, and Zhaoyu Jin'', '''IEEE Geoscience and Remote Sensing Letters''', 13, 1462-1466, (2016)
* [https://ahay.org/RSF/book/tccs/dipseis/paper_html/ Dip-separated structural filtering using seislet transform and adaptive empirical mode decomposition based dip filter] by ''Yangkang Chen'', '''Geophysical Journal International''', 206, 457-469, (2016)
* [https://ahay.org/RSF/book/tccs/halfthr/paper_html/ Irregular seismic data reconstruction using a percentile-half-thresholding algorithm] by ''Yangkang Chen, Keling Chen, Peidong Shi, and Yanyan Wang'', '''Journal of Geophysics and Engineering''', 11, 065001, (2014)
* [https://ahay.org/RSF/book/tccs/demulemd/paper_html/ Multiple reflections noise attenuation using adaptive randomized-order empirical mode decomposition] by ''Wei Chen, Jianyong Xie, Shaohuan Zu, Shuwei Gan, and Yangkang Chen'', '''IEEE Geoscience and Remote Sensing Letters''', 14, 18-22, (2017)
* [https://ahay.org/RSF/book/tccs/dmssa/paper_html/ Damped multichannel singular spectrum analysis for 3D random noise attenuation] by ''Weilin Huang, Runqiu Wang, Yangkang Chen, Huijian Li, and Shuwei Gan'', '''Geophysics''', 81, V261-V270, (2016)
* [https://ahay.org/RSF/book/tccs/dealiase/paper_html/ De-aliased seismic data interpolation using seislet transform with low-frequency constraint] by ''Shuwei Gan, Shoudong Wang, Yangkang Chen, Yizhuo Zhang, and Zhaoyu Jin'', '''IEEE Geoscience and Remote Sensing Letters''', 12, 2150-2154, (2015)
* [https://ahay.org/RSF/book/tccs/fraclapl/paper_html/ Viscoacoustic modeling and imaging using low-rank approximation] by ''Junzhe Sun, Tieyuan Zhu, and Sergey Fomel'', '''Geophysics''', 80, A103-A108, (2015)
* [https://ahay.org/RSF/book/tccs/welllogs/paper_html/ Missing log data interpolation and semiautomatic seismic well ties using data matching techniques] by ''Sean Bader, Xinming Wu, and Sergey Fomel'', '''Interpretation''', 7, T374-T361, (2019)
* [https://ahay.org/RSF/book/tccs/acrossfault/paper_html/ Predictive painting across faults] by ''Zhiguang Xue, Xinming Wu, and Sergey Fomel'', '''Interpretation''', 6, T449-T455, (2018)
* [https://ahay.org/RSF/book/tccs/sparse/paper_html/ Least-squares path-summation diffraction imaging using sparsity constraints] by ''Dmitrii Merzlikin, Sergey Fomel, and Mrinal K. Sen'', '''Geophysics''', 84, S187–S200, (2019)
* [https://ahay.org/RSF/book/tccs/gmresq/paper_html/ Q-compensated least-squares reverse time migration using lowrank one-step wave extrapolation] by ''Junzhe Sun, Sergey Fomel, Tieyuan Zhu, and Jingwei Hu'', '''Geophysics''', 81, S271-S279, (2016)
* [https://ahay.org/RSF/book/tccs/eseis/paper_html/ EMD-seislet transform] by ''Yangkang Chen and Sergey Fomel'', '''Geophysics''', 83, A27-A32, (2018)
* [https://ahay.org/RSF/book/tccs/elas/paper_html/ Recursive integral time extrapolation of elastic waves using low-rank symbol approximation] by ''Junzhe Sun, Sergey Fomel, Yanadet Sripanich, and Paul Fowler'', '''Geophysical Journal International''', 211, 1478-1493, (2017)
* [https://ahay.org/RSF/book/tccs/merge/paper_html/ Matching and merging high-resolution and legacy seismic images] by ''Sarah Greer and Sergey Fomel'', '''Geophysics''', 83, V115-V122, (2018)
* [https://ahay.org/RSF/book/tccs/t2dweak/paper_html/ Fast time-to-depth conversion and interval velocity estimation in the case of weak lateral variations] by ''Yanadet Sripanich and Sergey Fomel'', '''Geophysics''', 83, S227-S235, (2018)
* [https://ahay.org/RSF/book/tccs/sobel/paper_html/ Plane-wave Sobel attribute for discontinuity enhancement in seismic images] by ''Mason Phillips and Sergey Fomel'', '''Geophysics''', 82, WB63-WB69, (2017)
* [https://ahay.org/RSF/book/tccs/fwiseislet/paper_html/ Full-waveform inversion using seislet regularization] by ''Zhiguang Xue, Hejun Zhu, and Sergey Fomel'', '''Geophysics''', 82, A43-A49, (2017)
* [https://ahay.org/RSF/book/tccs/ovc/paper_html/ Diffraction imaging and time-migration velocity analysis using oriented velocity continuation] by ''Luke Decker, Dmitrii Merzlikin, and Sergey Fomel'', '''Geophysics''', 82, U25-U35, (2017)
* [https://ahay.org/RSF/book/tccs/pi/paper_html/ Analytical path-summation imaging of seismic diffractions] by ''Dmitrii Merzlikin and Sergey Fomel'', '''Geophysics''', 82, S51-S59, (2017)
* [https://ahay.org/RSF/book/tccs/hyper3/paper_html/ 3D generalized nonhyperboloidal moveout approximation] by ''Yanadet Sripanich, Sergey Fomel, Alexey Stovas, and Qi Hao'', '''Geophysics''', 82, C49-C59, (2017)
* [https://ahay.org/RSF/book/tccs/decomp/paper_html/ Elastic wave-vector decomposition in heterogeneous anisotropic media] by ''Yanadet Sripanich, Sergey Fomel, Junzhe Sun, and Jiubing Cheng'', '''Geophysical Prospecting''', doi 10.1111/1365-2478.12482, (2016)
* [https://ahay.org/RSF/book/tccs/interval/paper_html/ Theory of interval traveltime parameter estimation in layered anisotropic media] by ''Yanadet Sripanich and Sergey Fomel'', '''Geophysics''', 81, C253-C263, (2016)
* [https://ahay.org/RSF/book/tccs/onestep/paper_html/ Lowrank one-step wave extrapolation for reverse-time migration] by ''Junzhe Sun, Sergey Fomel, and Lexing Ying'', '''Geophysics''', 81, S39-S54, (2016)
* [https://ahay.org/RSF/book/tccs/dsd/paper_html/ Double sparsity dictionary for seismic noise attenuation] by ''Yangkang Chen, Jianwei Ma, and Sergey Fomel'', '''Geophysics''', 81, V17-V30, (2016)
* [https://ahay.org/RSF/book/tccs/intshape/paper_html/ Seismic data interpolation using nonlinear shaping regularization] by ''Yangkang Chen, Lele Zhang, and Le-wei Mo'', '''Journal of Seismic Exploration''', 24, 327-342, (2015)
* [https://ahay.org/RSF/book/tccs/orthogroll/paper_html/ Ground-roll noise attenuation using a simple and effective approach based on local band limited orthogonalization] by ''Yangkang Chen, Shebao Jiao, Jianwei Ma, Hanming Chen, Yatong Zhou, and Shuwei Gan'', '''IEEE Geoscience and Remote Sensing Letters''', 12, 2316-2320, (2015)
* [https://ahay.org/RSF/book/tccs/shemd/paper_html/ Random noise attenuation by a selective hybrid approach using f-x empirical mode decomposition] by ''Yangkang Chen, Shuwei Gan, Tingting Liu, Jiang Yuan, Yizhuo Zhang, and Zhaoyu Jin'', '''Journal of Geophysics and Engineering''', 12, 12-25, (2015)
* [https://ahay.org/RSF/book/tccs/svmf/paper_html/ Deblending using a space-varying median filter] by ''Yangkang Chen'', '''Exploration Geophysics''', doi 10.1071/EG14051
* [https://ahay.org/RSF/book/tccs/group3/paper_html/ On anelliptic approximations for qP velocities in TI and orthorhombic media] by ''Yanadet Sripanich and Sergey Fomel'', '''Geophysics''', 80, C89-C105, (2015)
* [https://ahay.org/RSF/book/tccs/dbortho/paper_html/ Iterative deblending with multiple constraints based on shaping regularization] by ''Yangkang Chen'', '''IEEE Geoscience and Remote Sensing Letters''', doi 10.1109/LGRS.2015.2463815
* [https://ahay.org/RSF/book/tccs/vscan/paper_html/ Velocity analysis using similarity-weighted semblance] by ''Yangkang Chen, Tingting Liu, and Xiaohong Chen'', '''Geophysics''', 80, A75-A82, (2015)
* [https://ahay.org/RSF/book/tccs/aii/paper_html/ Structure-constrained relative acoustic impedance using stratigraphic coordinates] by ''Parvaneh Karimi'', '''Geophysics''', 80, A63-A67, (2015)
* [https://ahay.org/RSF/book/tccs/scan3/paper_html/ A fast algorithm for 3D azimuthally anisotropic velocity scan] by ''Jingwei Hu, Sergey Fomel, and Lexing Ying'', '''Geophysical Prospecting''', 63, 368-377, (2015)
* [https://ahay.org/RSF/book/tccs/strat/paper_html/ Stratigraphic coordinates, a coordinate system tailored to seismic interpretation] by ''Parvaneh Karimi and Sergey Fomel'', '''Geophysical Prospecting''', v. 63, 1246-1255, (2015)
* [https://ahay.org/RSF/book/tccs/synth/paper_html/ Carbonate reservoir characterization using seismic diffraction imaging] by ''Luke Decker, Xavier Janson, and Sergey Fomel'', '''Interpretation''', 3, SF21-SF30, (2015)
* [https://ahay.org/RSF/book/tccs/ortho/paper_html/ Random noise attenuation using local signal-and-noise orthogonalization] by ''Yangkang Chen and Sergey Fomel'', '''Geophysics''', 80, WD1-WD9, (2015)
* [https://ahay.org/RSF/book/tccs/synwav/paper_html/ Time-frequency analysis of seismic data using synchrosqueezing wavelet transform] by ''Yangkang Chen, Tingting Liu, Xiaohong Chen, Jingye Li, and Erying Wang'', '''Journal of Seismic Exploration''', 23, 303-312, (2014)
* [https://ahay.org/RSF/book/tccs/nmodeblend/paper_html/ Deblending using normal moveout and median filtering in common-midpoint gathers] by ''Yangkang Chen, Jiang Yuan, Zhaoyu Jin, Keling Chen, and Lele Zhang'', '''Journal of Geophysics and Engineering''', 11, 045012, (2014)
* [https://ahay.org/RSF/book/tccs/time2depth2/paper_html/ A robust approach to time-to-depth conversion and interval velocity estimation from time migration in the presence of lateral velocity variations] by ''Siwei Li and Sergey Fomel'', '''Geophysical Prospecting''', 63, 315-337, (2015)
* [https://ahay.org/RSF/book/tccs/deblend/paper_html/ Iterative deblending of simultaneous-source seismic data using seislet-domain shaping regularization] by ''Yangkang Chen, Sergey Fomel, and Jingwei Hu'', '''Geophysics''', 79, V179-V189, (2014)
* [https://ahay.org/RSF/book/tccs/sglowrank/paper_html/ Lowrank seismic wave extrapolation on a staggered grid] by ''Gang Fang, Sergey Fomel, Qizhen Du, and Jingwei Hu'', '''Geophysics''', 79, T157-T168, (2014)
* [https://ahay.org/RSF/book/tccs/emdpf/paper_html/ Random noise attenuation by f-x empirical mode decomposition predictive filtering] by ''Yangkang Chen and Jitao Ma'', '''Geophysics''', 79, V81-V91, (2014)
* [https://ahay.org/RSF/book/tccs/optapert/paper_html/ Selecting an optimal aperture in Kirchhoff migration using dip-angle images] by ''Alexander Klokov and Sergey Fomel'', '''Geophysics''', 78, S243-S254, (2013)
* [https://ahay.org/RSF/book/tccs/phase/paper_html/ Local skewness attribute as a seismic phase detector] by ''Sergey Fomel and Mirko van der Baan'', '''Interpretation''', 2, SA49-SA56, (2014)
* [https://ahay.org/RSF/book/tccs/uncert/paper_html/ Structural uncertainty of time-migrated seismic images] by ''Sergey Fomel and Evgeny Landa'', '''Journal of Applied Geophysics''', 101, 27–30, (2014)
* [https://ahay.org/RSF/book/tccs/psp/paper_html/ A parallel sweeping preconditioner for heterogeneous 3D Helmholtz equations] by ''Jack Poulson, Björn Engquist, Siwei Li, and Lexing Ying'', '''SIAM Journal on Scientific Computing''', 35, C194-C212, (2013)
* [https://ahay.org/RSF/book/tccs/dsrtomo/paper_html/ First-break traveltime tomography with the double-square-root eikonal equation] by ''Siwei Li, Alexander Vladimirsky, and Sergey Fomel'', '''Geophysics''', 78, U89-U101, (2013)
* [https://ahay.org/RSF/book/tccs/nar/paper_html/ Seismic data decomposition into spectral components using regularized nonstationary autoregression] by ''Sergey Fomel'', '''Geophysics''', 78, O69-O76, (2013)
* [https://ahay.org/RSF/book/tccs/specrecom/paper_html/ Automated spectral recomposition with application in stratigraphic interpretation] by ''Yihua Cai, Sergey Fomel, and Hongliu Zeng'', '''Interpretation''', 1, SA109-SA116, (2013)
* [https://ahay.org/RSF/book/tccs/opwd/paper_html/ Omnidirectional plane-wave destruction] by ''Zhonghuan Chen, Sergey Fomel, and Wenkai Lu'', '''Geophysics''', 78, V171-V179, (2013)
* [https://ahay.org/RSF/book/tccs/butterfly/paper_html/ A fast butterfly algorithm for generalized Radon transforms] by ''Jingwei Hu, Sergey Fomel, Laurent Demane, and Lexing Ying'', '''Geophysics''', 78, U41-U51, (2013)
* [https://ahay.org/RSF/book/tccs/orthorhombic/paper_html/ Modeling of pseudo-acoustic P-waves in orthorhombic media with a lowrank approximation] by ''Xiaolei Song and Tariq Alkhalifah'', '''Geophysics''', 78, C33-C40, (2013)
* [https://ahay.org/RSF/book/tccs/eikods/paper_html/ Kirchhoff migration using eikonal-based computation of traveltime source-derivatives] by ''Siwei Li and Sergey Fomel'', '''Geophysics''', 78, S211-S219, (2013)
* [https://ahay.org/RSF/book/tccs/lfd/paper_html/ Lowrank finite-differences and lowrank Fourier finite-differences for seismic wave extrapolation in the acoustic approximation] by ''Xiaolei Song, Sergey Fomel, and Lexing Ying'', '''Geophysical Journal International''', 193, 960-969, (2013)
* [https://ahay.org/RSF/book/tccs/fpwd/paper_html/ Accelerated plane-wave destruction] by ''Zhonghuan Chen, Sergey Fomel, and Wenkai Lu'', '''Geophysics''', 78, V1-V9, (2013)
* [https://ahay.org/RSF/book/tccs/crs/paper_html/ Non-hyperbolic common reflection surface] by ''Sergey Fomel and Roman Kazinnik'', '''Geophysical Prospecting''', 61, 21-27, (2013)
* [https://ahay.org/RSF/book/tccs/lowrank/paper_html/ Seismic wave extrapolation using lowrank symbol approximation] by ''Sergey Fomel, Lexing Ying, and Xiaolei Song'', '''Geophysical Prospecting''', 61, 526–536, (2013)
* [https://ahay.org/RSF/book/tccs/ltft/paper_html/ Seismic data analysis using local time-frequency decomposition] by ''Yang Liu and Sergey Fomel'', '''Geophysical Prospecting''', 61, 516–525, (2013)
* [https://ahay.org/RSF/book/tccs/timefreq/paper_html/ Time-frequency analysis of seismic data using local attributes] by ''Guochang Liu, Sergey Fomel, and Xiaohong Chen'', '''Geophysics''', 76, P23-P34, (2011)
* [https://ahay.org/RSF/book/tccs/apefint/paper_html/ Seismic data interpolation beyond aliasing using regularized nonstationary autoregression] by ''Yang Liu and Sergey Fomel'', '''Geophysics''', 76, V69-V77, (2011)
* [https://ahay.org/RSF/book/tccs/ffd/paper_html/ Fourier finite-difference wave propagation] by ''Xiaolei Song and Sergey Fomel'', '''Geophysics''', 76, T123-T129, (2011)
* [https://ahay.org/RSF/book/tccs/reversible/paper_html/ A reversible transform for seismic data processing] by ''William Burnett and Robert Ferguson'', '''Journal of Geophysics and Engineering''', 8, 477-486, (2011)
* [https://ahay.org/RSF/book/tccs/vc3/paper_html/ Azimuthally anisotropic 3D velocity continuation] by ''William Burnett and Sergey Fomel'': '''International Journal of Geophysics''', Article ID 484653, (2011)
* [https://ahay.org/RSF/book/tccs/agath/paper_html/ Theory of 3-D angle gathers in wave-equation seismic imaging] by ''Sergey Fomel'': '''Journal of Petroleum Exploration and Production Technology''', 1, 11-16, (2011)
* [https://ahay.org/RSF/book/tccs/oc3/paper_html/ OC-seislet: seislet transform construction with differential offset continuation] by ''Yang Liu and Sergey Fomel'': '''Geophysics''', 75, WB235-WB245, (2010)
* [https://ahay.org/RSF/book/tccs/stackadcig/paper_html/ Stacking angle-domain common-image gathers for normalization of illumination] by ''Guochang Liu, Sergey Fomel, and Xiaohong Chen'': '''Geophysical Prospecting''', 59, 244-255, (2011)
* [https://ahay.org/RSF/book/tccs/flat/paper_html/ Predictive painting of 3-D seismic volumes] by ''Sergey Fomel'': '''Geophysics''', 75, no. 4, A25-A30, (2010)
* [https://ahay.org/RSF/book/tccs/seislet/paper_html/ Seislet transform and seislet frame] by ''Sergey Fomel and Yang Liu'': '''Geophysics''', 75, no. 3, V25-V38, (2010)
* [https://ahay.org/RSF/book/tccs/hyper/paper_html/ Generalized nonhyperbolic moveout approximation] by ''Sergey Fomel and Alexey Stovas'': '''Geophysics''', 75, no. 2, U9-U18, (2010)
* [https://ahay.org/RSF/book/tccs/strfilter/paper_html/ Nonlinear structure-enhancing filtering using plane-wave prediction] by ''Yang Liu, Sergey Fomel, and Guochang Liu'': '''Geophysical Prospecting''', 58, 415-427, (2010)
* [https://ahay.org/RSF/book/tccs/nmo3/paper_html/ 3D velocity-independent elliptically-anisotropic moveout correction] by ''William Burnett and Sergey Fomel'': '''Geophysics''', 74, no. 5, WB129-WB136, (2009)
* [https://ahay.org/RSF/book/tccs/simistack/paper_html/ Stacking seismic data using local correlation] by ''Guochang Liu, Sergey Fomel, Long Jin, and Xiaohong Chen'': '''Geophysics''', 74, no. 3, V43-V48, (2009)
* [https://ahay.org/RSF/book/tccs/atten/paper_html/ Fractal heterogeneities in sonic logs and low-frequency scattering attenuation] by ''Thomas J. Browaeys and Sergey Fomel'': '''Geophysics''', 74, no. 2, WA77-WA92, (2009)
* [https://ahay.org/RSF/book/tccs/timelapse/paper_html/ Time-lapse image registration using the local similarity attribute] by ''Sergey Fomel and Long Jin'': '''Geophysics''', 74, no. 2, A7-A11, (2009)
* [https://ahay.org/RSF/book/tccs/medianfilter/paper_html/ A 1-D time-varying median filter for seismic random, spike-like noise elimination] by ''Yang Liu, Cai Liu, and Dian Wang'': '''Geophysics''', 74, V17-V24, (2009)
* [https://ahay.org/RSF/book/tccs/lpf/paper_html/ Adaptive multiple subtraction using regularized nonstationary regression] by ''Sergey Fomel'': '''Geophysics''', 74, no. 1, V25-V33, (2009)
* [https://ahay.org/RSF/book/tccs/time2depth/paper_html/ Time-to-depth conversion and seismic velocity estimation using time-migration velocity] by ''Maria Cameron, Sergey Fomel, and James Sethian'': '''Geophysics''', 73, no. 5, VE205-VE210, (2008)
* [https://ahay.org/RSF/book/tccs/avo/paper_html/ Velocity analysis using AB semblance] by ''Sergey Fomel'': '''Geophysical Prospecting''', v. 57, 311-321 (2009)
* [https://ahay.org/RSF/book/tccs/diffr/paper_html/ Post-stack velocity analysis by separation and imaging of seismic diffractions] by ''Sergey Fomel, Evgeny Landa, and M. Turhan Taner'': '''Geophysics''', 72, U89-U94, (2007)
* [https://ahay.org/RSF/book/tccs/pmig/paper_html/ Velocity-independent time-domain seismic imaging using local event slopes] by ''Sergey Fomel'': '''Geophysics''', 72, no. 3, S139-S147, (2007)
* [https://ahay.org/RSF/book/tccs/attr/paper_html/ Local seismic attributes] by ''Sergey Fomel'': '''Geophysics''', 72, no. 3, A29-A33, (2007)
* [https://ahay.org/RSF/book/tccs/shape/paper_html/ Shaping regularization in geophysical estimation problems] by ''Sergey Fomel'': '''Geophysics''', 72 , no. 2, R29-R36, (2007)
* [https://ahay.org/RSF/book/tccs/group/paper_html/ On anelliptic approximations for qP velocities in transversally isotropic media] by ''Sergey Fomel'': '''Geophysical Prospecting''', v. 52, 247-259 (2004)

== [https://ahay.org/RSF/book/tongji/ Tongji University] ==
* [https://ahay.org/RSF/book/tongji/decoupledpropagation/paper_html/ Simulating propagation of decoupled elastic waves using low-rank approximate mixed-domain integral operators for anisotropic media] by ''Jiubing Cheng, Tariq Alkhalifah, Zedong Wu, Peng Zou, and Chenlong Wang'': '''Geophysics''', 81, T63-T77, (2016)
* [https://ahay.org/RSF/book/tongji/qswave/paper_html/ Simulating propagation of separated wave modes in general anisotropic media, Part II: qS-wave propagators] by ''Jiubing Cheng and Wei Kang'': '''Geophysics''', 81, C39-C52, (2016)
* [https://ahay.org/RSF/book/tongji/qpwave/paper_html/ Simulating propagation of separated wave modes in general anisotropic media, Part I: qP-wave propagators] by ''Jiubing Cheng and Wei Kang'': '''Geophysics''', 79, C1-C18, (2014)
* [https://ahay.org/RSF/book/tongji/lrmode/paper_html/ Fast algorithms for elastic-wave-mode separation and vector decomposition using low-rank approximation for anisotropic media] by ''Jiubing Cheng and Sergey Fomel'': '''Geophysics''', 79, C97-C110, (2014)

== [https://ahay.org/RSF/book/trip/ The Rice Inversion Project] ==
* [https://ahay.org/RSF/book/trip/asg/paper_html/ Acoustic staggered grid modeling in IWAVE] by ''William W. Symes''
* [https://ahay.org/RSF/book/trip/struct/paper_html/ IWAVE structure and basic use cases] by ''William W. Symes''

== [https://ahay.org/RSF/book/uh/ University of Houston] ==
* [https://ahay.org/RSF/book/uh/avostack/paper_html/ Weighted stacking of seismic AVO data using hybrid AB semblance and local similarity] by ''Pan Deng, Yangkang Chen, Yu Zhang, and Hua-Wei Zhou'': '''Journal of Geophysics and Engineering''', 13, 152-163, (2016)

== [https://ahay.org/RSF/book/uwa/ University of Western Australia] ==
* [https://ahay.org/RSF/book/uwa/geo2013ElasticModellingGPU/paper_html/ Solving 3D anisotropic elastic wave equations on parallel GPU devices] by ''Robin M. Weiss and Jeffrey Shragge'': '''Geophysics''', 78, F7-F15, (2013)

== [https://ahay.org/RSF/book/xjtu/ Xi'an Jiaotong University] ==
* [https://ahay.org/RSF/book/xjtu/mcaseislet/paper_html/paper.html Seislet-based morphological component analysis using scale-dependent exponential shrinkage] by ''Pengliang Yang and Sergey Fomel'': '''Journal of Applied Geophysics''', doi : 10.1016/j.jappgeo.2015.04.003, (2015)
* [https://ahay.org/RSF/book/xjtu/gpufwi/paper_html/ A graphics processing unit implementation of time-domain full-waveform inversion] by ''Pengliang Yang, Jinghuai Gao, and Baoli Wang'': '''Geophysics''', 80, F31-F39, (2015)
* [https://ahay.org/RSF/book/xjtu/primer/paper_html/ A numerical tour of wave propagation] by ''Pengliang Yang''
* [https://ahay.org/RSF/book/xjtu/gpurtm/paper_html/ RTM using effective boundary saving: A staggered grid GPU implementation] by ''Pengliang Yang, Jinghuai Gao, and Baoli Wang'': '''Computers & Geosciences''', 68, 64-72, (2014)

== [https://ahay.org/RSF/book/zju/ Zhejiang University] ==
* [https://ahay.org/RSF/book/zju/dtv/paper_html/ Full waveform inversion and joint migration inversion with an automatic directional total variation constraint] by ''Shan Qu, Eric Verschuur, and Yangkang Chen'': '''Geophysics''', 84, no.2, R175-R183, (2019)
* [https://ahay.org/RSF/book/zju/odrr5d/paper_html/ Five-dimensional seismic data reconstruction using the optimally damped rank-reduction method] by ''Yangkang Chen, Min Bai, Zhe Guan, Qingchen Zhang, Mi Zhang, and Hang Wang'': '''Geophysical Journal International''', 222, 1824-1845, (2020)
* [https://ahay.org/RSF/book/zju/odrr3d/paper_html/ Seismic signal enhancement based on the lowrank methods] by ''Min Bai, Guangtan Huang, Hang Wang, and Yangkang Chen'': '''Geophysical Prospecting''', 68, 2783-2807, (2020)
* [https://ahay.org/RSF/book/zju/diffrlrra/paper_html/ Separation and imaging of seismic diffractions using a localized rank-reduction method with adaptively selected ranks] by ''Hang Wang, Xingye Liu, and Yangkang Chen'': '''Geophysics''', 85, V497-V506, (2020)
* [https://ahay.org/RSF/book/zju/qrtm/paper_html/ CuQ-RTM: A CUDA-based code package for stable and efficient Q-compensated reverse time migration] by ''Yufeng Wang, Hui Zhou, Xuebin Zhao, Qingchen Zhang, Poru Zhao, Xiance Yu, and Yangkang Chen'': '''Geophysics''', 84, F1-F15, (2019)
* [https://ahay.org/RSF/book/zju/optnoise/paper_html/ Plane-wave orthogonal polynomial transform for amplitude-preserving noise attenuation] by ''Yangkang Chen, Weilin Huang, Yatong Zhou, Wei Liu, and Dong Zhang'': '''Geophysical Journal International''', 214, 1214-1232, (2018)
* [https://ahay.org/RSF/book/zju/sosvmf/paper_html/ Deblending of simultaneous-source data using a structure-oriented space-varying median filter] by ''Yangkang Chen, Shaohuan Zu, Yufeng Wang, and Xiaohong Chen'': '''Geophysical Journal International''', 216, 1214-1232, (2019)
* [https://ahay.org/RSF/book/zju/q/paper_html/ Multi-channel quality factor Q estimation] by ''Yangkang Chen'': '''Geophysical Journal International''', 218, 655-665, (2019)

Installation

2024-10-15T21:58:47Z

Fomels: /* Prerequisites */

[[Image:Fotolia_4727725_XS.jpg|right|]]
Madagascar has been installed and is periodically tested on different platforms
*Linux distributions (Fedora, RedHat, Ubuntu, etc.)
*MacOS X
*Windows under the [http://www.cygwin.com/ Cygwin] environment.

==Precompiled binary packages==

See the [[Download|Madagascar download page]] for the availability of binary packages.

==Installation from source==

===Platform-specific instructions===

[[Windows|Specific instructions are provided]] for '''Windows''' users.

Please consult the [[Advanced Installation#Platform-specific_installation_advice|Advanced Installation]] guide for other platform-specific instructions.

===Prerequisites===

#C compiler. Any ANSI-compliant compiler such as [http://gcc.gnu.org/ GCC] should work. GCC usually comes pre-installed on Linux machines.
#Python interpreter. [http://www.python.org/ Python] is an interpretable programming language. It is used in Madagascar installation scripts and project management scripts. Python comes pre-installed on some platforms. Madagascar supports Python 3.

Each API option has [[Advanced Installation#Dependencies|its own prerequisites]].

Prerequisites for optional add-on functionality are [[Advanced Installation#Platform specific installation advice|platform-specific]].

[[Windows|Building under cygwin on Windows]] requires several preparatory steps.

===General instructions===

# '''Configuration:''' Open a terminal window, change to the top Madagascar source directory, and run <syntaxhighlight lang="bash">./configure --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> 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 Fortran-90 API bindings in addition to the basic package, run <syntaxhighlight lang="bash">./configure API=f90 --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> After running <tt>./configure</tt> you may see a list of dependencies that your system does not have installed (the items that have "no" next to them). Most of them are optional. If you decide to install additional packages for your platform, rerun the <tt>./configure</tt> command.
# '''Building and installing the package:''' Run <syntaxhighlight lang="bash">make install</syntaxhighlight> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">make; su; make install</syntaxhighlight> or <syntaxhighlight lang="bash">make; sudo make install</syntaxhighlight> If <tt>make</tt> does not exist on your system, an alternative procedure can be found in the [[#Troubleshooting|Troubleshooting]] section.
# '''User setup:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, add to your <tt>$HOME/.bashrc</tt> and <tt>$HOME/.profile</tt> files the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.sh</syntaxhighlight> (if used something different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC). If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.csh</syntaxhighlight> (if used something different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC.) Please be aware that, on some systems, the default value for DATAPATH set in the script above may get automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> in your resource file to another location where you have write access and that allows large files. Remember that the value of DATAPATH should have a slash at the end. e.g. add <syntaxhighlight lang="bash">export DATAPATH=~/RSFDATA/ </syntaxhighlight> to ~/.bashrc and ~/.profile .

==Uninstall==
To clean all intermediate files and all installed files, run <pre>scons -c install</pre> or <pre>make distclean</pre> in the source code directory.

==Troubleshooting==
===Alternative build/install procedure===
# '''Set the environment variables:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, type <syntaxhighlight lang="bash">source env.sh</syntaxhighlight> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <syntaxhighlight lang="bash">source env.csh</syntaxhighlight>
# '''Build:''' Type <tt>scons</tt>
# '''Install:''' Run <tt>scons install</tt> . If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">su; scons install </syntaxhighlight> or <syntaxhighlight lang="bash">sudo scons install</syntaxhighlight>

===Other issues===
Note that <tt>scons</tt> does not inherit your environmental variables including <tt>PATH</tt>.
If the configuration part ends with the message like
<pre>
checking if cc works ... failed
</pre>
the problem may be that your compiler is in an unusual place. Try
<pre>
./configure CC=/full/path/to/cc
</pre>
or
<pre>
./configure CC=`which cc`
</pre>
On Windows under SFU, use the <tt>gcc</tt> compiler
<pre>
./configure CC=/opt/gcc.3.3/bin/gcc
</pre>

Please consult the [[Advanced Installation]] guide for more information.

==Testing and quick start==

Here are a few simple tests and a brief introduction to Madagascar:

Typing any Madagascar command in a terminal window without parameters should generate brief documentation. Try one of the following:

<pre>
sfin
sfattr
sfspike
sfbandpass
sfwiggle
</pre>

If you get an error like "Command not found," you may not have your <tt>$PATH</tt> environment variable set correctly, or you may need to issue the <tt>rehash</tt> command.

Now try making a simple Madagascar data file:
<pre>
sfspike n1=1000 k1=300 > spike.rsf
</pre>

This command generates a one-dimensional list of 1000 numbers, all zero except for a spike equal to one at position 300. If this generates an error like
<pre>
Cannot write to data file /path/spike.rsf@: Bad file descriptor
</pre>
you may need to create the directory pointed to by your <tt>$DATAPATH</tt> environment variable.

The file <tt>spike.rsf</tt> is a text header. The actual data are stored in the binary file pointed to by the <tt>in=</tt> parameter in the header. You can look at the header file directly with <tt>more</tt>, or better, examine the file properties with
<pre>
sfin spike.rsf
</pre>

You can learn more about the contents of <tt>spike.rsf</tt> with
<pre>
sfattr < spike.rsf
</pre>

The following command applies a bandpass filter to <tt>spike.rsf</tt> and puts the result in <tt>filter.rsf</tt>:
<pre>
sfbandpass fhi=2 phase=y < spike.rsf > filter.rsf
</pre>

The following command makes a graphics file from <tt>filter.rsf</tt>:
<pre>
sfwiggle clip=0.02 title="Welcome to Madagascar" < filter.rsf > filter.vpl
</pre>

If you have an X11 display program running, and your <tt>$DISPLAY</tt> environment variable is set correctly, you can display the graphics file with:

<pre>
sfpen < filter.vpl
</pre>

You can pipe Madagascar commands together and do the whole thing at once like this:

<pre>
sfspike n1=1000 k1=300 | sfbandpass fhi=2 phase=y | \
sfwiggle clip=0.02 title="Welcome to Madagascar" | sfpen
</pre>

If you have SCons installed, you can use it to automate Madagascar processing. Here is a simple <tt>SConstruct</tt> file to make <tt>filter.rsf</tt> and <tt>filter.vpl</tt>:

<syntaxhighlight lang="python">
#
# Setting up
#
from rsf.proj import *

#
# Make filter.rsf
#
Flow('filter',None,'spike n1=1000 k1=300 | bandpass fhi=2 phase=y')

#
# Make filter.vpl
#
Result('filter','wiggle clip=0.02 title="Welcome to Madagascar"')

End()
</syntaxhighlight>

Put the file in an empty directory, give it the name <tt>SConstruct</tt>, <tt>cd</tt> to that directory, and issue the command:

<pre>
scons
</pre>

The graphics file is now stored in the <tt>Fig</tt> subdirectory. You can view it manually with:

<pre>
sfpen Fig/filter.vpl
</pre>

... or you can use:

<pre>
scons view
</pre>

When a SConstruct file makes more than one graphics file, the <tt>scons view</tt> command will display all of them in sequence.
[[Image:filter.png|frame|center|Welcome to Madagascar.]]
Now edit the <tt>SConstruct</tt> file: change the title string on the <tt>Result</tt> line to "Hello World!", save the file, and rerun the scons command. You will see that scons has figured out that the file <tt>filter.rsf</tt> does not need to be rebuilt because nothing that affects it has changed. Only the file <tt>filter.vpl</tt> is rebuilt.

Installation

2024-10-15T21:58:07Z

Fomels: typos

[[Image:Fotolia_4727725_XS.jpg|right|]]
Madagascar has been installed and is periodically tested on different platforms
*Linux distributions (Fedora, RedHat, Ubuntu, etc.)
*MacOS X
*Windows under the [http://www.cygwin.com/ Cygwin] environment.

==Precompiled binary packages==

See the [[Download|Madagascar download page]] for the availability of binary packages.

==Installation from source==

===Platform-specific instructions===

[[Windows|Specific instructions are provided]] for '''Windows''' users.

Please consult the [[Advanced Installation#Platform-specific_installation_advice|Advanced Installation]] guide for other platform-specific instructions.

===Prerequisites===

#C compiler. Any ANSI-compliant compiler such as [http://gcc.gnu.org/ GCC] should work. GCC usually comes pre-installed on Linux machines.
#Python interpreter. [http://www.python.org/ Python] is an interpretable programming language. It is used in Madagascar installation scripts and project management scripts. Python comes pre-installed on some platforms. Madagascar supports both Python 2.7 and Python 3.

Each API option has [[Advanced Installation#Dependencies|its own prerequisites]].

Prerequisites for optional add-on functionality are [[Advanced Installation#Platform specific installation advice|platform-specific]].

[[Windows|Building under cygwin on Windows]] requires several preparatory steps.

===General instructions===

# '''Configuration:''' Open a terminal window, change to the top Madagascar source directory, and run <syntaxhighlight lang="bash">./configure --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> 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 Fortran-90 API bindings in addition to the basic package, run <syntaxhighlight lang="bash">./configure API=f90 --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> After running <tt>./configure</tt> you may see a list of dependencies that your system does not have installed (the items that have "no" next to them). Most of them are optional. If you decide to install additional packages for your platform, rerun the <tt>./configure</tt> command.
# '''Building and installing the package:''' Run <syntaxhighlight lang="bash">make install</syntaxhighlight> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">make; su; make install</syntaxhighlight> or <syntaxhighlight lang="bash">make; sudo make install</syntaxhighlight> If <tt>make</tt> does not exist on your system, an alternative procedure can be found in the [[#Troubleshooting|Troubleshooting]] section.
# '''User setup:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, add to your <tt>$HOME/.bashrc</tt> and <tt>$HOME/.profile</tt> files the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.sh</syntaxhighlight> (if used something different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC). If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.csh</syntaxhighlight> (if used something different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC.) Please be aware that, on some systems, the default value for DATAPATH set in the script above may get automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> in your resource file to another location where you have write access and that allows large files. Remember that the value of DATAPATH should have a slash at the end. e.g. add <syntaxhighlight lang="bash">export DATAPATH=~/RSFDATA/ </syntaxhighlight> to ~/.bashrc and ~/.profile .

==Uninstall==
To clean all intermediate files and all installed files, run <pre>scons -c install</pre> or <pre>make distclean</pre> in the source code directory.

==Troubleshooting==
===Alternative build/install procedure===
# '''Set the environment variables:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, type <syntaxhighlight lang="bash">source env.sh</syntaxhighlight> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <syntaxhighlight lang="bash">source env.csh</syntaxhighlight>
# '''Build:''' Type <tt>scons</tt>
# '''Install:''' Run <tt>scons install</tt> . If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">su; scons install </syntaxhighlight> or <syntaxhighlight lang="bash">sudo scons install</syntaxhighlight>

===Other issues===
Note that <tt>scons</tt> does not inherit your environmental variables including <tt>PATH</tt>.
If the configuration part ends with the message like
<pre>
checking if cc works ... failed
</pre>
the problem may be that your compiler is in an unusual place. Try
<pre>
./configure CC=/full/path/to/cc
</pre>
or
<pre>
./configure CC=`which cc`
</pre>
On Windows under SFU, use the <tt>gcc</tt> compiler
<pre>
./configure CC=/opt/gcc.3.3/bin/gcc
</pre>

Please consult the [[Advanced Installation]] guide for more information.

==Testing and quick start==

Here are a few simple tests and a brief introduction to Madagascar:

Typing any Madagascar command in a terminal window without parameters should generate brief documentation. Try one of the following:

<pre>
sfin
sfattr
sfspike
sfbandpass
sfwiggle
</pre>

If you get an error like "Command not found," you may not have your <tt>$PATH</tt> environment variable set correctly, or you may need to issue the <tt>rehash</tt> command.

Now try making a simple Madagascar data file:
<pre>
sfspike n1=1000 k1=300 > spike.rsf
</pre>

This command generates a one-dimensional list of 1000 numbers, all zero except for a spike equal to one at position 300. If this generates an error like
<pre>
Cannot write to data file /path/spike.rsf@: Bad file descriptor
</pre>
you may need to create the directory pointed to by your <tt>$DATAPATH</tt> environment variable.

The file <tt>spike.rsf</tt> is a text header. The actual data are stored in the binary file pointed to by the <tt>in=</tt> parameter in the header. You can look at the header file directly with <tt>more</tt>, or better, examine the file properties with
<pre>
sfin spike.rsf
</pre>

You can learn more about the contents of <tt>spike.rsf</tt> with
<pre>
sfattr < spike.rsf
</pre>

The following command applies a bandpass filter to <tt>spike.rsf</tt> and puts the result in <tt>filter.rsf</tt>:
<pre>
sfbandpass fhi=2 phase=y < spike.rsf > filter.rsf
</pre>

The following command makes a graphics file from <tt>filter.rsf</tt>:
<pre>
sfwiggle clip=0.02 title="Welcome to Madagascar" < filter.rsf > filter.vpl
</pre>

If you have an X11 display program running, and your <tt>$DISPLAY</tt> environment variable is set correctly, you can display the graphics file with:

<pre>
sfpen < filter.vpl
</pre>

You can pipe Madagascar commands together and do the whole thing at once like this:

<pre>
sfspike n1=1000 k1=300 | sfbandpass fhi=2 phase=y | \
sfwiggle clip=0.02 title="Welcome to Madagascar" | sfpen
</pre>

If you have SCons installed, you can use it to automate Madagascar processing. Here is a simple <tt>SConstruct</tt> file to make <tt>filter.rsf</tt> and <tt>filter.vpl</tt>:

<syntaxhighlight lang="python">
#
# Setting up
#
from rsf.proj import *

#
# Make filter.rsf
#
Flow('filter',None,'spike n1=1000 k1=300 | bandpass fhi=2 phase=y')

#
# Make filter.vpl
#
Result('filter','wiggle clip=0.02 title="Welcome to Madagascar"')

End()
</syntaxhighlight>

Put the file in an empty directory, give it the name <tt>SConstruct</tt>, <tt>cd</tt> to that directory, and issue the command:

<pre>
scons
</pre>

The graphics file is now stored in the <tt>Fig</tt> subdirectory. You can view it manually with:

<pre>
sfpen Fig/filter.vpl
</pre>

... or you can use:

<pre>
scons view
</pre>

When a SConstruct file makes more than one graphics file, the <tt>scons view</tt> command will display all of them in sequence.
[[Image:filter.png|frame|center|Welcome to Madagascar.]]
Now edit the <tt>SConstruct</tt> file: change the title string on the <tt>Result</tt> line to "Hello World!", save the file, and rerun the scons command. You will see that scons has figured out that the file <tt>filter.rsf</tt> does not need to be rebuilt because nothing that affects it has changed. Only the file <tt>filter.vpl</tt> is rebuilt.