Month: December 2012

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