Madagascar - User contributions [en]

HoustonWW 2018 i

2019-06-03T21:37:14Z

Karl:

==This is the invitation invitation to the 2018 working workshop. The workshop report is at [[HoustonWW2018]] ==
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location==
We will meet in room #219 Farish Hall at the University of Houston. Below are area and campus maps.

[[File:Uhlocation.png | 500px ]]
[[File:Uhfarishhall.png | 500px ]]

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

Advanced Installation

2018-12-14T21:55:15Z

Karl: /* Mac OS X */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
# Install python with libraries including jupyter and ipython. I recommend the Anaconda distribution. which is available at https://www.anaconda.com/download
# (Optionally) SWIG is required for some of the options of the Python api (used if you are coding in Python). run <pre>conda install swig</pre> . I had to run<pre>cp `which swig` /usr/local/bin</pre> to get ./configure to find swig.
#Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory <pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=python --prefix=`pwd`</pre>
#build the system with: <pre>make install</pre>
#After installing a new version of python you must run:
<pre>
./configure
make install
</pre>

In summer of 2018 on a new MacBook Pro running Mac OS 10.14.1 (Mojave) I encountered an "abort trap: 6" error message when running sfpen from command line. I do not
have a problem running sfpen inside scons. I changed to use xtpen from the command line. I continue to use this work around.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2018-12-14T21:53:44Z

Karl: /* Mac OS X */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
# Install python with libraries including jupyter and ipython. I recommend the Anaconda distribution. which is available at https://www.anaconda.com/download
# (Optionally) SWIG is required for some of the options of the Python api (used if you are coding in Python). run <pre>conda install swig</pre> . I had to run<pre>cp `which siwg` /usr/local/bin</pre> to get ./configure to find swig.
#Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory <pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=python --prefix=`pwd`</pre>
#build the system with: <pre>make install</pre>
#After installing a new version of python you must run:
<pre>
./configure
make install
</pre>

In summer of 2018 on a new MacBook Pro running Mac OS 10.14.1 (Mojave) I encountered an "abort trap: 6" error message when running sfpen from command line. I do not
have a problem running sfpen inside scons. I changed to use xtpen from the command line. I continue to use this work around.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2018-12-14T21:44:20Z

Karl: /* Mac OS X */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
# Install python with libraries including jupyter and ipython. I recommend the Anaconda distribution. which is available at https://www.anaconda.com/download
# (Optionally) SWIG is required for some of the options of the Python api (used if you are coding in Python). run <pre>conda install swig</pre> . I had to run<pre>cp `which siwg` /usr/local/bin</pre> to get ./configure to find swig.
#Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory <pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=python --prefix=`pwd`</pre>
#build the system with: <pre>make install</pre>
#After installing a new version of python you must run:
<pre>
./configure
make install
</pre>

In summer of 2018 on a new MacBook Pro running Mac OS 10.14.1 (Mojave) I encountered en abort trap: 6 error message when running sfpen from command line. I do not
have a problem running sfpen inside scons. I changed to use xtpen from the command line. I continue to use this work around.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2018-12-14T21:43:45Z

Karl: /* Mac OS X */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
# Install python with libraries including jupyter and ipython. I recommend the Anaconda distribution. which is available at https://www.anaconda.com/download
# (Optionally) SWIG is required for some of the options of the Python api (used if you are coding in Python). run <pre>conda install swig</pre> . I had to run<pre>cp `which siwg` /usr/local/bin</pre> to get ./configure to find swig.
#Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory <pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=python --prefix=`pwd`</pre>
#build the system with: <pre>make install</pre>
#After installing a new version of python you must run:
<pre>
./configure
make install
</pre>

In summer of 2018 on a new MacBook Pro running Mac OS 10.14.1 (Mojave) I encountered en abort trap: 6 error message when running sfpen from command line. I do not
have a problem running sfpen inside scons. I changed to use xtpen from the command line. I continue to use this work around.

command line.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Guide to madagascar API

2018-12-14T21:33:12Z

Karl: /* Python interface */

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<syntaxhighlight lang="c">
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

The include preprocessing directive is required to access the RSF interface.
<syntaxhighlight lang="c">
sf_file in=NULL, out=NULL; /* Input and output files */
</syntaxhighlight>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<syntaxhighlight lang="c">
/* Initialize RSF */
sf_init(argc,argv);
</syntaxhighlight>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<syntaxhighlight lang="c">
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</syntaxhighlight>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<syntaxhighlight lang="c">
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="c">
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<syntaxhighlight lang="c">
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="c">
/* allocate floating point array */
trace = sf_floatalloc (n1);
</syntaxhighlight>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<syntaxhighlight lang="c">
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</syntaxhighlight>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="cpp">
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</syntaxhighlight>

Let us examine it line by line.
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<syntaxhighlight lang="cpp">
sf_init(argc,argv); // Initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<syntaxhighlight lang="cpp">
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</syntaxhighlight>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<syntaxhighlight lang="cpp">
in.get("n1",n1);
n2=in.size(1);
</syntaxhighlight>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<syntaxhighlight lang="cpp">
par.get("clip",clip); // parameter from the command line
</syntaxhighlight>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<syntaxhighlight lang="cpp">
std::valarray<float> trace(n1);
</syntaxhighlight>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<syntaxhighlight lang="cpp">
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</syntaxhighlight>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
call sf_init()
</syntaxhighlight>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<syntaxhighlight lang="fortran">
in = sf_input("in")
out = sf_output("out")
</syntaxhighlight>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<syntaxhighlight lang="fortran">
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="fortran">
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="fortran">
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do

deallocate (trace)

end program Clipit
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
use rsf
</syntaxhighlight>

The program starts with importing the <tt>rsf</tt> module.
<syntaxhighlight lang="fortran">
call sf_init() ! initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<syntaxhighlight lang="fortran">
in = rsf_input()
out = rsf_output()
</syntaxhighlight>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<syntaxhighlight lang="fortran">
if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
n2 = filesize(in,1)
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<syntaxhighlight lang="fortran">
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==
Examples that use the python interface are in the directory $RSFSRC/api/python/test.

The Python script clip.py is:.

<syntaxhighlight lang="python">
#!/usr/bin/env python

import numpy
import m8r

par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type

n1 = inp.int("n1")
n2 = inp.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="python">
import numpy
import m8r
</syntaxhighlight>

The script starts with importing the <tt>numpy</tt> module and the
<tt>m8r</tt> API.
<syntaxhighlight lang="python">
par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type
</syntaxhighlight>

Next, we initialize the command line interface and the standard input and
output files. We also make sure that the input file type is floating point.
<syntaxhighlight lang="python">
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</syntaxhighlight>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<syntaxhighlight lang="python">
clip = par.float("clip")
assert clip
</syntaxhighlight>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<syntaxhighlight lang="python">
trace = numpy.zeros(n1,'f')
for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</syntaxhighlight>

Finally, we do the actual work: allocate an array to hold a trace and loop
over input traces, reading, clipping, and writing out each trace.

Alternative code use inp.trace to allocate an array and read
the whole file into memory. The loop is no longer needed:
<syntaxhighlight lang="python">
alltraces=inp.read()
alltraces = numpy.clip(alltraces,-clip,clip)
output.write(alltraces)
</syntaxhighlight>

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Using the Python API for interactive development in Jupyter notebooks===
Jupyter notebooks are a good way to prototype python code, explore data, and to
integrate rich text to describe your code. There are four example notebooks in
$RSFSRC/api/python/test that demonstrate how to use Jupyter notebooks. These are:
{|class="wikitable"
|-
| clip.ipynb || clip.py converted to a Jupyter notebook
|-
|simple_m8r_create_write_filter_read.ipynb || numpy, write rsf, Madagascar commands, read rsf, plot
|-
| tle_edge_preserve.ipynb || reproduces a paper from TLE with numpy and Matplotlib
|-
| file_filter_scons_example.ipynb || advanced m8r options; File, filter, and scons from python
|}
They can be started form the command line with the commands:
<pre>
cd $RSFSRC/api/python/test
jupyter notebook clip.ipynb
</pre>

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=9 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<syntaxhighlight lang="python">
import numpy, m8r

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data =inp.read(shape=(n2,n1))
data = data.transpose() # Example of numpy in action

print data
</syntaxhighlight>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<syntaxhighlight lang="python">
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</syntaxhighlight>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<syntaxhighlight lang="python">
show()
</syntaxhighlight>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<syntaxhighlight lang="python">
savefig('myfile.png')
</syntaxhighlight>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<syntaxhighlight lang="python">
#!/usr/bin/env python
import m8r, numpy, sys, pylab

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data=input.read()

pylab.imshow(data)
pylab.savefig('out.png')
</syntaxhighlight>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Guide to madagascar API

2018-12-14T17:18:56Z

Karl: /* Python interface */

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<syntaxhighlight lang="c">
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

The include preprocessing directive is required to access the RSF interface.
<syntaxhighlight lang="c">
sf_file in=NULL, out=NULL; /* Input and output files */
</syntaxhighlight>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<syntaxhighlight lang="c">
/* Initialize RSF */
sf_init(argc,argv);
</syntaxhighlight>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<syntaxhighlight lang="c">
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</syntaxhighlight>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<syntaxhighlight lang="c">
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="c">
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<syntaxhighlight lang="c">
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="c">
/* allocate floating point array */
trace = sf_floatalloc (n1);
</syntaxhighlight>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<syntaxhighlight lang="c">
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</syntaxhighlight>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="cpp">
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</syntaxhighlight>

Let us examine it line by line.
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<syntaxhighlight lang="cpp">
sf_init(argc,argv); // Initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<syntaxhighlight lang="cpp">
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</syntaxhighlight>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<syntaxhighlight lang="cpp">
in.get("n1",n1);
n2=in.size(1);
</syntaxhighlight>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<syntaxhighlight lang="cpp">
par.get("clip",clip); // parameter from the command line
</syntaxhighlight>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<syntaxhighlight lang="cpp">
std::valarray<float> trace(n1);
</syntaxhighlight>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<syntaxhighlight lang="cpp">
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</syntaxhighlight>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
call sf_init()
</syntaxhighlight>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<syntaxhighlight lang="fortran">
in = sf_input("in")
out = sf_output("out")
</syntaxhighlight>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<syntaxhighlight lang="fortran">
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="fortran">
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="fortran">
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do

deallocate (trace)

end program Clipit
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
use rsf
</syntaxhighlight>

The program starts with importing the <tt>rsf</tt> module.
<syntaxhighlight lang="fortran">
call sf_init() ! initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<syntaxhighlight lang="fortran">
in = rsf_input()
out = rsf_output()
</syntaxhighlight>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<syntaxhighlight lang="fortran">
if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
n2 = filesize(in,1)
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<syntaxhighlight lang="fortran">
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==
Examples that use the python interface are in the directory $RSFSRC/api/python/test.

The Python script clip.py is:.

<syntaxhighlight lang="python">
#!/usr/bin/env python

import numpy
import m8r

par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type

n1 = inp.int("n1")
n2 = inp.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="python">
import numpy
import m8r
</syntaxhighlight>

The script starts with importing the <tt>numpy</tt> module and the
<tt>m8r</tt> API.
<syntaxhighlight lang="python">
par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type
</syntaxhighlight>

Next, we initialize the command line interface and the standard input and
output files. We also make sure that the input file type is floating point.
<syntaxhighlight lang="python">
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</syntaxhighlight>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<syntaxhighlight lang="python">
clip = par.float("clip")
assert clip
</syntaxhighlight>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<syntaxhighlight lang="python">
trace = numpy.zeros(n1,'f')
for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</syntaxhighlight>

Finally, we do the actual work: allocate an array to hold a trace and loop
over input traces, reading, clipping, and writing out each trace.

Alternative code use inp.trace to allocate an array and read
the whole file into memory. The loop is no longer needed:
<syntaxhighlight lang="python">
alltraces=inp.read()
alltraces = numpy.clip(alltraces,-clip,clip)
output.write(alltraces)
</syntaxhighlight>

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Using the Python API for interactive development in Jupyter notebooks===
Jupyter notebooks are a good way to prototype python code, explore data, and to
integrate rich text to describe your code. There are four example notebooks in
$RSFSRC/api/python/test that demonstrate how to use Jupyter notebooks. These are:
{|class="wikitable"
|-
| clip.ipynb || clip.py converted to a Jupyter notebook
|-
|simple_m8r_create_write_filter_read.ipynb || numpy, write rsf, Madagascar commands, read rsf, plot
|-
| synthetic_for_tle_Edge-preserving.ipynb || reproduces a paper from TLE with numpy and Matplotlib
|-
| file_filter_scons_example.ipynb || advanced m8r options; File, filter, and scons from python
|}
They can be started form the command line with the commands:
<pre>
cd $RSFSRC/api/python/test
jupyter notebook clip.ipynb
</pre>

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=9 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<syntaxhighlight lang="python">
import numpy, m8r

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data =inp.read(shape=(n2,n1))
data = data.transpose() # Example of numpy in action

print data
</syntaxhighlight>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<syntaxhighlight lang="python">
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</syntaxhighlight>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<syntaxhighlight lang="python">
show()
</syntaxhighlight>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<syntaxhighlight lang="python">
savefig('myfile.png')
</syntaxhighlight>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<syntaxhighlight lang="python">
#!/usr/bin/env python
import m8r, numpy, sys, pylab

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data=input.read()

pylab.imshow(data)
pylab.savefig('out.png')
</syntaxhighlight>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Advanced Installation

2018-12-14T14:53:24Z

Karl: /* Mac OS X */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
# Install python with libraries including jupyter and ipython. I recommend the Anaconda distribution. which is available at https://www.anaconda.com/download
# (Optionally) SWIG is required for some of the options of the Python api (used if you are coding in Python). run <pre>conda install swig</pre> . I had to run<pre>cp `which siwg` /usr/local/bin</pre> to get ./configure to find swig.
#Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory <pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=python --prefix=`pwd`</pre>
#build the system with: <pre>make install</pre>
#After installing a new version of python you must run:
<pre>
./configure
make install
</pre>

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Advanced Installation

2018-12-13T23:05:23Z

Karl: /* Mac OS X */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
# Install python with libraries including jupyter and ipython. I recommend the Anaconda distribution. which is available at https://www.anaconda.com/download
# (Optionally) SWIG is required for some of the options of the Python api (used if you are coding in Python). run <pre>conda install swig</pre> . I had to run<pre>cp `which siwg` /usr/local/bin</pre> to get ./configure to find swig.
#Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory <pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=python --prefix=`pwd`</pre>
#build the system with: <pre>make install</pre>
#You must run: <pre>./configure </pre> and <pre>make install</pre> after installing a new version of python.

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Guide to madagascar API

2018-12-13T21:08:32Z

Karl: /* Python interface */

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<syntaxhighlight lang="c">
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

The include preprocessing directive is required to access the RSF interface.
<syntaxhighlight lang="c">
sf_file in=NULL, out=NULL; /* Input and output files */
</syntaxhighlight>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<syntaxhighlight lang="c">
/* Initialize RSF */
sf_init(argc,argv);
</syntaxhighlight>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<syntaxhighlight lang="c">
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</syntaxhighlight>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<syntaxhighlight lang="c">
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="c">
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<syntaxhighlight lang="c">
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="c">
/* allocate floating point array */
trace = sf_floatalloc (n1);
</syntaxhighlight>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<syntaxhighlight lang="c">
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</syntaxhighlight>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="cpp">
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</syntaxhighlight>

Let us examine it line by line.
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<syntaxhighlight lang="cpp">
sf_init(argc,argv); // Initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<syntaxhighlight lang="cpp">
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</syntaxhighlight>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<syntaxhighlight lang="cpp">
in.get("n1",n1);
n2=in.size(1);
</syntaxhighlight>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<syntaxhighlight lang="cpp">
par.get("clip",clip); // parameter from the command line
</syntaxhighlight>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<syntaxhighlight lang="cpp">
std::valarray<float> trace(n1);
</syntaxhighlight>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<syntaxhighlight lang="cpp">
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</syntaxhighlight>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
call sf_init()
</syntaxhighlight>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<syntaxhighlight lang="fortran">
in = sf_input("in")
out = sf_output("out")
</syntaxhighlight>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<syntaxhighlight lang="fortran">
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="fortran">
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="fortran">
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do

deallocate (trace)

end program Clipit
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
use rsf
</syntaxhighlight>

The program starts with importing the <tt>rsf</tt> module.
<syntaxhighlight lang="fortran">
call sf_init() ! initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<syntaxhighlight lang="fortran">
in = rsf_input()
out = rsf_output()
</syntaxhighlight>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<syntaxhighlight lang="fortran">
if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
n2 = filesize(in,1)
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<syntaxhighlight lang="fortran">
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==
Examples that use the python interface are in the directory $RSFSRC/api/python/test.

The Python script clip.py is:.

<syntaxhighlight lang="python">
#!/usr/bin/env python

import numpy
import m8r

par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type

n1 = inp.int("n1")
n2 = inp.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="python">
import numpy
import m8r
</syntaxhighlight>

The script starts with importing the <tt>numpy</tt> module and the
<tt>m8r</tt> API.
<syntaxhighlight lang="python">
par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type
</syntaxhighlight>

Next, we initialize the command line interface and the standard input and
output files. We also make sure that the input file type is floating point.
<syntaxhighlight lang="python">
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</syntaxhighlight>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<syntaxhighlight lang="python">
clip = par.float("clip")
assert clip
</syntaxhighlight>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<syntaxhighlight lang="python">
trace = numpy.zeros(n1,'f')
for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</syntaxhighlight>

Finally, we do the actual work: allocate an array to hold a trace and loop
over input traces, reading, clipping, and writing out each trace.

Alternative code use inp.trace to allocate an array and read
the whole file into memory. The loop is no longer needed:
<syntaxhighlight lang="python">
alltraces=inp.read()
alltraces = numpy.clip(alltraces,-clip,clip)
output.write(alltraces)
</syntaxhighlight>

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=9 output=x1+x2 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<syntaxhighlight lang="python">
import numpy, m8r

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data =inp.read(shape=(n2,n1))
data = data.transpose() # Example of numpy in action

print data
</syntaxhighlight>

You will get

