1. Running MATLAB Scripts in Octave Installation, porting, and advanced usage of Octave. Tom Holroyd NIMH MEG Core Facility April 19, 2007

2. Outline What is Octave? Issues for users Other tools Installation Prerequisites Octave Octave-forge (the toolboxes) Running Octave Initialization, paths, editing, script files, etc.

3. Outline (cont.) Porting Matlab.m files Octave is not “bug for bug” compatible No GUI, but 3 rd party packages exist Creating.oct files – Examples Stockwell transform Octave sockets Using the NIH Biowulf cluster Resources Very active developer community

4. 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.

5. Issues for Matlab Users Licensing – Octave is free Multi-processor and cluster 64-bit systems and large memory (> 2GB) Lack of GUI support Compatibility/portability issues with other analysis packages (e.g., R) Speed (we need to convert more.m files to C++) Support, e.g., bioinformatics experts

6. 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.

7. 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

8. 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

9. 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

10. 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.

11. 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

12. Installation (cont.) Prerequisites gperf – only required for building from CVS $ rpm -q gperf gperf-3.0.1-6 gnuplot – most likely already installed

13. 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.

14. 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

15. 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.

16. 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.

17. 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

18. 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 (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>

19. 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.

20. 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

21. 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.

22. 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.

23. 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

24. 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.

25. 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 = \

26. 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)”.

27. 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.

28. 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).

29. 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.

30. 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.

31. Using the NIH Biowulf Cluster Octave vs. NFS Octave maintains a cache of.m file locations and modification times. When a file changes it is re-read. For certain NFS configurations, this can be very slow. Even with “ignore_function_time_stamp("all")” Octave still has to search the path many times. The Biowulf has a set of nodes (about 100) that maintain strict Unix semantics on /home mounts: the flag “noac” for “no attribute cache” is used. Octave is much slower on these nodes. Perhaps this is a temporary situation?

32. 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).

33. 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 -l nodes=1

34. Using Swarm (cont.) To avoid the “noac” nodes, use a wrapper like this: #! /bin/sh if mount | grep noac > /dev/null; then echo “$1 must be redone” exit fi octave -q --eval “doit($1)” Calls to the above file can be batched and run with swarm, and the undone bits run later (automation helps). More elaborate checkpointing is often used anyway.

35. 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.

36. 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

37. Scripts used in this talk can be downloaded from: http://kurage.nimh.nih.gov/tomh/octave_class/ http://kurage.nimh.nih.gov/tomh/octave_class/