Matmap Documentation
[Documentation home]

Installing and Starting the matmap software

Using the SGI machines at CVRTI

 There is no need to install the software. After launching matlab go to the directory /mom/u/jeroen/matmap and run the matmap script.

To launch matlab at the SGIs enter the following line
> matlab -nodesktop

In matlab type the following instructions:
>> cd /mom/u/jeroen/matmap
>> matmap

A welcome message will be displayed and you are ready to go.


Using the OSX (Macintosh G4 and G5) machines at CVRTI

Again there is no need to install the software, as the mom.cvrti.utah.edu is already mounted on the macintosh machines. Currently the most stable way of running matlab is to launch matlab on the macintosh machines themselves rather than running matlab on the SGIs and porting the graphics through X11. To run matlab on the macintosh machines, launch an X11 terminal and enter the following line:

> /Applications/MATLAB6p5p1/bin/matlab -nodesktop

This will launch Matlab on the macintosh without the annoying desktop environment, which is currently very slow. The terminal window has to be run under X11 as matlab launches its figure windows through X11.

Once matlab has started, enter the following instructions to launch the matmap software
>> cd /mom/u/jeroen/matmap
>> matmap

A welcome message will be displayed and you are ready to go.

Using the software on a stand alone machine

In case, no continuous access to the servers at CVRTI is available, the software can be copied, by copying the whole directory to a different location. Please copy all files as there are dependencies between the files in the different directories. Note that most of functions will work except the automatic documentation generation, which will look for the web server for updating the documentation pages.

Of a bigger concern is a proper implementation of the mex functions. These files may need to be recompiled for the architecture on which the system is supposed to run. Currently there are precompiled versions for LINUX, SGI, and OSX available in the directory. However these files may be incompatible with the architecture of the system on which the software is supposed to run. If that is the case, the mex files need to be recompiled. All the mex-files (pieces of C-code) reside in the directory mex and need to be compiled in this directory. The makefile supports currently settings for LINUX, SGI and OSX.

 Recompiling the MEX files
For recompiling the mex files enter the following instructions
(where directory is the directory in which the matmap tree is copied and matlabdir is the path to the matlab directory):

for LINUX
> cd directory/matmap/mex
> make linux MATLAB=matlabdir

for SGI (IRIX)
 > cd directory/matmap/mex
> make irix MATLAB=matlabdir

for OSX (macintosh)
> cd directory/matmap/mex
> make osx MATLAB=matlabdir

This will compile the graphicsio library and a modified version of the gdbm library. All libraries will be included into the mex files, so matlab will always be able to find all the code. The README file in the mex directory has more details on compiling the mex files.

Currently the files are designed to work with matlab revision 12 and 13 and will hopefully work with future versions as well.

Running the software

Once matlab has started, enter the following instructions to launch the matmap software
>> cd directory/matmap
>> matmap

A welcome message will be displayed and you are ready to go.

What does the MATMAP script do ?

The first thing after launching matlab is to run the matmap.m script in the main directory of the matmap tree. This file serves a few purposes: (1) it will add all the sub-directories to the current matlab path settings, so you can go to a different directory but still use all the functions (matlab will be able to find all the files), (2) set up some global variables the software needs (will be explained below). Furthermore, the script will display the latest messages and updates, to inform users about changes and bug fixes that have been made.

Getting bored of the welcome message ?

In case the matmap script si used in the startup.m file (if this file resides in your main matlab directory it will always be started when launching matlab), the welcome message is not always welcome. Use matmap('nomsg') to suppress the welcome message.

Restarting matmap, but wanting to keep the global ?

When the matmap script is executed, all the globals it uses are cleared and the data is lost (a clean start). In case you want to keep the globals use matmap('keepglobal').


Why globals ?

Since timeseries data can take up a large amount of memory, and Matlab does not have a way of using pointers, globals are used to store the data. Currently, there are two globals in use: TS for timeseries and GEOM for geometries. Both globals can contain multiple timeseries, or geometries. These globals are initialised as cell arrays.  A cell array is nothing more then a collection of matrices, each cell of the global can hold one matrix. In case of the TS global, each cell holds one time series. The global TS is a one dimensional array of cells filled with time series. When ever new space is needed for a time series, the TS global is expanded to hold one more cell. The different time series in the cell array can be addressed by their index in the TS array. In that sense the TS is like a block of memory in which the index numbers serve as pointers.

The globals can be accessed in the following way:
>> TS{1}
This will retrieve the timeseries at position 1 in the TS array.

When the data is a timeseries, the timeseries data itself is a structured matrix. The fields of the timeseries can now be accessed as following:
>> TS{1}.potvals
This will access the potential values of the time series stored in the first cell.


[Documentation home]