<pre>
[[ 0. 1. 2. 3. 4. 5. 6. 7. 8.]
[ 1. 2. 3. 4. 5. 6. 7. 8. 9.]
[ 2. 3. 4. 5. 6. 7. 8. 9. 10.]
[ 3. 4. 5. 6. 7. 8. 9. 10. 11.]
[ 4. 5. 6. 7. 8. 9. 10. 11. 12.]
[ 5. 6. 7. 8. 9. 10. 11. 12. 13.]
[ 6. 7. 8. 9. 10. 11. 12. 13. 14.]
[ 7. 8. 9. 10. 11. 12. 13. 14. 15.]
[ 8. 9. 10. 11. 12. 13. 14. 15. 16.]
[ 9. 10. 11. 12. 13. 14. 15. 16. 17.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<syntaxhighlight lang="python">
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</syntaxhighlight>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<syntaxhighlight lang="python">
show()
</syntaxhighlight>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<syntaxhighlight lang="python">
savefig('myfile.png')
</syntaxhighlight>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<syntaxhighlight lang="python">
#!/usr/bin/env python
import m8r, numpy, sys, pylab

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data=input.read()

pylab.imshow(data)
pylab.savefig('out.png')
</syntaxhighlight>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Guide to madagascar API

2018-12-13T21:01:26Z

Karl: /* Python interface */

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<syntaxhighlight lang="c">
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

The include preprocessing directive is required to access the RSF interface.
<syntaxhighlight lang="c">
sf_file in=NULL, out=NULL; /* Input and output files */
</syntaxhighlight>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<syntaxhighlight lang="c">
/* Initialize RSF */
sf_init(argc,argv);
</syntaxhighlight>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<syntaxhighlight lang="c">
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</syntaxhighlight>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<syntaxhighlight lang="c">
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="c">
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<syntaxhighlight lang="c">
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="c">
/* allocate floating point array */
trace = sf_floatalloc (n1);
</syntaxhighlight>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<syntaxhighlight lang="c">
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</syntaxhighlight>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="cpp">
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</syntaxhighlight>

Let us examine it line by line.
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<syntaxhighlight lang="cpp">
sf_init(argc,argv); // Initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<syntaxhighlight lang="cpp">
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</syntaxhighlight>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<syntaxhighlight lang="cpp">
in.get("n1",n1);
n2=in.size(1);
</syntaxhighlight>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<syntaxhighlight lang="cpp">
par.get("clip",clip); // parameter from the command line
</syntaxhighlight>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<syntaxhighlight lang="cpp">
std::valarray<float> trace(n1);
</syntaxhighlight>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<syntaxhighlight lang="cpp">
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</syntaxhighlight>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
call sf_init()
</syntaxhighlight>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<syntaxhighlight lang="fortran">
in = sf_input("in")
out = sf_output("out")
</syntaxhighlight>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<syntaxhighlight lang="fortran">
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="fortran">
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="fortran">
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do

deallocate (trace)

end program Clipit
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
use rsf
</syntaxhighlight>

The program starts with importing the <tt>rsf</tt> module.
<syntaxhighlight lang="fortran">
call sf_init() ! initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<syntaxhighlight lang="fortran">
in = rsf_input()
out = rsf_output()
</syntaxhighlight>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<syntaxhighlight lang="fortran">
if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
n2 = filesize(in,1)
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<syntaxhighlight lang="fortran">
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==
Examples that use the python interface are in the directory $RSFSRC/api/python/test.

The Python script clip.py is:.

<syntaxhighlight lang="python">
#!/usr/bin/env python

import numpy
import m8r

par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type

n1 = inp.int("n1")
n2 = inp.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="python">
import numpy
import m8r
</syntaxhighlight>

The script starts with importing the <tt>numpy</tt> module and the
<tt>m8r</tt> API.
<syntaxhighlight lang="python">
par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type
</syntaxhighlight>

Next, we initialize the command line interface and the standard input and
output files. We also make sure that the input file type is floating point.
<syntaxhighlight lang="python">
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</syntaxhighlight>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<syntaxhighlight lang="python">
clip = par.float("clip")
assert clip
</syntaxhighlight>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<syntaxhighlight lang="python">
trace = numpy.zeros(n1,'f')
for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</syntaxhighlight>

Finally, we do the actual work: allocate an array to hold a trace and loop
over input traces, reading, clipping, and writing out each trace.

Alternative code use inp.trace to allocate an array and read
the whole file into memory. The loop is no longer needed:
<syntaxhighlight lang="python">
alltraces=inp.read()
alltraces = numpy.clip(alltraces,-clip,clip)
output.write(alltraces)
</syntaxhighlight>

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=5 output=x1+x2*100 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<syntaxhighlight lang="python">
import numpy, m8r

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data =inp.read(shape=(n2,n1))
data = data.transpose() # Example of numpy in action

print data
</syntaxhighlight>

You will get

<pre>
[[ 0. 100. 200. 300. 400.]
[ 1. 101. 201. 301. 401.]
[ 2. 102. 202. 302. 402.]
[ 3. 103. 203. 303. 403.]
[ 4. 104. 204. 304. 404.]
[ 5. 105. 205. 305. 405.]
[ 6. 106. 206. 306. 406.]
[ 7. 107. 207. 307. 407.]
[ 8. 108. 208. 308. 408.]
[ 9. 109. 209. 309. 409.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<syntaxhighlight lang="python">
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</syntaxhighlight>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<syntaxhighlight lang="python">
show()
</syntaxhighlight>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<syntaxhighlight lang="python">
savefig('myfile.png')
</syntaxhighlight>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<syntaxhighlight lang="python">
#!/usr/bin/env python
import m8r, numpy, sys, pylab

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data=input.read()

pylab.imshow(data)
pylab.savefig('out.png')
</syntaxhighlight>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

Guide to madagascar API

2018-12-13T20:43:32Z

Karl:

<center>''This page was created from the LaTeX source in [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/book/rsf/rsf/api.tex book/rsf/rsf/api.tex] using [[latex2wiki]]''</center>

[[Image:Fotolia_555071_XS.jpg|right|]]

This guide explains the RSF programming interface. See the '''[[Library_Reference | Library Reference]]''' for more information on how to use the particular APIs.

==Introduction==
To work with RSF files in your own programs, you may need to use an
appropriate programming interface. We will demonstrate the interface in
different languages using a simple example. The example is a clipping program.
It reads and writes RSF files and accesses parameters both from the input file
and the command line. The input is processed trace by trace. This is not
necessarily the most efficient approach<ref>Compare with the [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/filt/proc/Mclip.c?view=markup library clip program].</ref> but it suffices for a simple demonstration.

==Installation==
Only the C interface is installed by default. To install other APIs, use <tt>API=</tt>
parameter in the RSF configuration. For example, to install C++ and
Fortran-90 API bindings in addition to the basic package, run
<pre>
./configure API=c++,fortran-90
scons install
</pre>
The configuration parameters are stored in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C interface==

The C clip function is listed below.
<syntaxhighlight lang="c">
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
int n1, n2, i1, i2;
float clip, *trace=NULL;
sf_file in=NULL, out=NULL; /* Input and output files */

/* Initialize RSF */
sf_init(argc,argv);
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");

/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");

/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);

/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

/* allocate floating point array */
trace = sf_floatalloc (n1);

/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}

free(trace);
sf_close();
exit(0);
}
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

The include preprocessing directive is required to access the RSF interface.
<syntaxhighlight lang="c">
sf_file in=NULL, out=NULL; /* Input and output files */
</syntaxhighlight>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S., 1998, Programming abstractions in C: Addison-Wesley.</ref>).
<syntaxhighlight lang="c">
/* Initialize RSF */
sf_init(argc,argv);
</syntaxhighlight>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<syntaxhighlight lang="c">
/* standard input */
in = sf_input("in");
/* standard output */
out = sf_output("out");
</syntaxhighlight>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output.
<syntaxhighlight lang="c">
/* check that the input is float */
if (SF_FLOAT != sf_gettype(in))
sf_error("Need float input");
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="c">
/* n1 is the fastest dimension (trace length) */
if (!sf_histint(in,"n1",&n1))
sf_error("No n1= in input");
/* leftsize gets n2*n3*n4*... (the number of traces) */
n2 = sf_leftsize(in,1);
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<syntaxhighlight lang="c">
/* parameter from the command line (i.e. clip=1.5 ) */
if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="c">
/* allocate floating point array */
trace = sf_floatalloc (n1);
</syntaxhighlight>

Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<syntaxhighlight lang="c">
/* loop over traces */
for (i2=0; i2 < n2; i2++) {

/*read a trace */
sf_floatread(trace,n1,in);

/* loop over samples */
for (i1=0; i1 < n1; i1++) {
if (trace[i1] > clip) trace[i1]= clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

/* write a trace */
sf_floatwrite(trace,n1,out);
}
</syntaxhighlight>

The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered.

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="cpp">
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
sf_init(argc,argv); // Initialize RSF

iRSF par(0), in; // input parameter, file
oRSF out; // output file

int n1, n2; // trace length, number of traces
float clip;

in.get("n1",n1);
n2=in.size(1);

par.get("clip",clip); // parameter from the command line

std::valarray<float> trace(n1);

for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}

exit(0);
}
</syntaxhighlight>

Let us examine it line by line.
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<syntaxhighlight lang="cpp">
sf_init(argc,argv); // Initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<syntaxhighlight lang="cpp">
iRSF par(0), in; // input parameter, file
oRSF out; // output file
</syntaxhighlight>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled
as an <tt>iRSF</tt> object, initialized with zero.
<syntaxhighlight lang="cpp">
in.get("n1",n1);
n2=in.size(1);
</syntaxhighlight>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<syntaxhighlight lang="cpp">
par.get("clip",clip); // parameter from the command line
</syntaxhighlight>

The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<syntaxhighlight lang="cpp">
std::valarray<float> trace(n1);
</syntaxhighlight>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<syntaxhighlight lang="cpp">
for (int i2=0; i2 < n2; i2++) { // loop over traces
in >> trace; // read a trace

for (int i1=0; i1 < n1; i1++) { // loop over samples
if (trace[i1] > clip) trace[i1]=clip;
else if (trace[i1] < -clip) trace[i1]=-clip;
}

out << trace; // write a trace
}
</syntaxhighlight>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
implicit none
integer n1, n2, i1, i2, in, out
integer sf_input, sf_output, sf_leftsize, sf_gettype
logical sf_getfloat, sf_histint
real clip, trace(1000)

call sf_init()
in = sf_input("in")
out = sf_output("out")

if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")

if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)

if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")

do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue

stop
end
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
call sf_init()
</syntaxhighlight>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<syntaxhighlight lang="fortran">
in = sf_input("in")
out = sf_output("out")
</syntaxhighlight>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which may refer to a file name or a file
tag. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in
the standard input and <tt>"out"</tt> refers to the file in the
standard output.
<syntaxhighlight lang="fortran">
if (3 .ne. sf_gettype(in))
& call sf_error("Need float input")
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to floating-point numbers. If not, the program is aborted
with an error message, using the <tt>sf_error</tt> function. It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="fortran">
if (.not. sf_histint(in,"n1",n1)) then
call sf_error("No n1= in input")
else if (n1 > 1000) then
call sf_error("n1 is too long")
end if
n2 = sf_leftsize(in,1)
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the
<tt>sf_leftsize</tt> function. Calling <tt>sf_leftsize(in,0)</tt>
returns the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>sf_leftsize(in,1)</tt>
returns the number of traces (the product of <tt>n2</tt>, <tt>n3</tt>,
etc.), calling <tt>sf_leftsize(in,2)</tt> returns the product of
<tt>n3</tt>, <tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we
avoid the need to extract additional parameters for the hypercube
dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
if (.not. sf_getfloat("clip",clip))
& call sf_error("Need clip=")
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="fortran">
do 10 i2=1, n2
call sf_floatread(trace,n1,in)

do 20 i1=1, n1
if (trace(i1) > clip) then
trace(i1)=clip
else if (trace(i1) < -clip) then
trace(i1)=-clip
end if
20 continue

call sf_floatwrite(trace,n1,out)
10 continue
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagascar/etc/config.py</tt>.

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
use rsf

implicit none
type (file) :: in, out
integer :: n1, n2, i1, i2
real :: clip
real, dimension (:), allocatable :: trace

call sf_init() ! initialize RSF
in = rsf_input()
out = rsf_output()

if (sf_float /= gettype(in)) call sf_error("Need float type")

call from_par(in,"n1",n1)
n2 = filesize(in,1)

call from_par("clip",clip) ! command-line parameter

allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

call rsf_write(out,trace)
end do

deallocate (trace)

end program Clipit
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
use rsf
</syntaxhighlight>

The program starts with importing the <tt>rsf</tt> module.
<syntaxhighlight lang="fortran">
call sf_init() ! initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<syntaxhighlight lang="fortran">
in = rsf_input()
out = rsf_output()
</syntaxhighlight>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<syntaxhighlight lang="fortran">
if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function. Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
n2 = filesize(in,1)
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<syntaxhighlight lang="fortran">
allocate (trace (n1))

do i2=1, n2 ! loop over traces
call rsf_read(in,trace)

where (trace > clip) trace = clip
where (trace < -clip) trace = -clip

</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I$RSFROOT/include -L$RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>$RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].

==Python interface==
Examples that use the python interface are in the directory $RSFSRC/api/python/test.

The Python script clip.py is:.

<syntaxhighlight lang="python">
#!/usr/bin/env python

import numpy
import m8r

par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type

n1 = inp.int("n1")
n2 = inp.size(1)
assert n1

clip = par.float("clip")
assert clip

trace = numpy.zeros(n1,'f')

for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)

</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="python">
import numpy
import m8r
</syntaxhighlight>

The script starts with importing the <tt>numpy</tt> module and the
<tt>m8r</tt> API.
<syntaxhighlight lang="python">
par = m8r.Par()
inp = m8r.Input()
output = m8r.Output()
assert 'float' == inp.type
</syntaxhighlight>

Next, we initialize the command line interface and the standard input and
output files. We also make sure that the input file type is floating point.
<syntaxhighlight lang="python">
n1 = input.int("n1")
n2 = input.size(1)
assert n1
</syntaxhighlight>

We extract the "<tt>n1</tt>" parameter from the input file.
Conceptually, the RSF data model is a multidimensional hypercube. The
<tt>n1</tt> parameter refers to the fastest axis. If the input dataset
is a collection of traces, <tt>n1</tt> corresponds to the trace
length. We could proceed in a similar fashion, extracting <tt>n2</tt>,
<tt>n3</tt>, etc. If we are interested in the total number of traces,
like in the clip example, a shortcut is to use the <tt>size</tt>
method of the <tt>Input</tt> class. Calling <tt>size(0)</tt> returns
the total number of elements in the hypercube (the product of
<tt>n1</tt>, <tt>n2</tt>, etc.), calling <tt>size(1)</tt> returns the
number of traces (the product of <tt>n2</tt>, <tt>n3</tt>, etc.),
calling <tt>size(2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc.
<syntaxhighlight lang="python">
clip = par.float("clip")
assert clip
</syntaxhighlight>

The clip parameter is read from the command line, where it can be specified,
for example, as <tt>clip=10</tt>.
<syntaxhighlight lang="python">
for i2 in xrange(n2): # loop over traces
inp.read(trace)
trace = numpy.clip(trace,-clip,clip)
output.write(trace)
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.

===Compiling===
The python script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>PYTHONPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

===Interactive mode usage without graphics===
Madagascar's Python API can be used interactively too. Create an input dataset with

<pre>
sfmath n1=10 n2=5 output=x1+x2*100 > test.rsf
</pre>

Then, start the python interpreter and paste the following to its command line:

<syntaxhighlight lang="python">
import numpy, m8r

inp = m8r.Input('test.rsf')
n1 = inp.int("n1")
n2 = inp.int("n2")

data =inp.read(shape=(n2,n1))
data = data.transpose() # Example of numpy in action

print data
</syntaxhighlight>

You will get

<pre>
[[ 0. 100. 200. 300. 400.]
[ 1. 101. 201. 301. 401.]
[ 2. 102. 202. 302. 402.]
[ 3. 103. 203. 303. 403.]
[ 4. 104. 204. 304. 404.]
[ 5. 105. 205. 305. 405.]
[ 6. 106. 206. 306. 406.]
[ 7. 107. 207. 307. 407.]
[ 8. 108. 208. 308. 408.]
[ 9. 109. 209. 309. 409.]]
</pre>

This code will also work in batch mode in a Python script, not only pasted to the interpreter's command line.

===Graphics with Matplotlib===
Python can plot arrays directly from memory, without having to write a file to disk first. [http://matplotlib.sourceforge.net/ Matplotlib] is one of the [http://en.wikipedia.org/wiki/Category:Free_plotting_software several] packages that accomplish this. To create a figure, execute the code in the previous section, followed by:

<syntaxhighlight lang="python">
from pylab import *
imshow(data)
xlabel('X (m)')
ylabel('Y (m)')
title('Matplotlib example')
</syntaxhighlight>

If you want to pop up a figure in an interactive session, after pasting to a Python command line the code shown before, also paste:

<syntaxhighlight lang="python">
show()
</syntaxhighlight>

You will get Figure 1. The figure will pop up if you run the code in a script too, and the script will stop until the figure is manually closed. You must press the floppy disk button in order to save it. To have the image written to disk automatically, instead of <tt>show()</tt> use:

<syntaxhighlight lang="python">
savefig('myfile.png')
</syntaxhighlight>

[[Image:matplotlib_imshow.png]]

Putting it all together, here is a sample script reading a RSF file from stdin and printing out a figure:

<syntaxhighlight lang="python">
#!/usr/bin/env python
import rsf.api, numpy, sys, pylab

input = rsf.api.Input('test.rsf')
n1 = input.int("n1")
n2 = input.int("n2")

data = numpy.zeros((n2,n1),'f')
input.read(data)

pylab.imshow(data)
pylab.savefig('out.png')
</syntaxhighlight>
===Python interfaces to the standalone programs===
The <tt>m8r</tt> module offers a way to call Madagascar standalone programs (including graphics) elegantly from inside a Python program, interactively or in batch mode. The blog contains examples of running the <tt>m8r</tt> module [http://www.ahay.org/rsflog/index.php?/archives/173-Extending-Python-interface.html from inside a SAGE notebook] or [http://www.ahay.org/rsflog/index.php?/archives/264-Running-Madagascar-in-an-interactive-console.html from inside an iPython shell].

==MATLAB interface==

The MATLAB clip function is listed below.
<matlab>
function clip(in,out,clip)
%CLIP Clip the data

dims = rsf_dim(in);
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file

for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end

</matlab>

Let us examine it in detail.
<matlab>
dims = rsf_dim(in);
</matlab>

We start by figuring out the input file dimensions.
<matlab>
n1 = dims(1); % trace length
n2 = prod(dims(2:end)); % number of traces
</matlab>

The first dimension is the trace length, the product of all other
dimensions correspond to the number of traces.
<matlab>
trace = 1:n1; % allocate trace
rsf_create(out,in) % create an output file
</matlab>

Next, we allocate the trace array and create an output file.
<matlab>
for i2 = 1:n2 % loop over traces
rsf_read(trace,in,'same');
trace(trace > clip) = clip;
trace(trace < - clip) = -clip;
rsf_write(trace,out,'same');
end
</matlab>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Available functions===
Only some of the functions in the <tt>rsf</tt> library have received a MATLAB interface. These functions are <tt>rsf_par</tt>, <tt>rsf_dim</tt>, <tt>rsf_read</tt>, <tt>rsf_write</tt> and <tt>rsf_create</tt>. All these functions except <tt>rsf_par</tt> have been illustrated in the example above.
===Compiling===
The MATLAB script does not require compilation. Simply make sure that
<tt>$RSFROOT/lib</tt> is in <tt>MATLABPATH</tt> and <tt>LD_LIBRARY_PATH</tt>.

==Java Interface==
There are two interfaces to Java that are available. New codes should be written to use the SWIG interface ONLY. The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1 - Download the Java Standard Development Kit (JDK). Installation varies by platform.

2 - Create the JAVA_HOME environment variable for your shell. This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<bash>
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</bash>
3 - Reconfigure Madagascar:
<bash>
./configure API=java
</bash>
4 - Reinstall Madagascar (Ignore the compilation warnings for Java files):
<bash>
scons; scons install
</bash>

The installation creates two files: $RSFROOT/lib/libjrsf.so and $RSFROOT/lib/rsf.jar .

Make sure that you set your LD_LIBRARY_PATH to include $RSFROOT/lib.

A short demonstration of the interface follows:

<java>
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
static {
System.loadLibrary("jrsf");
}
public static void main(String[] args){
// Initialize command line argument passing
RSF par = new RSF(args);
// Get the input file name.
Input input = new Input("in");
Output output = new Output("out");
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
// Read our input header
int n3 = input.getN(3);
int n2 = input.getN(2);
int n1 = input.getN(1);
//Perform clipping operation on a single trace and write out.
float[] data = new float[n1];
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
input.read(data);
for(int k = 0; k < n1; ++k){
if (data[k] > clip) data[k] = clip;
else if (data[k] < -clip) data[k] = -clip;
}
output.write(data);
}
}
output.setN(1,n1);
output.setN(2,n2);
output.setN(3,n3);
input.close();
output.close();
}
}
</java>

There are only three classes in the interface:

1 -- RSF - The command line argument parser, and the initializer for the native interface. An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2 -- Input - An object that provides read access to an RSF file.

3 -- Output - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<bash>
javac -cp $RSFROOT/lib Clip.java
</bash>

To include this as part of a SCons script (SConstruct):
<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
'''
%s Clip clip=0.5
''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')

</python>

Note, that we compile Clip.java using the SCons Java builder. To execute the command, we have to locate the "java" command, which we do using WhereIs('java'). Then we execute the class name, and pass any command line arguments as usual. The files are read from standard in for this program and written to standard out.

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE. THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable.

The interface to Java is less full featured than others. Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files. '''The Java interface does not support reading from standard in, or writing from standard out. Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers. Java programs are not parsed for self-doc information like other programs are either. Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.

There are two ways to access the API:

1 - From the command line: point the classpath at BOTH compile and runtime to this location on the command line.
<bash>
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</bash>

2 - From within a SConstruct script: BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct. Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath. This allows you to include additional libraries automatically within your Java programs. The local directory (.) is also included in the CLASSPATH.

