Difference between revisions of "Manual"

From Madagascar
Jump to navigation Jump to search
Line 7: Line 7:
=About Madagascar=
=About Madagascar=
==What is Madagascar?==
==Package overview==
Madagascar description and features from the [[Main Page|main page]] of the wiki. Sections 1 and 2 (What is in Madagascar; Copyright) from [[Introduction to madagascar]].
[[Main Page|main page]] of the wiki, and the [[Package overview]].
==For people who do not read manuals==
==For people who do not read manuals==

Revision as of 03:32, 9 January 2009

Fotolia 8418493 XS.jpg

As the number of pages on the Wiki grows, the navbar starts becoming insufficient for proper organization of all documentation. A top-down view of all materials about Madagascar is also useful for determining whether gaps in coverage exist. This page will stay in the Sandbox for a long while -- until all gaps have been filled.

Ideally the manual will only consist of either links to wiki pages, or own content. "Forking", i.e. creating a modified copy of a page especially for the manual, invariably ends up with one version getting out of synch.

How nice would it be, and what publicity would bring, calling this manual "Reproducible data analysis with Madagascar" and getting it on SEG Bookmart's shelf :-)

About Madagascar

Package overview

main page of the wiki, and the Package overview.

For people who do not read manuals

Point them to Download, Short Install Guide, and the SEPlib Tour Revisited.

Why use Madagascar?

An articulate description of the reasons on the Why Madagascar page. Have some spectacular pictures obtained with algorithms that are not present in other packages. Describe algorithms/tools unavailable in other open-source geophysical data analysis packages.


A description of the current Madagascar community, with the map of downloads and an estimate of the number of installs, who are the biggest users, outstanding research results obtained with Madagascar, etc. Links to the blog, user mailing list, developer mailing list. Also mention the bug tracker and feature request tracker, encouraging the community to use them more. Mention forums as an alternative for those who want to ask questions or conduct discussions without subscribing to a mailing list.


A history of Madagascar, with the SEPlib/SU part of the "Alternatives" section of the Introduction, and mentions of landmark events (short descriptions where necessary):

More details can be found on the Conferences page.

Downloading and installing Madagascar




  1. Short installation guide
  2. Advanced installation guide

Using Madagascar

The lightning-quick tour

The revisited SEP Tour

The Madagascar file formats

The Regularly Sampled Format (RSF)

The current Guide to RSF file format

Handling irregularly sampled data

Explain the principle of the current method (sfheadermath/sfheaderwindow used on the trace header block output by su/segyread)

Calling existing Madagascar programs

Finding out what program you need

  1. sfdoc -k
  2. Task-centric program list and all its subordinate nodes
  3. Collection of 1-2 page reproducible papers -- "How to do raytracing in Madagascar"; "How to do modeling in Madagascar"; etc
  4. SU to m8r dictionary
  5. SEPlib to m8r dictionary
  6. Other such dictionaries, for free or proprietary seismic processing packages. Such dictionaries are also useful because they will highlight algorithms/utilities present in such packages but missing from m8r.

This chapter is now just a sketch, should get quite big. Users approach tools in a task-centric fashion, i.e. Q1:"how do I do X with Madagascar?", A1:"With feature Y"; Q2: "How do I use feature Y to this end?" M8r is very good at answering Q2, but people ask Q1 first. Many of the reproducible papers included so far contain cutting-edge research. Users learning how to use Madagascar need to start with something much more simple, where they do not have to focus on understanding research on top of understanding software.

Learning how to use a given program

  1. Command-line self-doc
  2. Local html self-doc ($RSFROOT/doc/index.html). Contains all programs installed on the user's machine and only those programs.
  3. Online self-doc
  4. The wiki Guide to Programs.
  5. The ultimate guide are the repro papers; pointer to relevant section of the manual ("Exploring reproducible papers")

What is reproducibility

The whole Reproducibility page, combined with Section 1 from Reproducible computational experiments using SCons

Exploring existing reproducible papers

Papers and books included in the Madagascar distribution

Reproducible Documents and more.

How to reproduce specific figures in existing papers

