From Documentation
Jump to: navigation, search
(Created page with "{{Software |package_name=OCTAVE |package_description=Mostly compatible language with Matlab primarily intended for numerical computations |package_idnumber=28 }} <font color=red...")
 
Line 5: Line 5:
 
}}
 
}}
  
−
<font color=red>NOTICE :</font> On December 1st 2011 octave/3.4.0 will be <b>removed</b> from all sharcnet clusters since version octave/3.4.3 is now installed and contains significant performance enhancements. Also on Dec 1 the octave/3.2.4 module will no longer load by default on goblin and hound clusters.
+
<u>LOADING THE OCTAVE MODULE</u>
  
 
For best performance load the latest version of octave by doing:
 
For best performance load the latest version of octave by doing:
Line 11: Line 11:
 
<pre>
 
<pre>
 
module unload octave
 
module unload octave
−
module load octave
+
module load octave/3.4.3
 
</pre>
 
</pre>
 +
 +
Starting with version 3.6.3 its necessary to first unload the intel compiler module (or any other compiler that might be loaded) before loading the octave module.  This is done to ensure any packages that are to be downloaded and installed into user space are built with the native gcc 4.4.6 compiler:
 +
 +
<u>RUNNING OCTAVE JOBS IN THE QUEUE</u>
  
 
On SHARCNET clusters Octave should only be run via the queuing system.  Octave serial jobs bas best submitted to the serial queue on kraken assuming they use less than 1gb by doing:
 
On SHARCNET clusters Octave should only be run via the queuing system.  Octave serial jobs bas best submitted to the serial queue on kraken assuming they use less than 1gb by doing:
  
 
<pre>
 
<pre>
−
sqsub -t -r 60m -f wha -o ofile.%J octave mycode.m
+
sqsub -r 60m -f wha -o ofile.%J octave mycode.m
 
</pre>
 
</pre>
  
−
As of version 3.4.3 the sharcnet octave installation supports multithreading which based on initial testing can result in an order of magnitude speedup for octave codes that are specifically lapack and blas intensive (compared to simply using a single core in the serial queue) without making any changes to your code.  Once the optimal number of processors is determined by scaling tests submit the job to the threaded queue for example:
+
As of version 3.4.3 the sharcnet octave installation supports multi-threading which based on initial testing lapack/blas intensive octave jobs run in the threaded queue achieve an order of magnitude speedup compared to running single core jobs in the serial queue, without making any changes to your code.  Once the optimal number of processors is determined by scaling tests submit the job to the threaded queue for example:
  
 
<pre>
 
<pre>
−
sqsub -t -r 60m -n 16 -q threaded --mpp=1G -o ofile.%J time octave mycode.m
+
sqsub -r 60m -n 8 -q threaded --mpp=1G -o ofile.%J time octave mycode.m
 
</pre>
 
</pre>
  
−
<u>WORKING WITH ADDITIONAL PACKAGES</u>
+
<u>DOWNLOAD AND INSTALLING PACKAGES</u>
  