<python>
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
'''
%s ${SOURCES[0].filebase} clip=0.5
in=${SOURCES[1]} out=$TARGET
''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</python>

The interface itself is fairly straightforward. More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<java>
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc. Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
public static void main(String[] args){
// Initialize command line argument passing
Par par = new Par(args);
// Get the input file name.
String input = par.getString("in","");
// If the input file name is nothing, then quit!
if (input.equals("")){
System.out.println("Did not find input file!");
System.exit(1);
}
//If the output file name is nothing, then quit!
String output = par.getString("out","");
if (output.equals("")){
System.out.println("Did not find output file!");
System.exit(1);
}
// Get the value to clip to.
float clip = par.getFloat("clip",0.0f);
//Read our header file.
Header header = Reader.readHeader(input);
// Read our binary data.
float[][][] data = Reader.readBinary3D(header);
//Initialize our array values.
int n3 = header.getN(3);
int n2 = header.getN(2);
int n1 = header.getN(1);
//Perform clipping operation.
for(int i = 0; i < n3; ++i){
for(int j = 0; j < n2; ++j){
for(int k = 0; k < n1; ++k){
float trace = data[i][j][k];
if (trace > clip) data[i][j][k] = clip;
else if (trace < -clip) data[i][j][k] = -clip;
}
}
}
//Write our data out, using the same header values to the file
//located at: output.
Writer.writeRSF(header,data,output);
}
}

</java>

How to read a file:

<java>

import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
}
}

</java>

How to write a file:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

//...Do something
Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
}
}

</java>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<java>
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
public static void main(String[] args){

int n1 = 20;
int n2 = 40;
float[][] data = new float[n2][n1];
//The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

//...Do something

Header header = new Header();
header.setN(1,n1);
/* We set the values using the proper RSF number for the dimension, instead of the Java array index.
Example: RSF Dimension 1, corresponds to array index 0 in Java.
However, we set the values using index 1. The mapping is handled behind the scenes.
*/
header.setN(2,n2);
header.setDelta(1,0.0);
header.setLabel(1,"time");
header.setUnits(1,"s");
Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
}
}

</java>

==References==
<references/>

HoustonWW2018

2018-10-23T16:30:30Z

Karl: changes introduction section

[[File:Houston-ww2018.jpg|1000px]]

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

In late August, 16 participants from 12 organizations collaborated at the University of Houston to learn how program geophysical applications using Python and Julia. These languages are good for prototyping and applying selected geophysical algorithms. Our goal was to promote more widespread use of these languages.

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem.

This is the sixth year that TCCS has organized working workshops where small groups collaborate to develop software or conduct computational experiments addressing a particular problem. This year participants were students, academic staff, and industry professionals. Projects included machine learning, 3D plotting, parallel processing, wave equation modeling, and well log analysis. For more information visit http://www.ahay.org/wiki/HoustonWW2018.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Summary of all workshop presentations===
Presentation summarizing all the individual presentations is at the link [https://drive.google.com/open?id=1EM1jIy-osfqBmYBWL7pssIZqjcn8jdxf].

===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [https://drive.google.com/open?id=1sRojofwRbNVYtrzqU2e-CaU651xJmPAl]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
Matt also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Rafael Pinto and Thu Nguyen===
Rafael and Thu processed wells from the Poseidon project in the NW Shelf Australia. They used lasio to read the data into a Panda data frame, then loaded the data into an sql database. Lasio processes logs from a single well. The sql database is good to manipulate multiple wells on a project. They visualized cross plots in matplotlib and datashader. Datashader plots were better. Their jupyter notebook can be downloaded from this link [https://drive.google.com/open?id=16Ul7r32VZRbrs7JxMIuv0ip0a0AG3JoV]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===
Carlos provided a new viewer for Madagascar. Sfpgreywfl, written in python, will plot a wavefield with a velocity background. He also wrote a julia version of acoustic finite difference wave equation modeling. This programs are being added to the Madagascar repository. His presentation can be downloaded by the link [https://drive.google.com/open?id=1gwGjVsabRADw4-cQwnOPI_x2GcxapO22]

===Sergey Fomel===
Madagascar already had example of acoustic finite difference wave equation modeling in C, C++, and Fortran90. Sergey Fomel implemented the same algorithm in Python. and benchmarked the program in all the languages These are described in the presentation: [https://drive.google.com/file/d/1w302kWFOLPWJwUqAt1NDdBGJ__73XVX1/view?usp=sharing]. 

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-10-12T16:10:31Z

Karl: /* Synopsis of Results with Links */

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Summary of all workshop presentations===
Presentation summarizing all the individual presentations is at the link [https://drive.google.com/open?id=1EM1jIy-osfqBmYBWL7pssIZqjcn8jdxf].

===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [https://drive.google.com/open?id=1sRojofwRbNVYtrzqU2e-CaU651xJmPAl]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
Matt also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Rafael Pinto and Thu Nguyen===
Rafael and Thu processed wells from the Poseidon project in the NW Shelf Australia. They used lasio to read the data into a Panda data frame, then loaded the data into an sql database. Lasio processes logs from a single well. The sql database is good to manipulate multiple wells on a project. They visualized cross plots in matplotlib and datashader. Datashader plots were better. Their jupyter notebook can be downloaded from this link [https://drive.google.com/open?id=16Ul7r32VZRbrs7JxMIuv0ip0a0AG3JoV]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===
Carlos provided a new viewer for Madagascar. Sfpgreywfl, written in python, will plot a wavefield with a velocity background. He also wrote a julia version of acoustic finite difference wave equation modeling. This programs are being added to the Madagascar repository. His presentation can be downloaded by the link [https://drive.google.com/open?id=1gwGjVsabRADw4-cQwnOPI_x2GcxapO22]

===Sergey Fomel===
Madagascar already had example of acoustic finite difference wave equation modeling in C, C++, and Fortran90. Sergey Fomel implemented the same algorithm in Python. and benchmarked the program in all the languages These are described in the presentation: [https://drive.google.com/file/d/1w302kWFOLPWJwUqAt1NDdBGJ__73XVX1/view?usp=sharing]. 

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-10-12T16:10:12Z

Karl: /* Synopsis of Results with Links */

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Summary of all workshop presentation===
Presentation summarizing all the individual presentations is at the link [https://drive.google.com/open?id=1EM1jIy-osfqBmYBWL7pssIZqjcn8jdxf].

===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [https://drive.google.com/open?id=1sRojofwRbNVYtrzqU2e-CaU651xJmPAl]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
Matt also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Rafael Pinto and Thu Nguyen===
Rafael and Thu processed wells from the Poseidon project in the NW Shelf Australia. They used lasio to read the data into a Panda data frame, then loaded the data into an sql database. Lasio processes logs from a single well. The sql database is good to manipulate multiple wells on a project. They visualized cross plots in matplotlib and datashader. Datashader plots were better. Their jupyter notebook can be downloaded from this link [https://drive.google.com/open?id=16Ul7r32VZRbrs7JxMIuv0ip0a0AG3JoV]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===
Carlos provided a new viewer for Madagascar. Sfpgreywfl, written in python, will plot a wavefield with a velocity background. He also wrote a julia version of acoustic finite difference wave equation modeling. This programs are being added to the Madagascar repository. His presentation can be downloaded by the link [https://drive.google.com/open?id=1gwGjVsabRADw4-cQwnOPI_x2GcxapO22]

===Sergey Fomel===
Madagascar already had example of acoustic finite difference wave equation modeling in C, C++, and Fortran90. Sergey Fomel implemented the same algorithm in Python. and benchmarked the program in all the languages These are described in the presentation: [https://drive.google.com/file/d/1w302kWFOLPWJwUqAt1NDdBGJ__73XVX1/view?usp=sharing]. 

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-10-12T16:09:28Z

Karl: add link to ppt presentation summarizing all the individual presentation

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===powerPoint presentation summarizing the workshop===
Presentation summarizing all the individual presentations is at the link [https://drive.google.com/open?id=1EM1jIy-osfqBmYBWL7pssIZqjcn8jdxf].

===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [https://drive.google.com/open?id=1sRojofwRbNVYtrzqU2e-CaU651xJmPAl]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
Matt also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Rafael Pinto and Thu Nguyen===
Rafael and Thu processed wells from the Poseidon project in the NW Shelf Australia. They used lasio to read the data into a Panda data frame, then loaded the data into an sql database. Lasio processes logs from a single well. The sql database is good to manipulate multiple wells on a project. They visualized cross plots in matplotlib and datashader. Datashader plots were better. Their jupyter notebook can be downloaded from this link [https://drive.google.com/open?id=16Ul7r32VZRbrs7JxMIuv0ip0a0AG3JoV]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===
Carlos provided a new viewer for Madagascar. Sfpgreywfl, written in python, will plot a wavefield with a velocity background. He also wrote a julia version of acoustic finite difference wave equation modeling. This programs are being added to the Madagascar repository. His presentation can be downloaded by the link [https://drive.google.com/open?id=1gwGjVsabRADw4-cQwnOPI_x2GcxapO22]

===Sergey Fomel===
Madagascar already had example of acoustic finite difference wave equation modeling in C, C++, and Fortran90. Sergey Fomel implemented the same algorithm in Python. and benchmarked the program in all the languages These are described in the presentation: [https://drive.google.com/file/d/1w302kWFOLPWJwUqAt1NDdBGJ__73XVX1/view?usp=sharing]. 

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2017

2018-10-11T15:58:07Z

Karl: corrected dates and other minor typos

[[Image:HoustonWW2017.JPG|center|frame|800px]]

==SEG Seismic Working Workshop - Reproducible Tutorials - August 9-13, 2017==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in pairs or small teams to develop new software code or to conduct computational experiments addressing a particular problem. In this workshop participants will work in small groups to create short, reproducible, geophysical tutorials. These tutorials are inspired by The Leading Edge geophysical tutorial [http://wiki.seg.org/wiki/A_user_guide_to_the_geophysical_tutorials articles]. Groups will make lightning talks (a five minute presentation) at then end of the workshop. An open repository will be created to share presentations and code after the workshop.

==Objective==
Groups of two or three participant were formed at the working workshop to create reproducible tutorials. The tutorial should be on a topic of interest to seismic interpreters, applied geophysicists, and general earth scientists. It should be about 1500 words, two or three figures, and code to makes the figures. Groups used any system to create and share the code that allows the tutorial figures to be reproduced by readers after the workshop. The tutorials may be candidates for publication (eg The Leading Edge geophysical tutorial [http://wiki.seg.org/wiki/A_user_guide_to_the_geophysical_tutorials articles] or the software section of Geophysics). groups came up with their own ideas or read [http://wiki.seg.org/wiki/Geophysical_tutorials previous TLE tutorials], Geophysical Image Estimation by Example (http://sepwww.stanford.edu/sep/prof/), Seismic Unix demos, Madagascar reproducible [http://www.reproducibility.org/RSF/book/gee/lmn/paper_html/node6.html documents], or Geophysical Society of Houston “Tutorial Nuggets”. Study, extend, or translate some of this material to another system. Collaborate and share your experience in a lightning talk (a five minute presentation).

Participants used their own laptops and software to create a tutorial during the workshop. Wifi internet access was available.

This working workshop provided a forum for geophysicist to learn, contribute, and network.

Previous tutorials from The Leading Edge can be downloaded with:

git clone https://github.com/seg/tutorials-2014 
git clone https://github.com/seg/tutorials-2015 
git clone https://github.com/seg/tutorials-2016 
git clone https://github.com/seg/tutorials-2017 

==Link to the original workshop invitation is [[HoustonWW 2017 i]]==

==Workshop agenda==
*Wednesday afternoon August 9, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 10, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 11, 2017
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 12, 2017
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**2:00-3:00 Lighting talks

==Synopsis of results with links ==
===Overview Presentation of Results===
Karl Schleicher completed a report of the highlights of the working workshop.
[https://drive.google.com/open?id=1ZdpWMpLyKVXLEf6Ng2rUQ1mN3ZbekmXL view Schleicher's overview presentation] 

===Keynote Presentation by Matt Hall===
Matt Hall made a presentation via Skype at the beginning of the workshop describing his experience in participatory meetings. He has organized several Geophysics Hackathons. He provided an overview of the Tutorials in The Leading Edge.
[https://drive.google.com/open?id=1tyoOuKUYXr90iADph7hi2LosrVaTH09q view Hall's Keynote presentation.] 

===Luke Decker, Matt Sexton, Will Sanger===
This group created tutorial material on Kirchhoff migration. Started with an SEP tutorial from the Madagascar source code repository they implemented least squares migration in Madagascar and Kirchhoff migration and modeling in a Jupyter notebook. A seperate accomplishment was to identify a web site that describes how to install Madagascar using Docker.
[https://drive.google.com/open?id=12GbwZjGUaASvmX0UQaoFluzpT_1CSFpC view Sanger's presentation] 

===Pongthep Thongsang, Lian Jiang, Hoa Li===
This group created a Madagascar modeling and processing tutorial. Starting with a modeling and processing papers in the Madagascar source code repository they created a beginners tutorial for the Madagascar software package. Their tutorial demonstrates finite difference modeling of cary of there Marmots 2 model and simple processing including NMO, stack, and post stack depth migration. The paper will soon be added to the Madagascar repository and the online reproducible papers. [https://drive.google.com/open?id=1shMEfaDUfE-JGMtrmJgQTKyoemuy1wWN view paper by Thongsang et al ] 

===Wenyuan Zhang===
Wenyuan Zhang encounterred problems running parallel Madagascar programs on the University of Houston Cluster. These are due to onitereaction between Madagascar patella options, the cluster configuration, the slum queueing system, and the scons environment. He was able to make small updates to Madagascar source code files api.c and config.py and his scripts now run. These updates have been included in the Madagascar distribution repository. 

===Karl Schleicher===
Reproduces one to "The Leading Edge Tutorials", Linear Inversion. The Jupyter notebook must be changed if you want to run using Python 2.7 instead of 3.5. This work lead to a new tutorial for :The Leading Edge" on the Conjugate Gradient Method. This tutorial is tentatively scheduled to be published in April 2018.
[https://drive.google.com/open?id=1g3qWvzcUFwHCnTAHtt7c94GJo8UfYLVz view schleicher's tle tutorial] 

===tar file of results===
The scripts created at the working workshop are saved in a a zipped tar file that can be downloaded.
[https://drive.google.com/open?id=13WANvsd5jNn0pqJSHcYkrPb-mZV9PehL download ww-hou17.tar.gz]

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
Rm 223, Science & Research Bld1 
University of Houston 
3507 Cullen Boulevard 
Houston, TX 77204-5007 
Use these maps to the location of the school: 

[[Image:Uhmapoverview.gif|600px]] 
[[Image:Uhmapdetail.gif|600px]] 

 

==Supporting Organizations==

[[Image:Beglogo.jpg]]

[[Image:Seglogo.png]]

===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

[[Image:Ricelogo.jpg|left]] [[Image:TRIP.png]] [http://www.trip.caam.rice.edu/ The Rice Inversion Project] 
Department of Computational and Applied Mathematics 
Rice University

Main Page

2018-09-21T16:05:19Z

Karl:

<big>'''Madagascar'''</big> is an open-source software package for multidimensional data analysis and [[Reproducibility|reproducible]] computational experiments. Its mission is to provide
* a convenient and powerful environment
* a convenient technology transfer tool
for researchers working with digital image and data processing in geophysics and related fields. Technology developed using the Madagascar project management system is transferred in the form of recorded processing histories, which become "computational recipes" to be verified, exchanged, and modified by users of the system.

== Features ==

[[Image:Crystal_Clear_app_katomic.png|left|30px|Modern]]
Madagascar is a modern package. Started in 2003 and publicly released in 2006, it was developed almost entirely from scratch. Being a relatively new package, it follows modern software engineering practices such as module encapsulation and test-driven development. A rapid development of a project of this scope (more than 1,000 main programs and more than 5,000 tests) would not be possible without standing on the shoulders of giants and learning from the 30 years of previous experience in open packages such as SEPlib and Seismic Unix. We have borrowed and reimplemented functionality and ideas from these other packages.

[[Image:Crystal_Clear_app_vcalendar.png|left|30px|Test-driven]]
Madagascar is a test-driven package. Test-driven development is not only an agile software programming practice but also a way of bringing scientific foundation to geophysical research that involves numerical experiments. Bringing reproducibility and peer review, the backbone of any real science, to the field of computational geophysics is the main motivation for Madagascar development. The package consists of two levels: low-level main programs (typically developed in the C programming language and working as data filters) and high-level processing flows (described using the Python programming language) that combine main programs and completely document data processing histories for testing and reproducibility. Experience shows that high-level programming is easily mastered even by beginning students who have no previous programming experience.

[[Image:Crystal_Clear_app_gadu.png|left|30px|Open]]
Madagascar is an open-source package. It is distributed under the standard GPL open-source license, which places no restriction on the usage and modification of the code. Moreover, access to modifying the source repository is not controlled by one organization but shared equally among different developers. This enables an open collaboration among different groups spread all over the world, in the true spirit of the open-source movement.

[[Image:Crystal_Clear_filesystem_blockdevice.png|left|30px|Simple,flexible]]
Madagascar uses a simple, flexible, and universal data format that can handle very large datasets but is not tied specifically to seismic data or data of any other particular kind. This "regularly sampled" format is borrowed from the traditional SEPlib. A universal data format allows us to share general-purpose data processing tools with scientists from other disciplines such as petroleum engineers working on large-scale reservoir simulations.

== Latest News ==

{{#widget:Feed
|feedurl=http://ahay.org/blog/feed/
|num=7
|desc=100
|date=n
|targ=n
}}

HoustonWW2018

2018-08-17T20:15:21Z

Karl: /* Synopsis of Results with Links */

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [https://drive.google.com/open?id=1sRojofwRbNVYtrzqU2e-CaU651xJmPAl]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
Matt also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Rafael Pinto and Thu Nguyen===
Rafael and Thu processed wells from the Poseidon project in the NW Shelf Australia. They used lasio to read the data into a Panda data frame, then loaded the data into an sql database. Lasio processes logs from a single well. The sql database is good to manipulate multiple wells on a project. They visualized cross plots in matplotlib and datashader. Datashader plots were better. Their jupyter notebook can be downloaded from this link [https://drive.google.com/open?id=16Ul7r32VZRbrs7JxMIuv0ip0a0AG3JoV]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===
Carlos provided a new viewer for Madagascar. Sfpgreywfl, written in python, will plot a wavefield with a velocity background. He also wrote a julia version of acoustic finite difference wave equation modeling. This programs are being added to the Madagascar repository. His presentation can be downloaded by the link [https://drive.google.com/open?id=1gwGjVsabRADw4-cQwnOPI_x2GcxapO22]

===Sergey Fomel===
Madagascar already had example of acoustic finite difference wave equation modeling in C, C++, and Fortran90. Sergey Fomel implemented the same algorithm in Python. and benchmarked the program in all the languages These are described in the presentation: [https://drive.google.com/file/d/1w302kWFOLPWJwUqAt1NDdBGJ__73XVX1/view?usp=sharing]. 

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-08-17T19:13:25Z

Karl: /* Matt Griffiths */

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [link to be created]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
Matt also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===

===Sergey Fomel and Karl Schleicher===

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-08-17T19:12:52Z

Karl: /* Derek Parks */

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Derek Parks===
Some participants found the current BIOS on Windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [link to be created]. Derek provided updates to python files in Madagascar required to make the system run under Python 3. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
He also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===

===Sergey Fomel and Karl Schleicher===

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-08-17T19:10:47Z

Karl: /* Objective */

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brought their laptops and formed small groups. They picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). Everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Derek Parks===
Some participants found the current BIOS on windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [link to be created]. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
He also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===

===Sergey Fomel and Karl Schleicher===

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-08-17T13:36:16Z

Karl:

[[File:Houston-ww2018.jpg|1000px]]
==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

This is the sixth year we have organized a working workshop. Information about previous events is at this [[http://www.ahay.org/wiki/Working_Workshops website]].

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brough their own laptops and formed small groups. These groups picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). I think everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Agenda==
*Wednesday afternoon August 8, 2018 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2018 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2018
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==
===Derek Parks===
Some participants found the current BIOS on windows computers would not allow them to boot Linux from a USB solid state disk. Derek created a virtual system that provided a platform that performed for the workshop. This virtual system can be downloaded at the link [link to be created]. 

===Derek Parks and Mark Mlella===
Derek and Mark created Jupyter notebooks with Python to read the Teapot Dome 3D segy final volume and displayed using Matplotlib and Mayavi. They also read horizon data which they used to flatten horizons and display stratal slices. They created the amplitude envelope and spectral decomposition volumes and displays. Their presentation is available at the link [https://drive.google.com/file/d/1Wl3MNZotqWMYxPcB5iGL0Kl6lUwih_Gd/view?usp=sharing]. 

===Matt Griffiths===
Matt experimented with Apache Spark, a parallel processing tool, that can be used on seismic data. Spark can be run on a cluster of a single PC with multiple cores. He found it easy to covert his code to run in parallel. His Principle Component Analysis ran about 3 times faster on his computer. His presentation is available at the link [https://drive.google.com/file/d/1mzOurkpcwB_KpG3bK4TyxRHO6R-afF-z/view?usp=sharing]. 
His spark code is at the link [https://drive.google.com/file/d/14xONUqo_eaQDYb_qVV_Ykt7rUMDxNcef/view?usp=sharing]. 
He also experimented with a simple 3D seismic viewer based on pywidgets and matplotlib. This code is available at the link [https://drive.google.com/file/d/1-28Nj5_r368GfougrABcJvCHgkt-GYHi/view?usp=sharing]. 

===Lian Jiang===
Lian worked on Facies classification using Machine Learning. He used a neural net to address the ML challenge data set from the Brendan Hall's Leading Edge Article. Ran trading experiments searching for the best results varying hyper parameters like learning_rate, epochs, and batch_size. Encouraging results are in his presentation at [https://drive.google.com/file/d/1BaceNSRvlKXsXd1LbhYfX-Wan-9nq8Ss/view?usp=sharing]. 

===Carlos da Costa===

===Sergey Fomel and Karl Schleicher===

==Contact us==
If you have some ideas about future working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location and Dates==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston. August 8-11, 2018.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW2018

2018-08-17T12:11:28Z

Karl: /* Draft agenda */

HoustonWW2018

2018-08-17T12:10:53Z

Karl: /* SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018 */

HoustonWW2018

2018-08-15T22:29:15Z

Karl:

File:Houston-ww2018.jpg

2018-08-15T22:24:09Z

Karl:

HoustonWW2018

2018-08-15T22:21:01Z

Karl:

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Participants brough their own laptops and formed small groups. These groups picked projects and started to make examples of geophysical applications written in Python and Julia. About once a day we all checked in to talk about progress. Sometimes participants collaborated with different groups. After two and a half days we shared results in a lightning talks (five minute presentations). I think everyone left the workshop with some new skills, ideas, and acquaintances.

The working workshop provided a forum for geophysicist to learn, contribute, and network.

==Link to the original workshop invitation is [[HoustonWW_2018_i]]==

==Draft agenda==
*Wednesday afternoon August 8, 2017 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Synopsis of Results with Links==

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location==
The workshop was held in rooms 218 and 219 in Farish Hall at the University of Houston.

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

Working Workshops

2018-08-08T17:48:32Z

Karl:

"Working workshops" as opposed to "talking workshops" are meetings where the participants work together (possibly divided into pairs or small teams) to develop new software code or to conduct computational experiments addressing a particular problem. Working workshops are a cross between scientific workshops and [http://en.wikipedia.org/wiki/Sprint_%28software_development%29 coding sprints] or [http://en.wikipedia.org/wiki/Hackathon hackathons] common among open-source software communities.

== Previous workshops ==

===[[Austin_2013|1st Madagascar Working Workshop Reproducibility and Migration Gallery]]===

==== Reproducibility ====

During this workshop, published papers that are not currently reproducible would be made reproducible and included with Madagascar (with permission from the authors). This includes both recent papers and old historical papers.

==== Migration Gallery ====

Migration gallery is a matrix where rows are different benchmark datasets and columns are different seismic migration methods. The goal of the workshop is to fill missing entries in the matrix and to add new rows and columns to it.

===[[Houston_2014|2nd Madagascar Working Workshop Parallel Computing]]===

The parallel computing workshop uses resources of a supercomputing center. The goal is to peform a number of large-scale parallel computations and to test and document different styles of simplifying parallel computing tasks in Madagascar.

===[[Houston_2015|3rd Working Workshop - 3D land Seismic processing]]===

In the data processing workshop, a particular field seismic dataset is selected for processing by different people and possibly different processing packages. A clear metric is developed for comparing results at different stages of data processing. The goal is to learn about the best data processing practices, to improve the existing tools, and to build reproducible examples.

===[[SEG_3D_Seismic_Processing_Working_Workshop_Houston_2016-_Land_3D | 4th Working Workshop - 3D land Seismic processing]]===

In this working workshop we revisted 3D land seismic processing. The goal was to learn about the best data processing practices, to improve the existing tools, and to build reproducible examples.

===[[HoustonWW2017 | 5th Working Workshop - Tutorials]]===
In the tutorial workshop created reproducible tutorials on topics of interest to seismic interpreters, applied geophysicists, and other earth scientists.

===[[HoustonWW2018 | 6th Working Workshop - Python and Julia for Geophysics]]===
In this workshop participants worked on interfacing seismic data to Python and Julia and creating examples using these languages to solve geophysical problems.

==Future workshops==

Here are some suggestions for future working workshops for the Madagascar community.

=== Documentation ===

The goal of this workshop would be to improve the existing Madagascar documentation and to create new documents (books, papers, user manuals).

=== Seismic Interpretation ===

Seismic interpreters can access the Madagascar functionality through the [http://opendtect.org OpendTect] interface. However, they are lacking particular examples of data analysis tasks relevant to seismic interpretation. This workshop will bring together Madagascar/OpendTect developers and practicing interpreters to go through case studies and to build necessary tools.

=== C++/Java/Python/Fortran/Matlab/Julia Interface ===

The goal of this workshop would be to extend the [[Guide_to_madagascar_API|Madagascar interface]] to the corresponding language and to create examples of its usage.

=== Non-seismic Geophysics ===

Develop programs and examples for non-seismic geophysics: potential-field methods (gravity and magnetics), controlled-source electromagnetics (CSEM), ground-penetrating radar (GPR), etc.

HoustonWW 2018 i

2018-08-06T19:09:29Z

Karl: /* Draft agenda */

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 1:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location==
We will meet in room #219 Farish Hall at the University of Houston. Below are area and campus maps.

[[File:Uhlocation.png | 500px ]]
[[File:Uhfarishhall.png | 500px ]]

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW 2018 i

2018-07-26T19:09:11Z

Karl:

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Workshow Location==
We will meet in room #219 Farish Hall at the University of Houston. Below are area and campus maps.

[[File:Uhlocation.png | 500px ]]
[[File:Uhfarishhall.png | 500px ]]

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW 2018 i

2018-07-26T18:55:53Z

Karl: add meeting location and provide maps

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
===The working workshop will be in room #219 Farish Hall at the University of Houston. Below are area and campus maps.===

[[File:Uhlocation.png | 500px ]]
[[File:Uhfarishhall.png | 500px ]]

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

File:Uhfarishhall.png

2018-07-26T18:52:10Z

Karl:

HoustonWW 2018 i

2018-07-26T18:40:50Z

Karl: /* Location */

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
The working workshop with be in Houston. The location has not been selected. Possible locations are the University of Houston or UT's Houston Research Center

[[Uhlocation.png | Location University of Houston]]
* Nearby hotels

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

File:Uhlocation.png

2018-07-26T18:36:36Z

Karl: location of 2018 working workshop

location of 2018 working workshop

Advanced Installation

2018-05-21T11:46:59Z

Karl: /* Ubuntu */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git emacs25

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory
<pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=f90,matlab --prefix=/directory/where/you/want/madagascar/installed</pre>

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

Installation

2018-05-19T14:59:45Z

Karl: /* General instructions */

[[Image:Fotolia_4727725_XS.jpg|right|]]
Madagascar has been installed and is periodically tested on
*Different Linux distributions (Fedora, RedHat, Ubuntu, etc.)
*Solaris
*MacOS X
*Windows under the [http://www.cygwin.com/ Cygwin] environment.

It was previously tested on
*FreeBSD
*HP-UX
*SGI Irix
*Windows under Microsoft's Services for UNIX environment.

==Precompiled binary packages==

See the [[Download|Madagascar download page]] for availability of binary packages.

==Installation from source==

===Platform-specific instructions===

[[Windows|Specific instructions are provided]] for '''Windows''' users.

For other platform-specific instructions, please consult the [[Advanced Installation#Platform-specific_installation_advice|Advanced Installation]] guide.

===Prerequisites===

#C compiler. Any ANSI-compliant compiler such as [http://gcc.gnu.org/ GCC] should work. GCC usually comes pre-installed on Linux machines.
#Python interpreter. [http://www.python.org/ Python] is an interpretable programming language. It is used in Madagascar installation scripts and project management scripts. Python comes pre-installed on some platforms. The preferred Python version is 2.7 but older versions are also supported. If you experience problems and you have an earlier version, you should probably upgrade.

Each API option has [[Advanced Installation#Dependencies|its own prerequisites]].

Prerequisites for optional add-on functionality are [[Advanced Installation#Platform specific installation advice|platform-specific]].

[[Windows|Building under cygwin on Windows]] requires several preparatory steps.

===General instructions===

# '''Configuration:''' Open a terminal window, change to the top Madagascar source directory, and run <syntaxhighlight lang="bash">./configure --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install Fortran-90 API bindings in addition to the basic package, run <syntaxhighlight lang="bash">./configure API=f90 --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> After running <tt>./configure</tt> you may see a list of dependencies that your system does not have installed (the items that have "no" next to them). Most of them are optional. If you decide to install additional packages for your platform, rerun the <tt>./configure</tt> command.
# '''Building and installing the package:''' Run <syntaxhighlight lang="bash">make install</syntaxhighlight> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">make; su; make install</syntaxhighlight> or <syntaxhighlight lang="bash">make; sudo make install</syntaxhighlight> If <tt>make</tt> does not exist on your system, an alternative procedure can be found in the [[#Troubleshooting|Troubleshooting]] section.
# '''User setup:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, add to your <tt>$HOME/.bashrc</tt> and <tt>$HOME/.profile</tt> files the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.sh</syntaxhighlight> (if used somthing different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC). If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.csh</syntaxhighlight> (if used somthing different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC.) Please be aware that, on some systems, the default value for DATAPATH set in the script above may get automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> in your resource file to another location where you have write access and that allows large files. Remember that the value of DATAPATH should have a slash at the end. e.g. add <syntaxhighlight lang="bash">export DATAPATH=~/RSFDATA/ </syntaxhighlight> to ~/.bashrc and ~/.profile after the source ~/RSFSRC/share/madagascar/etc/env.csh. You will also need to create that directory with: <syntaxhighlight lang="bash">mkdir ~/RSFDATA/ </syntaxhighlight> using the command line in a terminal window.

