Octave is a free Matlab workalike, available from http://octave.sourceforge.net/.

Octave has been built with Matlab compatibility in mind, however there are a few differences. For an overview of the key differences check this website.

Octave and qtoctave (an Octave GUI) are currently installed on the Power 7 Linux (see Getting Started on the Power755 Cluster). The login node is p2n14.canterbury.ac.nz.

Getting Started with Octave

To check the compatibility of your Matlab code with Octave, we recommend that you first test a very small version of your code on the login node (p2n14) that will only take a couple of minutes maximum to run. This is to insure that all the functions in your program are working with Octave as you expect with Matlab.

First in a terminal, login to the Power 7 login node:

> ssh username@p2n14.canterbury.ac.nz

Then you can call octave by simply running the following commands in the same terminal:

> module load octave
> octave
GNU Octave, version 3.8.0
Copyright (C) 2013 John W. Eaton and others.
This is free software; see the source code for copying conditions.
There is ABSOLUTELY NO WARRANTY; not even for MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  For details, type 'warranty'.
Octave was configured for "powerpc64-unknown-linux-gnu".
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/get-involved.html
Read http://www.octave.org/bugs.html to learn how to submit bug reports.
For information about changes from previous versions, type 'news'.
octave:1> 

You can run your program the same way you would with Matlab.

Alternatively you could use the Octave GUI by doing the following:

> ssh username@p2n14.canterbury.ac.nz -X

And then call the GUI

> module load octave
> qtoctave

Note that using the GUI with X forwarding might not be ideal if you have a slow internet connection. It is best to use this option while connecting from the Canterbury University campus.

Once your program works you can start full simulations on the compute node via the scheduling system Loadleveler.

(warning) Note: Using Octave as described above is only for small compatibility test purposes, to run simulations you need to submit a job via Loadeleveler.

Submitting jobs with Octave

Once you have insured that your program is fully compatible with Octave, you can submit jobs to the scheduling system Loadelever and using a more advance version of octave 3.6.4.

Serial jobs

The following script RunOctave_serial.ll is an example script that you can use and modify appropriately

# Example Serial LoadLeveler Job with Octave script
#
# @ shell              = /bin/bash
# @ job_name           = octave_job
# @ job_type           = parallel
# @ wall_clock_limit   = 00:30:00
# @ class              = p7linux
# Group and project account number 
# @ group              = UC
# Change your project account number below 
# @ account_no         = bfcs00000 
#
# @ output             = $(job_name).$(schedd_host).$(jobid).out
# @ error              = $(job_name).$(schedd_host).$(jobid).err
# @ notification       = complete
# @ notify_user        = user@email.address                     #change to your email address
# @ total_tasks        = 1                                      # In serial leave the number of tasks to 1
# @ blocking           = unlimited
# @ task_affinity      = core(8)                                # See comment below on task affinities
# @ rset               = rset_mcm_affinity
# @ mcm_affinity_options = mcm_mem_pref 
# @ environment = COPY_ALL
# @ queue
# suggested environment settings:
export MEMORY_AFFINITY=MCM  #to use the memory closest to the cpu

# All commands that follow will be run as part of my serial job
# Display name of host running serial job
hostname

# Display current time
date

# Run a serial octave program (do not include .m)
# make sure the environment is clean
module purge
# To use octave version 3.8.0
module load octave
poe octave --eval myProgram 

In this example, myProgram is the name of the Octave script you wish to run. Note that it cannot be a function with parameters (e.g myProgram(10,2,3) ), if you wish to use a function simply create a small program that contains a call to this function.

Note that you need to specify your group with # @ group = UC, from NZ, NZ_merit, UC, or UC_merit. If you are unsure of of your group, run the command line "whatgroupami" on the login node. Please see CurrentQuestions for more details.

To submit your job:

  1. Login to the login node,
  2. simply go to the directory where both RunOctave_serial.ll and your program are,
  3. enter the command line:

    > llsubmit RunOctave_serial.ll
  4. To check if your job is running or listed in the queue:

    > llq
    or alternatively to only see your own jobs
    > llq -u username

