Preface
*******

This is a list of frequently asked questions (FAQ) for Octave users.

I'm looking for new questions (with answers), better answers, or both.  Please send suggestions to bug@octave.org.  If you have general questions about Octave, or need help for something that is not covered by the Octave manual or the FAQ, please use the help@octave.org mailing list.

This FAQ is intended to supplement, not replace, the Octave manual. Before posting a question to the help-octave mailing list, you should first check to see if the topic is covered in the manual.

What is Octave?
***************

Octave is a high-level interactive language, primarily intended for numerical computations that is mostly compatible with MATLAB. (MATLAB is a registered trademark of The MathWorks, Inc.)

Octave can do arithmetic for real, complex or integer-valued scalars and matrices, solve sets of nonlinear algebraic equations, integrate functions over finite and infinite intervals, and integrate systems of ordinary differential and differential-algebraic equations.

Octave uses the GNU readline library to handle reading and editing input.  By default, the line editing commands are similar to the cursor movement commands used by GNU Emacs, and a vi-style line editing interface is also available.  At the end of each session, the command history is saved, so that commands entered during previous sessions are not lost.

The Octave distribution includes a 200+ page Texinfo manual.  Access to the complete text of the manual is available via the help command at the Octave prompt.

Who develops Octave?
====================

Development started in about 1988 with James B. Rawlings of the (U of Wisconsin-Madison) and John G. Ekerdt (U. of Texas) and has been going full-time since 1992 with John W. Eaton. The community of user/developers has in addition contributed some code and fuels the discussion on the mailing lists help@octave.org (for help), bug@octave.org (for bugs), octave-dev@lists.sourceforge.net (for a repository of user-contributed functions).

What version should I use?
==========================

There have been dozens of releases, the current recommended version being 2.9.5, as of 2006/04/30. In general, you will find the latest version on http://www.gnu.org/software/octave/download.html.

On what platforms does Octave run?
==================================

Octave runs on various Unices - at least Linux and Solaris, Mac OS X, Windows and anything you can compile it on. Binary distributions exist at least for Debian, Suse, Fedora and RedHat Linuxes (Intel and AMD CPUs, at least), for Mac Os X and Windows' 98, 2000 and XP.

Two and three dimensional plotting is fully supported using gnuplot.

The underlying numerical solvers are currently standard Fortran ones like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library of C++ classes.  If possible, the Fortran subroutines are compiled with the system's Fortran compiler, and called directly from the C++ functions.  If that's not possible, you can still compile Octave if you have the free Fortran to C translator f2c.

Octave is also free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

How can I cite Octave?
**********************

Pointing to http://www.octave.org is good, because that gives people a direct way to find out more.  If citation of a URL is not allowed by a publisher, or if you also want to point to a traditional reference, then you can cite the Octave manual:

       @BOOK{eaton:2002,
         author =     "John W. Eaton",
         title =      "GNU Octave Manual",
         publisher =  "Network Theory Limited",
         year =       "2002",
         isbn =       "0-9541617-2-6"
       }

What's new in version series 2.9.N of Octave
********************************************

The 2.9.N series, started in March 2005, have enough new features to justify a major version number change. Version 2.9.5 is nearly as stable as the latest 2.1.N releases and stability should increase as one gets near version 3.0.

Series 2.9.N brings

  * integer types

  * fixed point arithmetic

  * sparse matrices

Here are some features that have been around since 2.1.NN

  * NDarrays

  * cells

What features are unique to Octave?
***********************************

This section refers to Matlab 6,5.0 R 13 and Octave 2.9.5.

Functions defined on the command-line
=====================================

Functions can be defined by entering code on the command line, a feature not supported by the other leading brand. For example, you may type:

     octave:1> function s = hello_string (to_who)
     > ## Say hello
     > if nargin<1, to_who = "World"; end
     > s = ["Hello ",\
     >      to_who];
     > endfunction
     octave:2> hello_string ("Moon")
     ans = Hello Moon

Comments with #
===============

The pound character, '#', may be used to start comments, in addition to '%'. See the previous example.

Strings delimitted by double quotes "
=====================================

