\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 April, 2007
@sp 1
@author John W. Eaton
@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.

I'm looking for new questions (@emph{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.

@menu
* What is Octave?::  
* How can I cite Octave?::  
* Series 2.9.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 500+ 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 is Octave ``GNU Octave''?::  
* What version should I use?::  
* On what platforms does Octave run?::  
@end menu

@node Who develops Octave?
@section 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).

@node Why is Octave ``GNU Octave''?
@section 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.

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

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

@cindex FSF, contact <gnu@@gnu.org>
@cindex GNUware, anonymous FTP sites

@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:2002,
    author =     "John W. Eaton",
    title =      "GNU Octave Manual",
    publisher =  "Network Theory Limited",
    year =       "2002",
    isbn =       "0-9541617-2-6"
  @}
@end group
@end example

@node Series 2.9.N
@chapter 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.10 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

@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 many many other minor features and compatibility changes

@item a fully compatiable MEX interface

@end itemize

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

@itemize @bullet

@item NDarrays 

@item cells

@end itemize

@c The 2.9.N series, started in 6, 1998.  Most bugs
@c reported since version 2.0 was release have been fixed, and a number of
@c new features have been added.  Octave is now much more compatible with
@c @sc{Matlab}.

@c A list of user-visible changes in recent versions of Octave may be found
@c in the file NEWS, distributed in both source and binary releases of
@c Octave.

@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::
* Empty argument lists::
* Coherent syntax::             
* Exclamation mark as not operator::
@c * Short-circuit boolean operators::  
* Increment and decrement operators::  
* Unwind-protect::              
* Built-in ODE and DAE solvers::
@end menu

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

@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, '#', may be used to start comments, in addition
to '%'. See the previous example. The major advantage of this is that as
'#' is also a comment character for unix script files, any file that
starts with a string like ``#! /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, '"', 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, '\', in addition to three
points '...'. See the previous example.

@node Informative block closing
@section 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.

@node Empty argument lists
@section Empty argument lists

Parameter-less function calls may be made more readable by writing an
empty argument list.
@example
@group
octave:1> rand()
ans = 0.76213
@end group
@end example

@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

@c @item You can also use the function @code{is_struct} to determine
@c whether a given value is a data structure.  For example

@c @example
@c is_struct (x)
@c @end example

@c @noindent
@c returns 1 if the value of the variable @var{x} is a data structure.
@c @end itemize

@c This feature should be considered experimental, but you should expect it
@c to work.  Suggestions for ways to improve it are welcome.

@c @node Short-circuit boolean operators
@c @section Short-circuit boolean operators

@c @cindex Boolean operators, short-circuit
@c @cindex Logical operators, short-circuit
@c @cindex Short-circuit boolean operators
@c @cindex Operators, boolean

@c Octave's @samp{&&} and @samp{||} logical operators are evaluated in
@c a short-circuit fashion (like the corresponding operators in the C
@c language) and work differently than the element by element operators
@c @samp{&} and @samp{|}.

@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 '++', '+=' 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{@var{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{@var{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.

@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 375+ page manual that is also
distributed under the terms of the GNU GPL.
@c The Octave manual is intended to be a complete reference for Octave, but
@c it is not a finished document.  
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.

@c Because the Octave manual is written using Texinfo, t
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.

@c It is also possible to use your favorite WWW browser to read the Octave
@c manual by converting the Texinfo source to HTML using the
@c @code{texi2html} program.

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.


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

@example
help@@octave.org
@end example

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

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

@example
@group
help-request@@octave.org
     ^^^^^^^
@end group
@end example
@strong{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 @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{htt://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 "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 ship 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, 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.

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

@c @node Octave for Unix
@c @section How do I get a copy of Octave for Unix?

@c You can get Octave from a friend who has a copy, by anonymous FTP, or by
@c ordering a tape or CD-ROM from the Free Software Foundation (FSF).

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

@node Installation
@chapter Installation Issues and Problems

@cindex Octave, building 

Octave 2.9.10 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
@c How do I measure installed size?
you don't build shared libraries or the binaries and libraries do not
include 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 g++ 2.9.0 or later, although g++ 3.3 or later is 
recommended.  Octave has been successfully built with all versions of
g++ between 3.3 and 4.1. Later versions may work, but C++ is still evolving, 
so don't be too surprised if you run into some trouble.

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

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.

@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 is probably spending this time recursively searching directories for
function files.  Check the value of the internal variable LOADPATH,
accessible through the Octave fucntion @code{path}.  For those
elements that end in @samp{//}, 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.
@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 ... ?

@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
octave:5> output_precision = 3;
octave:6> pi
pi = 3.14
@end group
@end example


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

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

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

The differences between Octave and @sc{Matlab} typically fall into one of
three categories:

@enumerate
@item
Irrelevant.

@item
Known differences, perhaps configurable with a user preference variable.

@item
Unknown differences.
@end enumerate

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
@sc{Matlab} does it, and so introduced ``user preference variables'' so that
you can customize Octave's behavior to be either @sc{Matlab}-compatible or
to use Octave's new features.  To make Octave more @sc{Matlab}-compatible,
put the following statements in your @file{~/.octaverc} file, or use the
command line option @samp{--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.

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

Some other known differences are:

@itemize @bullet
@item
The Octave plotting functions are mostly compatible with the ones from
@sc{Matlab} 3.x, but not from @sc{Matlab} 4.x.
@end itemize

The third category of differences is (hopefully) shrinking.  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 bug@@octave.org.

@node Index
@appendix Concept Index

@printindex cp

@page
@contents
@bye