==Uninstall==
To clean all intermediate files and all installed files, run <pre>scons -c install</pre> or <pre>make distclean</pre> in the source code directory.

==Troubleshooting==
===Alternative build/install procedure===
# '''Set the environment variables:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, type <syntaxhighlight lang="bash">source env.sh</syntaxhighlight> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <syntaxhighlight lang="bash">source env.csh</syntaxhighlight>
# '''Build:''' Type <tt>scons</tt>
# '''Install:''' Run <tt>scons install</tt> . If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">su; scons install </syntaxhighlight> or <syntaxhighlight lang="bash">sudo scons install</syntaxhighlight>

===Other issues===
Note that <tt>scons</tt> does not inherit your environmental variables including <tt>PATH</tt>.
If the configuration part ends with the message like
<pre>
checking if cc works ... failed
</pre>
the problem may be that your compiler is in unusual place. Try
<pre>
./configure CC=/full/path/to/cc
</pre>
or
<pre>
./configure CC=`which cc`
</pre>
On Windows under SFU, use the <tt>gcc</tt> compiler
<pre>
./configure CC=/opt/gcc.3.3/bin/gcc
</pre>

For more information, please consult the [[Advanced Installation]] guide.

==Testing and quick start==

Here are a few simple tests and and a brief introduction to Madagascar:

Typing any Madagascar command in a terminal window without parameters should generate a brief documentation on that command. Try one of the following:

<pre>
sfin
sfattr
sfspike
sfbandpass
sfwiggle
</pre>

If you get an error like "Command not found", you may not have your <tt>$PATH</tt> environment variable set correctly, or you may need to issue the <tt>rehash</tt> command.

Now try making a simple Madagascar data file:
<pre>
sfspike n1=1000 k1=300 > spike.rsf
</pre>

This command generates a one dimensional list of 1000 numbers, all zero except for a spike equal to one at position 300. If this generates an error like
<pre>
Cannot write to data file /path/spike.rsf@: Bad file descriptor
</pre>
you may need to create the directory pointed to by your <tt>$DATAPATH</tt> environment variable.

The file <tt>spike.rsf</tt> is a text header. The actual data are stored in the binary file pointed to by the <tt>in=</tt> parameter in the header. You can look at the header file directly with <tt>more</tt>, or better, examine the file properties with
<pre>
sfin spike.rsf
</pre>

You can learn more about the contents of <tt>spike.rsf</tt> with
<pre>
sfattr < spike.rsf
</pre>

The following command applies a bandpass filter to <tt>spike.rsf</tt> and puts the result in <tt>filter.rsf</tt>:
<pre>
sfbandpass fhi=2 phase=y < spike.rsf > filter.rsf
</pre>

The following command makes a graphics file from <tt>filter.rsf</tt>:
<pre>
sfwiggle clip=0.02 title="Welcome to Madagascar" < filter.rsf > filter.vpl
</pre>

If you have an X11 display program running, and your <tt>$DISPLAY</tt> environment variable is set correctly, you can display the graphics file with:

<pre>
sfpen < filter.vpl
</pre>

You can pipe Madagascar commands together and do the whole thing at once like this:

<pre>
sfspike n1=1000 k1=300 | sfbandpass fhi=2 phase=y | \
sfwiggle clip=0.02 title="Welcome to Madagascar" | sfpen
</pre>

If you have SCons installed, you can use it to automate Madagascar processing. Here is a simple <tt>SConstruct</tt> file to make <tt>filter.rsf</tt> and <tt>filter.vpl</tt>:

<syntaxhighlight lang="python">
#
# Setting up
#
from rsf.proj import *

#
# Make filter.rsf
#
Flow('filter',None,'spike n1=1000 k1=300 | bandpass fhi=2 phase=y')

#
# Make filter.vpl
#
Result('filter','wiggle clip=0.02 title="Welcome to Madagascar"')

End()
</syntaxhighlight>

Put the file in an empty directory, give it the name <tt>SConstruct</tt>, <tt>cd</tt> to that directory, and issue the command:

<pre>
scons
</pre>

The graphics file is now stored in the <tt>Fig</tt> subdirectory. You can view it manually with:

<pre>
sfpen Fig/filter.vpl
</pre>

... or you can use:

<pre>
scons view
</pre>

When an SConstruct file makes more than one graphics file, the <tt>scons view</tt> command will display all of them in sequence.
[[Image:filter.png|frame|center|Welcome to Madagascar.]]
Now edit the <tt>SConstruct</tt> file: change the title string on the <tt>Result</tt> line to "Hello World!", save the file, and rerun the scons command. You will see that scons has figured out that the file <tt>filter.rsf</tt> does not need to be rebuilt because nothing that affects it has changed. Only the file <tt>filter.vpl</tt> is rebuilt.

Installation

2018-05-19T14:49:57Z

Karl: /* General instructions */

