From Documentation
Jump to: navigation, search
(→‎Version Selection)
 
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{Template:CCMissing}}
 
{{Software
 
{{Software
 
|package_name=OCTAVE
 
|package_name=OCTAVE
Line 9: Line 10:
 
Octave is provided on SHARCNET clusters  to allow serial or threaded jobs to be run in the queue as described below.
 
Octave is provided on SHARCNET clusters  to allow serial or threaded jobs to be run in the queue as described below.
  
−
=Version Selection=
+
==OCTAVE on the Graham national system==
  
−
To see what versions of Octave are available on sharcnet clusters consult the Availability table on the sharcnet OCTAVE web portal software page OR run the following command directly on a cluster:
+
On the Graham system the user simply needs to call the "module load" command without manually unloading conflicting packages.
  
−
<pre>module avail</pre>
+
$ module load octave/4.2.1
  
−
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 octave-forge packages that are to be downloaded and installed into user space are built with the native gcc compiler which is version 4.4.6 at the time of this writing.  Therefore to load octave/3.6.3 one would do:
+
To obtain information about the package's dependencies the "spider" action can be included in the call to "module":
  
 
<pre>
 
<pre>
−
module unload intel
+
$ module spider octave
−
module load octave/3.6.3
+
−
</pre>
+
  
−
Similarly, to load the default Octave module (currently version 3.8.1) one would do:
+
---------------------------------------------------------------------------------------------------------------------------------------------------------
 +
  octave:
 +
---------------------------------------------------------------------------------------------------------------------------------------------------------
 +
    Description:
 +
      GNU Octave is a high-level interpreted language, primarily intended for numerical computations. - Homepage: http://www.gnu.org/software/octave/
  
−
module unload intel
+
    Versions:
−
  module load octave
+
        octave/4.2.1
 +
 
 +
---------------------------------------------------------------------------------------------------------------------------------------------------------
 +
  For detailed information about a specific "octave" module (including how to load the modules) use the module's full name.
 +
  For example:
 +
 
 +
    $ module spider octave/4.2.1
 +
---------------------------------------------------------------------------------------------------------------------------------------------------------
 +
 
 +
   
 +
 
 +
[jdesjard@gra-login1 ~]$ module spider octave/4.2.1
 +
 
 +
---------------------------------------------------------------------------------------------------------------------------------------------------------
 +
  octave: octave/4.2.1
 +
---------------------------------------------------------------------------------------------------------------------------------------------------------
 +
    Description:
 +
      GNU Octave is a high-level interpreted language, primarily intended for numerical computations. - Homepage: http://www.gnu.org/software/octave/
 +
 
 +
    Properties:
 +
      Tools for development / Outils de développement
 +
 
 +
    You will need to load all module(s) on any one of the lines below before the "octave/4.2.1" module is available to load.
 +
 
 +
      nixpkgs/16.09  gcc/5.4.0
 +
      nixpkgs/16.09  intel/2016.4
 +
      nixpkgs/16.09  intel/2017.1
 +
 +
    Help:
 +
      GNU Octave is a high-level interpreted language, primarily intended for numerical computations. - Homepage: http://www.gnu.org/software/octave/
 +
</pre>
  
 
=Job Submission=
 
=Job Submission=
  
−
On SHARCNET clusters Octave should only be run via the queuing system. Octave serial jobs can be submitted to the serial queue using following sqsub command:
+
The Graham national system uses the Slurm scheduler which is different from the Torque Moab scheduler that is typical to the majority of other SHARCNET systems. In order to submit a simple "Hello World!" process to Graham the user would first need to create a submit script as follows.
  
−
<pre>sqsub -r 60m -o ofile.%J octave mycode.m</pre>
+
$ cat oct_serial.sh
 +
#!/bin/bash
 +
#SBATCH -t 0-00:01
 +
#SBATCH --mem=400
 +
octave --eval 'disp("Hello World! from Octave")'
  
−
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:
+
Then pass this submit script to "sbatch" to be entered into the queue:
  
−
<pre>sqsub -r 60m -n 8 -q threaded --mpp=1G -o  ofile.%J time octave mycode.m</pre>
+
$ sbatch --account=accountname oct_serial.sh
 +
 
 +
... where "accountname" is the name of the accounting group to submit to (e.g. def-groupname, rgg-projectname).
  
 
=Example Job=
 
=Example Job=
Line 66: Line 105:
 
sample.m arg1 arg2 arg3 etc
 
sample.m arg1 arg2 arg3 etc
 
</pre>
 
</pre>
 +
 +
 +
 +
==One the Graham national system==
 +
 +
Rather than dedicated development as it typical on some of the other SHARCNET systems the national systems have nodes that prioritize interactive jobs allocated by call to "salloc" of the Slurm scheduler.
 +
 +
To use Octave interactively on Graham you can do the following:
 +
 +
Use salloc to request a single task for one hour:
 +
 +
$ salloc --account=def-roxa88 --time=1:0:0 --ntasks=1
 +
 +
Then you will receive notification when the reservation is granted (including jobid), for
 +
example:
 +
 +
salloc: Granted job allocation 12345
 +
 +
Then use srun to start a terminal to work in on the reservation:
 +
 +
$ srun --wait 0 --pty bash
 +
 +
Once running the terminal in the allocation you can start your work with Octave by loading
 +
the module and starting the program:
 +
 +
<pre>
 +
$ module load octave
 +
$ octave
 +
octave: X11 DISPLAY environment variable not set
 +
octave: disabling GUI features
 +
GNU Octave, version 4.2.1
 +
Copyright (C) 2017 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 "x86_64-pc-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>
 +
 +
</pre>
 +
 +
... Then once you have the "octave:#>" prompt the terminal will behave like the Matlab
 +
command line.
 +
 +
Once you are finished with Octave use "quit" to exit the program, then "exit" to logout of
 +
the compute node (terminate srun), then "exit" again to terminate the allocation
 +
(relinquishing the allocate resources).
 +
 +
=Running on a visualization system=
 +
 +
Once logged in to a visualization system an instance of Octave can be launched from Applications Menu > Eduction > GNU Octave.
  
 
=General notes=
 
=General notes=
Line 76: Line 175:
 
  http://en.wikibooks.org/wiki/MATLAB_Programming/Differences_between_Octave_and_MATLAB  
 
  http://en.wikibooks.org/wiki/MATLAB_Programming/Differences_between_Octave_and_MATLAB  
 
provide good introductory explanations of code compatibility between Octave and Matlab.
 
provide good introductory explanations of code compatibility between Octave and Matlab.
 +
 +
In order to run Octave so that it interprets scripts as closely as possible to Matlab, use the --traditional flag. Taking from the above sqsub example the maximum Matlab compatible submission would be:
 +
 +
sqsub -r 60m -o ofile.%J octave --traditional mycode.m
  
 
==Reading/Writing Files==
 
==Reading/Writing Files==
Line 95: Line 198:
  
 
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.
−
 
−
==Large Memory Array Allocation==
 
−
 
−
The following command sequence should successfully run on hound or tope.  Since tope has 32gb of unlimited memory the test will be demonstrated there since it should be sufficient to run:
 
−
 
−
[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
 
−
octave:4> exit
 
  
 
==Octave-Forge==
 
==Octave-Forge==

Latest revision as of 09:34, 6 June 2019

This page is will be deleted pending it's creation on the CC wiki.
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


Introduction

Octave is provided on SHARCNET clusters to allow serial or threaded jobs to be run in the queue as described below.

OCTAVE on the Graham national system

On the Graham system the user simply needs to call the "module load" command without manually unloading conflicting packages. 

$ module load octave/4.2.1

To obtain information about the package's dependencies the "spider" action can be included in the call to "module": 

$ module spider octave

---------------------------------------------------------------------------------------------------------------------------------------------------------
  octave:
---------------------------------------------------------------------------------------------------------------------------------------------------------
    Description:
      GNU Octave is a high-level interpreted language, primarily intended for numerical computations. - Homepage: http://www.gnu.org/software/octave/

     Versions:
        octave/4.2.1

---------------------------------------------------------------------------------------------------------------------------------------------------------
  For detailed information about a specific "octave" module (including how to load the modules) use the module's full name.
  For example:

     $ module spider octave/4.2.1
---------------------------------------------------------------------------------------------------------------------------------------------------------

 

[jdesjard@gra-login1 ~]$ module spider octave/4.2.1

---------------------------------------------------------------------------------------------------------------------------------------------------------
  octave: octave/4.2.1
---------------------------------------------------------------------------------------------------------------------------------------------------------
    Description:
      GNU Octave is a high-level interpreted language, primarily intended for numerical computations. - Homepage: http://www.gnu.org/software/octave/

    Properties:
      Tools for development / Outils de développement

    You will need to load all module(s) on any one of the lines below before the "octave/4.2.1" module is available to load.

      nixpkgs/16.09  gcc/5.4.0
      nixpkgs/16.09  intel/2016.4
      nixpkgs/16.09  intel/2017.1
 
    Help:
      GNU Octave is a high-level interpreted language, primarily intended for numerical computations. - Homepage: http://www.gnu.org/software/octave/

Job Submission

The Graham national system uses the Slurm scheduler which is different from the Torque Moab scheduler that is typical to the majority of other SHARCNET systems. In order to submit a simple "Hello World!" process to Graham the user would first need to create a submit script as follows. 

$ cat oct_serial.sh 
#!/bin/bash
#SBATCH -t 0-00:01
#SBATCH --mem=400
octave --eval 'disp("Hello World! from Octave")'

Then pass this submit script to "sbatch" to be entered into the queue: 

$ sbatch --account=accountname oct_serial.sh

... where "accountname" is the name of the accounting group to submit to (e.g. def-groupname, rgg-projectname).

Example Job

This section shows howto submit a sample.m file to the serial queue that accepts command line arguments. 

[roberpj@hnd20:~/samples/octave/args] cat sample.m 
#! /bin/octave -qf
printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
    printf (" %s", arg_list{i});
endfor
printf ("\n");

To eliminate exatraneous verbosity in the output file two switches are passed: 

[roberpj@hnd20:~/samples/octave/args] sqsub -r 60m -o ofile.%J octave -qf --no-window-system sample.m arg1 arg2 arg3 etc
WARNING: no memory requirement defined; assuming 2GB per process.
submitted as jobid 6937872

The output file from the job appears as: 

[roberpj@hnd20:~/samples/octave/args] cat ofile.6937872.hnd50
sample.m arg1 arg2 arg3 etc


One the Graham national system

Rather than dedicated development as it typical on some of the other SHARCNET systems the national systems have nodes that prioritize interactive jobs allocated by call to "salloc" of the Slurm scheduler.

To use Octave interactively on Graham you can do the following:

Use salloc to request a single task for one hour: 

$ salloc --account=def-roxa88 --time=1:0:0 --ntasks=1

Then you will receive notification when the reservation is granted (including jobid), for example: 

salloc: Granted job allocation 12345

Then use srun to start a terminal to work in on the reservation: 

$ srun --wait 0 --pty bash

Once running the terminal in the allocation you can start your work with Octave by loading the module and starting the program: 

$ module load octave
$ octave
octave: X11 DISPLAY environment variable not set
octave: disabling GUI features
GNU Octave, version 4.2.1
Copyright (C) 2017 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 "x86_64-pc-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>

... Then once you have the "octave:#>" prompt the terminal will behave like the Matlab command line.

Once you are finished with Octave use "quit" to exit the program, then "exit" to logout of the compute node (terminate srun), then "exit" again to terminate the allocation (relinquishing the allocate resources).

Running on a visualization system

Once logged in to a visualization system an instance of Octave can be launched from Applications Menu > Eduction > GNU Octave.

General notes

Matlab Compatibility

The online wiki resources "Octave Wiki": 

http://wiki.octave.org/

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.

In order to run Octave so that it interprets scripts as closely as possible to Matlab, use the --traditional flag. Taking from the above sqsub example the maximum Matlab compatible submission would be: 

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

Reading/Writing Files

There are two strategies for handling file input and output described in the "Octave manual" viz ...
http://www.gnu.org/software/octave/doc/interpreter/Input-and-Output.html#Input-and-Output
http://www.gnu.org/software/octave/docs.html.

The following stanza demonstrates the "simple file I/O" approach: http://www.gnu.org/software/octave/doc/interpreter/Simple-File-I_002fO.html#Simple-File-I_002fO 

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.

Octave-Forge

Octave-forge packages are not pre-installed on SHARCNET clusters since none are available at this time for the operating system. Therefore any required packages must be downloaded, manually installed from source and then managed in local user accounts (as described below).

However 16 of approximately 95 octave-forge packages are installed on some sharcnet visualization workstations including viz1,2,3-uwaterloo, viz2-uwo, viz6-uoguelph under /usr/share/octave/packages. As a word of caution however, all package versions will likely be significantly old since they are tied to the operating system fedora /etc/redhat-release major version and hence not contain recent critical bug fixes (which could be numerical in nature). Users are therefore strongly recommended to likewise download and install the latest version similarly as would be done on the clusters.

Sharing Packages

Note that packages installed by a single sharcnet user in their home account can be shared out to other research group members or even among general SHARCNET users. To do this simply set access permissions for group or global read access accordingly. For details on how to change the permissions see: https://www.sharcnet.ca/help/index.php/Knowledge_Base#How_do_I_give_other_users_access_to_my_files_.3F

Managing 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 available for download that notable are generally only compatible with the latest major release of octave cat be found here http://octave.sourceforge.net/packages.php.

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 an older version of a package from 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

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

Package Commands

Additional examples of package commands are shown in this section. 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

To remove a package, from a terminal first do: 

cd ~/octave
rm -rf linear-algebra-2.2.0

... then from within octave do: 

octave:5>  pkg uninstall linear-algebra

To list all installed packages do: 

octave:6>  pkg list

To add a named packages to your path: 

octave:7>  pkg load name

To remove a named package from your path: 

octave:8>   pkg unload

To list all functions provided by a package: 

octave:9>  pkg describe -verbose all

To list functions provide by extra odepkg package: 

octave:10>  pkg describe odepkg

To list functions details for extra financial package: 

octave:11>  pkg describe financial -verbose

To get documentation for a topic such as sin do: 

octave:12>   doc sin

To get help using the doc command do: 

octave:13>   help doc

To get documentation for a topic such as matrix do: 

octave:14>  doc matrix

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

octave:15>  doc

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</PRE>

References

o Octave Homepage
http://www.gnu.org/software/octave/

o Octave 725 Page Manual (Version 3.4.0)
http://www.gnu.org/software/octave/doc/interpreter/

o Statistic Package Function Reference
http://octave.sourceforge.net/doc/funref_statistics.html

o GNU Octave Wiki
http://wiki.octave.org/

o Matlab-Like Tools for HPC (article)
http://www.admin-magazine.com/HPC/Articles/Matlab-Like-Tools-for-HPC

Retrieved from "https://sharcnet.ca/help/index.php?title=OCTAVE&oldid=17959"