If I write a research paper using Madagascar, do I need to add a reference?

January 19, 2013 FAQ No comments

Please take into account the following considerations:

  1. According to the GPL license, there is no legal requirement to reference Madagascar when you use it.
  2. Please consider contributing your paper to Madagascar. Multiple studies have shown that reproducible papers receive more attention from the readers and make a higher impact. Releasing your paper can also help you maintain your own research results. In words of Jon Claerbout,

    “It takes some effort to organize your research to be reproducible. We found that although the effort seems to be directed to helping other people stand up on your shoulders, the principal beneficiary is generally the author herself. This is because time turns each one of us into another person, and by making effort to communicate with strangers, we help ourselves to communicate with our future selves.”

  3. If codes from Madagascar played an important role in the research that led to your paper, referencing it is a scientifically ethical thing to do. As stated by the Ethical Guidelines of the American Mathematical Society,
    “The correct attribution of mathematical results is essential, both because it encourages creativity, by benefiting the creator whose career may depend on the recognition of the work and because it informs the community of when, where, and sometimes how original ideas entered into the chain of mathematical thought.”

Of course, such statements can be applied not only to mathematical ideas but also to computational results.

How to cite Madagascar? Mike Jackson from the Software Sustainability Institute makes a set of clear recommendations for citing software. A citation may look like Madagascar software. Version 1.4. October 2012. https://www.ahay.org/ or more specific with reference to a particular program used and its author. In BibTeX, you can use something like

