% Copyright (C) 1997-2012 John W. Eaton
%
% This file is part of Octave.
%
% Octave is 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; either version 3 of the License, or (at
% your option) any later version.
%
% Octave is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
% for more details.
%
% You should have received a copy of the GNU General Public License
% along with Octave; see the file COPYING.  If not, see
% <http://www.gnu.org/licenses/>.

\input texinfo.tex      @c -*-texinfo-*-

@setfilename OctaveFAQ.info
@settitle Frequently asked questions about Octave (with answers)

@setchapternewpage off
@direntry
* OctaveFAQ: (OctaveFAQ).  Frequently asked questions about Octave
@end direntry
@titlepage
@title Octave FAQ
@subtitle Frequently asked questions about Octave
@subtitle @today{}
@sp 1
@author John W. Eaton and David Bateman
@page
@end titlepage

@ifnottex
@node Top
@top
@unnumbered Preface
@cindex FAQ for Octave, latest version
@end ifnottex

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

We are always looking for new questions (@emph{with} answers), better
answers, or both. Please send suggestions to
@url{http://bugs.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 @email{help@@octave.org} mailing list.

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

@menu
* What is Octave?::
* Licensing Issues::
* How can I cite Octave?::
* Series 3.4.N::
* Octave Features::
* Learning more about Octave::
* Getting Octave::
* Installation::
* Common problems::
* Using Octave::
* @sc{Matlab} compatibility::
* Index::
@end menu

@node What is Octave?
@chapter What is Octave?

Octave is a high-level interactive language, primarily intended for
numerical computations that is mostly compatible with
@sc{Matlab}.@footnote{@sc{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 650+ page Texinfo manual. Access to
the complete text of the manual is available via the @code{doc} command
at the Octave prompt.

@menu
* Who develops Octave?::
* Why GNU Octave?::
* What version should I use?::
* On what platforms does Octave run?::
@end menu

@node Who develops Octave?
@section Who develops Octave?

Discussions about writing the software that would eventually become
Octave started in about 1988 with James B. Rawlings and John W. Eaton at
the University of Texas. John W. Eaton was the original author of
Octave, starting full-time development in February 1992. He is still the
primary maintainer. The community of users/developers has in addition
contributed some code and fuels the discussion on the mailing lists
@email{help@@octave.org} (user forum), @email{maintainers@@octave.org}
(development issues), and @email{octave-dev@@lists.sourceforge.net} (all
things related to the Octave Forge repository of user-contributed
functions).

@node Why GNU Octave?
@section Why GNU Octave?

The GNU Project was launched in 1984 to develop a complete Unix-like
operating system which is free software: the GNU system.

GNU is a recursive acronym for ``GNU's Not Unix''; it is pronounced
guh-noo, approximately like canoe.

The Free Software Foundation (FSF) is the principal organizational
sponsor of the GNU Project.

Octave became GNU Octave in 1997 (beginning with version 2.0.6).  This
meant agreeing to consider Octave a part of the GNU Project and support
the efforts of the FSF.  However, Octave is not and has never been
developed by the FSF.

For more information about the GNU project, see @url{www.gnu.org}.

@cindex FSF [Free Software Foundation]
@cindex GNU [GNU's not unix]

@node What version should I use?
@section What version should I use?

In general, you will find the latest version on
@url{http://www.octave.org/download.html}. It is recommended to use the
``stable'' version of octave for general use, and the ``development''
version if you want the latest features.

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

@node On what platforms does Octave run?
@section 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
@c Does Vista work? I get the feeling that even Windows users are trying
@c to forget Vista like a bad nightmare. Tatsuro only confirmed XP and
@c 7. I am tentatively assuming that Vista also works.
CPUs, at least), for Mac OS X and Windows' 98, 2000, XP, Vista, and 7.

Two and three dimensional plotting is fully supported using gnuplot and
an experimental OpenGL backend.

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, version 3, as
published by the Free Software Foundation, or at your option any later
version.

@node Licensing Issues
@chapter Licensing Issues

@menu
* If I write code using Octave do I have to release it under the GPL?: GPL
* Since the MEX interface allows plugins to be distributed under terms that are incompatible with the GPL, does this mean that you are encouraging people to to write non-free software for Octave?: Licensing MEX Files
* I wrote a program that links with Octave libraries and I don't want to release it under the terms of the GPL.  Will you change the license of the Octave libraries for me?: Requesting License Changes
@end menu

@node GPL
@section If I write code using Octave do I have to release it under the GPL?

The answer depends on precisely how the code is written and how it works.

Code written entirely in the scripting language of Octave
(interpreted code in .m files) may be released under the terms of
whatever license you choose.

Code written using Octave's native plug-in interface (also known
as a .oct file) necessarily links with Octave internals and is
considered a derivative work of Octave and therefore must be
released under terms that are compatible with the GPL.

Code written using Octave's implementation of the @sc{Matlab} MEX
interface may be released under the terms of whatever license you
choose, provided that the following conditions are met:

@enumerate
@item
The plugin should not use any bindings that are specific to Octave.  In
other words, the MEX file must use the MEX interface only, and not also
call on other Octave internals.  It should be possible in principle to
use the MEX file with other programs that implement the MEX interface
(e.g., @sc{Matlab}).

@item
The MEX file should not be distributed together with Octave in such a
way that they effectively create a single work.  For example, you should
not distribute the MEX file and Octave together in a single package such
that Octave automatically loads and runs the MEX file when it starts up.
There are other possible ways that you might effectively create a single
work; this is just one example.
@end enumerate

A program that embeds the Octave interpreter (e.g., by calling the
"octave_main" function), or that calls functions from Octave's
libraries (e.g., liboctinterp, liboctave, or libcruft) is
considered a derivative work of Octave and therefore must be
released under terms that are compatible with the GPL.

@node Licensing MEX Files
@section Since the MEX interface allows plugins to be distributed under terms that are incompatible with the GPL, does this mean that you are encouraging people to to write non-free software for Octave?

No.  The original reason for implementing the MEX interface for Octave
was to allow Octave to run free software that uses MEX files (the
particular goal was to run SundialsTB in Octave).  The intent was to
liberate that software from @sc{Matlab} and increase the amount of free
software available to Octave users, not to enable people to write
proprietary code for Octave.  For the good of the community, we strongly
encourage users of Octave to release the code they write for Octave
under terms that are compatible with the GPL.

@node Requesting License Changes
@section I wrote a program that links with Octave libraries and I don't want to release it under the terms of the GPL.  Will you change the license of the Octave libraries for me?

No.  Instead of asking us to change the licensing terms for Octave, we
recommend that you release your program under terms that are compatible
with the GPL so that the free software community can benefit from your
work the same as you have benefited from the work of all the people who
have contributed to Octave.

@node How can I cite Octave?
@chapter How can I cite Octave?

Pointing to @url{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:

@example
@group
@@BOOK@{eaton:2008,
  author =     "John W. Eaton and David Bateman and Søren Hauberg",
  title =      "GNU Octave Manual Version 3",
  publisher =  "Network Theory Limited",
  year =       "2008",
  isbn =       "0-9546120-6-X"
@}
@end group
@end example

@node Series 3.4.N
@chapter What's new in version series 3.4.N and 3.5.N of Octave

The 3.4.N series has enough new features to justify a minor version
number change. The full details are in the @file{NEWS} file, but in
brief 3.4.N series brings:

@c This list is distilled from the NEWS file. Does it have enough
@c things? Does it have too many?
@itemize @bullet

@item ARPACK now distributed with Octave

@item Indexing optimisations

@item FTP object using @file{libcurl}

@item Better consistency with ismatrix, issquare, and issymetric

@item Function handles aware of overloaded functions

@item More efficient matrix division by making a single LAPACK call

@item Other optimisations in matrix operations

@item @code{bsxfun} optimised for basic arithmetic functions

@item @sc{Matlab}-style ignoring of output arguments using @samp{~}

@item Many optimisations of the @code{accumarray} function

@item Sparse matrix indexing has been rewritten for speed

@item Configuration pseudo-variables like @code{page_screen_output}
accept a ``local'' option argument to limit their scope to function
scope

@item The @code{pkg} command now accepts a @code{-forge} option to pull
packages directly from Octave-forge

@item Several @code{dlmread} improvements

@item Octave now uses gnulib for better cross-platform compatibility

@end itemize

Here are some features that have been around since 3.2.N

@itemize @bullet

@item integer types

@item fixed point arithmetic

@item sparse matrices

@item Linear programming code based on GLPK

@item 64-bit compilation support

@item gzipped files and stream and consequently support of @sc{Matlab} v7 files

@item better support for both msvc and mingw

@item a fully compatible MEX interface

@item many many other minor features and compatibility changes

@item OpenGL graphics toolkit

An experimental OpenGL graphics toolkit to replace gnuplot.

@item Object Orient Programming

@item Block comments

@item imwrite and imread

The functions are based on the GraphicsMagick library.

@item Lazy transpose

Special treatment in the parser of things like "a' * b", where the
transpose is never explicitly formed but a flag is rather passed to the
underlying LAPACK code.

@item Single precision type

@item Improved array indexing
The underlying code used for indexing of arrays has been completely
rewritten and so the indexing of arrays is now significantly faster.

@end itemize

Here are some older features that have been around since 2.1.N:

@itemize @bullet

@item NDarrays

@item cells

@end itemize

The 3.5.N series is the current development release and will become a
3.6.N release in the future. This series brings the following new
features:

@itemize
@item Perl-compatible regular expressions are now part of Octave
@end itemize


@node Octave Features
@chapter What features are unique to Octave?

@menu
* Functions defined on the command-line::
* Comments with #::
* Strings delimited by double quotes "::
* Line continuation by backslash::
* Informative block closing::
* Coherent syntax::
* Exclamation mark as not operator::
* Increment and decrement operators::
* Unwind-protect::
* Built-in ODE and DAE solvers::
@end menu

This section refers to @sc{Matlab} R2010b and Octave 3.4.0.

@node Functions defined on the command-line
@section Functions defined on the command-line

Functions can be defined by entering code on the command line, a feature
not supported by @sc{Matlab}. For example, you may type:

@example
@group
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
@end group
@end example

@node Comments with #
@section Comments with #

The pound character, @samp{#}, may be used to start comments, in
addition to @samp{%}. See the previous example. The major advantage of
this is that as @samp{#} is also a comment character for unix script
files, any file that starts with a string like @samp{#! /usr/bin/octave
-q} will be treated as an octave script and be executed by octave.

@node Strings delimited by double quotes "
@section Strings delimited by double quotes "
The double quote, @samp{"}, may be used to delimit strings, in addition
to the single quote @samp{'}. See the previous example. Also,
double-quoted strings include backslash interpretation (like C++, C, and
Perl) while single quoted are uninterpreted (like @sc{Matlab} and Perl).

@node Line continuation by backslash
@section Line continuation by backslash

Lines can be continued with a backslash, @samp{\}, in addition to three
points @samp{@dots{}}.  See the previous example.

@node Informative block closing
@section Informative block closing

You may close @code{function}, @code{for}, @code{while}, @code{if},
@dots{} blocks with @code{endfunction}, @code{endfor}, @code{endwhile},
@dots{} keywords in addition to using @code{end}.  As with @sc{Matlab}, the
@code{end} (or @code{endfunction}) keyword that marks the end of a
function defined in a @file{.m} file is optional.

@node Coherent syntax
@section Coherent syntax

Indexing other things than variables is possible, as in:
@example
@group
octave:1> [3 1 4 1 5 9](3)
ans = 4
octave:2> cos([0 pi pi/4 7])(3)
ans = 0.70711
@end group
@end example

@node Exclamation mark as not operator
@section Exclamation mark as not operator

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

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

@noindent
Note however that @sc{Matlab} uses the @samp{!} operator for shell
escapes, for which Octave requires using the @code{system} command.

@node Increment and decrement operators
@section Increment and decrement operators

@cindex Increment operators
@cindex Decrement operators
@cindex Operators, increment
@cindex Operators, decrement

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

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

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

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

@node Unwind-protect
@section Unwind-protect

@cindex Unwind-protect

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

@example
@group
unwind_protect
  @var{body}
unwind_protect_cleanup
  @var{cleanup}
end_unwind_protect
@end group
@end example

@noindent
Where @var{body} and @var{cleanup} are both optional and may contain any
Octave expressions or commands.  The statements in @var{cleanup} are
guaranteed to be executed regardless of how control exits @var{body}.

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

@sc{Matlab} can be made to do something similar with their
@code{OnCleanUp} function that was introduced in 2008a. Octave also has
@code{onCleanup} since version 3.4.0.

@node Built-in ODE and DAE solvers
@section Built-in ODE and DAE solvers

@cindex DASSL
@cindex LSODE

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

@node Learning more about Octave
@chapter What documentation exists for Octave?

@menu
* Documentation::
* Getting additional help::
* User community::
* Bug reports::
@end menu

@node Documentation
@section What documentation exists for Octave?

@cindex Octave, documentation

The Octave distribution includes a 650+ page manual that is also
distributed under the terms of the GNU GPL.
It is available on the web at
@url{http://www.octave.org/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 @samp{doc} 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 report
it on @url{http://bugs.octave.org}.

@node Getting additional help
@section Getting additional help

@cindex Additional help
@cindex Mailing lists, help-octave

If you can't find an answer to your question, the
@email{help@@octave.org} mailing list is available for questions related
to using, installing, and porting Octave that are not adequately
answered by the Octave manual or by this document.

@node User community
@section User community

To subscribe to the list, go to @url{http://www.octave.org/archive.html}
and follow the link to the subscription page for the list.

@strong{Please do not} send requests to be added or removed from 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 @url{http://www.octave.org/archive.html}.

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

@node Bug reports
@section I think I have found a bug in Octave.

@cindex Bug in Octave, newly found

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

@cindex Manual, for Octave

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 and
configuration details of your operating system so that the Octave
maintainers can duplicate your bug.

@node Getting Octave
@chapter Getting Octave

@menu
* Source code::
* Pre-compiled binary packages::
* Octave for other platforms::
@end menu

@node Source code
@section Source code
@cindex Source code

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

@itemize @bullet
@item @url{http://www.octave.org/download.html}
@item @url{ftp://ftp.octave.org/pub/octave/}
@end itemize

Since Octave is distributed under the terms of the GPL, you can get
Octave from a friend who has a copy, or from the Octave website.

@node Pre-compiled binary packages
@section Pre-compiled binary packages
@cindex  Pre-compiled binary packages
@cindex  Binaries

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

@itemize @bullet
@item @url{http://www.octave.org/download.html}
@item @url{http://wiki.octave.org/wiki.pl?CategoryInstall}
@end itemize

As of today, Octave binaries are available at least on Debian, Ubuntu,
RedHat, Suse and Fedora GNU/Linuxen, Mac OS X, Windows' 98, 2000 and XP,
Vista, and 7.

@node Octave for other platforms
@section How do I get a copy of Octave for (some other platform)?

@cindex VMS support
@cindex VAX
@cindex MS-DOS support
@cindex Windows support
@cindex DJGPP
@cindex EMX
@cindex OS/2 support

Octave currently runs on Unix-like systems, Mac OS X, and Windows.
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
@email{maintainers@@octave.org}.

@c @menu
@c * Octave for Unix::
@c * Octave for other platforms::
@c * latest versions::
@c @end menu

@c @cindex Octave, ordering
@c @cindex Octave, getting a copy

@node Installation
@chapter Installation Issues and Problems

@cindex Octave, building

Octave 3.4 require approximately 1.3 GB of disk storage to unpack and
compile from source (considerably less if you don't compile with
debugging symbols). Once installed, Octave requires approximately 355 MB
of disk space (again, considerably less if you don't compile with
debugging symbols, approximately 50 MB).

@menu
* What else do I need?::
* Other C++ compilers?::
@end menu

@node What else do I need?
@section What else do I need?

@cindex GNU gcc
@cindex GNU g++
@cindex libg++
@cindex GNU Make
@cindex Flex
@cindex GNU Bison

To compile Octave, you will need a recent version of GNU Make.  You
will also need GCC 4.3  or later, although GCC 4.4 or later is
recommended.

@strong{You must have GNU Make to compile octave}.  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.

@node Other C++ compilers?
@section Can I compile Octave with another C++ compiler?

Yes, but development is done primarily with GCC, so you may hit some
incompatibilities. Octave is intended to be portable to any standard
conforming compiler. If you have difficulties that you think are bugs,
please report them to the @url{http://bugs.octave.org} bug tracker, or
ask for help on the @email{help@@octave.org} mailing list.

@node Common problems
@chapter Common problems

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

@itemize @bullet
@item
Octave takes a long time to find symbols.

Octave uses the @code{genpath} function to recursively add directories
to the list of directories searched for function files.  Check the list
of directories with the @code{path} command. If the path list is very
long check your use of the @code{genpath} function.

@item
When plotting Octave occasionally gives me errors like @samp{gnuplot> 9
0.735604 line 26317: invalid command}.

There is a known bug in gnuplot 4.2 that can cause an off by one error
while piping data to gnuplot. It has been fixed in gnuplot 4.4.

If you have obtained your copy of Octave from a distribution please file
a bug report requesting that the fix reported in the above bug report be
included.

@item
I cannot install a package. Octave complains about a missing
@code{mkoctfile}.

Most distributions split Octave into several packages. The script
@code{mkoctfile} is then part of a separate package:
@itemize @minus
@item
Debian/Ubuntu

@c This will work once we upload the Octave packages without a version
@c in their name to Debian.
@code{aptitude install octave-headers}

@item
Fedora

@code{yum install octave-devel}

@end itemize
@end itemize

@node Using Octave
@chapter  Using Octave

@menu
* How do I set the number of displayed decimals?::
* How does Octave solve linear systems?::
@end menu

@cindex Tips and tricks
@cindex Using Octave

@node How do I set the number of displayed decimals?
@section How do I set the number of displayed decimals?

@example
@group
octave:1> format long
octave:2> pi
pi = 3.14159265358979
octave:3> format short
octave:4> pi
pi = 3.1416
@end group
@end example

@node How does Octave solve linear systems?
@section How does Octave solve linear systems?

@cindex backslash operator

In addition to consulting Octave's source for the precise details, the
Octave manual contains a complete high-level description of the
algorithm that Octave uses to decide how to solve a particular linear
system, e.g. how the backslash operator @code{A\x} will be interpreted.
Sections ``Techniques Used for Linear Algebra'' and ``Linear Algebra on
Sparse Matrices'' from the manual describe this procedure.

@node @sc{Matlab} compatibility
@chapter Porting programs from @sc{Matlab} to Octave

@cindex @sc{Matlab} compatibility
@cindex Compatibility with @sc{Matlab}

People often ask

@quotation
I wrote some code for @sc{Matlab}, and I want to get it running under
Octave.  Is there anything I should watch out for?
@end quotation

@noindent
or alternatively

@quotation
I wrote some code in Octave, and want to share it with @sc{Matlab}
users.  Is there anything I should watch out for?
@end quotation

@noindent
which is not quite the same thing.  There are still a number of
differences between Octave and @sc{Matlab}, however in general
differences between the two are considered as bugs.  Octave might
consider that the bug is in @sc{Matlab} and do nothing about it, but
generally functionality is almost identical.  If you find a difference
between Octave behavior and @sc{Matlab}, then you should send a
description of this difference (with code illustrating the difference,
if possible) to @url{http://bugs.octave.org}.

Furthermore, Octave adds a few syntactical extensions to @sc{Matlab}
that might cause some issues when exchanging files between @sc{Matlab}
and Octave users. As both Octave and @sc{Matlab} are under constant
development the information in this section is subject to change at
anytime.

You should also look at the page
@url{http://octave.sourceforge.net/packages.html} and
@url{http://octave.sourceforge.net/doc/} that has a function reference
that is up to date. You can use this function reference to see the
number of octave function that are available and their @sc{Matlab}
compatibility.

The major differences between Octave 3.4.N and  @sc{Matlab} R2010b are:

@itemize @bullet
@item Nested Functions

Octave has limited support for nested functions. That is

@example
@group
function y = foo (x)
  y = bar(x)
  function y = bar (x)
    y = @dots{};
  end
end
@end group
@end example

is equivalent to

@example
@group
function y = foo (x)
   y = bar(x)
end
function y = bar (x)
   y = @dots{};
end
@end group
@end example

The main difference with @sc{Matlab} is a matter of scope. While nested
functions have access to the parent function's scope in @sc{Matlab}, no
such thing is available in Octave, due to how Octave essentially
``un-nests'' nested functions.

The authors of Octave consider the nested function scoping rules of
@sc{Matlab} to be more problems than they are worth as they introduce
difficult to find bugs as inadvertently modifying a variable in a
nested function that is also used in the parent is particularly easy.

@item Differences in core syntax
There a few core @sc{Matlab} syntaxes that are not accepted by Octave,
these being

@itemize @bullet
@item
Some limitations on the use of function handles. The major difference is
related to nested function scoping rules (as above) and their use with
function handles.

@item
Some limitations of variable argument lists on the LHS of an expression,
though the most common types are accepted.

@item
@sc{Matlab} classdef object oriented programming is not yet supported,
though work is underway and when development more on to Octave 3.5 this
will be included in the development tree.
@end itemize

@item Differences in core functions
A large number of the @sc{Matlab} core functions (ie those that are in
the core and not a toolbox) are implemented, and certainly all of the
commonly used ones. There are a few functions that aren't implemented,
usually to do with specific missing Octave functionality (GUI, DLL,
Java, ActiveX, DDE, web, and serial functions). Some of the core
functions have limitations that aren't in the @sc{Matlab} version. For
example the @code{sprandn} function can not force a particular condition
number for the matrix like @sc{Matlab} can.

@item Just-In-Time compiler
@sc{Matlab} includes a "Just-In-Time" compiler. This compiler allows the
acceleration of for-loops in @sc{Matlab} to almost native performance
with certain restrictions. The JIT must know the return type of all
functions called in the loops and so you can't include user functions in
the loop of JIT optimized loops. Octave doesn't have a JIT and so to
some might seem slower than @sc{Matlab}. For this reason you must
vectorize your code as much as possible. The MathWorks themselves have a
good document discussing vectorization at
@c It would be nice if we had our own guide for this instead of relying
@c on Matlab documentation.
@url{http://www.mathworks.com/support/tech-notes/1100/1109.html}.

@item Compiler
On a related point, there is no Octave compiler, and so you can't
convert your Octave code into a binary for additional speed or
distribution. There have been several aborted attempts at creating an
Octave compiler. Should the JIT compiler above ever be implemented, an
Octave compiler should be more feasible.
@c Should we mention here any of the efforts to create a compiler? There
@c used to be a dead link here to http://www.stud.tu-ilmenau.de/~rueckn/

@item Graphic Handles
Up to Octave 2.9.9 there was no support for graphic handles in Octave
itself. In the 3.2.N versions of Octave and beyond the support for
graphics handles is converging towards full compatibility. The
@code{patch} function is currently limited to 2-D patches, due to an
underlying limitation in gnuplot, but the experimental OpenGL backend is
starting to see an implementation of 3-D patches.

@item GUI
There are no @sc{Matlab} compatible GUI functions. There are a number of
bindings from Octave to Tcl/Tk, VTK and Zenity included in the Octave
@c Is it too early to mention here the nascent fltk UI buttons?
Forge project (@url{http://octave.sourceforge.net}) for example that can
be used for a GUI, but these are not @sc{Matlab} compatible. Work on a
@sc{Matlab} compatible GUI is in an alpha stage in the JHandles package
@c Is Jhandles still usable? I thought Michael Goffioul had more or less
@c already disowned it.
(@url{http://octave.sourceforge.net/jhandles/index.html}). This might be
an issue if you intend to exchange Octave code with @sc{Matlab} users.

@item Simulink
Octave itself includes no Simulink support. Typically the simulink
models lag research and are less flexible, so shouldn't really be used
in a research environment.  However, some @sc{Matlab} users that try to
use Octave complain about this lack.  There is a similar package to
simulink for the Octave and R projects available at
@c is this project in any state of usability?
@url{http://www.scicraft.org/}

@item Mex-Files
Octave includes an API to the @sc{Matlab} MEX interface. However, as MEX
is an API to the internals of @sc{Matlab} and the internals of Octave
differ from @sc{Matlab}, there is necessarily a manipulation of the data
to convert from a MEX interface to the Octave equivalent. This is
notable for all complex matrices, where @sc{Matlab} stores complex
arrays as real and imaginary parts, whereas Octave respects the C99/C++
standards of co-locating the real/imag parts in memory. Also due to the
way @sc{Matlab} allows access to the arrays passed through a pointer,
the MEX interface might require copies of arrays (even non complex
ones).

@item Block comments
Block comments denoted by "%@{" and "%@}" markers are supported by
Octave with some limitations. The major limitation is that block
comments are not supported within [] or @{@}.

@item Mat-File format
There are some differences in the mat v5 file format accepted by Octave.
@sc{Matlab} recently introduced the "-V7.3" save option which is an HDF5
format which is particularly useful for 64-bit platforms where the
standard @sc{Matlab} format can not correctly save variables. Octave
accepts HDF5 files, but is not yet compatible with the "-v7.3" versions
produced by @sc{Matlab}.

Although Octave can load inline function handles saved by @sc{Matlab},
it can not yet save them.

Finally, Some multi-byte Unicode characters aren't yet treated in
mat-files.

@item Profiler
Octave doesn't have a profiler. Though there is a patch for a flat
profiler, that might become a real profiler sometime in the future. See
the thread

@c Did this idea go anywhere? Should it be mentioned?
@url{http://octave.1599824.n4.nabble.com/Octave-profiler-td1641945.html#a1641947}

for more details.

@item Toolboxes
Octave is a community project and so the toolboxes that exist are
donated by those interested in them through the Octave Forge website
(@url{http://octave.sourceforge.net}). These might be lacking in certain
functionality relative to the @sc{Matlab} toolboxes, and might not
exactly duplicate the @sc{Matlab} functionality or interface.

@item Short-circuit & and | operators
The @code{&} and @code{|} operators in @sc{Matlab} short-circuit when
included in an if statement and not otherwise.  In Octave only the
@code{&&} and @code{||} short circuit.  Note that this means that

@example
@group
  if (a | b)
    @dots{}
  end
@end group
@end example

and

@example
@group
  t = a | b;
  if t
    @dots{}
  end
@end group
@end example

@noindent
are different in @sc{Matlab}. This is really a @sc{Matlab} bug, but
there is too much code out there that relies on this behaviour to change
it. Prefer the || and && operators in if statements if possible. If you
need to use code written for @sc{Matlab} that depends on this buggy
behaviour, you can enable it since Octave 3.4.0 with the following
command:

@example
@group
  do_braindead_shortcircuit_evaluation(1)
@end group
@end example

Note that the difference with @sc{Matlab} is also significant when
either argument is a function with side effects or if the first argument
is a scalar and the second argument is an empty matrix. For example,
note the difference between

@example
@group
  t = 1 | [];          ## results in [], so...
  if (t) 1, end        ## in if ([]), this is false.
@end group
@end example

and

@example
  if (1 | []) 1, end   ## short circuits so condition is true.
@end example

Another case that is documented in the @sc{Matlab} manuals is that

@example
@group
  t = [1, 1] | [1, 2, 3];          ## error
  if ([1, 1] | [1, 2, 3]) 1, end   ## OK
@end group
@end example

Also @sc{Matlab} requires the operands of && and || to be scalar values
but Octave does not (it just applies the rule that for an operand to be
considered true, every element of the object must be nonzero or
logically true).

Finally, note the inconsistence of thinking of the condition of an if
statement as being equivalent to @code{all(X(:))} when @var{X} is a
matrix.  This is true for all cases EXCEPT empty matrices:

@example
@group
  if ([0, 1]) == if (all ([0, 1]))   ==>  i.e., condition is false.
  if ([1, 1]) == if (all ([1, 1]))   ==>  i.e., condition is true.
@end group
@end example

However,

@example
  if ([]) != if (all ([]))
@end example

because @code{samp ([]) == 1} because, despite the name, it is really
returning true if none of the elements of the matrix are zero, and since
there are no elements, well, none of them are zero. This is an example
of vacuous truth. But, somewhere along the line, someone decided that if
@code{([])} should be false. Mathworks probably thought it just looks
wrong to have @code{[]} be true in this context even if you can use
logical gymnastics to convince yourself that "all" the elements of a
matrix that doesn't actually have any elements are nonzero. Octave
however duplicates this behavior for if statements containing empty
matrices.

@item Solvers for singular, under- and over-determined matrices

@sc{Matlab}'s solvers as used by the operators mldivide (\) and mrdivide
(/), use a different approach than Octave's in the case of singular,
under-, or over-determined matrices. In the case of a singular matrix,
@sc{Matlab} returns the result given by the LU decomposition, even
though the underlying solver has flagged the result as erroneous. Octave
has made the choice of falling back to a minimum norm solution of
matrices that have been flagged as singular which arguably is a better
result for these cases.

In the case of under- or over-determined matrices, Octave continues to
use a minimum norm solution, whereas @sc{Matlab} uses an approach that
is equivalent to

@example
@group
function x = mldivide (A, b)
  [Q, R, E] = qr(A);
  x = [A \ b, E(:, 1:m) * (R(:, 1:m) \ (Q' * b))]
end
@end group
@end example

@noindent
While this approach is certainly faster and uses less memory than
Octave's minimum norm approach, this approach seems to be inferior in
other ways.

A numerical question arises: how big can the null space component
become, relative to the minimum-norm solution? Can it be nicely bounded,
or can it be arbitrarily big? Consider this example:

@example
@group
m = 10;
n = 10000;
A = ones(m, n) + 1e-6 * randn(m,n);
b = ones(m, 1) + 1e-6 * randn(m,1);
norm(A \ b)
@end group
@end example

@noindent
while Octave's minimum-norm values are around 3e-2, @sc{Matlab}'s
results are 50-times larger. For another issue, try this code:

@example
@group
m = 5;
n = 100;
j = floor(m * rand(1, n)) + 1;
b = ones(m, 1);
A = zeros(m, n);
A(sub2ind(size(A),j,1:n)) = 1;
x = A \ b;
[dummy,p] = sort(rand(1,n));
y = A(:,p)\b;
norm(x(p)-y)
@end group
@end example

@noindent
It shows that unlike in Octave, mldivide in @sc{Matlab} is not invariant
with respect to column permutations. If there are multiple columns of
the same norm, permuting columns of the matrix gets you different
result than permuting the solution vector. This will surprise many
users.

Since the mldivide (\) and mrdivide (/) operators are often part of a
more complex expression, where there is no room to react to warnings or
flags, it should prefer intelligence (robustness) to speed, and so the
Octave developers are firmly of the opinion that Octave's approach for
singular, under- and over-determined matrices is a better choice that
@sc{Matlab}'s

@item Octave extensions
The extensions in Octave over @sc{Matlab} syntax are
very useful, but might cause issues when sharing with @sc{Matlab} users.
A list of the major extensions that should be avoided to be compatible
with @sc{Matlab} are

@itemize @bullet
@item
Comments in octave can be marked with @samp{#}. This allows POSIX
systems to have the first line as @samp{#! octave -q} and mark the
script itself executable. @sc{Matlab} doesn't have this feature due to
the absence of comments starting with @samp{#}".

@item
Code blocks like @code{if}, @code{for}, @code{while}, etc can be
terminated with block specific terminations like @code{endif}.
@sc{Matlab} doesn't have this and all blocks must be terminated with
@code{end}.

@item
Octave has a lisp like @code{unwind_protect} block that allows blocks of
code that terminate in an error to ensure that the variables that are
touched are restored. You can do something similar with
@code{try}/@code{catch} combined with @samp{rethrow (lasterror ())} in
@sc{Matlab}, however rethrow and lasterror are only available in Octave
2.9.10 and later. @sc{Matlab} 2008a also introduced @code{OnCleanUp}
that is similar to @code{unwind_protect}, except that the object created
by this function has to be explicitly cleared in order for the cleanup
code to run.

Note that using @code{try}/@code{catch} combined with @samp{rethrow
(lasterror ())} can not guarantee that global variables will be
correctly reset, as it won't catch user interrupts with Ctrl-C. For
example

@example
@group
  global a
  a = 1;
  try
    _a = a;
    a = 2
    while true
    end
  catch
    fprintf ('caught interrupt\n');
    a = _a;
    rethrow (lasterror());
  end
@end group
@end example

@noindent
compared to

@example
@group
  global a
  a = 1;
  unwind_protect
    _a = a;
    a = 2
    while true
    end
  unwind_protect_cleanup
    fprintf ('caught interrupt\n');
    a = _a;
  end
@end group
@end example

Typing Ctrl-C in the first case returns the user directly to the
prompt, and the variable "a" is not reset to the saved value. In the
second case the variable "a" is reset correctly.  Therefore @sc{Matlab}
gives no safe way of temporarily changing global variables.

@item
Indexing can be applied to all objects in Octave and not just
variable. Therefore @code{sin(x)(1:10);} for example is perfectly valid
in Octave but not @sc{Matlab}. To do the same in @sc{Matlab} you must do
@code{y = sin(x); y = y([1:10]);}

@item
Octave has the operators "++", "--", "-=", "+=", "*=", etc.  As
@sc{Matlab} doesn't, if you are sharing code these should be avoided.

@item
Character strings in Octave can be denoted with double or single
quotes. There is a subtle difference between the two in that escaped
characters like @code{\n} (newline), @code{\t} (tab), etc are
interpreted in double quoted strings but not single quoted strings. This
difference is important on Windows platforms where the "\" character is
used in path names, and so single quoted strings should be used in
paths. @sc{Matlab} doesn't have double quoted strings and so they should
be avoided if the code will be transferred to a @sc{Matlab} user.
@end itemize

@end itemize

@node Index
@appendix Concept Index

@printindex cp

@page
@contents
@bye