Octave was originally intended to be companion software for an undergraduate-level textbook on chemical reactor design being written by James B. Rawlings of the University of Wisconsin-Madison and John G. Ekerdt of the University of Texas.
Clearly, Octave is now much more than just another `courseware' package with limited utility beyond the classroom. Although our initial goals were somewhat vague, we knew that we wanted to create something that would enable students to solve realistic problems, and that they could use for many things other than chemical reactor design problems.
There are those who would say that we should be teaching the students Fortran instead, because that is the computer language of engineering, but every time we have tried that, the students have spent far too much time trying to figure out why their Fortran code crashes and not enough time learning about chemical engineering. With Octave, most students pick up the basics quickly, and are using it confidently in just a few hours.
Although it was originally intended to be used to teach reactor design, it has been used in several other undergraduate and graduate courses in the Chemical Engineering Department at the University of Texas, and the math department at the University of Texas has been using it for teaching differential equations and linear algebra as well. If you find it useful, please let us know. We are always interested to find out how Octave is being used in other places.
Virtually everyone thinks that the name Octave has something to do with music, but it is actually the name of a former professor of mine who wrote a famous textbook on chemical reaction engineering, and who was also well known for his ability to do quick `back of the envelope' calculations. We hope that this software will make it possible for many people to do more ambitious computations just as easily.
Everyone is encouraged to share this software with others under the terms of the GNU General Public License (see section GNU GENERAL PUBLIC LICENSE) as described at the beginning of this manual. You are also encouraged to help make Octave more useful by writing and contributing additional functions for it, and by reporting any problems you may have.
Many people have already contributed to Octave's development. In addition to John W. Eaton, the following people have helped write parts of Octave or helped out in various other ways.
popen
, pclose
, execute
, sync_system
, and
async_system
.
kpathsea
library
that allows Octave to recursively search directory paths for function
and script files.
readline
library
used for command history editing, and the portion of this manual that
documents it.
expm
, qzval
, qzhess
,
syl
, lyap
, and balance
.
corrcoef
, cov
, fftconv
, fftfilt
, gcd
,
lcd
, kurtosis
, null
, orth
, poly
,
polyfit
, roots
, and skewness
functions, supplied
documentation for these and numerous other functions, rewrote the Emacs
mode for editing Octave code and provided its documentation, and has
helped tremendously with testing. He has also been a constant source of
new ideas for improving Octave.
mahalanobis
function.
fread
, fwrite
, feof
, and
ferror
.
hess
and schur
functions.
gls
and ols
.
lin2mu
, loadaudio
, mu2lin
,
playaudio
, record
, saveaudio
, and setaudio
.
fft
and
ifft
functions and valuable bug reports for early versions.
Special thanks to the following people and organizations for supporting the development of Octave:
This project would not have been possible without the GNU software used in and used to produce Octave.
There are a number of ways that you can contribute to help make Octave a better system. Perhaps the most important way to contribute is to write high-quality code for solving new problems, and to make your code freely available for others to use.
If you find Octave useful, consider providing additional funding to continue its development. Even a modest amount of additional funding could make a significant difference in the amount of time that is available for development and support.
If you cannot provide funding or contribute code, you can still help make Octave better and more reliable by reporting any bugs you find and by offering suggestions for ways to improve Octave. See section Known Causes of Trouble, for tips on how to write useful bug reports.
Octave is free software. This means that everyone is free to use it and free to redistribute it on certain conditions. Octave is not in the public domain. It is copyrighted and there are restrictions on its distribution, but the restrictions are designed to ensure that others will have the same freedom to use and redistribute Octave that you have. The precise conditions can be found in the GNU General Public License that comes with Octave and that also appears in section GNU GENERAL PUBLIC LICENSE.
Octave is available on CD-ROM with various collections of other free software, and from the Free Software Foundation. Ordering a copy of Octave from the Free Software Foundation helps to fund the development of more free software. For more information, write to
Free Software Foundation
59 Temple Place--Suite 330
Boston, MA 02111--1307
USA
Octave is also available on the Internet from
ftp://ftp.che.wisc.edu/pub/octave
, and additional information is
available from http://www.che.wisc.edu/octave
.
This manual documents how to run, install and port GNU Octave, and how to report bugs.
GNU Octave is a high-level language, primarily intended for numerical computations. It provides a convenient command line interface for solving linear and nonlinear problems numerically, and for performing other numerical experiments. It may also be used as a batch-oriented language.
GNU Octave is also freely redistributable software. You may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. The GPL is included in this manual in section GNU GENERAL PUBLIC LICENSE.
This document corresponds to Octave version 2.0.5.
On most systems, the way to invoke Octave is with the shell command `octave'. Octave displays an initial message and then a prompt indicating it is ready to accept input. You can begin typing Octave commands immediately afterward.
If you get into trouble, you can usually interrupt Octave by typing Control-C (usually written C-c for short). C-c gets its name from the fact that you type it by holding down CTRL and then pressing c. Doing this will normally return you to Octave's prompt.
To exit Octave, type quit, or exit at the Octave prompt.
On systems that support job control, you can suspend Octave by sending
it a SIGTSTP
signal, usually by typing C-z.
The following chapters describe all of Octave's features in detail, but before doing that, it might be helpful to give a sampling of some of its capabilities.
If you are new to Octave, I recommend that you try these examples to begin learning Octave by using it. Lines marked with `octave:13>' are lines you type, ending each with a carriage return. Octave will respond with an answer, or by displaying a graph.
To create a new matrix and store it in a variable so that it you can refer to it later, type the command
octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]
Octave will respond by printing the matrix in neatly aligned columns. Ending a command with a semicolon tells Octave to not print the result of a command. For example
octave:2> b = rand (3, 2);
will create a 3 row, 2 column matrix with each element set to a random value between zero and one.
To display the value of any variable, simply type the name of the
variable. For example, to display the value stored in the matrix
b
, type the command
octave:3> b
Octave has a convenient operator notation for performing matrix
arithmetic. For example, to multiply the matrix a
by a scalar
value, type the command
octave:4> 2 * a
To multiply the two matrices a
and b
, type the command
octave:5> a * b
To form the matrix product type the command
octave:6> a' * a
To solve the set of linear equations ax = b
,
use the left division operator, `\':
octave:7> a \ b
This is conceptually equivalent to but avoids computing the inverse of a matrix directly.
If the coefficient matrix is singular, Octave will print a warning message and compute a minimum norm solution.
Octave has built-in functions for solving nonlinear differential equations of the form
For Octave to integrate equations of this form, you must first provide a definition of the function This is straightforward, and may be accomplished by entering the function body directly on the command line. For example, the following commands define the right hand side function for an interesting pair of nonlinear differential equations. Note that while you are entering a function, Octave responds with a different prompt, to indicate that it is waiting for you to complete your input.
octave:8> function xdot = f (x, t) > > r = 0.25; > k = 1.4; > a = 1.5; > b = 0.16; > c = 0.9; > d = 0.8; > > xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); > xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); > > endfunction
Given the initial condition
x0 = [1; 2];
and the set of output times as a column vector (note that the first output time corresponds to the initial condition given above)
t = linspace (0, 50, 200)';
it is easy to integrate the set of differential equations:
x = lsode ("f", x0, t);
The function lsode
uses the Livermore Solver for Ordinary
Differential Equations, described in A. C. Hindmarsh, ODEPACK, a
Systematized Collection of ODE Solvers, in: Scientific Computing, R. S.
Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55--64.
To display the solution of the previous example graphically, use the command
plot (t, x)
If you are using the X Window System, Octave will automatically create a separate window to display the plot. If you are using a terminal that supports some other graphics commands, you will need to tell Octave what kind of terminal you have. Type the command
gset term
to see a list of the supported terminal types. Octave uses
gnuplot
to display graphics, and can display graphics on any
terminal that is supported by gnuplot
.
To capture the output of the plot command in a file rather than sending the output directly to your terminal, you can use a set of commands like this
gset term postscript gset output "foo.ps" replot
This will work for other types of output devices as well. Octave's
gset
command is really just piped to the gnuplot
subprocess, so that once you have a plot on the screen that you like,
you should be able to do something like this to create an output file
suitable for your graphics printer.
Or, you can eliminate the intermediate file by using commands like this
gset term postscript gset output "|lpr -Pname_of_your_graphics_printer" replot
At the Octave prompt, you can recall, edit, and reissue previous commands using Emacs- or vi-style editing commands. The default keybindings use Emacs-style commands. For example, to recall the previous command, type Control-p (usually written C-p for short). C-p gets its name from the fact that you type it by holding down CTRL and then pressing p. Doing this will normally bring back the previous line of input. C-n will bring up the next line of input, C-b will move the cursor backward on the line, C-f will move the cursor forward on the line, etc.
A complete description of the command line editing capability is given in this manual in section Command Line Editing.
Octave has an extensive help facility. The same documentation that is available in printed form is also available from the Octave prompt, because both forms of the documentation are created from the same input file.
In order to get good help you first need to know the name of the command
that you want to use. This name of the function may not always be
obvious, but a good place to start is to just type help
.
This will show you all the operators, reserved words, functions,
built-in variables, and function files. You can then get more
help on anything that is listed by simply including the name as an
argument to help. For example,
help plot
will display the help text for the plot
function.
Octave sends output that is too long to fit on one screen through a
pager like less
or more
. Type a RET to advance one
line, a SPC to advance one page, and q to exit the pager.
The part of Octave's help facility that allows you to read the complete text of the printed manual from within Octave normally uses a separate program called Info. When you invoke Info you will be put into a menu driven program that contains the entire Octave manual. Help for using Info is provided in this manual in section Commands for Getting Help.
This section explains the notational conventions that are used in this manual. You may want to skip this section and refer back to it later.
Examples of Octave code appear in this font or form: svd (a)
.
Names that represent arguments or metasyntactic variables appear
in this font or form: first-number. Commands that you type at the
shell prompt sometimes appear in this font or form:
`octave --no-init-file'. Commands that you type at the Octave
prompt sometimes appear in this font or form: foo --bar --baz.
Specific keys on your keyboard appear in this font or form: ANY.
In the examples in this manual, results from expressions that you evaluate are indicated with `=>'. For example,
sqrt (2) => 1.4142
You can read this as "sqrt (2)
evaluates to 1.4142".
In some cases, matrix values that are returned by expressions are displayed like this
[1, 2; 3, 4] == [1, 3; 2, 4] => [ 1, 0; 0, 1 ]
and in other cases, they are displayed like this
eye (3) => 1 0 0 0 1 0 0 0 1
in order to clearly show the structure of the result.
Sometimes to help describe one expression, another expression is shown that produces identical results. The exact equivalence of expressions is indicated with `=='. For example,
rot90 ([1, 2; 3, 4], -1) == rot90 ([1, 2; 3, 4], 3) == rot90 ([1, 2; 3, 4], 7)
Many of the examples in this manual print text when they are
evaluated. Examples in this manual indicate printed text with
`-|'. The value that is returned by evaluating the
expression (here 1
) is displayed with `=>' and
follows on a separate line.
printf ("foo %s\n", "bar") -| foo bar => 1
Some examples signal errors. This normally displays an error message
on your terminal. Error messages are shown on a line starting with
error:
.
struct_elements ([1, 2; 3, 4]) error: struct_elements: wrong type argument `matrix'
Functions, commands, and variables are described in this manual in a uniform format. The first line of a description contains the name of the item followed by its arguments, if any. The category--function, variable, or whatever--is printed next to the right margin. The description follows on succeeding lines, sometimes with examples.
In a function description, the name of the function being described appears first. It is followed on the same line by a list of parameters. The names used for the parameters are also used in the body of the description.
Here is a description of an imaginary function foo
:
foo
subtracts x from y, then adds the
remaining arguments to the result. If y is not supplied, then the
number 19 is used by default.
foo (1, [3, 5], 3, 9) => [ 14, 16 ] foo (5) => 14
More generally,
foo (w, x, y, ...) == x - w + y + ...
Any parameter whose name contains the name of a type (e.g., integer, integer1 or matrix) is expected to be of that type. Parameters named object may be of any type. Parameters with other sorts of names (e.g., new_file) are discussed specifically in the description of the function. In some sections, features common to parameters of several functions are described at the beginning.
Functions in Octave may be defined in several different ways. The catagory name for functions may include another name that indicates the way that the function is defined. These additional tags include
Command descriptions have a format similar to function descriptions,
except that the word `Function' is replaced by `Command. Commands are
functions that may called without surrounding their arguments in
parentheses. For example, here is the description for Octave's
cd
command:
A variable is a name that can hold a value. Although any variable can be set by the user, built-in variables typically exist specifically so that users can change them to alter the way Octave behaves (built-in variables are also sometimes called user options). Ordinary variables and built-in variables are described using a format like that for functions except that there are no arguments.
Here is a description of the imaginary variable
do_what_i_mean_not_what_i_say
.
Other variable descriptions have the same format, but `Built-in Variable' is replaced by `Variable', for ordinary variables, or `Constant' for symbolic constants whose values cannot be changed.
This chapter explains some of Octave's basic features, including how to start an Octave session, get help at the command prompt, edit the command line, and write Octave programs that can be executed as commands from your shell.
Normally, Octave is used interactively by running the program `octave' without any arguments. Once started, Octave reads commands from the terminal until you tell it to exit.
You can also specify the name of a file on the command line, and Octave will read and execute the commands from the named file and then exit when it is finished.
You can further control how Octave starts by using the command-line options described in the next section, and Octave itself can remind you of the options available. Type `octave --help' to display all available options and briefly describe their use (`octave -h' is a shorter equivalent).
Here is a complete list of all the command line options that Octave accepts.
--debug
-d
--echo-commands
-x
--exec-path path
OCTAVE_EXEC_PATH
found in the environment, but not any commands
in the system or user startup files that set the built-in variable
EXEC_PATH
.
--help
-h
-?
--info-file filename
OCTAVE_INFO_FILE
found in the environment, but not any commands
in the system or user startup files that set the built-in variable
INFO_FILE
.
--info-program program
OCTAVE_INFO_PROGRAM
found in the environment, but not any
commands in the system or user startup files that set the built-in
variable INFO_PROGRAM
.
--interactive
-i
--no-init-file
--no-line-editing
--no-site-file
--norc
-f
--no-init-file
and --no-site-file
.
--path path
-p path
OCTAVE_PATH
found in the environment, but not any commands in the
system or user startup files that set the built-in variable LOADPATH
.
--silent
--quiet
-q
--traditional
--braindead
PS1 = ">> " PS2 = "" beep_on_error = 1 default_save_format = "mat-binary" define_all_return_values = 1 do_fortran_indexing = 1 crash_dumps_octave_core = 0 empty_list_elements_ok = 1 implicit_str_to_num_ok = 1 ok_to_lose_imaginary_part = 1 page_screen_output = 0 prefer_column_vectors = 0 print_empty_dimensions = 0 treat_neg_dim_as_zero = 1 warn_function_name_clash = 0 whitespace_in_literal_matrix = "traditional"
--verbose
-V
--version
-v
file
Octave also includes several built-in variables that contain information about the command line, including the number of arguments and all of the options.
octave --no-line-editing --silent
argv
would be a list of strings with the elements
--no-line-editing
and --silent
.
If you write an executable Octave script, argv
will contain the
list of arguments passed to the script. see section Executable Octave Programs.
program_invocation_name
is automatically set to the name that was
typed at the shell prompt to run Octave, and the value of
program_name
is automatically set to the final component of
program_invocation_name
. For example, if you typed
`/usr/local/bin/octave' to start Octave,
program_invocation_name
would have the value
"/usr/local/bin/octave"
, and program_name
would
have the value "octave"
.
If executing a script from the command line (e.g., octave foo.m
or using an executable Octave script, the program name is set to the
name of the script. See section Executable Octave Programs for an example of
how to create an executable Octave script.
Here is an example of using these variables to reproduce Octave's command line.
printf ("%s", program_name); for i = 1:nargin printf (" %s", argv(i)); endfor printf ("\n");
See section Index Expressions for an explanation of how to properly index
arrays of strings and substrings in Octave, and See section Defining Functions
for information about the variable nargin
.
When Octave starts, it looks for commands to execute from the following files:
octave-home/share/octave/site/m/startup/octaverc
octave-home/share/octave/version/m/startup/octaverc
~/.octaverc
.octaverc
cd
command in the `~/.octaverc' file will affect the directory that
Octave searches for the file `.octaverc'.
If you start Octave in your home directory, commands from from the file
`~/.octaverc' will only be executed once.
A message will be displayed as each of the startup files is read if you
invoke Octave with the --verbose
option but without the
--silent
option.
Startup files may contain any valid Octave commands, including function definitions.
function print_flops_at_exit () printf ("\n%s\n", system ("fortune")); fflush (stdout); endfunction atexit ("print_flops_at_exit");
will print a message when Octave exits.
The entire text of this manual is available from the Octave prompt via the command help -i. In addition, the documentation for individual user-written functions and variables is also available via the help command. This section describes the commands used for reading the manual and the documentation strings for user-supplied functions and variables. See section Function Files, for more information about how to document the functions you write.
help
command can be used to print brief usage-style
messages, or to display information directly from an on-line version of
the printed manual, using the GNU Info browser. If invoked without any
arguments, help
prints a list of all the available operators,
functions, and built-in variables. If the first argument is -i
,
the help
command searches the index of the on-line version of
this manual for the given topics.
For example, the command help help prints a short message
describing the help
command, and help -i help starts the
GNU Info browser at this node in the on-line version of the manual.
Once the GNU Info browser is running, help for using it is available using the command C-h.
The help command can give you information about operators, but not the comma and semicolons that are used as command separators. To get help for those, you must type help comma or help semicolon.
INFO_FILE
names the location of the Octave info file.
The default value is "octave-home/info/octave.info"
, where
octave-home is the directory where all of Octave is installed.
INFO_PROGRAM
names the info program to run. Its
initial value is
"octave-home/libexec/octave/version/exec/arch/info"
,
where octave-home is the directory where all of Octave is
installed, version is the Octave version number, and arch is
the machine type. The value of INFO_PROGRAM
can be overridden by
the environment variable OCTAVE_INFO_PROGRAM
, or the command line
argument --info-program NAME
, or by setting the value of the
built-in variable INFO_PROGRAM
in a startup script.
suppress_verbose_help_message
is nonzero, Octave
will not add additional help information to the end of the output from
the help
command and usage messages for built-in commands.
Octave uses the GNU readline library to provide an extensive set of command-line editing and history features. Only the most common features are described in this manual. Please see The GNU Readline Library manual for more information.
To insert printing characters (letters, digits, symbols, etc.), simply type the character. Octave will insert the character at the cursor and advance the cursor forward.
Many of the command-line editing functions operate using control characters. For example, the character Control-a moves the cursor to the beginning of the line. To type C-a, hold down CTRL and then press a. In the following sections, control characters such as Control-a are written as C-a.
Another set of command-line editing functions use Meta characters. On some terminals, you type M-u by holding down META and pressing u. If your terminal does not have a META key, you can still type Meta charcters using two-character sequences starting with ESC. Thus, to enter M-u, you could type ESCu. The ESC character sequences are also allowed on terminals with real Meta keys. In the following sections, Meta characters such as Meta-u are written as M-u.
The following commands allow you to position the cursor.
The above table describes the most basic possible keystrokes that you need in order to do editing of the input line. On most terminals, you can also use the arrow keys in place of C-f and C-b to move forward and backward.
Notice how C-f moves forward a character, while M-f moves forward a word. It is a loose convention that control keystrokes operate on characters while meta keystrokes operate on words.
There is also a function available so that you can clear the screen from within Octave programs.
Killing text means to delete the text from the line, but to save it away for later use, usually by yanking it back into the line. If the description for a command says that it `kills' text, then you can be sure that you can get the text back in a different (or the same) place later.
Here is the list of commands for killing text.
And, here is how to yank the text back into the line. Yanking means to copy the most-recently-killed text from the kill buffer.
When you use a kill command, the text is saved in a kill-ring. Any number of consecutive kills save all of the killed text together, so that when you yank it back, you get it in one clean sweep. The kill ring is not line specific; the text that you killed on a previously typed line is available to be yanked back later, when you are typing another line.
The following commands can be used for entering characters that would otherwise have a special meaning (e.g., TAB, C-q, etc.), or for quickly correcting typing mistakes.
The following commands allow Octave to complete command and variable names for you.
completion_append_char
is used as the character to
append to successful command-line completion attempts. The default
value is " "
(a single space).
This function is provided for the benefit of programs like Emacs which might be controlling Octave and handling user input. The current command number is not incremented when this function is called. This is a feature, not a bug.
Octave normally keeps track of the commands you type so that you can
recall previous commands to edit or execute them again. When you exit
Octave, the most recent commands you have typed, up to the number
specified by the variable history_size
, are saved in a file.
When Octave starts, it loads an initial list of commands from the file
named by the variable history_file
.
Here are the commands for simple browsing and searching the history list.
On most terminals, you can also use the arrow keys in place of C-p and C-n to move through the history list.
In addition to the keyboard commands for moving through the history list, Octave provides three functions for viewing, editing, and re-running chunks of commands from the history list.
history
displays a list of commands
that you have executed. Valid options are:
-w file
-r file
N
-q
For example, to display the five most recent commands that you have typed without displaying line numbers, use the command history -q 5.
edit_history
allows you to edit the
history list using the editor named by the variable EDITOR
. The
commands to be edited are first copied to a temporary file. When you
exit the editor, Octave executes the commands that remain in the file.
It is often more convenient to use edit_history
to define functions
rather than attempting to enter them directly on the command line.
By default, the block of commands is executed as soon as you exit the
editor. To avoid executing any commands, simply delete all the lines
from the buffer before exiting the editor.
The edit_history
command takes two optional arguments specifying
the history numbers of first and last commands to edit. For example,
the command
edit_history 13
extracts all the commands from the 13th through the last in the history list. The command
edit_history 13 169
only extracts commands 13 through 169. Specifying a larger number for the first command than the last command reverses the list of commands before placing them in the buffer to be edited. If both arguments are omitted, the previous command in the history list is used.
edit_history
, except that the editor is not invoked,
and the commands are simply executed as they appear in the history list.
edit_history
command.
If the environment variable EDITOR
is set when Octave starts, its
value is used as the default. Otherwise, EDITOR
is set to
"emacs"
.
"~/.octave_hist"
, but may be
overridden by the environment variable OCTAVE_HISTFILE
.
1024
, but may be overridden by the
environment variable OCTAVE_HISTSIZE
.
saving_history
is nonzero, command entered
on the command line are saved in the file specified by the variable
history_file
.
The following variables are available for customizing the appearance of the command-line prompts. Octave allows the prompt to be customized by inserting a number of backslash-escaped special characters that are decoded as follows:
PS1
when it is ready to read a
command.
The default value of PS1
is "\s:\#> "
. To change it, use a
command like
octave:13> PS1 = "\\u@\\H> "
which will result in the prompt `boris@kremvax> ' for the user `boris' logged in on the host `kremvax.kgb.su'. Note that two backslashes are required to enter a backslash into a string. See section Strings.
PS1
at the beginning of each line after the first. The default
value of PS2
is "> "
.
--echo-input
option, the value of
PS4
is printed before each line of input that is echoed. The
default value of PS4
is "+ "
. See section Invoking Octave, for
a description of --echo-input
.
Octave's diary feature allows you to keep a log of all or part of an interactive session by recording the input you type and the output that Octave produces in a separate file.
on
off
file
Without any arguments, diary
toggles the current diary state.
Sometimes it is useful to see the commands in a function or script as they are being evaluated. This can be especially helpful for debugging some kinds of problems.
on
off
on all
off all
If invoked without any arguments, echo
toggles the current echo
state.
More than one state can be active at once. For example, a value of 3 is equivalent to the command echo on all.
The value of echo_executing_commands
is set by the echo
command and the command line option --echo-input
.
Octave reports two kinds of errors for invalid programs.
A parse error occurs if Octave cannot understand something you have typed. For example, if you misspell a keyword,
octave:13> functon y = f (x) y = x^2; endfunction
Octave will respond immediately with a message like this:
parse error: functon y = f (x) y = x^2; endfunction ^
For most parse errors, Octave uses a caret (`^') to mark the point
on the line where it was unable to make sense of your input. In this
case, Octave generated an error message because the keyword
function
was misspelled. Instead of seeing `function f',
Octave saw two consecutive variable names, which is invalid in this
context. It marked the error at the y
because the first name by
itself was accepted as valid input.
Another class of error message occurs at evaluation time. These errors are called run-time errors, or sometimes evaluation errors because they occur when your program is being run, or evaluated. For example, if after correcting the mistake in the previous function definition, you type
octave:13> f ()
Octave will respond with
error: `x' undefined near line 1 column 24 error: evaluating expression near line 1, column 24 error: evaluating assignment expression near line 1, column 22 error: called from `f'
This error message has several parts, and gives you quite a bit of information to help you locate the source of the error. The messages are generated from the point of the innermost error, and provide a traceback of enclosing expressions and function calls.
In the example above, the first line indicates that a variable named `x' was found to be undefined near line 1 and column 24 of some function or expression. For errors occurring within functions, lines from the beginning of the file containing the function definition. For errors occurring at the top level, the line number indicates the input line number, which is usually displayed in the prompt string.
The second and third lines in the example indicate that the error
occurred within an assignment expression, and the last line of the error
message indicates that the error occurred within the function f
.
If the function f
had been called from another function, for
example, g
, the list of errors would have ended with one more
line:
error: called from `g'
These lists of function calls usually make it fairly easy to trace the path your program took before the error occurred, and to correct the error before trying again.
Once you have learned Octave, you may want to write self-contained Octave scripts, using the `#!' script mechanism. You can do this on GNU systems and on many Unix systems (1)
For example, you could create a text file named `hello', containing the following lines:
#! octave-interpreter-name -qf # a sample Octave program printf ("Hello, world!\n");
(where octave-interpreter-name should be replaced with the full
file name for your Octave binary). After making this file executable
(with the chmod
command), you can simply type:
hello
at the shell, and the system will arrange to run Octave as if you had typed:
octave hello
The line beginning with `#!' lists the full file name of an interpreter to be run, and an optional initial command line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument in the list is the full file name of the Octave program. The rest of the argument list will either be options to Octave, or data files, or both. The `-qf' option is usually specified in stand-alone Octave programs to prevent them from printing the normal startup message, and to keep them from behaving differently depending on the contents of a particular user's `~/.octaverc' file. See section Invoking Octave. Note that some operating systems may place a limit on the number of characters that are recognized after `#!'.
Self-contained Octave scripts are useful when you want to write a program which users can invoke without knowing that the program is written in the Octave language.
If you invoke an executable Octave script with command line arguments,
the arguments are available in the built-in variable argv
.
See section Command Line Options. For example, the following program will
reproduce the command line that is used to execute it.
#! /bin/octave -qf printf ("%s", program_name); for i = 1:nargin printf (" %s", argv(i,:)); endfor printf ("\n");
A comment is some text that is included in a program for the sake of human readers, and that is not really part of the program. Comments can explain what the program does, and how it works. Nearly all programming languages have provisions for comments, because programs are typically hard to understand without them.
In the Octave language, a comment starts with either the sharp sign
character, `#', or the percent symbol `%' and continues to the
end of the line. The Octave interpreter ignores the rest of a
line following a sharp sign or percent symbol. For example, we could
have put the following into the function f
:
function xdot = f (x, t) # usage: f (x, t) # # This function defines the right hand # side functions for a set of nonlinear # differential equations. r = 0.25; ... endfunction
The help
command (see section Commands for Getting Help) is able to find the first
block of comments in a function (even those that are composed directly
on the command line). This means that users of Octave can use the same
commands to get help for built-in functions, and for functions that you
have defined. For example, after defining the function f
above,
the command help f produces the output
usage: f (x, t) This function defines the right hand side functions for a set of nonlinear differential equations.
Although it is possible to put comment lines into keyboard-composed throw-away Octave programs, it usually isn't very useful, because the purpose of a comment is to help you or another person understand the program at a later time.
All versions of Octave include a number of built-in data types, including real and complex scalars and matrices, character strings, and a data structure type.
It is also possible to define new specialized data types by writing a small amount of C++ code. On some systems, new data types can be loaded dynamically while Octave is running, so it is not necessary to recompile all of Octave just to add a new type. See section Dynamically Linked Functions for more information about Octave's dynamic linking capabilities. section User-defined Data Types describes what you must do to define a new data type for Octave.
The standard built-in data types are real and complex scalars and matrices, ranges, character strings, and a data structure type. Additional built-in data types may be added in future versions. If you need a specialized data type that is not currently provided as a built-in type, you are encouraged to write your own user-defined data type and contribute it for distribution in a future release of Octave.
Octave's built-in numeric objects include real and complex scalars and
matrices. All built-in numeric data is currently stored as double
precision numbers. On systems that use the IEEE floating point format,
values in the range of approximately
can be stored, and the relative precision is approximately
The exact values are given by the variables realmin
,
realmax
, and eps
, respectively.
Matrix objects can be of any size, and can be dynamically reshaped and resized. It is easy to extract individual rows, columns, or submatrices is using a variety of powerful indexing features. See section Index Expressions.
See section Numeric Data Types, for more information.
A character string in Octave consists of a sequence of characters enclosed in either double-quote or single-quote marks. Internally, Octave currently stores strings as matrices of characters. All the indexing operations that work for matrix objects also work for strings.
See section Strings, for more information.
Octave's data structure type can help you to organize related objects of different types. The current implementation uses an associative array with indices limited to strings, but the syntax is more like C-style structures.
See section Data Structures, for more information.
Someday I hope to expand this to include a complete description of Octave's mechanism for managing user-defined data types. Until this feature is documented here, you will have to make do by reading the code in the `ov.h', `ops.h', and related files from Octave's `src' directory.
The following functions allow you to determine the size of a variable or
expression. These functions are defined for all objects. They return
-1 when the operation doesn't make sense. For example, Octave's
data structure type doesn't have rows or columns, so the rows
and
columns
functions return -1 for structure arguments.
With one input argument and one output argument, the result is returned in a 2 element row vector. If there are two output arguments, the number of rows is assigned to the first, and the number of columns to the second. For example,
size ([1, 2; 3, 4; 5, 6]) => [ 3, 2 ] [nr, nc] = size ([1, 2; 3, 4; 5, 6]) => nr = 3 => nc = 2
If given a second argument of either 1 or 2, size
will return
only the row or column dimension. For example
size ([1, 2; 3, 4; 5, 6], 2) => 2
returns the number of columns in the given matrix.
A numeric constant may be a scalar, a vector, or a matrix, and it may contain complex values.
The simplest form of a numeric constant, a scalar, is a single number that can be an integer, a decimal fraction, a number in scientific (exponential) notation, or a complex number. Note that all numeric constants are represented within Octave in double-precision floating point format (complex constants are stored as pairs of double-precision floating point values). Here are some examples of real-valued numeric constants, which all have the same value:
105 1.05e+2 1050e-1
To specify complex constants, you can write an expression of the form
3 + 4i 3.0 + 4.0i 0.3e1 + 40e-1i
all of which are equivalent. The letter `i' in the previous example stands for the pure imaginary constant, defined as
For Octave to recognize a value as the imaginary part of a complex constant, a space must not appear between the number and the `i'. If it does, Octave will print an error message, like this:
octave:13> 3 + 4 i parse error: 3 + 4 i ^
You may also use `j', `I', or `J' in place of the `i' above. All four forms are equivalent.
It is easy to define a matrix of values in Octave. The size of the matrix is determined automatically, so it is not necessary to explicitly state the dimensions. The expression
a = [1, 2; 3, 4]
results in the matrix
Elements of a matrix may be arbitrary expressions, provided that the dimensions all make sense when combining the various pieces. For example, given the above matrix, the expression
[ a, a ]
produces the matrix
ans = 1 2 1 2 3 4 3 4
but the expression
[ a, 1 ]
produces the error
error: number of rows must match near line 13, column 6
(assuming that this expression was entered as the first thing on line 13, of course).
Inside the square brackets that delimit a matrix expression, Octave looks at the surrounding context to determine whether spaces and newline characters should be converted into element and row separators, or simply ignored, so commands like
[ linspace (1, 2) ]
and
a = [ 1 2 3 4 ]
will work. However, some possible sources of confusion remain. For example, in the expression
[ 1 - 1 ]
the `-' is treated as a binary operator and the result is the scalar 0, but in the expression
[ 1 -1 ]
the `-' is treated as a unary operator and the result is the
vector [ 1, -1 ]
.
Given a = 1
, the expression
[ 1 a' ]
results in the single quote character `'' being treated as a
transpose operator and the result is the vector [ 1, 1 ]
, but the
expression
[ 1 a ' ]
produces the error message
error: unterminated string constant
because to not do so would make it impossible to correctly parse the valid expression
[ a 'foo' ]
For clarity, it is probably best to always use commas and semicolons to
separate matrix elements and rows. It is possible to enforce this style
by setting the built-in variable whitespace_in_literal_matrix
to
"ignore"
.
[m (1)]
or
[ 1, 2, 3, 4 ]
If the value of whitespace_in_literal_matrix
is "ignore"
,
Octave will never insert a comma or a semicolon in a literal matrix
list. For example, the expression [1 2]
will result in an error
instead of being treated the same as [1, 2]
, and the expression
[ 1, 2, 3, 4 ]
will result in the vector [ 1, 2, 3, 4 ]
instead of a matrix.
If the value of whitespace_in_literal_matrix
is "traditional"
,
Octave will convert spaces to a comma between identifiers and `('. For
example, given the matrix
m = [3 2]
the expression
[m (1)]
will be parsed as
[m, (1)]
and will result in
[3 2 1]
and the expression
[ 1, 2, 3, 4 ]
will result in a matrix because the newline character is converted to a semicolon (row separator) even though there is a comma at the end of the first line (trailing commas or semicolons are ignored). This is apparently how MATLAB behaves.
Any other value for whitespace_in_literal_matrix
results in behavior
that is the same as traditional, except that Octave does not
convert spaces to a comma between identifiers and `('. For
example, the expression
[m (1)]
will produce `3'. This is the way Octave has always behaved.
When you type a matrix or the name of a variable whose value is a matrix, Octave responds by printing the matrix in with neatly aligned rows and columns. If the rows of the matrix are too large to fit on the screen, Octave splits the matrix and displays a header before each section to indicate which columns are being displayed. You can use the following variables to control the format of the output.
It is possible to achieve a wide range of output styles by using
different values of output_precision
and
output_max_field_width
. Reasonable combinations can be set using
the format
function. See section Basic Input and Output.
If the value of split_long_rows
is nonzero, Octave will display
the matrix in a series of smaller pieces, each of which can fit within
the limits of your terminal width. Each set of rows is labeled so that
you can easily see which columns are currently being displayed.
For example:
octave:13> rand (2,10) ans = Columns 1 through 6: 0.75883 0.93290 0.40064 0.43818 0.94958 0.16467 0.75697 0.51942 0.40031 0.61784 0.92309 0.40201 Columns 7 through 10: 0.90174 0.11854 0.72313 0.73326 0.44672 0.94303 0.56564 0.82150
The default value of split_long_rows
is nonzero.
Octave automatically switches to scientific notation when values become
very large or very small. This guarantees that you will see several
significant figures for every value in a matrix. If you would prefer to
see all values in a matrix printed in a fixed point format, you can set
the built-in variable fixed_point_format
to a nonzero value. But
doing so is not recommended, because it can produce output that can
easily be misinterpreted.
octave:1> logspace (1, 7, 5)' ans = 1.0e+07 * 0.00000 0.00003 0.00100 0.03162 1.00000
Notice that first value appears to be zero when it is actually 1. For
this reason, you should be careful when setting
fixed_point_format
to a nonzero value.
The default value of fixed_point_format
is 0.
A matrix may have one or both dimensions zero, and operations on empty matrices are handled as described by Carl de Boor in An Empty Exercise, SIGNUM, Volume 25, pages 2--6, 1990 and C. N. Nett and W. M. Haddad, in A System-Theoretic Appropriate Realization of the Empty Matrix Concept, IEEE Transactions on Automatic Control, Volume 38, Number 5, May 1993.
By default, dimensions of the empty matrix are printed along with the
empty matrix symbol, `[]'. The built-in variable
print_empty_dimensions
controls this behavior.
print_empty_dimensions
is nonzero, the
dimensions of empty matrices are printed along with the empty matrix
symbol, `[]'. For example, the expression
zeros (3, 0)
will print
ans = [](3x0)
Empty matrices may also be used in assignment statements as a convenient way to delete rows or columns of matrices. See section Assignment Expressions.
Octave will normally issue a warning if it finds an empty matrix in the
list of elements that make up another matrix. You can use the variable
empty_list_elements_ok
to suppress the warning or to treat it as
an error.
For example, if the value of empty_list_elements_ok
is
nonzero, Octave will ignore the empty matrices in the expression
a = [1, [], 3, [], 5]
and the variable a
will be assigned the value [ 1, 3, 5 ]
.
The default value is "warn"
.
When Octave parses a matrix expression, it examines the elements of the list to determine whether they are all constants. If they are, it replaces the list with a single matrix constant.
propagate_empty_matrices
is nonzero,
functions like inverse
and svd
will return an empty matrix
if they are given one as an argument. The default value is 1.
A range is a convenient way to write a row vector with evenly spaced elements. A range expression is defined by the value of the first element in the range, an optional value for the increment between elements, and a maximum value which the elements of the range will not exceed. The base, increment, and limit are separated by colons (the `:' character) and may contain any arithmetic expressions and function calls. If the increment is omitted, it is assumed to be 1. For example, the range
1 : 5
defines the set of values `[ 1, 2, 3, 4, 5 ]', and the range
1 : 3 : 5
defines the set of values `[ 1, 4 ]'.
Although a range constant specifies a row vector, Octave does not convert range constants to vectors unless it is necessary to do so. This allows you to write a constant like `1 : 10000' without using 80,000 bytes of storage on a typical 32-bit workstation.
Note that the upper (or lower, if the increment is negative) bound on
the range is not always included in the set of values, and that ranges
defined by floating point values can produce surprising results because
Octave uses floating point arithmetic to compute the values in the
range. If it is important to include the endpoints of a range and the
number of elements is known, you should use the linspace
function
instead (see section Special Utility Matrices).
When Octave parses a range expression, it examines the elements of the expression to determine whether they are all constants. If they are, it replaces the range expression with a single range constant.
A string constant consists of a sequence of characters enclosed in either double-quote or single-quote marks. For example, both of the following expressions
"parrot" 'parrot'
represent the string whose contents are `parrot'. Strings in Octave can be of any length.
Since the single-quote mark is also used for the transpose operator (see section Arithmetic Operators) but double-quote marks have no other purpose in Octave, it is best to use double-quote marks to denote strings.
Some characters cannot be included literally in a string constant. You represent them instead with escape sequences, which are character sequences beginning with a backslash (`\').
One use of an escape sequence is to include a double-quote
(single-quote) character in a string constant that has been defined
using double-quote (single-quote) marks. Since a plain double-quote
would end the string, you must use `\"' to represent a single
double-quote character as a part of the string. The backslash character
itself is another character that cannot be included normally. You must
write `\\' to put one backslash in the string. Thus, the string
whose contents are the two characters `"\' may be written
"\"\\"
or '"\\'
. Similarly, the string whose contents are
the two characters `'\' may be written '\'\\'
or "'\\"
.
Another use of backslash is to represent unprintable characters such as newline. While there is nothing to stop you from writing most of these characters directly in a string constant, they may look ugly.
Here is a table of all the escape sequences used in Octave. They are the same as those used in the C programming language.
\\
\"
\'
\a
\b
\f
\n
\r
\t
\v
Strings may be concatenated using the notation for defining matrices. For example, the expression
[ "foo" , "bar" , "baz" ]
produces the string whose contents are `foobarbaz'. See section Numeric Data Types for more information about creating matrices.
sprintf
(see section Formatted Output).
setstr ([97, 98, 99]) => "abc"
s = [ "ab"; "cde" ]; strcat (s, s, s) => "ab ab ab " "cdecdecde"
" "
(a single space). For example,
string_fill_char = "X"; [ "these"; "are"; "strings" ] => "theseXX" "areXXXX" "strings"
Note:
This function is modelled after MATLAB. In Octave, you can create
a matrix of strings by [s_1; ...; s_n]
even if
the strings are not all the same length.
findstr ("ababab", "a") => [ 1, 3, 5 ] findstr ("abababa", "aba", 0) => [ 1, 5 ]
index ("Teststring", "t") => 4
Note: This function does not work for arrays of strings.
rindex ("Teststring", "t") => 6
Note: This function does not work for arrays of strings.
split ("Test string", "t") => "Tes " " s " "ring"
Note: For compatibility with MATLAB, Octave's strcmp function returns 1 if the strings are equal, and 0 otherwise. This is just the opposite of the corresponding C library function.
strrep ("This is a test string", "is", "&%$") => "Th&%$ &%$ a test string"
substr ("This is a test string", 6, 9) => "is a test"
Note: This function is patterned after AWK. You can get the same result by
s (beg : (beg + len - 1))
.
bin2dec ("1110") => 14
dec2bin (14) => "1110"
dec2hex (2748) => "abc"
hex2dec ("12B") => 299 hex2dec ("12b") => 299
toascii ("ASCII") => [ 65, 83, 67, 73, 73 ]
tolower ("MiXeD cAsE 123") => "mixed case 123"
toupper ("MiXeD cAsE 123") => "MIXED CASE 123"
bell = "\a";
assigns the value of the alert character (control-g, ASCII code 7) to
the string variable bell
. If this string is printed, the
system will ring the terminal bell (if it is possible). This is
normally the desired outcome. However, sometimes it is useful to be
able to print the original representation of the string, with the
special characters replaced by their escape sequences. For example,
octave:13> undo_string_escapes (bell) ans = \a
replaces the unprintable alert character with its printable representation.
implicit_num_to_str_ok
is nonzero, implicit
conversions of numbers to their ASCII character equivalents are
allowed when strings are constructed using a mixture of strings and
numbers in matrix notation. Otherwise, an error message is printed and
control is returned to the top level. The default value is 0. For
example,
[ "f", 111, 111 ] => "foo"
implicit_str_to_num_ok
is nonzero, implicit
conversions of strings to their numeric ASCII equivalents are allowed.
Otherwise, an error message is printed and control is returned to the
top level. The default value is 0.
Octave also provides the following character class test functions patterned after the functions in the standard C library. They all operate on string arrays and return matrices of zeros and ones. Elements that are nonzero indicate that the condition was true for the corresponding character in the string array. For example,
isalpha ("!Q@WERT^Y&") => [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]
isalpha
(a)
or isdigit (
) is true).
isupper (a)
or islower (
) is true).
Octave includes 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. For example, the three expressions
x.a = 1 x.b = [1, 2; 3, 4] x.c = "string"
create a structure with three elements. To print the value of the structure, you can type its name, just as for any other variable:
octave:2> x x = { a = 1 b = 1 2 3 4 c = string }
Note that Octave may print the elements in any order.
Structures may be copied.
octave:1> y = x y = { a = 1 b = 1 2 3 4 c = string }
Since structures are themselves values, structure elements may reference
other structures. The following statements change the value of the
element b
of the structure x
to be a data structure
containing the single element d
, which has a value of 3.
octave:1> x.b.d = 3 x.b.d = 3 octave:2> x.b ans = { d = 3 } octave:3> x x = { a = 1 b = { d = 3 } c = string }
Note that when Octave prints the value of a structure that contains other structures, only a few levels are displayed. For example,
octave:1> a.b.c.d.e = 1; octave:2> a a = { b = { c = <structure> } }
This prevents long and confusing output from large deeply nested structures.
struct_levels_to_print
. The default value is 2.
Functions can return structures. For example, the following function separates the real and complex parts of a matrix and stores them in two elements of the same structure variable.
octave:1> function y = f (x) > y.re = real (x); > y.im = imag (x); > endfunction
When called with a complex-valued argument, f
returns the data
structure containing the real and imaginary parts of the original
function argument.
octave:2> f (rand (3) + rand (3) * I); ans = { im = 0.26475 0.14828 0.18436 0.83669 re = 0.040239 0.242160 0.238081 0.402523 }
Function return lists can include structure elements, and they may be indexed like any other variable. For example,
octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) x.u = -0.40455 -0.91451 -0.91451 0.40455 x.s = 0.00000 0.00000 0.00000 0.00000 5.46499 0.00000 0.00000 0.00000 0.36597 x.v = -0.57605 0.81742 -0.81742 -0.57605
It is also possible to cycle through all the elements of a structure in
a loop, using a special form of the for
statement
(see section The for
Statement)
The following functions are available to give you information about structures.
struct_elements
with an
argument that is not a structure.
Variables let you give names to values and refer to them later. You have already seen variables in many of the examples. The name of a variable must be a sequence of letters, digits and underscores, but it may not begin with a digit. Octave does not enforce a limit on the length of variable names, but it is seldom useful to have variables with names longer than about 30 characters. The following are all valid variable names
x x15 __foo_bar_baz__ fucnrdthsucngtagdjb
However, names like __foo_bar_baz__
that begin and end with two
underscores are understood to be reserved for internal use by Octave.
You should not use them in code you write, except to access Octave's
documented internal variables and built-in symbolic constants.
Case is significant in variable names. The symbols a
and
A
are distinct variables.
A variable name is a valid expression by itself. It represents the variable's current value. Variables are given new values with assignment operators and increment operators. See section Assignment Expressions.
A number of variables have special built-in meanings. For example,
ans
holds the current working directory, and pi
names the
ratio of the circumference of a circle to its diameter. See section Summary of Built-in Variables, for a list of all the predefined variables. Some
of these built-in symbols are constants and may not be changed. Others
can be used and assigned just like all other variables, but their values
are also used or changed automatically by Octave.
Variables in Octave do not have fixed types, so it is possible to first store a numeric value in a variable and then to later use the same name to hold a string value in the same program. Variables may not be used before they have been given a value. Doing so results in an error.
A variable that has been declared global may be accessed from within a function body without having to pass it as a formal parameter.
A variable may be declared global using a global
declaration
statement. The following statements are all global declarations.
global a global b = 2 global c = 3, d, e = 5
It is necessary declare a variable as global within a function body in order to access it. For example,
global x function f () x = 1; endfunction f ()
does not set the value of the global variable x
to 1. In
order to change the value of the global variable x
, you must also
declare it to be global within the function body, like this
function f () global x; x = 1; endfunction
Passing a global variable in a function parameter list will make a local copy and not modify the global value. For example, given the function
function f (x) x = 0 endfunction
and the definition of x
as a global variable at the top level,
global x = 13
the expression
f (x)
will display the value of x
from inside the function as 0,
but the value of x
at the top level remains unchanged, because
the function works with a copy of its argument.
warn_comma_in_global_decl
is nonzero, a
warning is issued for statements like
global a = 1, b
which makes the variables a
and b
global and assigns the
value 1 to the variable a
, because in this context, the comma is
not interpreted as a statement separator.
The default value of warn_comma_in_global_decl
is nonzero.
initialize_global_variables
is nonzero, the value of
default_glbaol_variable_value
is used as the initial value of
global variables that are not explicitly initialized. for example,
initialize_global_variables = 1; default_global_variable_value = 13; global foo; foo => 13
the variable default_global_variable_value
is initially undefined.
global x is_global ("x") => 1
?
*
[ list ]
!
or ^
, match all characters except those
specified by list. For example, the pattern `[a-zA-Z]' will
match all lower and upper case alphabetic characters.
For example, the command
clear foo b*r
clears the name foo
and all names that begin with the letter
b
and end with the letter r
.
If clear
is called without any arguments, all user-defined
variables (local and global) are cleared from the symbol table. If
clear
is called with at least one argument, only the visible
names matching the arguments are cleared. For example, suppose you have
defined a function foo
, and then hidden it by performing the
assignment foo = 2
. Executing the command clear foo once
will clear the variable definition and restore the definition of
foo
as a function. Executing clear foo a second time will
clear the function definition.
This command may not be used within a function body.
-all
-builtins
LOADPATH
.
-functions
-long
-variables
Valid patterns are the same as described for the clear
command
above. If no patterns are supplied, all symbols from the given category
are listed. By default, only user defined functions and variables
visible in the local scope are displayed.
The command whos is equivalent to who -long.
Normally also displays if each name is user-defined or builtin;
the -q
option suppresses this behaviour.
Currently, Octave can only display functions that can be compiled cleanly, because it uses its internal representation of the function to recreate the program text.
Comments are not displayed because Octave's parser currently discards them as it converts the text of a function file to its internal representation. This problem may be fixed in a future release.
Here is a summary of all of Octave's built-in variables along with
cross references to additional information and their default values. In
the following table octave-home stands for the root directory
where all of Octave is installed (the default is `/usr/local',
version stands for the Octave version number (for example,
2.0.5) and arch stands for the type of system for which
Octave was compiled (for example, i586-pc-linux-gnu
).
DEFAULT_LOADPATH
".:octave-home/lib/version"
.
EDITOR
"emacs"
.
EXEC_PATH
":$PATH"
.
INFO_FILE
"octave-home/info/octave.info"
.
INFO_PROGRAM
"octave-home/libexec/octave/version/exec/arch/info"
.
LOADPATH
":"
, which tells Octave to use the directories
specified by the built-in variable DEFAULT_LOADPATH
.
OCTAVE_HOME
"/usr/local"
.
PAGER
"less", or "more"
.
PS1
"\s:\#> "
.
PS2
"> "
.
PS4
"+ "
.
auto_unload_dot_oct_files
automatic_replot
beep_on_error
completion_append_char
" "
.
default_eval_print_flag
default_return_value
[]
.
default_save_format
"ascii"
.
do_fortran_indexing
crash_dumps_octave_core
define_all_return_values
empty_list_elements_ok
"warn"
.
fixed_point_format
gnuplot_binary
"gnuplot"
.
history_file
"~/.octave_hist"
.
history_size
ignore_function_time_stamp
"system"
.
implicit_num_to_str_ok
implicit_str_to_num_ok
max_recursion_depth
ok_to_lose_imaginary_part
"warn"
.
output_max_field_width
output_precision
page_screen_output
prefer_column_vectors
print_answer_id_name
print_empty_dimensions
resize_on_range_error
return_last_computed_value
save_precision
saving_history
silent_functions
split_long_rows
struct_levels_to_print
suppress_verbose_help_message
treat_neg_dim_as_zero
warn_assign_as_truth_value
if
Statement.
Default value: 1.
warn_comma_in_global_decl
warn_divide_by_zero
warn_function_name_clash
warn_reload_forces_clear
warn_variable_switch_label
switch
Statement.
Default value: 0.
whitespace_in_literal_matrix
""
.
Octave uses the values of the following environment variables to set the default values for the corresponding built-in variables. In addition, the values from the environment may be overridden by command-line arguments. See section Command Line Options.
EDITOR
EDITOR
.
OCTAVE_EXEC_PATH
EXEC_PATH
.
Command-line argument: --exec-path
.
OCTAVE_PATH
LOADPATH
.
Command-line argument: --path
.
OCTAVE_INFO_FILE
INFO_FILE
.
Command-line argument: --info-file
.
OCTAVE_INFO_PROGRAM
INFO_PROGRAM
.
Command-line argument: --info-program
.
OCTAVE_HISTSIZE
history_size
.
OCTAVE_HISTFILE
history_file
.
Expressions are the basic building block of statements in Octave. An expression evaluates to a value, which you can print, test, store in a variable, pass to a function, or assign a new value to a variable with an assignment operator.
An expression can serve as a statement on its own. Most other kinds of statements contain one or more expressions which specify data to be operated on. As in other languages, expressions in Octave include variables, array references, constants, and function calls, as well as combinations of these with various operators.
An index expression allows you to reference or extract selected elements of a matrix or vector.
Indices may be scalars, vectors, ranges, or the special operator `:', which may be used to select entire rows or columns.
Vectors are indexed using a single expression. Matrices require two
indices unless the value of the built-in variable
do_fortran_indexing
is nonzero, in which case matrices may
also be indexed by a single expression.
do_fortran_indexing
is nonzero, Octave allows
you to select elements of a two-dimensional matrix using a single index
by treating the matrix as a single vector created from the columns of
the matrix. The default value is 0.
Given the matrix
a = [1, 2; 3, 4]
all of the following expressions are equivalent
a (1, [1, 2]) a (1, 1:2) a (1, :)
and select the first row of the matrix.
A special form of indexing may be used to select elements of a matrix or vector. If the indices are vectors made up of only ones and zeros, the result is a new matrix whose elements correspond to the elements of the index vector that are equal to one. For example,
a = [1, 2; 3, 4]; a ([1, 0], :)
selects the first row of the matrix a
.
This operation can be useful for selecting elements of a matrix based on some condition, since the comparison operators return matrices of ones and zeros.
This special zero-one form of indexing leads to a conflict with the standard indexing operation. For example, should the following statements
a = [1, 2; 3, 4]; a ([1, 1], :)
return the original matrix, or the matrix formed by selecting the first
row twice? Although this conflict is not likely to arise very often in
practice, you may select the behavior you prefer by setting the built-in
variable prefer_zero_one_indexing
.
prefer_zero_one_indexing
is nonzero, Octave
will perform zero-one style indexing when there is a conflict with the
normal indexing rules. See section Index Expressions. For example, given a
matrix
a = [1, 2, 3, 4]
with prefer_zero_one_indexing
is set to nonzero, the
expression
a ([1, 1, 1, 1])
results in the matrix [ 1, 2, 3, 4 ]
. If the value of
prefer_zero_one_indexing
set to 0, the result would be
the matrix [ 1, 1, 1, 1 ]
.
In the first case, Octave is selecting each element corresponding to a `1' in the index vector. In the second, Octave is selecting the first element multiple times.
The default value for prefer_zero_one_indexing
is 0.
Finally, indexing a scalar with a vector of ones can be used to create a vector the same size as the index vector, with each element equal to the value of the original scalar. For example, the following statements
a = 13; a ([1, 1, 1, 1])
produce a vector whose four elements are all equal to 13.
Similarly, indexing a scalar with two vectors of ones can be used to create a matrix. For example the following statements
a = 13; a ([1, 1], [1, 1, 1])
create a 2 by 3 matrix with all elements equal to 13.
This is an obscure notation and should be avoided. It is better to
use the function ones
to generate a matrix of the appropriate
size whose elements are all one, and then to scale it to produce the
desired result. See section Special Utility Matrices.
prefer_column_vectors
is nonzero, operations like
for i = 1:10 a (i) = i; endfor
(for a
previously undefined) produce column vectors. Otherwise, row
vectors are preferred. The default value is 1.
If a variable is already defined to be a vector (a matrix with a single
row or column), the original orientation is respected, regardless of the
value of prefer_column_vectors
.
resize_on_range_error
is nonzero, expressions
like
for i = 1:10 a (i) = sqrt (i); endfor
(for a
previously undefined) result in the variable a
being resized to be just large enough to hold the new value. New
elements that have not been given a value are set to zero. If the value
of resize_on_range_error
is 0, an error message is printed and
control is returned to the top level. The default value is 1.
Note that it is quite inefficient to create a vector using a loop like the one shown in the example above. In this particular case, it would have been much more efficient to use the expression
a = sqrt (1:10);
thus avoiding the loop entirely. In cases where a loop is still
required, or a number of values must be combined to form a larger
matrix, it is generally much faster to set the size of the matrix first,
and then insert elements using indexing commands. For example, given a
matrix a
,
[nr, nc] = size (a); x = zeros (nr, n * nc); for i = 1:n x(:,(i-1)*n+1:i*n) = a; endfor
is considerably faster than
x = a; for i = 1:n-1 x = [x, a]; endfor
particularly for large matrices because Octave does not have to repeatedly resize the result.
A function is a name for a particular calculation. Because it has
a name, you can ask for it by name at any point in the program. For
example, the function sqrt
computes the square root of a number.
A fixed set of functions are built-in, which means they are
available in every Octave program. The sqrt
function is one of
these. In addition, you can define your own functions.
See section Functions and Script Files, for information about how to do this.
The way to use a function is with a function call expression, which consists of the function name followed by a list of arguments in parentheses. The arguments are expressions which give the raw materials for the calculation that the function will do. When there is more than one argument, they are separated by commas. If there are no arguments, you can omit the parentheses, but it is a good idea to include them anyway, to clearly indicate that a function call was intended. Here are some examples:
sqrt (x^2 + y^2) # One argument ones (n, m) # Two arguments rand () # No arguments
Each function expects a particular number of arguments. For example, the
sqrt
function must be called with a single argument, the number
to take the square root of:
sqrt (argument)
Some of the built-in functions take a variable number of arguments, depending on the particular usage, and their behavior is different depending on the number of arguments supplied.
Like every other expression, the function call has a value, which is
computed by the function based on the arguments you give it. In this
example, the value of sqrt (argument)
is the square root of
the argument. A function can also have side effects, such as assigning
the values of certain variables or doing input or output operations.
Unlike most languages, functions in Octave may return multiple values. For example, the following statement
[u, s, v] = svd (a)
computes the singular value decomposition of the matrix a
and
assigns the three result matrices to u
, s
, and v
.
The left side of a multiple assignment expression is itself a list of expressions, and is allowed to be a list of variable names or index expressions. See also section Index Expressions, and section Assignment Expressions.
In Octave, unlike Fortran, function arguments are passed by value, which means that each argument in a function call is evaluated and assigned to a temporary location in memory before being passed to the function. There is currently no way to specify that a function parameter should be passed by reference instead of by value. This means that it is impossible to directly alter the value of function parameter in the calling function. It can only change the local copy within the function body. For example, the function
function f (x, n) while (n-- > 0) disp (x); endwhile endfunction
displays the value of the first argument n times. In this function, the variable n is used as a temporary variable without having to worry that its value might also change in the calling function. Call by value is also useful because it is always possible to pass constants for any function parameter without first having to determine that the function will not attempt to modify the parameter.
The caller may use a variable as the expression for the argument, but the called function does not know this: it only knows what value the argument had. For example, given a function called as
foo = "bar"; fcn (foo)
you should not think of the argument as being "the variable
foo
." Instead, think of the argument as the string value,
"bar"
.
Even though Octave uses pass-by-value semantics for function arguments, values are not copied unnecessarily. For example,
x = rand (1000); f (x);
does not actually force two 1000 by 1000 element matrices to exist
unless the function f
modifies the value of its
argument. Then Octave must create a copy to avoid changing the
value outside the scope of the function f
, or attempting (and
probably failing!) to modify the value of a constant or the value of a
temporary result.
With some restrictions(2), recursive function calls are allowed. A recursive function is one which calls itself, either directly or indirectly. For example, here is an inefficient(3) way to compute the factorial of a given integer:
function retval = fact (n) if (n > 0) retval = n * fact (n-1); else retval = 1; endif endfunction
This function is recursive because it calls itself directly. It eventually terminates because each time it calls itself, it uses an argument that is one less than was used for the previous call. Once the argument is no longer greater than zero, it does not call itself, and the recursion ends.
The built-in variable max_recursion_depth
specifies a limit to
the recursion depth and prevents Octave from recursing infinitely.
The default value is 256.
The following arithmetic operators are available, and work on scalars and matrices.
x + y
x .+ y
+
.
x - y
x .- y
-
.
x * y
x .* y
x / y
(inverse (y') * x')'but it is computed without forming the inverse of y'. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed.
x ./ y
x \ y
inverse (x) * ybut it is computed without forming the inverse of x. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed.
x .\ y
x ^ y
x ** y
x .^ y
x .** y
-x
+x
x'
conj (x.')
x.'
Note that because Octave's element by element operators begin with a `.', there is a possible ambiguity for statements like
1./m
because the period could be interpreted either as part of the constant or as part of the operator. To resolve this conflict, Octave treats the expression as if you had typed
(1) ./ m
and not
(1.) / m
Although this is inconsistent with the normal behavior of Octave's lexer, which usually prefers to break the input into tokens by preferring the longest possible match at any given point, it is more useful in this case.
warn_divide_by_zero
is nonzero, a warning
is issued when Octave encounters a division by zero. If the value is
0, the warning is omitted. The default value is 1.
Comparison operators compare numeric values for relationships such as equality. They are written using relational operators.
All of Octave's comparison operators return a value of 1 if the comparison is true, or 0 if it is false. For matrix values, they all work on an element-by-element basis. For example,
[1, 2; 3, 4] == [1, 3; 2, 4] => 1 0 0 1
If one operand is a scalar and the other is a matrix, the scalar is compared to each element of the matrix in turn, and the result is the same size as the matrix.
x < y
x <= y
x == y
x >= y
x > y
x != y
x ~= y
x <> y
String comparisons may also be performed with the strcmp
function, not with the comparison operators listed above.
See section Strings.
An element-by-element boolean expression is a combination of comparison expressions using the boolean operators "or" (`|'), "and" (`&'), and "not" (`!'), along with parentheses to control nesting. The truth of the boolean expression is computed by combining the truth values of the corresponding elements of the component expressions. A value is considered to be false if it is zero, and true otherwise.
Element-by-element boolean expressions can be used wherever comparison
expressions can be used. They can be used in if
and while
statements. However, if a matrix value used as the condition in an
if
or while
statement is only true if all of its
elements are nonzero.
Like comparison operations, each element of an element-by-element boolean expression also has a numeric value (1 if true, 0 if false) that comes into play if the result of the boolean expression is stored in a variable, or used in arithmetic.
Here are descriptions of the three element-by-element boolean operators.
boolean1 & boolean2
boolean1 | boolean2
! boolean
~ boolean
For matrix operands, these operators work on an element-by-element basis. For example, the expression
[1, 0; 0, 1] & [1, 0; 2, 3]
returns a two by two identity matrix.
For the binary operators, the dimensions of the operands must conform if both are matrices. If one of the operands is a scalar and the other a matrix, the operator is applied to the scalar and each element of the matrix.
For the binary element-by-element boolean operators, both subexpressions boolean1 and boolean2 are evaluated before computing the result. This can make a difference when the expressions have side effects. For example, in the expression
a & b++
the value of the variable b is incremented even if the variable a is zero.
This behavior is necessary for the boolean operators to work as described for matrix-valued operands.
Combined with the implicit conversion to scalar values in if
and
while
conditions, Octave's element-by-element boolean operators
are often sufficient for performing most logical operations. However,
it is sometimes desirable to stop evaluating a boolean expression as
soon as the overall truth value can be determined. Octave's
short-circuit boolean operators work this way.
boolean1 && boolean2
all (all (boolean1))
.
If it is false, the result of the overall expression is 0. If it is
true, the expression boolean2 is evaluated and converted to a
scalar using the equivalent of the operation all (all
(boolean1))
. If it is true, the result of the overall expression
is 1. Otherwise, the result of the overall expression is 0.
boolean1 || boolean2
all (all (boolean1))
.
If it is true, the result of the overall expression is 1. If it is
false, the expression boolean2 is evaluated and converted to a
scalar using the equivalent of the operation all (all
(boolean1))
. If it is true, the result of the overall expression
is 1. Otherwise, the result of the overall expression is 0.
The fact that both operands may not be evaluated before determining the overall truth value of the expression can be important. For example, in the expression
a && b++
the value of the variable b is only incremented if the variable a is nonzero.
This can be used to write somewhat more concise code. For example, it is possible write
function f (a, b, c) if (nargin > 2 && isstr (c)) ...
instead of having to use two if
statements to avoid attempting to
evaluate an argument that doesn't exist. For example, without the
short-circuit feature, it would be necessary to write
function f (a, b, c) if (nargin > 2) if (isstr (c)) ...
Writing
function f (a, b, c) if (nargin > 2 & isstr (c)) ...
would result in an error if f
were called with one or two
arguments because Octave would be forced to try to evaluate both of the
operands for the operator `&'.
An assignment is an expression that stores a new value into a
variable. For example, the following expression assigns the value 1 to
the variable z
:
z = 1
After this expression is executed, the variable z
has the value 1.
Whatever old value z
had before the assignment is forgotten.
The `=' sign is called an assignment operator.
Assignments can store string values also. For example, the following
expression would store the value "this food is good"
in the
variable message
:
thing = "food" predicate = "good" message = [ "this " , thing , " is " , predicate ]
(This also illustrates concatenation of strings.)
Most operators (addition, concatenation, and so on) have no effect except to compute a value. If you ignore the value, you might as well not use the operator. An assignment operator is different. It does produce a value, but even if you ignore the value, the assignment still makes itself felt through the alteration of the variable. We call this a side effect.
The left-hand operand of an assignment need not be a variable (see section Variables). It can also be an element of a matrix (see section Index Expressions) or a list of return values (see section Calling Functions). These are all called lvalues, which means they can appear on the left-hand side of an assignment operator. The right-hand operand may be any expression. It produces the new value which the assignment stores in the specified variable, matrix element, or list of return values.
It is important to note that variables do not have permanent types.
The type of a variable is simply the type of whatever value it happens
to hold at the moment. In the following program fragment, the variable
foo
has a numeric value at first, and a string value later on:
octave:13> foo = 1 foo = 1 octave:13> foo = "bar" foo = bar
When the second assignment gives foo
a string value, the fact that
it previously had a numeric value is forgotten.
Assignment of a scalar to an indexed matrix sets all of the elements
that are referenced by the indices to the scalar value. For example, if
a
is a matrix with at least two columns,
a(:, 2) = 5
sets all the elements in the second column of a
to 5.
Assigning an empty matrix `[]' works in most cases to allow you to delete rows or columns of matrices and vectors. See section Empty Matrices. For example, given a 4 by 5 matrix A, the assignment
A (3, :) = []
deletes the third row of A, and the assignment
A (:, 1:2:5) = []
deletes the first, third, and fifth columns.
An assignment is an expression, so it has a value. Thus, z = 1
as an expression has the value 1. One consequence of this is that you
can write multiple assignments together:
x = y = z = 0
stores the value 0 in all three variables. It does this because the
value of z = 0
, which is 0, is stored into y
, and then
the value of y = z = 0
, which is 0, is stored into x
.
This is also true of assignments to lists of values, so the following is a valid expression
[a, b, c] = [u, s, v] = svd (a)
that is exactly equivalent to
[u, s, v] = svd (a) a = u b = s c = v
In expressions like this, the number of values in each part of the expression need not match. For example, the expression
[a, b, c, d] = [u, s, v] = svd (a)
is equivalent to the expression above, except that the value of the variable `d' is left unchanged, and the expression
[a, b] = [u, s, v] = svd (a)
is equivalent to
[u, s, v] = svd (a) a = u b = s
You can use an assignment anywhere an expression is called for. For
example, it is valid to write x != (y = 1)
to set y
to 1
and then test whether x
equals 1. But this style tends to make
programs hard to read. Except in a one-shot program, you should rewrite
it to get rid of such nesting of assignments. This is never very hard.
Increment operators increase or decrease the value of a variable by 1. The operator to increment a variable is written as `++'. It may be used to increment a variable either before or after taking its value.
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.
Here is a list of all the increment and decrement expressions.
++x
x = x + 1
.
--x
x = x - 1
.
x++
x--
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.
Operator precedence determines how operators are grouped, when
different operators appear close by in one expression. For example,
`*' has higher precedence than `+'. Thus, the expression
a + b * c
means to multiply b
and c
, and then add
a
to the product (i.e., a + (b * c)
).
You can overrule the precedence of the operators by using parentheses. You can think of the precedence rules as saying where the parentheses are assumed if you do not write parentheses yourself. In fact, it is wise to use parentheses whenever you have an unusual combination of operators, because other people who read the program may not remember what the precedence is in this case. You might forget as well, and then you too could make a mistake. Explicit parentheses will help prevent any such mistake.
When operators of equal precedence are used together, the leftmost
operator groups first, except for the assignment and exponentiation
operators, which group in the opposite order. Thus, the expression
a - b + c
groups as (a - b) + c
, but the expression
a = b = c
groups as a = (b = c)
.
The precedence of prefix unary operators is important when another
operator follows the operand. For example, -x^2
means
-(x^2)
, because `-' has lower precedence than `^'.
Here is a table of the operators in Octave, in order of increasing precedence.
statement separators
assignment
logical "or" and "and"
element-wise "or" and "and"
relational
colon
add, subtract
multiply, divide
transpose
unary plus, minus, increment, decrement, and "not"
exponentiation
Normally, you evaluate expressions simply by typing them at the Octave prompt, or by asking Octave to interpret commands that you have saved in a file.
Sometimes, you may find it necessary to evaluate an expression that has
been computed and stored in a string, or use a string as the name of a
function to call. The eval
and feval
functions allow you
to do just that, and are necessary in order to evaluate commands that
are not known until run time, or to write functions that will need to
call user-supplied functions.
eval
returns. For example,
eval ("a = 13") -| a = 13 => 13
In this case, the value of the evaluated expression is printed and it is
also returned returned from eval
. Just as with any other
expression, you can turn printing off by ending the expression in a
semicolon. For example,
eval ("a = 13;") => 13
In this example, the variable a
has been given the value 13, but
the value of the expression is not printed. You can also turn off
automatic printing for all expressions executed by eval
using the
variable default_eval_print_flag
.
eval
that do not end with semicolons. If it
is zero, automatic printing is suppressed. The default value is 1.
feval ("acos", -1) => 3.1416
calls the function acos
with the argument `-1'.
The function feval
is necessary in order to be able to write
functions that call user-supplied functions, because Octave does not
have a way to declare a pointer to a function (like C) or to declare a
special kind of variable that can be used to hold the name of a function
(like EXTERNAL
in Fortran). Instead, you must refer to functions
by name, and use feval
to call them.
Here is a simple-minded function using feval
that finds the root
of a user-supplied function of one variable using Newton's method.
function result = newtroot (fname, x) # usage: newtroot (fname, x) # # fname : a string naming a function f(x). # x : initial guess delta = tol = sqrt (eps); maxit = 200; fx = feval (fname, x); for i = 1:maxit if (abs (fx) < tol) result = x; return; else fx_new = feval (fname, x + delta); deriv = (fx_new - fx) / delta; x = x - fx / deriv; fx = fx_new; endif endfor result = x; endfunction
Note that this is only meant to be an example of calling user-supplied
functions and should not be taken too seriously. In addition to using a
more robust algorithm, any serious code would check the number and type
of all the arguments, ensure that the supplied function really was a
function, etc. See See section Predicates for Numeric Objects, for example,
for a list of predicates for numeric objects, and See section Status of Variables, for a description of the exist
function.
Statements may be a simple constant expression or a complicated list of nested loops and conditional statements.
Control statements such as if
, while
, and so on
control the flow of execution in Octave programs. All the control
statements start with special keywords such as if
and
while
, to distinguish them from simple expressions.
Many control statements contain other statements; for example, the
if
statement contains another statement which may or may not be
executed.
Each control statement has a corresponding end statement that
marks the end of the end of the control statement. For example, the
keyword endif
marks the end of an if
statement, and
endwhile
marks the end of a while
statement. You can use
the keyword end
anywhere a more specific end keyword is expected,
but using the more specific keywords is preferred because if you use
them, Octave is able to provide better diagnostics for mismatched or
missing end tokens.
The list of statements contained between keywords like if
or
while
and the corresponding end statement is called the
body of a control statement.
if
Statement
The if
statement is Octave's decision-making statement. There
are three basic forms of an if
statement. In its simplest form,
it looks like this:
if (condition) then-body endif
condition is an expression that controls what the rest of the statement will do. The then-body is executed only if condition is true.
The condition in an if
statement is considered true if its value
is non-zero, and false if its value is zero. If the value of the
conditional expression in an if
statement is a vector or a
matrix, it is considered true only if all of the elements are
non-zero.
The second form of an if statement looks like this:
if (condition) then-body else else-body endif
If condition is true, then-body is executed; otherwise, else-body is executed.
Here is an example:
if (rem (x, 2) == 0) printf ("x is even\n"); else printf ("x is odd\n"); endif
In this example, if the expression rem (x, 2) == 0
is true (that
is, the value of x
is divisible by 2), then the first
printf
statement is evaluated, otherwise the second printf
statement is evaluated.
The third and most general form of the if
statement allows
multiple decisions to be combined in a single statement. It looks like
this:
if (condition) then-body elseif (condition) elseif-body else else-body endif
Any number of elseif
clauses may appear. Each condition is
tested in turn, and if one is found to be true, its corresponding
body is executed. If none of the conditions are true and the
else
clause is present, its body is executed. Only one
else
clause may appear, and it must be the last part of the
statement.
In the following example, if the first condition is true (that is, the
value of x
is divisible by 2), then the first printf
statement is executed. If it is false, then the second condition is
tested, and if it is true (that is, the value of x
is divisible
by 3), then the second printf
statement is executed. Otherwise,
the third printf
statement is performed.
if (rem (x, 2) == 0) printf ("x is even\n"); elseif (rem (x, 3) == 0) printf ("x is odd and divisible by 3\n"); else printf ("x is odd\n"); endif
Note that the elseif
keyword must not be spelled else if
,
as is allowed in Fortran. If it is, the space between the else
and if
will tell Octave to treat this as a new if
statement within another if
statement's else
clause. For
example, if you write
if (c1) body-1 else if (c2) body-2 endif
Octave will expect additional input to complete the first if
statement. If you are using Octave interactively, it will continue to
prompt you for additional input. If Octave is reading this input from a
file, it may complain about missing or mismatched end
statements,
or, if you have not used the more specific end
statements
(endif
, endfor
, etc.), it may simply produce incorrect
results, without producing any warning messages.
It is much easier to see the error if we rewrite the statements above like this,
if (c1) body-1 else if (c2) body-2 endif
using the indentation to show how Octave groups the statements. See section Functions and Script Files.
warn_assign_as_truth_value
is nonzero, a
warning is issued for statements like
if (s = t) ...
since such statements are not common, and it is likely that the intent was to write
if (s == t) ...
instead.
There are times when it is useful to write code that contains
assignments within the condition of a while
or if
statement. For example, statements like
while (c = getc()) ...
are common in C programming.
It is possible to avoid all warnings about such statements by setting
warn_assign_as_truth_value
to 0, but that may also
let real errors like
if (x = 1) # intended to test (x == 1)! ...
slip by.
In such cases, it is possible suppress errors for specific statements by writing them with an extra set of parentheses. For example, writing the previous example as
while ((c = getc())) ...
will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts.
The default value of warn_assign_as_truth_value
is 1.
switch
Statement
The switch
statement was introduced in Octave 2.0.5. It should
be considered experimental, and details of the implementation may change
slightly in future versions of Octave. If you have comments or would
like to share your experiences in trying to use this new command in real
programs, please send them to
octave-maintainers@bevo.che.wisc.edu. (But if you think you've
found a bug, please report it to bug-octave@bevo.che.wisc.edu.
The general form of the switch
statement is
switch expression case label command_list case label command_list ... otherwise command_list endswitch
switch
, case
, otherwise
, and
endswitch
are now keywords.
case label command_list
clause.
otherwise command_list
clause is optional.
end
keywords, endswitch
may be
replaced by end
, but you can get better diagnostics if you use
the specific forms.
switch (foo) case (1) -2 ...would produce surprising results, as would
switch (foo) case (1) case (2) doit (); ...particularly for C programmers.
if
block, even if all
the labels are integer constants. Perhaps a future variation on this
could detect all constant integer labels and improve performance by
using a jump table.
while
StatementIn programming, a loop means a part of a program that is (or at least can be) executed two or more times in succession.
The while
statement is the simplest looping statement in Octave.
It repeatedly executes a statement as long as a condition is true. As
with the condition in an if
statement, the condition in a
while
statement is considered true if its value is non-zero, and
false if its value is zero. If the value of the conditional expression
in a while
statement is a vector or a matrix, it is considered
true only if all of the elements are non-zero.
Octave's while
statement looks like this:
while (condition) body endwhile
Here body is a statement or list of statements that we call the body of the loop, and condition is an expression that controls how long the loop keeps running.
The first thing the while
statement does is test condition.
If condition is true, it executes the statement body. After
body has been executed, condition is tested again, and if it
is still true, body is executed again. This process repeats until
condition is no longer true. If condition is initially
false, the body of the loop is never executed.
This example creates a variable fib
that contains the first ten
elements of the Fibonacci sequence.
fib = ones (1, 10); i = 3; while (i <= 10) fib (i) = fib (i-1) + fib (i-2); i++; endwhile
Here the body of the loop contains two statements.
The loop works like this: first, the value of i
is set to 3.
Then, the while
tests whether i
is less than or equal to
10. This is the case when i
equals 3, so the value of the
i
-th element of fib
is set to the sum of the previous two
values in the sequence. Then the i++
increments the value of
i
and the loop repeats. The loop terminates when i
reaches 11.
A newline is not required between the condition and the body; but using one makes the program clearer unless the body is very simple.
See section The if
Statement for a description of the variable
warn_assign_as_truth_value
.
for
Statement
The for
statement makes it more convenient to count iterations of a
loop. The general form of the for
statement looks like this:
for var = expression body endfor
where body stands for any statement or list of statements, expression is any valid expression, and var may take several forms. Usually it is a simple variable name or an indexed variable. If the value of expression is a structure, var may also be a list. See section Looping Over Structure Elements, below.
The assignment expression in the for
statement works a bit
differently than Octave's normal assignment statement. Instead of
assigning the complete result of the expression, it assigns each column
of the expression to var in turn. If expression is a range,
a row vector, or a scalar, the value of var will be a scalar each
time the loop body is executed. If var is a column vector or a
matrix, var will be a column vector each time the loop body is
executed.
The following example shows another way to create a vector containing
the first ten elements of the Fibonacci sequence, this time using the
for
statement:
fib = ones (1, 10); for i = 3:10 fib (i) = fib (i-1) + fib (i-2); endfor
This code works by first evaluating the expression 3:10
, to
produce a range of values from 3 to 10 inclusive. Then the variable
i
is assigned the first element of the range and the body of the
loop is executed once. When the end of the loop body is reached, the
next value in the range is assigned to the variable i
, and the
loop body is executed again. This process continues until there are no
more elements to assign.
Although it is possible to rewrite all for
loops as while
loops, the Octave language has both statements because often a
for
loop is both less work to type and more natural to think of.
Counting the number of iterations is very common in loops and it can be
easier to think of this counting as part of looping rather than as
something to do inside the loop.
A special form of the for
statement allows you to loop over all
the elements of a structure:
for [ val, key ] = expression body endfor
In this form of the for
statement, the value of expression
must be a structure. If it is, key and val are set to the
name of the element and the corresponding value in turn, until there are
no more elements. For example,
x.a = 1 x.b = [1, 2; 3, 4] x.c = "string" for [val, key] = x key val endfor -| key = a -| val = 1 -| key = b -| val = -| -| 1 2 -| 3 4 -| -| key = c -| val = string
The elements are not accessed in any particular order. If you need to
cycle through the list in a particular way, you will have to use the
function struct_elements
and sort the list yourself.
The key variable may also be omitted. If it is, the brackets are also optional. This is useful for cycling through the values of all the structure elements when the names of the elements do not need to be known.
break
Statement
The break
statement jumps out of the innermost for
or
while
loop that encloses it. The break
statement may only
be used within the body of a loop. The following example finds the
smallest divisor of a given integer, and also identifies prime numbers:
num = 103; div = 2; while (div*div <= num) if (rem (num, div) == 0) break; endif div++; endwhile if (rem (num, div) == 0) printf ("Smallest divisor of %d is %d\n", num, div) else printf ("%d is prime\n", num); endif
When the remainder is zero in the first while
statement, Octave
immediately breaks out of the loop. This means that Octave
proceeds immediately to the statement following the loop and continues
processing. (This is very different from the exit
statement
which stops the entire Octave program.)
Here is another program equivalent to the previous one. It illustrates
how the condition of a while
statement could just as well
be replaced with a break
inside an if
:
num = 103; div = 2; while (1) if (rem (num, div) == 0) printf ("Smallest divisor of %d is %d\n", num, div); break; endif div++; if (div*div > num) printf ("%d is prime\n", num); break; endif endwhile
continue
Statement
The continue
statement, like break
, is used only inside
for
or while
loops. It skips over the rest of the loop
body, causing the next cycle around the loop to begin immediately.
Contrast this with break
, which jumps out of the loop altogether.
Here is an example:
# print elements of a vector of random # integers that are even. # first, create a row vector of 10 random # integers with values between 0 and 100: vec = round (rand (1, 10) * 100); # print what we're interested in: for x = vec if (rem (x, 2) != 0) continue; endif printf ("%d\n", x); endfor
If one of the elements of vec is an odd number, this example skips the print statement for that element, and continues back to the first statement in the loop.
This is not a practical example of the continue
statement, but it
should give you a clear understanding of how it works. Normally, one
would probably write the loop like this:
for x = vec if (rem (x, 2) == 0) printf ("%d\n", x); endif endfor
unwind_protect
StatementOctave 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.
This is useful to protect temporary changes to global variables from
possible errors. For example, the following code will always restore
the original value of the built-in variable do_fortran_indexing
even if an error occurs while performing the indexing operation.
save_do_fortran_indexing = do_fortran_indexing; unwind_protect do_fortran_indexing = 1; elt = a (idx) unwind_protect_cleanup do_fortran_indexing = save_do_fortran_indexing; end_unwind_protect
Without unwind_protect
, the value of do_fortran_indexing
would not be restored if an error occurs while performing the indexing
operation because evaluation would stop at the point of the error and
the statement to restore the value would not be executed.
try
StatementIn addition to unwind_protect, Octave supports another limited form of exception handling.
The general form of a try
block looks like this:
try body catch cleanup end_try_catch
Where body and cleanup are both optional and may contain any Octave expressions or commands. The statements in cleanup are only executed if an error occurs in body.
No warnings or error messages are printed while body is
executing. If an error does occur during the execution of body,
cleanup can access the text of the message that would have been
printed in the builtin constant __error_text__
. This is the same
as eval (try, catch)
(which may now also use
__error_text__
) but it is more efficient since the commands do
not need to be parsed each time the try and catch statements
are evaluated. See section Error Handling, for more information about the
__error_text__
variable.
Octave's try block is a very limited variation on the Lisp condition-case form (limited because it cannot handle different classes of errors separately). Perhaps at some point Octave can have some sort of classification of errors and try-catch can be improved to be as powerful as condition-case in Lisp.
In the Octave language, most statements end with a newline character and
you must tell Octave to ignore the newline character in order to
continue a statement from one line to the next. Lines that end with the
characters ...
or \
are joined with the following line
before they are divided into tokens by Octave's parser. For example,
the lines
x = long_variable_name ... + longer_variable_name \ - 42
form a single statement. The backslash character on the second line above is interpreted a continuation character, not as a division operator.
For continuation lines that do not occur inside string constants, whitespace and comments may appear between the continuation marker and the newline character. For example, the statement
x = long_variable_name ... # comment one + longer_variable_name \ # comment two - 42 # last comment
is equivalent to the one shown above. Inside string constants, the continuation marker must appear at the end of the line just before the newline character.
Input that occurs inside parentheses can be continued to the next line without having to use a continuation marker. For example, it is possible to write statements like
if (fine_dining_destination == on_a_boat || fine_dining_destination == on_a_train) suess (i, will, not, eat, them, sam, i, am, i, will, not, eat, green, eggs, and, ham); endif
without having to add to the clutter with continuation markers.
Complicated Octave programs can often be simplified by defining functions. Functions can be defined directly on the command line during interactive Octave sessions, or in external files, and can be called just like built-in functions.
In its simplest form, the definition of a function named name looks like this:
function name body endfunction
A valid function name is like a valid variable name: a sequence of letters, digits and underscores, not starting with a digit. Functions share the same pool of names as variables.
The function body consists of Octave statements. It is the most important part of the definition, because it says what the function should actually do.
For example, here is a function that, when executed, will ring the bell on your terminal (assuming that it is possible to do so):
function wakeup printf ("\a"); endfunction
The printf
statement (see section Input and Output) simply tells
Octave to print the string "\a"
. The special character `\a'
stands for the alert character (ASCII 7). See section Strings.
Once this function is defined, you can ask Octave to evaluate it by typing the name of the function.
Normally, you will want to pass some information to the functions you define. The syntax for passing parameters to a function in Octave is
function name (arg-list) body endfunction
where arg-list is a comma-separated list of the function's arguments. When the function is called, the argument names are used to hold the argument values given in the call. The list of arguments may be empty, in which case this form is equivalent to the one shown above.
To print a message along with ringing the bell, you might modify the
beep
to look like this:
function wakeup (message) printf ("\a%s\n", message); endfunction
Calling this function using a statement like this
wakeup ("Rise and shine!");
will cause Octave to ring your terminal's bell and print the message
`Rise and shine!', followed by a newline character (the `\n'
in the first argument to the printf
statement).
In most cases, you will also want to get some information back from the functions you define. Here is the syntax for writing a function that returns a single value:
function ret-var = name (arg-list) body endfunction
The symbol ret-var is the name of the variable that will hold the value to be returned by the function. This variable must be defined before the end of the function body in order for the function to return a value.
Variables used in the body of a function are local to the function. Variables named in arg-list and ret-var are also local to the function. See section Global Variables, for information about how to access global variables inside a function.
For example, here is a function that computes the average of the elements of a vector:
function retval = avg (v) retval = sum (v) / length (v); endfunction
If we had written avg
like this instead,
function retval = avg (v) if (is_vector (v)) retval = sum (v) / length (v); endif endfunction
and then called the function with a matrix instead of a vector as the argument, Octave would have printed an error message like this:
error: `retval' undefined near line 1 column 10 error: evaluating index expression near line 7, column 1
because the body of the if
statement was never executed, and
retval
was never defined. To prevent obscure errors like this,
it is a good idea to always make sure that the return variables will
always have values, and to produce meaningful error messages when
problems are encountered. For example, avg
could have been
written like this:
function retval = avg (v) retval = 0; if (is_vector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction
There is still one additional problem with this function. What if it is
called without an argument? Without additional error checking, Octave
will probably print an error message that won't really help you track
down the source of the error. To allow you to catch errors like this,
Octave provides each function with an automatic variable called
nargin
. Each time a function is called, nargin
is
automatically initialized to the number of arguments that have actually
been passed to the function. For example, we might rewrite the
avg
function like this:
function retval = avg (v) retval = 0; if (nargin != 1) usage ("avg (vector)"); endif if (is_vector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction
Although Octave does not automatically report an error if you call a function with more arguments than expected, doing so probably indicates that something is wrong. Octave also does not automatically report an error if a function is called with too few arguments, but any attempt to use a variable that has not been given a value will result in an error. To avoid such problems and to provide useful messages, we check for both possibilities and issue our own error message.
nargin
holds the number of command line arguments that
were passed to Octave.
silent_functions
is nonzero, internal output
from a function is suppressed. Otherwise, the results of expressions
within a function body that are not terminated with a semicolon will
have their values printed. The default value is 0.
For example, if the function
function f () 2 + 2 endfunction
is executed, Octave will either print `ans = 4' or nothing
depending on the value of silent_functions
.
Unlike many other computer languages, Octave allows you to define functions that return more than one value. The syntax for defining functions that return multiple values is
function [ret-list] = name (arg-list) body endfunction
where name, arg-list, and body have the same meaning
as before, and ret-list is a comma-separated list of variable
names that will hold the values returned from the function. The list of
return values must have at least one element. If ret-list has
only one element, this form of the function
statement is
equivalent to the form described in the previous section.
Here is an example of a function that returns two values, the maximum element of a vector and the index of its first occurrence in the vector.
function [max, idx] = vmax (v) idx = 1; max = v (idx); for i = 2:length (v) if (v (i) > max) max = v (i); idx = i; endif endfor endfunction
In this particular case, the two values could have been returned as elements of a single array, but that is not always possible or convenient. The values to be returned may not have compatible dimensions, and it is often desirable to give the individual return values distinct names.
In addition to setting nargin
each time a function is called,
Octave also automatically initializes nargout
to the number of
values that are expected to be returned. This allows you to write
functions that behave differently depending on the number of values that
the user of the function has requested. The implicit assignment to the
built-in variable ans
does not figure in the count of output
arguments, so the value of nargout
may be zero.
The svd
and lu
functions are examples of built-in
functions that behave differently depending on the value of
nargout
.
It is possible to write functions that only set some return values. For example, calling the function
function [x, y, z] = f () x = 1; z = 2; endfunction
as
[a, b, c] = f ()
produces:
a = 1 b = [](0x0) c = 2
provided that the built-in variable define_all_return_values
is
nonzero and the value of default_return_value
is `[]'.
See section Summary of Built-in Variables.
f ()
will result in nargout
being set to 0 inside the function
f
and
[s, t] = f ()
will result in nargout
being set to 2 inside the function
f
.
At the top level, nargout
is undefined.
define_all_return_values
is nonzero. The default value is
[]
.
define_all_return_values
is nonzero, Octave
will substitute the value specified by default_return_value
for
any return values that remain undefined when a function returns. The
default value is 0.
This is useful for checking to see that the number of arguments supplied to a function is within an acceptable range.
Octave has a real mechanism for handling functions that take an unspecified number of arguments, so it is not 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 (); ## Pre-decrement to skip `heading' arg. while (--nargin) disp (va_arg ()); endwhile endfunction
The ellipsis that marks the variable argument list may only appear once and must be the last element in the list of arguments.
va_start
if you do not plan to cycle through the
arguments more than once. This function may only be called inside
functions that have been declared to accept a variable number of input
arguments.
va_arg()
when there are no more arguments available.
Sometimes it is useful to be able to pass all unnamed arguments to another function. The keyword all_va_args makes this very easy to do. For example,
function f (...) while (nargin--) disp (va_arg ()) endwhile endfunction function g (...) f ("begin", all_va_args, "end") endfunction g (1, 2, 3) -| begin -| 1 -| 2 -| 3 -| end
va_start
. It can only be used within functions
that take a variable number of arguments. It is an error to use it in
other contexts.
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 a variable-length return list to produce n values:
function [...] = f (n, x) for i = 1:n vr_val (i * x); endfor endfunction [dos, quatro] = f (2, 2) => dos = 2 => quatro = 4
As with variable argument lists, the ellipsis that marks the variable return list may only appear once and must be the last element in the list of returned values.
vr_val
has been called, there is no way to go back to the
beginning of the list and rewrite any of the return values. This
function may only be called within functions that have been declared to
return an unspecified number of output arguments (by using the special
ellipsis notation described above).
The body of a user-defined function can contain a return
statement.
This statement returns control to the rest of the Octave program. It
looks like this:
return
Unlike the return
statement in C, Octave's return
statement cannot be used to return a value from a function. Instead,
you must assign values to the list of return variables that are part of
the function
statement. The return
statement simply makes
it easier to exit a function from a deeply nested loop or conditional
statement.
Here is an example of a function that checks to see if any elements of a vector are nonzero.
function retval = any_nonzero (v) retval = 0; for i = 1:length (v) if (v (i) != 0) retval = 1; return; endif endfor printf ("no nonzero elements found\n"); endfunction
Note that this function could not have been written using the
break
statement to exit the loop once a nonzero value is found
without adding extra logic to avoid printing the message if the vector
does contain a nonzero element.
return
inside a function or
script, it returns control to be caller immediately. At the top level,
the return statement is ignored. A return
statement is assumed
at the end of every function definition.
return_last_computed_value
is true, and a
function is defined without explicitly specifying a return value, the
function will return the value of the last expression. Otherwise, no
value will be returned. The default value is 0.
For example, the function
function f () 2 + 2; endfunction
will either return nothing, if the value of
return_last_computed_value
is 0, or 4, if the value of
return_last_computed_value
is nonzero.
Except for simple one-shot programs, it is not practical to have to define all the functions you need each time you need them. Instead, you will normally want to save them in a file so that you can easily edit them, and save them for use at a later time.
Octave does not require you to load function definitions from files before using them. You simply need to put the function definitions in a place where Octave can find them.
When Octave encounters an identifier that is undefined, it first looks
for variables or functions that are already compiled and currently
listed in its symbol table. If it fails to find a definition there, it
searches the list of directories specified by the built-in variable
LOADPATH
for files ending in `.m' that have the same base
name as the undefined identifier.(4) Once Octave finds a file
with a name that matches, the contents of the file are read. If it
defines a single function, it is compiled and executed.
See section Script Files, for more information about how you can define more
than one function in a single file.
When Octave defines a function from a function file, it saves the full name of the file it read and the time stamp on the file. After that, it checks the time stamp on the file every time it needs the function. If the time stamp indicates that the file has changed since the last time it was read, Octave reads it again.
Checking the time stamp allows you to edit the definition of a function while Octave is running, and automatically use the new function definition without having to restart your Octave session. Checking the time stamp every time a function is used is rather inefficient, but it has to be done to ensure that the correct function definition is used.
To avoid degrading performance unnecessarily by checking the time stamps on functions that are not likely to change, Octave assumes that function files in the directory tree `octave-home/share/octave/version/m' will not change, so it doesn't have to check their time stamps every time the functions defined in those files are used. This is normally a very good assumption and provides a significant improvement in performance for the function files that are distributed with Octave.
If you know that your own function files will not change while you are
running Octave, you can improve performance by setting the variable
ignore_function_time_stamp
to "all"
, so that Octave will
ignore the time stamps for all function files. Setting it to
"system"
gives the default behavior. If you set it to anything
else, Octave will check the time stamps on all function files.
LOADPATH
.
LOADPATH
overrides the environment variable OCTAVE_PATH
. See section Installing Octave.
LOADPATH
is now handled in the same way as TeX handles
TEXINPUTS
. Leading, trailing, or doubled colons that appear in
LOADPATH
are replaced by the value of DEFAULT_LOADPATH
.
The default value of LOADPATH
is ":"
, which tells Octave
to search in the directories specified by DEFAULT_LOADPATH
.
In addition, if any path element ends in `//', that directory and
all subdirectories it contains are searched recursively for function
files. This can result in a slight delay as Octave caches the lists of
files found in the LOADPATH
the first time Octave searches for a
function. After that, searching is usually much faster because Octave
normally only needs to search its internal cache for files.
To improve performance of recursive directory searching, it is best for each directory that is to be searched recursively to contain either additional subdirectories or function files, but not a mixture of both.
See section Organization of Functions Distributed with Octave for a description of the function file directories that are distributed with Octave.
stat
each time it looks up functions defined in function files.
If ignore_function_time_stamp
to "system"
, Octave will not
automatically recompile function files in subdirectories of
`octave-home/lib/version' if they have changed since
they were last compiled, but will recompile other function files in the
LOADPATH
if they change. If set to "all"
, Octave will not
recompile any function files unless their definitions are removed with
clear
. For any other value of ignore_function_time_stamp
,
Octave will always check to see if functions defined in function files
need to recompiled. The default value of ignore_function_time_stamp
is
"system"
.
warn_function_name_clash
is nonzero, a warning is
issued when Octave finds that the name of a function defined in a
function file differs from the name of the file. (If the names
disagree, the name declared inside the file is ignored.) If the value
is 0, the warning is omitted. The default value is 1.
A script file is a file containing (almost) any sequence of Octave commands. It is read and evaluated just as if you had typed each command at the Octave prompt, and provides a convenient way to perform a sequence of commands that do not logically belong inside a function.
Unlike a function file, a script file must not begin with the
keyword function
. If it does, Octave will assume that it is a
function file, and that it defines a single function that should be
evaluated as soon as it is defined.
A script file also differs from a function file in that the variables named in a script file are not local variables, but are in the same scope as the other variables that are visible on the command line.
Even though a script file may not begin with the function
keyword, it is possible to define more than one function in a single
script file and load (but not execute) all of them at once. To do
this, the first token in the file (ignoring comments and other white
space) must be something other than function
. If you have no
other statements to evaluate, you can use a statement that has no
effect, like this:
# Prevent Octave from thinking that this # is a function file: 1; # Define function one: function one () ...
To have Octave read and compile these functions into an internal form,
you need to make sure that the file is in Octave's LOADPATH
, then
simply type the base name of the file that contains the commands.
(Octave uses the same rules to search for script files as it does to
search for function files.)
If the first token in a file (ignoring comments) is function
,
Octave will compile the function and try to execute it, printing a
message warning about any non-whitespace characters that appear after
the function definition.
Note that Octave does not try to look up the definition of any identifier until it needs to evaluate it. This means that Octave will compile the following statements if they appear in a script file, or are typed at the command line,
# not a function file: 1; function foo () do_something (); endfunction function do_something () do_something_else (); endfunction
even though the function do_something
is not defined before it is
referenced in the function foo
. This is not an error because
Octave does not need to resolve all symbols that are referenced by a
function until the function is actually evaluated.
Since Octave doesn't look for definitions until they are needed, the
following code will always print `bar = 3' whether it is typed
directly on the command line, read from a script file, or is part of a
function body, even if there is a function or script file called
`bar.m' in Octave's LOADPATH
.
eval ("bar = 3"); bar
Code like this appearing within a function body could fool Octave if
definitions were resolved as the function was being compiled. It would
be virtually impossible to make Octave clever enough to evaluate this
code in a consistent fashion. The parser would have to be able to
perform the call to eval
at compile time, and that would be
impossible unless all the references in the string to be evaluated could
also be resolved, and requiring that would be too restrictive (the
string might come from user input, or depend on things that are not
known until the function is evaluated).
Although Octave normally executes commands from script files that have
the name `file.m', you can use the function source
to
execute commands from any file.
On some systems, Octave can dynamically load and execute functions written in C++. Octave can only directly call functions written in C++, but you can also load functions written in other languages by calling them from a simple wrapper function written in C++.
Here is an example of how to write a C++ function that Octave can load, with commentary. The source for this function is included in the source distributions of Octave, in the file `examples/oregonator.cc'. It defines the same set of differential equations that are used in the example problem of section Ordinary Differential Equations. By running that example and this one, we can compare the execution times to see what sort of increase in speed you can expect by using dynamically linked functions.
The function defined in `oregonator.cc' contains just 8 statements, and is not much different than the code defined in the corresponding M-file (also distributed with Octave in the file `examples/oregonator.m').
Here is the complete text of `oregonator.cc':
just
#include <octave/oct.h> DEFUN_DLD (oregonator, args, , "The `oregonator'.") { ColumnVector dx (3); ColumnVector x = args(0).vector_value (); dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0) - 8.375e-06*pow (x(0), 2)); dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27; dx(2) = 0.161*(x(0) - x(2)); return octave_value (dx); }
The first line of the file,
#include <octave/oct.h>
includes declarations for all of Octave's internal functions that you will need. If you need other functions from the standard C++ or C libraries, you can include the necessary headers here.
The next two lines
DEFUN_DLD (oregonator, args, , "The `oregonator'.")
declares the function. The macro DEFUN_DLD
and the macros that
it depends on are defined in the files `defun-dld.h',
`defun.h', and `defun-int.h' (these files are included in the
header file `octave/oct.h').
Note that the third parameter to DEFUN_DLD
(nargout
) is
not used, so it is omitted from the list of arguments to in order to
avoid the warning from gcc about an unused function parameter.
simply declares an object to store the right hand sides of the differential equation, and
The statement
ColumnVector x = args(0).vector_value ();
extracts a column vector from the input arguments. The variable
args
is passed to functions defined with DEFUN_DLD
as an
octave_value_list
object, which includes methods for getting the
length of the list and extracting individual elements.
In this example, we don't check for errors, but that is not difficult. All of the Octave's built-in functions do some form of checking on their arguments, so you can check the source code for those functions for examples of various strategies for verifying that the correct number and types of arguments have been supplied.
The next statements
ColumnVector dx (3); dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0) - 8.375e-06*pow (x(0), 2)); dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27; dx(2) = 0.161*(x(0) - x(2));
define the right hand side of the differential equation. Finally, we
can return dx
:
return octave_value (dx);
The actual return type is octave_value_list
, but it is only
necessary to convert the return type to an octave_value
because
there is a default constructor that can automatically create an object
of that type from an octave_value
object, so we can just use that
instead.
To use this file, your version of Octave must support dynamic linking. To find out if it does, type the command octave_config_info ("dld") at the Octave prompt. Support for dynamic linking is included if this command returns 1.
To compile the example file, type the command `mkoctfile
oregonator.cc' at the shell prompt. The script mkoctfile
should
have been installed along with Octave. Running it will create a file
called `oregonator.oct' that can be loaded by Octave. To test the
`oregonator.oct' file, start Octave and type the command
oregonator ([1, 2, 3], 0)
at the Octave prompt. Octave should respond by printing
ans = 77.269353 -0.012942 -0.322000
You can now use the `oregonator.oct' file just as you would the
oregonator.m
file to solve the set of differential equations.
On a 133 MHz Pentium running Linux, Octave can solve the problem shown
in section Ordinary Differential Equations in about 1.4 second using the
dynamically linked function, compared to about 19 seconds using the
M-file. Similar decreases in execution time can be expected for other
functions, particularly those that rely on functions like lsode
that require user-supplied functions.
Just as for M-files, Octave will automatically reload dynamically linked functions when the files that define them are more recent than the last time that the function was loaded. Two variables are available to control how Octave behaves when dynamically linked functions are cleared or reloaded.
auto_unload_dot_oct_files
is nonzero, Octave will
automatically unload any `.oct' files when there are no longer any
functions in the symbol table that reference them.
warn_reload_forces_clear
, Octave will warn you when this happens,
and print a list of the additional functions that it is forced to clear.
Additional examples for writing dynamically linked functions are available in the files in the `src' directory of the Octave distribution. Currently, this includes the files
balance.cc fft2.cc inv.cc qzval.cc chol.cc filter.cc log.cc schur.cc colloc.cc find.cc lsode.cc sort.cc dassl.cc fsolve.cc lu.cc svd.cc det.cc givens.cc minmax.cc syl.cc eig.cc hess.cc pinv.cc expm.cc ifft.cc qr.cc fft.cc ifft2.cc quad.cc
These files use the macro DEFUN_DLD_BUILTIN
instead of
DEFUN_DLD
. The difference between these two macros is just that
DEFUN_DLD_BUILTIN
can define a built-in function that is not
dynamically loaded if the operating system does not support dynamic
linking. To define your own dynamically linked functions you should use
DEFUN_DLD
.
There is currently no detailed description of all the functions that you can call in a built-in function. For the time being, you will have to read the source code for Octave.
Many of Octave's standard functions are distributed as function files. They are loosely organized by topic, in subdirectories of `octave-home/lib/octave/version/m', to make it easier to find them.
The following is a list of all the function file subdirectories, and the types of functions you will find there.
flipud
, rot90
,
and triu
, as well as other basic functions, like
is_matrix
, nargchk
, etc.
Octave includes several functions for printing error and warning messages. When you write functions that need to take special action when they encounter abnormal conditions, you should print the error messages using the functions described in this chapter.
error
function formats the optional arguments under the
control of the template string template using the same rules as
the printf
family of functions (see section Formatted Output).
The resulting message is prefixed by the string `error: ' and
printed on the stderr
stream.
Calling error
also sets Octave's internal error state such that
control will return to the top level without evaluating any more
commands. This is useful for aborting from functions or scripts.
If the error message does not end with a new line character, Octave will print a traceback of all the function calls leading to the error. For example, given the following function definitions:
function f () g () end function g () h () end function h () nargin == 1 || error ("nargin != 1"); end
calling the function f
will result in a list of messages that
can help you to quickly locate the exact location of the error:
f () error: nargin != 1 error: evaluating index expression near line 1, column 30 error: evaluating binary operator `||' near line 1, column 27 error: called from `h' error: called from `g' error: called from `f'
If the error message ends in a new line character, Octave will print the message but will not display any traceback messages as it returns control to the top level. For example, modifying the error message in the previous example to end in a new line causes Octave to only print a single message:
function h () nargin == 1 || error ("nargin != 1\n"); end f () error: nargin != 1
unwind_protect
or
try
statement or the try part of the most recent call to
the eval
function. Outside of the unwind_protect
and
try
statements or the eval
function, or if no error has
occurred within them, the value of error_text
is guaranteed to be
the empty string.
Note that the message does not include the first `error: ' prefix,
so that it may easily be passed to the error
function without
additional processing(5).
See section The try
Statement and section The unwind_protect
Statement.
beep_on_error
is nonzero, Octave will try
to ring your terminal's bell before printing an error message. The
default value is 0.
After usage
is evaluated, Octave will print a traceback of all
the function calls leading to the usage message.
You should use this function for reporting problems errors that result from an improper call to a function, such as calling a function with an incorrect number of arguments, or with arguments of the wrong type. For example, most functions distributed with Octave begin with code like this
if (nargin != 2) usage ("foo (a, b)"); endif
to check for the proper number of arguments.
The following pair of functions are of limited usefulness, and may be removed from future versions of Octave.
There are two distinct classes of input and output functions. The first set are modeled after the functions available in MATLAB. The second set are modeled after the standard I/O library used by the C programming language and offer more flexibility and control over the output.
When running interactively, Octave normally sends any output intended
for your terminal that is more than one screen long to a paging program,
such as less
or more
. This avoids the problem of having a
large volume of output stream by before you can read it. With
less
(and some versions of more
) you can also scan forward
and backward, and search for specific items.
Normally, no output is displayed by the pager until just before Octave
is ready to print the top level prompt, or read from the standard input
(for example, by using the fscanf
or scanf
functions).
This means that there may be some delay before any output appears on
your screen if you have asked Octave to perform a significant amount of
work with a single command statement. The function fflush
may be
used to force output to be sent to the pager (or any other stream)
immediately.
You can select the program to run as the pager by setting the variable
PAGER
, and you can turn paging off by setting the value of the
variable page_screen_output
to 0.
more
toggles the current state.
"less"
, "more"
, or
"pg"
, depending on what programs are installed on your system.
See section Installing Octave.
When running interactively, Octave sends any output intended for your
terminal that is more than one screen long to the program named by the
value of the variable PAGER
.
page_screen_output
is nonzero, all output
intended for the screen that is longer than one page is sent through a
pager. This allows you to view one screenful at a time. Some pagers
(such as less
---see section Installing Octave) are also capable of moving
backward on the output. The default value is 1.
page_output_immediately
is nonzero, Octave sends
output to the pager as soon as it is available. Otherwise, Octave
buffers its output and waits until just before the prompt is printed to
flush it to the pager. The default value is 0.
input
.
Since Octave normally prints the value of an expression as soon as it has been evaluated, the simplest of all I/O functions is a simple expression. For example, the following expression will display the value of pi
pi -| pi = 3.1416
This works well as long as it is acceptable to have the name of the
variable (or `ans') printed along with the value. To print the
value of a variable without printing its name, use the function
disp
.
The format
command offers some control over the way Octave prints
values with disp
and through the normal echoing mechanism.
3^2 + 4^2
is evaluated, the value of ans
is 25.
disp ("The value of pi is:"), disp (pi) -| the value of pi is: -| 3.1416
Note that the output from disp
always ends with a newline.
disp
and Octave's
normal echoing mechanism. Valid options are listed in the following
table.
short
long
long e
short e
3.14e+00
.
long E
short E
3.14159265358979E+00
.
free
none
bank
+
hex
pi
when printed in hex
format is 400921fb54442d18
.
This format only works for numeric values.
bit
pi
is
01000000000010010010000111111011 01010100010001000010110100011000(shown here in two 32 bit sections for typesetting purposes) when printed in bit format on a workstation which stores 8 byte real values in IEEE format with the least significant byte first. This format only works for numeric types.
By default, Octave will try to print numbers with at least 5 significant figures within a field that is a maximum of 10 characters wide.
If Octave is unable to format a matrix so that columns line up on the decimal point and all the numbers fit within the maximum field width, it switches to an `e' format.
If format
is invoked without any options, the default format
state is restored.
print_answer_id_name
is nonzero, variable
names are printed along with the result. Otherwise, only the result
values are printed. The default value is 1.
Octave has three functions that make it easy to prompt users for
input. The input
and menu
functions are normally
used for managing an interactive dialog with a user, and the
keyboard
function is normally used for doing simple debugging.
input ("Pick a number, any number! ")
prints the prompt
Pick a number, any number!
and waits for the user to enter a value. The string entered by the user is evaluated as an expression, so it may be a literal constant, a variable name, or any other valid expression.
Currently, input
only returns one value, regardless of the number
of values produced by the evaluation of the expression.
If you are only interested in getting a literal string value, you can
call input
with the character string "s"
as the second
argument. This tells Octave to return the string entered by the user
directly, without evaluating it first.
Because there may be output waiting to be displayed by the pager, it is
a good idea to always call fflush (stdout)
before calling
input
. This will ensure that all pending output is written to
the screen before your prompt. See section Input and Output.
keyboard
function is executed, Octave prints a prompt and waits
for user input. The input strings are then evaluated and the results
are printed. This makes it possible to examine the values of variables
within a function, and to assign new values to variables. No value is
returned from the keyboard
function, and it continues to prompt
for input until the user types `quit', or `exit'.
If keyboard
is invoked without any arguments, a default prompt of
`debug> ' is used.
For both input
and keyboard
, the normal command line
history and editing functions are available at the prompt.
Octave also has a function that makes it possible to get a single character from the keyboard without requiring the user to type a carriage return.
x = kbhit ();
will set x to the next character typed at the keyboard as soon as it is typed.
The save
and load
commands allow data to be written to and
read from disk files in various formats. The default format of files
written by the save
command can be controlled using the built-in
variables default_save_format
and save_precision
.
Note that Octave can not yet save or load structure variables or any user-defined types.
save
command are listed in the following table. Options that
modify the output format override the format specified by the built-in
variable default_save_format
.
-ascii
-binary
-float-binary
-mat-binary
-save-builtins
The list of variables to save may include wildcard patterns containing the following special characters:
?
*
[ list ]
!
or ^
, match all characters except those
specified by list. For example, the pattern `[a-zA-Z]' will
match all lower and upper case alphabetic characters.
Except when using the MATLAB binary data file format, saving global variables also saves the global status of the variable, so that if it is restored at a later time using `load', it will be restored as a global variable.
The command
save -binary data a b*
saves the variable `a' and all variables beginning with `b' to the file `data' in Octave's binary format.
There are two variables that modify the behavior of save
and one
that controls whether variables are saved when Octave exits unexpectedly.
save
command.
It should have one of the following values: "ascii"
,
"binary"
, float-binary
, or "mat-binary"
. The
initial default save format is Octave's text format.
save
,
you may specify a list of variables and load
will only extract
those variables with names that match. For example, to restore the
variables saved in the file `data', use the command
load data
Octave will refuse to overwrite existing variables unless you use the option `-force'.
If a variable that is not marked as global is loaded from a file when a global symbol with the same name already exists, it is loaded in the global symbol table. Also, if a variable is marked as global in a file and a local symbol exists, the local symbol is moved to the global symbol table and given the value from the file. Since it seems that both of these cases are likely to be the result of some sort of error, they will generate warnings.
The load
command can read data stored in Octave's text and
binary formats, and MATLAB's binary format. It will automatically
detect the type of file and do conversion from different floating point
formats (currently only IEEE big and little endian, though other formats
may added in the future).
Valid options for load
are listed in the following table.
-force
-ascii
-binary
-mat-binary
Octave's C-style input and output functions provide most of the functionality of the C programming language's standard I/O library. The argument lists for some of the input functions are slightly different, however, because Octave has no way of passing arguments by reference.
In the following, file refers to a file name and fid
refers
to an integer file number, as returned by fopen
.
There are three files that are always available. Although these files can be accessed using their corresponding numeric file ids, you should always use the symbolic names given in the table below, since it will make your programs easier to understand.
fopen
function opens the named file with
the specified mode (read-write, read-only, etc.) and architecture
interpretation (IEEE big endian, IEEE little endian, etc.), and returns
an integer value that may be used to refer to the file later. If an
error occurs, fid is set to -1 and msg contains the
corresponding system error message. The mode is a one or two
character string that specifies whether the file is to be opened for
reading, writing, or both.
The second form of the fopen
function returns a vector of file ids
corresponding to all the currently open files, excluding the
stdin
, stdout
, and stderr
streams.
The third form of the fopen
function returns the name of a
currently open file given its file id.
For example,
myfile = fopen ("splat.dat", "r", "ieee-le");
opens the file `splat.dat' for reading. If necessary, binary numeric values will be read assuming they are stored in IEEE format with the least significant bit first, and then converted to the native representation.
Opening a file that is already open simply opens it again and returns a separate file id. It is not an error to open a file several times, though writing to the same file through several different file ids may produce unexpected results.
The possible values `mode' may have are
The parameter arch is a string specifying the default data format for the file. Valid values for arch are:
however, conversions are currently only supported for `native' `ieee-be', and `ieee-le' formats.
fclose
returns
0. Otherwise, it returns 1.
If len is omitted, fgetl
reads until the next newline
character.
If there are no more characters to read, fgetl
returns -1.
If len is omitted, fgets
reads until the next newline
character.
If there are no more characters to read, fgets
returns -1.
This section describes how to call printf
and related functions.
The following functions are available for formatted output. They are modelled after the C language functions of the same name, but they interpret the format template differently in order to improve the performance of printing vector and matrix values.
printf
function prints the optional arguments under the
control of the template string template to the stream
stdout
.
printf
, except that the output is
written to the stream fid instead of stdout
.
printf
, except that the output is returned as a
string. Unlike the C library function, which requires you to provide a
suitably sized string as an argument, Octave's sprintf
function
returns the string, automatically sized to hold all of the items
converted.
The printf
function can be used to print any number of arguments.
The template string argument you supply in a call provides
information not only about the number of additional arguments, but also
about their types and what style should be used for printing them.
Ordinary characters in the template string are simply written to the output stream as-is, while conversion specifications introduced by a `%' character in the template cause subsequent arguments to be formatted and written to the output stream. For example,
pct = 37; filename = "foo.txt"; printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n", filename, pct);
produces output like
Processing of `foo.txt' is 37% finished. Please be patient.
This example shows the use of the `%d' conversion to specify that a scalar argument should be printed in decimal notation, the `%s' conversion to specify printing of a string argument, and the `%%' conversion to print a literal `%' character.
There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or `%x', respectively); or as a character value (`%c').
Floating-point numbers can be printed in normal, fixed-point notation using the `%f' conversion or in exponential notation using the `%e' conversion. The `%g' conversion uses either `%e' or `%f' format, depending on what is more appropriate for the magnitude of the particular number.
You can control formatting more precisely by writing modifiers between the `%' and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field.
The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections.
When given a matrix value, Octave's formatted output functions cycle through the format template until all the values in the matrix have been printed. For example,
printf ("%4.2f %10.2e %8.4g\n", hilb (3)); -| 1.00 5.00e-01 0.3333 -| 0.50 3.33e-01 0.25 -| 0.33 2.50e-01 0.2
If more than one value is to be printed in a single call, the output functions do not return to the beginning of the format template when moving on from one value to the next. This can lead to confusing output if the number of elements in the matrices are not exact multiples of the number of conversions in the format template. For example,
printf ("%4.2f %10.2e %8.4g\n", [1, 2], [3, 4]); -| 1.00 2.00e+00 3 -| 4.00
If this is not what you want, use a series of calls instead of just one.
This section provides details about the precise syntax of conversion
specifications that can appear in a printf
template
string.
Characters in the template string that are not part of a conversion specification are printed as-is to the output stream.
The conversion specifications in a printf
template string have
the general form:
% flags width [ . precision ] type conversion
For example, in the conversion specifier `%-10.8ld', the `-' is a flag, `10' specifies the field width, the precision is `8', the letter `l' is a type modifier, and `d' specifies the conversion style. (This particular type specifier says to print a numeric argument in decimal notation, with a minimum of 8 digits left-justified in a field at least 10 characters wide.)
In more detail, output conversion specifications consist of an initial `%' character followed in sequence by:
printf
function, but is recognized to provide
compatibility with the C language printf
.
The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use.
Here is a table summarizing what all the different conversions do:
scanf
for input
(see section Table of Input Conversions).
If the syntax of a conversion specification is invalid, unpredictable things will happen, so don't do this. If there aren't enough function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are unpredictable. If you supply more arguments than conversion specifications, the extra argument values are simply ignored; this is sometimes useful.
This section describes the options for the `%d', `%i', `%o', `%u', `%x', and `%X' conversion specifications. These conversions print integers in various formats.
The `%d' and `%i' conversion specifications both print an numeric argument as a signed decimal number; while `%o', `%u', and `%x' print the argument as an unsigned octal, decimal, or hexadecimal number (respectively). The `%X' conversion specification is just like `%x' except that it uses the characters `ABCDEF' as digits instead of `abcdef'.
The following flags are meaningful:
If a precision is supplied, it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If you don't specify a precision, the number is printed with as many digits as it needs. If you convert a value of zero with an explicit precision of zero, then no characters at all are produced.
This section discusses the conversion specifications for floating-point numbers: the `%f', `%e', `%E', `%g', and `%G' conversions.
The `%f' conversion prints its argument in fixed-point notation,
producing output of the form
[-
]ddd.
ddd,
where the number of digits following the decimal point is controlled
by the precision you specify.
The `%e' conversion prints its argument in exponential notation,
producing output of the form
[-
]d.
ddde
[+
|-
]dd.
Again, the number of digits following the decimal point is controlled by
the precision. The exponent always contains at least two digits. The
`%E' conversion is similar but the exponent is marked with the letter
`E' instead of `e'.
The `%g' and `%G' conversions print the argument in the style of `%e' or `%E' (respectively) if the exponent would be less than -4 or greater than or equal to the precision; otherwise they use the `%f' style. Trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.
The following flags can be used to modify the behavior:
The precision specifies how many digits follow the decimal-point
character for the `%f', `%e', and `%E' conversions. For
these conversions, the default precision is 6
. If the precision
is explicitly 0
, this suppresses the decimal point character
entirely. For the `%g' and `%G' conversions, the precision
specifies how many significant digits to print. Significant digits are
the first digit before the decimal point, and all the digits after it.
If the precision is 0
or not specified for `%g' or
`%G', it is treated like a value of 1
. If the value being
printed cannot be expressed precisely in the specified number of digits,
the value is rounded to the nearest number that fits.
This section describes miscellaneous conversions for printf
.
The `%c' conversion prints a single character. The `-' flag can be used to specify left-justification in the field, but no other flags are defined, and no precision or type modifier can be given. For example:
printf ("%c%c%c%c%c", "h", "e", "l", "l", "o");
prints `hello'.
The `%s' conversion prints a string. The corresponding argument must be a string. A precision can be specified to indicate the maximum number of characters to write; otherwise characters in the string up to but not including the terminating null character are written to the output stream. The `-' flag can be used to specify left-justification in the field, but no other flags or type modifiers are defined for this conversion. For example:
printf ("%3s%-6s", "no", "where");
prints ` nowhere ' (note the leading and trailing spaces).
Octave provides the scanf
, fscanf
, and sscanf
functions to read formatted input. There are two forms of each of these
functions. One can be used to extract vectors of data from a file, and
the other is more `C-like'.
The optional argument size specifies the amount of data to read and may be one of
Inf
nr
[nr, Inf]
[nr, nc]
nr * nc
elements, returning a matrix with
nr rows. If the number of elements read is not an exact multiple
of nr, the last column is padded with zeros.
If size is omitted, a value of Inf
is assumed.
A string is returned if template specifies only character conversions.
The number of items successfully read is returned in count.
In the second form, read from fid according to template, with each conversion specifier in template corresponding to a single scalar return value. This form is more `C-like', and also compatible with previous versions of Octave.
fscanf
, except that the characters are taken from the
string string instead of from a stream. Reaching the end of the
string is treated as an end-of-file condition.
fscanf
with fid = stdin
.
It is currently not useful to call scanf
in interactive
programs.
Calls to scanf
are superficially similar to calls to
printf
in that arbitrary arguments are read under the control of
a template string. While the syntax of the conversion specifications in
the template is very similar to that for printf
, the
interpretation of the template is oriented more towards free-format
input and simple pattern matching, rather than fixed-field formatting.
For example, most scanf
conversions skip over any amount of
"white space" (including spaces, tabs, and newlines) in the input
file, and there is no concept of precision for the numeric input
conversions as there is for the corresponding output conversions.
Ordinarily, non-whitespace characters in the template are expected to
match characters in the input stream exactly.
When a matching failure occurs, scanf
returns immediately,
leaving the first non-matching character as the next character to be
read from the stream, and scanf
returns all the items that were
successfully converted.
The formatted input functions are not used as frequently as the formatted output functions. Partly, this is because it takes some care to use them properly. Another reason is that it is difficult to recover from a matching error.
A scanf
template string is a string that contains ordinary
multibyte characters interspersed with conversion specifications that
start with `%'.
Any whitespace character in the template causes any number of whitespace characters in the input stream to be read and discarded. The whitespace characters that are matched need not be exactly the same whitespace characters that appear in the template string. For example, write ` , ' in the template to recognize a comma with optional whitespace before and after.
Other characters in the template string that are not part of conversion specifications must match characters in the input stream exactly; if this is not the case, a matching failure occurs.
The conversion specifications in a scanf
template string
have the general form:
% flags width type conversion
In more detail, an input conversion specification consists of an initial `%' character followed in sequence by:
scanf
finds a conversion
specification that uses this flag, it reads input as directed by the
rest of the conversion specification, but it discards this input, does
not use a pointer argument, and does not increment the count of
successful assignments.
scanf
function, but is recognized to provide
compatibility with the C language scanf
.
The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they allow.
Here is a table that summarizes the various conversion specifications:
If the syntax of a conversion specification is invalid, the behavior is undefined. If there aren't enough function arguments provided to supply addresses for all the conversion specifications in the template strings that perform assignments, or if the arguments are not of the correct types, the behavior is also undefined. On the other hand, extra arguments are simply ignored.
This section describes the scanf
conversions for reading numeric
values.
The `%d' conversion matches an optionally signed integer in decimal radix.
The `%i' conversion matches an optionally signed integer in any of the formats that the C language defines for specifying an integer constant.
For example, any of the strings `10', `0xa', or `012'
could be read in as integers under the `%i' conversion. Each of
these specifies a number with decimal value 10
.
The `%o', `%u', and `%x' conversions match unsigned integers in octal, decimal, and hexadecimal radices, respectively.
The `%X' conversion is identical to the `%x' conversion. They both permit either uppercase or lowercase letters to be used as digits.
Unlike the C language scanf
, Octave ignores the `h',
`l', and `L' modifiers.
This section describes the scanf
input conversions for reading
string and character values: `%s' and `%c'.
The `%c' conversion is the simplest: it matches a fixed number of characters, always. The maximum field with says how many characters to read; if you don't specify the maximum, the default is 1. This conversion does not skip over initial whitespace characters. It reads precisely the next n characters, and fails if it cannot get that many.
The `%s' conversion matches a string of non-whitespace characters. It skips and discards initial whitespace, but stops when it encounters more whitespace after having read something.
For example, reading the input:
hello, world
with the conversion `%10c' produces " hello, wo"
, but
reading the same input with the conversion `%10s' produces
"hello,"
.
Octave can read and write binary data using the functions fread
and fwrite
, which are patterned after the standard C functions
with the same names. The are able to automatically swap the byte order
of integer data and convert among ths supported floating point formats
as the data are read.
The optional argument size specifies the amount of data to read and may be one of
Inf
nr
[nr, Inf]
[nr, nc]
nr * nc
elements, returning a matrix with
nr rows. If the number of elements read is not an exact multiple
of nr, the last column is padded with zeros.
If size is omitted, a value of Inf
is assumed.
The optional argument precision is a string specifying the type of data to read and may be one of
"char"
"char*1"
"integer*1"
"int8"
"signed char"
"schar"
"unsigned char"
"uchar"
"short"
"unsigned short"
"ushort"
"int"
"unsigned int"
"uint"
"long"
"unsigned long"
"ulong"
"float"
"float32"
"real*4"
"double"
"float64"
"real*8"
"integer*2"
"int16"
"integer*4"
"int32"
The default precision is "uchar"
.
The optional argument skip specifies the number of bytes to skip before each element is read. If it is not specified, a value of 0 is assumed.
The optional argument arch is a string specifying the data format for the file. Valid values are
"native"
"ieee-le"
"ieee-be"
"vaxd"
"vaxg"
"cray"
Conversions are currently only supported for "ieee-be"
and
"ieee-le"
formats.
The data read from the file is returned in val, and the number of
values read is returned in count
The argument data is a matrix of values that are to be written to the file. The values are extracted in column-major order.
The remaining arguments precision, skip, and arch are
optional, and are interpreted as described for fread
.
The behavior of fwrite
is undefined if the values in data
are too large to fit in the specified precision.
Since the named file is not opened, by tmpnam
, it
is possible (though relatively unlikely) that it will not be available
by the time your program attempts to open it.
freport () -| number mode name -| -| 0 r stdin -| 1 w stdout -| 2 w stderr -| 3 r myfile
Three functions are available for setting and determining the position of the file pointer for a given file.
SEEK_CUR
(current
position), SEEK_SET
(beginning), or SEEK_END
(end of
file). If origin is omitted, SEEK_SET
is assumed. The
offset must be zero, or a value returned by ftell
(in which case
origin must be SEEK_SET
.
fseek
.
fseek (fid, 0, SEEK_SET)
.
The following example stores the current file position in the variable
marker
, moves the pointer to the beginning of the file, reads
four characters, and then returns to the original position.
marker = ftell (myfile); frewind (myfile); fourch = fgets (myfile, 4); fseek (myfile, marker, SEEK_SET);
All of Octave's plotting functions use gnuplot
to handle the
actual graphics. There are two low-level functions, gplot
and
gsplot
, that behave almost exactly like the corresponding
gnuplot
functions plot
and splot
. A number of
other higher level plotting functions, patterned after the graphics
functions found in MATLAB version 3.5, are also available.
These higher level functions are all implemented in terms of the two
low-level plotting functions.
The ranges, using, title, and style arguments are optional, and the using, title and style qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers.
The optional item ranges has the syntax
[ x_lo : x_up ] [ y_lo : y_up ]
and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data. The range for the y axes
and any of the individual limits may be omitted. A range [:]
indicates that the default limits should be used. This normally means
that a range just large enough to include all the data points will be
used.
The expression to be plotted must not contain any literal matrices
(e.g. [ 1, 2; 3, 4 ]
) since it is nearly impossible to
distinguish a plot range from a matrix of data.
See the help for gnuplot
for a description of the syntax for the
optional items.
By default, the gplot
command plots the second column of a matrix
versus the first. If the matrix only has one column, it is taken as a
vector of y-coordinates and the x-coordinate is taken as the element
index, starting with zero. For example,
gplot rand (100,1) with linespoints
will plot 100 random values and connect them with lines. When
gplot
is used to plot a column vector, the indices of the
elements are taken as x values.
If there are more than two columns, you can choose which columns to plot with the using qualifier. For example, given the data
x = (-10:0.1:10)'; data = [x, sin(x), cos(x)];
the command
gplot [-11:11] [-1.1:1.1] \ data with lines, data using 1:3 with impulses
will plot two lines. The first line is generated by the command
data with lines
, and is a graph of the sine function over the
range -10 to 10. The data is taken from the first two columns of
the matrix because columns to plot were not specified with the
using qualifier.
The clause using 1:3
in the second part of this plot command
specifies that the first and third columns of the matrix data
should be taken as the values to plot.
In this example, the ranges have been explicitly specified to be a bit larger than the actual range of the data so that the curves do not touch the border of the plot.
gset
and gshow
commands from gnuplot
are available,
as is replot
.
Note that in Octave 2.0, the set
and show
commands were
renamed to gset
and gshow
in order to allow for
compatibility with the MATLAB graphics and GUI commands in a future
version of Octave. (For now, the old set
and show
commands do work, but they print an annoying warning message to try to
get people to switch to using gset
and gshow
.)
The gset
and gshow
commands allow you to set and show
gnuplot
parameters. For more information about the gset
and gshow
commands, see the documentation for set
and
show
in the gnuplot
user's guide (also available on line
if you run gnuplot
directly, instead of running it from Octave).
The replot
command allows you to force the plot to be
redisplayed. This is useful if you have changed something about the
plot, such as the title or axis labels. The replot
command also
accepts the same arguments as gplot
or gsplot
(except for
data ranges) so you can add additional lines to existing plots.
For example,
gset term tek40 gset output "/dev/plotter" gset title "sine with lines and cosine with impulses" replot "sin (x) w l"
will change the terminal type for plotting, add a title to the current plot, add a graph of to the plot, and force the new plot to be sent to the plot device. This last step is normally required in order to update the plot. This default is reasonable for slow terminals or hardcopy output devices because even when you are adding additional lines with a replot command, gnuplot always redraws the entire plot, and you probably don't want to have a completely new plot generated every time something as minor as an axis label changes.
The command shg
is equivalent to executing replot
without
any arguments.
automatic_replot
to a nonzero value. Since this is fairly
inefficient, the default value is 0.
Note that NaN values in the plot data are automatically omitted, and Inf values are converted to a very large value before calling gnuplot.
The MATLAB-style two-dimensional plotting commands are:
plot (y)
where the argument is taken as the set of y coordinates and the x coordinates are taken to be the indices of the elements, starting with 1.
If more than one argument is given, they are interpreted as
plot (x, y, fmt ...)
where y and fmt are optional, and any number of argument sets may appear. The x and y values are interpreted as follows:
The fmt argument, if present is interpreted as follows. If fmt is missing, the default gnuplot line style is assumed.
@
or -@
specifiers.
"r"
, "g"
, "b"
, "m"
,
"c"
, or "w"
, it is interpreted as the plot color (red,
green, blue, magenta, cyan, or white).
The color line styles have the following meanings on terminals that support color.
Number Gnuplot colors (lines)points style 1 red * 2 green + 3 blue o 4 magenta x 5 cyan house 6 brown there exists
Here are some plot examples:
plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")
This command will plot y
with points of type 2 (displayed as
`+') and color 1 (red), y2
with lines, y3
with lines of
color 4 (magenta) and y4
with points displayed as `+'.
plot (b, "*")
This command will plot the data in the variable b
will be plotted
with points displayed as `*'.
hold on
turns the hold state on. An argument of off
turns the hold state
off, and hold
with no arguments toggles the current hold state.
clg
is aliased to clearplot
for compatibility with MATLAB.
The commands gplot clear, gsplot clear, and replot
clear are equivalent to clearplot
. (Previously, commands like
gplot clear would evaluate clear
as an ordinary expression
and clear all the visible variables.)
gnuplot
subprocess. If you are using X11,
this will close the plot window.
Octave creates temporary data files for gnuplot
and then sends
commands to gnuplot
through a pipe. Octave will delete the
temporary files on exit, but if you are doing a lot of plotting you may
want to clean up in the middle of a session.
A future version of Octave will eliminate the need to use temporary files to hold the plot data.
The argument limits should be a 2, 4, or 6 element vector. The first and second elements specify the lower and upper limits for the x axis. The third and fourth specify the limits for the y axis, and the fifth and sixth specify the limits for the z axis.
With no arguments, axis
turns autoscaling on.
If your plot is already drawn, then you need to use replot
before
the new axis limits will take effect. You can get this to happen
automatically by setting the built-in variable automatic_replot
to a nonzero value.
bar
produces a bar graph.
If only one argument is given, it is taken as a vector of y-values and the x coordinates are taken to be the indices of the elements.
If two output arguments are specified, the data are generated but not plotted. For example,
bar (x, y);
and
[xb, yb] = bar (x, y); plot (xb, yb);
are equivalent.
gnuplot
's contour routines
before this will be very useful.
With one vector input argument, plot a histogram of the values with 10 bins. The range of the histogram bins is determined by the range of the data.
Given a second scalar argument, use that as the number of bins.
Given a second vector argument, use that as the centers of the bins, with the width of the bins determined from the adjacent values in the vector.
Extreme values are lumped in the first and last bins.
With two output arguments, produce the values nn and xx such
that bar (xx, nn)
will plot the histogram.
plot
above for a description of the arguments that
loglog
will accept.
plot
above for a description of the arguments
that semilogx
will accept.
plot
above for a description of the arguments
that semilogy
will accept.
If only one argument is given, it is taken as a vector of y-values and the x coordinates are taken to be the indices of the elements.
If two output arguments are specified, the data are generated but not plotted. For example,
stairs (x, y);
and
[xs, ys] = stairs (x, y); plot (xs, ys);
are equivalent.
The ranges, using, title, and style arguments are optional, and the using, title and style qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers.
The optional item ranges has the syntax
[ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]
and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data. The range for the y and z
axes and any of the individual limits may be omitted. A range
[:]
indicates that the default limits should be used. This
normally means that a range just large enough to include all the data
points will be used.
The expression to be plotted must not contain any literal matrices (e.g.
[ 1, 2; 3, 4 ]
) since it is nearly impossible to distinguish a
plot range from a matrix of data.
See the help for gnuplot
for a description of the syntax for the
optional items.
By default, the gsplot
command plots each column of the
expression as the z value, using the row index as the x value, and the
column index as the y value. The indices are counted from zero, not
one. For example,
gsplot rand (5, 2)
will plot a random surface, with the x and y values taken from the row and column indices of the matrix.
If parametric plotting mode is set (using the command
gset parametric, then gsplot
takes the columns of the
matrix three at a time as the x, y and z values that define a line in
three space. Any extra columns are ignored, and the x and y values are
expected to be sorted. For example, with parametric
set, it
makes sense to plot a matrix like
but not rand (5, 30)
.
The MATLAB-style three-dimensional plotting commands are:
x
, and y from meshdom
and
a matrix z corresponding to the x and y coordinates of
the mesh.
See the file `sombrero.m' for an example of using mesh
and
meshdom
.
"gnuplot"
. See section Installing Octave.
replot
to redisplay it with the new title.
replot
to redisplay it with the new
labels.
The following functions all require a version of gnuplot
that
supports the multiplot feature.
plot
function that works with
the multiplot version of gnuplot
to plot multiple plots per page.
This plot version automatically advances to the next subplot position
after each set of arguments are processed.
See the description of the plot function for the various options.
If the arguments are non-zero, multiplot
will set up multiplot
mode with xn, yn subplots along the x and y
axes. If both arguments are zero, multiplot
closes multiplot
mode.
"blank"
"all"
"north"
"south"
"east"
"west"
The arguments may be abbreviated to single characters. Without any
arguments, plot_border
turns borders off.
gnuplot
in multiplot mode and plots in location
given by index (there are cols by rows subwindows).
Input:
If only one argument is supplied, then it must be a three digit value specifying the location in digits 1 (rows) and 2 (columns) and the plot index in digit 3.
The plot index runs row-wise. First all the columns in a row are filled and then the next row is filled.
For example, a plot with 4 by 2 grid will have plot indices running as follows:
multiplot
function, otherwise this command just becomes an alias
to multiplot
There are a number of functions available for checking to see if the elements of a matrix meet some condition, and for rearranging the elements of a matrix. For example, Octave can easily tell you if all the elements of a matrix are finite, or are less than some specified value. Octave can also rotate the elements, extract the upper- or lower-triangular parts, or sort the columns of a matrix.
The functions any
and all
are useful for determining
whether any or all of the elements of a matrix satisfy some condition.
The find
function is also useful in determining which elements of
a matrix meet a specified condition.
For a matrix argument, return a row vector of ones and zeros with each element indicating whether any of the elements of the corresponding column of the matrix are nonzero. For example,
any (eye (2, 4)) => [ 1, 1, 0, 0 ]
To see if any of the elements of a matrix are nonzero, you can use a statement like
any (any (a))
all
behaves like the function any
, except
that it returns true only if all the elements of a vector, or all the
elements in a column of a matrix, are nonzero.
Since the comparison operators (see section Comparison Operators) return matrices of ones and zeros, it is easy to test a matrix for many things, not just whether the elements are nonzero. For example,
all (all (rand (5) < 0.9)) => 0
tests a random 5 by 5 matrix to see if all of its elements are less than 0.9.
Note that in conditional contexts (like the test clause of if
and
while
statements) Octave treats the test as if you had typed
all (all (condition))
.
[errorcode, a, b] = common_size ([1 2; 3 4], 5) => errorcode = 0 => a = [ 1, 2; 3, 4 ] => b = [ 5, 5; 5, 5 ]
This is useful for implementing functions where arguments can either be scalars or of common size.
diff (x)
is the
vector of first differences
If x is a matrix, diff (x)
is the matrix of column
differences.
The second argument is optional. If supplied, diff (x,
k)
, where k is a nonnegative integer, returns the
k-th differences.
isinf ([13, Inf, NaN]) => [ 0, 1, 0 ]
isnan ([13, Inf, NaN]) => [ 0, 0, 1 ]
finite ([13, Inf, NaN]) => [ 1, 0, 0 ]
find (eye (2)) => [ 1; 4 ]
If two outputs are requested, find
returns the row and column
indices of nonzero elements of a matrix. For example,
[i, j] = find (2 * eye (2)) => i = [ 1; 2 ] => j = [ 1; 2 ]
If three outputs are requested, find
also returns a vector
containing the nonzero values. For example,
[i, j, v] = find (3 * eye (2)) => i = [ 1; 2 ] => j = [ 1; 2 ] => v = [ 3; 3 ]
fliplr ([1, 2; 3, 4]) => 2 1 4 3
flipud ([1, 2; 3, 4]) => 3 4 1 2
rot90 ([1, 2; 3, 4], -1) => 3 1 4 2
rotates the given matrix clockwise by 90 degrees. The following are all equivalent statements:
rot90 ([1, 2; 3, 4], -1) == rot90 ([1, 2; 3, 4], 3) == rot90 ([1, 2; 3, 4], 7)
For example,
reshape ([1, 2, 3, 4], 2, 2) => 1 3 2 4
If the variable do_fortran_indexing
is nonzero, the
reshape
function is equivalent to
retval = zeros (m, n); retval (:) = a;
but it is somewhat less cryptic to use reshape
instead of the
colon operator. Note that the total number of elements in the original
matrix must match the total number of elements in the new matrix.
If x is a matrix, do the same for each column of x.
sort
orders the elements in each
column.
For example,
sort ([1, 2; 2, 3; 3, 1]) => 1 1 2 2 3 3
The sort
function may also be used to produce a matrix
containing the original row indices of the elements in the sorted
matrix. For example,
[s, i] = sort ([1, 2; 2, 3; 3, 1]) => s = 1 1 2 2 3 3 => i = 1 3 2 1 3 2
Since the sort
function does not allow sort keys to be specified,
it can't be used to order the rows of a matrix according to the values
of the elements in various columns(6)
in a single call. Using the second output, however, it is possible to
sort all rows based on the values in a given column. Here's an example
that sorts the rows of a matrix based on the values in the second
column.
a = [1, 2; 2, 3; 3, 1]; [s, i] = sort (a (:, 2)); a (i, :) => 3 1 1 2 2 3
tril
)
or upper (triu
) triangular part of the matrix a, and
setting all other elements to zero. The second argument is optional,
and specifies how many diagonals above or below the main diagonal should
also be set to zero.
The default value of k is zero, so that triu
and
tril
normally include the main diagonal as part of the result
matrix.
If the value of k is negative, additional elements above (for
tril
) or below (for triu
) the main diagonal are also
selected.
The absolute value of k must not be greater than the number of sub- or super-diagonals.
For example,
tril (ones (3), -1) => 0 0 0 1 0 0 1 1 0
and
tril (ones (3), 1) => 1 1 0 1 1 1 1 1 1
eye
returns a square matrix with the dimension specified. If you
supply two scalar arguments, eye
takes them to be the number of
rows and columns. If given a vector with two elements, eye
uses
the values of the elements as the number of rows and columns,
respectively. For example,
eye (3) => 1 0 0 0 1 0 0 0 1
The following expressions all produce the same result:
eye (2) == eye (2, 2) == eye (size ([1, 2; 3, 4])
For compatibility with MATLAB, calling eye
with no arguments
is equivalent to calling it with an argument of 1.
eye
.
If you need to create a matrix whose values are all the same, you should use an expression like
val_matrix = val * ones (n, m)
eye
.
"seed"
, x)
eye
. In
addition, you can set the seed for the random number generator using the
form
rand ("seed", x)
where x is a scalar value. If called as
rand ("seed")
rand
returns the current value of the seed.
"seed"
, x)
eye
. In
addition, you can set the seed for the random number generator using the
form
randn ("seed", x)
where x is a scalar value. If called as
randn ("seed")
randn
returns the current value of the seed.
The rand
and randn
functions use separate generators.
This ensures that
rand ("seed", 13); randn ("seed", 13); u = rand (100, 1); n = randn (100, 1);
and
rand ("seed", 13); randn ("seed", 13); u = zeros (100, 1); n = zeros (100, 1); for i = 1:100 u(i) = rand (); n(i) = randn (); end
produce equivalent results.
Normally, rand
and randn
obtain their initial
seeds from the system clock, so that the sequence of random numbers is
not the same each time you run Octave. If you really do need for to
reproduce a sequence of numbers exactly, you can set the seed to a
specific value.
If it is invoked without arguments, rand
and randn
return a
single element of a random sequence.
The rand
and randn
functions use Fortran code from
RANLIB, a library of fortran routines for random number generation,
compiled by Barry W. Brown and James Lovato of the Department of
Biomathematics at The University of Texas, M.D. Anderson Cancer Center,
Houston, TX 77030.
diag ([1, 2, 3], 1) => 0 1 0 0 0 0 2 0 0 0 0 3 0 0 0 0
The functions linspace
and logspace
make it very easy to
create vectors with evenly or logarithmically spaced elements.
See section Ranges.
The linspace
function always returns a row vector, regardless of
the value of prefer_column_vectors
.
linspace
except that the values are logarithmically
spaced from
If limit is equal to the points are between not in order to be compatible with the corresponding MATLAB function.
treat_neg_dim_as_zero
is nonzero, expressions
like
eye (-1)
produce an empty matrix (i.e., row and column dimensions are zero). Otherwise, an error message is printed and control is returned to the top level. The default value is 0.
The following functions return famous matrix forms.
A Hankel matrix formed from an m-vector c, and an n-vector r, has the elements
inverse (hilb (n))
,
which suffers from the ill-conditioning of the Hilbert matrix, and the
finite precision of your computer's floating point arithmetic.
A square Toeplitz matrix has the form
A Vandermonde matrix has the form
Unless otherwise noted, all of the functions described in this chapter will work for real and complex scalar or matrix arguments.
The following functions are available for working with complex numbers. Each expects a single argument. They are called mapping functions because when given a matrix argument, they apply the given function to each element of the matrix.
ceil (real (x)) + ceil (imag (x)) * I
.
fix (real (x)) + fix (imag (x)) * I
.
floor (real (x)) + floor (imag (x)) * I
.
...
)
gcd (a1, ..., ak)
is the same as
gcd ([a1, ..., ak])
An optional second return value, v contains an integer vector such that
g = v(1) * a(k) + ... + v(k) * a(k)
...
)
lcm (a1, ..., ak)
is the same as
lcm ([a1, ..., ak]).
max (max (x))
returns the largest element of x.
For complex arguments, the magnitude of the elements are used for comparison.
max
, but return the minimum value.
If x is a vector, return nextpow2 (length (x))
.
x / y
, computed using the
expression
x - y .* fix (x ./ y)
An error message is printed if the dimensions of the arguments do not agree, or if either of the arguments is complex.
round (real (x)) + round (imag (x)) * I
.
For complex arguments, sign
returns x ./ abs (x)
.
xor (x, y)
is true if and only if x or y
is true, but not if both x and y are true.
The following functions are available for working with complex numbers. Each expects a single argument. Given a matrix they work on an element by element basis. In the descriptions of the following functions,
For example,
abs (3 + 4i) => 5
in radians.
For example,
arg (3 + 4i) => 0.92730
Octave provides the following trigonometric functions:
Each of these functions expect a single argument. For matrix arguments, they work on an element by element basis. For example,
sin ([1, 2; 3, 4]) => 0.84147 0.90930 0.14112 -0.75680
cumsum ([1, 2; 3, 4]) => 1 2 4 6
cumprod ([1, 2; 3, 4]) => 1 2 3 8
besselj
bessely
besseli
besselk
The second argument, x, must be a real matrix, vector, or scalar.
The first argument, alpha, must be greater than or equal to zero. If alpha is a range, it must have an increment equal to one.
If alpha is a scalar, the result is the same size as x.
If alpha is a range, x must be a vector or scalar, and the
result is a matrix with length(x)
rows and
length(alpha)
columns.
If x has more than one component, both a and b must be scalars. If x is a scalar, a and b must be of compatible dimensions.
For example,
bincoeff (5, 2) => 10
If a is scalar, then gammai (a, x)
is returned
for each element of x and vice versa.
If neither a nor x is scalar, the sizes of a and x must agree, and gammai is applied element-by-element.
cross ([1,1,0], [0,1,1]) => [ 1; -1; 1 ]
If only one argument m is given, is returned.
See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics.
See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics.
I
and J
forms are true constants, and cannot be
modified. The i
and j
forms are like ordinary variables,
and may be used for other purposes. However, unlike other variables,
they once again assume their special predefined values if they are
cleared See section Status of Variables.
Note that NaN always compares not equal to NaN. This behavior is
specified by the IEEE standard for floating point arithmetic. To
find NaN values, you must use the isnan
function.
pi
is computed as `4.0 * atan (1.0)'.
eps
is the largest
relative spacing between any two adjacent numbers in the machine's
floating point system. This number is obviously system-dependent. On
machines that support 64 bit IEEE floating point arithmetic, eps
is approximately
realmax
is approximately
realmin
is approximately
This chapter documents the linear algebra functions of Octave. Reference material for many of these functions may be found in Golub and Van Loan, Matrix Computations, 2nd Ed., Johns Hopkins, 1989, and in LAPACK Users' Guide, SIAM, 1992.
[dd, aa] = balance (a)
returns aa = dd \ a * dd
.
aa
is a matrix whose row and column norms are roughly equal in
magnitude, and dd
= p * d
, where p
is a permutation
matrix and d
is a diagonal matrix of powers of two. This allows
the equilibration to be computed without roundoff. Results of
eigenvalue calculation are typically improved by balancing first.
[cc, dd, aa, bb] = balance (a, b)
returns aa = cc*a*dd
and
bb = cc*b*dd)
, where aa
and bb
have non-zero
elements of approximately the same magnitude and cc
and dd
are permuted diagonal matrices as in dd
for the algebraic
eigenvalue problem.
The eigenvalue balancing option opt
is selected as follows:
"N"
, "n"
"P"
, "p"
"S"
, "s"
"B"
, "b"
Algebraic eigenvalue balancing uses standard LAPACK routines.
Generalized eigenvalue problem balancing uses Ward's algorithm (SIAM Journal on Scientific and Statistical Computing, 1981).
cond (a)
is
defined as norm (a) * norm (inv (a))
, and is computed via a
singular value decomposition.
For example,
givens (1, 1) => 0.70711 0.70711 -0.70711 0.70711
p = 2
is assumed.
If a is a matrix:
1
2
Inf
"fro"
sqrt (sum (diag (a' * a)))
.
If a is a vector or a scalar:
Inf
max (abs (a))
.
-Inf
min (abs (a))
.
(sum (abs (a) .^ p)) ^ (1/p)
.
The dimension of the null space is taken as the number of singular values of a not greater than tol. If the argument tol is missing, it is computed as
max (size (a)) * max (svd (a)) * eps
The dimension of the range space is taken as the number of singular values of a greater than tol. If the argument tol is missing, it is computed as
max (size (a)) * max (svd (a)) * eps
If the second argument is omitted, it is assumed that
tol = max (size (x)) * sigma_max (x) * eps,
where sigma_max (x)
is the maximal singular value of x.
tol = max (size (a)) * sigma (1) * eps;
where eps
is machine precision and sigma
is the largest
singular value of a.
sum (diag (a))
.
The Hessenberg decomposition is usually used as the first step in an eigenvalue computation, but has other applications as well (see Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The Hessenberg decomposition is
a = [1, 2; 3, 4]
,
[l, u, p] = lu (a)
returns
l = 1.00000 0.00000 0.33333 1.00000 u = 3.00000 4.00000 0.00000 0.66667 p = 0 1 1 0
a = [1, 2; 3, 4]
,
[q, r] = qr (a)
returns
q = -0.31623 -0.94868 -0.94868 0.31623 r = -3.16228 -4.42719 0.00000 -0.63246
The qr
factorization has applications in the solution of least
squares problems
for overdetermined systems of equations (i.e.,
is a tall, thin matrix). The QR factorization is
The permuted QR factorization [q, r, p] =
qr (a)
forms the QR factorization such that the diagonal
entries of r
are decreasing in magnitude order. For example,
given the matrix a = [1, 2; 3, 4]
,
[q, r, pi] = qr(a)
returns
q = -0.44721 -0.89443 -0.89443 0.44721 r = -4.47214 -3.13050 0.00000 0.44721 p = 0 1 1 0
The permuted qr
factorization [q, r, p] = qr (a)
factorization allows the construction of an orthogonal basis of
span (a)
.
lambda = qz(A,B)
Computes the generalized eigenvalues lambda of (A - sB).
[AA, BB, Q, Z {, V, W, lambda}] = qz (A, B)
Computes qz decomposition, generalized eigenvectors, and
generalized eigenvalues of (A - sB)
A V = B V diag(lambda) W' A = diag(lambda) W' B AA = Q'*A*Z, BB = Q'*B*Z with Q, Z orthogonal (unitary)= I
[AA,BB,Z{,lambda}] = qz(A,B,opt)
As in form [2], but allows ordering of generalized eigenpairs
for (e.g.) solution of discrete time algebraic Riccati equations.
Form 3 is not available for complex matrices and does not compute
the generalized eigenvectors V, W, nor the orthogonal matrix Q.
"N"
"S"
"B"
"-"
"+"
Note: qz performs permutation balancing, but not scaling (see balance). Order of output arguments was selected for compatibility with MATLAB
See also: balance, dare, eig, schur
(a, b)
, returning
aa = q * a * z
,
bb = q * b * z
, with q and z
orthogonal. For example,
[aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8]) => aa = [ -3.02244, -4.41741; 0.92998, 0.69749 ] => bb = [ -8.60233, -9.99730; 0.00000, -0.23250 ] => q = [ -0.58124, -0.81373; -0.81373, 0.58124 ] => z = [ 1, 0; 0, 1 ]
The Hessenberg-triangular decomposition is the first step in Moler and Stewart's QZ decomposition algorithm.
Algorithm taken from Golub and Van Loan, Matrix Computations, 2nd edition.
The arguments a and b must be real matrices.
are
and dare
).
schur
always returns
where
is a unitary matrix
and
is upper triangular. The eigenvalues of
are the diagonal elements of
If the matrix
is real, then the real Schur decomposition is computed, in which the
matrix
is orthogonal and
is block upper triangular
with blocks of size at most
blocks along the diagonal. The diagonal elements of
(or the eigenvalues of the
blocks, when
appropriate) are the eigenvalues of
and
The eigenvalues are optionally ordered along the diagonal according to
the value of opt
. opt = "a"
indicates that all
eigenvalues with negative real parts should be moved to the leading
block of
(used in are
), opt = "d"
indicates that all eigenvalues
with magnitude less than one should be moved to the leading block of
(used in dare
), and opt = "u"
, the default, indicates that
no ordering of eigenvalues should occur. The leading
columns of
always span the
subspace corresponding to the
leading eigenvalues of
The function svd
normally returns the vector of singular values.
If asked for three return values, it computes
For example,
svd (hilb (3))
returns
ans = 1.4083189 0.1223271 0.0026873
and
[u, s, v] = svd (hilb (3))
returns
u = -0.82704 0.54745 0.12766 -0.45986 -0.52829 -0.71375 -0.32330 -0.64901 0.68867 s = 1.40832 0.00000 0.00000 0.00000 0.12233 0.00000 0.00000 0.00000 0.00269 v = -0.82704 0.54745 0.12766 -0.45986 -0.52829 -0.71375 -0.32330 -0.64901 0.68867
If given a second argument, svd
returns an economy-sized
decomposition, eliminating the unnecessary rows or columns of u or
v.
x = [a(i, j) b]
For example,
kron (1:4, ones (3, 1)) => 1 2 3 4 1 2 3 4 1 2 3 4
syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12]) => [ -0.50000, -0.66667; -0.66667, -0.50000 ]
Octave can solve sets of nonlinear equations of the form
using the function fsolve
, which is based on the MINPACK
subroutine hybrd
.
f (x)
and an initial starting point x0, fsolve
solves the set of
equations such that f(x) == 0
.
fsolve
. Given one argument,
fsolve_options
returns the value of the corresponding option. If
no arguments are supplied, the names of all the available options and
their current values are displayed.
Here is a complete example. To solve the set of equations
you first need to write a function to compute the value of the given function. For example:
function y = f (x) y(1) = -2*x(1)^2 + 3*x(1)*x(2) + 4*sin(x(2)) - 6; y(2) = 3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4; endfunction
Then, call fsolve
with a specified initial condition to find the
roots of the system of equations. For example, given the function
f
defined above,
[x, info] = fsolve ("f", [1; 2])
results in the solution
x = 0.57983 2.54621 info = 1
A value of info = 1
indicates that the solution has converged.
The function perror
may be used to print English messages
corresponding to the numeric error codes. For example,
perror ("fsolve", 1) -| solution converged to requested tolerance
y = f (x)
where y and x are scalars.
The second and third arguments are limits of integration. Either or both may be infinite.
The optional argument tol is a vector that specifies the desired accuracy of the result. The first element of the vector is the desired absolute tolerance, and the second element is the desired relative tolerance. To choose a relative test only, set the absolute tolerance to zero. To choose an absolute test only, set the relative tolerance to zero.
The optional argument sing is a vector of values at which the integrand is known to be singular.
The result of the integration is returned in v and ier contains an integer error code (0 indicates a successful integration). The value of nfun indicates how many function evaluations were required, and err contains an estimate of the error in the solution.
quad
. Given one argument,
quad_options
returns the value of the corresponding option. If
no arguments are supplied, the names of all the available options and
their current values are displayed.
Here is an example of using quad
to integrate the function
This is a fairly difficult integration (plot the function over the range of integration to see why).
The first step is to define the function:
function y = f (x) y = x .* sin (1 ./ x) .* sqrt (abs (1 - x)); endfunction
Note the use of the `dot' forms of the operators. This is not necessary
for the call to quad
, but it makes it much easier to generate a
set of points for plotting (because it makes it possible to call the
function with a vector argument to produce a vector result).
Then we simply call quad:
[v, ier, nfun, err] = quad ("f", 0, 3) => 1.9819 => 1 => 5061 => 1.1522e-07
Although quad
returns a nonzero value for ier, the result
is reasonably accurate (to see why, examine what happens to the result
if you move the lower bound to 0.1, then 0.01, then 0.001, etc.).
Here is an example of using colloc
to generate weight matrices
for solving the second order differential equation
First, we can generate the weight matrices for n points (including the endpoints of the interval), and incorporate the boundary conditions in the right hand side (for a specific value of
n = 7; alpha = 0.1; [r, a, b] = colloc (n-2, "left", "right"); at = a(2:n-1,2:n-1); bt = b(2:n-1,2:n-1); rhs = alpha * b(2:n-1,n) - a(2:n-1,n);
Then the solution at the roots r is
u = [ 0; (at - alpha * bt) \ rhs; 1] => [ 0.00; 0.004; 0.01 0.00; 0.12; 0.62; 1.00 ]
Octave has two built-in functions for solving differential equations. Both are based on reliable ODE solvers written in Fortran.
The function lsode
can be used Solve ODEs of the form
using Hindmarsh's ODE solver LSODE.
The first argument, fcn, is a string that names the function to call to compute the vector of right hand sides for the set of equations. It must have the form
xdot = f (x, t)
where xdot and x are vectors and t is a scalar.
The fourth argument is optional, and may be used to specify a set of times that the ODE solver should not integrate past. It is useful for avoiding difficulties with singularities and points where there is a discontinuity in the derivative.
Here is an example of solving a set of three differential equations using
lsode
. Given the function
function xdot = f (x, t) xdot = zeros (3,1); xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \ - 8.375e-06*x(1)^2); xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27; xdot(3) = 0.161*(x(1) - x(3)); endfunction
and the initial condition x0 = [ 4; 1.1; 4 ]
, the set of
equations can be integrated using the command
t = linspace (0, 500, 1000); y = lsode ("f", x0, t);
If you try this, you will see that the value of the result changes dramatically between t = 0 and 5, and again around t = 305. A more efficient set of output points might be
t = [0, logspace (-1, log10(303), 150), \ logspace (log10(304), log10(500), 150)];
lsode
. Given one argument,
lsode_options
returns the value of the corresponding option. If
no arguments are supplied, the names of all the available options and
their current values are displayed.
See Alan C. Hindmarsh, ODEPACK, A Systematized Collection of ODE
Solvers, in Scientific Computing, R. S. Stepleman, editor, (1983) for
more information about the inner workings of lsode
.
The function dassl
can be used Solve DAEs of the form
using Petzold's DAE solver DASSL.
The first argument, fcn, is a string that names the function to call to compute the vector of residuals for the set of equations. It must have the form
res = f (x, xdot, t)
where x, xdot, and res are vectors, and t is a scalar.
The second and third arguments to dassl
specify the initial
condition of the states and their derivatives, and the fourth argument
specifies a vector of output times at which the solution is desired,
including the time corresponding to the initial condition.
The set of initial states and derivatives are not strictly required to be consistent. In practice, however, DASSL is not very good at determining a consistent set for you, so it is best if you ensure that the initial values result in the function evaluating to zero.
The fifth argument is optional, and may be used to specify a set of times that the DAE solver should not integrate past. It is useful for avoiding difficulties with singularities and points where there is a discontinuity in the derivative.
lsode
. Given one argument,
dassl_options
returns the value of the corresponding option. If
no arguments are supplied, the names of all the available options and
their current values are displayed.
See K. E. Brenan, et al., Numerical Solution of Initial-Value Problems in Differential-Algebraic Equations, North-Holland (1989) for more information about the implementation of DASSL.
Each row of Y and X is an observation and each column a variable.
The return values beta, v, and r are defined as follows.
s^2
.
r = y - x *
beta
.
Each row of y and x is an observation and each column a variable.
The return values beta, sigma, and r are defined as follows.
beta = pinv (x) *
y
, where pinv (x)
denotes the pseudoinverse of
x.
sigma = (y-x*beta)' * (y-x*beta) / (t-rank(x))
r = y - x * beta
.
I hope that someday Octave will include more statistics functions. If you would like to help improve Octave in this area, please contact bug-octave@bevo.che.wisc.edu.
cov (x, y)
is the covariance between the i-th
variable in x and the j-th variable in y. If called
with one argument, compute cov (x, x)
.
corrcoef (x, y)
is the correlation between the
i-th variable in x and the j-th variable in y.
If called with one argument, compute corrcoef (x, x)
.
of x. If x is a matrix, return the row vector containing the kurtosis of each column.
of x. If x is a matrix, return the row vector containing the skewness of each column.
Octave has a limited set of functions for managing sets of data, where a set is defined as a collection unique elements.
create_set ([ 1, 2; 3, 4; 4, 2 ]) => [ 1, 2, 3, 4 ]
union ([ 1, 2, 4 ], [ 2, 3, 5 ]) => [ 1, 2, 3, 4, 5 ]
intersection ([ 1, 2, 3 ], [ 2, 3, 5 ]) => [ 2, 3 ]
complement ([ 1, 2, 3 ], [ 2, 3, 5 ]) => 5
In Octave, a polynomial is represented by its coefficients (arranged in descending order). For example, a vector of length corresponds to the following polynomial of order
The companion matrix is
The eigenvalues of the companion matrix are equal to the roots of the polynomial.
y = conv (a, b)
returns a vector of length equal to
length (a) + length (b) - 1
.
If a and b are polynomial coefficient vectors, conv
returns the coefficients of the product polynomial.
[b, r] = deconv (y, a)
solves for b and r such that
y = conv (a, b) + r
.
If y and a are polynomial coefficient vectors, b will contain the coefficients of the polynomial quotient and r will be a remander polynomial of lowest order.
poly (a)
is the row vector of the coefficients of det (z * eye (N) - a)
,
the characteristic polynomial of a. If x is a vector,
poly (x)
is a vector of coefficients of the polynomial
whose roots are the elements of x.
If two output arguments are requested, the second contains the values of the polynomial for each value of x.
The constant of integration is set to zero.
polyval (c, x)
will evaluate the polynomial at the
specified value of x.
If x is a vector or matrix, the polynomial is evaluated at each of the elements of x.
polyvalm (c, x)
will evaluate the polynomial in the
matrix sense, i.e. matrix multiplication is used instead of element by
element multiplication as is used in polyval.
The argument x must be a square matrix.
The function residue
returns r, p, k, and
e, where the vector r contains the residue terms, p
contains the pole values, k contains the coefficients of a direct
polynomial term (if it exists) and e is a vector containing the
powers of the denominators in the partial fraction terms.
Assuming b and a represent polynomials we have:
where M is the number of poles (the length of the r, p, and e vectors) and N is the length of the k vector.
The argument tol is optional, and if not specified, a default value of 0.001 is assumed. The tolerance value is used to determine whether poles with small imaginary components are declared real. It is also used to determine if two poles are distinct. If the ratio of the imaginary part of a pole to the real part is less than tol, the imaginary part is discarded. If two poles are farther apart than tol they are distinct. For example,
b = [1, 1, 1]; a = [1, -5, 8, -4]; [r, p, k, e] = residue (b, a); => r = [-2, 7, 3] => p = [2, 2, 1] => k = [](0x0) => e = [1, 2, 1]
which implies the following partial fraction expansion
For a vector v with N components, return the roots of the polynomial
The Octave Control Systems Toolbox (OCST) was initially developed by Dr. A. Scottedward Hodel a.s.hodel@eng.auburn.edu with the assistance of his students
This development was supported in part by NASA's Marshall Space Flight
Center as part of an in-house CACSD environment. Additional important
contributions were made by Dr. Kai Mueller mueller@ifr.ing.tu-bs.de
and Jose Daniel Munoz Frias (place.m
).
An on-line menu-driven tutorial is available via section OCST demo program; beginning OCST users should start with this program.
octave:1> DEMOcontrol O C T A V E C O N T R O L S Y S T E M S T O O L B O X Octave Controls System Toolbox Demo [ 1] System representation [ 2] Block diagram manipulations [ 3] Frequency response functions [ 4] State space analysis functions [ 5] Root locus functions [ 6] LQG/H2/Hinfinity functions [ 7] End
Command examples are interactively run for users to observe the use of OCST functions.
The OCST stores all dynamic systems in a single data structure format that can represent continuous systems, discrete-systems, and mixed (hybrid) systems in state-space form, and can also represent purely continuous/discrete systems in either transfer function or pole-zero form. In order to provide more flexibility in treatment of discrete/hybrid systems, the OCST also keeps a record of which system outputs are sampled.
Octave structures are accessed with a syntax much like that used by the C programming language. For consistency in use of the data structure used in the OCST, it is recommended that the system structure access m-files be used (See section System Construction and Interface Functions). Some elements of the data structure are absent depending on the internal system representation(s) used. More than one system representation can be used for SISO systems; the OCST m-files ensure that all representations used are consistent with one another.
The data structure elements (and variable types) common to all system
representations are listed below; examples of the initialization
and use of the system data structures are given in subsequent sections and
in the online demo DEMOcontrol
.
tf2sys
or fir2sys
)
=1 for zp form (initialized with zp2sys
)
=2 for ss form (initialized with ss2sys
)
sysupdate
command.
The remaining variables of the system data structure are only present
if the corresponding entry of the sys
vector is true (=1).
tf
format variableszp
format variablesss
format variablesbode
, hinfsyn
)
will not accept systems with both discrete and continuous states/outputs
Construction and manipulations of the OCST system data structure (See section System Data Structure) requires attention to many details in order to ensure that data structure contents remain consistent. Users are strongly encouraged to use the system interface functions in this section. Functions for the formatted display in of system data structures are given in section System display functions.
Inputs:
Outputs sys (system data structure)
Example
octave:1> sys = fir2sys([1 -1 2 4],0.342,"A/D input","filter output"); octave:2> sysout(sys) Input(s) 1: A/D input Output(s): 1: filter output (discrete) Sampling interval: 0.342 transfer function form: 1*z^3 - 1*z^2 + 2*z^1 + 4 ------------------------- 1*z^3 + 0*z^2 + 0*z^1 + 0
Extract FIR data from system data structure; see section Finite impulse response system interface functions for parameter descriptions.
Inputs
rows
(a), nz = 0
rows
(a)
see below for system partitioning
x_n
for continuous states,
xd_n
for discrete states
u_n
y_n
rows
(c)
sys2ss
returns a vector yd where
yd(outlist) = 1; all other entries of yd are 0.
Outputs outsys = system data structure
System partitioning
Suppose for simplicity that outlist specified that the first several outputs were continuous and the remaining outputs were discrete. Then the system is partitioned as
x = [ xc ] (n x 1) [ xd ] (nz x 1 discrete states) a = [ acc acd ] b = [ bc ] [ adc add ] [ bd ] c = [ ccc ccd ] d = [ dc ] [ cdc cdd ] [ dd ] (cdc = c(outlist,1:n), etc.)
with dynamic equations:
Signal partitions
| continuous | discrete | ---------------------------------------------------- states | stname(1:n,:) | stname((n+1):(n+nz),:) | ---------------------------------------------------- outputs | outname(cout,:) | outname(outlist,:) | ----------------------------------------------------
where cout is the list of in 1:rows
(p)
that are not contained in outlist. (Discrete/continuous outputs
may be entered in any order desired by the user.)
Example
octave:1> a = [1 2 3; 4 5 6; 7 8 10]; octave:2> b = [0 0 ; 0 1 ; 1 0]; octave:3> c = eye(3); octave:4> sys = ss2sys(a,b,c,[],0,3,0,list("volts","amps","joules")); octave:5> sysout(sys); Input(s) 1: u_1 2: u_2 Output(s): 1: y_1 2: y_2 3: y_3 state-space form: 3 continuous states, 0 discrete states State(s): 1: volts 2: amps 3: joules A matrix: 3 x 3 1 2 3 4 5 6 7 8 10 B matrix: 3 x 2 0 0 0 1 1 0 C matrix: 3 x 3 1 0 0 0 1 0 0 0 1 D matrix: 3 x 3 0 0 0 0 0 0
Notice that the D matrix is constructed by default to the correct dimensions. Default input and output signals names were assigned since none were given.
Inputs sys system data structure (See section System Data Structure)
Outputs
Example
octave:1> sys=tf2sys([1 2],[3 4 5]); octave:2> [a,b,c,d] = sys2ss(sys) a = 0.00000 1.00000 -1.66667 -1.33333 b = 0 1 c = 0.66667 0.33333 d = 0
Inputs
Outputs sys = system data structure
Example
octave:1> sys=tf2sys([2 1],[1 2 1],0.1); octave:2> sysout(sys) Input(s) 1: u_1 Output(s): 1: y_1 (discrete) Sampling interval: 0.1 transfer function form: 2*z^1 + 1 ----------------- 1*z^2 + 2*z^1 + 1
See section Transfer function system interface functions for parameter descriptions.
Example
octave:1> sys=ss2sys([1 -2; -1.1,-2.1],[0;1],[1 1]); octave:2> [num,den] = sys2tf(sys) num = 1.0000 -3.0000 den = 1.0000 1.1000 -4.3000
Inputs
Outputs sys: system data structure
Example
octave:1> sys=zp2sys([1 -1],[-2 -2 0],1); octave:2> sysout(sys) Input(s) 1: u_1 Output(s): 1: y_1 zero-pole form: 1 (s - 1) (s + 1) ----------------- s (s + 2) (s + 2)
See section Zero-pole system interface functions for parameter descriptions.
Example
octave:1> sys=ss2sys([1 -2; -1.1,-2.1],[0;1],[1 1]); octave:2> [zer,pol,k] = sys2zp(sys) zer = 3.0000 pol = -2.6953 1.5953 k = 1
syssetsignals
Inputs
"all"
"cst"
"dst"
"in"
"out"
Outputs
Inputs
"in"
"out"
"st"
"yd"
0
1
Outputs
sigid="in"
sigid="out"
sigid="st"
sigid="yd"
"in"
,
"out"
, or "st"
), or else the logical flag
indicating whether output(s) signum is(are) discrete (sigval=1)
or continuous (sigval=0).
Examples (From sysrepdemo
)
octave> sys=ss2sys(rand(4),rand(4,2),rand(3,4)); octave> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys) i # get all signal names Ast = ( [1] = x_1 [2] = x_2 [3] = x_3 [4] = x_4 ) Ain = ( [1] = u_1 [2] = u_2 ) Aout = ( [1] = y_1 [2] = y_2 [3] = y_3 ) Ayd = 0 0 0 octave> Ain = sysgetsignals(sys,"in") # get only input signal names Ain = ( [1] = u_1 [2] = u_2 ) octave> Aout = sysgetsignals(sys,"out",2) # get name of output 2 (in list) Aout = ( [1] = y_2 ) octave> Aout = sysgetsignals(sys,"out",2,1) # get name of output 2 (as string) Aout = y_2
Inputs sys: system data structure
Outputs
systype: string indicating how the structure was initially
constructed:
values: "ss"
, "zp"
, or "tf"
Note FIR initialized systems return systype="tf"
.
"out"
"in"
"st"
"yd"
opt = "out", "in", or "st"
opt = "yd"
Outputs retsys=sys with appropriate signal names changed (or yd values, where appropriate)
Example
octave:1> sys=ss2sys([1 2; 3 4],[5;6],[7 8]); octave:2> sys = syssetsignals(sys,"st",str2mat("Posx","Velx")); octave:3> sysout(sys) Input(s) 1: u_1 Output(s): 1: y_1 state-space form: 2 continuous states, 0 discrete states State(s): 1: Posx 2: Velx A matrix: 2 x 2 1 2 3 4 B matrix: 2 x 1 5 6 C matrix: 1 x 2 7 8 D matrix: 1 x 1 0
Inputs
"tf"
"zp"
"ss"
"all"
Outputs retsys: contains union of data in sys and requested data. If requested data in sys is already up to date then retsys=sys.
Conversion to tf
or zp
exits with an error if the system is
mixed continuous/digital.
used internally, minimal argument checking
Example ioname = sysdefioname(5,"u",3)
returns the list:
ioname = ( [1] = u_3 [2] = u_4 [3] = u_5 )
used internally, minimal argument checking
[]
"ss"
"tf"
"zp"
"all"
c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
to string y or to the screen (if y is omitted)
x defaults to the string "s"
"s"
"s"
Inputs
1:rows(lmat)
Outputs prints the list to the screen, numbering each string in order.
See section System Analysis-Time Domain
Unless otherwise noted, all parameters (input,output) are system data structures.
Contributed by Kai Mueller.
Form an arbitrary complex (open or closed loop) system in
state-space form from several systems. "buildssic
" can
easily (despite it's cryptic syntax) integrate transfer functions
from a complex block diagram into a single system with one call.
This function is especially useful for building open loop
interconnections for H_infinity and H2 designs or for closing
loops with these controllers.
Although this function is general purpose, the use of "sysgroup
"
"sysmult
", "sysconnect
" and the like is recommended for standard
operations since they can handle mixed discrete and continuous
systems and also the names of inputs, outputs, and states.
The parameters consist of 4 lists that describe the connections
outputs and inputs and up to 8 systems s1-s8.
Format of the lists:
[1 2 -1; 2 1 0]
==> new input 1 is old inpout 1
+ output 2 - output 1, new input 2 is old input 2
+ output 1. The order of rows is arbitrary.
Example: Very simple closed loop system.
w e +-----+ u +-----+ --->o--*-->| K |--*-->| G |--*---> y ^ | +-----+ | +-----+ | - | | | | | | +----------------> u | | | | +-------------------------|---> e | | +----------------------------+
The closed loop system GW can be optained by
GW = buildssic([1 2; 2 -1], [2], [1 2 3], [2], G, K);
Here is a real example:
+----+ -------------------->| W1 |---> v1 z | +----+ ----|-------------+ || GW || => min. | | vz infty | +---+ v +----+ *--->| G |--->O--*-->| W2 |---> v2 | +---+ | +----+ | | | v u y
The closed loop system GW from [z; u]' to [v1; v2; y]' can be obtained by (all SISO systems):
GW = buildssic([1 4;2 4;3 1],[3],[2 3 5],[3 4],G,W1,W2,One);
where "One" is a unity gain (auxillary) function with order 0.
(e.g. One = ugain(1);
)
see also: ord2
Contributed by Kai Mueller
Outputs outsys system data structure has representation with w = 2 * pi * nfreq:
/ \ | / -2w*damp -w \ / w \ | G = | | |, | |, [ 0 gain ], 0 | | \ w 0 / \ 0 / | \ /
See also jet707
(MIMO example, Boeing 707-321 aircraft model)
____________________ | ________ | u ----->|----> | Asys |--->|----> y1 | | -------- | | | ________ | |--->|----> | Bsys |--->|----> y2 | -------- | -------------------- Ksys
________ ----| Gsys |--- u | ---------- +| ----- (_)----> y | ________ +| ----| Hsys |--- --------
Inputs
Outputs sys
sys.b := [sys.b , b] sys.c := [sys.c ] [ c ] sys.d := [sys.d | D12 ] [D21 | D22 ]
where D12, D21, and D22 are the appropriate dimensioned blocks of the input parameter d.
zeros(1,rows(c))
ones(1,rows(c))
Inputs
0
1
Outputs sys: resulting closed loop system.
Method
sysconnect
internally permutes selected inputs, outputs as shown
below, closes the loop, and then permutes inputs and outputs back to their
original order
____________________ u_1 ----->| |----> y_1 | sys | old u_2 | | u_2* ---->(+)--->| |----->y_2 (in_idx) ^ -------------------| | (out_idx) | | -------------------------------
The input that has the summing junction added to it has an * added to the end of the input name.
Inputs sys is a system data structure
Outputs
Inputs sys is a system data structure.
Outputs
Inputs sys = system data structure
Outputs
Inputs
Outputs
retsys: resulting closed loop system:
duplicated i/o names are appended with a "+"
suffix.
Method
sysdup
creates copies of selected inputs and outputs as
shown below. u1/y1 is the set of original inputs/outputs, and
u2,y2 is the set of duplicated inputs/outputs in the order specified
in in_idx, out_idx, respectively
____________________ u1 ----->| |----> y1 | Asys | u2 ------>| |----->y2 (in_idx) -------------------| (out_idx)
Inputs Asys, Bsys: system data structures
Outputs sys = block diag(Asys,Bsys)
__________________ | ________ | u1 ----->|--> | Asys |--->|----> y1 | -------- | | ________ | u2 ----->|--> | Bsys |--->|----> y2 | -------- | ------------------ Ksys
The function also rearranges the internal state-space realization of sys so that the continuous states come first and the discrete states come last. If there are duplicate names, the second name has a unique suffix appended on to the end of the name.
u ---------- ---------- --->| Bsys |---->| Asys |---> ---------- ----------
A warning occurs if there is direct feed-through from an input of Bsys or a continuous state of Bsys through a discrete output of Bsys to a continuous state or output in Asys (system data structure does not recognize discrete inputs).
Inputs
Outputs retsys: resulting system
____________________ u1 ------->| |----> y1 (in_idx) | Asys | (out_idx) u2 ------->| |----| y2 (deleted)-------------------- (deleted)
Inputs
vlen=vector length, list= a subset of [1:vlen]
,
Outputs
pv: a permutation vector to order elements of [1:vlen]
in
list
to the end of a vector.
Used internally by sysconnect
to permute vector elements to their
desired locations.
Inputs sys: structured system outscale, inscale: constant matrices of appropriate dimension
Outputs sys: resulting open loop system:
----------- ------- ----------- u --->| inscale |--->| sys |--->| outscale |---> y ----------- ------- -----------
If the input names and output names (each a list of strings) are not given and the scaling matrices are not square, then default names will be given to the inputs and/or outputs.
A warning message is printed if outscale attempts to add continuous system outputs to discrete system outputs; otherwise yd is set appropriately in the returned value of sys.
Method: Gsys and Hsys are connected in parallel The input vector is connected to both systems; the outputs are subtracted. Returned system names are those of Gsys.
________ ----| Gsys |--- u | ---------- +| ----- (_)----> y | ________ -| ----| Hsys |--- --------
See also: hinfdemo (MIMO H_infinty example, Boeing 707-321 aircraft model)
Weighting function are needed by the H2/H_infinity design procedure. These function are part of thye augmented plant P (see hinfdemo for an applicattion example).
vl = Gain @ low frequencies
vh = Gain @ high frequencies
fc = Corner frequency (in Hz, *not* in rad/sec)
Inputs for identically dimensioned square matrices
"B"
):
String option passed to balance
prior to ordered Schur decomposition.
Outputs x: solution of the ARE.
Method Laub's Schur method (IEEE Transactions on Automatic Control, 1979) is applied to the appropriate Hamiltonian matrix.
Return the solution, x of the discrete-time algebraic Riccati equation
Inputs
"B"
):
String option passed to balance
prior to ordered QZ decomposition.
Outputs x solution of DARE.
Method Generalized eigenvalue approach (Van Dooren; SIAM J. Sci. Stat. Comput., Vol 2) applied to the appropriate symplectic pencil.
See also: Ran and Rodman, "Stable Hermitian Solutions of Discrete Algebraic Riccati Equations," Mathematics of Control, Signals and Systems, Vol 5, no 2 (1992) pp 165-194.
x(k+1) = a x(k) + b u(k)
Inputs
Outputs m (n by n) satisfies
a m a' - m + b*b' = 0
Inputs
Outputs
x: matrix satisfying appropriate discrete time Lyapunov equation.
Options:
@itemize @bullet
@item b is square: solve a x a' - x + b = 0
@item b is not square: x satisfies either
@example
a x a' - x + b b' = 0
@end example
or
@example
a' x a - x + b' b = 0,
@end example
whichever is appropriate.
@end itemize
Method
Uses Schur decomposition method as in Kitagawa,
An Algorithm for Solving the Matrix Equation X =
FXF' + S,
International Journal of Control, Volume 25, Number 5, pages 745--753
(1977).
Column-by-column solution method as suggested in Hammarling, Numerical Solution of the Stable, Non-Negative Definite Lyapunov Equation, IMA Journal of Numerical Analysis, Volume 2, pages 303--323 (1982).
m satisfies a m + m a' + b b' = 0 .
If a, b, and c are specified, then lyap
returns
the solution of the Sylvester equation
@iftex
@tex
$$ A X + X B + C = 0 $$
@end tex
@end iftex
@ifinfo
@example
a x + x b + c = 0
@end example
@end ifinfo
If only (a, b)
are specified, then lyap
returns the
solution of the Lyapunov equation
@iftex
@tex
$$ A^T X + X A + B = 0 $$
@end tex
@end iftex
@ifinfo
@example
a' x + x a + b = 0
@end example
@end ifinfo
If b is not square, then lyap
returns the solution of either
@iftex
@tex
$$ A^T X + X A + B^T B = 0 $$
@end tex
@end iftex
@ifinfo
@example
a' x + x a + b' b = 0
@end example
@end ifinfo
or
@iftex
@tex
$$ A X + X A^T + B B^T = 0 $$
@end tex
@end iftex
@ifinfo
@example
a x + x a' + b b' = 0
@end example
@end ifinfo
whichever is appropriate.
A and B must be real matrices.
Note qzval
is obsolete; use qz
instead.
tzero
.
Minimal argument checking performed.
Details involving major subroutines:
zgpbal
zgpbal
computes a state/input/output
weighting that attempts to
reduced the range of the magnitudes of the nonzero elements of [a,b,c,d]
The weighting uses scalar multiplication by powers of 2, so no roundoff
will occur.
zgpbal
should be followed by zgpred
zgreduce
zgrownorm
zgscal
zgepbal
zgsgiv
zgshsr
e^(m)
(all ones) to
(column vector) y. Called by zgfslv
.
References:
If the matrices are compatibly dimensioned, then abcddim
returns
Otherwise abcddim
returns n = m = p = -1.
Note: n = 0 (pure gain block) is returned without warning.
See also: is_abcd
Used internally in abcddim
. If x is a zero-size matrix,
both dimensions are set to 0 in y.
my and ny are the row and column dimensions of the result.
2 n-1 Qs = [ B AB A B ... A B ]
of a system data structure or the pair (A, B).
Note ctrb
forms the controllability matrix.
The numerical properties of is_controllable
are much better for controllability tests.
Reference: Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard H2 and Hinf Control Problems", IEEE TAC August 1989
Inputs
Outputs
References: Doyle, Glover, Khargonekar, Francis, "State space solutions to standard H2 and Hinf control problems", IEEE TAC August 1989 Iglesias and Glover, "State-Space approach to discrete-time Hinf control," Int. J. Control, vol 54, #5, 1991 Zhou, Doyle, Glover, "Robust and Optimal Control," Prentice-Hall, 1996 $Revision: 1.9 $
| C | | CA | Qb = | CA^2 | | ... | | CA^(n-1) |
of a system data structure or the pair (A, C).
Note: obsv()
forms the observability matrix.
The numerical properties of is_observable() are much better for observability tests.
Outputs if omitted, the poles and zeros are plotted on the screen. otherwise, pol, zer are returned as the system poles and zeros. (see sys2zp for a preferable function call)
Inputs
10*eps
Outputs
Method Controllability is determined by applying Arnoldi iteration with complete re-orthogonalization to obtain an orthogonal basis of the Krylov subspace
span ([b,a*b,...,a^{n-1}*b]).
The Arnoldi iteration is executed with krylov
if the system has a single input; otherwise a block Arnoldi iteration is performed with krylovb
.
See also
is_observable
, is_stabilizable
, is_detectable
,
krylov
, krylovb
Returns 1 if the system a or the pair (a,c)is detectable, 0 if not.
See is_stabilizable
for detailed description of arguments and
computational method.
[dx/dt] = [A | Bw Bu ][w] [ z ] [Cz | Dzw Dzu ][u] [ y ] [Cy | Dyw Dyu ]
or similar discrete-time system. If necessary, orthogonal transformations Qw, Qz and nonsingular transformations Ru, Ry are applied to respective vectors w, z, u, y in order to satisfy DGKF assumptions. Loop shifting is used if Dyu block is nonzero.
Inputs
Outputs
is_dgkf
results. Entries:
is_dgkf
exits with an error if the system is mixed discrete/continuous
References
is_controllable
for detailed description of arguments
and default values.
is_controllable
for description of inputs, outputs.
Test for stabilizability is performed via an ordered Schur decomposition
that reveals the unstable subspace of the system A matrix.
dflg != 0
dflg == 0
Inputs
"ex"
"bi"
2(z-1) s = ----- T(z+1)FIXME: This option exits with an error if sys is not purely continuous. (The
ex
option can handle mixed systems.)
c2d
assumes that
the 2nd argument is T and performs appropriate argument checks.
Outputs dsys discrete time equivalent via zero-order hold, sample each T sec.
converts the system data structure describing
. x = Ac x + Bc u
into a discrete time equivalent model
x[n+1] = Ad x[n] + Bd u[n]
via the matrix exponential or bilinear transform
Note This function adds the suffix _d
to the names of the new discrete states.
sysgettsam(sys)
Inputs
"log"
option (see below)
"log"
d2c
(sys,tol), tol=positive scalar,
the "log"
option is used. The default value for tol is
1e-8
.
"bi"
sysgettsam
).
FIXME: bilinear option exits with an error if sys is not purely discrete
Outputs csys continuous time system (same dimensions and signal names as in sys).
sysgettsam(sys)
.
Inputs
dmr2d
exits with an error if sys is not discrete
sysgettsam(sys)
(may be empty)
sysgettsam(sys)
(may be empty)
sysgettsam(sys)
Outputs
WARNING Not thoroughly tested yet; especially when cuflg == 0.
See also: eig
impulse
produces a plot or the step response data for system sys.
Inputs
Outputs y, t: impulse response
impulse
.
impulse
, step
.
Demonstration/tutorial script
Inputs
exp
(jwT)), where
sysgettsam(sys)
(the system sampling time) and
exp
(jwT)=1) and select the frequency
range based on the breakpoint locations of the frequencies.
sysprune
.
Outputs
exp
(jwT)) at the selected frequency values.
Notes
bode(sys);bode plots the results to the screen. Descriptive labels are automatically placed. Failure to include a concluding semicolon will yield some garbage being printed to the screen (
ans = []
).
exp
(jwT))||
and phase information is not computed.
Used internally in freqresp (bode
, nyquist
)
Inputs
Outputs
Note bodquist could easily be incorporated into a Nichols plot function; this is in a "to do" list.
freqresp
to check that input frequency vector w is legal.
Returns boolean value.
bode
, nyquist
.
minimal argument checking; "do not attempt to do this at home"
Inputs
freqchkw
Outputs
Outputs out
-1 G(s) = (jw I-A) B
for complex frequencies s = jw.
Arguments are identical to bode
with exceptions as noted below:
Inputs (pass as empty to get default values)
Outputs
If no output arguments are given, nyquist plots the results to the screen. If atol != 0 and asymptotes are detected then the user is asked interactively if they wish to zoom in (remove asymptotes) Descriptive labels are automatically placed.
Note: if the requested plot is for an MIMO system, a warning message is presented; the returned information is of the magnitude ||G(jw)|| or ||G(exp(jwT))|| only; phase information is not computed.
. x = Ax + Bu y = Cx + Du
or discrete
x(k+1) = A x(k) + B u(k) y(k) = C x(k) + D u(k)
system. Outputs
References
bal = balancing option (see balance); default is "B".
Needs to incorporate mvzero
algorithm to isolate finite zeros; use
tzero
instead.
H_infinity optimal controller for the jet707 plant; Linearized state space model of a Boeing 707-321 aircraft at v=80m/s. (M = 0.26, Ga0 = -3 deg, alpha0 = 4 deg, kappa = 50 deg) inputs: (1) thrust and (2) elevator angle outputs: (1) airspeed and (2) pitch angle
The optimal controller minimizes the H_infinity norm of the augmented plant P (mixed-sensitivity problem):
w 1 -----------+ | +----+ +---------------------->| W1 |----> z1 w | | +----+ 2 ------------------------+ | | | | v +----+ v +----+ +--*-->o-->| G |-->o--*-->| W2 |---> z2 | +----+ | +----+ | | ^ v u (from y (to K) controller K) + + + + | z | | w | | 1 | | 1 | | z | = [ P ] * | w | | 2 | | 2 | | y | | u | + + + +
sigw = cov (w, w)
and
sigv = cov (v, v)
.
If specified, z is cov (w, v)
. Otherwise
cov (w, v) = 0
.
The observer structure is
The following values are returned:
z omitted or z included.
The following values are returned:
References
Inputs input system is passed as either
Outputs
hinfsyn
to compute the H_inf optimal controller.
Inputs
is_dgkf
Outputs controller K (system data structure)
Do not attempt to use this at home; no argument checking performed.
Inputs input system is passed as either
c2d
, d2c
)
Outputs
WARNING Argument checking not performed.
Inputs
Outputs
Solution method: Either Laub's schur method or Symplectic GEP approach; uses Van Dooren's code to re-order qz decompostion (www.netlib.com - toms/590)
See also: Ran and Rodman, "Stable Hermitian Solutions of Discrete Algebraic Riccati Equations," Mathematics of Control, Signals and Systems, Vol 5, no 2 (1992) pp 165-194.
hinfsyn
to see if gain g satisfies conditions in
Theorem 3 of
Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard
H2 and Hinf Control Problems", IEEE TAC August 1989
Warning Do not attempt to use this at home; no argument checking performed.
Inputs as returned by is_dgkf
, except for:
hinfsyn
Outputs: retval: = 1 if g exceeds optimal Hinf closed loop gain, else 0 Pc: solution of "regulator" H-inf ARE Pf: solution of "filter" H-inf ARE
sigw = cov (w, w) sigv = cov (v, v)
The optional argument z is the cross-covariance
cov (w, v)
. If it is omitted,
cov (w, v) = 0
is assumed.
Observer structure is dz/dt = A z + B u + k (y - C z - D u)
The following values are returned:
dx/dt = A x + B u + G w [w]=N(0,[Sigw 0 ]) y = C x + v [v] ( 0 Sigv ])
or
x(k+1) = A x(k) + B u(k) + G w(k) [w]=N(0,[Sigw 0 ]) y(k) = C x(k) + v(k) [v] ( 0 Sigv ])
Inputs
Outputs
sys2ss
, sys2tf
, or sys2zp
as appropriate)
z omitted or z included.
The following values are returned:
Produces a plot for the output of the system, sys.
U is an array that contains the system's inputs. Each column in u corresponds to a different time step. Each row in u corresponds to a different input. T is an array that contains the time index of the system. T should be regularly spaced. If initial conditions are required on the system, the x0 vector should be added to the argument list.
When the lsim function is invoked with output parameters: [y,x] = lsim(sys,u,t,[x0]) a plot is not displayed, however, the data is returned in y = system output and x = system states.
Version: Beta (May-1997): If you have any comments, please let me know. (see the file place.m for my address)
Written by: Jose Daniel Munoz Frias.
Inputs axdata nx2 matrix of data [x,y]
Outputs axvec vector of axis limits appropriate for call to axis() function
$Revision: 1.9 $
Octave Controls toolbox demo: Model Manipulations demo Written by David Clem August 15, 1994
function prompt([str]) Prompt user to continue str: input string. Default value: "\n ---- Press a key to continue ---" Written by David Clem August 15, 1994 Modified A. S. Hodel June 1995
[rldata, k] = rlocus(sys[,increment,min_k,max_k]) Displays root locus plot of the specified SISO system. ----- -- -------- --->| + |---|k|---->| SISO |-----------> ----- -- -------- | - ^ | |_____________________________| inputs: sys = system data structure min_k, max_k,increment: minimum, maximum values of k and the increment used in computing gain values Outputs: plots the root locus to the screen. rldata: Data points plotted column 1: real values, column 2: imaginary values) k: gains for real axis break points.
[yy,idx] = sortcom(xx[,opt]): sort a complex vector xx: complex vector opt: sorting option: "re": real part (default) "mag": by magnitude "im": by imaginary part if opt != "im" then complex conjugate pairs are grouped together, a - jb followed by a + jb. yy: sorted values idx: permutation vector: yy = xx(idx)
[num,den] = ss2tf(a,b,c,d) Conversion from tranfer function to state-space. The state space system . x = Ax + Bu y = Cx + Du is converted to a transfer function num(s) G(s)=------- den(s) used internally in system data structure format manipulations
Converts a state space representation to a set of poles and zeros. [pol,zer,k] = ss2zp(a,b,c,d) returns the poles and zeros of the state space system (a,b,c,d). K is a gain associated with the zeros. used internally in system data structure format manipulations
[sys] = starp(P, K, ny, nu) Redheffer star product or upper/lower LFT, respectively. +-------+ --------->| |---------> | P | +--->| |---+ ny | +-------+ | +-------------------+ | | +----------------+ | | | | +-------+ | +--->| |------+ nu | K | --------->| |---------> +-------+ If ny and nu "consume" all inputs and outputs of K then the result is a lower fractional transformation. If ny and nu "consume" all inputs and outputs of P then the result is an upper fractional transformation. ny and/or nu may be negative (= negative feedback)
[a1,b1] = swap(a,b) interchange a and b
function B = swapcols(A) permute columns of A into reverse order
function B = swaprows(A) permute rows of A into reverse order
Conversion from tranfer function to state-space. The state space system . x = Ax + Bu y = Cx + Du is obtained from a transfer function num(s) G(s)=------- den(s) via the function call [a,b,c,d] = tf2ss(num,den). The vector 'den' must contain only one row, whereas the vector 'num' may contain as many rows as there are outputs of the system 'y'. The state space system matrices obtained from this function will be in controllable canonical form as described in "Modern Control Theory", [Brogan, 1991].
Converts transfer functions to poles / zeros. [zer,pol,k] = tf2zp(num,den) returns the zeros and poles of the SISO system defined by num/den. K is a gain associated with the system zeros.
. x = Ax + Bu y = Cx + Du
is obtained from a vector of zeros and a vector of poles via the
function call [a,b,c,d] = zp2ss(zer,pol,k)
.
The vectors `zer' and
`pol' may either be row or column vectors. Each zero and pole that
has an imaginary part must have a conjugate in the list.
The number of zeros must not exceed the number of poles.
`k' is zp
-form leading coefficient.
zp2ss
Extract 2 values from rvals (if possible) and construct
a polynomial with those roots.
[num,den] = zp2tf(zer,pol,k)
forms the transfer function
num/den
from the vectors of poles and zeros.
I hope that someday Octave will include more signal processing functions. If you would like to help improve Octave in this area, please contact bug-octave@bevo.che.wisc.edu.
detrend (x, p)
removes the
best fit of a polynomial of order p from the data x.
If x is a matrix, detrend (x, p)
does the same
for each column in x.
The second argument is optional. If it is not specified, a value of 1 is assumed. This corresponds to removing a linear trend.
fft
computes the FFT for each column of a.
If called with two arguments, n is expected to be an integer specifying the number of elements of a to use. If a is a matrix, n specifies the number of rows of a to use. If n is larger than the size of a, a is resized and padded with zeros.
fft
computes the inverse FFT for each column
of a.
If called with two arguments, n is expected to be an integer specifying the number of elements of a to use. If a is a matrix, n specifies the number of rows of a to use. If n is larger than the size of a, a is resized and padded with zeros.
The optional arguments n and m may be used specify the number of rows and columns of a to use. If either of these is larger than the size of a, a is resized and padded with zeros.
The optional arguments n and m may be used specify the number of rows and columns of a to use. If either of these is larger than the size of a, a is resized and padded with zeros.
length (a) + length (b) - 1
. If a
and b are the coefficient vectors of two polynomials, the returned
value is the coefficient vector of the product polynomial.
The computation uses the FFT by calling the function fftfilt
. If
the optional argument n is specified, an N-point FFT is used.
With two arguments, fftfilt
filters x with the FIR filter
b using the FFT.
Given the optional third argument, n, fftfilt
uses the
overlap-add method to filter x with b using an N-point FFT.
where An equivalent form of this equation is:
where
In terms of the z-transform, y is the result of passing the discrete- time signal x through a system characterized by the following rational system function:
filter
function described above, except
that si is taken as the initial state of the system and the final
state is returned as sf. The state vector is a column vector
whose length is equal to the length of the longest coefficient vector
minus one. If si is not set, the initial state vector is set to
all zeros.
The output value w is a vector of the frequencies.
If the fourth argument is omitted, the response is evaluated at frequencies between 0 and
If n is omitted, a value of 512 is assumed.
If a is omitted, the denominator is assumed to be 1 (this corresponds to a simple FIR filter).
For fastest computation, n should factor into a small number of small primes.
Octave can display images with the X Window System using the
xloadimage
program. You do not need to be running X in order to
manipulate images, however, so some of these functions may be useful
even if you are not able to view the results.
Loading images only works with Octave's image format (a file with a matrix containing the image data, and a matrix containing the colormap). Contributions of robust, well-written functions to read other image formats are welcome. If you can provide them, or would like to improve Octave's image processing capabilities in other ways, please contact bug-octave@bevo.che.wisc.edu.
colormap (map)
sets the current colormap to map. The
color map should be an n row by 3 column matrix. The columns
contain red, green, and blue intensities respectively. All entries
should be between 0 and 1 inclusive. The new colormap is returned.
colormap ("default")
restores the default colormap (a gray scale
colormap with 64 entries). The default colormap is returned.
With no arguments, colormap
returns the current color map.
imshow (x)
displays an indexed image using the current
colormap.
imshow (x, map)
displays an indexed image using the
specified colormap.
imshow (i, n)
displays a gray scale intensity image.
imshow (r, g, b)
displays an RGB image.
"img"
"ppm"
"ps"
If the fourth argument is supplied, the specified colormap will also be saved along with the image.
Note: if the colormap contains only two entries and these entries are black and white, the bitmap ppm and PostScript formats are used. If the image is a gray scale image (the entries within each row of the colormap are equal) the gray scale ppm and PostScript image formats are used, otherwise the full color formats are used.
Octave provides a few functions for dealing with audio data. An audio `sample' is a single output value from an A/D converter, i.e., a small integer number (usually 8 or 16 bits), and audio data is just a series of such samples. It can be characterized by three parameters: the sampling rate (measured in samples per second or Hz, e.g. 8000 or 44100), the number of bits per sample (e.g. 8 or 16), and the number of channels (1 for mono, 2 for stereo, etc.).
There are many different formats for representing such data. Currently,
only the two most popular, linear encoding and mu-law
encoding, are supported by Octave. There is an excellent FAQ on audio
formats by Guido van Rossum <guido@cwi.nl> which can be found at any
FAQ ftp site, in particular in the directory
`/pub/usenet/news.answers/audio-fmts' of the archive site
rtfm.mit.edu
.
Octave simply treats audio data as vectors of samples (non-mono data are not supported yet). It is assumed that audio files using linear encoding have one of the extensions `lin' or `raw', and that files holding data in mu-law encoding end in `au', `mu', or `snd'.
lin2mu (x)
is the corresponding mu-law
encoding.
mu2lin
converts it to linear encoding. The optional argument
bps specifies whether the input data uses 8 bit per sample
(default) or 16 bit.
The extension ext determines how the data in the audio file is interpreted; the extensions `lin' (default) and `raw' correspond to linear, the extensions `au', `mu', or `snd' to mu-law encoding.
The argument bps can be either 8 (default) or 16, and specifies the number of bits per sample used in the audio file.
loadaudio
); defaults are `lin' and
8, respectively.
The following functions for audio I/O require special A/D hardware and operating system support. It is assumed that audio data in linear encoding can be played and recorded by reading from and writing to `/dev/dsp', and that similarly `/dev/audio' is used for mu-law encoding. These file names are system-dependent. Improvements so that these functions will work without modification on a wide variety of hardware are welcome.
For example, if vol
corresponds to the volume property, you can
set it to 50 (percent) by setaudio ("vol", 50)
.
This is an simple experimental program to control the audio hardware
settings. It assumes that there is a mixer
program which can be
used as mixer type value
, and simply executes
system ("mixer type value")
. Future releases might
get rid of this assumption by using the fcntl
interface.
This chapter describes the functions that are available to allow you to get information about what is happening outside of Octave, while it is still running, and use this information in your program. For example, you can get information about environment variables, the current time, and even start other programs from the Octave prompt.
Octave's core set of functions for manipulating time values are patterned after the corresponding functions from the standard C library. Several of these functions use a data structure for time that includes the following elements:
usec
sec
min
hour
mday
mon
year
wday
yday
isdst
zone
In the descriptions of the following functions, this structure is referred to as a tm_struct.
time
was 856163706.
time
(or any other nonnegative
integer), to the local time and return a string of the same form as
asctime
. The function ctime (time)
is equivalent to
asctime (localtime (time))
. For example,
ctime (time ()) => "Mon Feb 17 01:15:06 1997"
gmtime (time ()) => { usec = 0 year = 97 mon = 1 mday = 17 sec = 6 zone = CST min = 15 wday = 1 hour = 7 isdst = 0 yday = 47 }
localtime (time ()) => { usec = 0 year = 97 mon = 1 mday = 17 sec = 6 zone = CST min = 15 wday = 1 hour = 1 isdst = 0 yday = 47 }
mktime (localtime (time ()) => 856163706
asctime (localtime (time ()) => "Mon Feb 17 01:15:06 1997\n"
This is equivalent to ctime (time ())
.
printf
. Except where noted, substituted
fields have a fixed size; numeric fields are padded if necessary.
Padding is with zeros by default; for fields that display a single
number, padding can be changed or inhibited by following the `%'
with one of the modifiers described below. Unknown field specifiers are
copied as normal characters. All other characters are copied to the
output without change. For example,
strftime ("%r (%Z) %A %e %B %Y", localtime (time ()) => "01:15:06 AM (CST) Monday 17 February 1997"
Octave's strftime
function supports a superset of the ANSI C
field specifiers.
Literal character fields:
%
n
t
Numeric modifiers (a nonstandard extension):
- (dash)
_ (underscore)
Time fields:
%H
%I
%k
%l
%M
%p
%r
%R
%s
%S
%T
%X
%Z
Date fields:
%a
%A
%b
%B
%c
%C
%d
%e
%D
%h
%j
%m
%U
%w
%W
%x
%y
%Y
Most of the remaining functions described in this section are not patterned after the standard C library. Some are available for compatiblity with MATLAB and others are provided because they are useful.
clock () => [ 1993, 8, 20, 4, 56, 1 ]
The function clock is more accurate on systems that have the
gettimeofday
function.
date () => "20-Aug-93"
clock
. For example:
t0 = clock (); # many computations later... elapsed_time = etime (clock (), t0);
will set the variable elapsed_time
to the number of seconds since
the variable t0
was set.
cputime
returns 0 for each of its output values.
Note that because Octave used some CPU time to start, it is reasonable
to check to see if cputime
works by checking to see if the total
CPU time used is nonzero.
is_leap_year
will use the current year.
For example,
is_leap_year (2000) => 1
tic (); # many computations later... elapsed_time = toc ();
will set the variable elapsed_time
to the number of seconds since
the most recent call to the function tic
.
If you are more interested in the CPU time that your process used, you
should use the cputime
function instead. The tic
and
toc
functions report the actual wall clock time that elapsed
between the calls. This may include time spent processing other jobs or
doing nothing at all. For example,
tic (); sleep (5); toc () => 5 t = cputime (); sleep (5); cputime () - t => 0
(This example also illustrates that the CPU timer may have a fairly coarse resolution.)
fprintf (stderr, "wait please...\n"); pause (5); clc;
usleep
will pause the execution for
round (microseconds / 1e6)
seconds.
Octave includes the following functions for renaming and deleting files, creating, deleting, and reading directories, and for getting information about the status of files.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
dev
ino
modestr
nlink
uid
gid
rdev
size
atime
time
. See section Timing Utilities.
mtime
time
. See section Timing Utilities.
ctime
time
. See section Timing Utilities.
blksize
blocks
If the call is successful err is 0 and msg is an empty string. If the file does not exist, or some other error occurs, s is an empty matrix, err is -1, and msg contains the corresponding system error message.
If file is a symbolic link, stat
will return information
about the actual file the is referenced by the link. Use lstat
if you want information about the symbolic link itself.
For example,
[s, err, msg] = stat ("/vmlinuz") => s = { atime = 855399756 rdev = 0 ctime = 847219094 uid = 0 size = 389218 blksize = 4096 mtime = 847219094 gid = 6 nlink = 1 blocks = 768 modestr = -rw-r--r-- ino = 9316 dev = 2049 } => err = 0 => msg =
glob ("/vm*") => "/vmlinuz"
Note that multiple values are returned in a string matrix with the fill character set to ASCII NUL.
fnmatch ("a*b", ["ab"; "axyzb"; "xyzab"]) => [ 1; 1; 0 ]
LOADPATH
.
If the file cannot be found in the path, an empty matrix is returned. For example,
file_in_path (LOADPATH, "nargchk.m") => "/usr/local/share/octave/2.0/m/general/nargchk.m"
tilde_expand ("~joeuser/bin") => "/home/joeuser/bin" tilde_expand ("~/bin") => "/home/jwe/bin"
Octave includes some high-level commands like system
and
popen
for starting subprocesses. If you want to run another
program to perform some task and then look at its output, you will
probably want to use these functions.
Octave also provides several very low-level Unix-like functions which can also be used for starting subprocesses, but you should probably only use them if you can't find any way to do what you need with the higher-level functions.
"async"
, the process is started in the
background and the process id of the child process is returned
immediately. Otherwise, the process is started, and Octave waits until
it exits. If type argument is omitted, a value of "sync"
is assumed.
If two input arguments are given (the actual value of return_output is irrelevant) and the subprocess is started synchronously, or if system is called with one input argument and one or more output arguments, the output from the command is returned. Otherwise, if the subprocess is executed synchronously, it's output is sent to the standard output. To send the output of a command executed with system through the pager, use a command like
disp (system (cmd, 1));
or
printf ("%s\n", system (cmd, 1));
The system
function can return two values. The first is any
output from the command that was written to the standard output stream,
and the second is the output status of the command. For example,
[output, status] = system ("echo foo; exit 2");
will set the variable output
to the string `foo', and the
variable status
to the integer `2'.
"r"
"w"
For example,
fid = popen ("ls -ltr / | tail -3", "r"); while (isstr (s = fgets (fid))) fputs (stdout, s); endwhile -| drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc -| drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib -| drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp
popen
. You may also
use fclose
for the same purpose.
For example,
[in, out, pid] = popen2 ("sort", "-nr"); fputs (in, "these\nare\nsome\nstrings\n"); fclose (in); while (isstr (s = fgets (out))) fputs (stdout, s); endwhile fclose (out); -| are -| some -| strings -| these
EXEC_PATH
is a colon separated list of directories
to search when executing subprograms. Its initial value is taken from
the environment variable OCTAVE_EXEC_PATH
(if it exists) or
PATH
, but that value can be overridden by the command line
argument --exec-path PATH
, or by setting the value of
EXEC_PATH
in a startup script. If the value of EXEC_PATH
begins (ends) with a colon, the directories
octave-home/libexec/octave/site/exec/arch octave-home/libexec/octave/version/exec/arch
are prepended (appended) to EXEC_PATH
, where octave-home
is the top-level directory where all of Octave is installed
(the default value is `/usr/local'). If you don't specify
a value for EXEC_PATH
explicitly, these special directories are
prepended to your shell path.
In most cases, the following functions simply decode their arguments and
make the corresponding Unix system calls. For a complete example of how
they can be used, look at the definition of the function popen2
.
Fork can return one of the following values:
fork
is
the process id of the child process. You should probably arrange to
wait for any child processes to exit.
exec
to start another
process. If that fails, you should probably call exit
.
fork
failed for some reason. You must take evasive
action. A system dependent error message will be waiting in msg.
exec
without
first calling fork
will terminate your current Octave process and
replace it with the program named by file. For example,
exec ("ls" "-l")
will run ls
and return you to your shell prompt.
If successful, exec
does not return. If exec
does return,
err will be nonzero, and msg will contain a system-dependent
error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, fid is greater than zero and contains the new file ID. Otherwise, fid is negative and msg contains a system-dependent error message.
The options argument can be:
If the returned value of pid is greater than 0, it is the process ID of the child process that exited. If an error occurs, pid will be less than zero and msg will contain a system-dependent error message.
F_DUPFD
F_GETFD
F_SETFD
F_GETFL
O_RDONLY
O_WRONLY
O_RDWR
O_APPEND
O_NONBLOCK
O_SYNC
O_ASYNC
F_SETFL
O_APPEND
and
O_NONBLOCK
.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
getenv ("PATH")
returns a string containing the value of your path.
cd ~/octave
Changes the current working directory to `~/octave'. If the directory does not exist, an error message is printed and the working directory is not changed.
ls -l -| total 12 -| -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m -| -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m
The dir
and ls
commands are implemented by calling your
system's directory listing command, so the available options may vary
from system to system.
Octave's password database functions return information in a structure with the following fields.
name
passwd
uid
gid
gecos
dir
shell
In the descriptions of the following functions, this data structure is referred to as a pw_struct.
getpwent
returns 0.
getpwuid
returns 0.
getpwname
returns 0.
Octave's group database functions return information in a structure with the following fields.
name
passwd
gid
mem
In the descriptions of the following functions, this data structure is referred to as a grp_struct.
getgrent
returns 0.
getgrgid
returns 0.
getgrname
returns 0.
computer () -| i586-pc-linux-gnu x = computer () => x = "i586-pc-linux-gnu"
OCTAVE_VERSION
.
getrusage
:
idrss
inblock
isrss
ixrss
majflt
maxrss
minflt
msgrcv
msgsnd
nivcsw
nsignals
nswap
nvcsw
oublock
stime
sec
(seconds) usec
(microseconds).
utime
sec
(seconds) usec
(microseconds).
This chapter describes no additional features of Octave. Instead it gives advice on making effective use of the features described in the previous chapters.
Here are some tips for avoiding common errors in writing Octave code intended for widespread use:
fiddle_matrix
, don't call it by that name
in your program. Call it mylib_fiddle_matrix
in your program,
and send mail to bug-octave@bevo.che.wisc.edu suggesting that it
be added to Octave. If and when it is, the name can be changed easily
enough.
If one prefix is insufficient, your package may use two or three
alternative common prefixes, so long as they make sense.
Separate the prefix from the rest of the symbol name with an underscore
`_'. This will be consistent with Octave itself and with most
Octave programs.
error
(or usage
). The error
and usage
functions do not
return.
See section How Octave Reports Errors.
Here are some ways of improving the execution speed of Octave programs.
result = zeros (big_n, big_m) for i = over:and_over r1 = ... r2 = ... result (r1, r2) = new_value (); endforinstead of
result = []; for i = ever:and_ever result = [ result, new_value() ]; endfor
eval
or feval
whenever possible, because
they require Octave to parse input or look up the name of a function in
the symbol table.
If you are using eval
as an exception handling mechanism and not
because you need to execute some arbitrary text, use the try
statement instead. See section The try
Statement.
ignore_function_time_stamp
to "all"
so that Octave doesn't
waste a lot of time checking to see if you have updated your function
files.
Here are some tips for the writing of documentation strings.
/
refers to its second argument as `DIVISOR', because the
actual argument name is divisor
.
Also use all caps for meta-syntactic variables, such as when you show
the decomposition of a list or vector into subunits, some of which may
vary.
Here are the conventions to follow when writing comments.
indent-for-comment
)
command automatically inserts such a `#' in the right place, or
aligns such a comment if it is already present.
The indentation commands of the Octave mode in Emacs, such as M-;
(indent-for-comment
) and TAB (octave-indent-line
)
automatically indent comments according to these conventions,
depending on the number of semicolons. See section `Manipulating Comments' in The GNU Emacs Manual.
Octave has conventions for using special comments in function files to give information such as who wrote them. This section explains these conventions.
The top of the file should contain a copyright notice, followed by a block of comments that can be used as the help text for the function. Here is an example:
## Copyright (C) 1996, 1997 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 2, 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, ## write to the Free Software Foundation, 59 Temple Place - ## Suite 330, Boston, MA 02111-1307, USA. ## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) ## ## Start a subprocess with two-way communication. COMMAND ## specifies the name of the command to start. ARGS is an ## array of strings containing options for COMMAND. IN and ## OUT are the file ids of the input and streams for the ## subprocess, and PID is the process id of the subprocess, ## or -1 if COMMAND could not be executed. ## ## Example: ## ## [in, out, pid] = popen2 ("sort", "-nr"); ## fputs (in, "these\nare\nsome\nstrings\n"); ## fclose (in); ## while (isstr (s = fgets (out))) ## fputs (stdout, s); ## endwhile ## fclose (out);
Octave uses the first block of comments in a function file that do not appear to be a copyright notice as the help text for the file. For Octave to recognize the first comment block as a copyright notice, it must match the regular expression
^ Copyright (C).*\n\n This file is part of Octave.
or
^ Copyright (C).*\n\n This program is free softwar
(after stripping the leading comment characters). This is a fairly strict requirement, and may be relaxed somewhat in the future.
After the copyright notice and help text come several header comment lines, each beginning with `## header-name:'. For example,
## Author: jwe ## Keywords: subprocesses input-output ## Maintainer: jwe
Here is a table of the conventional possibilities for header-name:
## Author: John W. Eaton <jwe@bevo.che.wisc.edu>
Just about every Octave function ought to have the `Author' and `Keywords' header comment lines. Use the others if they are appropriate. You can also put in header lines with other header names--they have no standard meanings, so they can't do any harm.
This section describes known problems that affect users of Octave. Most of these are not Octave bugs per se--if they were, we would fix them. But the result for a user may be like the result of a bug.
Some of these problems are due to bugs in other software, some are missing features that are too much work to add, and some are places where people's opinions differ as to what is best.
fflush (stdout)Another possible workaround is to use the command
page_screen_output = "false"to turn the pager off.
Input line too longwhen trying to plot many lines on one graph, you have probably generated a plot command that is too larger for
gnuplot
's fixed-length
buffer for commands. Splitting up the plot command doesn't help because
replot is implemented in gnuplot by simply appending the new plotting
commands to the old command line and then evaluating it again.
You can demonstrate this `feature' by running gnuplot and doing
something like
plot sin (x), sin (x), sin (x), ... lots more ..., sin (x)and then
replot sin (x), sin (x), sin (x), ... lots more ..., sin (x)after repeating the replot command a few times, gnuplot will give you an error. Also, it doesn't help to use backslashes to enter a plot command over several lines, because the limit is on the overall command line length, once the backslashed lines are all pasted together. Because of this, Octave tries to use as little of the command-line length as possible by using the shortest possible abbreviations for all the plot commands and options. Unfortunately, the length of the temporary file names is probably what is taking up the most space on the command line. You can buy a little bit of command line space by setting the environment variable
TMPDIR
to be "." before starting Octave, or
you can increase the maximum command line length in gnuplot by changing
the following limits in the file plot.h in the gnuplot distribution and
recompiling gnuplot.
#define MAX_LINE_LEN 32768 /* originally 1024 */ #define MAX_TOKENS 8192 /* originally 400 */Of course, this doesn't really fix the problem, but it does make it much less likely that you will run into trouble unless you are putting a very large number of lines on a given plot.
A list of ideas for future enhancements is distributed with Octave. See the file `PROJECTS' in the top level directory in the source distribution.
Your bug reports play an essential role in making Octave reliable.
When you encounter a problem, the first thing to do is to see if it is already known. See section Known Causes of Trouble. If it isn't known, then you should report the problem.
Reporting a bug may help you by bringing a solution to your problem, or it may not. In any case, the principal function of a bug report is to help the entire community by making the next version of Octave work better. Bug reports are your contribution to the maintenance of Octave.
In order for a bug report to serve its purpose, you must include the information that makes it possible to fix the bug.
If you have Octave working at all, the easiest way to prepare a complete
bug report 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 you are not sure whether you have found a bug, here are some guidelines:
If you have Octave working at all, the easiest way to prepare a complete
bug report 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,
send bug reports for Octave to bug-octave@bevo.che.wisc.edu.
Do not send bug reports to `help-octave'. Most users of Octave do not want to receive bug reports. Those that do have asked to be on the mailing list.
As a last resort, send bug reports on paper to:
Octave Bugs c/o John W. Eaton University of Wisconsin-Madison Department of Chemical Engineering 1415 Engineering Drive Madison, Wisconsin 53706 USA
Send bug reports for Octave to one of the addresses listed in section Where to Report Bugs.
The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!
Often people omit facts because they think they know what causes the problem and they conclude that some details don't matter. Thus, you might assume that the name of the variable you use in an example does not matter. Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the interpreter into doing the right thing despite the bug. Play it safe and give a specific, complete example.
Keep in mind that the purpose of a bug report is to enable someone to fix the bug if it is not known. Always write your bug reports on the assumption that the bug is not known.
Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" This cannot help us fix a bug. It is better to send a complete bug report to begin with.
Try to make your bug report self-contained. If we have to ask you for more information, it is best if you include all the previous information in your response, as well as the information that was missing.
To enable someone to investigate the bug, you should include all these things:
configure
command when
you installed the interpreter.
Here are some things that are not necessary:
If you would like to write bug fixes or improvements for Octave, that is very helpful. When you send your changes, please follow these guidelines to avoid causing extra work for us in studying the patches.
If you don't follow these guidelines, your information might still be useful, but using it will take extra work. Maintaining Octave is a lot of work in the best of circumstances, and we can't keep up unless you do your best to help.
The mailing list help-octave@bevo.che.wisc.edu exists for the discussion of matters related to using and installing Octave. If would like to join the discussion, 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 mailing list, or other administrative trivia to the list itself.
If you think you have found a bug in the installation procedure, however, you should send a complete bug report for the problem to bug-octave@bevo.che.wisc.edu. See section How to Report Bugs for information that will help you to submit a useful report.
Here is the procedure for installing Octave from scratch on a Unix system. For instructions on how to install the binary distributions of Octave, see section Binary Distributions.
--prefix=prefix
--srcdir=dir
--with-f2c
f2c
even if a Fortran compiler is available.
--with-g77
g77
to compile Fortran code.
--enable-shared
--enable-lite-kernelel
or the dynamic loading features, you will
probably want to use this option. It will make your `.oct' files
much smaller and on some systems it may be necessary to build shared
libraries in order to use dynamically linked functions.
You may also want to build a shared version of libstdc++
, if your
system doesn't already have one. Note that a patch is needed to build
shared versions of version 2.7.2 of libstdc++
on the HP-PA
architecture. You can find the patch at
ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix
.
--enable-dl
dlopen
and friends to make Octave capable of dynamically
linking externally compiled functions. This only works on systems that
actually have these functions. If you plan on using this feature, you
should probably also use --enable-shared
to reduce the size of
your `.oct' files.
--enable-shl
shl_load
and friends to make Octave capable of dynamically
linking externally compiled functions. This only works on systems that
actually have these functions (only HP-UX systems). If you plan on
using this feature, you should probably also use --enable-shared
to reduce the size of your `.oct' files.
--enable-lite-kernel
dlopen
or shl_load
and friends so that Octave
can load functions at run time that are not loaded at compile time.
--help
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.
If you plan to modify the parser you will also need GNU bison
and
flex
. If you modify the documentation, you will need GNU
Texinfo, along with the patch for the makeinfo
program that is
distributed with Octave.
GNU Make, gcc
, and libstdc++
, gnuplot
,
bison
, flex
, and Texinfo are all available from many
anonymous ftp archives. The primary site is ftp.gnu.org
, but it
is often very busy. A list of sites that mirror the software on
ftp.gnu.org
is available by anonymous ftp from
ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP
.
If you don't have a Fortran compiler, or if your Fortran compiler
doesn't work like the traditional Unix f77, you will need to have the
Fortran to C translator f2c
. You can get f2c
from any
number of anonymous ftp archives. The most recent version of f2c
is always available from netlib.att.com
.
On an otherwise idle Pentium 133 running Linux, it will take somewhere
between 1-1/2 to 3 hours to compile everything, depending on whether you
are building shared libraries. You will need about 100 megabytes of disk
storage to work with (considerably less if you don't compile with debugging
symbols). To do that, use the command
make CFLAGS=-O CXXFLAGS=-O LDFLAGS=instead of just `make'.
This section contains a list of problems (and some apparent problems that don't really mean anything is wrong) that may show up during installation of Octave.
info
fails to compile if
HAVE_TERMIOS_H
is defined int `config.h'. Simply removing
the definition from `info/config.h' should allow it to compile.
configure
finds dlopen
, dlsym
, dlclose
,
and dlerror
, but not the header file `dlfcn.h', you need to
find the source for the header file and install it in the directory
`usr/include'. This is reportedly a problem with Slackware 3.1.
For Linux/GNU systems, the source for `dlfcn.h' is in the
ldso
package.
libstdc++
. A patch
is needed to build shared versions of version 2.7.2 of libstdc++
on the HP-PA architecture. You can find the patch at
ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix
.
options GPL_MATH_EMULATErather than
options MATH_EMULATEin the kernel configuration files (typically found in the directory `/sys/i386/conf'. After making this change, you'll need to rebuild the kernel, install it, and reboot.
passing `void (*)()' as argument 2 of `octave_set_signal_handler(int, void (*)(int))'or
warning: ANSI C++ prohibits conversion from `(int)' to `(...)'while compiling `sighandlers.cc', you may need to edit some files in the
gcc
include subdirectory to add proper prototypes for functions
there. For example, Ultrix 4.2 needs proper declarations for the
signal
function and the SIG_IGN
macro in the file
`signal.h'.
On some systems the SIG_IGN
macro is defined to be something like
this:
#define SIG_IGN (void (*)())1when it should really be something like:
#define SIG_IGN (void (*)(int))1to match the prototype declaration for the
signal
function. This
change should also be made for the SIG_DFL
and SIG_ERR
symbols. It may be necessary to change the definitions in
`sys/signal.h' as well.
The gcc
fixincludes
and fixproto
scripts should
probably fix these problems when gcc
installs its modified set of
header files, but I don't think that's been done yet.
You should not change the files in `/usr/include'. You
can find the gcc
include directory tree by running the command
gcc -print-libgcc-file-nameThe directory of
gcc
include files normally begins in the same directory
that contains the file `libgcc.a'.
zgemm.f: zgemm: warning: unexpected parent of complex expression subtree zgemm.f, line 245: warning: unexpected parent of complex expression subtree warning: unexpected parent of complex expression subtree zgemm.f, line 304: warning: unexpected parent of complex expression subtree warning: unexpected parent of complex expression subtree zgemm.f, line 327: warning: unexpected parent of complex expression subtree pcc_binval: missing IR_CONV in complex op make[2]: *** [zgemm.o] Error 1when compiling the Fortran subroutines in the `libcruft' subdirectory, you should either upgrade your compiler or try compiling with optimization turned off.
/usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656 /usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656when compiling `Array.cc' and `Matrix.cc', try recompiling these files without
-g
.
G_HAVE_SYS_WAIT
defined to be 0 instead of 1 when compiling
libg++
.
_tcgetattr _tcsetattr _tcflowwhich are part of `libposix.a'. Unfortunately, linking Octave with
-posix
results in the following undefined symbols.
.destructors_used .constructors_used _objc_msgSend _NXGetDefaultValue _NXRegisterDefaults .objc_class_name_NXStringTable .objc_class_name_NXBundleOne kluge around this problem is to extract `termios.o' from `libposix.a', put it in Octave's `src' directory, and add it to the list of files to link together in the makefile. Suggestions for better ways to solve this problem are welcome!
octave_ieee_init
in
the file `lo-ieee.cc' to correctly initialize Octave's internal
infinity and NaN variables.
If your system does not support IEEE arithmetic but Octave's configure
script incorrectly determined that it does, you can work around the
problem by editing the file `config.h' to not define
HAVE_ISINF
, HAVE_FINITE
, and HAVE_ISNAN
.
In any case, please report this as a bug since it might be possible to
modify Octave's configuration script to automatically determine the
proper thing to do.
run-octave
doesn't work. Emacs
hangs in accept-process-output
in inferior-octave-startup
.
This seems to be a problem with executing a shell script using the
comint package. You can avoid the problem by changing the way Octave is
installed to eliminate the need for the shell script. You can either
compile and install Octave using the source distribution, reinstall the
binary distribution in the default directory, or copy the commands in
the octave shell script wrapper to your shell startup files (and the
shell startup files for anyone else who is using Octave) and then
rename the file `octave.bin' to be `octave'.
Although Octave is not very difficult to build from its sources, it is a
relatively large program that does require a significant amount of time
and disk space to compile and install. Because of this, many people
want to be able to obtain binary distributions so they can start using
Octave immediately, without having to bother with the details of
compiling it first. This is understandable, so I try to maintain a
current collection of binary distributions at
ftp://ftp.che.wisc.edu/pub/octave/BINARIES
.
Please understand, however, that there is only a limited amount of time available to devote to making binaries, so binaries may not be immediately available for some platforms. (Please contact bug-octave@bevo.che.wisc.edu if you are interested in helping make a binary distribution available for your system.)
To install Octave from a binary distribution, execute the command
sh ./install-octave
in the top level directory of the distribution.
Binary distributions are normally compiled assuming that Octave will be installed in the following subdirectories of `/usr/local'.
where version stands for the current version number of the interpreter, and arch is the type of computer on which Octave is installed (for example, `i586-pc-linux-gnu').
If these directories don't exist, the script install-octave
will
create them for you. The installation script also creates the following
subdirectories of `/usr/local' that are intended for locally
installed functions:
If it is not possible for you to install Octave in `/usr/local', or if you would prefer to install it in a different directory, you can specify the name of the top level directory as an argument to the `install-octave' script. For example:
sh ./install-octave /some/other/directory
will install Octave in subdirectories of the directory `/some/other/directory'.
Here is how to build a binary distribution for others to use. If you
want to make a binary distribution for your system available along with
the Octave sources and binaries on ftp.che.wisc.edu
, please follow
this procedure. For directions explaining how to make the binary
available on the ftp site, please contact
bug-octave@bevo.che.wisc.edu.
gunzip -c octave-2.0.5.tar.gz | tar xf -
cd octave-2.0.5
make binary-distThis will create a compressed tar file ready for distribution. It will have a name like `octave-2.0.5-i586-pc-linux-gnu.tar.gz'
The development of Octave code can greatly be facilitated using Emacs with Octave mode, a major mode for editing Octave files which can e.g. automatically indent the code, do some of the typing (with Abbrev mode) and show keywords, comments, strings, etc. in different faces (with Font-lock mode on devices that support it).
It is also possible to run Octave from within Emacs, either by directly entering commands at the prompt in a buffer in Inferior Octave mode, or by interacting with Octave from within a file with Octave code. This is useful in particular for debugging Octave code.
Finally, you can convince Octave to use the Emacs info reader for help -i.
All functionality is provided by the Emacs Lisp package EOS (for "Emacs Octave Support"). This chapter describes how to set up and use this package.
Please contact <Kurt.Hornik@ci.tuwien.ac.at> if you have any questions or suggestions on using EOS.
The Emacs package EOS consists of the three files `octave-mod.el', `octave-inf.el', and `octave-hlp.el'. These files, or better yet their byte-compiled versions, should be somewhere in your Emacs load-path.
If you have GNU Emacs with a version number at least as high as 19.35, you are all set up, because EOS is respectively will be part of GNU Emacs as of version 19.35.
Otherwise, copy the three files from the `emacs' subdirectory of the Octave distribution to a place where Emacs can find them (this depends on how your Emacs was installed). Byte-compile them for speed if you want.
If you are lucky, your sysadmins have already arranged everything so that Emacs automatically goes into Octave mode whenever you visit an Octave code file as characterized by its extension `.m'. If not, proceed as follows.
(autoload 'octave-mode "octave-mod" nil t) (setq auto-mode-alist (cons '("\\.m$" . octave-mode) auto-mode-alist))
(add-hook 'octave-mode-hook (lambda () (abbrev-mode 1) (auto-fill-mode 1) (if (eq window-system 'x) (font-lock-mode 1))))See the Emacs manual for more information about how to customize Font-lock mode.
In Octave mode, the following special Emacs commands can be used in addition to the standard Emacs commands.
octave-reindent-then-newline-and-indent
). An abbrev before
point is expanded if abbrev-mode
is non-nil
.
indent-according-to-mode
).
octave-electric-semi
). If
octave-auto-indent
is non-nil
, reindent the current line.
If octave-auto-newline
is non-nil
, automagically insert a
newline and indent the new line.
octave-abbrev-start
). If Abbrev
mode is turned on, typing `C-h or `? lists all abbrevs.
Any other key combination is executed normally. Note that all Octave
abbrevs start with a grave accent.
octave-split-line
).
octave-complete-symbol
).
octave-beginning-of-defun
).
With prefix argument N, do it that many times if N is
positive; otherwise, move forward to the N-th following beginning
of a function.
octave-end-of-defun
).
With prefix argument N, do it that many times if N is
positive; otherwise, move back to the N-th preceding end of a
function.
octave-mark-defun
).
octave-indent-defun
).
octave-indent-for-comment
).
Point is left after the start of the comment which is properly aligned.
octave-comment-start
) at the beginning of every line in the
region (octave-comment-region
). With just C-u prefix
argument, uncomment each line in the region. A numeric prefix argument
N means use N comment characters.
octave-uncomment-region
).
octave-previous-code-line
). With numeric prefix argument
N, move that many code lines backward (forward if N is
negative).
octave-next-code-line
). With numeric prefix argument N,
move that many code lines forward (backward if N is negative).
octave-beginning-of-line
). If point is in an empty or comment
line, simply go to its beginning; otherwise, move backwards to the
beginning of the first code line which is not inside a continuation
statement, i.e., which does not follow a code line ending in `...'
or `\', or is inside an open parenthesis list.
octave-end-of-line
).
If point is in a code line, move forward to the end of the first Octave
code line which does not end in `...' or `\' or is inside an
open parenthesis list. Otherwise, simply go to the end of the current
line.
octave-forward-block
). With numeric prefix argument N,
move forward across n such blocks (backward if N is
negative).
octave-backward-block
). With numeric prefix argument N,
move backward across N such blocks (forward if N is
negative).
octave-down-block
). With numeric prefix argument, do it that
many times; a negative argument means move backward, but still go down
one level.
octave-backward-up-block
). With numeric prefix argument, do it
that many times; a negative argument means move forward, but still to a
less deep spot.
octave-mark-block
).
The block marked is the one that contains point or follows point.
octave-close-block
).
An error is signaled if no block to close is found.
octave-insert-defun
).
octave-help
). If used
interactively, the entry is prompted for with completion. If multiple
matches are found, one can cycle through them using the standard
`,' (Info-index-next
) command of the Info reader.
The variable octave-help-files
is a list of files to search
through and defaults to '("octave")
. If there is also an Octave
Local Guide with corresponding info file, say, `octave-LG', you can
have octave-help
search both files by
(setq octave-help-files '("octave" "octave-LG"))in one of your Emacs startup files.
A common problem is that the RET key does not indent the line to where the new text should go after inserting the newline. This is because the standard Emacs convention is that RET (aka C-m) just adds a newline, whereas LFD (aka C-j) adds a newline and indents it. This is particularly inconvenient for users with keyboards which do not have a special LFD key at all; in such cases, it is typically more convenient to use RET as the LFD key (rather than typing C-j).
You can make RET do this by adding
(define-key octave-mode-map "\C-m" 'octave-reindent-then-newline-and-indent)
to one of your Emacs startup files. Another, more generally applicable solution is
(defun RET-behaves-as-LFD () (let ((x (key-binding "\C-j"))) (local-set-key "\C-m" x))) (add-hook 'octave-mode-hook 'RET-behaves-as-LFD)
(this works for all modes by adding to the startup hooks, without having
to know the particular binding of RET in that mode!). Similar
considerations apply for using M-RET as M-LFD. As Barry
A. Warsaw <bwarsaw@cnri.reston.va.us> says in the documentation for his
cc-mode
, "This is a very common question. :-)
If you want
this to be the default behavior, don't lobby me, lobby RMS!"
The following variables can be used to customize Octave mode.
octave-auto-indent
nil
means auto-indent the current line after a semicolon or
space. Default is nil
.
octave-auto-newline
nil
means auto-insert a newline and indent after semicolons
are typed. The default value is nil
.
octave-blink-matching-block
nil
means show matching begin of block when inserting a space,
newline or `;' after an else or end keyword. Default is t
.
This is an extremely useful feature for automatically verifying that the
keywords match--if they don't, an error message is displayed.
octave-block-offset
octave-continuation-offset
octave-continuation-string
octave-mode-startup-message
t
(default), a startup message is displayed when Octave mode
is called.
If Font Lock mode is enabled, Octave mode will display
font-lock-string-face
font-lock-comment-face
font-lock-keyword-face
font-lock-reference-face
font-lock-variable-name-face
font-lock-function-name-face
.
There is also rudimentary support for Imenu (currently, function names can be indexed).
You can generate TAGS files for Emacs from Octave `.m' files using
the shell script otags
that is installed alongside your copy of
Octave.
Customization of Octave mode can be performed by modification of the
variable octave-mode-hook
. It the value of this variable is
non-nil
, turning on Octave mode calls its value.
If you discover a problem with Octave mode, you can conveniently send a
bug report using C-c C-b (octave-submit-bug-report
). This
automatically sets up a mail buffer with version information already
added. You just need to add a description of the problem, including a
reproducible test case and send the message.
The package `octave' provides commands for running an inferior Octave process in a special Emacs buffer. Use
M-x run-octave
to directly start an inferior Octave process. If Emacs does not know about this command, add the line
(autoload 'run-octave "octave-inf" nil t)
to your `.emacs' file.
This will start Octave in a special buffer the name of which is
specified by the variable inferior-octave-buffer
and defaults to
"*Inferior Octave*"
. From within this buffer, you can
interact with the inferior Octave process `as usual', i.e., by entering
Octave commands at the prompt. The buffer is in Inferior Octave mode,
which is derived from the standard Comint mode, a major mode for
interacting with an inferior interpreter. See the documentation for
comint-mode
for more details, and use C-h b to find out
about available special keybindings.
You can also communicate with an inferior Octave process from within files with Octave code (i.e., buffers in Octave mode), using the following commands.
octave-send-line
).
With positive prefix argument N, send that many lines.
If octave-send-line-auto-forward
is non-nil
, go to the
next unsent code line.
octave-send-block
).
octave-send-defun
).
octave-send-region
).
octave-show-process-buffer
).
octave-hide-process-buffer
).
octave-kill-process
).
The effect of the commands which send code to the Octave process can be customized by the following variables.
octave-send-echo-input
nil
means echo input sent to the inferior Octave process.
Default is t
.
octave-send-show-buffer
nil
means display the buffer running the Octave process after
sending a command (but without selecting it).
Default is t
.
If you send code and there is no inferior Octave process yet, it will be started automatically.
The startup of the inferior Octave process is highly customizable.
The variable inferior-octave-startup-args
can be used for
specifying command lines arguments to be passed to Octave on startup
as a list of strings. For example, to suppress the startup message and
use `traditional' mode, set this to '("-q" "--traditional")
.
You can also specify a startup file of Octave commands to be loaded on
startup; note that these commands will not produce any visible output
in the process buffer. Which file to use is controlled by the variable
inferior-octave-startup-file
. If this is nil
, the file
`~/.emacs-octave' is used if it exists.
And finally, inferior-octave-mode-hook
is run after starting the
process and putting its buffer into Inferior Octave mode. Hence, if you
like the up and down arrow keys to behave in the interaction buffer as
in the shell, and you want this buffer to use nice colors, add
(add-hook 'inferior-octave-mode-hook (lambda () (turn-on-font-lock) (define-key inferior-octave-mode-map [up] 'comint-previous-input) (define-key inferior-octave-mode-map [down] 'comint-next-input)))
to your `.emacs' file. You could also swap the roles of C-a
(beginning-of-line
) and C-c C-a
(comint-bol
) using
this hook.
Note: If you set your Octave prompts to something different from the defaults, make sure that
inferior-octave-prompt
matches them. Otherwise, nothing will work, because Emacs will have no idea when Octave is waiting for input, or done sending output.
You can also set up the Emacs Info reader for dealing with the results
of Octave's `help -i'. For this, the package `gnuserv' needs
to be installed, which unfortunately still does not come with GNU Emacs
(it does with XEmacs). It can be retrieved from any GNU Emacs Lisp Code
Directory archive, e.g.
ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive
,
in the `packages' subdirectory. The alpha version of an enhanced
version of gnuserv is available at
ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz
.
If `gnuserv' is installed, add the lines
(autoload 'octave-help "octave-hlp" nil t) (require 'gnuserv) (gnuserv-start)
to your `.emacs' file.
You can use either `plain' Emacs Info or the function octave-help
as your Octave info reader (for `help -i'). In the former case,
set the Octave variable INFO_PROGRAM
to "info-emacs-info"
.
The latter is perhaps more attractive because it allows to look up keys
in the indices of several info files related to Octave (provided
that the Emacs variable octave-help-files
is set correctly). In
this case, set INFO_PROGRAM
to "info-emacs-octave-help"
.
If you use Octave from within Emacs, these settings are best done in the
`~/.emacs-octave' startup file (or the file pointed to by the Emacs
variable inferior-octave-startup-file
).
Someday I hope to expand this to include a semi-formal description of Octave's language.
The following identifiers are keywords, and may not be used as variable or function names:
all_va_args endwhile break for case function catch global continue gplot else gsplot elseif if end otherwise end_try_catch return end_unwind_protect switch endfor try endfunction unwind_protect endif unwind_protect_cleanup endswitch while
The following command-like functions are also speical. They may be used as simple variable names, but not as formal parameters for functions, or as the names of structure variables. Failed assignments leave them undefined (you can recover the orginal definition as a function using clear).
casesen echo load show cd edit_history ls type chdir format more which clear help run_history who diary history save whos dir hold set
Version 2, June 1991
Copyright © 1989, 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
NO WARRANTY
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and a brief idea of what it does. Copyright (C) 19yy name of author This program 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 2 of the License, or (at your option) any later version. This program 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 this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
--braindead
--debug
--echo-commands
--exec-path path
--help
--info-file filename
--info-program program
--interactive
--no-init-file
--no-line-editing
--no-site-file
--norc
--path path
--quiet
--silent
--traditional
--verbose
--version
-?
-d
-f
-h
-i
-p path
-q
-V
-v
-x
...
, ...
...
continuation marker
.octaverc
\
continuation marker
break
statement
case
statement
catch
continue
statement
printf
)
scanf
)
else
statement
elseif
statement
end
statement
end_try_catch
end_unwind_protect
endfor
statement
endfunction
statement
endif
statement
endswitch
statement
endwhile
statement
printf
)
scanf
)
for
statement
function
statement
global
statement
if
statement
scanf
scanf
scanf
)
printf
)
otags
otherwise
statement
printf
printf
)
switch
statement
try
statement
unwind_protect
statement
unwind_protect_cleanup
while
statement
~/.octaverc
--
, --
This document was generated on 18 Febuary 1999 using the texi2html translator version 1.51a.