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 research and processing with Madagascar" and getting it on SEG Bookmart's shelf :-)
- 1 About Madagascar
- 2 Downloading and installing Madagascar
- 3 Using Madagascar
- 3.1 The lightning-quick tour
- 3.2 Calling existing Madagascar programs
- 3.3 What is reproducibility
- 3.4 Exploring existing reproducible papers
- 3.5 Writing a LaTeX paper in the Madagascar framework
- 3.6 Creating a reproducible paper
- 3.7 Creating a reproducible book
- 4 Developing in Madagascar
- 4.1 Writing your own programs
- 4.2 Madagascar framework development
What is Madagascar?
Sections 1-3 (what is M..., what is in M..., Copyright) from Introduction. Section 1 has been already been forked by the main page of the wiki. We should determine which of the two has precedence (probably the main page) and overwrite the other.
For people who do not read manuals
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.
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, mailing lists, forums.
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):
- when and where it was started
- 2004-08 (?): made available to selected alpha users
- 2005-02-16: RSF Blog started
- 2006-03-17: Registered on Sourceforge
- 2006-04-19: Name change from RSF to Madagascar
- 2006-06-11: Public launch at the Open Source E&P Software EAGE Workshop (Vienna)
- 2006-06-18: First stable version (0.9.1)
- 2006-07-23: Madagascar logo
- 2006-08-30/31: RSF School and Workshop (Vancouver) [How many participants, from how many universities and how many companies]
- 2007-04-20: RSF School (Austin)
More details can be found on the Conferences page.
Other free seismic processing and interpretation packages
Briefly mention SEPlib and SU, saying that they were covered in the History section. Follow with Free USP and the rest of the "Alternatives" section of the Introduction.
Downloading and installing Madagascar
The lightning-quick tour
Calling existing Madagascar programs
RSF, the Madagascar file format
The existing Guide to RSF file format
Finding out what program you need
- sfdoc -k
- Task-centric program list
- Collection of 1-2 page reproducible papers -- "How to do raytracing in Madagascar"; "How to do modeling in Madagascar"; etc
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?" Madagascar 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
- Local html self-doc ($RSFROOT/doc/index.html). Contains only and all programs installed on the user's machine.
- Online self-doc
- The wiki Guide to Programs.
- 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 results in existing papers
- If the interesting article has been found by browsing/hyperlink to Reproducible Documents, then the reproducibility package corresponding to
http://www.reproducibility.org/RSF/book/<bookname>/<papername>/paper_html/can be found in
RSFSRC/book/<bookname>/<papername>/Figure names are given in the html version too. [Note: In pdf versions obtained with scons pdf in paper directory, neither the book name nor paper directory name nor figure names are given. Figure names as well as a Geophysics-style header/footer with more details on the first page may be in order]
- 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
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.
- A paper with no figures.
- 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
How to add your program
How to document your program
How to test your program
Tips and tricks
Madagascar library reference
Madagascar framework development
Description of Madagascar's inner works for those who want to help improve and maintain Madagascar.
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.