[[Image:Fotolia_4727725_XS.jpg|right|]]
Madagascar has been installed and is periodically tested on
*Different Linux distributions (Fedora, RedHat, Ubuntu, etc.)
*Solaris
*MacOS X
*Windows under the [http://www.cygwin.com/ Cygwin] environment.

It was previously tested on
*FreeBSD
*HP-UX
*SGI Irix
*Windows under Microsoft's Services for UNIX environment.

==Precompiled binary packages==

See the [[Download|Madagascar download page]] for availability of binary packages.

==Installation from source==

===Platform-specific instructions===

[[Windows|Specific instructions are provided]] for '''Windows''' users.

For other platform-specific instructions, please consult the [[Advanced Installation#Platform-specific_installation_advice|Advanced Installation]] guide.

===Prerequisites===

#C compiler. Any ANSI-compliant compiler such as [http://gcc.gnu.org/ GCC] should work. GCC usually comes pre-installed on Linux machines.
#Python interpreter. [http://www.python.org/ Python] is an interpretable programming language. It is used in Madagascar installation scripts and project management scripts. Python comes pre-installed on some platforms. The preferred Python version is 2.7 but older versions are also supported. If you experience problems and you have an earlier version, you should probably upgrade.

Each API option has [[Advanced Installation#Dependencies|its own prerequisites]].

Prerequisites for optional add-on functionality are [[Advanced Installation#Platform specific installation advice|platform-specific]].

[[Windows|Building under cygwin on Windows]] requires several preparatory steps.

===General instructions===

# '''Configuration:''' Open a terminal window, change to the top Madagascar source directory, and run <syntaxhighlight lang="bash">./configure --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install Fortran-90 API bindings in addition to the basic package, run <syntaxhighlight lang="bash">./configure API=f90 --prefix=/directory/where/you/want/madagascar/installed</syntaxhighlight> After running <tt>./configure</tt> you may see a list of dependencies that your system does not have installed (the items that have "no" next to them). Most of them are optional. If you decide to install additional packages for your platform, rerun the <tt>./configure</tt> command.
# '''Building and installing the package:''' Run <syntaxhighlight lang="bash">make install</syntaxhighlight> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">make; su; make install</syntaxhighlight> or <syntaxhighlight lang="bash">make; sudo make install</syntaxhighlight> If <tt>make</tt> does not exist on your system, an alternative procedure can be found in the [[#Troubleshooting|Troubleshooting]] section.
# '''User setup:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, add to your <tt>$HOME/.bashrc</tt> and <tt>$HOME/.profile</tt> files the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.sh</syntaxhighlight> (if used somthing different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC). If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <syntaxhighlight lang="bash">source ~/RSFSRC/share/madagascar/etc/env.csh</syntaxhighlight> (if used somthing different in the <tt>--prefix</tt> option to <tt>./configure</tt>, use that instead of ~/RSFSRC.) Please be aware that, on some systems, the default value for DATAPATH set in the script above may get automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> in your resource file to another location where you have write access and that allows large files. Remember that the value of DATAPATH should have a slash at the end. e.g. add <syntaxhighlight lang="bash">export DATAPATH=~/DATAPATH/ </syntaxhighlight> to ~/.bashrc and ~/.profile after the source ~/RSFSRC/share/madagascar/etc/env.csh

==Uninstall==
To clean all intermediate files and all installed files, run <pre>scons -c install</pre> or <pre>make distclean</pre> in the source code directory.

==Troubleshooting==
===Alternative build/install procedure===
# '''Set the environment variables:''' If your shell is <tt>sh</tt> or <tt>bash</tt>, type <syntaxhighlight lang="bash">source env.sh</syntaxhighlight> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <syntaxhighlight lang="bash">source env.csh</syntaxhighlight>
# '''Build:''' Type <tt>scons</tt>
# '''Install:''' Run <tt>scons install</tt> . If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <syntaxhighlight lang="bash">su; scons install </syntaxhighlight> or <syntaxhighlight lang="bash">sudo scons install</syntaxhighlight>

===Other issues===
Note that <tt>scons</tt> does not inherit your environmental variables including <tt>PATH</tt>.
If the configuration part ends with the message like
<pre>
checking if cc works ... failed
</pre>
the problem may be that your compiler is in unusual place. Try
<pre>
./configure CC=/full/path/to/cc
</pre>
or
<pre>
./configure CC=`which cc`
</pre>
On Windows under SFU, use the <tt>gcc</tt> compiler
<pre>
./configure CC=/opt/gcc.3.3/bin/gcc
</pre>

For more information, please consult the [[Advanced Installation]] guide.

==Testing and quick start==

Here are a few simple tests and and a brief introduction to Madagascar:

Typing any Madagascar command in a terminal window without parameters should generate a brief documentation on that command. Try one of the following:

<pre>
sfin
sfattr
sfspike
sfbandpass
sfwiggle
</pre>

If you get an error like "Command not found", you may not have your <tt>$PATH</tt> environment variable set correctly, or you may need to issue the <tt>rehash</tt> command.

Now try making a simple Madagascar data file:
<pre>
sfspike n1=1000 k1=300 > spike.rsf
</pre>

This command generates a one dimensional list of 1000 numbers, all zero except for a spike equal to one at position 300. If this generates an error like
<pre>
Cannot write to data file /path/spike.rsf@: Bad file descriptor
</pre>
you may need to create the directory pointed to by your <tt>$DATAPATH</tt> environment variable.

The file <tt>spike.rsf</tt> is a text header. The actual data are stored in the binary file pointed to by the <tt>in=</tt> parameter in the header. You can look at the header file directly with <tt>more</tt>, or better, examine the file properties with
<pre>
sfin spike.rsf
</pre>

You can learn more about the contents of <tt>spike.rsf</tt> with
<pre>
sfattr < spike.rsf
</pre>

The following command applies a bandpass filter to <tt>spike.rsf</tt> and puts the result in <tt>filter.rsf</tt>:
<pre>
sfbandpass fhi=2 phase=y < spike.rsf > filter.rsf
</pre>

The following command makes a graphics file from <tt>filter.rsf</tt>:
<pre>
sfwiggle clip=0.02 title="Welcome to Madagascar" < filter.rsf > filter.vpl
</pre>

If you have an X11 display program running, and your <tt>$DISPLAY</tt> environment variable is set correctly, you can display the graphics file with:

<pre>
sfpen < filter.vpl
</pre>

You can pipe Madagascar commands together and do the whole thing at once like this:

<pre>
sfspike n1=1000 k1=300 | sfbandpass fhi=2 phase=y | \
sfwiggle clip=0.02 title="Welcome to Madagascar" | sfpen
</pre>

If you have SCons installed, you can use it to automate Madagascar processing. Here is a simple <tt>SConstruct</tt> file to make <tt>filter.rsf</tt> and <tt>filter.vpl</tt>:

<syntaxhighlight lang="python">
#
# Setting up
#
from rsf.proj import *

#
# Make filter.rsf
#
Flow('filter',None,'spike n1=1000 k1=300 | bandpass fhi=2 phase=y')

#
# Make filter.vpl
#
Result('filter','wiggle clip=0.02 title="Welcome to Madagascar"')

End()
</syntaxhighlight>

Put the file in an empty directory, give it the name <tt>SConstruct</tt>, <tt>cd</tt> to that directory, and issue the command:

<pre>
scons
</pre>

The graphics file is now stored in the <tt>Fig</tt> subdirectory. You can view it manually with:

<pre>
sfpen Fig/filter.vpl
</pre>

... or you can use:

<pre>
scons view
</pre>

When an SConstruct file makes more than one graphics file, the <tt>scons view</tt> command will display all of them in sequence.
[[Image:filter.png|frame|center|Welcome to Madagascar.]]
Now edit the <tt>SConstruct</tt> file: change the title string on the <tt>Result</tt> line to "Hello World!", save the file, and rerun the scons command. You will see that scons has figured out that the file <tt>filter.rsf</tt> does not need to be rebuilt because nothing that affects it has changed. Only the file <tt>filter.vpl</tt> is rebuilt.

Advanced Installation

2018-05-19T13:26:01Z

Karl: /* Ubuntu */

[[Image:Fotolia_419157_XS.jpg|right|]]
Before reading this document, please familiarize yourself with the [[Installation|short Installation guide]].
=What the installation process does=
The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.
# Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
# Build: compiles the software and documentation using RSFSRC/build as a "workplace"
# Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.
A successful installation will have created in <tt>$RSFROOT</tt> the following directories:
* <tt>bin/</tt>: executable programs
* <tt>doc/</tt>: auto-generated HTML documentation
* <tt>include/</tt>: header files with info on library procedures; fonts
* <tt>lib/</tt>: libraries and Python modules

=Old (1.0 and 1.1) version installation=

Use <tt>$RSFROOT/etc/madagascar/</tt> as the location of <tt>env</tt> scripts instead of <tt>$RSFROOT/share/madagascar/etc/</tt>.

=Old (0.9.9) version installation=

====Environment variables====
Example configuration for <tt>bash</tt>:
<syntaxhighlight lang="bash">
export RSFROOT=/usr/local/rsf # directory where Madagascar will be installed.
if [ -n "$PYTHONPATH" ]; then
export PYTHONPATH=${PYTHONPATH}:$RSFROOT/lib
else
export PYTHONPATH=$RSFROOT/lib
fi
export PATH=$RSFROOT/bin:$PATH
export DATAPATH=/var/tmp/
export MANPATH=$RSFROOT/share/man:$(manpath)
export LD_LIBRARY_PATH=$RSFROOT/lib:$LD_LIBRARY_PATH
</syntaxhighlight>
Notice the slash at the end of the <tt>DATAPATH</tt> variable.

Example configuration for <tt>csh</tt> and <tt>tcsh</tt>:
<pre>
setenv RSFROOT /usr/local/rsf
if ($?PYTHONPATH) then
setenv PYTHONPATH ${PYTHONPATH}:$RSFROOT/lib
else
setenv PYTHONPATH $RSFROOT/lib
endif
set path = ($RSFROOT/bin $path)
setenv DATAPATH /var/tmp/
setenv MANPATH $RSFROOT/share/man:`manpath`
setenv LD_LIBRARY_PATH $RSFROOT/lib:$LD_LIBRARY_PATH
</pre>
Notice the backticks surrounding the call to <tt>manpath</tt>.

Be aware that on some systems /var/tmp gets automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set <tt>DATAPATH</tt> to another location where you have write access and that allows large files.

====Software construction====

#Configuration. Change to the top source directory and run <pre>./configure</pre> You can examine the <tt>config.py</tt> file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running <tt>scons -h</tt>. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <pre>./configure API=c++,fortran-90</pre>
#Building and installing the package. Run <tt>scons install</tt> or the following two commands in succession: <pre>make; make install</pre> or <pre>scons; scons install</pre> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <pre>su; scons install </pre> or <pre>sudo scons install</pre>
#Cleaning. To clean all intermediate files generated by SCons, run <pre>make clean</pre> or <pre>scons -c</pre>

=Prerequisites=
Basic prerequisites are described in the [[Installation|short Installation guide]]. Here are some additional details.
==Compilers==
Madagascar has been built successfully with the following compilers, and possibly with others:
* gcc
* Intel (icc/ifort)
* open64
* clang
* cc (Solaris)

==Python and SCons==
As described below under [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]], Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. If your version of Python is older and you experience problems you should probably [http://www.python.org/ upgrade].

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to <tt>RSFSRC/scons</tt>, unpack the tar file, and type

<syntaxhighlight lang="bash">
python setup.py install
</syntaxhighlight>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<syntaxhighlight lang="bash">
python setup.py install --prefix=$RSFROOT
</syntaxhighlight>

==Location==
As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the [http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard] and either:
# Install everything (including <tt>figs</tt> if you do testing) under <tt>/usr/local/rsf</tt>, with the source tree in <tt>/usr/local/rsf/src</tt>, OR
# Put the source tree in <tt>/usr/local/src/rsf</tt>, and specify <tt>RSFROOT=/usr/local</tt>, so that header files and binaries go in <tt>/usr/local/bin</tt> and <tt>/usr/local/include</tt>. To follow the standard, before installing set <tt>RSFDOC=/usr/local/share/rsf/doc</tt> and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be <tt>/usr/local/share/rsf/figs/</tt>.
# Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the <tt>/usr/</tt> hierarchy, instead of in the <tt>/usr/local/</tt> one.

==Disk space==
At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (<tt>bin/</tt>, <tt>doc/</tt>, <tt>include/</tt> and <tt>lib</tt>) is 31Mb, and <tt>figs/</tt> (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is <tt>$DATAPATH</tt>. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up <tt>$DATAPATH</tt>. A real problem are "disk memory leaks" -- removing header files with anything else than <tt>sfrm</tt> will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time <tt>$DATAPATH</tt> inexorably fills up. You may need to
# keep irreplaceable data and expensive results in a separate place;
# remove the oldest files in <tt>$DATAPATH</tt> whenever the amount of free space declines under a preset threshold.

==Dependencies==
Some platforms feature complete lists of dependencies. See [[Advanced Installation#Platform-specific installation advice | Platform-specific installation advice]] for details.
===C++ API===
A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the <tt>CXX</tt> environment variable (can be passed as an option to the configuration script, like the <tt>API</tt> one).
===F77 API===
A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the <tt>F77</tt> variable, or if the executable is in your path, add its name to the list of F77 compilers in <tt>RSFSRC/configure.py</tt> .
===F90 API===
Same as for Fortran 77 – just substitute <tt>F90</tt>. If using the <tt>gfortran</tt> compiler, make sure to get [http://gcc.gnu.org/wiki/GFortranBinaries the latest version]. If you have more than one compiler installed on your system, specify the desired one at configuration time:
<bash>
./configure API=f90 F90=/path/to/preferred/compiler
</bash>

===Java API===
There are two styles of API, old (1.0 release and previous) and new. The two APIs are not compatible with each other.

The "old" interface requires the Mines Java Toolkit for fast Java file IO. The Mines JTK, is an open-source Java package that can be downloaded from [http://inside.mines.edu/~dhale/jtk/ Mines JTK]. Currently, the "old" interface will also build alongside the new one if the MINESJTK environment variable exists, and can be used as was previously.

To install the new API, you need the (Oracle) JDK. Set your JAVA_HOME environment variable to the location of the jdk (on Ubuntu 10.04 this is: /usr/lib/jvm/java-6-openjdk), then reconfigure (./configure API=java ...) and reinstall.

Ignore the SWIG warnings (there are lots).

Make sure to set your LD_LIBRARY_PATH to $RSFROOT/lib .

If you want to include additional Java packages, you can set them using your shell's CLASSPATH variable. This environment variable is now automatically passed onto all Java classes in SCons.

The installation can be tested using the example demonstrating the new API in api/java/test .

===Matlab API===
Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the <tt>MATLAB</tt> and <tt>MEX</tt> environment variables to specify their paths if they are installed, but not found.
===Octave API===
The Octave function compiler (<tt>mkoctfile</tt>) is sometimes bundled in a separate package, so it may be missing from the Octave installation.

===Python API===
This API requires [http://www.swig.org/ SWIG], [http://numpy.scipy.org/ numpy] and the Python development kit. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as [http://en.wikipedia.org/wiki/Glue_language glue] to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python [http://en.wikipedia.org/wiki/Meta-programs metaprograms] in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

===Python modules in user space===
Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

<pre>python setup.py install --prefix=/path/to/your/place</pre>

The installer will create a subdirectory named <tt>lib</tt>, or <tt>lib64</tt> under the directory above. These <tt>lib*</tt> dirs will have a directory named <tt>python</tt>, or <tt>python2.3</tt> for example, and those will have a subdirectory named <tt>site-packages</tt>. Add all paths to these <tt>site-packages</tt> subdirectories in your <tt>PYTHONPATH</tt> environment variable. Some (<tt>numpy</tt>) may create a <tt>bin</tt> directory that needs to be added to <tt>PATH</tt>.

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|short Installation guide]]), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv */*.c */*/*.c */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| RSFMEMSIZE || 100 || Maximum RAM (Mb) to be used by some programs
|-
| RSFSRC || undefined || Root of the Madagascar source tree
|-
| TMPDATAPATH || $DATAPATH || Datapath for temporary files on local disk.
|-
| LATEX2HTML || undefined || LateX2HTML customization directory
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar graphics programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| DEFAULT_PAPER_SIZE || "letter" || For pspen. Other options: legal, a3, a4, a5.
|-
| FATMULT || ? || Fatness multiplication factor.
|-
| GIFBORDER || 0.25 || For vplot2gif (spacing)
|-
| GIFDELAY || 100 || For vplot2gif (for animations)
|-
| IMAGE_TYPE || 'png' || Icon type for LateX2HTML
|-
| PATTERNMULT || None || Pattern multiplication factor
|-
| PLOTSTYLE || None || Used in vplot
|-
| PPI || 75 || For vplot2gif (screen resolution)
|-
| PPMSCALE || 1 || For vplot2gif
|-
| PSBORDER || 0.05 || For vplot2eps (border around the plot)
|-
| PSPRINTER || postscript or colorps || For pspen
|-
| PSTEXPENOPTS || color=n fat=1 fatmult=1.5 invras=y || Other vplot2eps options
|-
| VPLOTFONTDIR || $RSFROOT/include || Dir with backup fonts in case the runtime-loaded vplot fonts are not found
|-
| VPLOTSPOOLDIR || /tmp || Where to put vplot tmp files
|-
| WSTYPE || "default" || Workstation type.
|}

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| Variables set by OS/other apps, read-only to Madagascar
|-
| '''Name''' || '''Primarily used/set by'''
|-
| CWPROOT || Seismic Unix
|-
| DISPLAY || Operating System (OS)
|-
| HOME || OS
|-
| LD_LIBRARY_PATH || linker
|-
| MATLABPATH || Matlab
|-
| XAUTHORITY || X-Windows
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

==Used by the Matlab API==
To use the Matlab API, you need to add <tt>$RSFROOT/lib</tt> to <tt>MATLABPATH</tt>
==Used by the Octave API==
To use the Octave API, you need to add <tt>$RSFROOT/lib</tt> to Octave's path. Determine Octave's version with
<syntaxhighlight lang="bash">
octave -v | head -1
</syntaxhighlight>
If your version is lower than 2.9.6, type at a Unix command line:
<syntaxhighlight lang="bash">
echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc
</syntaxhighlight>
For later versions, use:
<syntaxhighlight lang="bash">
echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc
</syntaxhighlight>
==Used by the Java API==
New-style (post-1.0) API: Needs <tt>JAVA_HOME</tt>

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) NFS] are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. [http://en.wikipedia.org/wiki/RHEL RHEL]), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures:
<syntaxhighlight lang="bash">
REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then
export RSFROOT
elif [ $REDHAT_RELEASE == '3' ] ; then
export RSFROOT=$RSFROOT/$ARCH
fi
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.

=Platform-specific installation advice=
==Supported platforms==
Madagascar attempts to support any [http://en.wikipedia.org/wiki/POSIX POSIX-compliant] operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of [http://scons.org/ SCons]. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. [http://distrowatch.com/table.php?distribution=redhat Python 2.2 was bundled by RHEL3], so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but in January 2010 only Fedora 11 and 12 are actively maintained. Thus, in January 2010 Madagascar was not attempting to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support. An application of the above guidelines to some Linux distributions follows:

'''Support info'''
{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Distribution
! style="background:#ffdead;" | Life Cycle
! style="background:#ffdead;" | Supported versions
|-
| RHEL/CentOS/Scientific Linux
| [https://www.redhat.com/security/updates/errata/ 7 years]
|
* 6 until 2017-11-30
* 5 until 2014-03-31
|-
| Fedora
| [http://fedoraproject.org/wiki/Fedora_Release_Life_Cycle Release X maintained until one month after the release of X+2]
|
* 15 until 2012-06-24
* 14 until 2011-12-02
|-
| Ubuntu
| [https://wiki.ubuntu.com/Releases Releases every 6 mo, maintained for 1.5 yrs; LTS versions every 2 yrs, maintained for 5 yrs]
|
* 15.10 until July 2016
* 14.04 LTS until end of April 2019
* 12.04.4 LTS until end of April 2017
|-
| Debian
| [http://wiki.debian.org/DebianLenny Usually: stable releases every 1.5-3 yrs, release X maintained 1 yr after release X+1]
|
* 6 until its TBD end of life (approx. 2014)
* 5 until 2012-04
|-
| openSUSE
| [http://en.opensuse.org/Lifetime openSUSE releases Lifetime of 1.5-2.5 years]
|
* 11.4 until 2012-09-10
* 11.3 until 2012-01-15
|}

==Ubuntu==
In '''Ubuntu 18.04''', you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc scons git

</pre>
In '''Ubuntu 15.10 ''Wily Werewolf''''' (as well as some previous versions), you can install the essential Madagascar depenency by running
<pre>
sudo apt-get install libxaw7-dev
</pre>
and (optionally) all of Madagascar's dependencies by running
<pre>
sudo apt-get install libxaw7-dev freeglut3-dev libnetpbm10-dev libgd-dev libplplot-dev \
libavcodec-dev libcairo2-dev libjpeg-dev swig python-dev python-numpy g++ gfortran \
libopenmpi-dev libfftw3-dev libsuitesparse-dev python-epydoc
</pre>

In Ubuntu 13.04 ''Raring Ringtail'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc scons
</pre>

In Ubuntu 12.10 ''Quantal Quetzal'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libx11-dev libxaw7-dev \
libnetpbm10-dev swig python-dev python-numpy libblas-dev libcairo2-dev liblapack-dev \
libavcodec-dev python-epydoc
</pre>

In Ubuntu 12.04 ''Precise Pangolin'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install scons openmpi-bin libopenmpi-dev freeglut3-dev g++ gfortran libgd2-xpm-dev \
libglew1.6-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy \
libtiff4-dev scons units libblas-dev libcairo2-dev liblapack-dev libavcodec-dev python-epydoc
</pre>

In Ubuntu 10.10 ''Maverick Meerkat'', you can install all of Madagascar's dependencies by running
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev \
scons units libblas-dev libcairo2-dev libavcodec-dev libplplot-dev
</pre>

In Ubuntu 9.04 ''Jaunty Jackalope'', the corresponding command is
<pre>
sudo apt-get install freeglut3-dev g++ gfortran libc6-dev libgd2-xpm-dev libglew1.5-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

Earlier versions may work with
<pre>
sudo apt-get install mesa-libGL-devel g++ g77 libc6-dev libgd2-xpm-dev libglew-dev libjpeg62-dev \
libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy libtiff4-dev scons units
</pre>

If working with the development version, you will also need <tt>git</tt> or <tt>subversion</tt>.

==Fedora, RedHat, CentOS, Scientific Linux, openSUSE==

Install essential Madagascar dependencies with
<pre>
sudo yum install gcc libXaw-devel
</pre>

Dependency package names, sorted by Linux distribution and Madagascar feature they provide. Packages that are not included in the standard distro repositories are hyperlinked to their providers. The tables below cover build dependencies.

Names of packages that are runtime dependencies are '''highlighted''' in the tables below (task under construction).

''Note: In the future, it should be possible for the configuration scripts to output the dependency tables below, so that they are guaranteed to be in synch with a given Madagascar version''

'''Minimal install ("Core"), publishing and development'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Core
! style="background:#ffdead;" | LaTeX
! style="background:#ffdead;" | Development version
! style="background:#ffdead;" | C++ API
! style="background:#ffdead;" | F77 API, F90 API
! style="background:#ffdead;" | Python API
! style="background:#ffdead;" | Java API
! style="background:#ffdead;" | Octave API
! style="background:#ffdead;" | Matlab API
|-
! style="background:#ffdead;" | Fedora 15
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig, python-devel
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 14
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab] with Mex
|-
! style="background:#ffdead;" | Fedora 13
| binutils, gcc, glibc-headers, python
| texlive-latex
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?)
| octave, octave-devel
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | CentOS 5
| binutils, gcc, glibc-headers; python (needs [http://dag.wieers.com/rpm/FAQ.php#B2 RPMforge's RHEL5 repository])
| ?
| subversion
| gcc-c++
| gcc-gfortran
| numpy, swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave, octave-devel]
| [http://www.mathworks.com/ Matlab]
|-
! style="background:#ffdead;" | openSUSE 11.0
| gcc, python
| texlive-latex
| subversion
| gcc-c++
| gcc-fortran
| [http://numpy.scipy.org/ NumPy], swig
| Java (Sun's? IcedTea?), [http://inside.mines.edu/~dhale/jtk/ Mines JTK]
| [http://www.gnu.org/software/octave/ Octave]
| [http://www.mathworks.com/ Matlab]
|}

'''Graphics and visualization'''

The minimum requirement is X11 graphics for running '''xtpen'''.

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | X11 graphics
! style="background:#ffdead;" | vplot2gif
! style="background:#ffdead;" | vplot2avi
! style="background:#ffdead;" | Some sort of movies?
! style="background:#ffdead;" | TIFF output
! style="background:#ffdead;" | JPEG output
! style="background:#ffdead;" | PLplot graphics
! style="background:#ffdead;" | OpenGL graphics
! style="background:#ffdead;" | ppm (?)
! style="background:#ffdead;" | unknown
|-
! style="background:#ffdead;" | Fedora 13
| libXaw-devel
| gifsicle
| ffmpeg (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| ffmpeg-devel (needs the [http://rpmfusion.org/ RPM Fusion] repository enabled)
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| ?
|-
! style="background:#ffdead;" | openSUSE 11.0
| xorg-x11-devel
| ?
| ?
| ?
| libtiff-devel
| libjpeg-devel
| plplot-devel
| mesa-libGL-devel, freeglut, freeglut-devel
| netpbm-devel
| cairo-devel, gd-devel, glew-devel
|}

'''Numerical and file manipulation utilities'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | OpenMP
! style="background:#ffdead;" | MPI
! style="background:#ffdead;" | BLAS/ATLAS
! style="background:#ffdead;" | Interface to the Fast Discrete Curvelet Transform
! style="background:#ffdead;" | sfunits
|-
! style="background:#ffdead;" | Fedora 13
| libgomp
| openmpi, openmpi-devel; openmpi-libs (?)
| blas, blas-devel, atlas, atlas-devel
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| units
|-
! style="background:#ffdead;" | CentOS 5
| ?
| ?
| ?
| [https://wave.eos.ubc.ca/Software/Licenced/ pyct]
| [http://www.gnu.org/software/units/units.html Gnu Units]
|}

'''Other'''

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
|
! style="background:#ffdead;" | Inclusions from Seismic Unix
|-
! style="background:#ffdead;" | Fedora 14, 15
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]
|-
! style="background:#ffdead;" | CentOS 5
| [http://www.cwp.mines.edu/cwpcodes/ Seismic Unix]

|}

'''Command to install all dependencies present in the public repositories'''

Usually package management software will not install again a package that is already installed, so it should be safe to copy and paste the command below to a command line:

{| class="wikitable" align="center" cellspacing="0" border="1"
|-
! style="background:#ffdead;" | Fedora 15
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python python-devel swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | Fedora 13
| '''yum -y install''' binutils gcc glibc-headers scons texlive-latex subversion gcc-c++ gcc-gfortran numpy python swig octave octave-devel libgomp openmpi openmpi-devel blas blas-devel atlas atlas-devel units gifsicle ffmpeg ffmpeg-devel libtiff-devel libjpeg-devel plplot-devel mesa-libGL-devel freeglut freeglut-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | CentOS 5
| '''yum -y install''' binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel
|-
! style="background:#ffdead;" | openSUSE 11.0
| '''zypper install''' cairo-devel gcc gcc-c++ gcc-fortran gd-devel glew-devel libjpeg-devel libtiff-devel octave scons subversion texlive-latex xorg-x11-devel
|}

'''List of runtime dependencies only'''
(needed by packagers of Madagascar in order to properly list dependencies):
UNDER CONSTRUCTION

===Fedora 25===
The following explains how to install madagascar on Fedora 25.

We use the following compiler: <code>gcc</code>, <code>g++</code> and <code>gfortran</code>.

* Install some packages
<syntaxhighlight lang="bash" inline style="white-space:wrap">sudo dnf install scons lapack-static lapack64-static atlas-static fftw-static gd gd-devel libtool-ltdl-devel \
libXaw-devel mesa-libGL-devel freeglut-devel netpbm-devel plplot-devel ffmpeg-devel swig openmpi openmpi-devel suitesparse-devel</syntaxhighlight>
This installed the following packages:
<pre>
scons-2.5.1-1.fc25.noarch
lapack-static-3.6.1-2.fc25.x86_64
lapack64-static-3.6.1-2.fc25.x86_64
atlas-static-3.10.2-14.fc25.x86_64
fftw-static-3.3.5-3.fc25.x86_64
gd-2.2.4-1.fc25.x86_64
gd-devel-2.2.4-1.fc25.x86_64
libtool-ltdl-devel-2.4.6-13.fc25.x86_64
libXaw-devel-1.0.13-4.fc25.x86_64
mesa-libGL-devel-17.0.5-3.fc25.x86_64
freeglut-devel-3.0.0-3.fc24.x86_64
netpbm-devel-10.78.00-1.fc25.x86_64
plplot-devel-5.11.1-13.fc25.x86_64
ffmpeg-devel-3.1.9-1.fc25.x86_64
swig-3.0.11-1.fc25.x86_64
openmpi-1.10.5-1.fc25.x86_64
openmpi-devel-1.10.5-1.fc25.x86_64
suitesparse-devel-4.4.6-7.fc25.x86_64
</pre>
and many other dependencies.

* Get the sources from the git repository
<syntaxhighlight lang="bash">git clone https://github.com/ahay/src</syntaxhighlight>

If you run now the <code>configure</code> script, you will get:

<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... no

Optional package: plplot-devel
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... no

Optional package: blas + blas-devel + atlas + atlas-devel
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>

Libraries <code>plplot</code> and <code>lapack</code> are not found. File <code>config.log</code> says
<pre>
/bin/ld: cannot find -lplplotd
</pre>

and

<pre>
gcc -o .sconf_temp/sfconftest_21 .sconf_temp/conftest_21.o -L/usr/lib64/atlas -lm -lf77blas -lcblas -latlas -llapack -lcblas
/usr/lib64/atlas/liblapack.a(dgesv.o): In function `dgesv_':
(.text+0x69): undefined reference to `xerbla_'
/usr/lib64/atlas/liblapack.a(ATL_f77wrap_dgesv.o): In function `atl_f77wrap_dgesv_':
(.text+0x10d): undefined reference to `ATL_xerbla'
/usr/lib64/atlas/liblapack.a(ATL_dgetf2.o): In function `ATL_dgetf2':
(.text+0x184): undefined reference to `ATL_dger'
...
</pre>

So library <code>plplotd</code> doesn't exist on Fedora 25 and the <code>configure</code> script is looking for the wrong <code>lapack</code> library.

If compiling now, 2 other libraries won't be found: <code>gfortran</code> and <code>quadmath</code>

* Regarding the <code>plplotd</code> library, edit file <code>framework/configure.py</code> and change the line 724:
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplotd')</syntaxhighlight>
to
<syntaxhighlight lang="python" line start="724">plplot = context.env.get('PLPLOT','plplot')</syntaxhighlight>

* As for the libraries
** <code>lapack</code>
** <code>gfortran</code>
** <code>quadmath</code>
We must use the <code>lapack</code> library installed in <code>/usr/lib64</code>, not the one installed in <code>/usr/lib64/atlas</code>. And libraries <code>gfortran</code> and <code>quadmath</code> are installed in <code>/usr/lib/gcc/x86_64-redhat-linux/6.3.1/</code>.
Edit file <code>framework/configure.py</code> and add the following 4 lines:
<pre>
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/',
'/usr/lib64/',
</pre>
and
<pre>
LIBS.append('gfortran')
LIBS.append('quadmath')
</pre>

so that we end up with the following <code>blas</code> function:
<syntaxhighlight lang="python" line start="971">def blas(context):
context.Message("checking for BLAS ... ")
text = '''
#ifdef __APPLE__
#include <Accelerate/Accelerate.h>
#else
#ifdef HAVE_MKL
#include <mkl.h>
#else
#include <cblas.h>
#endif
#endif
int main(int argc,char* argv[]) {
float d, x[]={1.,2.,3.}, y[]={3.,2.,1.};
d = cblas_sdot(3,x,1,y,1);
return 0;
}\n'''

if plat['OS'] == 'cygwin':
context.env['ENV']['PATH'] = context.env['ENV']['PATH'] + \
':/lib/lapack'

res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['BLAS'] = True
else:
# first try blas
LIBS = path_get(context,'LIBS')
blas = context.env.get('BLAS','blas')
LIBS.append(blas)
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = blas
else:
# some systems require cblas and atlas
for atlas_dir in filter(os.path.isdir,
['/usr/lib/gcc/x86_64-redhat-linux/6.3.1/', # <--- add this line
'/usr/lib64/', # <--- add this line
'/usr/lib64/atlas/',
'/usr/lib/atlas/']):
context.env['LIBPATH'].append(atlas_dir)
LIBS.pop()
LIBS.append('f77blas')
LIBS.append('cblas')
LIBS.append('atlas')
LIBS.append('gfortran') # <----------------------------------------------- add this line
LIBS.append('quadmath') # <----------------------------------------------- add this line
res = context.TryLink(text,'.c')
if res:
context.Result(res)
context.env['LIBS'] = LIBS
context.env['BLAS'] = 'cblas'
else:
context.Result(context_failure)
context.env['CPPDEFINES'] = \
path_get(context,'CPPDEFINES','NO_BLAS')
LIBS.pop()
LIBS.pop()
LIBS.pop()
context.env['BLAS'] = None
need_pkg('blas', fatal=False)
</syntaxhighlight>
* Run the <code>configure</code> script, for example:
<syntaxhighlight lang="bash">./configure --prefix=/usr/local/rsf</syntaxhighlight>
Output should give:
<syntaxhighlight lang="bash">
checking for Python ... /usr/bin/python
checking Python version ... 2.7.13
checking for RSFROOT ... /usr/local/rsf
checking for SCons ... /usr/bin/scons
checking SCons version ... v2.5.1.rel_2.5.1:3735:9dc6cee5c168[MODIFIED]
Running RSFROOT=/usr/local/rsf /usr/bin/scons config ...
------------------------
scons: Reading SConscript files ...
checking platform ... (cached) linux [fedora]
checking for C compiler ... (cached) gcc
checking if gcc works ... yes
checking if gcc accepts '-x c -std=gnu99 -Wall -pedantic' ... yes
checking for ar ... (cached) ar
checking for libraries ... ['m']
checking complex support ... yes
checking for X11 headers ... /usr/include
checking for X11 libraries ... /usr/lib
checking for OpenGL ... yes
checking for sfpen ... (cached) xtpen
checking for ppm ... yes
checking for tiff ... yes
checking for GD (PNG) ... yes
checking for GD (GIF) ... yes
checking for plplot ... yes
checking for ffmpeg ... yes
checking for cairo (PNG) ... yes
checking for cairo (SVG) ... yes
checking for cairo (PDF) ... yes
checking for jpeg ... yes
checking for BLAS ... yes
checking for LAPACK ... yes
checking for SWIG ... (cached) /usr/bin/swig
checking for numpy ... (cached) yes
checking API options ... (cached) []
checking for C++ compiler ... (cached) g++
checking if g++ works ... yes
checking if g++ accepts '-std=c++11 -U__STRICT_ANSI__ -Wall -pedantic' ... yes
checking for MPICC ... (cached) /usr/lib64/openmpi/bin/mpicc
checking if /usr/lib64/openmpi/bin/mpicc works ... yes
checking for MPICXX ... (cached) /usr/lib64/openmpi/bin/mpicxx
checking if /usr/lib64/openmpi/bin/mpicxx works ... yes
checking for MPIRUN ... (cached) /usr/lib64/openmpi/bin/mpirun
checking for Posix threads ... yes
checking for OpenMP ... yes
checking for CUDA ... (cached) no
checking for FFTW ... yes
checking if FFTW supports threads ... yes
checking for SuiteSparse ... yes
checking for pfft ... no
scons: done reading SConscript files.
scons: Building targets ...
shell_script(["env.sh"], [])
shell_script(["env.csh"], [])
scons: done building targets.
------------------------
Done with configuration.
</syntaxhighlight>
* Then run the compilation:
<syntaxhighlight lang="bash">make</syntaxhighlight>

* and finally the installation
<syntaxhighlight lang="bash">sudo make install</syntaxhighlight>

==Debian 5==
Specific dependencies:
* Debian 5.0 ("Lenny"): Please make sure you have the <tt>libc6-dev</tt> package before trying to compile from source. The <tt>libXaw7-dev</tt> package might be a dependency for <tt>xtpen</tt> (was in Debian 4.0)

==Yellow Dog Linux 6.1 on Sony PlayStation 3==
See [http://www.reproducibility.org/rsflog/uploads/Friday_Seminar_Madagascar_on_PS3.ppt Will Burnett's guide (PowerPoint)]

==Mac OS X==

Install necessary Mac OS X applications using:
* [http://www.macports.org/ MacPorts], an easy-to-use system for compiling, installing, and upgrading open-source software on Mac OS X.
* [http://www.finkproject.org/ Fink], a tool that brings the full world of Unix Open Source software to Mac OS X.

Installation on Mac OS X Mountain Lion requires the following:
# Xcode: Download and install [https://developer.apple.com/xcode/ XCode] from Apple using App Store application. In Xcode, make sure to enable and install the command-line tools in Xcode/Preferences/Downloads
# (Optionally) X11: Install X11 libraries from [http://xquartz.macosforge.org Xquartz].
# (Optionally) gcc: Install the Gnu C compiler from [http://hpc.sourceforge.net HPC Mac OS X].
# (Optionally) [[SEGTeX]]: To use SEGTeX, you may need [http://www.tug.org/texlive/ TeX Live]. MacPorts and Fink provide an easy way to install it with commands <pre>sudo port install texlive</pre> or <pre>sudo fink install texlive</pre>
# (Optionally) FFTW: Using MacPorts, run <pre>sudo port install fftw-3-single</pre><pre>sudo port install fftw-3 +gfortran</pre>
# (Optionally) MPI: Using MacPorts, run <pre>sudo port install openmpi</pre><pre>sudo port select --set mpi openmpi-mp-fortran</pre>
# (Optionally) ppmpen: Using MacPorts, run <pre>sudo port install libnetpbm</pre>
# (Optionally) Open vplots using double click: [[machacks|Instructions]].
Proceed with configuration and installation following the normal procedure. You may need to use Apple's compiler (clang) instead of gcc. Use one of these commands in the $RSFSRC directory
<pre>./configure CC=clang CXX=clang++</pre> or <pre>./configure CC=clang CXX=clang++ API=f90,matlab --prefix=/directory/where/you/want/madagascar/installed</pre>

==OpenSolaris==

Use <tt>pkg</tt> to install missing components such as X11 headers.

<syntaxhighlight lang="bash">
pfexec pkg install SUNWxorg-headers
</syntaxhighlight>

==MS Windows==
Due to its size, this topic has been assigned [[Windows | its own Wiki page]].

==How to adapt Madagascar to a new platform==
The most laborious part of adapting madagascar to a new platform is finding the proper dependency names. This usually proceeds as follows: dependency X fails with a "missing file" error either as a header file in <tt>config.log</tt>, or a missing library during the build step. Possible package names are found through an internet search for the missing file name and the distribution name or by using specific [http://rpm.pbone.net/ rpm search tools]. Packages are installed and the configure (and, if necessary) build processes are repeated until the error goes away.

=Multi-user installs=
Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:
* "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import <tt>configure.py</tt> and <tt>config.py</tt> You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are
<syntaxhighlight lang="python">
srcroot = os.environ.get('RSFSRC', '../..')
sys.path.append(srcroot)
</syntaxhighlight>
and then replace <tt>../..</tt> throughout the SConstruct using <tt>os.path.join</tt> and the <tt>srcroot</tt> variable.
* "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:
<syntaxhighlight lang="bash">
ln -s /home/joe/rsfsrc $RSFSRC/user/joe
</syntaxhighlight>
''When the link exists'', those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type <tt>scons -c install</tt> (not likely).
* point the user's RSFDOC environment variable to a location where the user has write access
* edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole <tt>librsf</tt> with user-specific flags in <tt>RSFSRC/filt/lib/</tt>. To do that, replace in the user's SConstruct the env.Prepend statement with
<syntaxhighlight lang="python">
rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],
LIBPATH=[os.path.join(rsfroot,'lib')],
LIBS=['rsf'])
</syntaxhighlight>
* If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the [[Advanced_Installation#Disk_space|Disk Space subsection]] at the beginning of this document.

=Keeping your stuff separate=
A user may add his own programs and recipes to the Madagascar system. He may also create his own computational examples, data, and locked figures for testing. All of these components can be placed in their default locations, but it is not necessary to make them public. To keep these items private simply do not add them to the repository.

However, it might be desirable to keep these components in separate places. For example, if you keep your private programs in RSFSRC/user you will have to remember to make a copy somewhere else if you ever want to delete the Madagascar installation to perform a fresh install. Yup, I deleted all my programs that way once. Good thing I had a back up! Fortunately, it is easy to keep each of these components in a separate place if desired.

==Keeping programs separate==
User programs are ordinarily kept in a subdirectory of RSFSRC/user. However, if you want to keep your programs separate all you have to do is put your subdirectory somewhere else and make a link to it in RSFSRC/user:
<bash>
ln -s path_to_my_programs $RSFSRC/user/my_programs
</bash>
The additional instructions above for "multi-user installs" are for the case where the other users do not have write access to RSFSRC. However, if you have full write access and only want to keep the programs in a separate place the link is the only thing you need.

===Problems when symbolic linking and using SVN===
If you decide to use a symbolic link e.g. "ln -s ..." as above, you will have difficulties checking in your code into the SVN repository. SVN typically does not follow the symbolic link but will only the save the symbolic link.

See this answer from Stackoverflow (http://stackoverflow.com/questions/24850844/follow-symlinks-in-svn)

<blockquote>

If I understand your problem, you have:

project1/
project1/link1 -> ../../some/where/else

If you do a simple svn add link1 it adds a symlink entry to the subversion repository, but what you're trying to accomplish is getting the stuff under somewhere else into the tree.

If this is the case, then you're fighting in the wrong direction, you should make the real files and directories under link1, and make the target locations symlinks into the link1 directory. That would be a simple solution to the problem.

Another solution would be to make the location ../../some/where/else an svn location in it's own right, and make link1 an externals definition to that location. When you commit in the main directory, the externals would be committed at the same time which would achieve storing the information; however to ensure that the other location was kept in sync, you would have to make sure to update it to the same version as the stored data.

In my case, on my desktop, I have a settings directory:

$HOME/settings

This is a checked out copy of a directory containing .bashrc, .profile, .vimrc, .vim, etc. files and folders from an svn repo. All my profile files and directories were symlinks into this folder, so for example .profile -> settings/.profile, etc. When I make changes, they are reflected in the svn tree, which I can commit back to in order to ensure that I don't lose my config settings when I go to another system.

If you really want svn to follow symlinks as hardlinks (You can't make directory hardlinks because it would be a bad thing™), then you'll have to hack the svn client source so that it did what you wanted; but this would be a maintenance nightmare.

You could get away with making the symlink into a bind mount point directed at the target, but that has it's own issues - you would need to be root to accomplish this, and it ends up leaving funny entries in your /proc/mounts to accomplish this:

mount --bind /absolute/path/to/some/where/else project1/link1
</blockquote>

==Keeping recipes separate==
Computational recipes written in Python and imported by the SConstruct file of a workflow are normally stored in RSFSRC/book/Recipes. The install process copies these recipes to a directory like $RSFROOT/lib/python2.5/site-packages/rsf/recipes and adds this directory to your PYTHONPATH so that Python can find them.

However, you can put you own recipes anywhere you want. You only have to add that place to your PYTHONPATH like this (bash):
<syntaxhighlight lang="bash">
export PYTHONPATH=${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>
Or like this (csh):
<syntaxhighlight lang="bash">
setenv PYTHONPATH ${PYTHONPATH}:path_to_my_recipes
</syntaxhighlight>

==Keeping examples separate==
Madagascar's public collection of example workflows are stored in RSFSRC/book, but you can put your private workflows anywhere you want. No special instructions are required.

However, Madagascar assumes that the workflows are organized into a three-level book/chapter/section directory hierarchy when it creates a directory tree for the data and locked figures associated with your workflow. It is not required, but it might be easier to find the data and locked figures if you put your workflows in a three-level directory tree something like this: path_to_my_book/chapter/section/SConstruct.

==Keeping data separate==
The location of the data portion of your *.rsf files is controlled by your DATAPATH environment variable. However, you may want to keep the data for your private workflows in a different place, or several different places, than the data created by the public examples in RSFSRC/book. The way to do that is to temporarily change the DATAPATH variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['DATAPATH'] = 'path_to_my_private_data'

from rsf.proj import *
</syntaxhighlight>

==Keeping locked figures separate==
The command "scons lock" in the directory of a workflow will store a "locked" copy of your figures for regression testing. Normally these figures are stored in the location pointed to by your RSFFIGS variable, and that is where the figures from the figures repository should be stored for testing in RSFSRC/book.

However, you may want to keep your private figures in a different place. The way to do that is to temporarily change the RSFFIGS variable in the SConstruct ''before'' importing rsf.proj like this:
<syntaxhighlight lang="python">
import os
os.environ['RSFFIGS'] = 'path_to_my_private_figures'

from rsf.proj import *
</syntaxhighlight>
If you also create a RSFALTFIGS environment variable pointing to path_to_my_private_figures, then the testing script sffiglist will automatically test your figures against those in RSFALTFIGS when the sffiglist command is executed from a location outside of RSFSRC/book.

=Capturing error and warning messages=
The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file and observed at the same time with a command like this (tcsh):
<syntaxhighlight lang="bash">
nice +10 nohup /usr/bin/time -p scons -k |& tee log_build.asc
</syntaxhighlight>
The log file can be of course named otherwise than <tt>log_build.asc</tt>. The file can be later grepped for error and warnings with commands such as:
<syntaxhighlight lang="bash">
grep -c error log_build.asc
grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}'
grep -c warning log_build.asc
grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}'
</syntaxhighlight>

=Advanced troubleshooting=
* If you removed one of your programs or changed its name, and <tt>scons install</tt> fails with "Source <tt>oldprogname</tt> not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove <tt>RSFSRC/.sconsign*</tt>
* If during <tt>scons install</tt> you get a <tt>DBAccessError : (13, 'Permission denied')</tt> in some reproducible papers, check permissions in your <tt>$DATAPATH</tt> directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in <tt>rsf.proj</tt> and <tt>rsf.tex</tt>).
* If <tt>scons</tt> or <tt>scons install</tt> fail due to an a bug introduced in a tool you are certain you will not use, a quick workaround for the problem is already built into scons: the <tt>-k</tt> option, which means "keep going". Thus, if you use <tt>scons -k</tt> or <tt>scons -k install</tt>, SCons will not be able to build the failed component, or anything that depends on it, but it will keep going and make everything else that it can.

=Further support=
Subscribe to the [https://lists.sourceforge.net/lists/listinfo/rsf-user rsf-user mailing list].

WWHouston2018

2018-04-03T17:46:51Z

Karl: Redirected page to HoustonWW 2018 i

#REDIRECT [[HoustonWW_2018_i]]

HoustonWW 2018 i

2018-04-02T22:48:25Z

Karl:

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
The working workshop with be in Houston. The location has not been selected. Possible locations are the University of Houston or UT's Houston Research Center

* Nearby hotels

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:SEG Logo_Horizontal_SM.png|400px]]
===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

File:SEG Logo Horizontal SM.png

2018-04-02T22:44:25Z

Karl:

Conferences

2018-03-27T12:52:15Z

Karl: /* Schools, Workshops, and Working Workshops */

[[Image:Conferences.png|right|]]
In reverse chronological order.

==Schools, Workshops, and Working Workshops==
[[HoustonWW2018|SEG Working Workshop - Python and Julia for Geophysics, Houston August 8-11, 2018]]

[[HoustonWW2017|SEG Working Workshop in Houston 2017]]

[[Shanghai_2017|Madagascar School of Reproducible Computational Geophysics Shanghai 2017]]

[[Houston_2017|Madagascar School at the University of Houston 2017]]

[[SEG_3D_Seismic_Processing_Working_Workshop_Houston_2016-_Land_3D|SEG Land 3D Seismic Processing Working Workshop Houston 2016]]

[[Zurich 2016|Madagascar School on Reproducible Computational Geophysics in Zürich 2016]]

[[Vienna_2016|Workshop - Open-source Software in Applied Geosciences Vienna 2016]]

[[Qingdao_2015|Madagascar School for Advanced Users in Qingdao 2015]]

[[SEG 3D Seismic Processing Working Workshop Houston 2015- Land 3D|SEG 3D Land Seismic Processing Working Workshop Houston 2015]]

[[Harbin_2015|School in Harbin 2015]]

[[Houston_2014|Second Madagascar Working Workshop Houston 2014]]

[[Petersburg_2014|Workshop at EAGE/St. Petersburg 2014]]

[[Melbourne_2013|Workshop at ASEG 2013]]

[[Austin_2013|First Madagascar Working Workshop Austin 2013]]

[[Austin_2012|Madagascar School and Workshop on Reproducible Computational Geophysics Austin 2012]]

[[Copenhagen_2012|Workshop - Open-source E&P Software - Six Years Later Copenhagen 2012]]

[[Beijing_2011|Madagascar School of Reproducible Computational Geophysics Beijing 2011]]

[[Houston_2011|Workshop - Open Software Tools for Reproducible Computational Geophysics Houston 2011]]

[[Houston_2010|Madagascar School of Reproducible Computational Geophysics and Hands-On School Houston 2010]]

[[Salvador_2009|Madagascar School on Reproducible Computational Geophysics Salvador 2009]]

[[Delft_2009|Madagascar School on Reproducible Computational Geophysics Delft 2009]]

[[2008_Implementation_Workshop|Towards full automation and better robustness Coding Sprint Golden 2008]]

[[RSF_Austin_School_2007|Using and Extending RSF/Madagascar School Austin 2007]].

[[RSF_School_and_Workshop%2C_Vancouver_2006|Reproducible Research in Computational Geophysics School and Workshop Vancouver 2006]].

==Conference presentations==

===Lausanne 2016 (PASC)===

Two presentations about <tt>Madagascar</tt> were presented in the minisymposium on '''Open Source Software (OSS) and High Performance Computing (HPC)''' at the [http://www.pasc16.org/ Platform for Advanced Scientific Computing] conference in Lausanne, Switzerland, on June 9, 2016. See presentation slides:
* [http://reproducibility.org/wikilocal/docs/FOMEL-PASC2016.pdf Data-Parallel Processing Using Madagascar Open-Source Software Package]
* [http://reproducibility.org/wikilocal/docs/POTTER-SHRAGGE-PASC2016.pdf Leveraging the Madagascar Framework for Reproducible Large-scale Cluster and Cloud Computing]

===San Francisco 2015 (AGU)===

<tt>Madagascar</tt> was presented in the session on '''Informatics and Intelligent Systems in Reproducible Geoscience Research''' at the [http://fallmeeting.agu.org/2015/ AGU Fall Meeting] in San Francisco, California, on December 17, 2015. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-AGU-2015.pdf slides] and the [https://agu.confex.com/agu/fm15/meetingapp.cgi/Session/10540 session program].

===Stanford 2015 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Advances in Software for Computational Geosciences''' at the [http://www.siam.org/meetings/gs15/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Stanford, California, on June 30, 2015. See presentation [http://reproducibility.org/wikilocal/docs/Fomel-SIAM-Geosciences-2015.pdf slides] and the [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=21097 minisymposium program].

===New York 2013 (NYU Poly)===

<tt>Madagascar</tt> was presented at the Workshop on [http://www.reproduciblescience.org/index.php/Workshop_on_Software_Infrastructure_for_Reproducibility_in_Science_--_May_30th-31st,_2013 Software Infrastructure for Reproducibility in Science] at the Polytechnic Institute of New York University in Brooklyn, New York, on May 30, 2013. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-NYC.pdf slides].

The workshop was supported by the [http://www.sloan.org/ Alfred P. Sloan Foundation]. Juliana Freire provides the complete [http://vgc.poly.edu/~juliana/ReproducibleScience/SoftwareInfrastructure/agenda.pdf workshop program].

===Providence 2012 (ICERM)===

<tt>Madagascar</tt> was presented at the [http://icerm.brown.edu/tw12-5-rcem Reproducibility in Computational and Experimental Mathematics] Workshop at the Institute for Computational and Experimental Research in Mathematics (ICERM) in Providence, Rhode Island, on December 13, 2012.

See presentation [http://reproducibility.org/wikilocal/docs/ICERM.pptx slides], the complete [http://icerm.brown.edu/tw12-5-rcem workshop program], and Victoria Stodden's [http://wiki.stodden.net/ICERM_Reproducibility_in_Computational_and_Experimental_Mathematics:_Readings_and_References wiki page].

===Austin 2012 (SciPy)===

The Python interface to <tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2012/ Scientific Computing with Python Conference] in Austin, Texas, on July 19, 2012. See the poster by clicking on the image below
. 

[[Image:SciPy2012Poster.png|link=http://www.ahay.org/wikilocal/docs/SciPy2012Poster.pdf]]

===Cary 2011 (Interface)===
<tt>Madagascar</tt> was presented in the special session on '''Reproducible Research''' at the [http://www.interfacesymposia.org/Interface2011/ 42nd Symposium on the Interface] (Statistical, Machine Learning, and Visualization Algorithms) in Cary, North Carolina, on June 1, 2011. See the [http://www.interfacesymposia.org/Interface2011/Program.pdf symposium program].

===Long Beach 2011 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Reproducible Science and Open-Source Software in the Geosciences''' at the [http://www.siam.org/meetings/gs11/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Long Beach, California, on March 23, 2011. See presentation [http://reproducibility.org/wikilocal/docs/longbeach2011.pdf slides] and the minisymposium program: [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11822 Part 1] and [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11823 Part 2].

===Reno 2011 (SIAM CS&E)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Verifiable, Reproducible Research and Computational Science''' at the [http://www.siam.org/meetings/cse11/ SIAM Conference on Computational Science and Engineering] in Reno, Nevada, on March 4, 2011. See presentation [http://reproducibility.org/wikilocal/docs/reno2011.pdf slides].

Jarrod Millman provides a complete [http://jarrodmillman.com/events/siam2011.html session program].

===Austin 2010 (SciPy)===

<tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2010/ Python in Scientific Computing Conference] in Austin, Texas, on July 1, 2010. See presentation [http://reproducibility.org/wikilocal/docs/scipy2010.pdf slides] and [http://conference.scipy.org/scipy2010/schedule.html complete program].

===Salt Lake City 2010 (NSF Archive Workshop)===

<tt>Madagascar</tt> was presented at the [http://users.emulab.net/trac/archive10/ NSF Workshop on Archiving Experiments to Raise Scientific Standards] in Salt Lake City on May 25, 2010. See presentation [http://reproducibility.org/wikilocal/docs/slc.pdf slides] and [http://users.emulab.net/trac/archive10/wiki/WorkshopSchedule complete program].

===Düsseldorf 2008 (Berlin 6) ===

<tt>Madagascar</tt> was mentioned in the special session on '''Open Data and Reproducible Research''' at the [http://www.berlin6.org/ Berlin 6 Open Access Conference] in Düsseldorf, Germany, on November 12, 2008. See presentation [http://reproducibility.org/wikilocal/docs/Berlin-6.ppt slides].

Mark Liberman provides a complete [http://ldc.upenn.edu/myl/Berlin6Session5/Overview.html session program].

===Austin 2008 (Texas Python Unconference)===

''New Directions in Literate Programming with Madagascar'' was presented at the Second Annual Texas Python Unconference hosted by Enthought Corporation on the UT campus on October 4, 2008. See presentation [http://www.ig.utexas.edu/people/staff/tobis/MadLiter/madliter.html slides].

===Austin 2008 (Scientific Software Days)===

<tt>Madagascar</tt> was presented at the Second Annual Scientific Software Days at the University of Texas at Austin on May 15, 2008. See presentation [http://reproducibility.org/wikilocal/docs/ssd2.pdf slides] and [http://www.tacc.utexas.edu/softwareday/ complete program].

===Rio de Janeiro 2007 (SBGf)===

<tt>Madagascar</tt> and reproducible scientific computing were presented at the 2007 [http://www.sbgf.org.br Congress of the Brazilian Geophysical Society] in Rio de Janeiro. See presentation [http://reproducibility.org/wikilocal/docs/2007_SBGf_ReproducibleScientificComputingUsingMadagascar.pdf slides].

===Vancouver 2007 (AIP)===

<tt>Madagascar</tt> was presented at a minisymposium on '''Software for Inverse Problems''' at the [http://www.pims.math.ca/science/2007/07aip/ Conference on Applied Inverse Problems] in Vancouver on June 29, 2007. See presentation [http://reproducibility.org/wikilocal/docs/Fomel-AIP.ppt slides].

===Honolulu 2007 (ICASSP)===

The paper [http://reproducibility.org/wikilocal/docs/scons.pdf Reproducible computational experiments using SCons] was presented in the [http://www.icassp2007.org/Papers/PublicSessionIndex3.asp?Sessionid=1168 special session] on '''Reproducible Signal Processing Research''' at the [http://www.icassp2007.org/ International Conference on Acoustics, Speech, and Signal Processing] in Honolulu on April 18, 2007 . See presentation [http://reproducibility.org/wikilocal/docs/SCons.ppt slides].

Patrick Vandewalle provides a complete [http://lcavwww.epfl.ch/reproducible_research/ICASSP07/ session program].

===Austin 2007 (Scientific Software Day)===

<tt>Madagascar</tt> was presented at the First Annual Scientific Software Day at the University of Texas at Austin on April 2, 2007. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-SSD.ppt slides].

===New Orleans 2006 (SEG)===

These advertising posters were prepared for the SEG Annual Meeting in New Orleans. The idea by Gilles Hennenfent, implementation by Scott Rodgers.

[[Image:Poker_comp_BEG.png]] [[Image:Poker_comp_CSM.png]] [[Image:Poker_comp_UBC.png]]

===Vienna 2006 (EAGE)===

RSF/Madagascar was first presented at the EAGE Workshop [http://www.eage.org/events/index.php?evp=274&eventid=1&ActiveMenu=16&Opendivs=s2,s11,s13 Open Source E&P Software – Putting the Pieces Together] in Vienna on June 11, 2006. See presentation [http://reproducibility.org/wikilocal/docs/vienna.pdf slides].

Joe Dellinger provides a complete [http://sepwww.stanford.edu/oldsep/joe/Vienna/ workshop program with abstracts].

Main Page

2018-03-27T12:50:45Z

Karl: /* Latest News */ add 2018 working workshop

<big>'''Madagascar'''</big> is an open-source software package for multidimensional data analysis and [[Reproducibility|reproducible]] computational experiments. Its mission is to provide
* a convenient and powerful environment
* a convenient technology transfer tool
for researchers working with digital image and data processing in geophysics and related fields. Technology developed using the Madagascar project management system is transferred in the form of recorded processing histories, which become "computational recipes" to be verified, exchanged, and modified by users of the system.

== Features ==

[[Image:Crystal_Clear_app_katomic.png|left|30px|Modern]]
Madagascar is a modern package. Started in 2003 and publicly released in 2006, it was developed almost entirely from scratch. Being a relatively new package, it follows modern software engineering practices such as module encapsulation and test-driven development. A rapid development of a project of this scope (more than 1,000 main programs and more than 5,000 tests) would not be possible without standing on the shoulders of giants and learning from the 30 years of previous experience in open packages such as SEPlib and Seismic Unix. We have borrowed and reimplemented functionality and ideas from these other packages.

[[Image:Crystal_Clear_app_vcalendar.png|left|30px|Test-driven]]
Madagascar is a test-driven package. Test-driven development is not only an agile software programming practice but also a way of bringing scientific foundation to geophysical research that involves numerical experiments. Bringing reproducibility and peer review, the backbone of any real science, to the field of computational geophysics is the main motivation for Madagascar development. The package consists of two levels: low-level main programs (typically developed in the C programming language and working as data filters) and high-level processing flows (described using the Python programming language) that combine main programs and completely document data processing histories for testing and reproducibility. Experience shows that high-level programming is easily mastered even by beginning students who have no previous programming experience.

[[Image:Crystal_Clear_app_gadu.png|left|30px|Open]]
Madagascar is an open-source package. It is distributed under the standard GPL open-source license, which places no restriction on the usage and modification of the code. Moreover, access to modifying the source repository is not controlled by one organization but shared equally among different developers. This enables an open collaboration among different groups spread all over the world, in the true spirit of the open-source movement.

[[Image:Crystal_Clear_filesystem_blockdevice.png|left|30px|Simple,flexible]]
Madagascar uses a simple, flexible, and universal data format that can handle very large datasets but is not tied specifically to seismic data or data of any other particular kind. This "regularly sampled" format is borrowed from the traditional SEPlib. A universal data format allows us to share general-purpose data processing tools with scientists from other disciplines such as petroleum engineers working on large-scale reservoir simulations.

== Latest News ==
{| border="1" cellpadding="5" cellspacing="2"
| style="background-color:#ffdead;font-weight:bold;font-style:italic" | Upcoming events: 

[[HoustonWW2018|SEG Working Workshop - Python and Julia for Geophysics, Houston August 8-11, 2018]]


|}

{{#widget:Feed
|feedurl=http://ahay.org/blog/feed/
|num=7
|desc=100
|date=n
|targ=n
}}

Conferences

2018-03-27T12:44:18Z

Karl: /* Schools, Workshops, and Working Workshops */ add working workshop houston 2018

[[Image:Conferences.png|right|]]
In reverse chronological order.

==Schools, Workshops, and Working Workshops==
[[HoustonWW2018|SEG Working Workshop - Python and Julia for Geophysics, Houston 2018]]

[[HoustonWW2017|SEG Working Workshop in Houston 2017]]

[[Shanghai_2017|Madagascar School of Reproducible Computational Geophysics Shanghai 2017]]

[[Houston_2017|Madagascar School at the University of Houston 2017]]

[[SEG_3D_Seismic_Processing_Working_Workshop_Houston_2016-_Land_3D|SEG Land 3D Seismic Processing Working Workshop Houston 2016]]

[[Zurich 2016|Madagascar School on Reproducible Computational Geophysics in Zürich 2016]]

[[Vienna_2016|Workshop - Open-source Software in Applied Geosciences Vienna 2016]]

[[Qingdao_2015|Madagascar School for Advanced Users in Qingdao 2015]]

[[SEG 3D Seismic Processing Working Workshop Houston 2015- Land 3D|SEG 3D Land Seismic Processing Working Workshop Houston 2015]]

[[Harbin_2015|School in Harbin 2015]]

[[Houston_2014|Second Madagascar Working Workshop Houston 2014]]

[[Petersburg_2014|Workshop at EAGE/St. Petersburg 2014]]

[[Melbourne_2013|Workshop at ASEG 2013]]

[[Austin_2013|First Madagascar Working Workshop Austin 2013]]

[[Austin_2012|Madagascar School and Workshop on Reproducible Computational Geophysics Austin 2012]]

[[Copenhagen_2012|Workshop - Open-source E&P Software - Six Years Later Copenhagen 2012]]

[[Beijing_2011|Madagascar School of Reproducible Computational Geophysics Beijing 2011]]

[[Houston_2011|Workshop - Open Software Tools for Reproducible Computational Geophysics Houston 2011]]

[[Houston_2010|Madagascar School of Reproducible Computational Geophysics and Hands-On School Houston 2010]]

[[Salvador_2009|Madagascar School on Reproducible Computational Geophysics Salvador 2009]]

[[Delft_2009|Madagascar School on Reproducible Computational Geophysics Delft 2009]]

[[2008_Implementation_Workshop|Towards full automation and better robustness Coding Sprint Golden 2008]]

[[RSF_Austin_School_2007|Using and Extending RSF/Madagascar School Austin 2007]].

[[RSF_School_and_Workshop%2C_Vancouver_2006|Reproducible Research in Computational Geophysics School and Workshop Vancouver 2006]].

==Conference presentations==

===Lausanne 2016 (PASC)===

Two presentations about <tt>Madagascar</tt> were presented in the minisymposium on '''Open Source Software (OSS) and High Performance Computing (HPC)''' at the [http://www.pasc16.org/ Platform for Advanced Scientific Computing] conference in Lausanne, Switzerland, on June 9, 2016. See presentation slides:
* [http://reproducibility.org/wikilocal/docs/FOMEL-PASC2016.pdf Data-Parallel Processing Using Madagascar Open-Source Software Package]
* [http://reproducibility.org/wikilocal/docs/POTTER-SHRAGGE-PASC2016.pdf Leveraging the Madagascar Framework for Reproducible Large-scale Cluster and Cloud Computing]

===San Francisco 2015 (AGU)===

<tt>Madagascar</tt> was presented in the session on '''Informatics and Intelligent Systems in Reproducible Geoscience Research''' at the [http://fallmeeting.agu.org/2015/ AGU Fall Meeting] in San Francisco, California, on December 17, 2015. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-AGU-2015.pdf slides] and the [https://agu.confex.com/agu/fm15/meetingapp.cgi/Session/10540 session program].

===Stanford 2015 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Advances in Software for Computational Geosciences''' at the [http://www.siam.org/meetings/gs15/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Stanford, California, on June 30, 2015. See presentation [http://reproducibility.org/wikilocal/docs/Fomel-SIAM-Geosciences-2015.pdf slides] and the [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=21097 minisymposium program].

===New York 2013 (NYU Poly)===

<tt>Madagascar</tt> was presented at the Workshop on [http://www.reproduciblescience.org/index.php/Workshop_on_Software_Infrastructure_for_Reproducibility_in_Science_--_May_30th-31st,_2013 Software Infrastructure for Reproducibility in Science] at the Polytechnic Institute of New York University in Brooklyn, New York, on May 30, 2013. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-NYC.pdf slides].

The workshop was supported by the [http://www.sloan.org/ Alfred P. Sloan Foundation]. Juliana Freire provides the complete [http://vgc.poly.edu/~juliana/ReproducibleScience/SoftwareInfrastructure/agenda.pdf workshop program].

===Providence 2012 (ICERM)===

<tt>Madagascar</tt> was presented at the [http://icerm.brown.edu/tw12-5-rcem Reproducibility in Computational and Experimental Mathematics] Workshop at the Institute for Computational and Experimental Research in Mathematics (ICERM) in Providence, Rhode Island, on December 13, 2012.

See presentation [http://reproducibility.org/wikilocal/docs/ICERM.pptx slides], the complete [http://icerm.brown.edu/tw12-5-rcem workshop program], and Victoria Stodden's [http://wiki.stodden.net/ICERM_Reproducibility_in_Computational_and_Experimental_Mathematics:_Readings_and_References wiki page].

===Austin 2012 (SciPy)===

The Python interface to <tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2012/ Scientific Computing with Python Conference] in Austin, Texas, on July 19, 2012. See the poster by clicking on the image below
. 

[[Image:SciPy2012Poster.png|link=http://www.ahay.org/wikilocal/docs/SciPy2012Poster.pdf]]

===Cary 2011 (Interface)===
<tt>Madagascar</tt> was presented in the special session on '''Reproducible Research''' at the [http://www.interfacesymposia.org/Interface2011/ 42nd Symposium on the Interface] (Statistical, Machine Learning, and Visualization Algorithms) in Cary, North Carolina, on June 1, 2011. See the [http://www.interfacesymposia.org/Interface2011/Program.pdf symposium program].

===Long Beach 2011 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Reproducible Science and Open-Source Software in the Geosciences''' at the [http://www.siam.org/meetings/gs11/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Long Beach, California, on March 23, 2011. See presentation [http://reproducibility.org/wikilocal/docs/longbeach2011.pdf slides] and the minisymposium program: [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11822 Part 1] and [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11823 Part 2].

===Reno 2011 (SIAM CS&E)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Verifiable, Reproducible Research and Computational Science''' at the [http://www.siam.org/meetings/cse11/ SIAM Conference on Computational Science and Engineering] in Reno, Nevada, on March 4, 2011. See presentation [http://reproducibility.org/wikilocal/docs/reno2011.pdf slides].

Jarrod Millman provides a complete [http://jarrodmillman.com/events/siam2011.html session program].

===Austin 2010 (SciPy)===

<tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2010/ Python in Scientific Computing Conference] in Austin, Texas, on July 1, 2010. See presentation [http://reproducibility.org/wikilocal/docs/scipy2010.pdf slides] and [http://conference.scipy.org/scipy2010/schedule.html complete program].

===Salt Lake City 2010 (NSF Archive Workshop)===

<tt>Madagascar</tt> was presented at the [http://users.emulab.net/trac/archive10/ NSF Workshop on Archiving Experiments to Raise Scientific Standards] in Salt Lake City on May 25, 2010. See presentation [http://reproducibility.org/wikilocal/docs/slc.pdf slides] and [http://users.emulab.net/trac/archive10/wiki/WorkshopSchedule complete program].

===Düsseldorf 2008 (Berlin 6) ===

<tt>Madagascar</tt> was mentioned in the special session on '''Open Data and Reproducible Research''' at the [http://www.berlin6.org/ Berlin 6 Open Access Conference] in Düsseldorf, Germany, on November 12, 2008. See presentation [http://reproducibility.org/wikilocal/docs/Berlin-6.ppt slides].

Mark Liberman provides a complete [http://ldc.upenn.edu/myl/Berlin6Session5/Overview.html session program].

===Austin 2008 (Texas Python Unconference)===

''New Directions in Literate Programming with Madagascar'' was presented at the Second Annual Texas Python Unconference hosted by Enthought Corporation on the UT campus on October 4, 2008. See presentation [http://www.ig.utexas.edu/people/staff/tobis/MadLiter/madliter.html slides].

===Austin 2008 (Scientific Software Days)===

<tt>Madagascar</tt> was presented at the Second Annual Scientific Software Days at the University of Texas at Austin on May 15, 2008. See presentation [http://reproducibility.org/wikilocal/docs/ssd2.pdf slides] and [http://www.tacc.utexas.edu/softwareday/ complete program].

===Rio de Janeiro 2007 (SBGf)===

<tt>Madagascar</tt> and reproducible scientific computing were presented at the 2007 [http://www.sbgf.org.br Congress of the Brazilian Geophysical Society] in Rio de Janeiro. See presentation [http://reproducibility.org/wikilocal/docs/2007_SBGf_ReproducibleScientificComputingUsingMadagascar.pdf slides].

===Vancouver 2007 (AIP)===

<tt>Madagascar</tt> was presented at a minisymposium on '''Software for Inverse Problems''' at the [http://www.pims.math.ca/science/2007/07aip/ Conference on Applied Inverse Problems] in Vancouver on June 29, 2007. See presentation [http://reproducibility.org/wikilocal/docs/Fomel-AIP.ppt slides].

===Honolulu 2007 (ICASSP)===

The paper [http://reproducibility.org/wikilocal/docs/scons.pdf Reproducible computational experiments using SCons] was presented in the [http://www.icassp2007.org/Papers/PublicSessionIndex3.asp?Sessionid=1168 special session] on '''Reproducible Signal Processing Research''' at the [http://www.icassp2007.org/ International Conference on Acoustics, Speech, and Signal Processing] in Honolulu on April 18, 2007 . See presentation [http://reproducibility.org/wikilocal/docs/SCons.ppt slides].

Patrick Vandewalle provides a complete [http://lcavwww.epfl.ch/reproducible_research/ICASSP07/ session program].

===Austin 2007 (Scientific Software Day)===

<tt>Madagascar</tt> was presented at the First Annual Scientific Software Day at the University of Texas at Austin on April 2, 2007. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-SSD.ppt slides].

===New Orleans 2006 (SEG)===

These advertising posters were prepared for the SEG Annual Meeting in New Orleans. The idea by Gilles Hennenfent, implementation by Scott Rodgers.

[[Image:Poker_comp_BEG.png]] [[Image:Poker_comp_CSM.png]] [[Image:Poker_comp_UBC.png]]

===Vienna 2006 (EAGE)===

RSF/Madagascar was first presented at the EAGE Workshop [http://www.eage.org/events/index.php?evp=274&eventid=1&ActiveMenu=16&Opendivs=s2,s11,s13 Open Source E&P Software – Putting the Pieces Together] in Vienna on June 11, 2006. See presentation [http://reproducibility.org/wikilocal/docs/vienna.pdf slides].

Joe Dellinger provides a complete [http://sepwww.stanford.edu/oldsep/joe/Vienna/ workshop program with abstracts].

Conferences

2018-03-27T12:42:54Z

Karl: /* Schools, Workshops, and Working Workshops */

[[Image:Conferences.png|right|]]
In reverse chronological order.

==Schools, Workshops, and Working Workshops==
[[HoustonWW2018|SEG Working Workshop in Houston 2018]]

[[HoustonWW2017|SEG Working Workshop in Houston 2017]]

[[Shanghai_2017|Madagascar School of Reproducible Computational Geophysics Shanghai 2017]]

[[Houston_2017|Madagascar School at the University of Houston 2017]]

[[SEG_3D_Seismic_Processing_Working_Workshop_Houston_2016-_Land_3D|SEG Land 3D Seismic Processing Working Workshop Houston 2016]]

[[Zurich 2016|Madagascar School on Reproducible Computational Geophysics in Zürich 2016]]

[[Vienna_2016|Workshop - Open-source Software in Applied Geosciences Vienna 2016]]

[[Qingdao_2015|Madagascar School for Advanced Users in Qingdao 2015]]

[[SEG 3D Seismic Processing Working Workshop Houston 2015- Land 3D|SEG 3D Land Seismic Processing Working Workshop Houston 2015]]

[[Harbin_2015|School in Harbin 2015]]

[[Houston_2014|Second Madagascar Working Workshop Houston 2014]]

[[Petersburg_2014|Workshop at EAGE/St. Petersburg 2014]]

[[Melbourne_2013|Workshop at ASEG 2013]]

[[Austin_2013|First Madagascar Working Workshop Austin 2013]]

[[Austin_2012|Madagascar School and Workshop on Reproducible Computational Geophysics Austin 2012]]

[[Copenhagen_2012|Workshop - Open-source E&P Software - Six Years Later Copenhagen 2012]]

[[Beijing_2011|Madagascar School of Reproducible Computational Geophysics Beijing 2011]]

[[Houston_2011|Workshop - Open Software Tools for Reproducible Computational Geophysics Houston 2011]]

[[Houston_2010|Madagascar School of Reproducible Computational Geophysics and Hands-On School Houston 2010]]

[[Salvador_2009|Madagascar School on Reproducible Computational Geophysics Salvador 2009]]

[[Delft_2009|Madagascar School on Reproducible Computational Geophysics Delft 2009]]

[[2008_Implementation_Workshop|Towards full automation and better robustness Coding Sprint Golden 2008]]

[[RSF_Austin_School_2007|Using and Extending RSF/Madagascar School Austin 2007]].

[[RSF_School_and_Workshop%2C_Vancouver_2006|Reproducible Research in Computational Geophysics School and Workshop Vancouver 2006]].

==Conference presentations==

===Lausanne 2016 (PASC)===

Two presentations about <tt>Madagascar</tt> were presented in the minisymposium on '''Open Source Software (OSS) and High Performance Computing (HPC)''' at the [http://www.pasc16.org/ Platform for Advanced Scientific Computing] conference in Lausanne, Switzerland, on June 9, 2016. See presentation slides:
* [http://reproducibility.org/wikilocal/docs/FOMEL-PASC2016.pdf Data-Parallel Processing Using Madagascar Open-Source Software Package]
* [http://reproducibility.org/wikilocal/docs/POTTER-SHRAGGE-PASC2016.pdf Leveraging the Madagascar Framework for Reproducible Large-scale Cluster and Cloud Computing]

===San Francisco 2015 (AGU)===

<tt>Madagascar</tt> was presented in the session on '''Informatics and Intelligent Systems in Reproducible Geoscience Research''' at the [http://fallmeeting.agu.org/2015/ AGU Fall Meeting] in San Francisco, California, on December 17, 2015. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-AGU-2015.pdf slides] and the [https://agu.confex.com/agu/fm15/meetingapp.cgi/Session/10540 session program].

===Stanford 2015 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Advances in Software for Computational Geosciences''' at the [http://www.siam.org/meetings/gs15/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Stanford, California, on June 30, 2015. See presentation [http://reproducibility.org/wikilocal/docs/Fomel-SIAM-Geosciences-2015.pdf slides] and the [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=21097 minisymposium program].

===New York 2013 (NYU Poly)===

<tt>Madagascar</tt> was presented at the Workshop on [http://www.reproduciblescience.org/index.php/Workshop_on_Software_Infrastructure_for_Reproducibility_in_Science_--_May_30th-31st,_2013 Software Infrastructure for Reproducibility in Science] at the Polytechnic Institute of New York University in Brooklyn, New York, on May 30, 2013. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-NYC.pdf slides].

The workshop was supported by the [http://www.sloan.org/ Alfred P. Sloan Foundation]. Juliana Freire provides the complete [http://vgc.poly.edu/~juliana/ReproducibleScience/SoftwareInfrastructure/agenda.pdf workshop program].

===Providence 2012 (ICERM)===

<tt>Madagascar</tt> was presented at the [http://icerm.brown.edu/tw12-5-rcem Reproducibility in Computational and Experimental Mathematics] Workshop at the Institute for Computational and Experimental Research in Mathematics (ICERM) in Providence, Rhode Island, on December 13, 2012.

See presentation [http://reproducibility.org/wikilocal/docs/ICERM.pptx slides], the complete [http://icerm.brown.edu/tw12-5-rcem workshop program], and Victoria Stodden's [http://wiki.stodden.net/ICERM_Reproducibility_in_Computational_and_Experimental_Mathematics:_Readings_and_References wiki page].

===Austin 2012 (SciPy)===

The Python interface to <tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2012/ Scientific Computing with Python Conference] in Austin, Texas, on July 19, 2012. See the poster by clicking on the image below
. 

[[Image:SciPy2012Poster.png|link=http://www.ahay.org/wikilocal/docs/SciPy2012Poster.pdf]]

===Cary 2011 (Interface)===
<tt>Madagascar</tt> was presented in the special session on '''Reproducible Research''' at the [http://www.interfacesymposia.org/Interface2011/ 42nd Symposium on the Interface] (Statistical, Machine Learning, and Visualization Algorithms) in Cary, North Carolina, on June 1, 2011. See the [http://www.interfacesymposia.org/Interface2011/Program.pdf symposium program].

===Long Beach 2011 (SIAM Geosciences)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Reproducible Science and Open-Source Software in the Geosciences''' at the [http://www.siam.org/meetings/gs11/ SIAM Conference on Mathematical & Computational Issues in the Geosciences] in Long Beach, California, on March 23, 2011. See presentation [http://reproducibility.org/wikilocal/docs/longbeach2011.pdf slides] and the minisymposium program: [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11822 Part 1] and [http://meetings.siam.org/sess/dsp_programsess.cfm?SESSIONCODE=11823 Part 2].

===Reno 2011 (SIAM CS&E)===

<tt>Madagascar</tt> was presented in the minisymposium on '''Verifiable, Reproducible Research and Computational Science''' at the [http://www.siam.org/meetings/cse11/ SIAM Conference on Computational Science and Engineering] in Reno, Nevada, on March 4, 2011. See presentation [http://reproducibility.org/wikilocal/docs/reno2011.pdf slides].

Jarrod Millman provides a complete [http://jarrodmillman.com/events/siam2011.html session program].

===Austin 2010 (SciPy)===

<tt>Madagascar</tt> was presented at the [http://conference.scipy.org/scipy2010/ Python in Scientific Computing Conference] in Austin, Texas, on July 1, 2010. See presentation [http://reproducibility.org/wikilocal/docs/scipy2010.pdf slides] and [http://conference.scipy.org/scipy2010/schedule.html complete program].

===Salt Lake City 2010 (NSF Archive Workshop)===

<tt>Madagascar</tt> was presented at the [http://users.emulab.net/trac/archive10/ NSF Workshop on Archiving Experiments to Raise Scientific Standards] in Salt Lake City on May 25, 2010. See presentation [http://reproducibility.org/wikilocal/docs/slc.pdf slides] and [http://users.emulab.net/trac/archive10/wiki/WorkshopSchedule complete program].

===Düsseldorf 2008 (Berlin 6) ===

<tt>Madagascar</tt> was mentioned in the special session on '''Open Data and Reproducible Research''' at the [http://www.berlin6.org/ Berlin 6 Open Access Conference] in Düsseldorf, Germany, on November 12, 2008. See presentation [http://reproducibility.org/wikilocal/docs/Berlin-6.ppt slides].

Mark Liberman provides a complete [http://ldc.upenn.edu/myl/Berlin6Session5/Overview.html session program].

===Austin 2008 (Texas Python Unconference)===

''New Directions in Literate Programming with Madagascar'' was presented at the Second Annual Texas Python Unconference hosted by Enthought Corporation on the UT campus on October 4, 2008. See presentation [http://www.ig.utexas.edu/people/staff/tobis/MadLiter/madliter.html slides].

===Austin 2008 (Scientific Software Days)===

<tt>Madagascar</tt> was presented at the Second Annual Scientific Software Days at the University of Texas at Austin on May 15, 2008. See presentation [http://reproducibility.org/wikilocal/docs/ssd2.pdf slides] and [http://www.tacc.utexas.edu/softwareday/ complete program].

===Rio de Janeiro 2007 (SBGf)===

<tt>Madagascar</tt> and reproducible scientific computing were presented at the 2007 [http://www.sbgf.org.br Congress of the Brazilian Geophysical Society] in Rio de Janeiro. See presentation [http://reproducibility.org/wikilocal/docs/2007_SBGf_ReproducibleScientificComputingUsingMadagascar.pdf slides].

===Vancouver 2007 (AIP)===

<tt>Madagascar</tt> was presented at a minisymposium on '''Software for Inverse Problems''' at the [http://www.pims.math.ca/science/2007/07aip/ Conference on Applied Inverse Problems] in Vancouver on June 29, 2007. See presentation [http://reproducibility.org/wikilocal/docs/Fomel-AIP.ppt slides].

===Honolulu 2007 (ICASSP)===

The paper [http://reproducibility.org/wikilocal/docs/scons.pdf Reproducible computational experiments using SCons] was presented in the [http://www.icassp2007.org/Papers/PublicSessionIndex3.asp?Sessionid=1168 special session] on '''Reproducible Signal Processing Research''' at the [http://www.icassp2007.org/ International Conference on Acoustics, Speech, and Signal Processing] in Honolulu on April 18, 2007 . See presentation [http://reproducibility.org/wikilocal/docs/SCons.ppt slides].

Patrick Vandewalle provides a complete [http://lcavwww.epfl.ch/reproducible_research/ICASSP07/ session program].

===Austin 2007 (Scientific Software Day)===

<tt>Madagascar</tt> was presented at the First Annual Scientific Software Day at the University of Texas at Austin on April 2, 2007. See presentation [http://reproducibility.org/wikilocal/docs/Madagascar-SSD.ppt slides].

===New Orleans 2006 (SEG)===

These advertising posters were prepared for the SEG Annual Meeting in New Orleans. The idea by Gilles Hennenfent, implementation by Scott Rodgers.

[[Image:Poker_comp_BEG.png]] [[Image:Poker_comp_CSM.png]] [[Image:Poker_comp_UBC.png]]

===Vienna 2006 (EAGE)===

RSF/Madagascar was first presented at the EAGE Workshop [http://www.eage.org/events/index.php?evp=274&eventid=1&ActiveMenu=16&Opendivs=s2,s11,s13 Open Source E&P Software – Putting the Pieces Together] in Vienna on June 11, 2006. See presentation [http://reproducibility.org/wikilocal/docs/vienna.pdf slides].

Joe Dellinger provides a complete [http://sepwww.stanford.edu/oldsep/joe/Vienna/ workshop program with abstracts].

HoustonWW 2018 i

2018-03-22T21:15:03Z

Karl: /* Objective */ Minor grammer changes

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
The working workshop with be in Houston. The location has not been selected. Possible locations are the University of Houston or UT's Houston Research Center

* Nearby hotels

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:Seglogo.png]]

===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW 2018 i

2018-03-22T21:07:04Z

Karl: /* Supporting Organizations */ minor formatting

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with an ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
The working workshop with be in Houston. The location has not been selected. Possible locations are the University of Houston or UT's Houston Research Center

* Nearby hotels

 

==Supporting Organizations==
===Bureau of Economic Geology, University of Texas at Austin===
[[Image:Beglogo.jpg]]
===Society of Exploration Geophysicists===
[[Image:Seglogo.png]]

===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW 2018 i

2018-03-01T18:16:34Z

Karl: /* Supporting Organizations */

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with an ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
The working workshop with be in Houston. The location has not been selected. Possible locations are the University of Houston or UT's Houston Research Center

* Nearby hotels

 

==Supporting Organizations==

[[Image:Beglogo.jpg]]

[[Image:Seglogo.png]]

===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

HoustonWW 2018 i

2018-03-01T18:14:09Z

Karl: /* Objective */

==SEG Working Workshop - Python and Julia for Geophysics - August 8-11, 2018==

[[Working Workshops]] as opposed to "talking workshops" are meetings where the participants work in small teams to develop new software code or to conduct computational experiments addressing a particular problem. This workshop asks participants to create small groups to identify and address obstacles to more widespread use of Python and Julia in the geophysical community. Results will be shared in lighting talks and code repositories.

==Objective==
Python and Julia are good languages for prototyping and applying selected processing. Lack of good examples that read geophysical data, interface to legacy processing systems, and implement common algorithms are obstacles to more widespread use of these languages in the geophysical community. The objective of this working workshop is to identify and address these obstacles and promote more widespread use of the languages.

Small groups of participants will form at the working workshop to address these issues. You might work on I/O functions or a processing algorithm. You might work on interfacing to Madagascar or Seismic Unix. You might want to produce examples of importing data into machine learning systems like tensor flow. Come to the workshop with an ideas or listen to ideas presented by others. Create a small group and work on the project for three days. Share your project at the end of the workshop in a lightning talk (a five minute presentation). You're likely learn new skills, get some new ideas, and meet some new people that will help you in the future. The working workshop is open to beginners and professionals.

Participants are expected to bring laptops with the software and data they will use during the workshop. Wifi internet access will be available.

This working workshop hopes to provide a forum for geophysicist to learn, contribute, and network.

==[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Registration]==

The workshop participation is free but requires an application. Space is limited. The application deadline is August 1, 2018.
[https://docs.google.com/forms/d/e/1FAIpQLSc1W25g5phkB0HXnjiMGhBoTSfkCSctBeY_MWNN3oGK12V_uw/viewform?usp=sf_link Link to the application form]

==Draft agenda==
*Wednesday afternoon August 8, 2017 3:00-6:00 PM. Optional work session to configure your computer and install open seismic software
**Do you want help getting your computer up to speed before the working workshop? Come for informal, one-on-one assistance to:
*** Install Linux on your computer.
*** Configure Linux/OSX on your computer.
*** Install Seismic Unix on your computer
*** Install Madagascar on your computer.
*** Install Jupyter and python on your computer.
*** Install a virtual Linux system on your Windows computer that will allow you to experiment with a Linux development environment. 

*Thursday August 9, 2017 (working workshop starts)
**8:30-9:00 Coffee
**9:00-10:00 Introductions, project proposals, and team formations
**10:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams

*Friday August 10, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
**1:00-2:00 Group discussion
**2:00-5:30 Breakout into work teams
**6:00-8:00 Dinner

*Saturday August 11, 2016
**8:30-9:00 Coffee. Reform teams.
**9:00-12:00 Breakout into work teams
**12:00-1:00 Lunch (provided)
** 1:00-2:00 Finalize lightning talks
**1:00-3:00 Lighting talks

==Contact us==
If you have some ideas about working workshops, tell us about it! Send email to [mailto:seismic.working.workshop@gmail.com seismic.working.workshop@gmail.com].

==Location==
The working workshop with be in Houston. The location has not been selected. Possible locations are the University of Houston or UT's Houston Research Center

* Nearby hotels

 

==Supporting Organizations==

[[Image:Beglogo.jpg]]

[[Image:Seglogo.png]]

===SEG Wavelets===
SEG Wavelets is the University of Houston's SEG student chapter. It is devoted to promoting education in exploration geophysics. We work with professional organizations, industry professionals, University of Houston faculty, and other student organizations to bring students educational, social, and possible future employment opportunities. More details can be found on our [http://segwavelets.uh.edu/ website].

[[Image:Ricelogo.jpg|left]] [[Image:TRIP.png]] [http://www.trip.caam.rice.edu/ The Rice Inversion Project] 
Department of Computational and Applied Mathematics 
Rice University