% Copyright (C) 1997, 1998, 1999, 2001, 2003, 2004, 2005, 2007, 2008
%               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 Octave-FAQ.info
@settitle Frequently asked questions about Octave (with answers)

@setchapternewpage off
@direntry
* Octave-FAQ: (Octave-FAQ).  Frequently asked questions about Octave
@end direntry
@titlepage
@title Octave FAQ
@subtitle Frequently asked questions about Octave
@subtitle September 2008
@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 @email{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
@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?::  
* How can I cite Octave?::  
* Series 3.0.N::  
* Octave Features::  
* Learning more about Octave:: 
* Getting Octave::  
* Installation::  
* Common problems::             
* How do I ...?::  
* 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 590+ page Texinfo manual.  Access
to the complete text of the manual is available via the help command
@c really, the *complete* text?
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{bug@@octave.org} (bug reports), @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 ``testing'' 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
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.

@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.0.N
@chapter What's new in version series 3.0.N and 3.1.N of Octave

The 3.0.N series has enough new features to justify a major version
number change. The 3.0.N series brings

@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 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

@end itemize

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

@itemize @bullet

@item NDarrays 

@item cells

@end itemize

The 3.1.N series is the current development release and will become a
3.2.N release in the future. This series brings the new features

@itemize
@item OpenGL backend

An experimental OpenGL graphics backend to replace the 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


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

@menu
* Functions defined on the command-line::
* Comments with #::            
* Strings delimitted 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 Matlab R2008b and Octave 2.1.51.

@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 the other leading brand.  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 delimitted by double quotes " 
@section Strings delimitted 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 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 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 '!' (aka ``Bang!'') is a negation operator, just
like the tilde '~':

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

@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 modelled 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.

Matlab can be made to do something similar with their @code{OnCleanUp}
function that was introduced in 2008a.

@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 590+ 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{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 @email{bug@@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{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 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 @code{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 (in a unix-like
operating system).

@cindex Octave bug report
@cindex Mailing lists, bug-octave

If for some reason you cannot use Octave's @code{bug_report} function,
mail your bug report to @email{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.


@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 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).

@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, RedHat,
Suse and Fedora Linuxes, Mac OS X, Windows' 98, 2000 and XP.

@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{bug@@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.2 require approximately 800MB of disk storage to unpack
and compile from source (considerably less if you don't compile with
debugging symbols).  Once installed, Octave requires approximately 200MB
of disk space (again, considerably less if you don't compile with
debugging symbols).

@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 3.3 or later, although GCC 4.1 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 @email{bug@@octave.org} mailing list, 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. The relevant gnuplot bug report can be
found at @url{http://sourceforge.net/tracker/index.php?func=detail&aid=1716556&group_id=2055&atid=102055}

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

@code{aptitude install octave3.0-headers}

@item
Fedora

@code{yum install octave-devel}

@end itemize
@end itemize

@node How do I ...?
@chapter  How do I ...?

@menu
* How do I set the number of displayed decimals?::
@end menu

@cindex Tips and tricks
@cindex How do I @dots{} ?

@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 MATLAB compatibility
@chapter Porting programs from @sc{Matlab} to Octave

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

People often ask

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

or alternatively

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

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 @email{bug@@octave.org}.

Furthermore, Octave adds a few syntactical extensions to Matlab that
might cause some issues when exchanging files between 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.2.N and  @sc{Matlab} R2008a are:

@itemize @bullet
@item Nested Functions

Octave doesn't yet have 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

There was discussion in Octave of having these even prior to @sc{Matlab},
and the decision was made not to have these in Octave at the time for
compatibility.  The above written with sub-functions functions would be

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

Now that @sc{Matlab} has recently introduced nested functions, Octave will
probably have them soon as well.  Until then nested functions in Octave
are treated as sub-functions with the same scoping rules as
sub-functions.  

The authors of Octave consider the nested function scoping rules of
Matlab to be more problems than they are worth as they introduce
diffiult to find bugs as inadvertantly 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 supportted,
though work is underway and when development more on to Octave 3.3 this
will be included in teh 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,
for example @code{condest} or 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
@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 is an example of how to do this at
@url{http://www.stud.tu-ilmenau.de/~rueckn/}, but this is a very early
example code and would need lots of work to complete it.

@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 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.

@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 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 matlab compatible GUI is in an alpha stage in the
JHandles package (@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
@url{http://www.scicraft.org/}

@item Mex-Files
Octave includes an API to the 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 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 abd 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

@url{http://www.cae.wisc.edu/pipermail/octave-maintainers/2007-January/001685.html}

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 matlab functionality or interface.

@item Short-circuit & and | operators
The @code{&} and @code{|} operators in @sc{Matlab} short-circuit when
included in an if statemant 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 behavior to change
it. Prefer the || and && operators in if statements if possible.

Note that the difference 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).  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

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, 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 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, 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 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 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 if, for, while, etc can be terminated with block
specific terminations like "endif". @sc{Matlab} doesn't have this and
all blocks must be terminated with "end"

@item
Octave has a lisp like 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.

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 save 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 transfered to a @sc{Matlab} user.
@end itemize

@end itemize

@node Index
@appendix Concept Index

@printindex cp

@page
@contents
@bye