A new paper is added to the collection of reproducible documents:
Kirchhoff migration using eikonal-based computation of traveltime source-derivatives

A new paper is added to the collection of reproducible documents:
Solving 3D anisotropic elastic wave equations on parallel GPU devices
This is the first contribution from the University of Western Australia.

A new paper is added to the collection of reproducible documents:
Automatic traveltime picking using the instantaneous traveltime

Another old paper is added to the collection of reproducible documents:
Wavefront construction using waverays

A new paper is added to the collection of reproducible documents:
Lowrank finite-differences and lowrank Fourier finite-differences for seismic wave extrapolation in the acoustic approximation

A new paper is added to the collection of reproducible documents:
Wavefield extrapolation in pseudodepth domain

Lack of information in self-documentation of Madagascar programs is one of the most common user complaints. In her recent presentation at the Scientific Software Days, Aleksandra Pawlik from Open University described how the NumPy project has managed to dramatically improve self-documentation of its modules by enabling and encouraging users to participate in editing. We can easily attempt to do something similar.

As the first step, the following wiki pages contain the current self-documents of programs in $RSFSRC/system:

• Documentation:system/main
• Documentation:system/generic
• Documentation:system/seismic

Users are encouraged to edit these documents directly to improve the current descriptions of different programs and to make them more complete and/or easier to understand. To edit wiki pages, follow the Mediawiki Guide.

It’s very easy to edit the contents of a wiki. It only takes a few clicks.

1. Click the “Edit” page tab at the top of the page.
2. Make changes to the text.
3. Click the “Save page” button.

Simple as that!

After review by Madagascar developers, the changes will be incorporated in the source code.

A new paper is added to the collection of reproducible documents:
Accelerated plane-wave destruction

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

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