Octave uses a multi-threaded version of the ATLAS library (instead of BLAS and Lapack) and can take advantage of free parallelisation under the hood for all calculations involving matrix or vector operations. To enable more than 2 threads per core (task_affinity=core(1)) and therefore improving the speed of your code it is recommended that you check how much faster your code will be when increasing the value of core(X), e.g task_affinity=core(1), core(8), core(16), core(32). On the Power 7 you can have a maximum of 32 cores per task. If you don't see a speed-up between core(8) and core(16), keep the core option to core(8). Typically the larger the matrix sizes are in the code (over 1000 by 1000) the more octave will take advantage of using a larger amount of cores. In some cases you can see a speed-up of roughly 10 times faster when using core(8) instead of core(1).

Note that Matlab typically uses a multi-threaded version of BLAS and Lapack (MKL) and take advantage of multicores on your PC in a similar way.

 

Parallel jobs with pMatlab/MatlabMPI libraries

Several open source MPI libraries have and are being developed for Octave and Matlab. Some rely on "true" message passing interface:

Others rely on "fake" message passing interface based on file I/O and shared file system:

MatlabMPI developed by MIT is a set of Matlab scripts that implement a subset of MPI and allow any Matlab/Octave program to be run on a parallel computer. The advantages are that this is completely platform independent (no compiling is involved) and only rely on a shared file system other than the presence of Octave or Matlab.

Furtheremore MIT has also developed a Distributed Computing Library "pMatlab" that provides a user friendly interface to work with distributed numerical array specified by a map construct. pMatlab relies on MatlabMPI and abstracts the communication layer from the application layer. The user doe snot have to worry about parallel programming concepts such as deadlocks, barriers and synchronisation.

For more information about pMatlab check http://www.ll.mit.edu/mission/isr/pmatlab/pmatlab.html, and specifically for an introduction to parallel programming with pMatlab see the following documentation pMatlab_intro.pdf

The advantage of using pMatlab/MatlabMPI libraries for parallel and memory distributed computing is that it is highly compatible with Matlab and Octave.

