Running MATLAB Scripts in Octave

Installation, porting, and advanced usage of Octave.

Tom HolroydTom Holroyd

NIMH MEG Core FacilityNIMH MEG Core Facility

April 19, 2007April 19, 2007

Outline

What is Octave? Issues for users Other tools

Installation Prerequisites Octave Octave-forge (the toolboxes)

Running Octave Initialization, paths, editing, script files, etc.

Outline (cont.)

Porting Matlab .m files Octave is not “bug for bug” compatible No GUI, but 3rd party packages exist

Creating .oct files – Examples Stockwell transform Octave sockets

Using the NIH Biowulf cluster Resources

Very active developer community

What is Octave?

Octave is an open source implementation of the MATLAB™ scripting language, available for Linux and Windows. It is distributed under the Gnu Public License (GPL).

While many features are compatible, there are differences. This class is designed to familiarize Matlab users with the things they will need to do in order to run scripts in Octave.

Issues for Matlab UsersLicensing – Octave is freeMulti-processor and cluster64-bit systems and large memory (> 2GB)Lack of GUI supportCompatibility/portability issues with other analysis packages (e.g., R)Speed (we need to convert more .m files to C++)Support, e.g., bioinformatics experts

The License Hog

This ran for a week.

What the note doesn't say is that he was also using a license; nobody else could use Matlab for a week.

I had a user who ran a long job which failed right at the end when it needed to do a t-test and the stats toolbox was busy.

Speed

Octave is generally slower than Matlab, however C/C++ extensions can be written (.oct files)

MEX file support – Octave can execute .mex files with some limitations

No artificial limits on CPUs due to licensing

Other Tools

Gnuplot – Octave uses gnuplot as a plotting engine matplotlib/pylab – Python extensions that have

Matlab/Octave-like capability Open formats (e.g., HDF5) guarantee ease of use

with other tools

Example – Contour Plots

The time-frequency graph shown here was calculated using Octave with a C++ extension, then the data were exported to pylab for rendering in a manner similar to that used for Gnuplot.

Stockwell Transform

Example – MEG Source Localization

Power spectral estimates are used to generate maps of brain activity. Octave is used as a compute engine; we run hundreds of such datasets on the Biowulf cluster. The data are exported to AFNI for display.

Installation - Linux Prerequisites

BLAS – may already be installed, e.g.,$ rpm -q blas

blas-3.0-37.fc4 LAPACK

$ rpm -q lapack

lapack-3.0-37.fc4 ATLAS – optional faster version of the above two FFTW

$ rpm -q fftw

fftw-3.1.1-1.fc4

Installation (cont.) Prerequisites

gperf – only required for building from CVS$ rpm -q gperf

gperf-3.0.1-6 gnuplot – most likely already installed

Installation (cont.) Get Octave

http://www.gnu.org/software/octave/download.html Three versions listed: stable, testing, and development. Stable is

ancient, testing lacks features. Get the development version (currently 2.9.10). For the brave, get the latest CVS, but that changes daily.

Note: some distributions, such as Fedora, have binaries available. Installation may be as simple as:

$ yum install octave

The Fedora binary is built with ATLAS, too.

Installation (cont.)

Compile and Install Octave The usual:

$ cd /usr/local/src

$ tar -xjvf octave-2.9.10.tar.bz2

$ cd octave-2.9.10

$ ./configure

$ make

$ make install If you have an older compiler, this may help:

./configure CXXFLAGS=-fpermissive

Installation - Windows

A Windows build is available. http://www.dbateman.org/?page=octave

From here you can download an installer that contains a complete Octave system for Windows that is very easy to use. It also includes the latest plotting tools.

Octave Forge Octave Forge is a set of packages

Available at sourceforge.net:http://sourceforge.net/project/showfiles.php?group_id=2888

octave:1> pkg install statistics-1.0.0.tar.gz

octave:2> pkg list

Package Name | Version | Installation directory

-------------+---------+-----------------------

geometry | 1.0.0 | /home/tomh/octave/geometry-1.0.0

parallel | 1.0.0 | /home/tomh/octave/parallel-1.0.0

signal | 1.0.0 | /home/tomh/octave/signal-1.0.0

statistics | 1.0.0 | /home/tomh/octave/statistics-1.0.0

Some toolboxes have prerequisites, e.g., the geometry toolbox requires qhull.

Octave Forge

arpack

audio

civil

combinatorics

communications

control

econometrics

engine

fixed

general

geometry

graceplot

gsl

ident

image

informationtheory

integration

io

irsa

java

linear

macosx

mapping

miscellaneous

nan

nnet

octcdf

odepkg

optim

optiminterp

parallel

db

physicalconstants

plot

polynomial

pt_br

signal

specfun

special

splines

statistics

strings

struct

symband

symbolic

tcl

time

tsa

vrml

windows

xraylib

zenity

Running Octave$ octave

GNU Octave, version 2.9.10 (i686-pc-linux-gnu).

Copyright (C) 2007 John W. Eaton.

This is free software; see the source code for copying conditions.

There is ABSOLUTELY NO WARRANTY; not even for MERCHANTIBILITY or