@Manual{Madagascar,  
author = {{Madagascar Development Team}},  
title = {Madagascar Software, Version~1.4},  
year = {2012},  
address = {https://www.ahay.org/}  
}

Program of the month: sfricker1

January 8, 2013 Programs No comments

sfricker1 implements 1-D convolution with the Ricker wavelet.

The following example from rsf/rsf/wedge shows convolution modeling with a wedge model using sfricker1.

The convolution is implemented in the frequency domain, where the Ricker wavelet takes the form
$$F(\omega) = \frac{\omega^2}{\omega_0^2}\,\exp\left(-\frac{\omega^2}{\omega_0^2}\right)$$
The peak frequency $\omega_0$ can be specified either in hertz (with frequency= parameter) as a fraction of the Nyquist frequency (with freq= parameter). Optionally, it is possible to combine the Ricker wavelet with a half-order derivative filter using deriv=y.

10 previous programs of the month

Program of the month: sfhalfint

December 23, 2012 Programs No comments

sfhalfint implements half-order integration or differentiation, a filtering operation common in 2-D imaging operators such as as slant stacking or Kirchhoff migration.

By default, sfhalfint performs half-order integration. To apply half-order differentiation, use inv=y. To apply the adjoint operator, use adj=y.

Theoretically, half-order integration and differiation correspond to division by $(i\omega)^{1/2}$. For stability, $i\omega$ is replaced in practice by $1-\rho\,Z$ when doing differentiation and by $\frac{1}{2}\,\frac{1-\rho\,Z}{1+\rho\,Z}$ when doing integration. Here $Z=e^{i\omega\,\Delta t}$. As explained by Jon Claerbout, this approximation attenuates high frequencies and assures a causal impulse response. The value of the $\rho$ parameter is controlled by rho=.

The following plot from bei/ft1/hankel shows the impulse response of half-order differentiation (also known as the “rho filter”)

10 previous programs of the month

The role of selfdocs in Madagascar

December 20, 2012 Documentation No comments

Documentation is an important component of any software product. Madagascar has reproducible documents, wiki pages, example scripts, and source code. Carefully selected variable names and comments in the source code can provide critical assistance to the next developer that extends a program. Every Madagascar program also has selfdoc that appears with the program is executed without parameters. The selfdoc is simple ASCII text that prints to the terminal to help the end users input to the program. There are tools to reformat the selfdoc into other formates like HTML, LaTeX, and man pages (see the selfdoc on sfdoc). Be kind to your end users with a good selfdoc, in a few months YOU might find it useful!
User documentation simply describes how a program is used. A general overview of the program, a description of all the features, and each parameter needs to be described. A description of the input and output data is important, especially with the program is intended to be used in combination with other programs (for example a program might expect input or output data to be forward or inverse Fourier transformed, or the program might expect the input or output data to be transposed). Users often find example flows very helpful. Include the flows in the selfdoc or recommend other useful documents. In depth theory is better left to reproducible documents or printed papers.
Standard sections in the selfdoc are:
NAME
The name of the command or function. This comes from the name file containing your source code.
DESCRIPTION
A one-line description of what it does. This comes from the first line of the comment at the very beginning of your source code.
SYNOPSIS
A terse list of the program’s parameters and illustration of possible values. Experienced users can use this as a reminder of parameter names, whether integer or floating point numbers can be input, and the defaults. This is automatically created for the source by looking for functions that get parameters from the command line (eg sf_getint, sf_getfloat, sf_getstring).
COMMENTS
This is a free form area that contains everything after the first line in the comment at the very beginning of the program’s source code. This is where you describe the input and output data, how you intend the program to be used with other programs, and provide examples. EXAMPLES are often easy to produce and are likely to be exactly what the end user needs. You should also recommend key parameter settings. Some parameter values might be difficult to select, but the research geophysicist and software developer are probably better qualified than a new end user to make initial settings of the parameters. You may be able to recommend tests that can help select improved settings. Be kind to your users, you are fortunate to have someone use and extend your technology.
PARAMETERS
A list of each parameter, the type (integer, float, string, or a list of integers, floats or strings) and the default. This is automatically created from the source code from the name of the function (sf_getint, sf_getfloat, sf_getstring, …). Each parameter is also described using the comment in the source code immediately following the sf_get function call.
USED IN
This sections is automatically created when the program is created. The Madagascar build system searches the main Madagascar directory to find all the places the program is used. A user can use these examples as a template for her processing needs.
SOURCE
This sections is automatically created when the program is created. The Madagascar build system discovers the location of the source code and adds it to the selfdoc.
Example selfdoc for the program sffold is:
NAME
sffold
DESCRIPTION
Make a seismic foldplot/stacking chart.
SYNOPSIS
sffold < in.rsf > out.rsf verbose=1 o1= o2= o3= n1= n2= n3= d1= d2= d3= label1= label2= label3=
COMMENTS
This is a general 3D histogram program implemented to create foldplot or
stacking charts on a 3d project from trace headers. Axis1, 2 and 3 define
the bins for the output fold map. These are usually (offset,xline,iline),
but you might want to compute some other histogram. This can be done by
selecting other segy headers using label1, 2 and 3.
See also fold= option in sfbin for creating 2D histograms.
EXAMPLES:
To make a stacking chart movie showing fold(xline,offset) for each inline
from a 3d segyfile:
sfsegyread tfile=tteapot.rsf hfile=teapot.asc bfile=teapot.bin \
tape=npr3_field.sgy > teapot.rsf
# read the tfile, which contains the segy trace headers
< tteapot.rsf sfdd type=float \ | sffold verbose=1 \ o1=0 n1=96 d1=200 label1=offset \ o2=1 n2=188 d2=1 label2=xline \ o3=1 n3=345 d3=1 label3=iline \ >foldplot.rsf

Program of the month: sfbandpass

November 3, 2012 Programs No comments

sfbandpass implements bandpass filtering using the Butterworth algorithm.

The desired bandwidth is specified by low and high frequencies (in Hertz) flo= and fhi=. A continuous low-pass Butterworth filter is given by
$$B_N^2(\omega) = \displaystyle \frac{1}{\displaystyle 1+\left(\frac{\omega}{\omega_0}\right)^{2N}}$$
The actual filtering is implemented by recursive (Infinite Impulse Response) convolution in the time domain. The number of poles ($N$) for the low-pass and high-pass filters are specified by nplo= and nphi= parameters.

The following example from sep/pwd/hector shows a land shot gather after linear moveout and low-pass filtering that isolates ground-roll noise.

By default, the applied filter has zero phase. To use a minimum-phase filter, use phase=y. This is the option used in the Madagascar test example from rsf/rsf/test

An alternative way to implement bandpass filtering is using the Fourier transform and tapering functions in the Fourier domain. One example of this approach is provided by sferf.

10 previous programs of the month

madagascar-1.4 released

October 29, 2012 Celebration No comments

The 1.4 stable release features 5 new reproducible papers and multiple other enhancements. The main new feature is the addition of the IWAVE modeling package from Bill Symes and The Rice Inversion Project.

According to the SourceForge statistics, the previous 1.3 stable distribution (released six months ago) has been downloaded more than 2,000 times. The total number of Madagascar downloads has reached 20,000. According to Ohloh.net, the year before 1.4 release was the period of record development activity, with 27 contributors (up 35% compared to the previous year) making 1,500 commits to the repository (up 70%). Ohloh.net says that Madagascar “has a well established, mature codebase maintained by a large development team with increasing year-over-year commits” and estimated 125 man-years of effort.

Helical Fourier transform

October 28, 2012 Documentation No comments

Another old paper is added to the collection of reproducible documents:
Multi-dimensional Fourier transforms in the helical coordinate system

Layer-stripping Kirchhoff migration

October 21, 2012 Documentation No comments

Another old paper is added to the collection of reproducible documents:
Imaging complex structures with first-arrival traveltimes

How do I convert a reproducible paper from LaTeX to HTML?

October 21, 2012 FAQ No comments

Follow the following steps:

  1. Install SEGTeX.
  2. Install LaTeX2HTML.
  3. Set LATEX2HTML environmental variable to $TEXMF/latex2html where $TEXMF is the place of your SEGTeX installation.
  4. In the reproducible paper directory, run 
    sftour scons lock

    to install reproducible figures. Then run 

    scons html

    or 

    scons papername.html

    (if the file name is papername.tex rather than paper.tex) to convert the paper to HTML.

  5. In the reproducible paper directory, run 
    scons install

    or 

    scons papername.install

    (if the file name is papername.tex rather than paper.tex) to install the HTML paper under $RSFROOT/share/madagascar/book

  6. On the book level, you can convert a full report or book to HTML by running 
    scons www

See more instructions on assembling reports from papers.

Program of the month: sfkirmod

October 3, 2012 Programs No comments

sfkirmod is a program for modeling seismic reflection data using the Kirchhoff method. According to this method, the reflection response is computed by integrating over the reflector surface. For a theoretical derivation, see, for example,

Haddon, R. A. W., and P. W. Buchen, 1981, Use of Kirchhoff’s formula for body wave calculations in the earth: Geophys. J. Roy. Astr. Soc., 67, 587-598.

At the moment, sfkirmod can handle only asymptotic Green’s functions, analytically computed in three kinds of velocity models:

  1. Constant velocity
  2. Constant gradient of velocity
  3. Constant gradient of velocity squared

The type is specified with type= parameter, and the velocity model is specified with vel=, refx=, refz=, gradx=, and gradz=.

The following example from rsf/scons/rsf shows shot gathers modeled by sfkirmod in a medium with horizontal reflectors and a constant vertical gradient of velocity

It is also possible to model a converted (PS or SP) wave by supplying vel2=, gradx2=, and gradz2= to specify the converted velocity. The standard input file for sfkirmod contains the shape of one or more reflectors. Several other input files can be optionally provided: dip= specifies the slope of the reflector(s), refl= specifies normal-incidence reflectivity (AVA intercept), rgrad= specifies AVA gradient.

The sampling of the time axis in the output is controlled by nt=, t0=, and dt= parameters. A Ricker wavelet is used with the peak frequency specified by freq=. Factors such as the geometrical spreading and the obliquity factor are taken into account. The geometrical spreading correction is different for 2-D (cylindrical waves) or 2.5-D (spherical waves). The default behavior is 2.5_D. To switch to 2-D, use twod=y. By default, sfkirmod outputs shot gathers.

It is also possible to compute CMP gathers directly by using cmp=y. The following example from jsg/crs/dome2 shows CMP gathers computed over a hyperbolic-shape reflector.

Since Kirchhoff modeling is fundamentally a linear operation, it is easy to run sfkirmod in a data-parallel fashion, for example by using pscons with split=[1,n1] and reduce=’add’.

The 3-D version of sfkirmod is sfkirmod3.

10 previous programs of the month