You can download examples  from the MIT website ( http://www.ll.mit.edu/mission/isr/pmatlab/pmatlab.html) or alternatively on our Power7 system:

  1. Log in to p2n14 via a terminal or Putty:

    ssh username@p2n14.canterbury.ac.nz
  2. Copy the "Example" folder from /usr/local/pkg/pMatlab/version/Examples into your home directory or a directory of your choice.

    scp -r /usr/local/pkg/pMatlab/version/Examples .
    or
    scp -r /usr/local/pkg/pMatlab/version/Examples MY_DIRECTORY/.

Basic concepts for running pMatlab jobs on your local PC

In pMatlab, the user can issue pMatlab commands by invoking scripts or functions that contain pMatlab code.  The following script RUN.m can be executed at the command line instead of directly calling the parallel function written with pMatlab.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% pMatlab: Parallel Matlab Toolbox
% Software Engineer: Ms. Nadya Travinin (nt@ll.mit.edu)
% Architect: Dr. Jeremy Kepner (kepner@ll.mit.edu)
% MIT Lincoln Laboratory
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% RUN is a generic script for running pMatlab scripts.

% Code to run.
mFile = 'pFFT';

% Interactive runs:
%------------------------
% Define number of processors to use.
Nprocs=2;
% Define machines, empty means run locally.
machines = {};

% Run the script.
disp(['Running: ' mFile ' on ' num2str(Nprocs) ' processors']);
eval(pRUN(mFile, Nprocs, machines));

 

For example let's look at the following Fast Fourier Transform code with pMatlab.The program is called pFFT.

%%%%%%%%%%%%%%%%%%%%%%%%
% Fast Fourier Transform with pMatlab
%%%%%%%%%%%%%%%%%%%%%%%%
% To run in serial without distributed arrays, set         
%   PARALLEL = 0
% At the Matlab/Octave prompt type
%   pFFT
% To run in serial with distributed arrays, set         
%   PARALLEL = 1
% At the Matlab/Octave prompt type
%   pFFT
% To run in parallel with distributed arrays
% at the Matlab prompt type 
%   eval(pRUN('pFFT',2,{}))
%%%%%%%%%%%%%%%%%%%%%%%%

% Number of processors is Np (and is set automatically by pMatlab
% to Np=Nprocs when calling eval(pRUN('pFFT',Nprocs,machines))  )
N = 2^10; % NxN Matrix size.

% Turn parallelism on:1 or off:0.
PARALLEL = 1; % Can be 1 or 0.

% Create Maps.
mapX = 1; mapY = 1;
if (PARALLEL)
% Break up channels.
mapX = map([1 Np], {}, 0:Np-1);
mapY = map([1 Np], {}, 0:Np-1);
end

% Allocate data structures.
X = rand(N,N,mapX);
Y = zeros(N,N,mapY);
% Do fft. Changes Y from real to complex.
Y(:,:) = fft(X);

% Finalize the pMATLAB program
disp('SUCCESS');

To test your parallel program "interactively", you can start qtoctave and enter the following line in the command line:

> RUN

where Nprocs and machines are defined as follow in RUN.m:

% Interactive runs:
%------------------------
% Define number of processors to use.
Nprocs=2;
% Define machines, empty means run locally.
machines = {};

Alternatively, you can directly enter the following command line at the Octave prompt:

> eval(pRUN(pFFT, 2, {}));

This will run your pMatlab program pFFT.m with 2 processors on the login node (where Octave was started).

Submitting parallel Octave jobs (with pMatlab)  with Loadeleveler

To submit your pMatlab program on the  BlueFern power7 systems, you will have to use a Loadleveler script and  will need to specify the number or processors (cores) you wish to use in this Loadleveler script only, with the option # @ total_tasks = 10, (for 10 processors/tasks).

The following script RunOctave_parallel.ll is an example script that you can use and modify appropriately:

# Example Parallel LoadLeveler Job with Octave script
#
# @ shell              = /bin/bash
# @ job_name           = octave_job
# @ wall_clock_limit   = 02:00:00
# @ class              = p7linux
# Group and project account number 
# @ group              = UC
# Change your project account number below 
# @ account_no         = bfcs00000
#  
# @ output             = $(job_name).$(schedd_host).$(jobid).out
# @ error              = $(job_name).$(schedd_host).$(jobid).err
#
# @ notification       = complete
# change to your email address 
# @ notify_user        = user@email.address 
#
# CHANGE BELOW the number of tasks
# @ total_tasks = 10
# @ job_type           = parallel   
# @ blocking           = unlimited  

# @ task_affinity      = core(2)                   # See comment below on task affinities
# @ rset               = rset_mcm_affinity   
# @ mcm_affinity_options = mcm_mem_pref
# @ environment = COPY_ALL
# @ queue

# Specify the name of your parallel Octave job below
PARALLEL_CODE='pStream'                    # CHANGE HERE to your own Octave script (do not include .m)                       
export PARALLEL_CODE

#Display name of host running master
hostname

# Display current time
date

# make sure the environment is clean
module purge
# To use octave version 3.8.0, load the appropriate module
module load octave
# Serial preparation Step to set-up a parallel Octave job  ## Do NOT change
octave --eval Mpi_Octave_init

# Execute the parallel Octave job using the distributed pMatlab library
poe  octave --eval pMatlab_Octave_run -labelio yes -stdoutmode ordered   ## DO NOT change 
# Note that -labelio yes -stdoutmode ordered is to see the outputs from each worker and leader ordered into 1 output file 

Note that you need to specify your group with # @ group = UC, from NZ, NZ_merit, UC, or UC_merit. If you are unsure of of your group, run the  command line "whatgroupami" on the login node. Please see CurrentQuestions for more details.

Octave uses a multi-threaded version of the ATLAS library (instead of BLAS and Lapack) and can take advantage of free parallelisation under the hood for all calculations involving matrix or vector operations. To enable more than 2 threads per core (task_affinity=core(1)) and therefore improving the speed of your code it is recommended that you check how much faster your code will be when increasing the value of core(X), e.g task_affinity=core(1), core(8), core(16), core(32). On the Power 7 you can have a maximum of 32 cores per task. If you don't see a speed-up between core(8) and core(16), keep the core option to core(8). Typically the larger the matrix sizes are in the code (over 1000 by 1000) the more octave will take advantage of using a larger amount of cores. In some cases you can see a speed-up of roughly 10 times faster when using core(8) instead of core(1).

Note that Matlab typically uses a multi-threaded version of BLAS and Lapack (MKL) and take advantage of multicores on your PC in a similar way.

To submit your parallel Octave job:

  1. Login to the login node,
  2. simply go to the directory where both RunOctave_parallel.ll and your program are,
  3. enter the command line:

    > llsubmit RunOctave_parallel.ll
  4. To check if your job is running or listed in the queue:

    > llq
    or alternatively to only see your own jobs
    > llq -u username

Submitting parallel Octave jobs (with MatlabMPI)  with Loadeleveler

To submit your MatlabMPI program on the  BlueFern power7 systems, you will have to use a Loadleveler script and  will need to specify the number or processors (cores) you wish to use in this Loadleveler script only, with the option # @ total_tasks = 10, (for 10 processors/tasks).

The following script RunOctave_parallel.ll is an example script that you can use and modify appropriately:

# Example Parallel LoadLeveler Job with Octave script
#
# @ shell              = /bin/bash
# @ job_name           = octave_job
# @ wall_clock_limit   = 02:00:00
# @ class              = p7linux
# Group and project account number 
# @ group              = UC
# Change your project account number below 
# @ account_no         = bfcs00000
#  
# @ output             = $(job_name).$(schedd_host).$(jobid).out
# @ error              = $(job_name).$(schedd_host).$(jobid).err
#
# @ notification       = complete
# change to your email address 
# @ notify_user        = user@email.address 
#
# CHANGE BELOW the number of tasks
# @ total_tasks = 10
# @ job_type           = parallel   
# @ blocking           = unlimited  

# @ task_affinity      = core(2)                   # See comment below on task affinities
# @ rset               = rset_mcm_affinity   
# @ mcm_affinity_options = mcm_mem_pref
# @ environment = COPY_ALL
# @ queue

# Specify the name of your parallel Octave job below
PARALLEL_CODE='basic_app'                    # CHANGE HERE to your own Octave MatlabMPI script (do not include .m)                       
export PARALLEL_CODE

#Display name of host running master
hostname

# Display current time
date

# make sure the environment is clean
module purge
# To use octave version 3.8.0, load the appropriate module
module load octave
# Serial preparation Step to set-up a parallel Octave job  ## Do NOT change
octave --eval Mpi_Octave_init

# Execute the parallel Octave job using the MPI MatlabMPI library
poe  octave --eval Mpi_Octave_run -labelio yes -stdoutmode ordered   ## DO NOT change 
# Note that -labelio yes -stdoutmode ordered is to see the outputs from each worker and leader ordered into 1 output file 

Note that you need to specify your group with # @ group = UC, from NZ, NZ_merit, UC, or UC_merit. If you are unsure of of your group, run the  command line "whatgroupami" on the login node. Please see CurrentQuestions for more details.

Octave uses a multi-threaded version of the ATLAS library (instead of BLAS and Lapack) and can take advantage of free parallelisation under the hood for all calculations involving matrix or vector operations. To enable more than 2 threads per core (task_affinity=core(1)) and therefore improving the speed of your code it is recommended that you check how much faster your code will be when increasing the value of core(X), e.g task_affinity=core(1), core(8), core(16), core(32). On the Power 7 you can have a maximum of 32 cores per task. If you don't see a speed-up between core(8) and core(16), keep the core option to core(8). Typically the larger the matrix sizes are in the code (over 1000 by 1000) the more octave will take advantage of using a larger amount of cores. In some cases you can see a speed-up of roughly 10 times faster when using core(8) instead of core(1).

Note that Matlab typically uses a multi-threaded version of BLAS and Lapack (MKL) and take advantage of multicores on your PC in a similar way.

To submit your parallel Octave job:

  1. Login to the login node,
  2. simply go to the directory where both RunOctave_parallel.ll and your program are,
  3. enter the command line:

    > llsubmit RunOctave_parallel.ll
  4. To check if your job is running or listed in the queue:

    > llq
    or alternatively to only see your own jobs
    > llq -u username

Octave versus Matlab and key differences on the Power 7

As highlighted previously, Octave is a free Matlab workalike, available from http://octave.sourceforge.net/.

Octave has been built with Matlab compatibility in mind, however there are a few differences. For an overview of the key differences check out http://en.wikibooks.org/wiki/MATLAB_Programming/Differences_between_Octave_and_MATLAB.

Below are some key differences to keep in mind when working with Octave on the Power 7.

Reading and Saving .mat files and compatibility with Matlab and Octave

If you run simulations with Octave and save the results in a .mat file you might also want to read and load the same file with Matlab on your PC for post-processing. Alternatively, you may have input data created with Maltab that you wish to read on the Power 7 with Octave. Let's assume that we want to create  "data.mat" that contains 2 matrices A and B.

From Maltab to Octave

There is no specific options that need to be added when saving or reading the .mat file: Octave will be able to read data.m saved by Matlab on a different architecture.

% In Matlab
% Create some random matrices
A = rand(3,3);
B = rand(3,3);
 
% Save A and B in data.mat
% From Matlab: no specific options required to read in Octave
save('data.mat', 'A', 'B');
% In Octave
% Reading data.mat (which was saved with Matlab)
load('data.mat')

From Octave to Matlab

In order to read a .mat file with Matlab that was saved with Octave you DO need to specify a particular set of format options: use "Matlab's v7 binary data format" when saving the .mat file (note that you could also use format 4 and 6 instead of 7.)

% In Octave
% Create some random matrices
A = rand(3,3);
B = rand(3,3);
 
% Save A and B in data.mat
% From Octave: use '-7' to read in Matlab 
save('-7','data.mat', 'A', 'B');
% In Matlab
% Reading data.mat (which was saved with Octave)
load('data.mat')

Plotting and saving figures with Octave

When running simulations with Octave on the Power 7, it is strongly recommended to save your data in ".mat" format and plotting figures at a later post-processing stage. Octave uses gnuplot for plotting figures and does not recognise the ".fig" Matlab  format. Furthermore, you can only save figures with specific image formats with Octave, e.g eps or jpeg format. The following highlight the syntax difference when saving figures:

% Plotting a figure (same syntax for Octave and Matlab)
figure(1)
plot(x,y);
xlabel('x');
ylabel('y');
title('My plot');
 
% Saving a figure
 
% Matlab syntax
saveas(1,'my_fig1.fig');
 
% Octave syntax
print(1,'my_fig1.eps','-depsc2');
 

 

ODE solvers in Octave and Matlab

ODE functions are the strongest key differences between Octave and Matlab. The syntax as well as the order of the input parameters are different. See the example below:

 

Octave uses "lsode"
[x_sol,t]=lsode("my_ode_function_Octave",[x0;y0;z0; u0;v0;w0], time_vector);
 
([x0;y0;z0; u0;v0;w0] = initial values) 
 
Matlab uses "ode23" (or ode45)
[t,x_sol]=ode23(@my_ode_function_Matlab,[0 final_time],[x0;y0;z0; u0;v0;w0]);
 
The 2 ode functions will have different ordering:
function z=my_ode_function_Octave(x,t)
function z=my_ode_function_Matlab(t,x)