FITNESS FOR A PARTICULAR PURPOSE. For details, type `warranty'.

Additional information about Octave is available at http://www.octave.org.

Please contribute if you find this software useful.

For more information, visit http://www.octave.org/help-wanted.html

Report bugs to <bug@octave.org> (but first, please read

http://www.octave.org/bugs.html to learn how to write a helpful report).

octave:1> 2 + 2

ans = 4

octave:2>

Initialization – .octaverc A sample .octaverc file:

addpath('/opt/afni/afni_src/matlab');

addpath('/home/tomh/octave-extras');

pkg load all;

crash_dumps_octave_core(0);

page_screen_output(0);

page_output_immediately(1);

warning("off", "all"); # see help warning_ids

#ignore_function_time_stamp("all");# if .m files will not change, this is faster

Invoke Octave with -f to skip all initialization files.

Editing Commands

Octave uses readline The usual arrow editing keys can be used, and in addition,

Octave will recall a previous command based on its prefix (even across sessions!):

octave:1> x = 5;

octave:2> sin(x)

ans = -0.95892

octave:3> x[uparrow] = 5 * pi;

octave:4> s[uparrow]in(x)

ans = 6.1230e-16

Script Files

Normal .m files begin with the word “function” and can contain only one function definition.

If an .m file does not begin with the word “function”, it is a script file and can contain many function definitions as well as executable statements.

1; # this trick forces the file to be a script file

function y = f1(x), y = x + 1; end;

function y = f2(x), y = x + 2; end;

f2(f1(2)) The above file can be named anything.m.

Porting .m Files

Logical And and Or Octave's operators shortcut like those in C:

if a != 1 && foo() ...

# foo() will not be called if a == 1. && is a logical op.

x = (a != 1) & (foo() == 2);

# foo() is always called. & is an element by element op. In Matlab, single & and | shortcut! In Octave they do not. This is

probably the most common problem for porting legacy Matlab code. Note that Matlab now has && and || which shortcut properly, while & and | still shortcut, but only in 'if' statements.

Porting .m Files (cont.)

The Octave interpreter has many features that the Matlab interpreter does NOT have. If you use them, your code will not run in Matlab.

Most Matlab features are available, but the syntax is sometimes different.

Use the following construct to protect such code:if (exist ('OCTAVE_VERSION'))

%% Octave ...

else

%% Matlab ...

end

Porting .m Files (cont.)

Octave allows double quotes, Matlab doesn't.s = “this is an octave-only string”;

s = 'this works in both'; Octave allows the “#” comment character.

# This is an Octave-only comment.

% This works in both Octave and Matlab. Initialization file:

.octaverc – can be in current directory or $HOME.

startup.m – Matlab only.

Strings

Octave's double quoted strings interpret backslash escapes:octave:1> a = "this\nthat"

a = this

that Single quoted strings do not:

octave:2> a = 'this\nthat'

a = this\nthat

octave:3> a(5)

ans = \

Porting .m Files (cont.) Octave allows ** and ^, Matlab only allows ^.

x = 2**8; # works in Octave but not Matlab Octave allows != and ~=, Matlab only allows ~=. Matlab always requires “...”

# Octave doesn't:

x = rand(2,

2) Octave allows “endif”, etc., Matlab does not.

if foo()

# do stuff

endif For “eig(A,B)” use “qz(A,B)”.

Porting .m Files (cont.)

Octave doesn't have dbstack, use mfilename():% get the name of the function

try

[st, i] = dbstack;

name = st(i);

catch

name = mfilename('fullpath');

end

# Or use the “OCTAVE_VERSION” trick instead of try/catch.

# Or don't use dbstack. dbstep/dbnext commands have a different syntax.

Porting .m Files (cont.)

Toolboxes Not all the Matlab toolboxes exist in Octave or Octave-forge.

However many .m files can be found on the web (e.g., dpss.m and related functions).

If you have a Matlab toolbox, e.g., stats, the functions will generally work (but are copyrighted so cannot be distributed).

Toolboxes Octave-forge provides a central location for people to

contribute code, and for people to work on it in a collaborative way. It, like Octave, is a community project, and it is freely available.

Some of the packages work well, some do not. But if you find a problem, it can be fixed.

Example: the control toolbox uses classes. Octave doesn't have classes yet. The toolbox is there, but your code may need changes.

Plotting

Octave uses gnuplot to render plots. High level commands such as “plot()” and “mesh()” are available, as well as access to all low level gnuplot features via “__gnuplot_raw__()”.

“Handle” graphics.

Using the NIH Biowulf Cluster An Octave build is available

Add /home/holroydt/data/octave/build/bin to your $PATH (the Biowulf crew will put this up in a better place if we ask).

Using the NIH Biowulf Cluster Swarm

If your task has many independent components, just run them in parallel using swarm. Create a file like:

octave -q --eval “doit(1)”

octave -q --eval “doit(2)”

octave -q --eval “doit(3)”

octave -q --eval “doit(4)”

octave -q --eval “doit(5)” Then:

swarm -f <file> -l nodes=1

Using the NIH Biowulf Cluster Multiprocessor

Octave-forge has a “parallel” package that uses socket I/O for communication.

Use the newer “octave_sockets” package and do it yourself. Data can be sent via the filesystem, but that's slow.

Resources The main Octave website:

http://www.octave.org/ The main Octave-forge website:

http://sourceforge.net/projects/octave The Octave-forge home page (has many links):

http://octave.sourceforge.net/ The Wiki (many more links):

http://wiki.octave.org/ Main documentation page:

http://www.gnu.org/software/octave/docs.html The “help” list:

help-octave@octave.org

Scripts used in this talk can be downloaded from:

http://kurage.nimh.nih.gov/tomh/octave_class/