A frequently encountered case is when a researcher wants to reproduce only one or several figures from an entire paper, but not the entire paper. This can happen because on that system LaTeX dependencies of Madagascar are missing or not working properly, or simply because the researcher is interested only in that result.

  1. Finding the paper directory: If the interesting article has been found by browsing/hyperlink to Reproducible Documents, then the reproducibility package corresponding to
    can be found in
  2. Finding result names: Use the html version of the paper, or grep in all .tex files in the directory for a text string that occurs in the figure legend. Multiple-panel figures may have individual names for each panel. [Note: In pdf versions obtained with scons pdf in paper directory, neither the book name nor paper directory name nor figure names are given. LaTeX options to have figure names as well as a Geophysics-style header/footer with more details on the first page may be in order]
  3. Finding where to launch the re-build: In some cases, rules for creating a result are specified in SConstruct files in subdirectories of the main paper directory. If step 4 fails in the main paper directory, then you will have to find where the figure is built. Because result names may be generated automatically, a simple grep may not be enough and you may need to read the SConstruct and python modules imported by it to figure out if the result is generated there.
  4. Re-build and display the figure by typing scons resultname.view in the appropriate directory.

How to reproduce entire papers

  1. See the previous section for how to find the paper directory
  2. The relevant SCons commands to reproduce the paper (scons pdf and scons read). Troubleshooting:
    • If it fails with this kind of messages (details here), you miss TeX system dependencies. Install a TeX system. Tex Live should have it all. Note: It's a 1 Gb download. Too large for many individual users to bother with it and for most IT departments of companies to review for security. We should implement individual dependency checking, like we do in the installation. Otherwise it is equivalent to telling the user that in order to install Madagascar, he should install Debian with all 30000 packages in the repository... the dependencies will be among them.
    • If scons pdf in the paper directory pdf figures already in place in order to work, run sftour scons lock.
    • Tell the user to expect conditional reproducibility: If Matlab is not present, rsftex will not try to build the figures but will use the stored PDF files (same goes for Mathematica, xfig, etc.)

How to reproduce whole books

The 2006-12-22 rsf-user thread, the 2007-04-08 blog entry and more.

Writing a LaTeX paper in the Madagascar framework

Follows the natural progression of learning of somebody who may even not know LaTeX, let alone SCons.

  1. A paper with no figures.
  2. A paper with NR-only figures

Creating a reproducible paper

Sections 2 3 from Reproducible computational experiments using SCons. Also, mention the "SCons macros" in book/packages.

Creating a reproducible book

Developing in Madagascar

Writing your own programs

The Madagascar API

  1. The existing data clipping API demo
  2. A more complex finite differences API demo – add Python, F77 and Matlab APIs to it

Parallelizing Madagascar programs

Content on the Parallel Computing page and from the 2007-12-27 blog post

How to add your program

The relevant section in "Adding programs"

How to document your program

The relevant section in "Adding programs"

Style guide

The relevant section in "Adding programs"

How to test your program

The relevant section in "Adding programs"

Tips and tricks

The relevant section in "Adding programs"

Madagascar library reference

Library Reference

Madagascar framework development

Description of m8r's inner works for those who want to help improve and maintain Madagascar. This section does not have a structure yet, and is so far just a place for gathering content.


This source code file provides a machine-independent interface between C procedures, Fortran procedures and global data (more details 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 two places. Version 4.3 (2002) is still distributed through the website of the original author. Another version (fork?) is maintained at CERN and distributed in the include directory of the interface to event generators in the Monte Carlo libraries in the CERN Program Library (CERNlib). Debian distributes the Free Software part of this package as cernlib. Under Fedora, cfortran.h is included in cernlib-g77-devel and cernlib-devel, which happily overwrite each other's files and create copies of cfortran.h in two different locations deeply nested under /usr/include. CERNlib's Debian maintainer states that "CERNlib is an ancient mass of mostly Fortran code" and that "Most components of CERNLIB are completely broken on modern 64-bit architectures", so m8r developers should be aware that CERNlib will probably be superseded at some point in the future by ROOT, with upstream cfortran.h maintenance possibly continuing this way.

Automated code checks

Madagascar contains the beginning of an implementation of static code checks for security vulnerabilities and coding mistakes with Splint. This is visible in the code through the presence of comments like /*@out@*/ and /*@null@*/, which instruct Splint about the intent of different variables and function return values. Future plans include using also dynamic checking by Valgrind or IBM's Rational Purify.

Datasets distributed with Madagascar

  • Description of datasets – pictures of the velocity model, of sample gathers, zero-offset sections, migrated image.
  • Comment on which are the main problems they illustrate (internal multiples? overturning waves? etc). Algorithm used for generating them, references to published literature describing the datasets
  • Command line options for correctly reading them from the storage format (SEG-Y, most probably) into RSF
  • In general, expand the datasets section of Reproducible Documents page to include other datasets

Other open-source data analysis packages

Geophysical software

Other open-source geophysical packages. Briefly discuss each of them. Mention "dictionaries" from them to m8r where available (should attempt to have dictionaries for all of them)

Other tools

Mention other open-source codes that are commonly used by geophysicists: