Madagascar - User contributions [en]

Installation

2014-03-31T20:09:14Z

R-swindeman:

[[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. Madagascar currently attempts to support Python versions 2.2 through 2.6. Versions before 2.2 are not common, but if you experience problems and you have an earlier version you should probably upgrade.
#SCons is also required, but it is included with Madagascar and the configure scripts will attempt to install it for you if you don't have it already. Alternatively you can get it through yum with "yum install scons" in a terminal window. For more information see the [[Advanced Installation#Prerequisites|Advanced Installation]] guide.

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 and change to the top source directory (sometimes called "RSFSRC"). Next, you'll have to make some changes to your .bashrc file, so open it in you're favorite editor, e.g. <bash> vim ~/.bashrc </bash> or <bash> gedit ~/.bashrc </bash> Now simply append these lines to the bottom of the .bashrc file:<ol>
<bash>export DATAPATH=$HOME/scratch/
export EDITOR=nedit
export OMP_NUM_THREADS=2
export LATEX2HTML=$HOME/texmf/latex2html
export RSFROOT=~/madagascar
#source $HOME/Desktop/RSFSRC/env.sh
</bash>Notice that the "source" line of this file is commented out for now. After this directory is created during the install, we'll come back here to fix this. Another tweak you make elect to implement is changing the OMP_NUM_THREADS line to a number greater than 2 but less than or equal to the number of cores on your machine (2 is the max for a dual-core processor). Incrementing this environment variable will have benefits when running parallelized code. I also assume that you want Madagascar installed to a directory called "madagascar". Feel free to adjust the second to last line accordingly. To have the changes you just made to the file take effect, type <pre>bash</pre> into your terminal window. Now you're ready to run <bash>./configure --prefix=/directory/where/you/want/madagascar/installed</bash> 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 <bash>./configure API=c++,f90 --prefix=/directory/where/you/want/madagascar/installed</bash> Oftentimes after running "./configure ..." you'll see a list of things that your system may not have installed (the items that have "no" next to them). Usually they are optional, but for the best experience with Madagascar, it is strongly recommended that you install these packages using a package manager such as yum. Example syntax is used here. Just change the name from "python-devel" to whatever you might be missing.<bash>yum install python-devel</bash>After installing this dependency, rerun the .configure command above and repeat this step until you have all of the desired packages installed.</ol>
# '''Building and installing the package:''' Run <bash>make install</bash> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <bash>make; su; make install</bash> or <bash>make; sudo make install</bash> 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/.bash_profile</tt> files the line <bash>source $RSFROOT/share/madagascar/etc/env.sh</bash> where RSFROOT is the install directory you specified in the <tt>--prefix</tt> option to <tt>./configure</tt>. If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <bash>source $RSFROOT/share/madagascar/etc/env.csh</bash> 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.

==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 (or uncomment) <bash>source env.sh</bash> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <bash>source env.csh</bash>
# '''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 <bash>su; scons install </bash> or <bash>sudo scons install</bash>
===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>:

<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()
</python>

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

2014-03-31T19:52:13Z

R-swindeman:

[[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. Madagascar currently attempts to support Python versions 2.2 through 2.6. Versions before 2.2 are not common, but if you experience problems and you have an earlier version you should probably upgrade.

SCons is also required, but it is included with Madagascar and the configure scripts will attempt to install it for you if you don't have it already. Alternatively you can get it through yum with "yum install scons" in a terminal window. For more information see the [[Advanced Installation#Prerequisites|Advanced Installation]] guide.

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 and change to the top source directory (sometimes called "RSFSRC"). Next, you'll have to make some changes to your .bashrc file, so open it in you're favorite editor, e.g. <bash> vim ~/.bashrc </bash> or <bash> gedit ~/.bashrc </bash> Now simply append these lines to the bottom of the .bashrc file:<ol>
<bash>export DATAPATH=$HOME/scratch/
export EDITOR=nedit
export OMP_NUM_THREADS=2
export LATEX2HTML=$HOME/texmf/latex2html
export RSFROOT=~/madagascar
#source $HOME/Desktop/RSFSRC/env.sh
</bash>Notice that the "source" line of this file is commented out for now. After this directory is created during the install, we'll come back here to fix this. Another tweak you make elect to implement is changing the OMP_NUM_THREADS line to a number greater than 2 but less than or equal to the number of cores on your machine (2 is the max for a dual-core processor). Incrementing this environment variable will have benefits when running parallelized code. I also assume that you want Madagascar installed to a directory called "madagascar". Feel free to adjust the second to last line accordingly. To have the changes you just made to the file take effect, type <pre>bash</pre> into your terminal window. Now you're ready to run <bash>./configure --prefix=/directory/where/you/want/madagascar/installed</bash> 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 <bash>./configure API=c++,f90 --prefix=/directory/where/you/want/madagascar/installed</bash> Oftentimes after running "./configure ..." you'll see a list of things that your system may not have installed (the items that have "no" next to them). Usually they are optional, but for the best experience with Madagascar, it is strongly recommended that you install these packages using a package manager such as yum. Example syntax is used here. Just change the name from "python-devel" to whatever you might be missing.<bash>yum install python-devel</bash>After installing this dependency, rerun the .configure command above and repeat this step until you have all of the desired packages installed.</ol>
# '''Building and installing the package:''' Run <bash>make install</bash> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <bash>make; su; make install</bash> or <bash>make; sudo make install</bash> 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/.bash_profile</tt> files the line <bash>source $RSFROOT/share/madagascar/etc/env.sh</bash> where RSFROOT is the install directory you specified in the <tt>--prefix</tt> option to <tt>./configure</tt>. If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <bash>source $RSFROOT/share/madagascar/etc/env.csh</bash> 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.

==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 (or uncomment) <bash>source env.sh</bash> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <bash>source env.csh</bash>
# '''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 <bash>su; scons install </bash> or <bash>sudo scons install</bash>
===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>:

<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()
</python>

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

2014-03-31T00:29:04Z

R-swindeman:

[[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. Madagascar currently attempts to support Python versions 2.2 through 2.6. Versions before 2.2 are not common, but if you experience problems and you have an earlier version you should probably upgrade.

SCons is also required, but it is included with Madagascar and the configure scripts will attempt to install it for you if you don't have it already. Alternatively you can get it through yum with "yum install scons" in a terminal window. For more information see the [[Advanced Installation#Prerequisites|Advanced Installation]] guide.

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 and change to the top source directory (sometimes called "RSFSRC"). Next, you'll have to make some changes to your .bashrc file, so open it in you're favorite editor, e.g. <bash> vim ~/.bashrc </bash> or <bash> gedit ~/.bashrc </bash> Now simply append these lines to the bottom of the .bashrc file:
<bash>
export DATAPATH=$HOME/scratch/
export EDITOR=nedit
export OMP_NUM_THREADS=2
export LATEX2HTML=$HOME/texmf/latex2html
export RSFROOT=~/madagascar
#source $HOME/Desktop/RSFSRC/env.sh
</bash>Notice that the "source" line of this file is commented out for now. After this directory is created during the install, we'll come back here to fix this. Another tweak you make elect to implement is changing the OMP_NUM_THREADS line to a number greater than 2 but less than or equal to the number of cores on your machine (2 is the max for a dual-core processor). Incrementing this environment variable will have benefits when running parallelized code. I also assume that you want Madagascar installed to a directory called "madagascar". Feel free to adjust the second to last line accordingly. To have the changes you just made to the file take effect, type <pre>bash</pre> into your terminal window. Now you're ready to run <bash>./configure --prefix=/directory/where/you/want/madagascar/installed</bash> 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 <bash>./configure API=c++,f90 --prefix=/directory/where/you/want/madagascar/installed</bash> Oftentimes after running "./configure ..." you'll see a list of things that your system may not have installed (the items that have "no" next to them). Usually they are optional, but for the best experience with Madagascar, it is strongly recommended that you install these packages using a package manager such as yum. Example syntax is used here. Just change the name from "python-devel" to whatever you might be missing.<bash>yum install python-devel</bash>After installing this dependency, rerun the .configure command above and repeat this step until you have all of the desired packages installed.
# '''Building and installing the package:''' Run <bash>make install</bash> If you need "root" privileges for installing under <tt>$RSFROOT</tt>, you may need to run <bash>make; su; make install</bash> or <bash>make; sudo make install</bash> 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/.bash_profile</tt> files the line <bash>source $RSFROOT/share/madagascar/etc/env.sh</bash> where RSFROOT is the install directory you specified in the <tt>--prefix</tt> option to <tt>./configure</tt>. If your shell is <tt>(t)csh</tt>, add to your <tt>$HOME/.cshrc</tt> file the line <bash>source $RSFROOT/share/madagascar/etc/env.csh</bash> 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.

==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 (or uncomment) <bash>source env.sh</bash> Else, if your shell is <tt>csh</tt> or <tt>tcsh</tt>, type <bash>source env.csh</bash>
# '''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 <bash>su; scons install </bash> or <bash>sudo scons install</bash>
===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>:

<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()
</python>

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.

Download

2014-03-28T21:38:43Z

R-swindeman: /* LATEX package */

[[Image:Fotolia_2043821_XS.jpg|right|]]
You can choose to download either the latest stable release, or the current development version (frequently updated).

==Stable release==

[http://sourceforge.net/projects/rsf/files/ Download the source code distribution from Sourceforge], then unpack the directory with
<pre>gunzip < madagascar-*.tar.gz | tar xvf -</pre>
or
<pre>bunzip2 < madagascar-*.tar.bz2 | tar xvf -</pre>
The <tt>bz2</tt> file is a bit smaller, but takes longer to unpack.

Next, follow [[Installation|Installation instructions]] to install.

==Current development version==

To download the most recent Madagascar source code, you need to have a [http://subversion.apache.org/ Subversion client] (<tt>svn</tt>) installed. If you want to download it read-only, run the following command:
<pre>
svn co <nowiki>http://svn.code.sf.net/p/rsf/code/trunk</nowiki> RSFSRC
</pre>
Replace <tt>RSFSRC</tt> with the path where you want to put the Madagascar source code.
If you are a Madagascar project contributor and you want to download it in read-write mode, use
<pre>
svn co \
--username=<your_sourceforge_username> \
<nowiki>https://svn.code.sf.net/p/rsf/code/trunk</nowiki> RSFSRC
</pre>

Next, follow [[Installation|Installation instructions]] to install.

You can also [http://sourceforge.net/p/rsf/code/HEAD/tree/trunk browse the Subversion repository].

===Updating===

To update the Madagascar source code on your computer with the changes made by developers, <tt>cd</tt> to the directory where you placed the sources and run
<pre>
svn update
</pre>

===Troubleshooting===

*If, after running the <tt>svn co...</tt> command, nothing happens, no message, no return to the command line: you may be behind a proxy. This is especially likely if your computer is on a corporate Intranet. To get past a proxy, you need to tell Subversion: (1) The IP number or URL of the proxy and (2) the port that will allow <tt>svn</tt> through – most likely 80, the standard HTTP port. Open your <tt>~/.subversion/servers</tt> file in a text editor. If this file does not exist, running any <tt>svn</tt> command (even an unsuccessful one, like the one above) will automatically create the file. In the <tt>[global]</tt> section, add the following lines, with your own proxy URL and port names instead of the dummy ones below:
<pre>http-proxy-host = www-proxy.yourcompany.com
http-proxy-port = 80
</pre> Now your <tt>svn</tt> commands should work. You can find more details [http://subversion.tigris.org/faq.html#proxy in the Subversion documentation]. It would also be a good idea to set in your <tt>.bashrc</tt> or <tt>.cshrc</tt> the environment variable <tt>HTTP_PROXY</tt> to your adaptation of <pre>http://www-proxy.yourcompany.com:80</pre> so that input datasets for reproducible figures can be downloaded automatically when you need them.

*If you get a "is already a working copy for a different URL" error, this means you have an existing directory downloaded from another server. Run <tt>svn switch --relocate</tt> to switch servers.

*If you are using an old Linux distribution (e.g. RedHat 9), the version of Subversion included with your distribution may need to be updated to handle the secure URL (<nowiki>https://</nowiki>). If <tt>svn</tt> complains about an "unrecognized URL scheme" (and you've given it the correctly formatted URL), then you need to update it.

*If you are behind a firewall, you may need to set up more variables in your file <tt>~/.subversion/servers</tt> (check with your IT support for all the required variables to get past the proxy) as for example
<pre>
[global]
http-proxy-host = proxy-host-company.site.corp
http-proxy-port = 1111
http-proxy-username = Yourusernameforproxy
http-proxy-password = Yourpasswordforproxy
</pre>
It would be a good idea then to protect your file <tt>~/.subversion/servers</tt> from being read by others.

==Other packages==
There are two other packages that might be useful in conjunction with RSF:
===Reproducible figures===

Using Subversion, run
<pre>svn co http://svn.code.sf.net/p/rsf/code/figs $RSFROOT/share/madagascar/figs </pre>
This installs a wide collection of more than 5,000 reproducible figures. It may take a long time to download and more than 6 Gb of disk space.
The figures are preserved with the purpose of regression testing whenever the software or the environment change.

You can reproduce the figures (excluding those generated with proprietary data or additional software) by running <tt>scons lock</tt> in individual project directories or by going to <tt>RSFSRC</tt> and running
<pre>sfbooklist command="scons lock" book</pre>

===LaTeX package===

[[SEGTeX]] is a LaTeX package for geophysical publications. It can be used with madagascar for writing [[Reproducible Documents|reproducible papers]].