The double-quote, '"', may be used to delimit strings, in addition to the single quote ``'''. See the previous example.

Line continuation by backslash
==============================

Lines can be continued with a backslash, '\', in addition to three points '...'. See the previous example.

Informative block closing
=========================

You may close ``function'', ``for'', ``while'', ``if'' ... blocks with ``endfunction'', ``endfor'', ``endwhile'' ... Also, by default, M-files may end with 'end' without eliciting a warning.

Empty argument lists
====================

Parameter-less function calls may be made more readable by writing an empty argument list.

     octave:1> rand()
     ans = 0.76213

Coherent syntax
===============

Indexing other things than variables is possible, as in:

     octave:1> [3 1 4 1 5 9](3)
     ans = 4
     octave:2> cos([0 pi pi/4 7])(3)
     ans = 0.70711

Exclamation mark as not operator
================================

The exclamation mark '!' (aka ``Bang!'') is a negation operator, just like the tilde '~':

     octave:1> if ! strcmp (program_name, "octave"),
     >   "It's an error"
     > else
     >   "It works!"
     > end
     ans = It works!

Increment and decrement operators
=================================

If you like the '++', '+=' etc operators, rejoice! Octave includes the C-like increment and decrement operators ++ and -- in both their prefix and postfix forms, in addition to +=, -=, *=, /=, ^=, .*=, ./=, and .^=.

For example, to pre-increment the variable X, you would write ++X.  This would add one to X and then return the new value of X as the result of the expression.  It is exactly the same as the expression X = X + 1.

To post-increment a variable X, you would write X++. This adds one to the variable X, but returns the value that X had prior to incrementing it.  For example, if X is equal to 2, the result of the expression X++ is 2, and the new value of X is 3.

For matrix and vector arguments, the increment and decrement operators work on each element of the operand.

Unwind-protect
==============

Octave supports a limited form of exception handling modelled after the unwind-protect form of Lisp.  The general form of an unwind_protect block looks like this:

     unwind_protect
       BODY
     unwind_protect_cleanup
       CLEANUP
     end_unwind_protect

Where BODY and CLEANUP are both optional and may contain any Octave expressions or commands.  The statements in CLEANUP are guaranteed to be executed regardless of how control exits BODY.

The unwind_protect statement is often used to reliably restore the values of global variables that need to be temporarily changed.

Built-in ODE and DAE solvers
============================

Octave includes LSODE and DASSL for solving systems of stiff ordinary differential and differential-algebraic equations.  These functions are built in to the interpreter.

What documentation exists for Octave?
*************************************

The Octave distribution includes a 375+ page manual that is also distributed under the terms of the GNU GPL. It is available on the web at http://www.gnu.org/software/octave/docs.html and you will also find there instructions on how to order a paper version.

The complete text of the Octave manual is also available using the GNU Info system via the GNU Emacs, info, or xinfo programs, or by using the help -i command to start the GNU info browser directly from the Octave prompt.

If you have problems using this documentation, or find that some topic is not adequately explained, indexed, or cross-referenced, please send a bug report to bug@octave.org.

Getting additional help
=======================

If you can't find an answer to your question, the mailing list

     help@octave.org

is available for questions related to using, installing, and porting Octave that are not adequately answered by the Octave manual or by this document.

User community
==============

If you would like to join the discussion and receive all messages sent to the list, please send a short note to

     help-request@octave.org
          ^^^^^^^

Please do not send requests to be added or removed from the the mailing list, or other administrative trivia to the list itself.

An archive of old postings to the help-octave mailing list is maintained on http://www.gnu.org/software/octave/archive.html.

You will also find some user advice and code spread over the web. Good starting points are the Octave Wiki http://wiki.octave.org and Octave-Forge htt://octave.sourceforge.net

I think I have found a bug in Octave.
=====================================

``I think I have found a bug in Octave, but I'm not sure.  How do I know, and who should I tell?''

First, see the section on bugs and bug reports in the Octave manual. When you report a bug, make sure to describe the type of computer you are using, the version of the operating system it is running, and the version of Octave that you are using.  Also provide enough code so that the Octave maintainers can duplicate your bug.

If you have Octave working at all, the easiest way to do this is to use the Octave function bug_report.  When you execute this function, Octave will prompt you for a subject and then invoke the editor on a file that already contains all the configuration information.  When you exit the editor, Octave will mail the bug report for you.

If for some reason you cannot use Octave's bug_report function, mail your bug report to "bug@octave.org".  Your message needs to include enough information to allow the maintainers of Octave to fix the bug.  Please read the section on bugs and bug reports in the Octave manual for a list of things that should be included in every bug report.

Getting Octave
**************

Source code
===========

Source code is available on the Octave development site, where you are sure to get the latest version.

  * http://www.gnu.org/software/octave/download.html

  * ftp://ftp.octave.org/pub/octave/

Since Octave is distrubted under the terms of the GPL, you can get Octave from a friend who has a copy, by anonymous FTP, or by ordering a tape or CD-ROM from the Free Software Foundation (FSF).

Pre-compiled binary packages
============================

The Octave project does not ship binary packages, but other projects do. For an up-to-date listing of packagers, see:

  * http://www.gnu.org/software/octave/download.html

  * http://wiki.octave.org/wiki.pl?CategoryInstall

As of today, Octave binaries are available at least on Debian, RedHat, Suse and Fedora Linuxes, Mac OS X, Windows' 98, 2000 and XP.

How do I get a copy of Octave for (some other platform)?
========================================================

Octave currently runs on Unix-like systems, OS/2, and Windows NT/95 (using the Cygwin tools from Red Hat).  It should be possible to make Octave work on other systems as well.  If you are interested in porting Octave to other systems, please contact bug@octave.org.

Why is Octave ``GNU Octave''?
*****************************

Octave was not developed by the FSF, but the FSF does distribute Octave, and the developers of Octave support the efforts of the FSF by encouraging users of Octave to order Octave on CD-ROM directly from the FSF.

The FSF is a nonprofit organization that distributes software and manuals to raise funds for more GNU development.  Buying a CD-ROM from the FSF contributes directly to paying staff to develop GNU software. CD-ROMs cost $240 if an organization is buying, or $60 if an individual is buying.

For more information about ordering from the FSF, contact gnu@gnu.org, phone (617) 542-5942 or anonymous ftp the file /pub/gnu/GNUinfo/ORDERS from ftp.gnu.org.

If you are on the Internet, you can copy the latest distribution version of Octave from the file /pub/octave/octave-M.N.tar.gz, on the host ftp.che.wisc.edu.  This tar file has been compressed with GNU gzip, so be sure to use binary mode for the transfer.  M and N stand for version numbers; look at a listing of the directory through ftp to see what version is available.  After you unpack the distribution, be sure to look at the files README and INSTALL.

Binaries for several popular systems are also available.  If you would like help out by making binaries available for other systems, please contact bug@octave.org.

A list of user-visible changes since the last release is available in the file NEWS.  The file ChangeLog in the source distribution contains a more detailed record of changes made since the last release.

Installation Issues and Problems
********************************

Octave 2.9.5 requires approximately 400MB of disk storage to unpack and compile from source (about 120MB if you don't compile with debugging symbols or create shared libraries).  Once installed, Octave requires approximately 65MB of disk space (again, considerably less if you don't build shared libraries or the binaries and libraries do not include debugging symbols).

What else do I need?
====================

To compile Octave, you will need a recent version of GNU Make.  You will also need g++ 2.7.2 or later.  Version 2.8.0 or egcs 1.0.x should work.  Later versions may work, but C++ is still evolving, so don't be too surprised if you run into some trouble.

It is no longer necessary to have libg++, but you do need to have the GNU implementation of libstdc++.  If you are using g++ 2.7.2, libstdc++ is distributed along with libg++, but for later versions, libstdc++ is distributed separately.  For egcs, libstdc++ is included with the compiler distribution.

<em>You must have gnu make to compile octave</em>.  Octave's Makefiles use features of GNU Make that are not present in other versions of make. GNU Make is very portable and easy to install.

Can I compile Octave with another C++ compiler?
===============================================

Currently, Octave can only be compiled with the GNU C++ compiler.  It would be nice to make it possible to compile Octave with other C++ compilers, but the maintainers do not have sufficient time to devote to this.  If you are interested in working to make Octave portable to other compilers, please contact bug@octave.org.

Common problems
***************

This list is probably far too short.  Feel free to suggest additional questions (preferably with answers!)

  * Octave takes a long time to find symbols.

     Octave is probably spending this time recursively searching directories for function files.  Check the value of your LOADPATH.  For those elements that end in //, do any name a very large directory tree? Does it contain directories that have a mixture of files and directories?  In order for the recursive directory searching code to work efficiently, directories that are to be searched recursively should have either function files only, or subdirectories only, but not a mixture of both.  Check to make sure that Octave's standard set of function files is installed this way.

How do I ... ?
**************

How do I set the number of displayed decimals?
==============================================

     octave:1> format long
     octave:2> pi
     pi = 3.14159265358979
     octave:3> format short
     octave:4> pi
     pi = 3.1416
     octave:5> output_precision = 3;
     octave:6> pi
     pi = 3.14

Porting programs from MATLAB to Octave
**************************************

``I wrote some code for MATLAB, and I want to get it running under Octave.  Is there anything I should watch out for?''

The differences between Octave and MATLAB typically fall into one of three categories:

 1. Irrelevant.

 2. Known differences, perhaps configurable with a user preference variable.

 3. Unknown differences.

The first category, irrelevant differences, do not affect computations and most likely do not affect the execution of function files.

The differences of the second category are usually because the authors of Octave decided on a better (subjective) implementation that the way MATLAB does it, and so introduced ``user preference variables'' so that you can customize Octave's behavior to be either MATLAB-compatible or to use Octave's new features.  To make Octave more MATLAB-compatible, put the following statements in your ~/.octaverc file, or use the command line option --traditional, which implies all of these settings.  Note that this list may not be complete, because some new variables may have been introduced since this document was last updated.

       PS1                           = ">> "
       PS2                           = ""
       beep_on_error                 = true
       crash_dumps_octave_core       = false
       default_save_format           = "mat-binary"
       fixed_point_format            = true
       page_screen_output            = false
       print_empty_dimensions        = false
       warn_function_name_clash      = false

Some other known differences are:

  * The Octave plotting functions are mostly compatible with the ones from MATLAB 3.x, but not from MATLAB 4.x.

The third category of differences is (hopefully) shrinking.  If you find a difference between Octave behavior and MATLAB, then you should send a description of this difference (with code illustrating the difference, if possible) to bug@octave.org.

An archive of old postings to the Octave mailing lists is maintained on ftp.che.wisc.edu in the directory /pub/octave/MAILING-LISTS.