Octave
FAQ
Frequently
asked questions about Octave
February
14, 1998
John
W. Eaton
Table
of Contents
This
is a list of frequently asked questions (FAQ) for Octave users.
Some
information in this FAQ was written for earlier versions of
Octave and may now be obsolete.
I'm
looking for new questions (with answers), better
answers, or both. Please send suggestions to bug-octave@bevo.che.wisc.edu.
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@bevo.che.wisc.edu 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.
Octave
is a high-level interactive language, primarily intended for
numerical computations that is mostly compatible with MATLAB.(1)
Octave
can do arithmetic for real and complex scalars and matrices,
solve sets of nonlinear algebraic equations, integrate functions
over finite and infinite intervals, and integrate systems
of ordinary differential and differential-algebraic equations.
Octave
uses the GNU readline library to handle reading and editing
input. By default, the line editing commands are similar to
the cursor movement commands used by GNU Emacs, and a vi-style
line editing interface is also available. At the end of each
session, the command history is saved, so that commands entered
during previous sessions are not lost.
The
Octave distribution includes a 200+ page Texinfo manual. Access
to the complete text of the manual is available via the help
command at the Octave prompt.
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.
Version
2.0.10 of Octave was released February 6, 1998. Most bugs
reported since version 2.0 was release have been fixed, and
a number of new features have been added. Octave is now much
more compatible with MATLAB.
A
list of user-visible changes in recent versions of Octave
may be found in the file NEWS, distributed in both source
and binary releases of Octave.
Typing
a TAB character (ASCII code 9) on the command line causes
Octave to attempt to complete variable, function, and file
names. Octave uses the text before the cursor as the initial
portion of the name to complete.
For
example, if you type `fu' followed by TAB at
the Octave prompt, Octave will complete the rest of the name
`function' on the command line (unless you have
other variables or functions defined that begin with the characters
`fu'). If there is more than one possible completion,
Octave will ring the terminal bell to let you know that your
initial sequence of characters is not enough to specify a
unique name. To complete the name, you may either edit the
initial character sequence (usually adding more characters
until completion is possible) or type another TAB to cause
Octave to display the list of possible completions.
When
running interactively, Octave saves the commands you type
in an internal buffer so that you can recall and edit them.
Emacs and vi editing modes are available with Emacs keybindings
enabled by default.
When
Octave exits, the current command history is saved to the
file `~/.octave_hist', and each time Octave starts,
it inserts the contents of the `~/.octave_hist' file
in the history list so that it is easy to begin working where
you left off.
Octave
includes a limited amount of support for organizing data in
structures. The current implementation uses an associative
array with indices limited to strings, but the syntax is more
like C-style structures. Here are some examples of using data
structures in Octave.
- Elements
of structures can be of any value type.
octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string";
octave:2> x.a
x.a = 1
octave:3> x.b
x.b =
1 2
3 4
octave:4> x.c
x.c = string
- Structures
may be copied.
octave:1> y = x
y =
{
a = 1
b =
1 2
3 4
c = string
s =
0.00000 0.00000 0.00000
0.00000 5.46499 0.00000
0.00000 0.00000 0.36597
u =
-0.40455 -0.91451
-0.91451 0.40455
v =
-0.57605 0.81742
-0.81742 -0.57605
}
- Structure
elements may reference other structures.
octave:1> x.b.d = 3
x.b.d = 3
octave:2> x.b
ans =
{
d = 3
}
octave:3> x.b.d
ans = 3
- Functions
can return structures.
octave:1> function y = f (x)
> y.re = real (x);
> y.im = imag (x);
> endfunction
octave:2> f (rand + rand*I);
ans =
{
im = 0.18033
re = 0.19069
}
- Function
return lists can include structure elements, and they may
be indexed like any other variable.
octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]);
octave:2> x
x =
{
s =
0.00000 0.00000 0.00000
0.00000 5.46499 0.00000
0.00000 0.00000 0.36597
u =
-0.40455 -0.91451
-0.91451 0.40455
v =
-0.57605 0.81742
-0.81742 -0.57605
}
- You
can also use the function
is_struct to determine
whether a given value is a data structure. For example
is_struct (x)
returns 1 if the value of the variable x is a
data structure.
This
feature should be considered experimental, but you should
expect it to work. Suggestions for ways to improve it are
welcome.
Octave's
`&&' and `||' logical operators
are evaluated in a short-circuit fashion (like the corresponding
operators in the C language) and work differently than the
element by element operators `&' and `|'.
Octave
includes the C-like increment and decrement operators `++'
and `--' in both their prefix and postfix forms.
For
example, to pre-increment the variable x, you would
write ++x. This would add one to x
and then return the new value of x as the result
of the expression. It is exactly the same as the expression
x = x + 1.
To
post-increment a variable x, you would write x++.
This adds one to the variable x, but returns the
value that x had prior to incrementing it. For
example, if x is equal to 2, the result of the
expression x++ is 2, and the new value
of x is 3.
For
matrix and vector arguments, the increment and decrement operators
work on each element of the operand.
It
is not currently possible to increment index expressions.
For example, you might expect that the expression v(4)++
would increment the fourth element of the vector v,
but instead it results in a parse error. This problem may
be fixed in a future release of Octave.
Octave
supports a limited form of exception handling modelled after
the unwind-protect form of Lisp. The general form of an unwind_protect
block looks like this:
unwind_protect
body
unwind_protect_cleanup
cleanup
end_unwind_protect
Where
body and cleanup are both optional and
may contain any Octave expressions or commands. The statements
in cleanup are guaranteed to be executed regardless
of how control exits body.
The
unwind_protect statement is often used to reliably
restore the values of global variables that need to be temporarily
changed.
Octave
has a real mechanism for handling functions that take an unspecified
number of arguments, so it is no longer necessary to place
an upper bound on the number of optional arguments that a
function can accept.
Here
is an example of a function that uses the new syntax to print
a header followed by an unspecified number of values:
function foo (heading, ...)
disp (heading);
va_start ();
while (--nargin)
disp (va_arg ());
endwhile
endfunction
Calling
va_start() positions an internal pointer to the
first unnamed argument and allows you to cycle through the
arguments more than once. It is not necessary to call va_start()
if you do not plan to cycle through the arguments more than
once.
The
function va_arg() returns the value of the next
available argument and moves the internal pointer to the next
argument. It is an error to call va_arg() when
there are no more arguments available.
It
is also possible to use the keyword all_va_args
to pass all unnamed arguments to another function.
Octave
also has a real mechanism for handling functions that return
an unspecified number of values, so it is no longer necessary
to place an upper bound on the number of outputs that a function
can produce.
Here
is an example of a function that uses the new syntax to produce
`N' values:
function [...] = foo (n)
for i = 1:n
vr_val (i);
endfor
endfunction
Octave
includes LSODE and DASSL for solving systems of stiff ordinary
differential and differential-algebraic equations. These functions
are built in to the interpreter.
The
Octave distribution includes a 220+ page manual that is also
distributed under the terms of the GNU GPL.
The
Octave manual is intended to be a complete reference for Octave,
but it is not a finished document. If you have problems using
it, or find that some topic is not adequately explained, indexed,
or cross-referenced, please send a bug report to bug-octave@bevo.che.wisc.edu.
Because
the Octave manual is written using Texinfo, the complete text
of the Octave manual is also available on line using the GNU
Info system via the GNU Emacs, info, or xinfo programs, or
by using the `help -i' command to start the GNU
info browser directly from the Octave prompt.
It
is also possible to use your favorite WWW browser to read
the Octave manual by converting the Texinfo source to HTML
using the texi2html program.
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).
Octave
was not developed by the FSF, but the FSF does distribute
Octave, and the developers of Octave support the efforts of
the FSF by encouraging users of Octave to order Octave on
CD-ROM directly from the FSF.
The
FSF is a nonprofit organization that distributes software
and manuals to raise funds for more GNU development. Buying
a CD-ROM from the FSF contributes directly to paying staff
to develop GNU software. CD-ROMs cost $240 if an organization
is buying, or $60 if an individual is buying.
For
more information about ordering from the FSF, contact gnu@gnu.org,
phone (617) 542-5942 or anonymous ftp the file `/pub/gnu/GNUinfo/ORDERS'
from ftp.gnu.org.
If
you are on the Internet, you can copy the latest distribution
version of Octave from the file `/pub/octave/octave-M.N.tar.gz',
on the host `ftp.che.wisc.edu'. This tar file has
been compressed with GNU gzip, so be sure to use binary mode
for the transfer. `M' and `N' stand
for version numbers; look at a listing of the directory through
ftp to see what version is available. After you unpack the
distribution, be sure to look at the files `README'
and `INSTALL'.
Binaries
for several popular systems are also available. If you would
like help out by making binaries available for other systems,
please contact bug-octave@bevo.che.wisc.edu.
A
list of user-visible changes since the last release is available
in the file `NEWS'. The file `ChangeLog'
in the source distribution contains a more detailed record
of changes made since the last release.
Octave
currently runs on Unix-like systems, OS/2, and Windows NT/95
(using the gnu-win32 tools from Cygnus Support). 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@bevo.che.wisc.edu.
The
latest version of Octave is 2.0.10, released February 6, 1998.
Octave
requires approximately 125MB of disk storage to unpack and
compile from source (significantly less if you don't compile
with debugging symbols or create shared libraries). Once installed,
Octave requires approximately 65MB of disk space (again, considerably
less if you don't build shared libraries or the binaries and
libraries do not include debugging symbols).
To
compile Octave, you will need a recent version of GNU Make.
You will also need g++ 2.7.2 or later. Version 2.8.0 or egcs
1.0.x should work. Later versions may work, but C++ is still
evolving, so don't be too surprised if you run into some trouble.
It
is no longer necessary to have libg++, but you do need to
have the GNU implementation of libstdc++. If you are using
g++ 2.7.2, libstdc++ is distributed along with libg++, but
for later versions, libstdc++ is distributed separately. For
egcs, libstdc++ is included with the compiler distribution.
<em>You
must have gnu make to compile octave</em>. Octave's
Makefiles use features of GNU Make that are not present in
other versions of make. GNU Make is very portable and easy
to install.
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@bevo.che.wisc.edu.
This
list is probably far too short. Feel free to suggest additional
questions (preferably with answers!)
- Octave
takes a long time to find symbols. Octave is probably spending
this time recursively searching directories for function
files. Check the value of your LOADPATH. For those elements
that end in `//', do any name a very large
directory tree? Does it contain directories that have a
mixture of files and directories? In order for the recursive
directory searching code to work efficiently, directories
that are to be searched recursively should have either function
files only, or subdirectories only, but not a mixture of
both. Check to make sure that Octave's standard set of function
files is installed this way.
The
mailing list
help-octave@bevo.che.wisc.edu
is
available for questions related to using, installing, and
porting Octave that are not adequately answered by the Octave
manual or by this document.
If
you would like to join the discussion and receive all messages
sent to the list, please send a short note to
help-octave-request@bevo.che.wisc.edu
^^^^^^^
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 ftp.che.wisc.edu in the directory `/pub/octave/MAILING-LISTS'.
"I
think I have found a bug in Octave, but I'm not sure. How
do I know, and who should I tell?"
First,
see the section on bugs and bug reports in the Octave manual.
The Octave manual is included in the Octave distribution.
When
you report a bug, make sure to describe the type of computer
you are using, the version of the operating system it is running,
and the version of Octave that you are using. Also provide
enough code so that the Octave maintainers can duplicate your
bug.
If
you have Octave working at all, the easiest way to do this
is to use the Octave function bug_report. When
you execute this function, Octave will prompt you for a subject
and then invoke the editor on a file that already contains
all the configuration information. When you exit the editor,
Octave will mail the bug report for you.
If
for some reason you cannot use Octave's bug_report
function, mail your bug report to "bug-octave@bevo.che.wisc.edu".
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.
"I
wrote some code for MATLAB, and I want to get it running under
Octave. Is there anything I should watch out for?"
The
differences between Octave and MATLAB typically fall into
one of three categories:
- Irrelevant.
- Known
differences, perhaps configurable with a user preference
variable.
- Unknown
differences.
The
first category, irrelevant differences, do not affect computations
and most likely do not affect the execution of function files.
The
differences of the second category are usually because the
authors of Octave decided on a better (subjective) implementation
that the way MATLAB does it, and so introduced "user preference
variables" so that you can customize Octave's behavior to
be either MATLAB-compatible or to use Octave's new features.
To make Octave more MATLAB-compatible, put the following statements
in your `~/.octaverc' file, or use the command line
option `--traditional', which implies all of
these settings. Note that this list may not be complete, because
some new variables may have been introduced since this document
was last updated.
PS1 = ">> "
PS2 = ""
beep_on_error = 1.0
default_eval_print_flag = 0.0
default_save_format = "mat-binary"
define_all_return_values = 1.0
do_fortran_indexing = 1.0
empty_list_elements_ok = 1.0
fixed_point_format = 1.0
implicit_num_to_str_ok = 1.0
implicit_str_to_num_ok = 1.0
ok_to_lose_imaginary_part = 1.0
page_screen_output = 0.0
prefer_column_vectors = 0.0
prefer_zero_one_indexing = 1.0
print_empty_dimensions = 0.0
treat_neg_dim_as_zero = 1.0
warn_function_name_clash = 0.0
whitespace_in_literal_matrix = "traditional"
Some
other known differences are:
- The
Octave plotting functions are mostly compatible with the
ones from MATLAB 3.x, but not from MATLAB 4.x.
The
third category of differences is (hopefully) shrinking. If
you find a difference between Octave behavior and MATLAB,
then you should send a description of this difference (with
code illustrating the difference, if possible) to bug-octave@bevo.che.wisc.edu.
An
archive of old postings to the Octave mailing lists is maintained
on ftp.che.wisc.edu in the directory `/pub/octave/MAILING-LISTS'.
a
Additional
help
Argument
lists, variable-length
b
Boolean
operators, short-circuit
Bug
in Octave, newly found
c
Command
completion
Command
history
Compatibility
with MATLAB
d
DASSL
Data
structures
Decrement
operators
DJGPP
e
EMX
f
Flex
FSF
[Free Software Foundation]
#IDX30
Function
name completion
g
GNU
[GNU's not unix]
GNU
Bison
GNU
g++
GNU
gcc
GNU
Make
GNUware,
anonymous FTP sites
h
History
i
Increment
operators
l
libg++
Logical
operators, short-circuit
LSODE
m
Mailing
lists, bug-octave
Mailing
lists, help-octave
Manual,
for Octave
MATLAB
compatibility
MS-DOS
support
n
Name
completion
o
Octave
bug report
Octave,
building
Octave,
documentation
Octave,
getting a copy
Octave,
ordering
Octave,
version date
Operators,
boolean
Operators,
decrement
Operators,
increment
OS/2
support
r
Return
lists, variable-length
s
Short-circuit
boolean operators
Source
code
Structures
u
Unwind-protect
v
Variable
name completion
Variable-length
argument lists
Variable-length
return lists
VAX
VMS
support
w
Windows
support
Footnotes
MATLAB
is a registered trademark of The MathWorks, Inc.
|