−
The "Octave Forge"[http://octave.sourceforge.net/] project provides extra packages for use with octave that can be downloaded and manually installed into your own sharcnet account.  A list of packages which can be downloaded can be found "here"[http://octave.sourceforge.net/]. Consider setting up a directory called <i>my_octave_sources</i> in your sharcnet home account for all your downloaded packages as is assumed in the following example:
+
The "Octave Forge":http://octave.sourceforge.net/ project provides extra packages for use with octave that can be downloaded into a directory such as <i>~/my_octave_sources</i> then manually installed into your own sharcnet account as will be shown in the follow example.  A current list of packages availble for download can be found "here":http://octave.sourceforge.net/packages.php however please note these are generally only compatible with the latest major release of octave.
 +
 
 +
In the event where the major version of octave on sharcnet you are using (for instance 3.4.x) is not the same as latest major version (at the time of writing 3.6.x) and there were programming api changes between the two versions that effect the package you want to use, then you probably will need to download the an older version of a package from "here":http://sourceforge.net/projects/octave/files/Octave%20Forge%20Packages/Individual%20Package%20Releases/. for it to work.
 +
 +
To help estimate the package version required as a starting point, consider the major release dates of recent which are octave-3.4.3 (10/10/11), octave-3.6.0 (01/15/12), octave-3.6.1 (02/22/12) and finally octave-3.6.2 (05/31/12).  Next consider you want to download the latest geometry package that was compatible with  octave-3.4.3 at the time of its release, then simply display all the archived versions as shown in the following stanza and pick the last available geometry release date before the next major release octave-3.6.0 (01/15/12).  To show a list of all archived geometry versions, do the following steps:
  
 
<pre>
 
<pre>
−
[jole@bul125:~] octave
+
http://octave.sourceforge.net/
 +
Click Packages on top menu menu bar
 +
Scroll down to the miscellaneous package row and click details
 +
Click (older versions) located below "Download Package"
 +
Click Octave Forge Packages
 +
Click  Individual Package Releases
 +
Please wait for the page to load ...
 +
Click "Name" at the top of first colum to sort packages alphabetically
 +
Scroll down you will find all available archived geometry packages:
 +
geometry-1.0.1.tar.gz  2011-09-27
 +
geometry-1.1.1.tar.gz  2011-10-06
 +
geometry-1.1.2.tar.gz  2011-10-09
 +
geometry-1.1.3.tar.gz  2011-10-13
 +
geometry-1.1.tar.gz    2011-10-04
 +
geometry-1.2.0.tar.gz  2011-10-22
 +
geometry-1.2.1.tar.gz  2011-11-02
 +
geometry-1.2.2.tar.gz  2011-11-04
 +
geometry-1.4.0.tar.gz  2012-01-25
 +
geometry-1.4.1.tar.gz  2012-03-24
 +
geometry-1.5.0.tar.gz  2012-06-05
 +
</pre>
 +
 
 +
Therefore you will download geometry-1.2.2.tar.gz (2011-11-04) since the next
 +
release geometry-1.4.0.tar.gz (2012-01-25) and then install it into octave
 +
3.4.3 as follows:
 +
 
 +
<pre>
 +
[roberpj@tope:~/my_octave_sources] octave
 +
GNU Octave, version 3.4.3
 +
octave:1> pkg install geometry-1.2.2.tar.gz
 +
octave:2> pkg list
 +
Package Name  | Version | Installation directory
 +
---------------+---------+-----------------------
 +
    geometry  |  1.2.2 | /home/roberpj/octave/geometry-1.2.2
 +
octave:15> pkg load geometry
 +
octave:16> pkg describe geometry
 +
---
 +
Package name:
 +
        geometry
 +
Version:
 +
        1.2.2
 +
Short description:
 +
        Library for geometric computing extending MatGeom functions. Useful to create,
 +
transform, manipulate and display geometric primitives.
 +
Status:
 +
        Loaded
 +
</pre>
 +
 
 +
Any questions regarding package version compatibility with major or minor octave release should be referred to the developers.
 +
 
 +
 
 +
<u>ADDITIONAL EXAMPLES OF PACKAGE COMMANDS</u>
 +
 
 +
For demonstration purpose linear-algebra will first be downloaded:
 +
 
 +
<pre>
 +
[roberpj@iqaluk:~] mkdir my_octave_sources
 +
[roberpj@iqaluk:~] cd my_octave_sources
 +
  wget http://downloads.sourceforge.net/octave/general-1.3.2.tar.gz
 +
  wget http://downloads.sourceforge.net/octave/linear-algebra-2.2.0.tar.gz
 +
</pre>
 +
 
 +
<pre>
 +
[myusername@orc-login1:~]octave
  
 
octave:1>  help pkg
 
octave:1>  help pkg
 
</pre>
 
</pre>
  
−
To install a package such as linear-algebra do
+
To install a package such as linear-algebra do:
  
 
<pre>
 
<pre>
 
octave:2>  cd ~/my_octave_sources
 
octave:2>  cd ~/my_octave_sources
 +
octave:3>  pkg install  general-1.3.2.tar.gz
 +
octave:4>  pkg install linear-algebra-2.2.0.tar.gz</pre>
 +
</pre>
  
−
octave:3>  pkg install linear-algebra-2.1.0.tar.gz</pre>
+
To then remove it do:
  
−
To then remove the linear-algebra do
+
pre. octave:5>  pkg uninstall linear-algebra
  
−
  octave:4>  pkg uninstall linear-algebra
+
To list all installed packages do:
  
−
To list all installed packages do
+
pre. octave:6>  pkg list
  
−
  octave:5>  pkg list
+
To add a named packages to your path:
  
−
To add a named packages to your path do
+
pre. octave:7>  pkg load name
  
−
  octave:6>  pkg load name
+
To remove a named package from your path:
  
−
To remove a named package from your path do
+
pre. octave:8>  pkg unload
  
−
  octave:8>  pkg unload
+
To list all functions provided by a package:
  
−
To list all functions provided by a package do
+
pre. octave:9>  pkg describe -verbose all
  
−
  octave:9>  pkg describe -verbose all
+
To list functions provide by extra odepkg package:
  
−
To list functions provide by extra odepkg package do
+
pre. octave:10>  pkg describe odepkg
  
−
  octave:10>  pkg describe odepkg
+
To list functions details for extra financial package:
  
−
To list functions details for extra financial package
+
pre. octave:11>  pkg describe financial -verbose
  
−
  octave:11>  pkg describe financial -verbose
+
To get documentation for a topic such as sin do:
  
−
To get documentation for a topic such as sin do
+
pre. octave:12>  doc sin
  
−
  octave:12>  doc sin
+
To get help using the doc command do:
  
−
To get help using the doc command do
+
pre. octave:13>  help doc
  
−
octave:13>  help doc
+
To get documentation for a topic such as matrix do:
  
−
To get documentation for a topic such as matrix do
+
pre. octave:14>  doc matrix
  
−
  octave:14>  doc matrix
+
To get documentation for any topic run the doc command alone:
  
−
To get documentation for any topic run the doc command alone
+
pre. octave:15>  doc
  
−
octave:15>  doc
 
  
 
<u>READING OR WRITING FILES</u>
 
<u>READING OR WRITING FILES</u>
  
−
There are two strategies for handling file "input and output"[http://www.gnu.org/software/octave/doc/interpreter/Input-and-Output.html#Input-and-Output] described in the "Octave manual"[http://www.gnu.org/software/octave/docs.html].  The following are some demonstrating the "simple file I/O"[http://www.gnu.org/software/octave/doc/interpreter/Simple-File-I_002fO.html#Simple-File-I_002fO] approach
+
There are two strategies for handling file "input and output":http://www.gnu.org/software/octave/doc/interpreter/Input-and-Output.html#Input-and-Output described in the "Octave manual":http://www.gnu.org/software/octave/docs.html.  The following are some demonstrating the "simple file I/O":http://www.gnu.org/software/octave/doc/interpreter/Simple-File-I_002fO.html#Simple-File-I_002fO approach
  
−
<pre>
+
pre. save myiofile.dat A B C
−
save myiofile.dat A B C
+
 
save ("-text", "myiofile.dat", "A", "B", "C")
 
save ("-text", "myiofile.dat", "A", "B", "C")
 
save ("-binary", "myiofile.dat", "A", "B", "C")
 
save ("-binary", "myiofile.dat", "A", "B", "C")
Line 98: Line 170:
 
load ("-text", "myiofile.dat", "A", "B", "C")
 
load ("-text", "myiofile.dat", "A", "B", "C")
 
load ("-binary", "myiofile.dat", "A", "B", "C")
 
load ("-binary", "myiofile.dat", "A", "B", "C")
−
</pre>
+
 
 
where A, B and C are a potential mix of entities such as scalars, vectors or matrices.  Note that for large files the binary format is strongly recommended to both minimize disk space and file read/write wallclock times.
 
where A, B and C are a potential mix of entities such as scalars, vectors or matrices.  Note that for large files the binary format is strongly recommended to both minimize disk space and file read/write wallclock times.
  
 
<U>A COMPLETE PACKAGE EXAMPLE</U>
 
<U>A COMPLETE PACKAGE EXAMPLE</U>
  
−
This example assumes you first create two directories in your home account one being named <i>~/my_octave_packages</i> and the other <i>~/my_octave_sources</i> then download the required three tar.gz files into the latter from here [http://octave.sourceforge.net/packages.php]
+
This example assumes you first create two directories in your home account one being named <i>~/my_octave_packages</i> and the other <i>~/my_octave_sources</i> then download the required three tar.gz files into the latter from http://octave.sourceforge.net/packages.php ...
  
 
<PRE>
 
<PRE>
Line 126: Line 198:
 
<U>MATLAB COMPATIBILITY</U>
 
<U>MATLAB COMPATIBILITY</U>
  
−
The online wiki resources "Octave Wiki"[http://wiki.octave.org/wiki.pl?MatlabOctaveCompatibility] or "Wikibook"[http://en.wikibooks.org/wiki/MATLAB_Programming/Differences_between_Octave_and_MATLAB] provide good introductory explanations of code compatibility between Octave and Matlab.
+
The online wiki resources "Octave Wiki":http://wiki.octave.org/wiki.pl?MatlabOctaveCompatibility or "Wikibook":http://en.wikibooks.org/wiki/MATLAB_Programming/Differences_between_Octave_and_MATLAB provide good introductory explanations of code compatibility between Octave and Matlab.
  
 
<u>LARGE MEMORY ARRAY ALLOCATION TESTING</u>
 
<u>LARGE MEMORY ARRAY ALLOCATION TESTING</u>

Revision as of 10:20, 20 November 2012

OCTAVE
Description: Mostly compatible language with Matlab primarily intended for numerical computations
SHARCNET Package information: see OCTAVE software page in web portal
Full list of SHARCNET supported software



LOADING THE OCTAVE MODULE

For best performance load the latest version of octave by doing: 

module unload octave
module load octave/3.4.3

Starting with version 3.6.3 its necessary to first unload the intel compiler module (or any other compiler that might be loaded) before loading the octave module. This is done to ensure any packages that are to be downloaded and installed into user space are built with the native gcc 4.4.6 compiler:

RUNNING OCTAVE JOBS IN THE QUEUE

On SHARCNET clusters Octave should only be run via the queuing system. Octave serial jobs bas best submitted to the serial queue on kraken assuming they use less than 1gb by doing: 

sqsub -r 60m -f wha -o ofile.%J octave mycode.m

As of version 3.4.3 the sharcnet octave installation supports multi-threading which based on initial testing lapack/blas intensive octave jobs run in the threaded queue achieve an order of magnitude speedup compared to running single core jobs in the serial queue, without making any changes to your code. Once the optimal number of processors is determined by scaling tests submit the job to the threaded queue for example: 

sqsub -r 60m -n 8 -q threaded --mpp=1G -o ofile.%J time octave mycode.m

DOWNLOAD AND INSTALLING PACKAGES

The "Octave Forge":http://octave.sourceforge.net/ project provides extra packages for use with octave that can be downloaded into a directory such as ~/my_octave_sources then manually installed into your own sharcnet account as will be shown in the follow example. A current list of packages availble for download can be found "here":http://octave.sourceforge.net/packages.php however please note these are generally only compatible with the latest major release of octave.

In the event where the major version of octave on sharcnet you are using (for instance 3.4.x) is not the same as latest major version (at the time of writing 3.6.x) and there were programming api changes between the two versions that effect the package you want to use, then you probably will need to download the an older version of a package from "here":http://sourceforge.net/projects/octave/files/Octave%20Forge%20Packages/Individual%20Package%20Releases/. for it to work.

To help estimate the package version required as a starting point, consider the major release dates of recent which are octave-3.4.3 (10/10/11), octave-3.6.0 (01/15/12), octave-3.6.1 (02/22/12) and finally octave-3.6.2 (05/31/12). Next consider you want to download the latest geometry package that was compatible with octave-3.4.3 at the time of its release, then simply display all the archived versions as shown in the following stanza and pick the last available geometry release date before the next major release octave-3.6.0 (01/15/12). To show a list of all archived geometry versions, do the following steps: 

http://octave.sourceforge.net/
Click Packages on top menu menu bar
Scroll down to the miscellaneous package row and click details
Click (older versions) located below "Download Package"
Click Octave Forge Packages
Click  Individual Package Releases
Please wait for the page to load ...
Click "Name" at the top of first colum to sort packages alphabetically
Scroll down you will find all available archived geometry packages:
 geometry-1.0.1.tar.gz  2011-09-27
 geometry-1.1.1.tar.gz  2011-10-06
 geometry-1.1.2.tar.gz  2011-10-09
 geometry-1.1.3.tar.gz  2011-10-13
 geometry-1.1.tar.gz    2011-10-04
 geometry-1.2.0.tar.gz  2011-10-22
 geometry-1.2.1.tar.gz  2011-11-02
 geometry-1.2.2.tar.gz  2011-11-04
 geometry-1.4.0.tar.gz  2012-01-25
 geometry-1.4.1.tar.gz  2012-03-24
 geometry-1.5.0.tar.gz  2012-06-05

Therefore you will download geometry-1.2.2.tar.gz (2011-11-04) since the next release geometry-1.4.0.tar.gz (2012-01-25) and then install it into octave 3.4.3 as follows: 

[roberpj@tope:~/my_octave_sources] octave
GNU Octave, version 3.4.3
octave:1> pkg install geometry-1.2.2.tar.gz
octave:2> pkg list
Package Name   | Version | Installation directory
---------------+---------+-----------------------
     geometry  |   1.2.2 | /home/roberpj/octave/geometry-1.2.2
octave:15> pkg load geometry
octave:16> pkg describe geometry
---
Package name:
        geometry
Version:
        1.2.2
Short description:
        Library for geometric computing extending MatGeom functions. Useful to create,
transform, manipulate and display geometric primitives.
Status:
        Loaded

Any questions regarding package version compatibility with major or minor octave release should be referred to the developers.


ADDITIONAL EXAMPLES OF PACKAGE COMMANDS

For demonstration purpose linear-algebra will first be downloaded: 

[roberpj@iqaluk:~] mkdir my_octave_sources
[roberpj@iqaluk:~] cd my_octave_sources
  wget http://downloads.sourceforge.net/octave/general-1.3.2.tar.gz
  wget http://downloads.sourceforge.net/octave/linear-algebra-2.2.0.tar.gz

[myusername@orc-login1:~]octave

octave:1>  help pkg

To install a package such as linear-algebra do: 

octave:2>  cd ~/my_octave_sources
octave:3>  pkg install  general-1.3.2.tar.gz
octave:4>  pkg install linear-algebra-2.2.0.tar.gz

</pre>

To then remove it do:

pre. octave:5> pkg uninstall linear-algebra

To list all installed packages do:

pre. octave:6> pkg list

To add a named packages to your path:

pre. octave:7> pkg load name

To remove a named package from your path:

pre. octave:8> pkg unload

To list all functions provided by a package:

pre. octave:9> pkg describe -verbose all

To list functions provide by extra odepkg package:

pre. octave:10> pkg describe odepkg

To list functions details for extra financial package:

pre. octave:11> pkg describe financial -verbose

To get documentation for a topic such as sin do:

pre. octave:12> doc sin

To get help using the doc command do:

pre. octave:13> help doc

To get documentation for a topic such as matrix do:

pre. octave:14> doc matrix

To get documentation for any topic run the doc command alone:

pre. octave:15> doc


READING OR WRITING FILES

There are two strategies for handling file "input and output":http://www.gnu.org/software/octave/doc/interpreter/Input-and-Output.html#Input-and-Output described in the "Octave manual":http://www.gnu.org/software/octave/docs.html. The following are some demonstrating the "simple file I/O":http://www.gnu.org/software/octave/doc/interpreter/Simple-File-I_002fO.html#Simple-File-I_002fO approach

pre. save myiofile.dat A B C save ("-text", "myiofile.dat", "A", "B", "C") save ("-binary", "myiofile.dat", "A", "B", "C") load myiofile.dat load ("-text", "myiofile.dat", "A", "B", "C") load ("-binary", "myiofile.dat", "A", "B", "C")

where A, B and C are a potential mix of entities such as scalars, vectors or matrices. Note that for large files the binary format is strongly recommended to both minimize disk space and file read/write wallclock times.

A COMPLETE PACKAGE EXAMPLE

This example assumes you first create two directories in your home account one being named ~/my_octave_packages and the other ~/my_octave_sources then download the required three tar.gz files into the latter from http://octave.sourceforge.net/packages.php ... 

[roberpj@orc-login1:~] module unload octave
[roberpj@orc-login1:~] module load octave
[roberpj@orc-login1:~] octave
GNU Octave, version 3.4.3
octave:1> pkg prefix ~/my_octave_packages
ans = /home/roberpj/my_octave_packages
octave:2> cd my_octave_sources
octave:3> ls
miscellaneous-1.0.11.tar.gz  optim-1.0.17.tar.gz  struct-1.0.9.tar.gz
octave:4> pkg install miscellaneous-1.0.11.tar.gz optim-1.0.17.tar.gz struct-1.0.9.tar.gz
octave:5> pkg list
Package Name   | Version | Installation directory
---------------|---------|-----------------------
miscellaneous *|  1.0.11 | /home/roberpj/my_octave_packages/miscellaneous-1.0.11
        optim *|  1.0.17 | /home/roberpj/my_octave_packages/optim-1.0.17
       struct *|   1.0.9 | /home/roberpj/my_octave_packages/struct-1.0.9


MATLAB COMPATIBILITY

The online wiki resources "Octave Wiki":http://wiki.octave.org/wiki.pl?MatlabOctaveCompatibility or "Wikibook":http://en.wikibooks.org/wiki/MATLAB_Programming/Differences_between_Octave_and_MATLAB provide good introductory explanations of code compatibility between Octave and Matlab.

LARGE MEMORY ARRAY ALLOCATION TESTING

The following command sequence should successfully run on hound or tope. Since tope is recommended for interactive use and has 32gb of memory the test will be demonstrated there: 

[mypc ~] ssh tope.sharcnet.ca

[tope ~] module load octave/3.4.0

[tope ~] octave
GNU Octave, version 3.4.0
octave:3> N=4e8; A=[1:N]; B=[2*(1:N)]; C=A+B; C(1); C(N); 3*N 
ans =  1.2000e+09

[tope ~] top
24985 roberpj   24   0 9406m 9.0g  12m S  0.0 32.6   0:34.34 octave
Retrieved from "https://sharcnet.ca/help/index.php?title=OCTAVE&oldid=4524"