This is octave.info, produced by makeinfo version 4.8 from octave.texi.

START-INFO-DIR-ENTRY
* Octave: (octave).	Interactive language for numerical computations.
END-INFO-DIR-ENTRY

   Copyright (C) 1996, 1997 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Top,  Next: Preface,  Up: (dir)

GNU Octave
**********

This manual documents how to run, install and port GNU Octave, as well
as its new features and incompatibilities, and how to report bugs.  It
corresponds to GNU Octave version 2.1.x.

* Menu:

* Preface::
* Introduction::                A brief introduction to Octave.
* Getting Started::
* Data Types::
* Numeric Data Types::
* Strings::
* Data Structures::
* Containers::
* I/O Streams::
* Variables::
* Expressions::                 Expressions.
* Evaluation::
* Statements::                  Looping and program flow control.
* Functions and Scripts::
* Error Handling::
* Debugging::
* Input and Output::
* Plotting::
* Matrix Manipulation::
* Arithmetic::
* Linear Algebra::
* Nonlinear Equations::
* Quadrature::
* Differential Equations::
* Optimization::
* Statistics::
* Financial Functions::
* Sets::
* Polynomial Manipulations::
* Control Theory::
* Signal Processing::
* Image Processing::
* Audio Processing::
* Quaternions::
* System Utilities::
* Tips::
* Trouble::                     If you have trouble installing Octave.
* Installation::                How to configure, compile and install Octave.
* Emacs::
* Grammar::
* Copying::                     The GNU General Public License.
* Concept Index::               An item for each concept.
* Variable Index::              An item for each documented variable.
* Function Index::              An item for each documented function.
* Operator Index::              An item for each documented operator.

 --- The Detailed Node Listing ---

Preface

* Acknowledgements::
* How You Can Contribute to Octave::
* Distribution::

A Brief Introduction to Octave

* Running Octave::
* Simple Examples::
* Conventions::

Conventions

* Fonts::
* Evaluation Notation::
* Printing Notation::
* Error Messages::
* Format of Descriptions::

Format of Descriptions

* A Sample Function Description::
* A Sample Command Description::
* A Sample Variable Description::

Getting Started

* Invoking Octave::
* Quitting Octave::
* Getting Help::
* Command Line Editing::
* Errors::
* Executable Octave Programs::
* Comments::

Invoking Octave

* Command Line Options::
* Startup Files::

Command Line Editing

* Cursor Motion::
* Killing and Yanking::
* Commands For Text::
* Commands For Completion::
* Commands For History::
* Customizing readline::
* Customizing the Prompt::
* Diary and Echo Commands::

Data Types

* Built-in Data Types::
* User-defined Data Types::
* Object Sizes::

Built-in Data Types

* Numeric Objects::
* String Objects::
* Data Structure Objects::

Numeric Data Types

* Matrices::
* Ranges::
* Logical Values::
* Predicates for Numeric Objects::

Matrices

* Empty Matrices::

Strings

* Creating Strings::
* Searching and Replacing::
* String Conversions::
* Character Class Functions::

Containers

* Lists::
* Cell Arrays::

Variables

* Global Variables::
* Status of Variables::
* Summary of Built-in Variables::
* Defaults from the Environment::

Expressions

* Index Expressions::
* Calling Functions::
* Arithmetic Ops::
* Comparison Ops::
* Boolean Expressions::
* Assignment Ops::
* Increment Ops::
* Operator Precedence::

Calling Functions

* Call by Value::
* Recursion::

Boolean Expressions

* Element-by-element Boolean Operators::
* Short-circuit Boolean Operators::

Statements

* The if Statement::
* The switch Statement::
* The while Statement::
* The do-until Statement::
* The for Statement::
* The break Statement::
* The continue Statement::
* The unwind_protect Statement::
* The try Statement::
* Continuation Lines::

The `for' Statement

* Looping Over Structure Elements::

Functions and Script Files

* Defining Functions::
* Multiple Return Values::
* Variable-length Argument Lists::
* Variable-length Return Lists::
* Returning From a Function::
* Function Files::
* Script Files::
* Dynamically Linked Functions::
* Organization of Functions::

Error Handling

Debugging

Input and Output

* Basic Input and Output::
* C-Style I/O Functions::

Basic Input and Output

* Terminal Output::
* Terminal Input::
* Simple File I/O::

C-Style I/O Functions

* Opening and Closing Files::
* Simple Output::
* Line-Oriented Input::
* Formatted Output::
* Output Conversion for Matrices::
* Output Conversion Syntax::
* Table of Output Conversions::
* Integer Conversions::
* Floating-Point Conversions::  Other Output Conversions::
* Other Output Conversions::
* Formatted Input::
* Input Conversion Syntax::
* Table of Input Conversions::
* Numeric Input Conversions::
* String Input Conversions::
* Binary I/O::
* Temporary Files::
* EOF and Errors::
* File Positioning::

Plotting

* Two-Dimensional Plotting::
* Specialized Two-Dimensional Plots::
* Three-Dimensional Plotting::
* Plot Annotations::
* Multiple Plots on One Page::
* Multiple Plot Windows::
* Interaction with gnuplot::

Matrix Manipulation

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::

Arithmetic

* Utility Functions::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Special Functions::
* Mathematical Constants::

Linear Algebra

* Basic Matrix Functions::
* Matrix Factorizations::
* Functions of a Matrix::

Quadrature

* Functions of One Variable::
* Orthogonal Collocation::

Differential Equations

* Ordinary Differential Equations::
* Differential-Algebraic Equations::

Optimization

* Quadratic Programming::
* Nonlinear Programming::
* Linear Least Squares::

Statistics

* Basic Statistical Functions::
* Tests::
* Models::
* Distributions::

Control Theory

* sysstruct::
* sysinterface::
* sysdisp::
* blockdiag::
* numerical::
* sysprop::
* systime::
* sysfreq::
* cacsd::
* misc::

System Data Structure

* sysstructvars::
* sysstructtf::
* sysstructzp::
* sysstructss::

System Construction and Interface Functions

* fir2sys::
* ss2sys::
* tf2sys::
* zp2sys::
* structaccess::
* structintern::

System Utilities

* Timing Utilities::
* Filesystem Utilities::
* Controlling Subprocesses::
* Process ID Information::
* Environment Variables::
* Current Working Directory::
* Password Database Functions::
* Group Database Functions::
* System Information::

Tips and Standards

* Style Tips::                  Writing clean and robust programs.
* Coding Tips::                 Making code run faster.
* Documentation Tips::          Writing readable documentation strings.
* Comment Tips::                Conventions for writing comments.
* Function Headers::            Standard headers for functions.

Known Causes of Trouble with Octave

* Actual Bugs::                 Bugs we will fix later.
* Reporting Bugs::
* Bug Criteria::
* Bug Lists::
* Bug Reporting::
* Sending Patches::
* Service::

Reporting Bugs

* Bug Criteria::
* Where: Bug Lists.             Where to send your bug report.
* Reporting: Bug Reporting.     How to report a bug effectively.
* Patches: Sending Patches.     How to send a patch for Octave.

Installing Octave

* Installation Problems::

Emacs Octave Support

* Installing EOS::
* Using Octave Mode::
* Running Octave From Within Emacs::
* Using the Emacs Info Reader for Octave::

Grammar

* Keywords::


File: octave.info,  Node: Preface,  Next: Introduction,  Prev: Top,  Up: Top

Preface
*******

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 (*note Copying::) 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.

* Menu:

* Acknowledgements::
* How You Can Contribute to Octave::
* Distribution::


File: octave.info,  Node: Acknowledgements,  Next: How You Can Contribute to Octave,  Up: Preface

Acknowledgements
================

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.

   * Thomas Baier <baier@ci.tuwien.ac.at> wrote the original versions
     of `popen', `pclose', `execute', `sync_system', and `async_system'.

   * David Bateman <dbateman@free.fr> improved the sort and min/max
     functions, made many functions N-d aware, converted several
     built-in functions to use Lapack instead of Linpack, split the
     functionality of `load-save.cc' out into the `octave_value'
     classes, and has contributed in many other ways.

   * Karl Berry <karl@cs.umb.edu> wrote the `kpathsea' library that
     allows Octave to recursively search directory paths for function
     and script files.

   * Georg Beyerle <gbeyerle@awi-potsdam.de> contributed code to save
     values in MATLAB's `.mat'-file format, and has provided many
     useful bug reports and suggestions.

   * John Campbell <jcc@bevo.che.wisc.edu> wrote most of the file and
     C-style input and output functions.

   * Dirk Eddelbuettel <edd@debian.org> made Octave easy to install for
     users of Debian GNU/Linux.

   * Brian Fox <bfox@gnu.org> wrote the `readline' library used for
     command history editing, and the portion of this manual that
     documents it.

   * Klaus Gebhardt <gebhardt@crunch.ikp.physik.th-darmstadt.de> ported
     Octave to OS/2.

   * Kai Habel <kai.habel@gmx.de> implemted functions for performing
     coordinate transformations.

   * A. Scottedward Hodel <A.S.Hodel@eng.auburn.edu> contributed a
     number of functions including `expm', `qzval', `qzhess', `syl',
     `lyap', and `balance'.

   * Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at> provided the `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.

   * Cai Jianming <caijianming@yahoo.co.uk> contributed the inital cell
     array implementation.

   * Phil Johnson <johnsonp@nicco.sscnet.ucla.edu> has helped to make
     Linux releases available.

   * Steven G. Johnson <stevenj@alum.mit.edu> added support for ATLAS,
     saving data in HDF5 files, and ported Octave's configure script to
     Autoconf 2.50.

   * Mumit Khan <khan@nanotech.wisc.edu> helped make it possible for
     Octave to be compiled by ISO standard C++ compilers other than GCC.

   * Paul Kienzle <pkienzle@users.sf.net> has provided many
     enhancements to improve Octave's compatibility with MATLAB, and
     also maintains the collection of conributed code at
     `http://octave.sf.net'.

   * Bill Lash <lash@tellabs.com> provided the `unwrap' function.

   * Dirk Laurie <dlaurie@na-net.ornl.gov> rewrote `invhilb' to be
     faster and more accurate.

   * Friedrich Leisch <leisch@ci.tuwien.ac.at> provided the
     `mahalanobis' function.

   * Ken Neighbors <wkn@leland.stanford.edu> has provided many useful
     bug reports and comments on MATLAB compatibility.

   * Rick Niles <niles@axp745.gsfc.nasa.gov> rewrote Octave's plotting
     functions to add line styles and the ability to specify an
     unlimited number of lines in a single call.  He also continues to
     track down odd incompatibilities and bugs.

   * Mark Odegard <meo@getech.com> provided the initial implementation
     of `fread', `fwrite', `feof', and `ferror'.

   * Gabriele Pannocchia  <pannocchia@ing.unipi.it> provided the
     `dkalman.m' function, added support for singular system matrices
     to `dlqe' and `dlqr', and has made various other improvements to
     the control system functions.

   * Tony Richardson <richardson@evansville.edu> wrote Octave's image
     processing functions as well as most of the original polynomial
     functions.

   * Petter Risholm <Petter.Risholm@idi.ntnu.no> helped to implement
     much of Octave's N-d array functionality.

   * Ben Sapp <bsapp@lanl.gov> implemented the debugger functions and
     added Texinfo markup commands to the internal doc strings.

   * R. Bruce Tenison <btenison@rstc.cc.al.us> wrote the `hess' and
     `schur' functions.

   * Teresa Twaroch <twaroch@ci.tuwien.ac.at> provided the functions
     `gls' and `ols'.

   * James R. Van Zandt <jrv@vanzandt.mv.com> added support for reading
     and writing MATLAB version 5 binary data files.

   * Andreas Weingessel <Andreas.Weingessel@ci.tuwien.ac.at> wrote the
     audio functions `lin2mu', `loadaudio', `mu2lin', `playaudio',
     `record', `saveaudio', and `setaudio'.

   * Fook Fah Yap <ffy@eng.cam.ac.uk> provided the `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:

   * The National Science Foundation, through grant numbers CTS-0105360,
     CTS-9708497, CTS-9311420, and CTS-8957123.

   * The industrial members of the Texas-Wisconsin Modeling and Control
     Consortium (TWMCC (http://www.che.utexas.edu/twmcc)).

   * The Paul A. Elfers Endowed Chair in Chemical Engineering at the
     University of Wisconsin-Madison.

   * Digital Equipment Corporation, for an equipment grant as part of
     their External Research Program.

   * Sun Microsystems, Inc., for an Academic Equipment grant.

   * International Business Machines, Inc., for providing equipment as
     part of a grant to the University of Texas College of Engineering.

   * Texaco Chemical Company, for providing funding to continue the
     development of this software.

   * The University of Texas College of Engineering, for providing a
     Challenge for Excellence Research Supplement, and for providing an
     Academic Development Funds grant.

   * The State of Texas, for providing funding through the Texas
     Advanced Technology Program under Grant No. 003658-078.

   * Noel Bell, Senior Engineer, Texaco Chemical Company, Austin Texas.

   * James B. Rawlings, Professor, University of Wisconsin-Madison,
     Department of Chemical Engineering.

   * Richard Stallman, for writing GNU.

   This project would not have been possible without the GNU software
used in and used to produce Octave.


File: octave.info,  Node: How You Can Contribute to Octave,  Next: Distribution,  Prev: Acknowledgements,  Up: Preface

How You Can Contribute to 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.  *Note Trouble::,
for tips on how to write useful bug reports.


File: octave.info,  Node: Distribution,  Prev: How You Can Contribute to Octave,  Up: Preface

Distribution
============

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 *Note Copying::.

   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
     51 Franklin Street, Fifth Floor
     Boston, MA 02110-1301-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'.


File: octave.info,  Node: Introduction,  Next: Getting Started,  Prev: Preface,  Up: Top

1 A Brief Introduction to 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 *Note Copying::.

   This document corresponds to Octave version 2.1.x.

* Menu:

* Running Octave::
* Simple Examples::
* Conventions::


File: octave.info,  Node: Running Octave,  Next: Simple Examples,  Up: Introduction

1.1 Running Octave
==================

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


File: octave.info,  Node: Simple Examples,  Next: Conventions,  Prev: Running Octave,  Up: Introduction

1.2 Simple Examples
===================

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.

Creating a Matrix
-----------------

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

Matrix Arithmetic
-----------------

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 `transpose (a) * a', type the command

     octave:6> a' * a

Solving Linear Equations
------------------------

To solve the set of linear equations `aX = b', use the left division
operator, `\':

     octave:7> a \ b

This is conceptually equivalent to `inv (a) * b', 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.

Integrating Differential Equations
----------------------------------

Octave has built-in functions for solving nonlinear differential
equations of the form

     dx
     -- = f (x, t)
     dt

with the initial condition

     x(t = t0) = x0

For Octave to integrate equations of this form, you must first provide a
definition of the function `f(x,t)'.  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.

Producing Graphical Output
--------------------------

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

Editing What You Have Typed
---------------------------

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 *Note Command Line Editing::.

Help and Documentation
----------------------

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 *Note Getting Help::.


File: octave.info,  Node: Conventions,  Prev: Simple Examples,  Up: Introduction

1.3 Conventions
===============

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.

* Menu:

* Fonts::
* Evaluation Notation::
* Printing Notation::
* Error Messages::
* Format of Descriptions::


File: octave.info,  Node: Fonts,  Next: Evaluation Notation,  Up: Conventions

1.3.1 Fonts
-----------

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


File: octave.info,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: Fonts,  Up: Conventions

1.3.2 Evaluation Notation
-------------------------

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)


File: octave.info,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions

1.3.3 Printing Notation
-----------------------

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


File: octave.info,  Node: Error Messages,  Next: Format of Descriptions,  Prev: Printing Notation,  Up: Conventions

1.3.4 Error Messages
--------------------

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'


File: octave.info,  Node: Format of Descriptions,  Prev: Error Messages,  Up: Conventions

1.3.5 Format of Descriptions
----------------------------

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--appears at the beginning of the line.  The
description follows on succeeding lines, sometimes with examples.

* Menu:

* A Sample Function Description::
* A Sample Command Description::
* A Sample Variable Description::


File: octave.info,  Node: A Sample Function Description,  Next: A Sample Command Description,  Up: Format of Descriptions

1.3.5.1 A Sample Function Description
.....................................

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':

 -- Function:  foo (X, Y, ...)
     The function `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

Built-in Function
     The function described is written in a language like C++, C, or
     Fortran, and is part of the compiled Octave binary.

Loadable Function
     The function described is written in a language like C++, C, or
     Fortran.  On systems that support dynamic linking of user-supplied
     functions, it may be automatically linked while Octave is running,
     but only if it is needed.  *Note Dynamically Linked Functions::.

Function File
     The function described is defined using Octave commands stored in
     a text file.  *Note Function Files::.

Mapping Function
     The function described works element-by-element for matrix and
     vector arguments.


File: octave.info,  Node: A Sample Command Description,  Next: A Sample Variable Description,  Prev: A Sample Function Description,  Up: Format of Descriptions

1.3.5.2 A Sample Command Description
....................................

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:

 -- Command: cd dir
 -- Command: chdir dir
     Change the current working directory to DIR.  For example, `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.


File: octave.info,  Node: A Sample Variable Description,  Prev: A Sample Command Description,  Up: Format of Descriptions

1.3.5.3 A Sample Variable Description
.....................................

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

 -- Built-in Variable: do_what_i_mean_not_what_i_say
     If the value of this variable is nonzero, Octave will do what you
     actually wanted, even if you have typed a completely different and
     meaningless list of commands.

   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.


File: octave.info,  Node: Getting Started,  Next: Data Types,  Prev: Introduction,  Up: Top

2 Getting Started
*****************

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.

* Menu:

* Invoking Octave::
* Quitting Octave::
* Getting Help::
* Command Line Editing::
* Errors::
* Executable Octave Programs::
* Comments::


File: octave.info,  Node: Invoking Octave,  Next: Quitting Octave,  Up: Getting Started

2.1 Invoking Octave
===================

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

* Menu:

* Command Line Options::
* Startup Files::


File: octave.info,  Node: Command Line Options,  Next: Startup Files,  Up: Invoking Octave

2.1.1 Command Line Options
--------------------------

Here is a complete list of all the command line options that Octave
accepts.

`--debug'
`-d'
     Enter parser debugging mode.  Using this option will cause Octave's
     parser to print a lot of information about the commands it reads,
     and is probably only useful if you are actually trying to debug
     the parser.

`--echo-commands'
`-x'
     Echo commands as they are executed.

`--exec-path PATH'
     Specify the path to search for programs to run.  The value of PATH
     specified on the command line will override any value of
     `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'
`-?'
     Print short help message and exit.

`--info-file FILENAME'
     Specify the name of the info file to use.  The value of FILENAME
     specified on the command line will override any value of
     `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'
     Specify the name of the info program to use.  The value of PROGRAM
     specified on the command line will override any value of
     `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'
     Force interactive behavior.  This can be useful for running Octave
     via a remote shell command or inside an Emacs shell buffer.  For
     another way to run Octave within Emacs, see *Note Emacs::.

`--no-history'
`-H'
     Disable command-line history.

`--no-init-file'
     Don't read the `~/.octaverc' or `.octaverc' files.

`--no-line-editing'
     Disable command-line editing.

`--no-site-file'
     Don't read the site-wide `octaverc' file.

`--norc'
`-f'
     Don't read any of the system or user initialization files at
     startup.  This is equivalent to using both of the options
     `--no-init-file' and `--no-site-file'.

`--path PATH'
`-p PATH'
     Specify the path to search for function files.  The value of PATH
     specified on the command line will override any value of
     `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'
     Don't print the usual greeting and version message at startup.

`--traditional'
`--braindead'
     Set initial values for user-preference variables to the following
     values for compatibility with MATLAB.

            PS1                           = ">> "
            PS2                           = ""
            beep_on_error                 = true
            crash_dumps_octave_core       = false
            default_save_format           = "mat-binary"
            fixed_point_format            = true
            page_screen_output            = false
            print_empty_dimensions        = false
            warn_function_name_clash      = false

`--verbose'
`-V'
     Turn on verbose output.

`--version'
`-v'
     Print the program version number and exit.

`FILE'
     Execute commands from 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.

 -- Built-in Variable: argv
     The command line arguments passed to Octave are available in this
     variable.  For example, if you invoked Octave using the command

          octave --no-line-editing --silent

     `argv' would be a cell array 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.  *Note Executable Octave
     Programs::, for an example of how to create an executable Octave
     script.

 -- Built-in Variable: program_invocation_name
 -- Built-in Variable: program_name
     When Octave starts, the value of the built-in variable
     `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.  *Note 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", nth (argv, i));
     endfor
     printf ("\n");

*Note Index Expressions::, for an explanation of how to properly index
arrays of strings and substrings in Octave, and *Note Defining
Functions::, for information about the variable `nargin'.


File: octave.info,  Node: Startup Files,  Prev: Command Line Options,  Up: Invoking Octave

2.1.2 Startup Files
-------------------

When Octave starts, it looks for commands to execute from the following
files:

`OCTAVE-HOME/share/octave/site/m/startup/octaverc'
     Where OCTAVE-HOME is the directory in which all of Octave is
     installed (the default is `/usr/local').  This file is provided so
     that changes to the default Octave environment can be made
     globally for all users at your site for all versions of Octave you
     have installed.  Some care should be taken when making changes to
     this file, since all users of Octave at your site will be affected.

`OCTAVE-HOME/share/octave/VERSION/m/startup/octaverc'
     Where OCTAVE-HOME is the directory in which all of Octave is
     installed (the default is `/usr/local'), and VERSION is the
     version number of Octave.  This file is provided so that changes
     to the default Octave environment can be made globally for all
     users for a particular version of Octave.  Some care should be
     taken when making changes to this file, since all users of Octave
     at your site will be affected.

`~/.octaverc'
     This file is normally used to make personal changes to the default
     Octave environment.

`.octaverc'
     This file can be used to make changes to the default Octave
     environment for a particular project.  Octave searches for this
     file in the current directory after it reads `~/.octaverc'.  Any
     use of the `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.


File: octave.info,  Node: Quitting Octave,  Next: Getting Help,  Prev: Invoking Octave,  Up: Getting Started

2.2 Quitting Octave
===================

 -- Built-in Function:  exit (STATUS)
 -- Built-in Function:  quit (STATUS)
     Exit the current Octave session.  If the optional integer value
     STATUS is supplied, pass that value to the operating system as the
     Octave's exit status.

 -- Built-in Function:  atexit (FCN)
     Register a function to be called when Octave exits.  For example,

          function print_fortune ()
            printf ("\n%s\n", system ("fortune"));
            fflush (stdout);
          endfunction
          atexit ("print_fortune");

     will print a message when Octave exits.


File: octave.info,  Node: Getting Help,  Next: Command Line Editing,  Prev: Quitting Octave,  Up: Getting Started

2.3 Commands for Getting Help
=============================

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.  *Note Function Files::, for more information about how to
document the functions you write.

 -- Command: help
     Octave's `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'.

 -- Built-in Variable: INFO_FILE
     The variable `INFO_FILE' names the location of the Octave info
     file.  The default value is `"OCTAVE-HOME/info/octave.info"', in
     which OCTAVE-HOME is the directory where all of Octave is
     installed.

 -- Built-in Variable: INFO_PROGRAM
     The variable `INFO_PROGRAM' names the info program to run.  Its
     default initial value is
     `"OCTAVE-HOME/libexec/octave/VERSION/exec/ARCH/info"' in which
     OCTAVE-HOME is the directory where all of Octave is installed,
     VERSION is the Octave version number, and ARCH is the system type
     (for example, `i686-pc-linux-gnu').  The default initial value may
     be overridden by the environment variable `OCTAVE_INFO_PROGRAM',
     or the command line argument `--info-program NAME', or by setting
     the value of `INFO_PROGRAM' in a startup script

 -- Built-in Variable: MAKEINFO_PROGRAM
     The variable `MAKEINFO_PROGRAM' names the makeinfo program that
     Octave runs to format help text that contains Texinfo markup
     commands.  Its default initial value is `"makeinfo"'.

 -- Built-in Variable: suppress_verbose_help_message
     If the value of `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.


File: octave.info,  Node: Command Line Editing,  Next: Errors,  Prev: Getting Help,  Up: Getting Started

2.4 Command Line Editing
========================

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 <ESC><u>.  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'.

* Menu:

* Cursor Motion::
* Killing and Yanking::
* Commands For Text::
* Commands For Completion::
* Commands For History::
* Customizing readline::
* Customizing the Prompt::
* Diary and Echo Commands::


File: octave.info,  Node: Cursor Motion,  Next: Killing and Yanking,  Up: Command Line Editing

2.4.1 Cursor Motion
-------------------

The following commands allow you to position the cursor.

`C-b'
     Move back one character.

`C-f'
     Move forward one character.

`<DEL>'
     Delete the character to the left of the cursor.

`C-d'
     Delete the character underneath the cursor.

`M-f'
     Move forward a word.

`M-b'
     Move backward a word.

`C-a'
     Move to the start of the line.

`C-e'
     Move to the end of the line.

`C-l'
     Clear the screen, reprinting the current line at the top.

`C-_'
`C-/'
     Undo the last thing that you did.  You can undo all the way back
     to an empty line.

`M-r'
     Undo all changes made to this line.  This is like typing the `undo'
     command enough times to get back to the beginning.

   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.

 -- Built-in Function:  clc ()
 -- Built-in Function:  home ()
     Clear the terminal screen and move the cursor to the upper left
     corner.


File: octave.info,  Node: Killing and Yanking,  Next: Commands For Text,  Prev: Cursor Motion,  Up: Command Line Editing

2.4.2 Killing and Yanking
-------------------------

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

`C-k'
     Kill the text from the current cursor position to the end of the
     line.

`M-d'
     Kill from the cursor to the end of the current word, or if between
     words, to the end of the next word.

`M-<DEL>'
     Kill from the cursor to the start of the previous word, or if
     between words, to the start of the previous word.

`C-w'
     Kill from the cursor to the previous whitespace.  This is
     different than `M-<DEL>' because the word boundaries differ.

   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.

`C-y'
     Yank the most recently killed text back into the buffer at the
     cursor.

`M-y'
     Rotate the kill-ring, and yank the new top.  You can only do this
     if the prior command is `C-y' or `M-y'.

   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.


File: octave.info,  Node: Commands For Text,  Next: Commands For Completion,  Prev: Killing and Yanking,  Up: Command Line Editing

2.4.3 Commands For Changing Text
--------------------------------

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.

`C-q'
`C-v'
     Add the next character that you type to the line verbatim.  This is
     how to insert things like `C-q' for example.

`M-<TAB>'
     Insert a tab character.

`C-t'
     Drag the character before the cursor forward over the character at
     the cursor, also moving the cursor forward.  If the cursor is at
     the end of the line, then transpose the two characters before it.

`M-t'
     Drag the word behind the cursor past the word in front of the
     cursor moving the cursor over that word as well.

`M-u'
     Uppercase the characters following the cursor to the end of the
     current (or following) word, moving the cursor to the end of the
     word.

`M-l'
     Lowecase the characters following the cursor to the end of the
     current (or following) word, moving the cursor to the end of the
     word.

`M-c'
     Uppercase the character following the cursor (or the beginning of
     the next word if the cursor is between words), moving the cursor
     to the end of the word.


File: octave.info,  Node: Commands For Completion,  Next: Commands For History,  Prev: Commands For Text,  Up: Command Line Editing

2.4.4 Letting Readline Type For You
-----------------------------------

The following commands allow Octave to complete command and variable
names for you.

`<TAB>'
     Attempt to do completion on the text before the cursor.  Octave can
     complete the names of commands and variables.

`M-?'
     List the possible completions of the text before the cursor.

 -- Built-in Variable: completion_append_char
     The value of `completion_append_char' is used as the character to
     append to successful command-line completion attempts.  The default
     value is `" "' (a single space).

 -- Built-in Function:  completion_matches (HINT)
     Generate possible completions given HINT.

     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.


File: octave.info,  Node: Commands For History,  Next: Customizing readline,  Prev: Commands For Completion,  Up: Command Line Editing

2.4.5 Commands For Manipulating The History
-------------------------------------------

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.

`<LFD>'
`<RET>'
     Accept the line regardless of where the cursor is.  If this line is
     non-empty, add it to the history list.  If this line was a history
     line, then restore the history line to its original state.

`C-p'
     Move `up' through the history list.

`C-n'
     Move `down' through the history list.

`M-<'
     Move to the first line in the history.

`M->'
     Move to the end of the input history, i.e., the line you are
     entering!

`C-r'
     Search backward starting at the current line and moving `up'
     through the history as necessary.  This is an incremental search.

`C-s'
     Search forward starting at the current line and moving `down'
     through the history as necessary.

   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.

 -- Command: history options
     If invoked with no arguments, `history' displays a list of commands
     that you have executed.  Valid options are:

    `-w FILE'
          Write the current history to the file FILE.  If the name is
          omitted, use the default history file (normally
          `~/.octave_hist').

    `-r FILE'
          Read the file FILE, replacing the current history list with
          its contents.  If the name is omitted, use the default
          history file (normally `~/.octave_hist').

    `N'
          Only display the most recent N lines of history.

    `-q'
          Don't number the displayed lines of history.  This is useful
          for cutting and pasting commands if you are using the X
          Window System.

     For example, to display the five most recent commands that you have
     typed without displaying line numbers, use the command `history -q
     5'.

 -- Command: edit_history options
     If invoked with no arguments, `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.

 -- Command: run_history [first] [last]
     Similar to `edit_history', except that the editor is not invoked,
     and the commands are simply executed as they appear in the history
     list.

 -- Built-in Variable: EDITOR
     A string naming the editor to use with the `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"'.

 -- Built-in Variable: history_file
     This variable specifies the name of the file used to store command
     history.  The default value is `"~/.octave_hist"', but may be
     overridden by the environment variable `OCTAVE_HISTFILE'.

 -- Built-in Variable: history_size
     This variable specifies how many entries to store in the history
     file.  The default value is `1024', but may be overridden by the
     environment variable `OCTAVE_HISTSIZE'.

 -- Built-in Variable: saving_history
     If the value of `saving_history' is nonzero, command entered on
     the command line are saved in the file specified by the variable
     `history_file'.


File: octave.info,  Node: Customizing readline,  Next: Customizing the Prompt,  Prev: Commands For History,  Up: Command Line Editing

2.4.6 Customizing `readline'
----------------------------

 -- Built-in Function:  read_readline_init_file (FILE)
     Read the readline library initialiazation file FILE.  If FILE is
     omitted, read the default initialization file (normally
     `~/.inputrc'.


File: octave.info,  Node: Customizing the Prompt,  Next: Diary and Echo Commands,  Prev: Customizing readline,  Up: Command Line Editing

2.4.7 Customizing the Prompt
----------------------------

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:

`\t'
     The time.

`\d'
     The date.

`\n'
     Begins a new line by printing the equivalent of a carriage return
     followed by a line feed.

`\s'
     The name of the program (usually just `octave').

`\w'
     The current working directory.

`\W'
     The basename of the current working directory.

`\u'
     The username of the current user.

`\h'
     The hostname, up to the first `.'.

`\H'
     The hostname.

`\#'
     The command number of this command, counting from when Octave
     starts.

`\!'
     The history number of this command.  This differs from `\#' by the
     number of commands in the history list when Octave starts.

`\$'
     If the effective UID is 0, a `#', otherwise a `$'.

`\nnn'
     The character whose character code in octal is NNN.

`\\'
     A backslash.

 -- Built-in Variable: PS1
     The primary prompt string.  When executing interactively, Octave
     displays the primary prompt `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.
     *Note Strings::.

 -- Built-in Variable: PS2
     The secondary prompt string, which is printed when Octave is
     expecting additional input to complete a command.  For example,
     when defining a function over several lines, Octave will print the
     value of `PS1' at the beginning of each line after the first.  The
     default value of `PS2' is `"> "'.

 -- Built-in Variable: PS4
     If Octave is invoked with the `--echo-commands' option, the value
     of `PS4' is printed before each line of input that is echoed.  The
     default value of `PS4' is `"+ "'.  *Note Invoking Octave::, for a
     description of `--echo-commands'.


File: octave.info,  Node: Diary and Echo Commands,  Prev: Customizing the Prompt,  Up: Command Line Editing

2.4.8 Diary and Echo Commands
-----------------------------

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.

 -- Command: diary options
     Create a list of all commands _and_ the output they produce, mixed
     together just as you see them on your terminal.  Valid options are:

    `on'
          Start recording your session in a file called `diary' in your
          current working directory.

    `off'
          Stop recording your session in the diary file.

    `FILE'
          Record your session in the file named 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.

 -- Command: echo options
     Control whether commands are displayed as they are executed.  Valid
     options are:

    `on'
          Enable echoing of commands as they are executed in script
          files.

    `off'
          Disable echoing of commands as they are executed in script
          files.

    `on all'
          Enable echoing of commands as they are executed in script
          files and functions.

    `off all'
          Disable echoing of commands as they are executed in script
          files and functions.

     If invoked without any arguments, `echo' toggles the current echo
     state.

 -- Built-in Variable: echo_executing_commands
     This variable may also be used to control the echo state.  It may
     be the sum of the following values:

    1
          Echo commands read from script files.

    2
          Echo commands from functions.

    4
          Echo commands read from command line.

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


File: octave.info,  Node: Errors,  Next: Executable Octave Programs,  Prev: Command Line Editing,  Up: Getting Started

2.5 How Octave Reports Errors
=============================

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 `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
are counted 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.


File: octave.info,  Node: Executable Octave Programs,  Next: Comments,  Prev: Errors,  Up: Getting Started

2.6 Executable Octave Programs
==============================

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.
*Note 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'.
*Note 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");

   ---------- Footnotes ----------

   (1) The `#!' mechanism works on Unix systems derived from Berkeley
Unix, System V Release 4, and some System V Release 3 systems.


File: octave.info,  Node: Comments,  Prev: Executable Octave Programs,  Up: Getting Started

2.7 Comments in Octave Programs
===============================

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 (*note 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.


File: octave.info,  Node: Data Types,  Next: Numeric Data Types,  Prev: Getting Started,  Up: Top

3 Data Types
************

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.  *Note Dynamically Linked
Functions::, for more information about Octave's dynamic linking
capabilities.  *Note User-defined Data Types:: describes what you must
do to define a new data type for Octave.

 -- Built-in Function:  typeinfo (EXPR)
     Return the type of the expression EXPR, as a string.  If EXPR  is
     omitted, return an array of strings containing all the currently
     installed data types.

* Menu:

* Built-in Data Types::
* User-defined Data Types::
* Object Sizes::


File: octave.info,  Node: Built-in Data Types,  Next: User-defined Data Types,  Up: Data Types

3.1 Built-in Data Types
=======================

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.

* Menu:

* Numeric Objects::
* Missing Data::
* String Objects::
* Data Structure Objects::


File: octave.info,  Node: Numeric Objects,  Next: Missing Data,  Up: Built-in Data Types

3.1.1 Numeric Objects
---------------------

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  2.2251e-308 to 1.7977e+308  can
be stored, and the relative precision is approximately  2.2204e-16.
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 using a variety of powerful indexing features.  *Note Index
Expressions::.

   *Note Numeric Data Types::, for more information.


File: octave.info,  Node: Missing Data,  Next: String Objects,  Prev: Numeric Objects,  Up: Built-in Data Types

3.1.2 Missing Data
------------------

 -- Built-in Variable: NA
     Missing value.

 -- Mapping Function:  isna (X)
     Return 1 for elements of X that are NA (missing) values and zero
     otherwise. For example,

          is_NA ([13, Inf, NA, NaN])
               => [ 0, 0, 1, 0 ]

 -- Mapping Function:  is_nan_or_na (X)
     Return 1 for elements of X that are NaN or NA (missing) values and
     zero otherwise. For example,

          is_NAN_or_NA ([13, Inf, NA, NaN])
               => [ 0, 0, 1, 1 ]


File: octave.info,  Node: String Objects,  Next: Data Structure Objects,  Prev: Missing Data,  Up: Built-in Data Types

3.1.3 String Objects
--------------------

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.

   *Note Strings::, for more information.


File: octave.info,  Node: Data Structure Objects,  Prev: String Objects,  Up: Built-in Data Types

3.1.4 Data Structure Objects
----------------------------

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.

   *Note Data Structures::, for more information.


File: octave.info,  Node: User-defined Data Types,  Next: Object Sizes,  Prev: Built-in Data Types,  Up: Data Types

3.2 User-defined Data Types
===========================

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.


File: octave.info,  Node: Object Sizes,  Prev: User-defined Data Types,  Up: Data Types

3.3 Object Sizes
================

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.

 -- Function File:  columns (A)
     Return the number of columns of A.

 -- Function File:  rows (A)
     Return the number of rows of A.

 -- Built-in Function:  length (A)
     Return the `length' of the object A.  For matrix objects, the
     length is the number of rows or columns, whichever is greater (this
     odd definition is used for compatibility with Matlab).

 -- Built-in Function:  size (A, N)
     Return the number rows and columns of A.

     With one input argument and one output argument, the result is
     returned in a row vector.  If there are multiple output arguments,
     the number of rows is assigned to the first, and the number of
     columns to the second, etc.  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, `size' will return the size of the
     corresponding dimension.  For example

          size ([1, 2; 3, 4; 5, 6], 2)
               => 2

     returns the number of columns in the given matrix.

 -- Built-in Function:  isempty (A)
     Return 1 if A is an empty matrix (either the number of rows, or
     the number of columns, or both are zero).  Otherwise, return 0.


File: octave.info,  Node: Numeric Data Types,  Next: Strings,  Prev: Data Types,  Up: Top

4 Numeric Data Types
********************

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   `sqrt (-1)'.

   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.

* Menu:

* Matrices::
* Ranges::
* Logical Values::
* Predicates for Numeric Objects::


File: octave.info,  Node: Matrices,  Next: Ranges,  Up: Numeric Data Types

4.1 Matrices
============

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


             /      \
             | 1  2 |
       a  =  |      |
             | 3  4 |
             \      /

   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 an expression like

     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 ]'.  Similarly, the expression

     [ sin (pi) ]

will be parsed as

     [ sin, (pi) ]

and will result in an error since the `sin' function will be called
with no arguments.  To get around this, you must omit the space between
`sin' and the opening parenthesis, or enclose the expression in a set
of parentheses:

     [ (sin (pi)) ]

   Whitespace surrounding the single quote character (`'', used as a
transpose operator and for delimiting character strings) can also cause
confusion.  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 cause trouble when parsing the valid
expression

     [ a 'foo' ]

   For clarity, it is probably best to always use commas and semicolons
to separate matrix elements and rows.

 -- Built-in Variable: warn_separator_insert
     Print warning if commas or semicolons might be inserted
     automatically in literal matrices.

   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.

 -- Built-in Variable: output_max_field_width
     This variable specifies the maximum width of a numeric output
     field.  The default value is 10.

 -- Built-in Variable: output_precision
     This variable specifies the minimum number of significant figures
     to display for numeric output.  The default value is 5.

   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.  *Note
Basic Input and Output::.

 -- Built-in Variable: split_long_rows
     For large matrices, Octave may not be able to display all the
     columns of a given row on one line of your screen.  This can
     result in missing information or output that is nearly impossible
     to decipher, depending on whether your terminal truncates or wraps
     long lines.

     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.

 -- Built-in Variable: fixed_point_format
     If the value of this variable is nonzero, Octave will scale all
     values in a matrix so that the largest may be written with one
     leading digit.  The scaling factor is printed on the first line of
     output.  For example,

          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.

* Menu:

* Empty Matrices::


File: octave.info,  Node: Empty Matrices,  Up: Matrices

4.1.1 Empty Matrices
--------------------

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.  Briefly, given a scalar S, an M by N matrix
`M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both
dimensions equal to zero), the following are true:

     s * [](mxn) = [](mxn) * s = [](mxn)

         [](mxn) + [](mxn) = [](mxn)

         [](0xm) *  M(mxn) = [](0xn)

          M(mxn) * [](nx0) = [](mx0)

         [](mx0) * [](0xn) =  0(mxn)

   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.

 -- Built-in Variable: print_empty_dimensions
     If the value of `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.  *Note Assignment
Expressions: Assignment Ops.

 -- Built-in Variable: warn_empty_list_elements
     If the value of `warn_empty_list_elements' is nonzero, print a
     warning when an empty matrix is found in a matrix list.  For
     example,

          a = [1, [], 3, [], 5]

     The default value is 0.

   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.


File: octave.info,  Node: Ranges,  Next: Logical Values,  Prev: Matrices,  Up: Numeric Data Types

4.2 Ranges
==========

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 (*note 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.


File: octave.info,  Node: Logical Values,  Next: Predicates for Numeric Objects,  Prev: Ranges,  Up: Numeric Data Types

4.3 Logical Values
==================

 -- Built-in Variable: true
     Logical true value.

 -- Built-in Variable: false
     Logical false value.


File: octave.info,  Node: Predicates for Numeric Objects,  Prev: Logical Values,  Up: Numeric Data Types

4.4 Predicates for Numeric Objects
==================================

 -- Built-in Function:  isnumeric (X)
     Return nonzero if X is a numeric object.

 -- Built-in Function:  isreal (X)
     Return true if X is a real-valued numeric object.

 -- Built-in Function:  iscomplex (X)
     Return true if X is a complex-valued numeric object.

 -- Built-in Function:  ismatrix (A)
     Return 1 if A is a matrix.  Otherwise, return 0.

 -- Function File:  isvector (A)
     Return 1 if A is a vector.  Otherwise, return 0.

 -- Function File:  isscalar (A)
     Return 1 if A is a scalar.  Otherwise, return 0.

 -- Function File:  issquare (X)
     If X is a square matrix, then return the dimension of X.
     Otherwise, return 0.

 -- Function File:  issymmetric (X, TOL)
     If X is symmetric within the tolerance specified by TOL, then
     return the dimension of X.  Otherwise, return 0.  If TOL is
     omitted, use a tolerance equal to the machine precision.

 -- Built-in Functio:  isbool (X)
     Return true if X is a boolean object.


File: octave.info,  Node: Strings,  Next: Data Structures,  Prev: Numeric Data Types,  Up: Top

5 Strings
*********

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
(*note Arithmetic Ops::) 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.

`\\'
     Represents a literal backslash, `\'.

`\"'
     Represents a literal double-quote character, `"'.

`\''
     Represents a literal single-quote character, `''.

`\0'
     Represents the "nul" character, control-@, ASCII code 0.

`\a'
     Represents the "alert" character, control-g, ASCII code 7.

`\b'
     Represents a backspace, control-h, ASCII code 8.

`\f'
     Represents a formfeed, control-l, ASCII code 12.

`\n'
     Represents a newline, control-j, ASCII code 10.

`\r'
     Represents a carriage return, control-m, ASCII code 13.

`\t'
     Represents a horizontal tab, control-i, ASCII code 9.

`\v'
     Represents a vertical tab, control-k, ASCII code 11.


   Strings may be concatenated using the notation for defining matrices.
For example, the expression

     [ "foo" , "bar" , "baz" ]

produces the string whose contents are `foobarbaz'.  *Note Numeric Data
Types::, for more information about creating matrices.

* Menu:

* Creating Strings::
* Searching and Replacing::
* String Conversions::
* Character Class Functions::


File: octave.info,  Node: Creating Strings,  Next: Searching and Replacing,  Up: Strings

5.1 Creating Strings
====================

 -- Function File:  blanks (N)
     Return a string of N blanks.

 -- Built-in Function:  char (X)
 -- Built-in Function:  char (CELL_ARRAY)
 -- Built-in Function:  char (S1, S2, ...)
     Create a string array from a numeric matrix, cell array, or list of

     If the argument is a numeric matrix, each element of the matrix is
     converted to the corresponding ASCII character.  For example,

          char ([97, 98, 99])
               => "abc"

     If the argument is a cell array of strings, the result is a string
     array with each element corresponding to one element of the cell
     array.

     For multiple string arguments, the result is a string array with
     each element corresponding to the arguments.

     The returned values are padded with blanks as needed to make each
     row of the string array have the same length.

 -- Function File:  int2str (N)
 -- Function File:  num2str (X, PRECISION)
 -- Function File:  num2str (X, FORMAT)
     Convert a number to a string.  These functions are not very
     flexible, but are provided for compatibility with MATLAB.  For
     better control over the results, use `sprintf' (*note Formatted
     Output::).

 -- Function File:  com2str (ZZ, FLG)
     This function has been deprecated.  Use num2str instead.

     Convert complex number to a string.  *Inputs*
    ZZ
          complex number

    FLG
          format flag 0 (default):            -1, 0, 1,   1i,   1 + 0.5i
          1 (for use with zpout): -1, 0, + 1, + 1i, + 1 + 0.5i

 -- Function File:  strcat (S1, S2, ...)
     Return a string containing all the arguments concatenated.  For
     example,

          s = [ "ab"; "cde" ];
          strcat (s, s, s)
          => "ab ab ab "
                  "cdecdecde"

 -- Built-in Variable: string_fill_char
     The value of this variable is used to pad all strings in a string
     matrix to the same length.  It should be a single character.  The
     default value is `" "' (a single space).  For example,

          string_fill_char = "X";
          [ "these"; "are"; "strings" ]
               => "theseXX"
                  "areXXXX"
                  "strings"

 -- Function File:  str2mat (S_1, ..., S_N)
     Return a matrix containing the strings S_1, ..., S_N as its rows.
     Each string is padded with blanks in order to form a valid matrix.

     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.

 -- Built-in Function:  ischar (A)
     Return 1 if A is a string.  Otherwise, return 0.

 -- Function File:  isstr (A)
     This function has been deprecated.  Use ischar instead.


File: octave.info,  Node: Searching and Replacing,  Next: String Conversions,  Prev: Creating Strings,  Up: Strings

5.2 Searching and Replacing
===========================

 -- Function File:  deblank (S)
     Removes the trailing blanks and nulls from the string S.  If S is
     a matrix, DEBLANK trims each row to the length of longest string.

 -- Function File:  findstr (S, T, OVERLAP)
     Return the vector of all positions in the longer of the two strings
     S and T where an occurrence of the shorter of the two starts.  If
     the optional argument OVERLAP is nonzero, the returned vector can
     include overlapping positions (this is the default).  For example,

          findstr ("ababab", "a")
          => [ 1, 3, 5 ]
          findstr ("abababa", "aba", 0)
          => [ 1, 5 ]

 -- Function File:  index (S, T)
     Return the position of the first occurrence of the string T in the
     string S, or 0 if no occurrence is found.  For example,

          index ("Teststring", "t")
          => 4

     *Caution:*  This function does not work for arrays of strings.

 -- Function File:  rindex (S, T)
     Return the position of the last occurrence of the string T in the
     string S, or 0 if no occurrence is found.  For example,

          rindex ("Teststring", "t")
          => 6

     *Caution:*  This function does not work for arrays of strings.

 -- Function File:  split (S, T)
     Divides the string S into pieces separated by T, returning the
     result in a string array (padded with blanks to form a valid
     matrix).  For example,

          split ("Test string", "t")
          => "Tes "
                  " s  "
                  "ring"

 -- Function File:  strcmp (S1, S2)
     Compares two character strings, returning true if they are the
     same, and false otherwise.

     *Caution:*  For compatibility with MATLAB, Octave's strcmp
     function returns true if the character strings are equal, and false
     otherwise.  This is just the opposite of the corresponding C
     library function.

 -- Function File:  strrep (S, X, Y)
     Replaces all occurrences of the substring X of the string S with
     the string Y.  For example,

          strrep ("This is a test string", "is", "&%$")
          => "Th&%$ &%$ a test string"

 -- Function File:  substr (S, BEG, LEN)
     Return the substring of S which starts at character number BEG and
     is LEN characters long.

     If OFFSET is negative, extraction starts that far from the end of
     the string.  If LEN is omitted, the substring extends to the end
     of S.

     For example,

          substr ("This is a test string", 6, 9)
          => "is a test"

          This function is patterned after AWK.  You can get the same
          result by `S (BEG : (BEG + LEN - 1))'.


File: octave.info,  Node: String Conversions,  Next: Character Class Functions,  Prev: Searching and Replacing,  Up: Strings

5.3 String Conversions
======================

 -- Function File:  hex2dec (S)
     Return the decimal number corresponding to the binary number stored
     in the string S.  For example,

          hex2dec ("1110")
          => 14

     If S is a string matrix, returns a column vector of converted
     numbers, one per row of S.  Invalid rows evaluate to NaN.

 -- Function File:  dec2bin (N, LEN)
     Return a binary number corresponding the nonnegative decimal number
     N, as a string of ones and zeros.  For example,

          dec2bin (14)
          => "1110"

     If N is a vector, returns a string matrix, one row per value,
     padded with leading zeros to the width of the largest value.

     The optional second argument, LEN, specifies the minimum number of
     digits in the result.

 -- Function File:  dec2hex (N, LEN)
     Return the hexadecimal string corresponding to the nonnegative
     integer N.  For example,

          dec2hex (2748)
          => "ABC"

     If N is a vector, returns a string matrix, one row per value,
     padded with leading zeros to the width of the largest value.

     The optional second argument, LEN, specifies the minimum number of
     digits in the result.

 -- Function File:  hex2dec (S)
     Returns the integer corresponding to the hexadecimal number stored
     in the string S.  For example,

          hex2dec ("12B")
          => 299
          hex2dec ("12b")
          => 299

     If S is a string matrix, returns a column vector of converted
     numbers, one per row of S.  Invalid rows evaluate to NaN.

 -- Function File:  dec2base (N, B, LEN)
     Return a string of symbols in base B corresponding to the the
     nonnegative integer N.

          dec2base (123, 3)
          => "11120"

     If N is a vector, return a string matrix with one row per value,
     padded with leading zeros to the width of the largest value.

     If B is a string then the characters of B are used as the symbols
     for the digits of N.  Space (' ') may not be used as a symbol.

          dec2base (123, "aei")
          => "eeeia"

     The optional third argument, LEN, specifies the minimum number of
     digits in the result.

 -- Function File:  base2dec (S, B)
     Convert S from a string of digits of base B into an integer.

          base2dec ("11120", 3)
          => 123

     If S is a matrix, returns a column vector with one value per row
     of S.  If a row contains invalid symbols then the corresponding
     value will be NaN.  Rows are right-justified before converting so
     that trailing spaces are ignored.

     If B is a string, the characters of B are used as the symbols for
     the digits of S. Space (' ') may not be used as a symbol.

          base2dec ("yyyzx", "xyz")
          => 123


 -- Function File:  strjust (S, ["left"|"right"|"center"])
     Shift the non-blank text of S to the left, right or center of the
     string.  If S is a string array, justify each string in the array.
     Null characters are replaced by blanks.  If no justification is
     specified, then all rows are right-justified.

 -- Function File:  str2num (S)
     Convert the string S to a number.

 -- Mapping Function:  toascii (S)
     Return ASCII representation of S in a matrix.  For example,

          toascii ("ASCII")
               => [ 65, 83, 67, 73, 73 ]


 -- Mapping Function:  tolower (S)
     Return a copy of the string S, with each upper-case character
     replaced by the corresponding lower-case one; nonalphabetic
     characters are left unchanged.  For example,

          tolower ("MiXeD cAsE 123")
               => "mixed case 123"

 -- Built-in Function:  toupper (S)
     Return a copy of the string S, with each  lower-case character
     replaced by the corresponding upper-case one; nonalphabetic
     characters are left unchanged.  For example,

          toupper ("MiXeD cAsE 123")
               => "MIXED CASE 123"

 -- Built-in Function:  do_string_escapes (STRING)
     Convert special characters in STRING to their escaped forms.

 -- Built-in Function:  undo_string_escapes (S)
     Converts special characters in strings back to their escaped
     forms.  For example, the expression

          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.

 -- Built-in Variable: warn_num_to_str
     If the value of `warn_num_to_str' is nonzero, a warning is printed
     for implicit conversions of numbers to their ASCII character
     equivalents when strings are constructed using a mixture of
     strings and numbers in matrix notation.  For example,

          [ "f", 111, 111 ]
               => "foo"
     elicits a warning if `warn_num_to_str' is nonzero.  The
     default value is 1.

 -- Built-in Variable: warn_str_to_num
     If the value of `warn_str_to_num' is nonzero, a warning is printed
     for implicit conversions of strings to their numeric ASCII
     equivalents.  For example,
          "abc" + 0
               => 97 98 99
     elicits a warning if `warn_str_to_num' is nonzero.  The
     default value is 0.

 -- Built-in Variable: warn_single_quote_string
     Print warning if a signle quote character is used to introduce a
     string constant.


File: octave.info,  Node: Character Class Functions,  Prev: String Conversions,  Up: Strings

5.4 Character Class Functions
=============================

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 ]

 -- Mapping Function:  isalnum (S)
     Return 1 for characters that are letters or digits (`isalpha (S)'
     or `isdigit (S)' is true).

 -- Mapping Function:  isalpha (S)
 -- Mapping Function:  isletter (S)
     Return true for characters that are letters (`isupper (S)' or
     `islower (S)' is true).

 -- Mapping Function:  isascii (S)
     Return 1 for characters that are ASCII (in the range 0 to 127
     decimal).

 -- Mapping Function:  iscntrl (S)
     Return 1 for control characters.

 -- Mapping Function:  isdigit (S)
     Return 1 for characters that are decimal digits.

 -- Mapping Function:  isgraph (S)
     Return 1 for printable characters (but not the space character).

 -- Mapping Function:  islower (S)
     Return 1 for characters that are lower case letters.

 -- Mapping Function:  isprint (S)
     Return 1 for printable characters (including the space character).

 -- Mapping Function:  ispunct (S)
     Return 1 for punctuation characters.

 -- Mapping Function:  isspace (S)
     Return 1 for whitespace characters (space, formfeed, newline,
     carriage return, tab, and vertical tab).

 -- Mapping Function:  isupper (S)
     Return 1 for upper case letters.

 -- Mapping Function:  isxdigit (S)
     Return 1 for characters that are hexadecimal digits.


File: octave.info,  Node: Data Structures,  Next: Containers,  Prev: Strings,  Up: Top

6 Data Structures
*****************

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 =
         {
           d: 1x1 struct
         }
       }
     }

This prevents long and confusing output from large deeply nested
structures.

 -- Built-in Variable: struct_levels_to_print
     You can tell Octave how many structure levels to display by
     setting the built-in variable `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 (2) + rand (2) * 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 (*note The for
Statement::)

   The following functions are available to give you information about
structures.

 -- Built-in Function:  isstruct (EXPR)
     Return 1 if the value of the expression EXPR is a structure.

 -- Built-in Function:  fieldnames (STRUCT)
     Return a cell array of strings naming the elements of the structure
     STRUCT.  It is an error to call `fieldnames' with an argument that
     is not a structure.

 -- Built-in Function:  isfield (EXPR, NAME)
     Return true if the expression EXPR is a structure and it includes
     an element named NAME.  The first argument must be a structure and
     the second must be a string.


File: octave.info,  Node: Containers,  Next: I/O Streams,  Prev: Data Structures,  Up: Top

7 Containers
************

* Menu:

* Lists::
* Cell Arrays::


File: octave.info,  Node: Lists,  Next: Cell Arrays,  Up: Containers

7.1 Lists
=========

 -- Built-in Function:  list (A1, A2, ...)
     Create a new list with elements given by the arguments A1, A2, ....

 -- Built-in Function:  nth (LIST, N)
     Return the N-th element of LIST.

 -- Built-in Function:  append (LIST, A1, A2, ...)
     Return a new list created by appending A1, A1, ..., to LIST.  If
     any of the arguments to be appended is a list, its elements are
     appended individually.  For example,

          x = list (1, 2);
          y = list (3, 4);
          append (x, y);

     results in the list containing the four elements `(1 2 3 4)', not
     a list containing the three elements `(1 2 (3 4))'.

 -- Built-in Function:  reverse (LIST)
     Return a new list created by reversing the elements of LIST.

 -- Built-in Function:  splice (LIST_1, OFFSET, LENGTH, LIST_2)
     Replace LENGTH elements of LIST_1 beginning at OFFSET with the
     contents of LIST_2 (if any).  If LENGTH is omitted, all elements
     from OFFSET to the end of LIST_1 are replaced.  As a special case,
     if OFFSET is one greater than the length of LIST_1 and LENGTH is
     0, splice is equivalent to `append (LIST_1, LIST_2)'.

 -- Built-in Function:  islist (X)
     Return nonzero if X is a list.


File: octave.info,  Node: Cell Arrays,  Prev: Lists,  Up: Containers

7.2 Cell Arrays
===============

 -- Built-in Function:  cell (X)
 -- Built-in Function:  cell (N, M)
     Create a new cell array object.  If invoked with a single scalar
     argument, `cell' returns a square cell array with the dimension
     specified.  If you supply two scalar arguments, `cell' takes them
     to be the number of rows and columns.  If given a vector with two
     elements, `cell' uses the values of the elements as the number of
     rows and columns, respectively.

 -- Built-in Function:  cellstr (STRING)
     Create a new cell array object from the elements of the string
     array STRING.

 -- Built-in Function:  iscell (X)
     Return true if X is a cell array object.  Otherwise, return false.


File: octave.info,  Node: I/O Streams,  Next: Variables,  Prev: Containers,  Up: Top

8 I/O Streams
*************

 -- Built-in Function:  isstream (X)
     Return true if X is a stream object.  Otherwise, return false.


File: octave.info,  Node: Variables,  Next: Expressions,  Prev: I/O Streams,  Up: Top

9 Variables
***********

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".  *Note Assignment
Expressions: Assignment Ops.

   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. *Note 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.

* Menu:

* Global Variables::
* Persistent Variables::
* Status of Variables::
* Summary of Built-in Variables::
* Defaults from the Environment::


File: octave.info,  Node: Global Variables,  Next: Persistent Variables,  Up: Variables

9.1 Global Variables
====================

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 a b
     global c = 2
     global d = 3 e f = 5

   A global variable may only be initialized once in a `global'
statement.  For example, after executing the following code

     global gvar = 1
     global gvar = 2

the value of the global variable `gvar' is 1, not 2.

   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.

 -- Built-in Function:  isglobal (NAME)
     Return 1 if NAME is globally visible.  Otherwise, return 0.  For
     example,

          global x
          isglobal ("x")
               => 1


File: octave.info,  Node: Persistent Variables,  Next: Status of Variables,  Prev: Global Variables,  Up: Variables

9.2 Persistent Variables
========================

A variable that has been declared "persistent" within a function will
retain its contents in memory between subsequent calls to the same
function. The difference between persistent variables and global
variables is that persistent variables are local in scope to a
particular function and are not visible elsewhere.

   A variable may be declared persistent using a `persistent'
declaration statement.  The following statements are all persistent
declarations.

     persistent a
     persistent a b
     persistent c = 2
     persistent d = 3 e f = 5

   The behavior of persistent variables is equivalent to the behavior of
static variables in C. The command `static' in octave is also
recognized and is equivalent to `persistent'. Unlike global variables,
every initialization statement will re-initialize the variable. For
example, after executing the following code

     persistent pvar = 1
     persistent pvar = 2

the value of the persistent variable `pvar' is 2.


File: octave.info,  Node: Status of Variables,  Next: Summary of Built-in Variables,  Prev: Persistent Variables,  Up: Variables

9.3 Status of Variables
=======================

 -- Command: clear [-x] pattern ...
     Delete the names matching the given patterns from the symbol
     table.  The pattern may contain the following special characters:

    `?'
          Match any single character.

    `*'
          Match zero or more characters.

    `[ LIST ]'
          Match the list of characters specified by LIST.  If the first
          character is `!' 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.

     With -x, clear the variables that don't match the patterns.

     This command may not be used within a function body.

 -- Command: who options pattern ...
 -- Command: whos options pattern ...
     List currently defined symbols matching the given patterns.  The
     following are valid options.  They may be shortened to one
     character but may not be combined.

    `-all'
          List all currently defined symbols.

    `-builtins'
          List built-in variables and functions.  This includes all
          currently compiled function files, but does not include all
          function files that are in the `LOADPATH'.

    `-functions'
          List user-defined functions.

    `-long'
          Print a long listing including the type and dimensions of any
          symbols.  The symbols in the first column of output indicate
          whether it is possible to redefine the symbol, and whether it
          is possible for it to be cleared.

    `-variables'
          List user-defined 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'.

 -- Command: whos options pattern ...
     See who.

 -- Built-in Variable: whos_line_format
     This string decides in what order attributtes of variables are to
     be printed.  The following commands are used:
    `%b'
          Prints number of bytes occupied by variables.

    `%e'
          Prints elements held by variables.

    `%n'
          Prints variable names.

    `%p'
          Prints protection attributtes of variables.

    `%s'
          Prints dimensions of variables.

    `%t'
          Prints type names of variables.

     Every command may also have a modifier:
    `l'
          Left alignment.

    `r'
          Right alignment (this is the default).

    `c'
          Centered (may only be applied to command %s).

     A command is composed like this:
     %[modifier]<command>[:size_of_parameter[:center-specific[:print_dims[:balance]]]];

     Command and modifier is already explained. Size_of_parameter tells
     how many columns the parameter will need for printing.  print_dims
     tells how many dimensions to print. If number of dimensions
     exceeds print_dims, dimensions will be printed like x-D.
     center-specific and print_dims may only be applied to command %s.
     A negative value for print_dims will cause Octave to print all
     dimensions whatsoever.  balance specifies the offset for printing
     of the dimensions string.

     Default format is "  %p:4; %ln:6; %cs:16:6:8:1;  %rb:12;
     %lt:-1;\n".

 -- Built-in Function:  exist (NAME, TYPE)
     Return 1 if the name exists as a variable, 2 if the name (after
     appending `.m') is a function file in Octave's LOADPATH, 3 if the
     name is a `.oct' file in Octave's LOADPATH, 5 if the name is a
     built-in function, 7 if the name is a directory, 101 if the name is
     a built-in variable, 102 if the name is a built-in constant, or 103
     if the name is a function not associated with a file (entered on
     the command line).

     Otherwise, return 0.

     This function also returns 2 if a regular file called NAME exists
     in Octave's `LOADPATH'.  If you want information about other types
     of files, you should use some combination of the functions
     `file_in_path' and `stat' instead.

     If the optional argument TYPE is supplied, check only for symbols
     of the specified type.  Valid types are

    `"var"'
          Check only for variables.

    `"builtin"'
          Check only for built-in functions.

    `"file"'
          Check only for files.

    `"dir"'
          Check only for directories.

 -- Built-in Function:  document (SYMBOL, TEXT)
     Set the documentation string for SYMBOL to TEXT.

 -- Command: type options name ...
     Display the definition of each NAME that refers to a function.

     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.

 -- Command: which name ...
     Display the type of each NAME.  If NAME is defined from a function
     file, the full name of the file is also displayed.


File: octave.info,  Node: Summary of Built-in Variables,  Next: Defaults from the Environment,  Prev: Status of Variables,  Up: Variables

9.4 Summary of Built-in Variables
=================================

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.1.x) and ARCH stands for the
type of system for which Octave was compiled (for example,
`i586-pc-linux-gnu').

`DEFAULT_LOADPATH'
     *Note Function Files::.

     Default value: `".:OCTAVE-HOME/lib/VERSION"'.

`EDITOR'
     *Note Commands For History::.

     Default value: `"emacs"'.

`EXEC_PATH'
     *Note Controlling Subprocesses::.

     Default value: `":$PATH"'.

`INFO_FILE'
     *Note Getting Help::.

     Default value: `"OCTAVE-HOME/info/octave.info"'.

`INFO_PROGRAM'
     *Note Getting Help::.

     Default value:
     `"OCTAVE-HOME/libexec/octave/VERSION/exec/ARCH/info"'.

`LOADPATH'
     *Note Function Files::.

     Default value: `":"', which tells Octave to use the directories
     specified by the built-in variable `DEFAULT_LOADPATH'.

`OCTAVE_HOME'
     Default value: `"/usr/local"'.

`PAGER'
     *Note Input and Output::.

     Default value: `"less", or "more"'.

`PS1'
     *Note Customizing the Prompt::.

     Default value: `"\s:\#> "'.

`PS2'
     *Note Customizing the Prompt::.

     Default value: `"> "'.

`PS4'
     *Note Customizing the Prompt::.

     Default value: `"+ "'.

`automatic_replot'
     *Note Two-Dimensional Plotting::.

     Default value: 0.

`beep_on_error'
     *Note Error Handling::.

     Default value: 0.

`completion_append_char'
     *Note Commands For Completion::.

     Default value: `" "'.

`default_save_format'
     *Note Simple File I/O::.

     Default value: `"ascii"'.

`crash_dumps_octave_core'
     *Note Simple File I/O::.

     Default value: 1.

`fixed_point_format'
     *Note Matrices::.

     Default value: 0.

`gnuplot_binary'
     *Note Three-Dimensional Plotting::.

     Default value: `"gnuplot"'.

`history_file'
     *Note Commands For History::.

     Default value: `"~/.octave_hist"'.

`history_size'
     *Note Commands For History::.

     Default value: 1024.

`ignore_function_time_stamp'
     *Note Function Files::.

     Default value: `"system"'.

`max_recursion_depth'
     *Note Recursion::.

     Default value: 256.

`output_max_field_width'
     *Note Matrices::.

     Default value: 10.

`output_precision'
     *Note Matrices::.

     Default value: 5.

`page_screen_output'
     *Note Input and Output::.

     Default value: 1.

`print_answer_id_name'
     *Note Terminal Output::.

     Default value: 1.

`print_empty_dimensions'
     *Note Empty Matrices::.

     Default value: 1.

`return_last_computed_value'
     *Note Returning From a Function::.

     Default value: 0.

`save_precision'
     *Note Simple File I/O::.

     Default value: 17.

`saving_history'
     *Note Commands For History::.

     Default value: 1.

`sighup_dumps_octave_core'
     *Note Simple File I/O::.

     Default value: 1.

`sigterm_dumps_octave_core'
     *Note Simple File I/O::.

     Default value: 1.

`silent_functions'
     *Note Defining Functions::.

     Default value: 0.

`split_long_rows'
     *Note Matrices::.

     Default value: 1.

`struct_levels_to_print'
     *Note Data Structures::.

     Default value: 2.

`suppress_verbose_help_message'
     *Note Getting Help::.

     Default value: 1.

`warn_assign_as_truth_value'
     *Note The if Statement::.

     Default value: 1.

`warn_comma_in_global_decl'
     *Note Global Variables::.

     Default value: 1.

`warn_divide_by_zero'
     *Note Arithmetic Ops::.

     Default value: 1.

`warn_empty_list_elements'
     *Note Empty Matrices::.

     Default value: 0.

`warn_fortran_indexing'
     *Note Index Expressions::.

     Default value: 0.

`warn_function_name_clash'
     *Note Function Files::.

     Default value: 1.

`warn_imag_to_real'
     *Note Special Utility Matrices::.

     Default value: 0.

`warn_missing_semicolon'
     *Note Defining Functions::.

     Default value: 0.

`warn_neg_dim_as_zero'
     *Note Special Utility Matrices::.

     Default value: 0.

`warn_num_to_str'
     *Note String Conversions::.

     Default value: 1.

`warn_reload_forces_clear'
     *Note Dynamically Linked Functions::.

     Default value: 1.

`warn_resize_on_range_error'
     *Note Index Expressions::.

     Default value: 0.

`warn_separator_insert'
     *Note Matrices::.

     Default value: 0.

`warn_single_quote_string'
     *Note String Conversions::.

     Default value: 0.

`warn_str_to_num'
     *Note String Conversions::.

     Default value: 0.

`warn_undefined_return_values'
     *Note Multiple Return Values::.

     Default value: 0.

`warn_variable_switch_label'
     *Note The switch Statement::.

     Default value: 0.


File: octave.info,  Node: Defaults from the Environment,  Prev: Summary of Built-in Variables,  Up: Variables

9.5 Defaults from the Environment
=================================

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.  *Note Command Line Options::.

`EDITOR'
     *Note Commands For History::.

     Built-in variable: `EDITOR'.

`OCTAVE_EXEC_PATH'
     *Note Controlling Subprocesses::.

     Built-in variable: `EXEC_PATH'.  Command-line argument:
     `--exec-path'.

`OCTAVE_PATH'
     *Note Function Files::.

     Built-in variable: `LOADPATH'.  Command-line argument: `--path'.

`OCTAVE_INFO_FILE'
     *Note Getting Help::.

     Built-in variable: `INFO_FILE'.  Command-line argument:
     `--info-file'.

`OCTAVE_INFO_PROGRAM'
     *Note Getting Help::.

     Built-in variable: `INFO_PROGRAM'.  Command-line argument:
     `--info-program'.

`OCTAVE_HISTSIZE'
     *Note Commands For History::.

     Built-in variable: `history_size'.

`OCTAVE_HISTFILE'
     *Note Commands For History::.

     Built-in variable: `history_file'.


File: octave.info,  Node: Expressions,  Next: Evaluation,  Prev: Variables,  Up: Top

10 Expressions
**************

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.

* Menu:

* Index Expressions::
* Calling Functions::
* Arithmetic Ops::
* Comparison Ops::
* Boolean Expressions::
* Assignment Ops::
* Increment Ops::
* Operator Precedence::


File: octave.info,  Node: Index Expressions,  Next: Calling Functions,  Up: Expressions

10.1 Index Expressions
======================

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 may be
indexed using one or two indices (a warning is issued if a single index
is used unless the value of the built-in variable
`warn_fortran_indexing' is zero).

 -- Built-in Variable: warn_fortran_indexing
     If the value of `warn_fortran_indexing' is nonzero, a warning is
     printed for expressions which select elements of a two-dimensional
     matrix using a single index.  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.

   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.  *Note Special Utility Matrices::.

 -- Built-in Variable: warn_resize_on_range_error
     If the value of `warn_resize_on_range_error' is nonzero, print a
     warning when a matrix is resized by an indexed assignment with
     indices outside the current bounds.  The default value is 0.

   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)*nc+1:i*nc) = 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.


File: octave.info,  Node: Calling Functions,  Next: Arithmetic Ops,  Prev: Index Expressions,  Up: Expressions

10.2 Calling Functions
======================

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.  *Note
Functions and Scripts::, 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 *Note Index Expressions::, and *Note Assignment
Ops::.

* Menu:

* Call by Value::
* Recursion::


File: octave.info,  Node: Call by Value,  Next: Recursion,  Up: Calling Functions

10.2.1 Call by Value
--------------------

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.


File: octave.info,  Node: Recursion,  Prev: Call by Value,  Up: Calling Functions

10.2.2 Recursion
----------------

With some restrictions(1), recursive function calls are allowed.  A
"recursive function" is one which calls itself, either directly or
indirectly.  For example, here is an inefficient(2) 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.

 -- Built-in Variable: max_recursion_depth
     Limit the number of times a function may be called recursively.
     If the limit is exceeded, an error message is printed and control
     returns to the top level.

     The default value is 256.

   ---------- Footnotes ----------

   (1) Some of Octave's function are implemented in terms of functions
that cannot be called recursively.  For example, the ODE solver `lsode'
is ultimately implemented in a Fortran subroutine that cannot be called
recursively, so `lsode' should not be called either directly or
indirectly from within the user-supplied function that `lsode'
requires.  Doing so will result in undefined behavior.

   (2) It would be much better to use `prod (1:n)', or `gamma (n+1)'
instead, after first checking to ensure that the value `n' is actually a
positive integer.


File: octave.info,  Node: Arithmetic Ops,  Next: Comparison Ops,  Prev: Calling Functions,  Up: Expressions

10.3 Arithmetic Operators
=========================

The following arithmetic operators are available, and work on scalars
and matrices.

`X + Y'
     Addition.  If both operands are matrices, the number of rows and
     columns must both agree.  If one operand is a scalar, its value is
     added to all the elements of the other operand.

`X .+ Y'
     Element by element addition.  This operator is equivalent to `+'.

`X - Y'
     Subtraction.  If both operands are matrices, the number of rows and
     columns of both must agree.

`X .- Y'
     Element by element subtraction.  This operator is equivalent to
     `-'.

`X * Y'
     Matrix multiplication.  The number of columns of X must agree with
     the number of rows of Y.

`X .* Y'
     Element by element multiplication.  If both operands are matrices,
     the number of rows and columns must both agree.

`X / Y'
     Right division.  This is conceptually equivalent to the expression

          (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'
     Element by element right division.

`X \ Y'
     Left division.  This is conceptually equivalent to the expression

          inverse (x) * y

     but 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'
     Element by element left division.  Each element of Y is divided by
     each corresponding element of X.

`X ^ Y'
`X ** Y'
     Power operator.  If X and Y are both scalars, this operator
     returns X raised to the power Y.  If X is a scalar and Y is a
     square matrix, the result is computed using an eigenvalue
     expansion.  If X is a square matrix. the result is computed by
     repeated multiplication if Y is an integer, and by an eigenvalue
     expansion if Y is not an integer.  An error results if both X and
     Y are matrices.

     The implementation of this operator needs to be improved.

`X .^ Y'

`X .** Y'
     Element by element power operator.  If both operands are matrices,
     the number of rows and columns must both agree.

`-X'
     Negation.

`+X'
     Unary plus.  This operator has no effect on the operand.

`X''
     Complex conjugate transpose.  For real arguments, this operator is
     the same as the transpose operator.  For complex arguments, this
     operator is equivalent to the expression

          conj (x.')

`X.''
     Transpose.

   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.

 -- Built-in Variable: warn_divide_by_zero
     If the value of `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.


File: octave.info,  Node: Comparison Ops,  Next: Boolean Expressions,  Prev: Arithmetic Ops,  Up: Expressions

10.4 Comparison Operators
=========================

"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'
     True if X is less than Y.

`X <= Y'
     True if X is less than or equal to Y.

`X == Y'
     True if X is equal to Y.

`X >= Y'
     True if X is greater than or equal to Y.

`X > Y'
     True if X is greater than Y.

`X != Y'
`X ~= Y'
`X <> Y'
     True if X is not equal to Y.

   String comparisons may also be performed with the `strcmp' function,
not with the comparison operators listed above.  *Note Strings::.


File: octave.info,  Node: Boolean Expressions,  Next: Assignment Ops,  Prev: Comparison Ops,  Up: Expressions

10.5 Boolean Expressions
========================

* Menu:

* Element-by-element Boolean Operators::
* Short-circuit Boolean Operators::


File: octave.info,  Node: Element-by-element Boolean Operators,  Next: Short-circuit Boolean Operators,  Up: Boolean Expressions

10.5.1 Element-by-element Boolean Operators
-------------------------------------------

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'
     Elements of the result are true if both corresponding elements of
     BOOLEAN1 and BOOLEAN2 are true.

`BOOLEAN1 | BOOLEAN2'
     Elements of the result are true if either of the corresponding
     elements of BOOLEAN1 or BOOLEAN2 is true.

`! BOOLEAN'
`~ BOOLEAN'
     Each element of the result is true if the corresponding element of
     BOOLEAN is false.

   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.


File: octave.info,  Node: Short-circuit Boolean Operators,  Prev: Element-by-element Boolean Operators,  Up: Boolean Expressions

10.5.2 Short-circuit Boolean Operators
--------------------------------------

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'
     The expression BOOLEAN1 is evaluated and converted to a scalar
     using the equivalent of the operation `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'
     The expression BOOLEAN1 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.  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 `&'.


File: octave.info,  Node: Assignment Ops,  Next: Increment Ops,  Prev: Boolean Expressions,  Up: Expressions

10.6 Assignment Expressions
===========================

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 (*note
Variables::).  It can also be an element of a matrix (*note Index
Expressions::) or a list of return values (*note 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.  *Note 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, second, 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.

 -- Built-in Variable: print_rhs_assign_val
     If the value of this variable is non-zero, Octave will print the
     value of the right hand side of assignment expressions instead of
     the value of the left hand side (after the assignment).


File: octave.info,  Node: Increment Ops,  Next: Operator Precedence,  Prev: Assignment Ops,  Up: Expressions

10.7 Increment Operators
========================

_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'
     This expression increments the variable X.  The value of the
     expression is the _new_ value of X.  It is equivalent to the
     expression `X = X + 1'.

`--X'
     This expression decrements the variable X.  The value of the
     expression is the _new_ value of X.  It is equivalent to the
     expression `X = X - 1'.

`X++'
     This expression causes the variable X to be incremented.  The
     value of the expression is the _old_ value of X.

`X--'
     This expression causes the variable X to be decremented.  The
     value of the expression is the _old_ value of 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.


File: octave.info,  Node: Operator Precedence,  Prev: Increment Ops,  Up: Expressions

10.8 Operator Precedence
========================

"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'
     `='.  This operator groups right to left.

`logical "or" and "and"'
     `||', `&&'.

`element-wise "or" and "and"'
     `|', `&'.

`relational'
     `<', `<=', `==', `>=', `>', `!=', `~=', `<>'.

`colon'
     `:'.

`add, subtract'
     `+', `-'.

`multiply, divide'
     `*', `/', `\', `.\', `.*', `./'.

`transpose'
     `'', `.''

`unary plus, minus, increment, decrement, and ``not'''
     `+', `-', `++', `--', `!', `~'.

`exponentiation'
     `^', `**', `.^', `.**'.


File: octave.info,  Node: Evaluation,  Next: Statements,  Prev: Expressions,  Up: Top

11 Evaluation
*************

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.

 -- Built-in Function:  eval (TRY, CATCH)
     Parse the string TRY and evaluate it as if it were an Octave
     program.  If that fails, evaluate the string CATCH.  The string
     TRY is evaluated in the current context, so any results remain
     available after `eval' returns.

 -- Built-in Function:  feval (NAME, ...)
     Evaluate the function named NAME.  Any arguments after the first
     are passed on to the named function.  For example,

          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 *Note Predicates for Numeric
Objects::, for example, for a list of predicates for numeric objects,
and *Note Status of Variables::, for a description of the `exist'
function.


File: octave.info,  Node: Statements,  Next: Functions and Scripts,  Prev: Evaluation,  Up: Top

12 Statements
*************

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.

* Menu:

* The if Statement::
* The switch Statement::
* The while Statement::
* The do-until Statement::
* The for Statement::
* The break Statement::
* The continue Statement::
* The unwind_protect Statement::
* The try Statement::
* Continuation Lines::


File: octave.info,  Node: The if Statement,  Next: The switch Statement,  Up: Statements

12.1 The `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.  *Note
Functions and Scripts::.

 -- Built-in Variable: warn_assign_as_truth_value
     If the value of `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.


File: octave.info,  Node: The switch Statement,  Next: The while Statement,  Prev: The if Statement,  Up: Statements

12.2 The `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 <maintainers@octave.org>.  (But if you
think you've found a bug, please report it to <bug@octave.org>.

   The general form of the `switch' statement is

     switch EXPRESSION
       case LABEL
         COMMAND_LIST
       case LABEL
         COMMAND_LIST
       ...

       otherwise
         COMMAND_LIST
     endswitch

   * The identifiers `switch', `case', `otherwise', and `endswitch' are
     now keywords.

   * The LABEL may be any expression.

   * Duplicate LABEL values are not detected.  The COMMAND_LIST
     corresponding to the first match will be executed.

   * You must have at least one `case LABEL COMMAND_LIST' clause.

   * The `otherwise COMMAND_LIST' clause is optional.

   * As with all other specific `end' keywords, `endswitch' may be
     replaced by `end', but you can get better diagnostics if you use
     the specific forms.

   * Cases are exclusive, so they don't `fall through' as do the cases
     in the switch statement of the C language.

   * The COMMAND_LIST elements are not optional.  Making the list
     optional would have meant requiring a separator between the label
     and the command list.  Otherwise, things like

          switch (foo)
            case (1) -2
            ...

     would produce surprising results, as would

          switch (foo)
            case (1)
            case (2)
              doit ();
            ...

     particularly for C programmers.

   * The implementation is simple-minded and currently offers no real
     performance improvement over an equivalent `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.

 -- Built-in Variable: warn_variable_switch_label
     If the value of this variable is nonzero, Octave will print a
     warning if a switch label is not a constant or constant expression


File: octave.info,  Node: The while Statement,  Next: The do-until Statement,  Prev: The switch Statement,  Up: Statements

12.3 The `while' Statement
==========================

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

   *Note The if Statement::, for a description of the variable
`warn_assign_as_truth_value'.


File: octave.info,  Node: The do-until Statement,  Next: The for Statement,  Prev: The while Statement,  Up: Statements

12.4 The `do-until' Statement
=============================

The `do-until' statement is similar to the `while' statement, except
that it repeatedly executes a statement until a condition becomes true,
and the test of the condition is at the end of the loop, so the body of
the loop is always executed at least once.  As with the condition in an
`if' statement, the condition in a `do-until' 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 `do-until' statement is a
vector or a matrix, it is considered true only if _all_ of the elements
are non-zero.

   Octave's `do-until' statement looks like this:

     do
       BODY
     until (CONDITION)

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.

   This example creates a variable `fib' that contains the first ten
elements of the Fibonacci sequence.

     fib = ones (1, 10);
     i = 2;
     do
       i++;
       fib (i) = fib (i-1) + fib (i-2);
     until (i == 10)

   A newline is not required between the `do' keyword and the body; but
using one makes the program clearer unless the body is very simple.

   *Note The if Statement::, for a description of the variable
`warn_assign_as_truth_value'.


File: octave.info,  Node: The for Statement,  Next: The break Statement,  Prev: The do-until Statement,  Up: Statements

12.5 The `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.  *Note 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.

* Menu:

* Looping Over Structure Elements::


File: octave.info,  Node: Looping Over Structure Elements,  Up: The for Statement

12.5.1 Looping Over Structure Elements
--------------------------------------

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.


File: octave.info,  Node: The break Statement,  Next: The continue Statement,  Prev: The for Statement,  Up: Statements

12.6 The `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


File: octave.info,  Node: The continue Statement,  Next: The unwind_protect Statement,  Prev: The break Statement,  Up: Statements

12.7 The `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


File: octave.info,  Node: The unwind_protect Statement,  Next: The try Statement,  Prev: The continue Statement,  Up: Statements

12.8 The `unwind_protect' Statement
===================================

Octave supports a limited form of exception handling modelled after the
unwind-protect form of Lisp.

   The general form of an `unwind_protect' block looks like this:

     unwind_protect
       BODY
     unwind_protect_cleanup
       CLEANUP
     end_unwind_protect

Where BODY and CLEANUP are both optional and may contain any Octave
expressions or commands.  The statements in CLEANUP are guaranteed to
be executed regardless of how control exits BODY.

   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 `warn_fortran_indexing'
even if an error occurs while performing the indexing operation.

     save_warn_fortran_indexing = warn_fortran_indexing;
     unwind_protect
       warn_fortran_indexing = 1;
       elt = a (idx)
     unwind_protect_cleanup
       warn_fortran_indexing = save_warn_fortran_indexing;
     end_unwind_protect

   Without `unwind_protect', the value of WARN_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.


File: octave.info,  Node: The try Statement,  Next: Continuation Lines,  Prev: The unwind_protect Statement,  Up: Statements

12.9 The `try' Statement
========================

In 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 use
the function `lasterr' to access the text of the message that would
have been printed.  This is the same as `eval (TRY, CATCH)' but it is
more efficient since the commands do not need to be parsed each time
the TRY and CATCH statements are evaluated.  *Note Error Handling::,
for more information about the `lasterr' function.

   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.


File: octave.info,  Node: Continuation Lines,  Prev: The try Statement,  Up: Statements

12.10 Continuation Lines
========================

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)
       seuss (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.


File: octave.info,  Node: Functions and Scripts,  Next: Error Handling,  Prev: Statements,  Up: Top

13 Functions and Script Files
*****************************

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.

* Menu:

* Defining Functions::
* Multiple Return Values::
* Variable-length Argument Lists::
* Variable-length Return Lists::
* Returning From a Function::
* Function Files::
* Script Files::
* Dynamically Linked Functions::
* Function Handles and Inline::
* Organization of Functions::


File: octave.info,  Node: Defining Functions,  Next: Multiple Return Values,  Up: Functions and Scripts

13.1 Defining 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 (*note Input and Output::) simply tells
Octave to print the string `"\a"'.  The special character `\a' stands
for the alert character (ASCII 7).  *Note 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.
*Note 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 (isvector (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 (isvector (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 (isvector (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.

 -- Built-in Function:  nargin ()
 -- Built-in Function:  nargin (FCN_NAME)
     Within a function, return the number of arguments passed to the
     function.  At the top level, return the number of command line
     arguments passed to Octave.  If called with the optional argument
     FCN_NAME, return the maximum number of arguments the named
     function can accept, or -1 if the function accepts a variable
     number of arguments.

 -- Built-in Variable: silent_functions
     If the value of `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'.

 -- Built-in Variable: warn_missing_semicolon
     If the value of this variable is nonzero, Octave will warn when
     statements in function definitions don't end in semicolons.  The
     default value is 0.


File: octave.info,  Node: Multiple Return Values,  Next: Variable-length Argument Lists,  Prev: Defining Functions,  Up: Functions and Scripts

13.2 Multiple Return Values
===========================

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

along with a warning if the value of the built-in variable
`warn_undefined_return_values' is nonzero.

 -- Built-in Function:  nargout ()
 -- Built-in Function:  nargout (FCN_NAME)
     Within a function, return the number of values the caller expects
     to receive.  If called with the optional argument FCN_NAME, return
     the maximum number of values the named function can produce, or -1
     if the function can produce a variable number of values.

     For example,

          f ()

     will cause `nargout' to return 0 inside the function `f' and

          [s, t] = f ()

     will cause `nargout' to return 2 inside the function `f'.

     At the top level, `nargout' is undefined.

 -- Built-in Variable: warn_undefined_return_values
     If the value of `warn_undefined_return_values' is nonzero, print a
     warning if a function does not define all the values in the return
     list which are expected.  The default value is 1.

 -- Function File:  nargchk (NARGIN_MIN, NARGIN_MAX, N)
     If N is in the range NARGIN_MIN through NARGIN_MAX inclusive,
     return the empty matrix.  Otherwise, return a message indicating
     whether N is too large or too small.

     This is useful for checking to see that the number of arguments
     supplied to a function is within an acceptable range.


File: octave.info,  Node: Variable-length Argument Lists,  Next: Variable-length Return Lists,  Prev: Multiple Return Values,  Up: Functions and Scripts

13.3 Variable-length Argument Lists
===================================


File: octave.info,  Node: Variable-length Return Lists,  Next: Returning From a Function,  Prev: Variable-length Argument Lists,  Up: Functions and Scripts

13.4 Variable-length Return Lists
=================================


File: octave.info,  Node: Returning From a Function,  Next: Function Files,  Prev: Variable-length Return Lists,  Up: Functions and Scripts

13.5 Returning From a Function
==============================

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.

 -- Keyword: return
     When Octave encounters the keyword `return' inside a function or
     script, it returns control to the caller immediately. At the top
     level, the return statement is ignored.  A `return' statement is
     assumed at the end of every function definition.


File: octave.info,  Node: Function Files,  Next: Script Files,  Prev: Returning From a Function,  Up: Functions and Scripts

13.6 Function Files
===================

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.(1)  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.  *Note 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.

 -- Built-in Variable: DEFAULT_LOADPATH
     A colon separated list of directories in which to search for
     function files.  The value of this variable is automatically
     substituted for leading, trailing, or doubled colons that appear
     in the built-in variable `LOADPATH'.

 -- Built-in Variable: LOADPATH
     A colon separated list of directories in which to search for
     function files.  *Note Functions and Scripts::.  The value of
     `LOADPATH' overrides the environment variable `OCTAVE_PATH'.
     *Note Installation::.

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

     *Note Organization of Functions::, for a description of the
     function file directories that are distributed with Octave.

 -- Built-in Function:  rehash ()
     Reinitialize Octave's `LOADPATH' directory cache.

 -- Built-in Function:  file_in_loadpath (FILE)
 -- Built-in Function:  file_in_loadpath (FILE, "all")
     Return the absolute name name of FILE if it can be found in the
     list of directories specified by `LOADPATH'.  If no file is found,
     return an empty matrix.

     If the first argument is a cell array of of strings, search each
     directory of the loadpath for element of the cell array and return
     the first that matches.

     If the second optional argument `"all"' is supplied, return a cell
     array containing the list of all files that have the same name in
     the path.  If no files are found, return an empty cell array.

 -- Built-in Variable: ignore_function_time_stamp
     This variable can be used to prevent Octave from making the system
     call `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"'.

 -- Built-in Variable: warn_function_name_clash
     If the value of `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.

 -- Built-in Variable: warn_future_time_stamp
     If the value of this variable is nonzero, Octave will print a
     warning if it finds a function file with a time stamp that is in
     the future.

   ---------- Footnotes ----------

   (1) The `.m' suffix was chosen for compatibility with MATLAB.


File: octave.info,  Node: Script Files,  Next: Dynamically Linked Functions,  Prev: Function Files,  Up: Functions and Scripts

13.7 Script Files
=================

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.

 -- Built-in Function:  source (FILE)
     Parse and execute the contents of FILE.  This is equivalent to
     executing commands from a script file, but without requiring the
     file to be named `FILE.m'.


File: octave.info,  Node: Dynamically Linked Functions,  Next: Function Handles and Inline,  Prev: Script Files,  Up: Functions and Scripts

13.8 Dynamically Linked Functions
=================================

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 *Note 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 in order to avoid the
warning from gcc about an unused function parameter.

   The next line,

     ColumnVector dx (3);

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 vector from the first input argument.  The `vector_value'
method is used so that the user of the function can pass either a row
or column vector.  The `ColumnVector' constructor is needed because the
ODE class requires a column vector.  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

     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 *Note Ordinary Differential Equations::, in about 1.4 seconds
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 a dynamically
linked function when the file that defines it is more recent than the
last time that the function was loaded.  If more than one function is
defined in a single `.oct' file, reloading the file may force other
functions to be cleared and reloaded.  If all the functions loaded from
a given `.oct' file are cleared, Octave will automatically unload the
`.oct' file.

 -- Built-in Variable: warn_reload_forces_clear
     If several functions have been loaded from the same file, Octave
     must clear all the functions before any one of them can be
     reloaded.  If `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.

 -- Built-in Variable: variables_can_hide_functions
     If the value of this variable is nonzero, assignments to variables
     may hide previously defined functions of the same name.  A
     negative value will cause Octave to print a warning, but allow the
     operation.

   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.


File: octave.info,  Node: Function Handles and Inline,  Next: Organization of Functions,  Prev: Dynamically Linked Functions,  Up: Functions and Scripts

13.9 Function Handles and Inline
================================

This is a place holder for the description of function handles and
inline functions.

* Menu:

* Function Handles::
* Inline Functions::


File: octave.info,  Node: Function Handles,  Next: Inline Functions,  Up: Function Handles and Inline

13.9.1 Function Handles
-----------------------

 -- Built-in Function:  functions (FCN_HANDLE)
     Return a struct containing information about the function handle
     FCN_HANDLE.

 -- Built-in Function:  func2str (FCN_HANDLE)
     Return a string containing the name of the function referenced by
     the function handle FCN_HANDLE.

 -- Built-in Function:  str2func (FCN_NAME)
     Return a function handle constructed from the string FCN_NAME.


File: octave.info,  Node: Inline Functions,  Prev: Function Handles,  Up: Function Handles and Inline

13.9.2 Inline Functions
-----------------------

 -- Built-in Function:  inline (STR)
 -- Built-in Function:  inline (STR, ARG1, ...)
 -- Built-in Function:  inline (STR, N)
     Create an inline function from the character string STR.  If
     called with a single argument, the arguments of the generated
     function are extracted from the function itself. The generated
     function arguments will then be in alphabetical order. It should
     be noted that i, and j are ignored as arguments due to the
     ambiguity between their use as a variable or their use as an
     inbuilt constant. All arguments followed by a parentheses are
     considered to be functions.

     If the second and subsequent arguments are character strings, they
     are the names of the arguments of the function.

     If the second argument is an integer N, the arguments are `"x"',
     `"P1"', ..., `"PN"'.

 -- Built-in Function:  argnames (FUN)
     Return a cell array of character strings containing the names of
     the arguments of the inline function FUN.

 -- Built-in Function:  formula (FUN)
     Return a character string representing the inline function FUN.
     Note that `char (FUN)' is equivalent to `formula (FUN)'.

 -- Built-in Function:  argnames (FUN)
     Create a vectorized version of the inline function FUN by
     replacing all occurrences of `*', `/', etc., with `.*', `./', etc.


File: octave.info,  Node: Organization of Functions,  Prev: Function Handles and Inline,  Up: Functions and Scripts

13.10 Organization of Functions Distributed with 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.

`audio'
     Functions for playing and recording sounds.

`control'
     Functions for design and simulation of automatic control systems.

`elfun'
     Elementary functions.

`general'
     Miscellaneous matrix manipulations, like `flipud', `rot90', and
     `triu', as well as other basic functions, like `ismatrix',
     `nargchk', etc.

`image'
     Image processing tools.  These functions require the X Window
     System.

`io'
     Input-ouput functions.

`linear-algebra'
     Functions for linear algebra.

`miscellaneous'
     Functions that don't really belong anywhere else.

`plot'
     A set of functions that implement the MATLAB-like plotting
     functions.

`polynomial'
     Functions for manipulating polynomials.

`set'
     Functions for creating and manipulating sets of unique values.

`signal'
     Functions for signal processing applications.

`specfun'
     Special functions.

`special-matrix'
     Functions that create special matrix forms.

`startup'
     Octave's system-wide startup file.

`statistics'
     Statistical functions.

`strings'
     Miscellaneous string-handling functions.

`time'
     Functions related to time keeping.


File: octave.info,  Node: Error Handling,  Next: Debugging,  Prev: Functions and Scripts,  Up: Top

14 Error Handling
*****************

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.

 -- Built-in Function:  error (TEMPLATE, ...)
     The `error' function formats the optional arguments under the
     control of the template string TEMPLATE using the same rules as
     the `printf' family of functions (*note 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

 -- Built-in Variable: beep_on_error
     If the value of `beep_on_error' is nonzero, Octave will try to
     ring your terminal's bell before printing an error message.  The
     default value is 0.

 -- Built-in Function:  warning (MSG)
     Print a warning message MSG prefixed by the string `warning: '.
     After printing the warning message, Octave will continue to execute
     commands.  You should use this function when you want to notify
     the user of an unusual condition, but only when it makes sense for
     your program to go on.

 -- Built-in Function:  usage (MSG)
     Print the message MSG, prefixed by the string `usage: ', and set
     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.

     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.

 -- Built-in Function:  lasterr ()
 -- Built-in Function:  lasterr (MSG)
     Without any arguments, return the last error message.  With one
     argument, set the last error message to MSG.

 -- Built-in Function:  lastwarn ()
 -- Built-in Function:  lastwarn (MSG)
     Without any arguments, return the last warning message.  With one
     argument, set the last warning message to MSG.

   The following pair of functions are of limited usefulness, and may be
removed from future versions of Octave.

 -- Function File:  perror (NAME, NUM)
     Print the error message for function NAME corresponding to the
     error number NUM.  This function is intended to be used to print
     useful error messages for those functions that return numeric error
     codes.

 -- Function File:  strerror (NAME, NUM)
     Return the text of an error message for function NAME
     corresponding to the error number NUM.  This function is intended
     to be used to print useful error messages for those functions that
     return numeric error codes.


File: octave.info,  Node: Debugging,  Next: Input and Output,  Prev: Error Handling,  Up: Top

15 Debugging
************

 -- Loadable Function: rline = dbstop (func, line)
     Set a breakpoint in a function
    `func'
          String representing the function name.  When already in debug
          mode this should be left out and only the line should be
          given.

    `line'
          Line you would like the breakpoint to be set on

     The rline returned is the real line that the breakpoint was set at.


 -- Loadable Function:  dbclear (func, line)
     Delete a breakpoint in a function
    `func'
          String representing the function name.  When already in debug
          mode this should be left out and only the line should be
          given.

    `line'
          Line where you would like to remove the the breakpoint
     No checking is done to make sure that the line you requested is
     really a breakpoint.   If you get the wrong line nothing will
     happen.

 -- Loadable Function: lst = dbstatus ([func])
     Return a vector containing the lines on which a function has
     breakpoints set.
    `func'
          String representing the function name.  When already in debug
          mode this should be left out.

 -- Loadable Function:  dbwhere ()
     Show where we are in the code

 -- Loadable Function:  dbtype ()
     List script file with line numbers.

 -- Built-in Variable: debug_on_interrupt
     If `debug_on_interrupt' is nonzero, Octave will try to enter
     debugging mode when it receives an interrupt signal (typically
     generated with `C-c').  If a second interrupt signal is received
     before reaching the debugging mode, a normal interrupt will occur.
     The default value is 0.

 -- Built-in Variable: debug_on_warning
     If the value of `debug_on_warning' is nonzero, Octave will try to
     enter the debugger when a warning is encountered.  The default
     value is 0.

 -- Built-in Variable: debug_on_error
     If the value of `debug_on_error' is nonzero, Octave will try to
     enter the debugger when an error is encountered.  This will also
     inhibit printing of the normal traceback message (you will only see
     the top-level error message).  The default value is 0.


File: octave.info,  Node: Input and Output,  Next: Plotting,  Prev: Debugging,  Up: Top

16 Input and Output
*******************

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.

 -- Command: more
 -- Command: more on
 -- Command: more off
     Turn output pagination on or off.  Without an argument, `more'
     toggles the current state.

 -- Built-in Variable: PAGER
     The default value is normally `"less"', `"more"', or `"pg"',
     depending on what programs are installed on your system.  *Note
     Installation::.

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

 -- Built-in Variable: page_screen_output
     If the value of `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 *Note Installation::) are also
     capable of moving backward on the output.  The default value is 1.

 -- Built-in Variable: page_output_immediately
     If the value of `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.

 -- Built-in Function:  fflush (FID)
     Flush output to FID.  This is useful for ensuring that all pending
     output makes it to the screen before some other event occurs.  For
     example, it is always a good idea to flush the standard output
     stream before calling `input'.

     `fflush' returns 0 on success and an OS dependent error value (-1
     on unix) on error.

* Menu:

* Basic Input and Output::
* C-Style I/O Functions::


File: octave.info,  Node: Basic Input and Output,  Next: C-Style I/O Functions,  Up: Input and Output

16.1 Basic Input and Output
===========================

* Menu:

* Terminal Output::
* Terminal Input::
* Simple File I/O::


File: octave.info,  Node: Terminal Output,  Next: Terminal Input,  Up: Basic Input and Output

16.1.1 Terminal Output
----------------------

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.

 -- Built-in Variable: ans
     This variable holds the most recently computed result that was not
     explicitly assigned to a variable.  For example, after the
     expression

          3^2 + 4^2

     is evaluated, the value of `ans' is 25.

 -- Built-in Function:  fdisp (FID, X)
     Display the value of X on the stream FID.  For example,

          fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi)

               -| the value of pi is:
               -| 3.1416

     Note that the output from `fdisp' always ends with a newline.

 -- Built-in Function:  disp (X)
     Display the value of X.  For example,

          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.

     If an output value is requested, `disp' prints nothing and returns
     the formatted output in a string.

 -- Command: format options
     Control the format of the output produced by `disp' and Octave's
     normal echoing mechanism.  Valid options are listed in the
     following table.

    `short'
          Octave will try to print numbers with at least 5 significant
          figures within a field that is a maximum of 10 characters
          wide (not counting additional spacing that is added between
          columns of a matrix).

          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.

    `long'
          Octave will try to print numbers with at least 15 significant
          figures within a field that is a maximum of 20 characters
          wide (not counting additional spacing that is added between
          columns of a matrix).

          As will the `short' format, Octave will switch to an `e'
          format if it 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.

    `long e'
    `short e'
          The same as `format long' or `format short' but always display
          output with an `e' format.  For example, with the `short e'
          format, `pi' is displayed as `3.14e+00'.

    `long E'
    `short E'
          The same as `format long e' or `format short e' but always
          display output with an uppercase `E' format.  For example,
          with the `long E' format, `pi' is displayed as
          `3.14159265358979E+00'.

    `long g'
    `short g'
          Choose between normal `long' (or `short') and and `long e'
          (or `short e') formats based on the magnitude of the number.
          For example, with the `short g' format, `pi .^ [2; 4; 8; 16;
          32]' is displayed as

               ans =

                     3.1416
                     9.8696
                     97.409
                     9488.5
                 9.0032e+07
                 8.1058e+15

    `long G'
    `short G'
          The same as `format long g' or `format short g' but use an
          uppercase `E' format.  For example, with the `short G' format,
          `pi .^ [2; 4; 8; 16; 32]' is displayed as

               ans =

                     3.1416
                     9.8696
                     97.409
                     9488.5
                 9.0032E+07
                 8.1058E+15

    `free'
    `none'
          Print output in free format, without trying to line up
          columns of matrices on the decimal point.  This also causes
          complex numbers to be formatted like this `(0.604194,
          0.607088)' instead of like this `0.60419 + 0.60709i'.

    `bank'
          Print in a fixed format with two places to the right of the
          decimal point.

    `+'
    `+ CHARS'
    `plus'
    `plus CHARS'
          Print a `+' symbol for nonzero matrix elements and a space
          for zero matrix elements.  This format can be very useful for
          examining the structure of a large matrix.

          The optional argument CHARS specifies a list of 3 characters
          to use for printing values greater than zero, less than zero
          and equal to zero.  For example, with the `+ "+-."' format,
          `[1, 0, -1; -1, 0, 1]' is displayed as

               ans =

               +.-
               -.+

    `native-hex'
          Print the hexadecimal representation numbers as they are
          stored in memory.  For example, on a workstation which stores
          8 byte real values in IEEE format with the least significant
          byte first, the value of `pi' when printed in `hex' format is
          `400921fb54442d18'.  This format only works for numeric
          values.

    `hex'
          The same as `native-hex', but always print the most
          significant byte first.

    `native-bit'
          Print the bit representation of numbers as stored in memory.
          For example, the value of `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.

    `bit'
          The same as `native-bit', but always print the most
          significant bits first.

    `compact'
          Remove extra blank space around column number labels.

    `loose'
          Insert blank lines above and below column number labels (this
          is the default).

     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.

 -- Built-in Variable: print_answer_id_name
     If the value of `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.


File: octave.info,  Node: Terminal Input,  Next: Simple File I/O,  Prev: Terminal Output,  Up: Basic Input and Output

16.1.2 Terminal Input
---------------------

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.

 -- Built-in Function:  input (PROMPT)
 -- Built-in Function:  input (PROMPT, "s")
     Print a prompt and wait for user input.  For example,

          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.  *Note Input and Output::.

 -- Function File:  menu (TITLE, OPT1, ...)
     Print a title string followed by a series of options.  Each option
     will be printed along with a number.  The return value is the
     number of the option selected by the user.  This function is
     useful for interactive programs.  There is no limit to the number
     of options that may be passed in, but it may be confusing to
     present more than will fit easily on one screen.

 -- Built-in Function:  keyboard (PROMPT)
     This function is normally used for simple debugging.  When the
     `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.

 -- Built-in Function:  kbhit ()
     Read a single keystroke from the keyboard. If called with one
     argument, don't wait for a keypress.  For example,

          x = kbhit ();

     will set X to the next character typed at the keyboard as soon as
     it is typed.

          x = kbhit (1);

     identical to the above example, but don't wait for a keypress,
     returning the empty string if no key is available.


File: octave.info,  Node: Simple File I/O,  Prev: Terminal Input,  Up: Basic Input and Output

16.1.3 Simple File I/O
----------------------

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 cannot yet save or load structure variables or any
user-defined types.

 -- Command: save options file v1 v2 ...
     Save the named variables V1, V2, ... in the file FILE.  The
     special filename `-' can be used to write the output to your
     terminal.  If no variable names are listed, Octave saves all the
     variables in the current scope.  Valid options for the `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'
          Save the data in Octave's text data format.

          *WARNING: the meaning of this option will change in a future
          version of Octave to be compatible with MATLAB.  To keep the
          meaning of your code the same across this change, use the
          `-text' option instead.*

    `-binary'
          Save the data in Octave's binary data format.

    `-float-binary'
          Save the data in Octave's binary data format but only using
          single precision.  You should use this format only if you
          know that all the values to be saved can be represented in
          single precision.

    `-mat'
    `-mat-binary'
          Save the data in MATLAB's binary data format.

    `-V4'
    `-v4'
    `-4'
    `-mat4-binary'
          Save the data in the binary format written by MATLAB version
          4.

    `-hdf5'
          Save the data in HDF5 format.  (HDF5 is a free, portable
          binary format developed by the National Center for
          Supercomputing Applications at the University of Illinois.)

          HDF5 load and save are not available, as this Octave
          executable was not linked with the HDF5 library.

    `-float-hdf5'
          Save the data in HDF5 format but only using single precision.
          You should use this format only if you know that all the
          values to be saved can be represented in single precision.

    `-save-builtins'
          Force Octave to save the values of built-in variables too.
          By default, Octave does not save built-in variables.

     The list of variables to save may include wildcard patterns
     containing the following special characters:
    `?'
          Match any single character.

    `*'
          Match zero or more characters.

    `[ LIST ]'
          Match the list of characters specified by LIST.  If the first
          character is `!' 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.

    `-text'
          Save the data in Octave's text data format.

     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 three variables that modify the behavior of `save' and
three more that control whether variables are saved when Octave exits
unexpectedly.

 -- Built-in Variable: crash_dumps_octave_core
     If this variable is set to a nonzero value, Octave tries to save
     all current variables the the file "octave-core" if it crashes or
     receives a hangup, terminate or similar signal.  The default value
     is 1.


 -- Built-in Variable: sighup_dumps_octave_core
     If this variable is set to a nonzero value and
     `crash_dumps_octave_core' is also nonzero, Octave tries to save all
     current variables the the file "octave-core" if it receives a
     hangup signal.  The default value is 1.

 -- Built-in Variable: sigterm_dumps_octave_core
     If this variable is set to a nonzero value and
     `crash_dumps_octave_core' is also nonzero, Octave tries to save all
     current variables the the file "octave-core" if it receives a
     terminate signal.  The default value is 1.

 -- Built-in Variable: default_save_format
     This variable specifies the default format for the `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.

 -- Built-in Variable: save_precision
     This variable specifies the number of digits to keep when saving
     data in text format.  The default value is 17.

 -- Built-in Variable: save_header_format_string
     This variable specifies the the format string for the comment line
     that is written at the beginning of text-format data files saved by
     Octave.  The format string is passed to `strftime' and should
     begin with the character `#' and contain no newline characters.
     If the value of `save_header_format_string' is the empty string,
     the header comment is omitted from text-format data files.  The
     default value is

          "# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"


 -- Command: load options file v1 v2 ...
     Load the named variables from the file FILE.  As with `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

     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.

     If invoked with a single output argument, Octave returns data
     instead of inserting variables in the symbol table.  If the data
     file contains only numbers (TAB- or space-delimited columns), a
     matrix of values is returned.  Otherwise, `load' returns a
     structure with members  corresponding to the names of the
     variables in the file.

     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'
          The `-force' option is accepted but ignored for backward
          compatiability. Octave now overwrites variables currently in
          memeory with the same name as those found in the file.

    `-ascii'
          Force Octave to assume the file is in Octave's text format.

          *WARNING: the meaning of this option will change in a future
          version of Octave to be compatible with MATLAB.  To keep the
          meaning of your code the same across this change, use the
          `-text' option instead.*

    `-binary'
          Force Octave to assume the file is in Octave's binary format.

    `-mat'
    `-mat-binary'
          Force Octave to assume the file is in MATLAB's version 6
          binary format.

    `-V4'
    `-v4'
    `-4'
    `-mat4-binary'
          Force Octave to assume the file is in the binary format
          written by MATLAB version 4.

    `-hdf5'
          Force Octave to assume the file is in HDF5 format.  (HDF5 is
          a free, portable binary format developed by the National
          Center for Supercomputing Applications at the University of
          Illinois.)  Note that Octave can read HDF5 files not created
          by itself, but may skip some datasets in formats that it
          cannot support.

          HDF5 load and save are not available, as this Octave
          executable was not linked with the HDF5 library.

    `-import'
          The `-import' is accepted but ignored for backward
          compatiability.  Octave can now support multi-dimensional HDF
          data and automatically modifies variable names if they are
          invalid Octave identifiers.

    `-text'
          Force Octave to assume the file is in Octave's text format.


File: octave.info,  Node: C-Style I/O Functions,  Prev: Basic Input and Output,  Up: Input and Output

16.2 C-Style I/O Functions
==========================

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.

 -- Built-in Variable: stdin
     The standard input stream (file id 0).  When Octave is used
     interactively, this is filtered through the command line editing
     functions.

 -- Built-in Variable: stdout
     The standard output stream (file id 1).  Data written to the
     standard output is normally filtered through the pager.

 -- Built-in Variable: stderr
     The standard error stream (file id 2).  Even if paging is turned
     on, the standard error is not sent to the pager.  It is useful for
     error messages and prompts.

* Menu:

* Opening and Closing Files::
* Simple Output::
* Line-Oriented Input::
* Formatted Output::
* Output Conversion for Matrices::
* Output Conversion Syntax::
* Table of Output Conversions::
* Integer Conversions::
* Floating-Point Conversions::  Other Output Conversions::
* Other Output Conversions::
* Formatted Input::
* Input Conversion Syntax::
* Table of Input Conversions::
* Numeric Input Conversions::
* String Input Conversions::
* Binary I/O::
* Temporary Files::
* EOF and Errors::
* File Positioning::


File: octave.info,  Node: Opening and Closing Files,  Next: Simple Output,  Up: C-Style I/O Functions

16.2.1 Opening and Closing Files
--------------------------------

 -- Built-in Function: [FID, MSG] = fopen (NAME, MODE, ARCH)
 -- Built-in Function: FID_LIST = fopen ("all")
 -- Built-in Function: FILE = fopen (FID)
     The first form of the `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

    `r'
          Open a file for reading.

    `w'
          Open a file for writing.  The previous contents are discared.

    `a'
          Open or create a file for writing at the end of the file.

    `r+'
          Open an existing file for reading and writing.

    `w+'
          Open a file for reading or writing.  The previous contents are
          discarded.

    `a+'
          Open or create a file for reading or writing at the end of the
          file.

     Append a "t" to the mode string to open the file in text mode or a
     "b" to open in binary mode.  On Windows and Macintosh systems, text
     mode reading and writing automatically converts linefeeds to the
     appropriate line end character for the system (carriage-return
     linefeed on Windows, carriage-returnn on Macintosh).  The default
     if no mode is specified is binary mode.

     The parameter ARCH is a string specifying the default data format
     for the file.  Valid values for ARCH are:

          `native' The format of the current machine (this is the
          default).

          `ieee-be' IEEE big endian format.

          `ieee-le' IEEE little endian format.

          `vaxd' VAX D floating format.

          `vaxg' VAX G floating format.

          `cray' Cray floating format.

     however, conversions are currently only supported for `native'
     `ieee-be', and `ieee-le' formats.

 -- Built-in Function:  fclose (FID)
     Closes the specified file.  If successful, `fclose' returns 0,
     otherwise, it returns -1.


File: octave.info,  Node: Simple Output,  Next: Line-Oriented Input,  Prev: Opening and Closing Files,  Up: C-Style I/O Functions

16.2.2 Simple Output
--------------------

 -- Built-in Function:  fputs (FID, STRING)
     Write a string to a file with no formatting.

     Return a non-negative number on success and EOF on error.

 -- Built-in Function:  puts (STRING)
     Write a string to the standard output with no formatting.

     Return a non-negative number on success and EOF on error.


File: octave.info,  Node: Line-Oriented Input,  Next: Formatted Output,  Prev: Simple Output,  Up: C-Style I/O Functions

16.2.3 Line-Oriented Input
--------------------------

 -- Built-in Function:  fgetl (FID, LEN)
     Read characters from a file, stopping after a newline, or EOF, or
     LEN characters have been read.  The characters read, excluding the
     possible trailing newline, are returned as a string.

     If LEN is omitted, `fgetl' reads until the next newline character.

     If there are no more characters to read, `fgetl' returns -1.

 -- Built-in Function:  fgets (FID, LEN)
     Read characters from a file, stopping after a newline, or EOF, or
     LEN characters have been read.  The characters read, including the
     possible trailing newline, are returned as a string.

     If LEN is omitted, `fgets' reads until the next newline character.

     If there are no more characters to read, `fgets' returns -1.


File: octave.info,  Node: Formatted Output,  Next: Output Conversion for Matrices,  Prev: Line-Oriented Input,  Up: C-Style I/O Functions

16.2.4 Formatted Output
-----------------------

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.

 -- Built-in Function:  printf (TEMPLATE, ...)
     Print optional arguments under the control of the template string
     TEMPLATE to the stream `stdout'.

     Return the number of characters printed.

 -- Built-in Function:  fprintf (FID, TEMPLATE, ...)
     This function is just like `printf', except that the output is
     written to the stream FID instead of `stdout'.

 -- Built-in Function:  sprintf (TEMPLATE, ...)
     This is like `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.


File: octave.info,  Node: Output Conversion for Matrices,  Next: Output Conversion Syntax,  Prev: Formatted Output,  Up: C-Style I/O Functions

16.2.5 Output Conversion for Matrices
-------------------------------------

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.


File: octave.info,  Node: Output Conversion Syntax,  Next: Table of Output Conversions,  Prev: Output Conversion for Matrices,  Up: C-Style I/O Functions

16.2.6 Output Conversion Syntax
-------------------------------

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:

   * Zero or more "flag characters" that modify the normal behavior of
     the conversion specification.  

   * An optional decimal integer specifying the "minimum field width".
     If the normal conversion produces fewer characters than this, the
     field is padded with spaces to the specified width.  This is a
     _minimum_ value; if the normal conversion produces more characters
     than this, the field is _not_ truncated.  Normally, the output is
     right-justified within the field.  

     You can also specify a field width of `*'.  This means that the
     next argument in the argument list (before the actual value to be
     printed) is used as the field width.  The value is rounded to the
     nearest integer.  If the value is negative, this means to set the
     `-' flag (see below) and to use the absolute value as the field
     width.

   * An optional "precision" to specify the number of digits to be
     written for the numeric conversions.  If the precision is
     specified, it consists of a period (`.') followed optionally by a
     decimal integer (which defaults to zero if omitted).  

     You can also specify a precision of `*'.  This means that the next
     argument in the argument list (before the actual value to be
     printed) is used as the precision.  The value must be an integer,
     and is ignored if it is negative.

   * An optional "type modifier character".  This character is ignored
     by Octave's `printf' function, but is recognized to provide
     compatibility with the C language `printf'.

   * A character that specifies the conversion to be applied.

   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.


File: octave.info,  Node: Table of Output Conversions,  Next: Integer Conversions,  Prev: Output Conversion Syntax,  Up: C-Style I/O Functions

16.2.7 Table of Output Conversions
----------------------------------

Here is a table summarizing what all the different conversions do:

`%d', `%i'
     Print an integer as a signed decimal number.  *Note Integer
     Conversions::, for details.  `%d' and `%i' are synonymous for
     output, but are different when used with `scanf' for input (*note
     Table of Input Conversions::).

`%o'
     Print an integer as an unsigned octal number.  *Note Integer
     Conversions::, for details.

`%u'
     Print an integer as an unsigned decimal number.  *Note Integer
     Conversions::, for details.

`%x', `%X'
     Print an integer as an unsigned hexadecimal number.  `%x' uses
     lower-case letters and `%X' uses upper-case.  *Note Integer
     Conversions::, for details.

`%f'
     Print a floating-point number in normal (fixed-point) notation.
     *Note Floating-Point Conversions::, for details.

`%e', `%E'
     Print a floating-point number in exponential notation.  `%e' uses
     lower-case letters and `%E' uses upper-case.  *Note Floating-Point
     Conversions::, for details.

`%g', `%G'
     Print a floating-point number in either normal (fixed-point) or
     exponential notation, whichever is more appropriate for its
     magnitude.  `%g' uses lower-case letters and `%G' uses upper-case.
     *Note Floating-Point Conversions::, for details.

`%c'
     Print a single character.  *Note Other Output Conversions::.

`%s'
     Print a string.  *Note Other Output Conversions::.

`%%'
     Print a literal `%' character.  *Note Other Output 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.


File: octave.info,  Node: Integer Conversions,  Next: Floating-Point Conversions,  Prev: Table of Output Conversions,  Up: C-Style I/O Functions

16.2.8 Integer Conversions
--------------------------

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:

`-'
     Left-justify the result in the field (instead of the normal
     right-justification).

`+'
     For the signed `%d' and `%i' conversions, print a plus sign if the
     value is positive.

` '
     For the signed `%d' and `%i' conversions, if the result doesn't
     start with a plus or minus sign, prefix it with a space character
     instead.  Since the `+' flag ensures that the result includes a
     sign, this flag is ignored if you supply both of them.

`#'
     For the `%o' conversion, this forces the leading digit to be `0',
     as if by increasing the precision.  For `%x' or `%X', this
     prefixes a leading `0x' or `0X' (respectively) to the result.
     This doesn't do anything useful for the `%d', `%i', or `%u'
     conversions.

`0'
     Pad the field with zeros instead of spaces.  The zeros are placed
     after any indication of sign or base.  This flag is ignored if the
     `-' flag is also specified, or if a precision is specified.

   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.


File: octave.info,  Node: Floating-Point Conversions,  Next: Other Output Conversions,  Prev: Integer Conversions,  Up: C-Style I/O Functions

16.2.9 Floating-Point Conversions
---------------------------------

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`.'DDD`e'[`+'|`-']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:

`-'
     Left-justify the result in the field.  Normally the result is
     right-justified.

`+'
     Always include a plus or minus sign in the result.

` '
     If the result doesn't start with a plus or minus sign, prefix it
     with a space instead.  Since the `+' flag ensures that the result
     includes a sign, this flag is ignored if you supply both of them.

`#'
     Specifies that the result should always include a decimal point,
     even if no digits follow it.  For the `%g' and `%G' conversions,
     this also forces trailing zeros after the decimal point to be left
     in place where they would otherwise be removed.

`0'
     Pad the field with zeros instead of spaces; the zeros are placed
     after any sign.  This flag is ignored if the `-' flag is also
     specified.

   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.


File: octave.info,  Node: Other Output Conversions,  Next: Formatted Input,  Prev: Floating-Point Conversions,  Up: C-Style I/O Functions

16.2.10 Other Output Conversions
--------------------------------

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


File: octave.info,  Node: Formatted Input,  Next: Input Conversion Syntax,  Prev: Other Output Conversions,  Up: C-Style I/O Functions

16.2.11 Formatted Input
-----------------------

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

 -- Built-in Function: [VAL, COUNT] = fscanf (FID, TEMPLATE, SIZE)
 -- Built-in Function: [V1, V2, ..., COUNT] =  fscanf (FID, TEMPLATE,
          "C")
     In the first form, read from FID according to TEMPLATE, returning
     the result in the matrix VAL.

     The optional argument SIZE specifies the amount of data to read
     and may be one of

    `Inf'
          Read as much as possible, returning a column vector.

    `NR'
          Read up to NR elements, returning a column vector.

    `[NR, Inf]'
          Read as much as possible, 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.

    `[NR, NC]'
          Read up to `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.  The number of successful
     conversions is returned in COUNT

 -- Built-in Function: [VAL, COUNT] = sscanf (STRING, TEMPLATE, SIZE)
 -- Built-in Function: [V1, V2, ..., COUNT] =  sscanf (STRING,
          TEMPLATE, "C")
     This is like `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.

   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.


File: octave.info,  Node: Input Conversion Syntax,  Next: Table of Input Conversions,  Prev: Formatted Input,  Up: C-Style I/O Functions

16.2.12 Input Conversion Syntax
-------------------------------

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:

   * An optional "flag character" `*', which says to ignore the text
     read for this specification.  When `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 return any value, and does not increment the count
     of successful assignments.  

   * An optional decimal integer that specifies the "maximum field
     width".  Reading of characters from the input stream stops either
     when this maximum is reached or when a non-matching character is
     found, whichever happens first.  Most conversions discard initial
     whitespace characters, and these discarded characters don't count
     towards the maximum field width.  Conversions that do not discard
     initial whitespace are explicitly documented.  

   * An optional type modifier character.  This character is ignored by
     Octave's `scanf' function, but is recognized to provide
     compatibility with the C language `scanf'.

   * A character that specifies the conversion to be applied.

   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.


File: octave.info,  Node: Table of Input Conversions,  Next: Numeric Input Conversions,  Prev: Input Conversion Syntax,  Up: C-Style I/O Functions

16.2.13 Table of Input Conversions
----------------------------------

Here is a table that summarizes the various conversion specifications:

`%d'
     Matches an optionally signed integer written in decimal.  *Note
     Numeric Input Conversions::.

`%i'
     Matches an optionally signed integer in any of the formats that
     the C language defines for specifying an integer constant.  *Note
     Numeric Input Conversions::.

`%o'
     Matches an unsigned integer written in octal radix.  *Note Numeric
     Input Conversions::.

`%u'
     Matches an unsigned integer written in decimal radix.  *Note
     Numeric Input Conversions::.

`%x', `%X'
     Matches an unsigned integer written in hexadecimal radix.  *Note
     Numeric Input Conversions::.

`%e', `%f', `%g', `%E', `%G'
     Matches an optionally signed floating-point number.  *Note Numeric
     Input Conversions::.

`%s'
     Matches a string containing only non-whitespace characters.  *Note
     String Input Conversions::.

`%c'
     Matches a string of one or more characters; the number of
     characters read is controlled by the maximum field width given for
     the conversion.  *Note String Input Conversions::.

`%%'
     This matches a literal `%' character in the input stream.  No
     corresponding argument is used.

   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.


File: octave.info,  Node: Numeric Input Conversions,  Next: String Input Conversions,  Prev: Table of Input Conversions,  Up: C-Style I/O Functions

16.2.14 Numeric Input Conversions
---------------------------------

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.


File: octave.info,  Node: String Input Conversions,  Next: Binary I/O,  Prev: Numeric Input Conversions,  Up: C-Style I/O Functions

16.2.15 String Input Conversions
--------------------------------

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,"'.


File: octave.info,  Node: Binary I/O,  Next: Temporary Files,  Prev: String Input Conversions,  Up: C-Style I/O Functions

16.2.16 Binary I/O
------------------

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.

 -- Built-in Function: [VAL, COUNT] = fread (FID, SIZE, PRECISION,
          SKIP, ARCH)
     Read binary data of type PRECISION from the specified file ID FID.

     The optional argument SIZE specifies the amount of data to read
     and may be one of

    `Inf'
          Read as much as possible, returning a column vector.

    `NR'
          Read up to NR elements, returning a column vector.

    `[NR, Inf]'
          Read as much as possible, 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.

    `[NR, NC]'
          Read up to `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

    `"schar"'
    `"signed char"'
          Signed character.

    `"uchar"'
    `"unsigned char"'
          Unsigned character.

    `"int8"'
    `"integer*1"'
          8-bit signed integer.

    `"int16"'
    `"integer*2"'
          16-bit signed integer.

    `"int32"'
    `"integer*4"'
          32-bit signed integer.

    `"int64"'
    `"integer*8"'
          64-bit signed integer.

    `"uint8"'
          8-bit unsigned integer.

    `"uint16"'
          16-bit unsigned integer.

    `"uint32"'
          32-bit unsigned integer.

    `"uint64"'
          64-bit unsigned integer.

    `"single"'
    `"float32"'
    `"real*4"'
          32-bit floating point number.

    `"double"'
    `"float64"'
    `"real*8"'
          64-bit floating point number.

    `"char"'
    `"char*1"'
          Single character.

    `"short"'
          Short integer (size is platform dependent).

    `"int"'
          Integer (size is platform dependent).

    `"long"'
          Long integer (size is platform dependent).

    `"ushort"'
    `"unsigned short"'
          Unsigned short integer (size is platform dependent).

    `"uint"'
    `"unsigned int"'
          Unsigned integer (size is platform dependent).

    `"ulong"'
    `"unsigned long"'
          Unsigned long integer (size is platform dependent).

    `"float"'
          Single precision floating point number (size is platform
          dependent).

     The default precision is `"uchar"'.

     The PRECISION argument may also specify an optional repeat count.
     For example, `32*single' causes `fread' to read a block of 32
     single precision floating point numbers.  Reading in blocks is
     useful in combination with the SKIP argument.

     The PRECISION argument may also specify a type conversion.  For
     example, `int16=>int32' causes `fread' to read 16-bit integer
     values and return an array of 32-bit integer values.  By default,
     `fread' returns a double precision array.  The special form
     `*TYPE' is shorthand for `TYPE=>TYPE'.

     The conversion and repeat counts may be combined.  For example,
     `32*single=>single' causes `fread' to read blocks of single
     precision floating point values and return an array of single
     precision values instead of the default array of double precision
     values.

     The optional argument SKIP specifies the number of bytes to skip
     after each element (or block of elements) is read.  If it is not
     specified, a value of 0 is assumed.  If the final block read is not
     complete, the final skip is omitted.  For example,

          fread (f, 10, "3*single=>single", 8)

     will omit the final 8-byte skip because the last read will not be
     a complete block of 3 values.

     The optional argument ARCH is a string specifying the data format
     for the file.  Valid values are

    `"native"'
          The format of the current machine.

    `"ieee-be"'
          IEEE big endian.

    `"ieee-le"'
          IEEE little endian.

    `"vaxd"'
          VAX D floating format.

    `"vaxg"'
          VAX G floating format.

    `"cray"'
          Cray floating format.

     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'

 -- Built-in Function: COUNT = fwrite (FID, DATA, PRECISION, SKIP, ARCH)
     Write data in binary form of type PRECISION to the specified file
     ID FID, returning the number of values successfully written to the
     file.

     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.


File: octave.info,  Node: Temporary Files,  Next: EOF and Errors,  Prev: Binary I/O,  Up: C-Style I/O Functions

16.2.17 Temporary Files
-----------------------

 -- Built-in Function: [FID, NAME, MSG] = mkstemp (TEMPLATE, DELETE)
     Return the file ID corresponding to a new temporary file with a
     unique name created from TEMPLATE.  The last six characters of
     TEMPLATE must be `XXXXXX' and these are replaced with a string
     that makes the filename unique.  The file is then created with
     mode read/write and permissions that are system dependent (on
     GNU/Linux systems, the permissions will be 0600 for versions of
     glibc 2.0.7 and later).  The file is opened with the `O_EXCL' flag.

     If the optional argument DELETE is supplied and is true, the file
     will be deleted automatically when Octave exits, or when the
     function `purge_tmp_files' is called.

     If successful, FID is a valid file ID, NAME is the name of the
     file, and and MSG is an empty string.  Otherwise, FID is -1, NAME
     is empty, and MSG contains a system-dependent error message.

 -- Built-in Function: [FID, MSG] = tmpfile ()
     Return the file ID corresponding to a new temporary file with a
     unique name.  The file is opened in binary read/write (`"w+b"')
     mode.  The file will be deleted automatically when it is closed or
     when Octave exits.

     If successful, FID is a valid file ID and MSG is an empty string.
     Otherwise, FID is -1 and MSG contains a system-dependent error
     message.

 -- Built-in Function:  tmpnam (DIR, PREFIX)
     Return a unique temporary file name as a string.

     If PREFIX is omitted, a value of `"oct-"' is used.  If DIR is also
     omitted, the default directory for temporary files is used.  If
     DIR is provided, it must exist, otherwise the default directory
     for temporary files is used.  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.


File: octave.info,  Node: EOF and Errors,  Next: File Positioning,  Prev: Temporary Files,  Up: C-Style I/O Functions

16.2.18 End of File and Errors
------------------------------

 -- Built-in Function:  feof (FID)
     Return 1 if an end-of-file condition has been encountered for a
     given file and 0 otherwise.  Note that it will only return 1 if
     the end of the file has already been encountered, not if the next
     read operation will result in an end-of-file condition.

 -- Built-in Function:  ferror (FID)
     Return 1 if an error condition has been encountered for a given
     file and 0 otherwise.  Note that it will only return 1 if an error
     has already been encountered, not if the next operation will
     result in an error condition.

 -- Built-in Function:  freport ()
     Print a list of which files have been opened, and whether they are
     open for reading, writing, or both.  For example,

          freport ()

               -|  number  mode  name
               -|
               -|       0     r  stdin
               -|       1     w  stdout
               -|       2     w  stderr
               -|       3     r  myfile


File: octave.info,  Node: File Positioning,  Prev: EOF and Errors,  Up: C-Style I/O Functions

16.2.19 File Positioning
------------------------

Three functions are available for setting and determining the position
of the file pointer for a given file.

 -- Built-in Function:  ftell (FID)
     Return the position of the file pointer as the number of characters
     from the beginning of the file FID.

 -- Built-in Function:  fseek (FID, OFFSET, ORIGIN)
     Set the file pointer to any location within the file FID.

     The pointer is positioned OFFSET characters from the ORIGIN, which
     may be one of the predefined variables `SEEK_CUR' (current
     position), `SEEK_SET' (beginning), or `SEEK_END' (end of file) or
     strings "cof", "bof" or "eof". 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'.

     Return 0 on success and -1 on error.

 -- Built-in Variable: SEEK_SET
 -- Built-in Variable: SEEK_CUR
 -- Built-in Variable: SEEK_END
     These variables may be used as the optional third argument for the
     function `fseek'.

    `SEEK_SET'
          Position file relative to the beginning.

    `SEEK_CUR'
          Position file relative to the current position.

    `SEEK_END'
          used with fseek to position file relative to the end.

 -- Built-in Function:  frewind (FID)
     Move the file pointer to the beginning of the file FID, returning
     0 for success, and -1 if an error was encountered.  It is
     equivalent to `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);


File: octave.info,  Node: Plotting,  Next: Matrix Manipulation,  Prev: Input and Output,  Up: Top

17 Plotting
***********

All of Octave's plotting functions use `gnuplot' to handle the actual
graphics. Most types of plots can be generated using the basic plotting
functions, which are patterned after the equivalent functions in
MATLAB. The use of these functions is generally straightforward, and is
the preferred method for generating plots.  However, for users familiar
with `gnuplot', or for some specialized applications where the basic
commands are inadequate, Octave also provides two low-level functions,
`gplot' and `gsplot', that behave almost exactly like the corresponding
`gnuplot' functions `plot' and `splot'. Also note that some advanced
MATLAB features from recent versions are not implemented, such as
handle-graphics and related functions.

* Menu:

* Two-Dimensional Plotting::
* Specialized Two-Dimensional Plots::
* Three-Dimensional Plotting::
* Plot Annotations::
* Multiple Plots on One Page::
* Multiple Plot Windows::
* Low-Level plotting commands::
* Interaction with gnuplot::


File: octave.info,  Node: Two-Dimensional Plotting,  Next: Specialized Two-Dimensional Plots,  Up: Plotting

17.1 Two-Dimensional Plotting
=============================

The MATLAB-style two-dimensional plotting commands are:

 -- Function File:  plot (ARGS)
     This function produces two-dimensional plots.  Many different
     combinations of arguments are possible.  The simplest form is

          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:

        * If a single data argument is supplied, it 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 the first argument is a vector and the second is a matrix,
          the the vector is plotted versus the columns (or rows) of the
          matrix.  (using whichever combination matches, with columns
          tried first.)

        * If the first argument is a matrix and the second is a vector,
          the the columns (or rows) of the matrix are plotted versus
          the vector.  (using whichever combination matches, with
          columns tried first.)

        * If both arguments are vectors, the elements of Y are plotted
          versus the elements of X.

        * If both arguments are matrices, the columns of Y are plotted
          versus the columns of X.  In this case, both matrices must
          have the same number of rows and columns and no attempt is
          made to transpose the arguments to make the number of rows
          match.

          If both arguments are scalars, a single point is plotted.

     If the FMT argument is supplied, it is interpreted as follows.  If
     FMT is missing, the default gnuplot line style is assumed.

    `-'
          Set lines plot style (default).

    `.'
          Set dots plot style.

    `@'
          Set points plot style.

    `-@'
          Set linespoints plot style.

    `^'
          Set impulses plot style.

    `L'
          Set steps plot style.

    `N'
          Interpreted as the plot color if N is an integer in the range
          1 to 6.

    `NM'
          If NM is a two digit integer and M is an integer in the range
          1 to 6, M is interpreted as the point style.  This is only
          valid in combination with the `@' or `-@' specifiers.

    `C'
          If C is one of `"r"', `"g"', `"b"', `"m"', `"c"', or `"w"',
          it is interpreted as the plot color (red, green, blue,
          magenta, cyan, or white).

    `";title;"'
          Here `"title"' is the label for the key.

    `+'
    `*'
    `o'
    `x'
          Used in combination with the points or linespoints styles,
          set the point style.

     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

     The FMT argument can also be used to assign key titles.  To do so,
     include the desired title between semi-colons after the formatting
     sequence described above, e.g. "+3;Key Title;" Note that the last
     semi-colon is required and will generate an error if it is left
     out.

     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 `*'.

          t = 0:0.1:6.3;
          plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");

     This will plot the cosine and sine functions and label them
     accordingly in the key.

 -- Built-in Function:  hold ARGS
     Tell Octave to `hold' the current data on the plot when executing
     subsequent plotting commands.  This allows you to execute a series
     of plot commands and have all the lines end up on the same figure.
     The default is for each new plot command to clear the plot device
     first.  For example, the command

          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.

 -- Built-in Function:  ishold
     Return 1 if the next line will be added to the current plot, or 0
     if the plot device will be cleared before drawing the next line.

 -- Built-in Function:  clearplot
 -- Built-in Function:  clg
     Clear the plot window and any titles or axis labels.  The name
     `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.)

 -- Function File:  shg
     Show the graph window.  Currently, this is the same as executing
     replot.


 -- Built-in Function:  closeplot
     Close stream to the `gnuplot' subprocess.  If you are using X11,
     this will close the plot window.

 -- Built-in Function:  purge_tmp_files
     Delete the temporary files created by the plotting commands.

     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.

 -- Function File:  axis (LIMITS)
     Set axis limits for plots.

     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.

     Without any arguments, `axis' turns autoscaling on.

     With one output argument, `x=axis' returns the current axes (this
     is not yet implemented for automatic axes).

     The vector argument specifying limits is optional, and additional
     string arguments may be used to specify various axis properties.
     For example,

          axis ([1, 2, 3, 4], "square");

     forces a square aspect ratio, and

          axis ("labely", "tic");

     turns tic marks on for all axes and tic mark labels on for the
     y-axis only.

     The following options control the aspect ratio of the axes.

    `"square"'
          Force a square aspect ratio.

    `"equal"'
          Force x distance to equal y-distance.

    `"normal"'
          Restore the balance.

     The following options control the way axis limits are interpreted.

    `"auto"'
          Set the specified axes to have nice limits around the data or
          all if no axes are specified.

    `"manual"'
          Fix the current axes limits.

    `"tight"'
          Fix axes to the limits of the data (not implemented).

     The option `"image"' is equivalent to `"tight"' and `"equal"'.

     The following options affect the appearance of tic marks.

    `"on"'
          Turn tic marks and labels on for all axes.

    `"off"'
          Turn tic marks off for all axes.

    `"tic[xyz]"'
          Turn tic marks on for all axes, or turn them on for the
          specified axes and off for the remainder.

    `"label[xyz]"'
          Turn tic labels on for all axes, or turn them on for the
          specified axes and off for the remainder.

    `"nolabel"'
          Turn tic labels off for all axes.
     Note, if there are no tic marks for an axis, there can be no
     labels.

     The following options affect the direction of increasing values on
     the axes.

    `"ij"'
          Reverse y-axis, so lower values are nearer the top.

    `"xy"'
          Restore y-axis, so higher values are nearer the top.



File: octave.info,  Node: Specialized Two-Dimensional Plots,  Next: Three-Dimensional Plotting,  Prev: Two-Dimensional Plotting,  Up: Plotting

17.2 Specialized Two-Dimensional Plots
======================================

 -- Function File:  bar (X, Y)
     Given two vectors of x-y data, `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.

 -- Function File:  contour (Z, N)
 -- Function File:  contour (X, Y, Z, N)
     Make a contour plot of the three-dimensional surface described by
     Z.  Someone needs to improve `gnuplot''s contour routines before
     this will be very useful.

 -- Function File:  hist (Y, X, NORM)
     Produce histogram counts or plots.

     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.

     If third argument is provided, the histogram is normalised such
     that the sum of the bars is equal to NORM.

     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.

 -- Function File:  loglog (ARGS)
     Make a two-dimensional plot using log scales for both axes.  See
     the description of `plot' for a description of the arguments that
     `loglog' will accept.

 -- Function File:  polar (THETA, RHO, FMT)
     Make a two-dimensional plot given polar the coordinates THETA and
     RHO.

     The optional third argument specifies the line type.

 -- Function File:  semilogx (ARGS)
     Make a two-dimensional plot using a log scale for the X axis.  See
     the description of `plot' for a description of the arguments that
     `semilogx' will accept.

 -- Function File:  semilogy (ARGS)
     Make a two-dimensional plot using a log scale for the Y axis.  See
     the description of `plot' for a description of the arguments that
     `semilogy' will accept.

 -- Function File:  stairs (X, Y)
     Given two vectors of x-y data, bar produces a `stairstep' plot.

     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.

 -- Function File:  errorbar (ARGS)
     This function produces two-dimensional plots with errorbars. Many
     different combinations of arguments are possible.  The simplest
     form is

          errorbar (Y, EY)

     where the first argument is taken as the set of Y coordinates and
     the second argument EY is taken as the errors of the Y values. X
     coordinates are taken to be the indices of the elements, starting
     with 1.

     If more than two arguments are given, they are interpreted as

          errorbar (X, Y, ..., FMT ...)

     where after X and Y there can be up to four error parameters such
     as EY, EX, LY, UY etc., depending on the plot type. Any number of
     argument sets may appear, as long as they are separated with a
     format string FMT.

     If Y is a matrix, X and error parameters must also be matrices
     having same dimensions. The columns of Y are plotted versus the
     corresponding columns of X and errorbars are drawn from the
     corresponding columns of error parameters.

     If FMT is missing, yerrorbars ("~") plot style is assumed.  If the
     FMT argument is supplied, it is interpreted as in normal plots
     (See __pltopt__). In addition the following plot styles are
     supported by errorbar:

    `~'
          Set yerrorbars plot style (default).

    `>'
          Set xerrorbars plot style.

    `~>'
          Set xyerrorbars plot style.

    `#'
          Set boxes plot style.

    `#~'
          Set boxerrorbars plot style.

    `#~>'
          Set boxxyerrorbars plot style.


     Examples:

          errorbar(X, Y, EX, ">")

     xerrorbar plot of Y versus X with X errorbars drawn from X-EX to
     X+EX.

          errorbar(X, Y1, EY, "~", X, Y2, LY, UY)

     Two yerrorbar plots with Y1 and Y2 versus X.  Errorbars for Y1 are
     drawn from Y1-EY to Y1+EY, errorbars for Y2 from Y2-LY to Y2+UY.

          errorbar(X, Y, LX, UX, LY, UY, "~>")

     xyerrorbar plot of Y versus X where X errorbars are drawn from
     X-LX to X+UX and Y errorbars from Y-LY to Y+UY.


 -- Function File:  loglogerr (ARGS)
     This function produces two-dimensional plots on double logarithm
     axis with errorbars. Many different combinations of arguments are
     possible.  The most used form is

          loglogerr (X, Y, EY, FMT)

     which produces a double logarithm plot of Y versus X with errors
     in the Y-scale defined by EY and the plot format defined by FMT.
     See errorbar for available formats and additional information.


 -- Function File:  semilogxerr (ARGS)
     This function produces two-dimensional plots on a semilogarithm
     axis with errorbars. Many different combinations of arguments are
     possible.  The most used form is

          semilogxerr (X, Y, EY, FMT)

     which produces a semi-logarithm plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT. See
     errorbar for available formats and additional information.


 -- Function File:  semilogyerr (ARGS)
     This function produces two-dimensional plots on a semilogarithm
     axis with errorbars. Many different combinations of arguments are
     possible.  The most used form is

          semilogyerr (X, Y, EY, FMT)

     which produces a semi-logarithm plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT. See
     errorbar for available formats and additional information.



File: octave.info,  Node: Three-Dimensional Plotting,  Next: Plot Annotations,  Prev: Specialized Two-Dimensional Plots,  Up: Plotting

17.3 Three-Dimensional Plotting
===============================

The MATLAB-style three-dimensional plotting commands are:

 -- Function File:  mesh (X, Y, Z)
     Plot a mesh given matrices X, and Y from `meshdom' and a matrix Z
     corresponding to the X and Y coordinates of the mesh.  If X and Y
     are vectors, then a typical vertex is (X(j), Y(i), Z(i,j)).  Thus,
     columns of Z correspond to different X values and rows of Z
     correspond to different Y values.

 -- Function File: [XX, YY] = meshgrid (X, Y)
 -- Function File: [XX, YY] = meshgrid (X)
     Given vectors of X and Y coordinates, return two matrices
     corresponding to the X and Y coordinates of a mesh.  The rows of
     XX are copies of X, and the columns of YY are copies of Y.

 -- Function File:  meshdom (X, Y)
     Given vectors of X and Y coordinates, return two matrices
     corresponding to the X and Y coordinates of the mesh.

     Note: this function is provided for compatibility with older
     versions of MATLAB.  You should use `meshgrid' instead.


File: octave.info,  Node: Plot Annotations,  Next: Multiple Plots on One Page,  Prev: Three-Dimensional Plotting,  Up: Plotting

17.4 Plot Annotations
=====================

 -- Function File:  grid (ARG)
     For two-dimensional plotting, force the display of a grid on the
     plot.  The argument may be either `"on"' or `"off"'.  If it is
     omitted, `"on"' is assumed.

 -- Function File:  title (STRING)
     Specify a title for a plot.

 -- Function File:  xlabel (STRING)
 -- Function File:  ylabel (STRING)
 -- Function File:  zlabel (STRING)
     Specify x, y, and z axis labels for the plot.  If you already have
     a plot displayed, use the command `replot' to redisplay it with
     the new labels.

 -- Function File:  top_title (STRING)
 -- Function File:  bottom_title (STRING)
     Makes a title with text STRING at the top (bottom) of the plot.


File: octave.info,  Node: Multiple Plots on One Page,  Next: Multiple Plot Windows,  Prev: Plot Annotations,  Up: Plotting

17.5 Multiple Plots on One Page
===============================

The following functions all require a version of `gnuplot' that
supports the multiplot feature.

 -- Function File:  mplot (X, Y)
 -- Function File:  mplot (X, Y, FMT)
 -- Function File:  mplot (X1, Y1, X2, Y2)
     This is a modified version of the `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.

 -- Function File:  multiplot (XN, YN)
     Sets and resets multiplot mode.

     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.

 -- Function File:  oneplot ()
     If in multiplot mode, switches to single plot mode.

 -- Function File:  plot_border (...)
     Multiple arguments allowed to specify the sides on which the border
     is shown.  Allowed arguments include:

    `"blank"'
          No borders displayed.

    `"all"'
          All borders displayed

    `"north"'
          North Border

    `"south"'
          South Border

    `"east"'
          East Border

    `"west"'
          West Border

     The arguments may be abbreviated to single characters.  Without any
     arguments, `plot_border' turns borders off.

 -- Function File:  subplot (ROWS, COLS, INDEX)
 -- Function File:  subplot (RCN)
     Sets `gnuplot' in multiplot mode and plots in location given by
     index (there are COLS by ROWS subwindows).

     The global variable __MULTIPLOT_SCALE__ should be used when the
     command `__gnuplot_set__ size xsize, ysize' has been used prior to
     calling `subplot'.

     The value of __MULTIPLOT_SCALE__ should be a vector with two
     elements, the first set equal to XSIZE and the second to YSIZE.

     Input:

    ROWS
          Number of rows in subplot grid.

    COLUMNS
          Number of columns in subplot grid.

    INDEX
          Index of subplot where to make the next plot.

     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:
          +----+----+----+----+
          |  1  |  2  |  3  |  4  |
          +----+----+----+----+
          |  5  |  6  |  7  |  8  |
          +----+----+----+----+

 -- Function File:  subwindow (XN, YN)
     Sets the subwindow position in multiplot mode for the next plot.
     The multiplot mode has to be previously initialized using the
     `multiplot' function, otherwise this command just becomes an alias
     to `multiplot'


File: octave.info,  Node: Multiple Plot Windows,  Next: Low-Level plotting commands,  Prev: Multiple Plots on One Page,  Up: Plotting

17.6 Multiple Plot Windows
==========================

 -- Function File:  figure (N)
     Set the current plot window to plot window N.  This function
     currently requires X11 and a version of gnuplot that supports
     multiple frames.  If N is not specified, the next available window
     number is chosen.


File: octave.info,  Node: Low-Level plotting commands,  Next: Interaction with gnuplot,  Prev: Multiple Plot Windows,  Up: Plotting

17.7 Low-Level plotting commands
================================

 -- Command: gplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 2-dimensional plot.

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

 -- Command: gsplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 3-dimensional plot.

     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

          1 1 3 2 1 6 3 1 9
          1 2 2 2 2 5 3 2 8
          1 3 1 2 3 4 3 3 7

     but not `rand (5, 30)'.

 -- Command: gset options
 -- Command: gshow options
 -- Command: replot options
     In addition to the basic plotting commands, the whole range of
     `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 sin (x) 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.

   Note that NaN values in the plot data are automatically omitted, and
Inf values are converted to a very large value before calling gnuplot.


File: octave.info,  Node: Interaction with gnuplot,  Prev: Low-Level plotting commands,  Up: Plotting

17.8 Interaction with `gnuplot'
===============================

 -- Built-in Variable: gnuplot_binary
     The name of the program invoked by the plot command.  The default
     value is `"gnuplot"'.  *Note Installation::.

 -- Built-in Variable: gnuplot_has_frames
     If the value of this variable is nonzero, Octave assumes that your
     copy of gnuplot has support for multiple frames that is included
     in recent 3.6beta releases.  Its initial value is determined by
     configure, but it can be changed in your startup script or at the
     command line in case configure got it wrong, or if you upgrade
     your gnuplot installation.

 -- Built-in Variable: gnuplot_command_plot

 -- Built-in Variable: gnuplot_command_replot

 -- Built-in Variable: gnuplot_command_splot

 -- Built-in Variable: gnuplot_command_using

 -- Built-in Variable: gnuplot_command_with

 -- Built-in Variable: gnuplot_command_axes

 -- Built-in Variable: gnuplot_command_title

 -- Built-in Variable: gnuplot_command_end


File: octave.info,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top

18 Matrix Manipulation
**********************

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.

* Menu:

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::


File: octave.info,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Up: Matrix Manipulation

18.1 Finding Elements and Checking Conditions
=============================================

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.

 -- Built-in Function:  any (X, DIM)
     For a vector argument, return 1 if any element of the vector is
     nonzero.

     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 ]

     If the optional argument DIM is supplied, work along dimension
     DIM.  For example,

          any (eye (2, 4), 2)
               => [ 1; 1 ]

 -- Built-in Function:  all (X, DIM)
     The function `all' behaves like the function `any', except that it
     returns true only if all the elements of a vector, or all the
     elements along dimension DIM of a matrix, are nonzero.

   Since the comparison operators (*note Comparison Ops::) 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))'.

 -- Mapping Function:  xor (X, Y)
     Return the `exclusive or' of the entries of X and Y.  For boolean
     expressions X and Y, `xor (X, Y)' is true if and only if X or Y is
     true, but not if both X and Y are true.

 -- Function File:  is_duplicate_entry (X)
     Return non-zero if any entries in X are duplicates of one another.

 -- Function File:  diff (X, K, DIM)
     If X is a vector of length N, `diff (X)' is the vector of first
     differences X(2) - X(1), ..., X(n) - X(n-1).

     If X is a matrix, `diff (X)' is the matrix of column differences
     along the first non-singleton dimension.

     The second argument is optional.  If supplied, `diff (X, K)',
     where K is a nonnegative integer, returns the K-th differences. It
     is possible that K is larger than then first non-singleton
     dimension of the matrix. In this case, `diff' continues to take
     the differences along the next non-singleton dimension.

     The dimension along which to take the difference can be explicitly
     stated with the optional variable DIM. In this case the K-th order
     differences are calculated along this dimension.  In the case
     where K exceeds `size (X, DIM)' then an empty matrix is returned.

 -- Mapping Function:  isinf (X)
     Return 1 for elements of X that are infinite and zero otherwise.
     For example,

          isinf ([13, Inf, NA, NaN])
               => [ 0, 1, 0, 0 ]

 -- Mapping Function:  isnan (X)
     Return 1 for elements of X that are NaN values and zero otherwise.
     For example,

          isnan ([13, Inf, NA, NaN])
               => [ 0, 0, 0, 1 ]

 -- Mapping Function:  finite (X)
     Return 1 for elements of X that are finite values and zero
     otherwise. For example,

          finite ([13, Inf, NA, NaN])
               => [ 1, 0, 0, 0 ]

 -- Loadable Function:  find (X)
     Return a vector of indices of nonzero elements of a matrix.  To
     obtain a single index for each matrix element, Octave pretends
     that the columns of a matrix form one long vector (like Fortran
     arrays are stored).  For example,

          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 ]

 -- Function File: [ERR, Y1, ...] = common_size (X1, ...)
     Determine if all input arguments are either scalar or of common
     size.  If so, ERR is zero, and YI is a matrix of the common size
     with all entries equal to XI if this is a scalar or XI otherwise.
     If the inputs cannot be brought to a common size, errorcode is 1,
     and YI is XI.  For example,

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


File: octave.info,  Node: Rearranging Matrices,  Next: Special Utility Matrices,  Prev: Finding Elements and Checking Conditions,  Up: Matrix Manipulation

18.2 Rearranging Matrices
=========================

 -- Function File:  fliplr (X)
     Return a copy of X with the order of the columns reversed.  For
     example,

          fliplr ([1, 2; 3, 4])
          =>  2  1
                   4  3

     Note that `fliplr' only workw with 2-D arrays.  To flip N-d arrays
     use `flipdim' instead.

 -- Function File:  flipud (X)
     Return a copy of X with the order of the rows reversed.  For
     example,

          flipud ([1, 2; 3, 4])
          =>  3  4
                   1  2

     Due to the difficulty of defining which axis about which to flip
     the matrix `flipud' only work with 2-d arrays.  To flip N-d arrays
     use `flipdim' instead.

 -- Function File:  flipdim (X, DIM)
     Return a copy of X flipped about the dimension DIM.  For example

          flipdim ([1, 2; 3, 4], 2)
          =>  2  1
                   4  3

 -- Function File:  rot90 (X, N)
     Return a copy of X with the elements rotated counterclockwise in
     90-degree increments.  The second argument is optional, and
     specifies how many 90-degree rotations are to be applied (the
     default value is 1).  Negative values of N rotate the matrix in a
     clockwise direction.  For example,

          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)

     Due to the difficulty of defining an axis about which to rotate the
     matrix `rot90' only work with 2-D arrays.  To rotate N-d arrays
     use `rotdim' instead.

 -- Function File:  rotdim (X, N, PLANE)
     Return a copy of X with the elements rotated counterclockwise in
     90-degree increments.  The second argument is optional, and
     specifies how many 90-degree rotations are to be applied (the
     default value is 1).  The third argument is also optional and
     defines the plane of the rotation. As such PLANE is a two element
     vector containing two different valid dimensions of the matrix. If
     PLANE is not given Then the first two non-singleton dimensions are
     used.

     Negative values of N rotate the matrix in a clockwise direction.
     For example,

          rotdim ([1, 2; 3, 4], -1, [1, 2])
          =>  3  1
                   4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rot90 ([1, 2; 3, 4], -1, [1, 2])
          ==
          rot90 ([1, 2; 3, 4], 3, [1, 2])
          ==
          rot90 ([1, 2; 3, 4], 7, [1, 2])

 -- Built-in Function:  cat (DIM, ARRAY1, ARRAY2, ..., ARRAYN)
     Return the concatenation of N-d array objects, ARRAY1, ARRAY2,
     ..., ARRAYN along dimension DIM.

          A = ones (2, 2);
          B = zeros (2, 2);
          cat (2, A, B)
          => ans =

               1 1 0 0
               1 1 0 0

     Alternatively, we can concatenate A and B along the second
     dimension the following way:

          [A, B].

     DIM can be larger than the dimensions of the N-d array objects and
     the result will thus have DIM dimensions as the following example
     shows:
          cat (4, ones(2, 2), zeros (2, 2))
          => ans =

             ans(:,:,1,1) =

               1 1
               1 1

             ans(:,:,1,2) =
               0 0
               0 0


 -- Built-in Function:  horzcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the horizontal concatenation of N-d array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 2.

 -- Built-in Function:  vertcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the vertical concatenation of N-d array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 1.

 -- Built-in Function:  permute (A, PERM)
     Return the generalized transpose for an N-d array object A.  The
     permutation vector PERM must contain the elements `1:ndims(a)' (in
     any order, but each element must appear just once).


 -- Built-in Function:  ipermute (A, IPERM)
     The inverse of the `permute' function.  The expression

          ipermute (permute (a, perm), perm)
     returns the original array A.


 -- Function File:  reshape (A, M, N, ...)
 -- Function File:  reshape (A, SIZ)
     Return a matrix with the given dimensions whose elements are taken
     from the matrix A.  The elements of the matrix are access in
     column-major order (like Fortran arrays are stored).

     For example,

          reshape ([1, 2, 3, 4], 2, 2)
               =>  1  3
                   2  4

     Note that the total number of elements in the original matrix must
     match the total number of elements in the new matrix.

     A single dimension of the return matrix can be unknown and is
     flagged by an empty argument.

 -- Function File: Y = circshift (X, N)
     Circularly shifts the values of the array X. N must be a vector of
     integers no longer than the number of dimensions in X. The values
     of N can be either positive or negative, which determines the
     direction in which the values or X are shifted. If an element of N
     is zero, then the corresponding dimension of X will not be
     shifted. For example

          x = [1, 2, 3; 4, 5, 6, 7, 8, 9];
          circshift (x, 1)
          =>  7, 8, 9
              1, 2, 3
              4, 5, 6
          circshift (x, -2)
          =>  7, 8, 9
              1, 2, 3
              4, 5, 6
          circshift (x, [0,1])
          =>  3, 1, 2
              6, 4, 5
              9, 7, 8

 -- Function File: Y = shiftdim (X, N)
 -- Function File: [Y, NS] = shiftdim (X)
     Shifts the dimension of X by N, where N must be an integer scalar.
     When N is positive, the dimensions of X are shifted to the left,
     with the leading dimensions circulated to the end. If N is
     negative, then the dimensions of X are shifted to the right, with
     N leading singleton dimensions added.

     Called with a single argument, `shiftdim', removes the leading
     singleton dimensions, returning the number of dimensions removed
     in the second output argument NS.

     For example

          x = ones (1, 2, 3);
          size (shiftdim (x, -1))
          => [2, 3, 1]
          size (shiftdim (x, 1))
          => [1, 1, 2, 3]
          [b, ns] = shiftdim (x);
          => b =  [1, 1, 1; 1, 1, 1]
          => ns = 1

 -- Function File:  shift (X, B)
 -- Function File:  shift (X, B, DIM)
     If X is a vector, perform a circular shift of length B of the
     elements of X.

     If X is a matrix, do the same for each column of X.  If the
     optional DIM argument is given, operate along this dimension

 -- Loadable Function: [S, I] = sort (X)
 -- Loadable Function: [S, I] = sort (X, DIM)
 -- Loadable Function: [S, I] = sort (X, MODE)
 -- Loadable Function: [S, I] = sort (X, DIM, MODE)
     Return a copy of X with the elements elements arranged in
     increasing order.  For matrices, `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

     If the optional argument DIM is given, then the matrix is sorted
     along the dimension defined by DIM. The optional argument `mode'
     defines the order in which the values will be sorted. Valid values
     of `mode' are `ascend' or `descend'.

     For equal elements, the indices are such that the equal elements
     are listed in the order that appeared in the original list.

     The `sort' function may also be used to sort strings and cell
     arrays of strings, it which case the dictionary order of the
     strings is used.

     The algorithm used in `sort' is optimized for the sorting of
     partially ordered lists.

   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(1) 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

 -- Function File:  tril (A, K)
 -- Function File:  triu (A, K)
     Return a new matrix formed by extracting extract the lower (`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

 -- Function File:  vec (X)
     Return the vector obtained by stacking the columns of the matrix X
     one above the other.

 -- Function File:  vech (X)
     Return the vector obtained by eliminating all supradiagonal
     elements of the square matrix X and stacking the result one column
     above the other.

 -- Function File:  prepad (X, L, C)
 -- Function File:  postpad (X, L, C)
 -- Function File:  postpad (X, L, C, DIM)
     Prepends (appends) the scalar value C to the vector X until it is
     of length L.  If the third argument is not supplied, a value of 0
     is used.

     If `length (X) > L', elements from the beginning (end) of X are
     removed until a vector of length L is obtained.

     If X is a matrix, elements are prepended or removed from each row.

     If the optional DIM argument is given, then operate along this
     dimension.

   ---------- Footnotes ----------

   (1) For example, to first sort based on the values in column 1, and
then, for any values that are repeated in column 1, sort based on the
values found in column 2, etc.


File: octave.info,  Node: Special Utility Matrices,  Next: Famous Matrices,  Prev: Rearranging Matrices,  Up: Matrix Manipulation

18.3 Special Utility Matrices
=============================

 -- Built-in Function:  eye (X)
 -- Built-in Function:  eye (N, M)
 -- Built-in Function:  eye (..., CLASS)
     Return an identity matrix.  If invoked with a single scalar
     argument, `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])

     The optional argument CLASS, allows `eye' to return an array of
     the specified type, like

          val = zeros (n,m, "uint8")

     For compatibility with MATLAB, calling `eye' with no arguments is
     equivalent to calling it with an argument of 1.

 -- Built-in Function:  ones (X)
 -- Built-in Function:  ones (N, M)
 -- Built-in Function:  ones (N, M, K, ...)
 -- Built-in Function:  ones (..., CLASS)
     Return a matrix or N-dimensional array whose elements are all 1.
     The arguments are handled the same as the arguments for `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)

     The optional argument CLASS, allows `ones' to return an array of
     the specified type, like

          val = ones (n,m, "uint8")

 -- Built-in Function:  zeros (X)
 -- Built-in Function:  zeros (N, M)
 -- Built-in Function:  zeros (N, M, K, ...)
 -- Built-in Function:  zeros (..., CLASS)
     Return a matrix or N-dimensional array whose elements are all 0.
     The arguments are handled the same as the arguments for `eye'.

     The optional argument CLASS, allows `zeros' to return an array of
     the specified type, like

          val = zeros (n,m, "uint8")

 -- Function File:  repmat (A, M, N)
 -- Function File:  repmat (A, [M N])
     Form a block matrix of size M by N, with a copy of matrix A as
     each element.  If N is not specified, form an M by M block matrix.

 -- Loadable Function:  rand (X)
 -- Loadable Function:  rand (N, M)
 -- Loadable Function:  rand (`"seed"', X)
     Return a matrix with random elements uniformly distributed on the
     interval (0, 1).  The arguments are handled the same as the
     arguments for `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.

 -- Loadable Function:  randn (X)
 -- Loadable Function:  randn (N, M)
 -- Loadable Function:  randn (`"seed"', X)
     Return a matrix with normally distributed random elements.  The
     arguments are handled the same as the arguments for `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.

 -- Function File:  randperm (N)
     Return a row vector containing a random permutation of the
     integers from 1 to N.

 -- Built-in Function:  diag (V, K)
     Return a diagonal matrix with vector V on diagonal K.  The second
     argument is optional.  If it is positive, the vector is placed on
     the K-th super-diagonal.  If it is negative, it is placed on the
     -K-th sub-diagonal.  The default value of K is 0, and the vector
     is placed on the main diagonal.  For example,

          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.  *Note Ranges::.

 -- Built-in Function:  linspace (BASE, LIMIT, N)
     Return a row vector with N linearly spaced elements between BASE
     and LIMIT.  The number of elements, N, must be greater than 1.
     The BASE and LIMIT are always included in the range.  If BASE is
     greater than LIMIT, the elements are stored in decreasing order.
     If the number of points is not specified, a value of 100 is used.

     The `linspace' function always returns a row vector.

 -- Function File:  logspace (BASE, LIMIT, N)
     Similar to `linspace' except that the values are logarithmically
     spaced from 10^base to 10^limit.

     If LIMIT is equal to pi, the points are between 10^base and pi,
     _not_ 10^base and 10^pi, in order to  be compatible with the
     corresponding MATLAB function.

 -- Built-in Variable: warn_neg_dim_as_zero
     If the value of `warn_neg_dim_as_zero' is nonzero, print a warning
     for expressions like

          eye (-1)

     The default value is 0.

 -- Built-in Variable: warn_imag_to_real
     If the value of `warn_imag_to_real' is nonzero, a warning is
     printed for implicit conversions of complex numbers to real
     numbers.  The default value is 0.


File: octave.info,  Node: Famous Matrices,  Prev: Special Utility Matrices,  Up: Matrix Manipulation

18.4 Famous Matrices
====================

The following functions return famous matrix forms.

 -- Function File:  hankel (C, R)
     Return the Hankel matrix constructed given the first column C, and
     (optionally) the last row R.  If the last element of C is not the
     same as the first element of R, the last element of C is used.  If
     the second argument is omitted, it is assumed to be a vector of
     zeros with the same size as C.

     A Hankel matrix formed from an m-vector C, and an n-vector R, has
     the elements

          H(i,j) = c(i+j-1),  i+j-1 <= m;
          H(i,j) = r(i+j-m),  otherwise

 -- Function File:  hilb (N)
     Return the Hilbert matrix of order N.  The i, j element of a
     Hilbert matrix is defined as

          H (i, j) = 1 / (i + j - 1)

 -- Function File:  invhilb (N)
     Return the inverse of a Hilbert matrix of order N.  This can be
     computed computed exactly using

                      (i+j)         /n+i-1\  /n+j-1\   /i+j-2\ 2
           A(i,j) = -1      (i+j-1)(       )(       ) (       )
                                    \ n-j /  \ n-i /   \ i-2 /

                  = p(i) p(j) / (i+j-1)
     where
                       k  /k+n-1\   /n\
              p(k) = -1  (       ) (   )
                          \ k-1 /   \k/

     The validity of this formula can easily be checked by expanding
     the binomial coefficients in both formulas as factorials.  It can
     be derived more directly via the theory of Cauchy matrices: see J.
     W. Demmel, Applied Numerical Linear Algebra, page 92.

     Compare this with the numerical calculation of `inverse (hilb
     (n))', which suffers from the ill-conditioning of the Hilbert
     matrix, and the finite precision of your computer's floating point
     arithmetic.


 -- Function File:  sylvester_matrix (K)
     Return the Sylvester matrix of order n = 2^k.

 -- Function File:  toeplitz (C, R)
     Return the Toeplitz matrix constructed given the first column C,
     and (optionally) the first row R.  If the first element of C is
     not the same as the first element of R, the first element of C is
     used.  If the second argument is omitted, the first row is taken
     to be the same as the first column.

     A square Toeplitz matrix has the form:

          c(0)  r(1)   r(2)  ...  r(n)
          c(1)  c(0)   r(1)  ... r(n-1)
          c(2)  c(1)   c(0)  ... r(n-2)
           .     ,      ,   .      .
           .     ,      ,     .    .
           .     ,      ,       .  .
          c(n) c(n-1) c(n-2) ...  c(0)

 -- Function File:  vander (C)
     Return the Vandermonde matrix whose next to last column is C.

     A Vandermonde matrix has the form:

          c(1)^(n-1) ... c(1)^2  c(1)  1
          c(2)^(n-1) ... c(2)^2  c(2)  1
              .     .      .      .    .
              .       .    .      .    .
              .         .  .      .    .
          c(n)^(n-1) ... c(n)^2  c(n)  1


File: octave.info,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Matrix Manipulation,  Up: Top

19 Arithmetic
*************

Unless otherwise noted, all of the functions described in this chapter
will work for real and complex scalar or matrix arguments.

* Menu:

* Utility Functions::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Special Functions::
* Coordinate Transformations::
* Mathematical Constants::


File: octave.info,  Node: Utility Functions,  Next: Complex Arithmetic,  Up: Arithmetic

19.1 Utility Functions
======================

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.

 -- Mapping Function:  ceil (X)
     Return the smallest integer not less than X.  If X is complex,
     return `ceil (real (X)) + ceil (imag (X)) * I'.

 -- Mapping Function:  exp (X)
     Compute the exponential of X.  To compute the matrix exponential,
     see *Note Linear Algebra::.

 -- Mapping Function:  fix (X)
     Truncate X toward zero.  If X is complex, return `fix (real (X)) +
     fix (imag (X)) * I'.

 -- Mapping Function:  floor (X)
     Return the largest integer not greater than X.  If X is complex,
     return `floor (real (X)) + floor (imag (X)) * I'.

 -- Loadable Function: G = gcd (A1, `...')
 -- Loadable Function: [G, V1, ...] = gcd (A1, `...')
     If a single argument is given then compute the greatest common
     divisor of the elements of this argument. Otherwise if more than
     one argument is given all arguments must be the same size or
     scalar. In this case the greatest common divisor is calculated for
     element individually. All elements must be integers. For example,

          gcd ([15, 20])
              =>  5

     and

          gcd ([15, 9], [20 18])
              =>  5  9

     Optional return arguments V1, etc, contain integer vectors such
     that,

          G = V1 .* A1 + V2 .* A2 + ...

     For backward compatiability with previous versions of this
     function, when all arguments are scalr, a single return argument
     V1 containing all of the values of V1, ... is acceptable.

 -- Mapping Function:  lcm (X, `...')
     Compute the least common multiple of the elements elements of X, or
     the list of all the arguments.  For example,

          lcm (a1, ..., ak)

     is the same as

          lcm ([a1, ..., ak]).

     All elements must be the same size or scalar.

 -- Mapping Function:  log (X)
     Compute the natural logarithm for each element of X.  To compute
     the matrix logarithm, see *Note Linear Algebra::.

 -- Mapping Function:  log10 (X)
     Compute the base-10 logarithm for each element of X.

 -- Mapping Function:  log2 (X)
 -- Mapping Function: [F, E] = log2 (X)
     Compute the base-2 logarithm of X.  With two outputs, returns F
     and E such that  1/2 <= abs(f) < 1 and x = f * 2^e.

 -- Mapping Function:  max (X, Y, DIM)
 -- Mapping Function: [W, IW] = max (X)
     For a vector argument, return the maximum value.  For a matrix
     argument, return the maximum value from each column, as a row
     vector, or over the dimension DIM if defined. For two matrices (or
     a matrix and scalar), return the pair-wise maximum.  Thus,

          max (max (X))

     returns the largest element of X, and

          max (2:5, pi)
              =>  3.1416  3.1416  4.0000  5.0000
     compares each element of the range `2:5' with `pi', and
     returns a row vector of the maximum values.

     For complex arguments, the magnitude of the elements are used for
     comparison.

     If called with one input and two output arguments, `max' also
     returns the first index of the maximum value(s). Thus,

          [x, ix] = max ([1, 3, 5, 2, 5])
              =>  x = 5
                  ix = 3

 -- Mapping Function:  min (X, Y, DIM)
 -- Mapping Function: [W, IW] = min (X)
     For a vector argument, return the minimum value.  For a matrix
     argument, return the minimum value from each column, as a row
     vector, or over the dimension DIM if defined. For two matrices (or
     a matrix and scalar), return the pair-wise minimum.  Thus,

          min (min (X))

     returns the smallest element of X, and

          min (2:5, pi)
              =>  2.0000  3.0000  3.1416  3.1416
     compares each element of the range `2:5' with `pi', and
     returns a row vector of the minimum values.

     For complex arguments, the magnitude of the elements are used for
     comparison.

     If called with one input and two output arguments, `min' also
     returns the first index of the minimum value(s). Thus,

          [x, ix] = min ([1, 3, 0, 2, 5])
              =>  x = 0
                  ix = 3

 -- Mapping Function:  mod (X, Y)
     Compute modulo function, using

          x - y .* floor (x ./ y)

     Note that this handles negative numbers correctly: `mod (-1, 3)'
     is 2, not -1 as `rem (-1, 3)' returns.  Also, `mod (X, 0)' returns
     X.

     An error message is printed if the dimensions of the arguments do
     not agree, or if either of the arguments is complex.

 -- Function File:  nextpow2 (X)
     If X is a scalar, returns the first integer N such that  2^n >=
     abs (x).

     If X is a vector, return `nextpow2 (length (X))'.

 -- Mapping Function:  pow2 (X)
 -- Mapping Function:  pow2 (F, E)
     With one argument, computes  2 .^ x for each element of X.  With
     two arguments, returns  f .* (2 .^ e).

 -- Mapping Function:  rem (X, Y)
     Return the remainder of `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.

 -- Mapping Function:  round (X)
     Return the integer nearest to X.  If X is complex, return `round
     (real (X)) + round (imag (X)) * I'.

 -- Mapping Function:  sign (X)
     Compute the "signum" function, which is defined as

                     -1, x < 0;
          sign (x) =  0, x = 0;
                      1, x > 0.

     For complex arguments, `sign' returns `x ./ abs (X)'.

 -- Mapping Function:  sqrt (X)
     Compute the square root of X.  If X is negative, a complex result
     is returned.  To compute the matrix square root, see *Note Linear
     Algebra::.


File: octave.info,  Node: Complex Arithmetic,  Next: Trigonometry,  Prev: Utility Functions,  Up: Arithmetic

19.2 Complex Arithmetic
=======================

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, Z is the complex number X + IY, where I is defined as `sqrt
(-1)'.

 -- Mapping Function:  abs (Z)
     Compute the magnitude of Z, defined as |Z| = `sqrt (x^2 + y^2)'.

     For example,

          abs (3 + 4i)
               => 5

 -- Mapping Function:  arg (Z)
 -- Mapping Function:  angle (Z)
     Compute the argument of Z, defined as THETA = `atan (Y/X)'.  in
     radians.

     For example,

          arg (3 + 4i)
               => 0.92730

 -- Mapping Function:  conj (Z)
     Return the complex conjugate of Z, defined as `conj (Z)' = X - IY.

 -- Mapping Function:  imag (Z)
     Return the imaginary part of Z as a real number.

 -- Mapping Function:  real (Z)
     Return the real part of Z.


File: octave.info,  Node: Trigonometry,  Next: Sums and Products,  Prev: Complex Arithmetic,  Up: Arithmetic

19.3 Trigonometry
=================

Octave provides the following trigonometric functions.  Angles are
specified in radians.  To convert from degrees to radians multipy by
`pi/180'  (e.g. `sin (30 * pi/180)' returns the sine of 30 degrees).

 -- Mapping Function:  sin (X)
     Compute the sine of each element of X.

 -- Mapping Function:  cos (X)
     Compute the cosine of each element of X.

 -- Mapping Function:  tan (Z)
     Compute tangent of each element of X.

 -- Mapping Function:  sec (X)
     Compute the secant of each element of X.

 -- Mapping Function:  csc (X)
     Compute the cosecant of each element of X.

 -- Mapping Function:  cot (X)
     Compute the cotangent of each element of X.

 -- Mapping Function:  asin (X)
     Compute the inverse sine of each element of X.

 -- Mapping Function:  acos (X)
     Compute the inverse cosine of each element of X.

 -- Mapping Function:  atan (X)
     Compute the inverse tangent of each element of X.

 -- Mapping Function:  asec (X)
     Compute the inverse secant of each element of X.

 -- Mapping Function:  acsc (X)
     Compute the inverse cosecant of each element of X.

 -- Mapping Function:  acot (X)
     Compute the inverse cotangent of each element of X.

 -- Mapping Function:  sinh (X)
     Compute the inverse hyperbolic sine of each element of X.

 -- Mapping Function:  cosh (X)
     Compute the hyperbolic cosine of each element of X.

 -- Mapping Function:  tanh (X)
     Compute hyperbolic tangent of each element of X.

 -- Mapping Function:  sech (X)
     Compute the hyperbolic secant of each element of X.

 -- Mapping Function:  csch (X)
     Compute the hyperbolic cosecant of each element of X.

 -- Mapping Function:  coth (X)
     Compute the hyperbolic cotangent of each element of X.

 -- Mapping Function:  asinh (X)
     Compute the inverse hyperbolic sine of each element of X.

 -- Mapping Function:  acosh (X)
     Compute the inverse hyperbolic cosine of each element of X.

 -- Mapping Function:  atanh (X)
     Compute the inverse hyperbolic tangent of each element of X.

 -- Mapping Function:  asech (X)
     Compute the inverse hyperbolic secant of each element of X.

 -- Mapping Function:  acsch (X)
     Compute the inverse hyperbolic cosecant of each element of X.

 -- Mapping Function:  acoth (X)
     Compute the inverse hyperbolic cotangent of each element of X.

   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

 -- Mapping Function:  atan2 (Y, X)
     Compute atan (Y / X) for corresponding elements of Y and X.  The
     result is in range -pi to pi.


File: octave.info,  Node: Sums and Products,  Next: Special Functions,  Prev: Trigonometry,  Up: Arithmetic

19.4 Sums and Products
======================

 -- Built-in Function:  sum (X, DIM)
     Sum of elements along dimension DIM.  If DIM is omitted, it
     defaults to 1 (column-wise sum).

     As a special case, if X is a vector and DIM is omitted, return the
     sum of the elements.

 -- Built-in Function:  prod (X, DIM)
     Product of elements along dimension DIM.  If DIM is omitted, it
     defaults to 1 (column-wise products).

     As a special case, if X is a vector and DIM is omitted, return the
     product of the elements.

 -- Built-in Function:  cumsum (X, DIM)
     Cumulative sum of elements along dimension DIM.  If DIM is
     omitted, it defaults to 1 (column-wise cumulative sums).

     As a special case, if X is a vector and DIM is omitted, return the
     cumulative sum of the elements as a vector with the same
     orientation as X.

 -- Built-in Function:  cumprod (X, DIM)
     Cumulative product of elements along dimension DIM.  If DIM is
     omitted, it defaults to 1 (column-wise cumulative products).

     As a special case, if X is a vector and DIM is omitted, return the
     cumulative product of the elements as a vector with the same
     orientation as X.

 -- Built-in Function:  sumsq (X, DIM)
     Sum of squares of elements along dimension DIM.  If DIM is
     omitted, it defaults to 1 (column-wise sum of squares).

     As a special case, if X is a vector and DIM is omitted, return the
     sum of squares of the elements.

     This function is conceptually equivalent to computing
          sum (x .* conj (x), dim)
     but it uses less memory and avoids calling conj if X is real.


File: octave.info,  Node: Special Functions,  Next: Coordinate Transformations,  Prev: Sums and Products,  Up: Arithmetic

19.5 Special Functions
======================

 -- Loadable Function: [J, IERR] = besselj (ALPHA, X, OPT)
 -- Loadable Function: [Y, IERR] = bessely (ALPHA, X, OPT)
 -- Loadable Function: [I, IERR] = besseli (ALPHA, X, OPT)
 -- Loadable Function: [K, IERR] = besselk (ALPHA, X, OPT)
 -- Loadable Function: [H, IERR] = besselh (ALPHA, K, X, OPT)
     Compute Bessel or Hankel functions of various kinds:

    `besselj'
          Bessel functions of the first kind.

    `bessely'
          Bessel functions of the second kind.

    `besseli'
          Modified Bessel functions of the first kind.

    `besselk'
          Modified Bessel functions of the second kind.

    `besselh'
          Compute Hankel functions of the first (K = 1) or second (K  =
          2) kind.

     If the argument OPT is supplied, the result is scaled by the `exp
     (-I*X)' for K = 1 or `exp (I*X)' for  K = 2.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     `length (X)' rows and `length (ALPHA)' columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     The value of ALPHA must be real.  The value of X may be complex.

     If requested, IERR contains the following status information and
     is the same size as the result.

       0. Normal return.

       1. Input error, return `NaN'.

       2. Overflow, return `Inf'.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          `NaN'.

       5. Error--no computation, algorithm termination condition not
          met, return `NaN'.

 -- Loadable Function: [A, IERR] = airy (K, Z, OPT)
     Compute Airy functions of the first and second kind, and their
     derivatives.

            K   Function   Scale factor (if a third argument is supplied)
           ---  --------   ----------------------------------------------
            0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
            1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
            2   Bi (Z)     exp (-abs (real ((2/3) * Z *sqrt (Z))))
            3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z *sqrt (Z))))

     The function call `airy (Z)' is equivalent to `airy (0, Z)'.

     The result is the same size as Z.

     If requested, IERR contains the following status information and
     is the same size as the result.

       0. Normal return.

       1. Input error, return `NaN'.

       2. Overflow, return `Inf'.

       3. Loss of significance by argument reduction results in less
          than half  of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          `NaN'.

       5. Error--no computation, algorithm termination condition not
          met, return `NaN'

 -- Mapping Function:  beta (A, B)
     Return the Beta function,

          beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).

 -- Mapping Function:  betainc (X, A, B)
     Return the incomplete Beta function,

                                                x
                                               /
          betainc (x, a, b) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt.
                                               /
                                            t=0

     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.

 -- Mapping Function:  bincoeff (N, K)
     Return the binomial coefficient of N and K, defined as

           /   \
           | n |    n (n-1) (n-2) ... (n-k+1)
           |   |  = -------------------------
           | k |               k!
           \   /

     For example,

          bincoeff (5, 2)
          => 10

 -- Mapping Function:  erf (Z)
     Computes the error function,

                                   z
                                  /
          erf (z) = (2/sqrt (pi)) | e^(-t^2) dt
                                  /
                               t=0

 -- Mapping Function:  erfc (Z)
     Computes the complementary error function, `1 - erf (Z)'.

 -- Mapping Function:  erfinv (Z)
     Computes the inverse of the error function.

 -- Mapping Function:  gamma (Z)
     Computes the Gamma function,

                      infinity
                      /
          gamma (z) = | t^(z-1) exp (-t) dt.
                      /
                   t=0

 -- Mapping Function:  gammainc (X, A)
     Computes the incomplete gamma function,

                                          x
                                1        /
          gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                            gamma (a)    /
                                      t=0

     If A is scalar, then `gammainc (X, A)' is returned for each
     element of X and vice versa.

     If neither X nor A is scalar, the sizes of X and A must agree, and
     GAMMAINC is applied element-by-element.

 -- Mapping Function:  lgamma (A, X)
 -- Mapping Function:  gammaln (A, X)
     Return the natural logarithm of the gamma function.

 -- Function File:  cross (X, Y, DIM)
     Computes the vector cross product of the two 3-dimensional vectors
     X and Y.

          cross ([1,1,0], [0,1,1])
          => [ 1; -1; 1 ]

     If X and Y are matrices, the cross product is applied along the
     first dimension with 3 elements. The optional argument DIM is used
     to force the cross product to be calculated along the dimension
     defiend by DIM.

 -- Function File:  commutation_matrix (M, N)
     Return the commutation matrix  K(m,n)  which is the unique M*N by
     M*N  matrix such that K(m,n) * vec(A) = vec(A')  for all m by n
     matrices A.

     If only one argument M is given, K(m,m)  is returned.

     See Magnus and Neudecker (1988), Matrix differential calculus with
     applications in statistics and econometrics.

 -- Function File:  duplication_matrix (N)
     Return the duplication matrix Dn  which is the unique n^2 by
     n*(n+1)/2  matrix such that Dn vech (A) = vec (A)  for all
     symmetric n by n  matrices A.

     See Magnus and Neudecker (1988), Matrix differential calculus with
     applications in statistics and econometrics.


File: octave.info,  Node: Coordinate Transformations,  Next: Mathematical Constants,  Prev: Special Functions,  Up: Arithmetic

19.6 Coordinate Transformations
===============================

 -- Function File:  [THETA, R] = cart2pol (X, Y)
 -- Function File:  [THETA, R, Z] = cart2pol (X, Y, Z)
     Transform cartesian to polar or cylindrical coordinates.  X, Y
     (and Z) must be of same shape.  THETA describes the angle relative
     to the x - axis.  R is the distance to the z - axis (0, 0, z).

 -- Function File:  [X, Y] = pol2cart (THETA, R)
 -- Function File:  [X, Y, Z] = pol2cart (THETA, R, Z)
     Transform polar or cylindrical to cartesian coordinates.  THETA, R
     (and Z) must be of same shape.  THETA describes the angle relative
     to the x - axis.  R is the distance to the z - axis (0, 0, z).

 -- Function File:  [THETA, PHI, R] = cart2sph (X, Y, Z)
     Transform cartesian to spherical coordinates.  X, Y and Z must be
     of same shape.  THETA describes the angle relative to the x - axis.
     PHI is the angle relative to the xy - plane.  R is the distance to
     the origin (0, 0, 0).

 -- Function File:  [X, Y, Z] = sph2cart (THETA, PHI, R)
     Transform spherical to cartesian coordinates.  X, Y and Z must be
     of same shape.  THETA describes the angle relative to the x-axis.
     PHI is the angle relative to the xy-plane.  R is the distance to
     the origin (0, 0, 0).


File: octave.info,  Node: Mathematical Constants,  Prev: Coordinate Transformations,  Up: Arithmetic

19.7 Mathematical Constants
===========================

 -- Built-in Variable: I
 -- Built-in Variable: J
 -- Built-in Variable: i
 -- Built-in Variable: j
     A pure imaginary number, defined as   `sqrt (-1)'.  These built-in
     variables behave like functions so you can use the names for other
     purposes.  If you use them as variables and assign values to them
     and then clear them, they once again assume their special
     predefined values *Note Status of Variables::.

 -- Built-in Variable: Inf
 -- Built-in Variable: inf
     Infinity.  This is the result of an operation like 1/0, or an
     operation that results in a floating point overflow.

 -- Built-in Variable: NaN
 -- Built-in Variable: nan
     Not a number.  This is the result of an operation like 0/0, or
     `Inf - Inf', or any operation with a NaN.

     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.

 -- Built-in Variable: pi
     The ratio of the circumference of a circle to its diameter.
     Internally, `pi' is computed as `4.0 * atan (1.0)'.

 -- Built-in Variable: e
     The base of natural logarithms.  The constant  E  satisfies the
     equation  `log' (E) = 1.

 -- Built-in Variable: eps
     The machine precision.  More precisely, `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  2.2204e-16.

 -- Built-in Variable: realmax
     The largest floating point number that is representable.  The
     actual value is system-dependent.  On machines that support 64-bit
     IEEE floating point arithmetic, `realmax' is approximately
     1.7977e+308

 -- Built-in Variable: realmin
     The smallest normalized floating point number that is
     representable.  The actual value is system-dependent.  On machines
     that support 64-bit IEEE floating point arithmetic, `realmin' is
     approximately  2.2251e-308


File: octave.info,  Node: Linear Algebra,  Next: Nonlinear Equations,  Prev: Arithmetic,  Up: Top

20 Linear Algebra
*****************

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.

* Menu:

* Basic Matrix Functions::
* Matrix Factorizations::
* Functions of a Matrix::


File: octave.info,  Node: Basic Matrix Functions,  Next: Matrix Factorizations,  Up: Linear Algebra

20.1 Basic Matrix Functions
===========================

 -- Loadable Function: AA = balance (A, OPT)
 -- Loadable Function: [DD, AA] = balance (A, OPT)
 -- Loadable Function: [CC, DD, AA, BB] = balance (A, B, OPT)
     `[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"'
          No balancing; arguments copied, transformation(s) set to
          identity.

    `"P"', `"p"'
          Permute argument(s) to isolate eigenvalues where possible.

    `"S"', `"s"'
          Scale to improve accuracy of computed eigenvalues.

    `"B"', `"b"'
          Permute and scale, in that order. Rows/columns of a (and b)
          that are isolated by permutation are not scaled.  This is the
          default behavior.

     Algebraic eigenvalue balancing uses standard LAPACK routines.

     Generalized eigenvalue problem balancing uses Ward's algorithm
     (SIAM Journal on Scientific and Statistical Computing, 1981).

 -- Function File:  cond (A)
     Compute the (two-norm) condition number of a matrix. `cond (a)' is
     defined as `norm (a) * norm (inv (a))', and is computed via a
     singular value decomposition.

 -- Loadable Function: [D, RCOND] =  det (A)
     Compute the determinant of A using LAPACK.  Return an estimate of
     the reciprocal condition number if requested.

 -- Function File:  dmult (A, B)
     If A is a vector of length `rows (B)', return `diag (A) * B' (but
     computed much more efficiently).

 -- Function File:  dot (X, Y, DIM)
     Computes the dot product of two vectors. If X and Y are matrices,
     calculate the dot-product along the first non-singleton dimension.
     If the optional argument DIM is given, calculate the dot-product
     along this dimension.

 -- Loadable Function: LAMBDA = eig (A)
 -- Loadable Function: [V, LAMBDA] = eig (A)
     The eigenvalues (and eigenvectors) of a matrix are computed in a
     several step process which begins with a Hessenberg decomposition,
     followed by a Schur decomposition, from which the eigenvalues are
     apparent.  The eigenvectors, when desired, are computed by further
     manipulations of the Schur decomposition.

 -- Loadable Function: G = givens (X, Y)
 -- Loadable Function: [C, S] = givens (X, Y)
     Return a 2 by 2 orthogonal matrix `G = [C S; -S' C]' such that `G
     [X; Y] = [*; 0]' with X and Y scalars.

     For example,

          givens (1, 1)
               =>   0.70711   0.70711
                   -0.70711   0.70711

 -- Loadable Function: [X, RCOND] =  inv (A)
 -- Loadable Function: [X, RCOND] =  inverse (A)
     Compute the inverse of the square matrix A.  Return an estimate of
     the reciprocal condition number if requested, otherwise warn of an
     ill-conditioned matrix if the reciprocal condition number is small.

 -- Function File:  norm (A, P)
     Compute the p-norm of the matrix A.  If the second argument is
     missing, `p = 2' is assumed.

     If A is a matrix:

    P = `1'
          1-norm, the largest column sum of the absolute values of A.

    P = `2'
          Largest singular value of A.

    P = `Inf'
          Infinity norm, the largest row sum of the absolute values of
          A.

    P = `"fro"'
          Frobenius norm of A, `sqrt (sum (diag (A' * A)))'.

     If A is a vector or a scalar:

    P = `Inf'
          `max (abs (A))'.

    P = `-Inf'
          `min (abs (A))'.

    other
          p-norm of A, `(sum (abs (A) .^ P)) ^ (1/P)'.

 -- Function File:  null (A, TOL)
     Return an orthonormal basis of the null space of A.

     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

 -- Function File:  orth (A, TOL)
     Return an orthonormal basis of the range space of A.

     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

 -- Loadable Function:  pinv (X, TOL)
     Return the pseudoinverse of X.  Singular values less than TOL are
     ignored.

     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.

 -- Function File:  rank (A, TOL)
     Compute the rank of A, using the singular value decomposition.
     The rank is taken to be the number  of singular values of A that
     are greater than the specified tolerance TOL.  If the second
     argument is omitted, it is taken to be

          tol = max (size (A)) * sigma(1) * eps;

     where `eps' is machine precision and `sigma(1)' is the largest
     singular value of A.

 -- Function File:  trace (A)
     Compute the trace of A, `sum (diag (A))'.


File: octave.info,  Node: Matrix Factorizations,  Next: Functions of a Matrix,  Prev: Basic Matrix Functions,  Up: Linear Algebra

20.2 Matrix Factorizations
==========================

 -- Loadable Function:  chol (A)
     Compute the Cholesky factor, R, of the symmetric positive definite
     matrix A, where

          r' * r = a.

 -- Loadable Function: H = hess (A)
 -- Loadable Function: [P, H] = hess (A)
     Compute the Hessenberg decomposition of the matrix 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 `p * h * p' = a' where `p'
     is a square unitary matrix (`p' * p = I', using complex-conjugate
     transposition) and `h' is upper Hessenberg (`i >= j+1 => h (i, j)
     = 0').

 -- Loadable Function: [L, U, P] = lu (A)
     Compute the LU decomposition of A, using subroutines from LAPACK.
     The result is returned in a permuted form, according to the
     optional return value P.  For example, given the matrix `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

     The matrix is not required to be square..

 -- Loadable Function: [Q, R, P] = qr (A)
     Compute the QR factorization of A, using standard LAPACK
     subroutines.  For example, given the matrix `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

          `min norm(A x - b)'

     for overdetermined systems of equations (i.e., `a'  is a tall,
     thin matrix).  The QR factorization is `q * r = a' where `q' is an
     orthogonal matrix and `r' is upper triangular.

     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, p] = 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)'.

 -- Loadable Function: LAMBDA = qz (A, B)
     Generalized eigenvalue problem A x = s B x, QZ decomposition.
     There are three ways to call this function:
       1. `lambda = qz(A,B)'

          Computes the generalized eigenvalues LAMBDA of (A - s B).

       2. `[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 and Z orthogonal (unitary)= I

       3. `[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.
         OPT
               for ordering eigenvalues of the GEP pencil.  The leading
               block              of the revised pencil contains all
               eigenvalues that satisfy:
              `"N"'
                    = unordered (default)

              `"S"'
                    = small: leading block has all |lambda| <=1

              `"B"'
                    = big: leading block has all |lambda >= 1

              `"-"'
                    = negative real part: leading  block has all
                    eigenvalues                   in the open left
                    half-plant

              `"+"'
                    = nonnegative real part:  leading block has all
                    eigenvalues                   in the closed right
                    half-plane

     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

 -- Function File: [AA, BB, Q, Z] = qzhess (A, B)
     Compute the Hessenberg-triangular decomposition of the matrix
     pencil `(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'.

 -- Loadable Function: S = schur (A)
 -- Loadable Function: [U, S] = schur (A, OPT)
     The Schur decomposition is used to compute eigenvalues of a square
     matrix, and has applications in the solution of algebraic Riccati
     equations in control (see `are' and `dare').  `schur' always
     returns `s = u' * a * u' where `u'  is a unitary matrix (`u'* u'
     is identity) and `s' is upper triangular.  The eigenvalues of `a'
     (and `s') are the diagonal elements of `s' If the matrix `a' is
     real, then the real Schur decomposition is computed, in which the
     matrix `u' is orthogonal and `s' is block upper triangular with
     blocks of size at most `2 x 2' along the diagonal.  The diagonal
     elements of `s' (or the eigenvalues of the `2 x 2' blocks, when
     appropriate) are the eigenvalues of `a' and `s'.

     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 `s' (used in `are'), `opt = "d"' indicates that all
     eigenvalues with magnitude less than one should be moved to the
     leading block of `s' (used in `dare'), and `opt = "u"', the
     default, indicates that no ordering of eigenvalues should occur.
     The leading `k' columns of `u' always span the `a'-invariant
     subspace corresponding to the `k' leading eigenvalues of `s'.

 -- Loadable Function: S = svd (A)
 -- Loadable Function: [U, S, V] = svd (A)
     Compute the singular value decomposition of A

          a = u * sigma * v'

     The function `svd' normally returns the vector of singular values.
     If asked for three return values, it computes U, S, and V.  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.

 -- Function File: [HOUSV, BETA, ZER] = housh (X, J, Z)
     Computes householder reflection vector housv to reflect x to be
     jth column of identity, i.e., (I - beta*housv*housv')x =e(j) inputs
      x: vector   j: index into vector   z: threshold for zero
     (usually should be the number 0) outputs: (see Golub and Van Loan)
      beta: If beta = 0, then no reflection need be applied (zer set
     to 0)   housv: householder vector

 -- Function File: [U, H, NU] = krylov (A, V, K, EPS1, PFLG);
     construct orthogonal basis U of block Krylov subspace;  [v a*v
     a^2*v ... a^(k+1)*v]; method used: householder reflections to
     guard against loss of orthogonality eps1: threshhold for 0
     (default: 1e-12) pflg: flag to use row pivoting  (improves
     numerical behavior)   0 [default]: no pivoting; prints a warning
     message if trivial                null space is corrupted   1
        : pivoting performed

     outputs:   u: orthogonal basis of block krylov subspace   h:
     Hessenberg matrix; if v is a vector then a u = u h      otherwise
     h is meaningless  nu: dimension of span of krylov subspace (based
     on eps1) if b is a vector and k > m-1, krylov returns h = the
     Hessenberg decompostion of a.

     Reference: Hodel and Misra, "Partial Pivoting in the Computation of
        Krylov Subspaces", to be submitted to Linear Algebra and its
      Applications


File: octave.info,  Node: Functions of a Matrix,  Prev: Matrix Factorizations,  Up: Linear Algebra

20.3 Functions of a Matrix
==========================

 -- Loadable Function:  expm (A)
     Return the exponential of a matrix, defined as the infinite Taylor
     series

          expm(a) = I + a + a^2/2! + a^3/3! + ...

     The Taylor series is _not_ the way to compute the matrix
     exponential; see Moler and Van Loan, `Nineteen Dubious Ways to
     Compute the Exponential of a Matrix', SIAM Review, 1978.  This
     routine uses Ward's diagonal Pade' approximation method with three
     step preconditioning (SIAM Journal on Numerical Analysis, 1977).
     Diagonal Pade'  approximations are rational polynomials of matrices

               -1
          D (a)   N (a)

     whose Taylor series matches the first `2q+1' terms of the Taylor
     series above; direct evaluation of the Taylor series (with the
     same preconditioning steps) may be desirable in lieu of the Pade'
     approximation when `Dq(a)' is ill-conditioned.

 -- Function File:  logm (A)
     Compute the matrix logarithm of the square matrix A.  Note that
     this is currently implemented in terms of an eigenvalue expansion
     and needs to be improved to be more robust.

 -- Loadable Function: [RESULT, ERROR_ESTIMATE] = sqrtm (A)
     Compute the matrix square root of the square matrix A.

     Ref: Nicholas J. Higham. A new sqrtm for MATLAB. Numerical Analysis
     Report No. 336, Manchester Centre for Computational Mathematics,
     Manchester, England, January 1999.

 -- Function File:  kron (A, B)
     Form the kronecker product of two matrices, defined block by block
     as

          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

 -- Loadable Function: X = syl (A, B, C)
     Solve the Sylvester equation

          A X + X B + C = 0
     using standard LAPACK subroutines.  For example,

          syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])
               => [ -0.50000, -0.66667; -0.66667, -0.50000 ]


File: octave.info,  Node: Nonlinear Equations,  Next: Quadrature,  Prev: Linear Algebra,  Up: Top

21 Nonlinear Equations
**********************

Octave can solve sets of nonlinear equations of the form

     F (x) = 0

using the function `fsolve', which is based on the MINPACK subroutine
`hybrd'.

 -- Loadable Function: [X, INFO, MSG] = fsolve (FCN, X0)
     Given FCN, the name of a function of the form `f (X)' and an
     initial starting point X0, `fsolve' solves the set of equations
     such that `f(X) == 0'.

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a
     function of the form `j (X)' to compute the Jacobian matrix with
     elements

                     df_i
          jac(i,j) = ----
                     dx_j

     You can use the function `fsolve_options' to set optional
     parameters for `fsolve'.

 -- Loadable Function:  fsolve_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `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.

     Options include

    `"tolerance"'
          Nonnegative relative tolerance.

   Here is a complete example.  To solve the set of equations

     -2x^2 + 3xy   + 4 sin(y) = 6
      3x^2 - 2xy^2 + 3 cos(x) = -4

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


File: octave.info,  Node: Quadrature,  Next: Differential Equations,  Prev: Nonlinear Equations,  Up: Top

22 Quadrature
*************

* Menu:

* Functions of One Variable::
* Orthogonal Collocation::


File: octave.info,  Node: Functions of One Variable,  Next: Orthogonal Collocation,  Up: Quadrature

22.1 Functions of One Variable
==============================

 -- Loadable Function: [V, IER, NFUN, ERR] = quad (F, A, B, TOL, SING)
     Integrate a nonlinear function of one variable using Quadpack.
     The first argument is the name of the  function, the function
     handle or the inline function to call to compute the value of the
     integrand.  It must have the form

          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.

     You can use the function `quad_options' to set optional parameters
     for `quad'.

 -- Loadable Function:  quad_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance; may be zero for pure relative error test.

    `"relative tolerance"'
          Nonnegative relative tolerance.  If the absolute tolerance is
          zero, the relative tolerance must be greater than or equal to
          `max (50*eps, 0.5e-28)'.

   Here is an example of using `quad' to integrate the function

       F(X) = X * sin (1/X) * sqrt (abs (1 - X))

from X = 0 to X = 3.

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


File: octave.info,  Node: Orthogonal Collocation,  Prev: Functions of One Variable,  Up: Quadrature

22.2 Orthogonal Collocation
===========================

 -- Loadable Function: [R, AMAT, BMAT, Q] = colloc (N, "left", "right")
     Compute derivative and integral weight matrices for orthogonal
     collocation using the subroutines given in J. Villadsen and M. L.
     Michelsen, `Solution of Differential Equation Models by Polynomial
     Approximation'.

   Here is an example of using `colloc' to generate weight matrices for
solving the second order differential equation U' - ALPHA * U" = 0 with
the boundary conditions U(0) = 0 and U(1) = 1.

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

     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 ]


File: octave.info,  Node: Differential Equations,  Next: Optimization,  Prev: Quadrature,  Up: Top

23 Differential Equations
*************************

Octave has two built-in functions for solving differential equations.
Both are based on reliable ODE solvers written in Fortran.

* Menu:

* Ordinary Differential Equations::
* Differential-Algebraic Equations::


File: octave.info,  Node: Ordinary Differential Equations,  Next: Differential-Algebraic Equations,  Up: Differential Equations

23.1 Ordinary Differential Equations
====================================

The function `lsode' can be used to solve ODEs of the form

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

 -- Loadable Function: [X, ISTATE, MSG] lsode (FCN, X_0, T, T_CRIT)
     Solve the set of differential equations

          dx
          -- = f(x, t)
          dt

     with

          x(t_0) = x_0

     The solution is returned in the matrix X, with each row
     corresponding to an element of the vector T.  The first element of
     T should be t_0 and should correspond to the initial state of the
     system X_0, so that the first row of the output is X_0.

     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.  The function must have the form

          XDOT = f (X, T)

     in which XDOT and X are vectors and T is a scalar.

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a function
     to compute the Jacobian of f.  The Jacobian function must have the
     form

          JAC = j (X, T)

     in which JAC is the matrix of partial derivatives

                       | df_1  df_1       df_1 |
                       | ----  ----  ...  ---- |
                       | dx_1  dx_2       dx_N |
                       |                       |
                       | df_2  df_2       df_2 |
                       | ----  ----  ...  ---- |
                df_i   | dx_1  dx_2       dx_N |
          jac = ---- = |                       |
                dx_j   |  .    .     .    .    |
                       |  .    .      .   .    |
                       |  .    .       .  .    |
                       |                       |
                       | df_N  df_N       df_N |
                       | ----  ----  ...  ---- |
                       | dx_1  dx_2       dx_N |

     The second and third arguments specify the intial state of the
     system, x_0, and the initial value of the independent variable t_0.

     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.

     After a successful computation, the value of ISTATE will be 2
     (consistent with the Fortran version of LSODE).

     If the computation is not successful, ISTATE will be something
     other than 2 and MSG will contain additional information.

     You can use the function `lsode_options' to set optional
     parameters for `lsode'.

 -- Loadable Function:  lsode_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector.

    `"relative tolerance"'
          Relative tolerance parameter.  Unlike the absolute tolerance,
          this parameter may only be a scalar.

          The local error test applied at each integration step is

                 abs (local error in x(i)) <= rtol * abs (y(i)) + atol(i)

    `"integration method"'
          A string specifing the method of integration to use to solve
          the ODE system.  Valid values are

         "adams"
         "non-stiff"
               No Jacobian used (even if it is available).

         "bdf"

         "stiff"
               Use stiff backward differentiation formula (BDF) method.
               If a function to compute the Jacobian is not supplied,
               `lsode' will compute a finite difference approximation
               of the Jacobian matrix.

    `"initial step size"'
          The step size to be attempted on the first step (default is
          determined automatically).

    `"maximum order"'
          Restrict the maximum order of the solution method.  If using
          the Adams method, this option must be between 1 and 12.
          Otherwise, it must be between 1 and 5, inclusive.

    `"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions  (default is not specified).

    `"minimum step size"'
          The minimum absolute step size allowed (default is 0).

    `"step limit"'
          Maximum number of steps allowed (default is 100000).

   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)];

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


File: octave.info,  Node: Differential-Algebraic Equations,  Prev: Ordinary Differential Equations,  Up: Differential Equations

23.2 Differential-Algebraic Equations
=====================================

The function `daspk' can be used to solve DAEs of the form

     0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0

using Petzold's DAE solver DASPK.

 -- Loadable Function: [X, XDOT, ISTATE, MSG] = daspk (FCN, X_0,
          XDOT_0, T, T_CRIT)
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T.  The first element of T should be t_0 and correspond to
     the initial state of the system X_0 and its derivative XDOT_0, so
     that the first row of the output X is X_0 and the first row of the
     output XDOT is XDOT_0.

     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)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a
     function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)

     The second and third arguments to `daspk' 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.  If they are not consistent, you must
     use the `daspk_options' function to provide additional information
     so that `daspk' can compute a consistent starting point.

     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.

     After a successful computation, the value of ISTATE will be
     greater than zero (consistent with the Fortran version of DASPK).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function `daspk_options' to set optional
     parameters for `daspk'.

 -- Loadable Function:  daspk_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `daspk'.  Given one argument,
     `daspk_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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

    `"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is

                 abs (local error in x(i))
                      <= rtol(i) * abs (Y(i)) + atol(i)

    `"compute consistent initial condition"'
          Denoting the differential variables in the state vector by
          `Y_d' and the algebraic variables by `Y_a', `ddaspk' can solve
          one of two initialization problems:

            1. Given Y_d, calculate Y_a and Y'_d

            2. Given Y', calculate Y.

          In either case, initial values for the given components are
          input, and initial guesses for the unknown components must
          also be provided as input.  Set this option to 1 to solve the
          first problem, or 2 to solve the second (the default default
          is 0, so you must provide a set of initial conditions that
          are consistent).

          If this option is set to a nonzero value, you must also set
          the `"algebraic variables"' option to declare which variables
          in the problem are algebraic.

    `"use initial condition heuristics"'
          Set to a nonzero value to use the initial condition
          heuristics options described below.

    `"initial condition heuristics"'
          A vector of the following parameters that can be used to
          control the initial condition calculation.

         `MXNIT'
               Maximum number of Newton iterations (default is 5).

         `MXNJ'
               Maximum number of Jacobian evaluations (default is 6).

         `MXNH'
               Maximum number of values of the artificial stepsize
               parameter to be tried if the `"compute consistent
               initial condition"' option has been set to 1 (default is
               5).

               Note that the maximum number of Newton iterations
               allowed in all is `MXNIT*MXNJ*MXNH' if the `"compute
               consistent initial condition"' option has been set to 1
               and `MXNIT*MXNJ' if it is set to 2.

         `LSOFF'
               Set to a nonzero value to disable the linesearch
               algorithm (default is 0).

         `STPTOL'
               Minimum scaled step in linesearch algorithm (default is
               eps^(2/3)).

         `EPINIT'
               Swing factor in the Newton iteration convergence test.
               The test is applied to the residual vector,
               premultiplied by the approximate Jacobian.  For
               convergence, the weighted RMS norm of this vector
               (scaled by the error weights) must be less than
               `EPINIT*EPCON', where `EPCON' = 0.33 is the analogous
               test constant used in the time steps. The default is
               `EPINIT' = 0.01.

    `"print initial condition info"'
          Set this option to a nonzero value to display detailed
          information about the initial condition calculation (default
          is 0).

    `"exclude algebraic variables from error test"'
          Set to a nonzero value to exclude algebraic variables from
          the error test.  You must also set the `"algebraic
          variables"' option to declare which variables in the problem
          are algebraic (default is 0).

    `"algebraic variables"'
          A vector of the same length as the state vector.  A nonzero
          element indicates that the corresponding element of the state
          vector is an algebraic variable (i.e., its derivative does
          not appear explicitly in the equation set.

          This option is required by the `compute consistent initial
          condition"' and `"exclude algebraic variables from error
          test"' options.

    `"enforce inequality constraints"'
          Set to one of the following values to enforce the inequality
          constraints specified by the `"inequality constraint types"'
          option (default is 0).

            1. To have constraint checking only in the initial
               condition calculation.

            2. To enforce constraint checking during the integration.

            3. To enforce both options 1 and 2.

    `"inequality constraint types"'
          A vector of the same length as the state specifying the type
          of inequality constraint.  Each element of the vector
          corresponds to an element of the state and should be assigned
          one of the following codes

         -2
               Less than zero.

         -1
               Less than or equal to zero.

         0
               Not constrained.

         1
               Greater than or equal to zero.

         2
               Greater than zero.

          This option only has an effect if the `"enforce inequality
          constraints"' option is nonzero.

    `"initial step size"'
          Differential-algebraic problems may occaisionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize
          (default is computed automatically).

    `"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive (default is 5).

    `"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions (default is not specified).

   Octave also includes DASSL, an earlier version of DASPK, and DASRT,
which can be used to solve DAEs with constraints (stopping conditions).

 -- Loadable Function: [X, XDOT, T_OUT, ISTAT, MSG] = dasrt (FCN [, G],
          X_0, XDOT_0, T [, T_CRIT])
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     with functional stopping criteria (root solving).

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T_OUT.  The first element of T should be t_0 and correspond
     to the initial state of the system X_0 and its derivative XDOT_0,
     so that the first row of the output X is X_0 and the first row of
     the output XDOT is XDOT_0.

     The vector T provides an upper limit on the length of the
     integration.  If the stopping condition is met, the vector T_OUT
     will be shorter than T, and the final element of T_OUT will be the
     point at which the stopping condition was met, and may not
     correspond to any element of the vector T.

     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)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a
     function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)

     The optional second argument names a function that defines the
     constraint functions whose roots are desired during the
     integration.  This function must have the form

          G_OUT = g (X, T)

     and return a vector of the constraint function values.  If the
     value of any of the constraint functions changes sign, DASRT will
     attempt to stop the integration at the point of the sign change.

     If the name of the constraint function is omitted, `dasrt' solves
     the same problem as `daspk' or `dassl'.

     Note that because of numerical errors in the constraint functions
     due to roundoff and integration error, DASRT may return false
     roots, or return the same root at two or more nearly equal values
     of T.  If such false roots are suspected, the user should consider
     smaller error tolerances or higher precision in the evaluation of
     the constraint functions.

     If a root of some constraint function defines the end of the
     problem, the input to DASRT should nevertheless allow integration
     to a point slightly past that root, so that DASRT can locate the
     root by interpolation.

     The third and fourth arguments to `dasrt' 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 sixth 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.

     After a successful computation, the value of ISTATE will be
     greater than zero (consistent with the Fortran version of DASSL).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function `dasrt_options' to set optional
     parameters for `dasrt'.

 -- Loadable Function:  dasrt_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `dasrt'.  Given one argument,
     `dasrt_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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

    `"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is
                 abs (local error in x(i)) <= rtol(i) * abs (Y(i)) + atol(i)

    `"initial step size"'
          Differential-algebraic problems may occaisionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize.

    `"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive.

    `"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions.

    `"step limit"'
          Maximum number of integration steps to attempt on a single
          call to the underlying Fortran code.

   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.


File: octave.info,  Node: Optimization,  Next: Statistics,  Prev: Differential Equations,  Up: Top

24 Optimization
***************

* Menu:

* Linear Programming::
* Quadratic Programming::
* Nonlinear Programming::
* Linear Least Squares::


File: octave.info,  Node: Linear Programming,  Next: Quadratic Programming,  Up: Optimization

24.1 Linear Programming
=======================


File: octave.info,  Node: Quadratic Programming,  Next: Nonlinear Programming,  Prev: Linear Programming,  Up: Optimization

24.2 Quadratic Programming
==========================


File: octave.info,  Node: Nonlinear Programming,  Next: Linear Least Squares,  Prev: Quadratic Programming,  Up: Optimization

24.3 Nonlinear Programming
==========================


File: octave.info,  Node: Linear Least Squares,  Prev: Nonlinear Programming,  Up: Optimization

24.4 Linear Least Squares
=========================

 -- Function File: [BETA, V, R] = gls (Y, X, O)
     Generalized least squares estimation for the multivariate model y
     = x b + e with mean (e) = 0 and cov (vec (e)) = (s^2) o,  where y
     is a t by p matrix, x is a t by k matrix, b is a k by p matrix, e
     is a t by p matrix, and o is a t p by t p matrix.

     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.

    BETA
          The GLS estimator for b.

    V
          The GLS estimator for s^2.

    R
          The matrix of GLS residuals, r = y - x beta.

 -- Function File: [BETA, SIGMA, R] = ols (Y, X)
     Ordinary least squares estimation for the multivariate model y = x
     b + e with mean (e) = 0 and cov (vec (e)) = kron (s, I).   where y
     is a t by p matrix, x is a t by k matrix, b is a k by p matrix, and
     e is a t by p matrix.

     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
          The OLS estimator for B, `BETA = pinv (X) * Y', where `pinv
          (X)' denotes the pseudoinverse of X.

    SIGMA
          The OLS estimator for the matrix S,

               SIGMA = (Y-X*BETA)'
                 * (Y-X*BETA)
                 / (T-rank(X))

    R
          The matrix of OLS residuals, `R = Y - X * BETA'.


File: octave.info,  Node: Statistics,  Next: Financial Functions,  Prev: Optimization,  Up: Top

25 Statistics
*************

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

* Menu:

* Basic Statistical Functions::
* Tests::
* Models::
* Distributions::


File: octave.info,  Node: Basic Statistical Functions,  Next: Tests,  Up: Statistics

25.1 Basic Statistical Functions
================================

 -- Function File:  mean (X, DIM, OPT)
     If X is a vector, compute the mean of the elements of X

          mean (x) = SUM_i x(i) / N
     If X is a matrix, compute the mean for each column and return them
     in a row vector.

     With the optional argument OPT, the kind of mean computed can be
     selected.  The following options are recognized:

    `"a"'
          Compute the (ordinary) arithmetic mean.  This is the default.

    `"g"'
          Computer the geometric mean.

    `"h"'
          Compute the harmonic mean.

     If the optional argument DIM is supplied, work along dimension DIM.

     Both DIM and OPT are optional.  If both are supplied, either may
     appear first.

 -- Function File:  median (X)
     If X is a vector, compute the median value of the elements of X.

                      x(ceil(N/2)),             N odd
          median(x) =
                      (x(N/2) + x((N/2)+1))/2,  N even
     If X is a matrix, compute the median value for each column
     and return them in a row vector.

 -- Function File:  std (X)
 -- Function File:  std (X, OPT)
 -- Function File:  std (X, OPT, DIM)
     If X is a vector, compute the standard deviation of the elements
     of X.

          std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
     If X is a matrix, compute the standard deviation for each
     column and return them in a row vector.

     The argument OPT determines the type of normalization to use.
     Valid values are

    0:
          normalizes with N-1, provides the square root of best
          unbiased estimator of   the variance [default]

    1:
          normalizes with N, this provides the square root of the
          second moment around   the mean

     The third argument DIM determines the dimension along which the
     standard deviation is calculated.

 -- Function File:  cov (X, Y)
     If each row of X and Y is an observation and each column is a
     variable, the (I, J)-th entry of `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)'.

 -- Function File:  corrcoef (X, Y)
     If each row of X and Y is an observation and each column is a
     variable, the (I, J)-th entry of `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)'.

 -- Function File:  kurtosis (X, DIM)
     If X is a vector of length N, return the kurtosis

          kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3

     of X.  If X is a matrix, return the kurtosis over the first
     non-singleton dimension. The optional argument DIM can be given to
     force the kurtosis to be given over that dimension.

 -- Function File:  mahalanobis (X, Y)
     Return the Mahalanobis' D-square distance between the multivariate
     samples X and Y, which must have the same number of components
     (columns), but may have a different number of observations (rows).

 -- Function File:  skewness (X, DIM)
     If X is a vector of length n, return the skewness

          skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)

     of X.  If X is a matrix, return the skewness along the first
     non-singleton dimension of the matrix. If the optional DIM
     argument is given, operate along this dimension.

 -- Function File:  values (X)
     Return the different values in a column vector, arranged in
     ascending order.

 -- Function File:  var (X)
     For vector arguments, return the (real) variance of the values.
     For matrix arguments, return a row vector contaning the variance
     for each column.

     The argument OPT determines the type of normalization to use. Valid
     values are

    0:
          normalizes with N-1, provides the square root of best
          unbiased estimator   of the variance [default]

    1:
          normalizes with N, this provides the square root of the
          second moment   around the mean

     The third argument DIM determines the dimension along which the
     variance is calculated.

 -- Function File: [T, L_X] = table (X)
 -- Function File: [T, L_X, L_Y] = table (X, Y)
     Create a contingency table T from data vectors.  The L vectors are
     the corresponding levels.

     Currently, only 1- and 2-dimensional tables are supported.

 -- Function File:  studentize (X, DIM)
     If X is a vector, subtract its mean and divide by its standard
     deviation.

     If X is a matrix, do the above along the first non-singleton
     dimension. If the optional argument DIM is given then operate
     along this dimension.

 -- Function File:  statistics (X)
     If X is a matrix, return a matrix with the minimum, first
     quartile, median, third quartile, maximum, mean, standard
     deviation, skewness and kurtosis of the columns of X as its rows.

     If X is a vector, treat it as a column vector.

 -- Function File:  spearman (X, Y)
     Compute Spearman's rank correlation coefficient RHO for each of
     the variables specified by the input arguments.

     For matrices, each row is an observation and each column a
     variable; vectors are always observations and may be row or column
     vectors.

     `spearman (X)' is equivalent to `spearman (X, X)'.

     For two data vectors X and Y, Spearman's RHO is the correlation of
     the ranks of X and Y.

     If X and Y are drawn from independent distributions, RHO has zero
     mean and variance `1 / (n - 1)', and is asymptotically normally
     distributed.

 -- Function File:  run_count (X, N)
     Count the upward runs along the first non-singleton dimension of X
     of length 1, 2, ..., N-1 and greater than or equal to N. If the
     optional argument DIM is given operate along this dimension

 -- Function File:  ranks (X, DIM)
     If X is a vector, return the (column) vector of ranks of X
     adjusted for ties.

     If X is a matrix, do the above for along the first non-singleton
     dimension. If the optional argument DIM is given, operate along
     this dimension.

 -- Function File:  range (X)
 -- Function File:  range (X, DIM)
     If X is a vector, return the range, i.e., the difference between
     the maximum and the minimum, of the input data.

     If X is a matrix, do the above for each column of X.

     If the optional argument DIM is supplied, work along dimension DIM.

 -- Function File: [Q, S] = qqplot (X, DIST, PARAMS)
     Perform a QQ-plot (quantile plot).

     If F is the CDF of the distribution DIST with parameters PARAMS
     and G its inverse, and X a sample vector of length N, the QQ-plot
     graphs ordinate S(I) = I-th largest element of x versus abscissa
     Q(If) = G((I - 0.5)/N).

     If the sample comes from F except for a transformation of location
     and scale, the pairs will approximately follow a straight line.

     The default for DIST is the standard normal distribution.  The
     optional argument PARAMS contains a list of parameters of DIST.
     For example, for a quantile plot of the uniform distribution on
     [2,4] and X, use

          qqplot (x, "uniform", 2, 4)

     If no output arguments are given, the data are plotted directly.

 -- Function File:  probit (P)
     For each component of P, return the probit (the quantile of the
     standard normal distribution) of P.

 -- Function File: [P, Y] = ppplot (X, DIST, PARAMS)
     Perform a PP-plot (probability plot).

     If F is the CDF of the distribution DIST with parameters PARAMS
     and X a sample vector of length N, the PP-plot graphs ordinate
     Y(I) = F (I-th largest element of X) versus abscissa P(I) = (I -
     0.5)/N.  If the sample comes from F, the pairs will approximately
     follow a straight line.

     The default for DIST is the standard normal distribution.  The
     optional argument PARAMS contains a list of parameters of DIST.
     For example, for a probability plot of the uniform distribution on
     [2,4] and X, use

          ppplot (x, "uniform", 2, 4)

     If no output arguments are given, the data are plotted directly.

 -- Function File:  moment (X, P, OPT, DIM)
     If X is a vector, compute the P-th moment of X.

     If X is a matrix, return the row vector containing the P-th moment
     of each column.

     With the optional string opt, the kind of moment to be computed can
     be specified.  If opt contains `"c"' or `"a"', central and/or
     absolute moments are returned.  For example,

          moment (x, 3, "ac")

     computes the third central absolute moment of X.

     If the optional argument DIM is supplied, work along dimension DIM.

 -- Function File:  meansq (X)
 -- Function File:  meansq (X, DIM)
     For vector arguments, return the mean square of the values.  For
     matrix arguments, return a row vector contaning the mean square of
     each column. With the optional DIM argument, returns the mean
     squared of the values along this dimension

 -- Function File:  logit (P)
     For each component of P, return the logit `log (P / (1-P))' of P.

 -- Function File:  kendall (X, Y)
     Compute Kendall's TAU for each of the variables specified by the
     input arguments.

     For matrices, each row is an observation and each column a
     variable; vectors are always observations and may be row or column
     vectors.

     `kendall (X)' is equivalent to `kendall (X, X)'.

     For two data vectors X, Y of common length N, Kendall's TAU is the
     correlation of the signs of all rank differences of X and Y;
     i.e., if both X and Y have distinct entries, then

                   1
          tau = -------   SUM sign (q(i) - q(j)) * sign (r(i) - r(j))
                n (n-1)   i,j

     in which the Q(I) and R(I)  are the ranks of X and Y, respectively.

     If X and Y are drawn from independent distributions, Kendall's TAU
     is asymptotically normal with mean 0 and variance `(2 * (2N+5)) /
     (9 * N * (N-1))'.

 -- Function File:  iqr (X, DIM)
     If X is a vector, return the interquartile range, i.e., the
     difference between the upper and lower quartile, of the input data.

     If X is a matrix, do the above for first non singleton dimension
     of X.. If the option DIM argument is given, then operate along
     this dimension.

 -- Function File:  cut (X, BREAKS)
     Create categorical data out of numerical or continuous data by
     cutting into intervals.

     If BREAKS is a scalar, the data is cut into that many equal-width
     intervals.  If BREAKS is a vector of break points, the category
     has `length (BREAKS) - 1' groups.

     The returned value is a vector of the same size as X telling which
     group each point in X belongs to.  Groups are labelled from 1 to
     the number of groups; points outside the range of BREAKS are
     labelled by `NaN'.

 -- Function File:  cor (X, Y)
     The (I, J)-th entry of `cor (X, Y)' is the correlation between the
     I-th variable in X and the J-th variable in Y.

     For matrices, each row is an observation and each column a
     variable; vectors are always observations and may be row or column
     vectors.

     `cor (X)' is equivalent to `cor (X, X)'.

 -- Function File:  cloglog (X)
     Return the complementary log-log function of X, defined as

          - log (- log (X))

 -- Function File:  center (X)
 -- Function File:  center (X, DIM)
     If X is a vector, subtract its mean.  If X is a matrix, do the
     above for each column.  If the optional argument DIM is given,
     perform the above operation along this dimension


File: octave.info,  Node: Tests,  Next: Models,  Prev: Basic Statistical Functions,  Up: Statistics

25.2 Tests
==========

 -- Function File: [PVAL, F, DF_B, DF_W] = anova (Y, G)
     Perform a one-way analysis of variance (ANOVA).  The goal is to
     test whether the population means of data taken from K different
     groups are all equal.

     Data may be given in a single vector Y with groups specified by a
     corresponding vector of group labels G (e.g., numbers from 1 to
     K). This is the general form which does not impose any restriction
     on the number of data in each group or the group labels.

     If Y is a matrix and G is omitted, each column of Y is treated as
     a group.  This form is only appropriate for balanced ANOVA in
     which the numbers of samples from each group are all equal.

     Under the null of constant means, the statistic F follows an F
     distribution with DF_B and DF_W degrees of freedom.

     The p-value (1 minus the CDF of this distribution at F) is
     returned in PVAL.

     If no output argument is given, the standard one-way ANOVA table is
     printed.

 -- Function File: [PVAL, CHISQ, DF] = bartlett_test (X1, ...)
     Perform a Bartlett test for the homogeneity of variances in the
     data vectors X1, X2, ..., XK, where K > 1.

     Under the null of equal variances, the test statistic CHISQ
     approximately ollows a chi-square distribution with DF degrees of
     freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, CHISQ, DF] = chisquare_test_homogeneity (X,
          Y, C)
     Given two samples X and Y, perform a chisquare test for
     homogeneity of the null hypothesis that X and Y come from the same
     distribution, based on the partition induced by the (strictly
     increasing) entries of C.

     For large samples, the test statistic CHISQ approximately follows a
     chisquare distribution with DF = `length (C)' degrees of freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, CHISQ, DF] = chisquare_test_independence (X)
     Perform a chi-square test for indepence based on the contingency
     table X.  Under the null hypothesis of independence, CHISQ
     approximately has a chi-square distribution with DF degrees of
     freedom.

     The p-value (1 minus the CDF of this distribution at chisq) of the
     test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File:  cor_test (X, Y, ALT, METHOD)
     Test whether two samples X and Y come from uncorrelated
     populations.

     The optional argument string ALT describes the alternative
     hypothesis, and can be `"!="' or `"<>"' (non-zero), `">"' (greater
     than 0), or `"<"' (less than 0).  The default is the two-sided
     case.

     The optional argument string METHOD specifies on which correlation
     coefficient the test should be based.  If METHOD is `"pearson"'
     (default), the (usual) Pearson's product moment correlation
     coefficient is used.  In this case, the data should come from a
     bivariate normal distribution.  Otherwise, the other two methods
     offer nonparametric alternatives. If METHOD is `"kendall"', then
     Kendall's rank correlation tau is used.  If METHOD is
     `"spearman"', then Spearman's rank correlation rho is used.  Only
     the first character is necessary.

     The output is a structure with the following elements:

    PVAL
          The p-value of the test.

    STAT
          The value of the test statistic.

    DIST
          The distribution of the test statistic.

    PARAMS
          The parameters of the null distribution of the test statistic.

    ALTERNATIVE
          The alternative hypothesis.

    METHOD
          The method used for testing.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, F, DF_NUM, DF_DEN] = f_test_regression (Y, X,
          RR, R)
     Perform an F test for the null hypothesis rr * b = r in a classical
     normal regression model y = X * b + e.

     Under the null, the test statistic F follows an F distribution
     with DF_NUM and DF_DEN degrees of freedom.

     The p-value (1 minus the CDF of this distribution at F) is
     returned in PVAL.

     If not given explicitly, R = 0.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, TSQ] = hotelling_test (X, M)
     For a sample X from a multivariate normal distribution with unknown
     mean and covariance matrix, test the null hypothesis that `mean
     (X) == M'.

     Hotelling's T^2 is returned in TSQ.  Under the null, (n-p) T^2 /
     (p(n-1)) has an F distribution with p and n-p degrees of freedom,
     where n and p are the numbers of samples and variables,
     respectively.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, TSQ] = hotelling_test_2 (X, Y)
     For two samples X from multivariate normal distributions with the
     same number of variables (columns), unknown means and unknown
     equal covariance matrices, test the null hypothesis `mean (X) ==
     mean (Y)'.

     Hotelling's two-sample T^2 is returned in TSQ.  Under the null,

          (n_x+n_y-p-1) T^2 / (p(n_x+n_y-2))

     has an F distribution with p and n_x+n_y-p-1 degrees of freedom,
     where n_x and n_y are the sample sizes and p is the number of
     variables.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, KS] = kolmogorov_smirnov_test (X, DIST,
          PARAMS, ALT)
     Perform a Kolmogorov-Smirnov test of the null hypothesis that the
     sample X comes from the (continuous) distribution dist. I.e., if F
     and G are the CDFs corresponding to the sample and dist,
     respectively, then the null is that F == G.

     The optional argument PARAMS contains a list of parameters of
     DIST.  For example, to test whether a sample X comes from a
     uniform distribution on [2,4], use

          kolmogorov_smirnov_test(x, "uniform", 2, 4)

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative F != G.  In this case, the test
     statistic KS follows a two-sided Kolmogorov-Smirnov distribution.
     If ALT is `">"', the one-sided alternative F > G is considered.
     Similarly for `"<"', the one-sided alternative F > G is
     considered.  In this case, the test statistic KS has a one-sided
     Kolmogorov-Smirnov distribution.  The default is the two-sided
     case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, KS, D] = kolmogorov_smirnov_test_2 (X, Y, ALT)
     Perform a 2-sample Kolmogorov-Smirnov test of the null hypothesis
     that the samples X and Y come from the same (continuous)
     distribution.  I.e., if F and G are the CDFs corresponding to the
     X and Y samples, respectively, then the null is that F == G.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative F != G.  In this case, the test
     statistic KS follows a two-sided Kolmogorov-Smirnov distribution.
     If ALT is `">"', the one-sided alternative F > G is considered.
     Similarly for `"<"', the one-sided alternative F < G is
     considered.  In this case, the test statistic KS has a one-sided
     Kolmogorov-Smirnov distribution.  The default is the two-sided
     case.

     The p-value of the test is returned in PVAL.

     The third returned value, D, is the test statistic, the maximum
     vertical distance between the two cumulative distribution
     functions.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, K, DF] = kruskal_wallis_test (X1, ...)
     Perform a Kruskal-Wallis one-factor "analysis of variance".

     Suppose a variable is observed for K > 1 different groups, and let
     X1, ..., XK be the corresponding data vectors.

     Under the null hypothesis that the ranks in the pooled sample are
     not affected by the group memberships, the test statistic K is
     approximately chi-square with DF = K - 1 degrees of freedom.

     The p-value (1 minus the CDF of this distribution at K) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File:  manova (Y, G)
     Perform a one-way multivariate analysis of variance (MANOVA). The
     goal is to test whether the p-dimensional population means of data
     taken from K different groups are all equal.  All data are assumed
     drawn independently from p-dimensional normal distributions with
     the same covariance matrix.

     The data matrix is given by Y.  As usual, rows are observations
     and columns are variables.  The vector G specifies the
     corresponding group labels (e.g., numbers from 1 to K).

     The LR test statistic (Wilks' Lambda) and approximate p-values are
     computed and displayed.

 -- Function File: [PVAL, CHISQ, DF] = mcnemar_test (X)
     For a square contingency table X of data cross-classified on the
     row and column variables, McNemar's test can be used for testing
     the null hypothesis of symmetry of the classification
     probabilities.

     Under the null, CHISQ is approximately distributed as chisquare
     with DF degrees of freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = prop_test_2 (X1, N1, X2, N2, ALT)
     If X1 and N1 are the counts of successes and trials in one sample,
     and X2 and N2 those in a second one, test the null hypothesis that
     the success probabilities P1 and P2 are the same.  Under the null,
     the test statistic Z approximately follows a standard normal
     distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative P1 != P2.  If ALT is `">"', the
     one-sided alternative P1 > P2 is used.  Similarly for `"<"', the
     one-sided alternative P1 < P2 is used.  The default is the
     two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, CHISQ] = run_test (X)
     Perform a chi-square test with 6 degrees of freedom based on the
     upward runs in the columns of X.  Can be used to test whether X
     contains independent data.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, B, N] = sign_test (X, Y, ALT)
     For two matched-pair samples X and Y, perform a sign test of the
     null hypothesis PROB (X > Y) == PROB (X < Y) == 1/2.  Under the
     null, the test statistic B roughly follows a binomial distribution
     with parameters `N = sum (X != Y)' and P = 1/2.

     With the optional argument `alt', the alternative of interest can
     be selected.  If ALT is `"!="' or `"<>"', the null hypothesis is
     tested against the two-sided alternative PROB (X < Y) != 1/2.  If
     ALT is `">"', the one-sided alternative PROB (X > Y) > 1/2 ("x is
     stochastically greater than y") is considered.  Similarly for
     `"<"', the one-sided alternative PROB (X > Y) < 1/2 ("x is
     stochastically less than y") is considered.  The default is the
     two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test (X, M, ALT)
     For a sample X from a normal distribution with unknown mean and
     variance, perform a t-test of the null hypothesis `mean (X) == M'.
     Under the null, the test statistic T follows a Student
     distribution with `DF = length (X) - 1' degrees of freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != M'.  If ALT is
     `">"', the one-sided alternative `mean (X) > M' is considered.
     Similarly for "<", the one-sided alternative `mean (X) < M' is
     considered,  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test_2 (X, Y, ALT)
     For two samples x and y from normal distributions with unknown
     means and unknown equal variances, perform a two-sample t-test of
     the null hypothesis of equal means.  Under the null, the test
     statistic T follows a Student distribution with DF degrees of
     freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != mean (Y)'.  If ALT
     is `">"', the one-sided alternative `mean (X) > mean (Y)' is used.
     Similarly for `"<"', the one-sided alternative `mean (X) < mean
     (Y)' is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test_regression (Y, X, RR, R, ALT)
     Perform an t test for the null hypothesis `RR * B = R' in a
     classical normal regression model `Y = X * B + E'.  Under the
     null, the test statistic T follows a T distribution with DF
     degrees of freedom.

     If R is omitted, a value of 0 is assumed.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `RR * B != R'.  If ALT is `">"',
     the one-sided alternative `RR * B > R' is used.  Similarly for
     "<", the one-sided alternative `RR * B < R' is used.  The default
     is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = u_test (X, Y, ALT)
     For two samples X and Y, perform a Mann-Whitney U-test of the null
     hypothesis PROB (X > Y) == 1/2 == PROB (X < Y).  Under the null,
     the test statistic Z approximately follows a standard normal
     distribution.  Note that this test is equivalent to the Wilcoxon
     rank-sum test.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative PROB (X > Y) != 1/2.  If ALT is
     `">"', the one-sided alternative PROB (X > Y) > 1/2 is considered.
     Similarly for `"<"', the one-sided alternative PROB (X > Y) < 1/2
     is considered,  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, F, DF_NUM, DF_DEN] = var_test (X, Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and unknown variances, perform an F-test of the null
     hypothesis of equal variances.  Under the null, the test statistic
     f follows an F-distribution with df_num and df_den degrees of
     freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `var (X) != var (Y)'.  If ALT is
     `">"', the one-sided alternative `var (X) > var (Y)' is used.
     Similarly for "<", the one-sided alternative `var (X) > var (Y)'
     is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = welch_test (X, Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and unknown and not necessarily equal variances, perform a
     Welch test of the null hypothesis of equal means.  Under the null,
     the test statistic t approximately follows a Student distribution
     with df degrees of freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != M'.  If ALT is
     `">"', the one-sided alternative mean(x) > M is considered.
     Similarly for `"<"', the one-sided alternative mean(x) < M is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = wilcoxon_test (X, Y, ALT)
     For two matched-pair sample vectors X and Y, perform a Wilcoxon
     signed-rank test of the null hypothesis PROB (X > Y) == 1/2.
     Under the null, the test statistic Z approximately follows a
     standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative PROB (X > Y) != 1/2.  If alt is
     `">"', the one-sided alternative PROB (X > Y) > 1/2 is considered.
     Similarly for `"<"', the one-sided alternative PROB (X > Y) < 1/2
     is considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = z_test (X, M, V, ALT)
     Perform a Z-test of the null hypothesis `mean (X) == M' for a
     sample X from a normal distribution with unknown mean and known
     variance V.  Under the null, the test statistic Z follows a
     standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != M'.  If ALT is
     `">"', the one-sided alternative `mean (X) > M' is considered.
     Similarly for `"<"', the one-sided alternative `mean (X) < M' is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed along with some information.

 -- Function File: [PVAL, Z] = z_test_2 (X, Y, V_X, V_Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and known variances V_X and V_Y, perform a Z-test of the
     hypothesis of equal means.  Under the null, the test statistic Z
     follows a standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != mean (Y)'.  If alt
     is `">"', the one-sided alternative `mean (X) > mean (Y)' is used.
     Similarly for `"<"', the one-sided alternative `mean (X) < mean
     (Y)' is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed along with some information.


File: octave.info,  Node: Models,  Next: Distributions,  Prev: Tests,  Up: Statistics

25.3 Models
===========

 -- Functio File: [THETA, BETA, DEV, DL, D2L, P] = logistic_regression
          (Y, X, PRINT, THETA, BETA)
     Perform ordinal logistic regression.

     Suppose Y takes values in K ordered categories, and let `gamma_i
     (X)' be the cumulative probability that Y falls in one of the
     first I categories given the covariate X.  Then

          [theta, beta] = logistic_regression (y, x)

     fits the model

          logit (gamma_i (x)) = theta_i - beta' * x,   i = 1, ..., k-1

     The number of ordinal categories, K, is taken to be the number of
     distinct values of `round (Y)'.  If K equals 2, Y is binary and
     the model is ordinary logistic regression.  The matrix X is
     assumed to have full column rank.

     Given Y only, `theta = logistic_regression (y)' fits the model
     with baseline logit odds only.

     The full form is

          [theta, beta, dev, dl, d2l, gamma]
             = logistic_regression (y, x, print, theta, beta)

     in which all output arguments and all input arguments except Y are
     optional.

     Stting PRINT to 1 requests summary information about the fitted
     model to be displayed.  Setting PRINT to 2 requests information
     about convergence at each iteration.  Other values request no
     information to be displayed.  The input arguments THETA and BETA
     give initial estimates for THETA and BETA.

     The returned value DEV holds minus twice the log-likelihood.

     The returned values DL and D2L are the vector of first and the
     matrix of second derivatives of the log-likelihood with respect to
     THETA and BETA.

     P holds estimates for the conditional distribution of Y given X.


File: octave.info,  Node: Distributions,  Prev: Models,  Up: Statistics

25.4 Distributions
==================

 -- Function File:  beta_cdf (X, A, B)
     For each element of X, returns the CDF at X of the beta
     distribution with parameters A and B, i.e., PROB (beta (A, B) <=
     X).

 -- Function File:  beta_inv (X, A, B)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Beta distribution with parameters A and B.

 -- Function File:  beta_pdf (X, A, B)
     For each element of X, returns the PDF at X of the beta
     distribution with parameters A and B.

 -- Function File:  beta_rnd (A, B, R, C)
 -- Function File:  beta_rnd (A, B, SZ)
     Return an R by C or `size (SZ)' matrix of random samples from the
     Beta distribution with parameters A and B.  Both A and B must be
     scalar or of size R  by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  binomial_cdf (X, N, P)
     For each element of X, compute the CDF at X of the binomial
     distribution with parameters N and P.

 -- Function File:  binomial_inv (X, N, P)
     For each element of X, compute the quantile at X of the binomial
     distribution with parameters N and P.

 -- Function File:  binomial_pdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the binomial distribution with parameters N and P.

 -- Function File:  binomial_rnd (N, P, R, C)
 -- Function File:  binomial_rnd (N, P, SZ)
     Return an R by C  or a `size (SZ)' matrix of random samples from
     the binomial distribution with parameters N and P.  Both N and P
     must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of N and P.

 -- Function File:  cauchy_cdf (X, LAMBDA, SIGMA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Cauchy distribution with location
     parameter LAMBDA and scale parameter SIGMA.  Default values are
     LAMBDA = 0, SIGMA = 1.

 -- Function File:  cauchy_inv (X, LAMBDA, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Cauchy distribution with location parameter
     LAMBDA and scale parameter SIGMA.  Default values are LAMBDA = 0,
     SIGMA = 1.

 -- Function File:  cauchy_pdf (X, LAMBDA, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the Cauchy distribution with location parameter
     LAMBDA and scale parameter SIGMA > 0.  Default values are LAMBDA =
     0, SIGMA = 1.

 -- Function File:  cauchy_rnd (LAMBDA, SIGMA, R, C)
 -- Function File:  cauchy_rnd (LAMBDA, SIGMA, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the Cauchy distribution with parameters LAMBDA and SIGMA which
     must both be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of LAMBDA and SIGMA.

 -- Function File:  chisquare_cdf (X, N)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the chisquare distribution with N degrees
     of freedom.

 -- Function File:  chisquare_inv (X, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the chisquare distribution with N degrees of freedom.

 -- Function File:  chisquare_pdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the chisquare distribution with K degrees of freedom.

 -- Function File:  chisquare_rnd (N, R, C)
 -- Function File:  chisquare_rnd (N, SZ)
     Return an R by C  or a `size (SZ)' matrix of random samples from
     the chisquare distribution with N degrees of freedom.  N must be a
     scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the size
     of N.

 -- Function File:  discrete_cdf (X, V, P)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of a univariate discrete distribution which
     assumes the values in v with probabilities P.

 -- Function File:  discrete_inv (X, V, P)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the univariate distribution which assumes the values
     in V with probabilities P.

 -- Function File:  discrete_pdf (X, V, P)
     For each element of X, compute the probability density function
     (pDF) at X of a univariate discrete distribution which assumes the
     values in V with probabilities P.

 -- Function File:  discrete_rnd (N, V, P)
 -- Function File:  discrete_rnd (V, P, R, C)
 -- Function File:  discrete_rnd (V, P, SZ)
     Generate a row vector containing a random sample of size N from
     the univariate distribution which assumes the values in V with
     probabilities P. N must be a scalar.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  empirical_cdf (X, DATA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the empirical distribution obtained from
     the univariate sample DATA.

 -- Function File:  empirical_inv (X, DATA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File:  empirical_pdf (X, DATA)
     For each element of X, compute the probability density function
     (PDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File:  empirical_rnd (N, DATA)
 -- Function File:  empirical_rnd (DATA, R, C)
 -- Function File:  empirical_rnd (DATA, SZ)
     Generate a bootstrap sample of size N from the empirical
     distribution obtained from the univariate sample DATA.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  exponential_cdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the exponential distribution with parameter
     LAMBDA.

     The arguments can be of common size or scalar.

 -- Function File:  exponential_inv (X, LAMBDA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the exponential distribution with parameter LAMBDA.

 -- Function File:  exponential_pdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) of the exponential distribution with parameter LAMBDA.

 -- Function File:  exponential_rnd (LAMBDA, R, C)
 -- Function File:  exponential_rnd (LAMBDA, SZ)
     Return an R by C matrix of random samples from the exponential
     distribution with parameter LAMBDA, which must be a scalar or of
     size R by C. Or if SZ is a vector, create a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the size
     of LAMBDA.

 -- Function File:  f_cdf (X, M, N)
     For each element of X, compute the CDF at X of the F distribution
     with M and N degrees of freedom, i.e., PROB (F (M, N) <= X).

 -- Function File:  f_inv (X, M, N)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the F distribution with parameters M and N.

 -- Function File:  f_pdf (X, M, N)
     For each element of X, compute the probability density function
     (PDF) at X of the F distribution with M and N degrees of freedom.

 -- Function File:  f_rnd (M, N, R, C)
 -- Function File:  f_rnd (M, N, SZ)
     Return an R by C matrix of random samples from the F distribution
     with M and N degrees of freedom.  Both M and N must be scalar or
     of size R by C.  If SZ is a vector the random samples are in a
     matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of M and N.

 -- Function File:  gamma_cdf (X, A, B)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Gamma distribution with parameters A
     and B.

 -- Function File:  gamma_inv (X, A, B)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Gamma distribution with parameters A and B.

 -- Function File:  gamma_pdf (X, A, B)
     For each element of X, return the probability density function
     (PDF) at X of the Gamma distribution with parameters A and B.

 -- Function File:  gamma_rnd (A, B, R, C)
 -- Function File:  gamma_rnd (A, B, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the Gamma distribution with parameters A and B.  Both A and B must
     be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  geometric_cdf (X, P)
     For each element of X, compute the CDF at X of the geometric
     distribution with parameter P.

 -- Function File:  geometric_inv (X, P)
     For each element of X, compute the quantile at X of the geometric
     distribution with parameter P.

 -- Function File:  geometric_pdf (X, P)
     For each element of X, compute the probability density function
     (PDF) at X of the geometric distribution with parameter P.

 -- Function File:  geometric_rnd (P, R, C)
 -- Function File:  geometric_rnd (P, SZ)
     Return an R by C matrix of random samples from the geometric
     distribution with parameter P, which must be a scalar or of size R
     by C.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  hypergeometric_cdf (X, M, T, N)
     Compute the cumulative distribution function (CDF) at X of the
     hypergeometric distribution with parameters M, T, and N.  This is
     the probability of obtaining not more than X marked items when
     randomly drawing a sample of size N without replacement from a
     population of total size T containing M marked items.

     The parameters M, T, and N must positive integers with M and N not
     greater than T.

 -- Function File:  hypergeometric_inv (X, M, T, N)
     For each element of X, compute the quantile at X of the
     hypergeometric distribution with parameters M, T, and N.

     The parameters M, T, and N must positive integers with M and N not
     greater than T.

 -- Function File:  hypergeometric_pdf (X, M, T, N)
     Compute the probability density function (PDF) at X of the
     hypergeometric distribution with parameters M, T, and N. This is
     the probability of obtaining X marked items when randomly drawing
     a sample of size N without replacement from a population of total
     size T containing M marked items.

     The arguments must be of common size or scalar.

 -- Function File:  hypergeometric_rnd (N_SIZE, M, T, N)
 -- Function File:  hypergeometric_rnd (M, T, N, R, C)
 -- Function File:  hypergeometric_rnd (M, T, N, SZ)
     Generate a row vector containing a random sample of size N_SIZE
     from the hypergeometric distribution with parameters M, T, and N.

     If  R and C are given create a matrix with R rows and C columns.
     Or if SZ is a vector, create a matrix of size SZ.

     The parameters M, T, and N must positive integers with M and N not
     greater than T.

 -- Function File:  kolmogorov_smirnov_cdf (X, TOL)
     Return the CDF at X of the Kolmogorov-Smirnov distribution,
                   Inf
          Q(x) =   SUM    (-1)^k exp(-2 k^2 x^2)
                 k = -Inf

     for X > 0.

     The optional parameter TOL specifies the precision up to which the
     series should be evaluated;  the default is TOL = `eps'.

 -- Function File:  laplace_cdf (X)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Laplace distribution.

 -- Function File:  laplace_inv (X)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Laplace distribution.

 -- Function File:  laplace_pdf (X)
     For each element of X, compute the probability density function
     (PDF) at X of the Laplace distribution.

 -- Function File:  laplace_rnd (R, C)
 -- Function File:  laplace_rnd (SZ);
     Return an R by C matrix of random numbers from the Laplace
     distribution. Or is SZ is a vector, create a matrix of SZ.

 -- Function File:  logistic_cdf (X)
     For each component of X, compute the CDF at X of the logistic
     distribution.

 -- Function File:  logistic_inv (X)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the logistic distribution.

 -- Function File:  logistic_pdf (X)
     For each component of X, compute the PDF at X of the logistic
     distribution.

 -- Function File:  logistic_rnd (R, C)
 -- Function File:  logistic_rnd (SZ)
     Return an R by C matrix of random numbers from the logistic
     distribution. Or is SZ is a vector, create a matrix of SZ.

 -- Function File:  lognormal_cdf (X, A, V)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the lognormal distribution with parameters
     A and V.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean `log (A)' and variance
     V.

     Default values are A = 1, V = 1.

 -- Function File:  lognormal_inv (X, A, V)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the lognormal distribution with parameters A and V.
     If a random variable follows this distribution, its logarithm is
     normally distributed with mean `log (A)' and variance V.

     Default values are A = 1, V = 1.

 -- Function File:  lognormal_pdf (X, A, V)
     For each element of X, compute the probability density function
     (PDF) at X of the lognormal distribution with parameters A and V.
     If a random variable follows this distribution, its logarithm is
     normally distributed with mean `log (A)' and variance V.

     Default values are A = 1, V = 1.

 -- Function File:  lognormal_rnd (A, V, R, C)
 -- Function File:  lognormal_rnd (A, V, SZ)
     Return an R by C matrix of random samples from the lognormal
     distribution with parameters A and V. Both A and V must be scalar
     or of size R by C.  Or if SZ is a vector, create a matrix of size
     SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of A and V.

 -- Function File:  normal_cdf (X, M, V)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the normal distribution with mean M and
     variance V.

     Default values are M = 0, V = 1.

 -- Function File:  normal_inv (X, M, V)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the normal distribution with mean M and variance V.

     Default values are M = 0, V = 1.

 -- Function File:  normal_pdf (X, M, V)
     For each element of X, compute the probability density function
     (PDF) at X of the normal distribution with mean M and variance V.

     Default values are M = 0, V = 1.

 -- Function File:  normal_rnd (M, V, R, C)
 -- Function File:  normal_rnd (M, V, SZ)
     Return an R by C  or `size (SZ)' matrix of random samples from the
     normal distribution with parameters M and V.  Both M and V must be
     scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of M and V.

 -- Function File:  pascal_cdf (X, N, P)
     For each element of X, compute the CDF at x of the Pascal
     (negative binomial) distribution with parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  pascal_inv (X, N, P)
     For each element of X, compute the quantile at X of the Pascal
     (negative binomial) distribution with parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  pascal_pdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the Pascal (negative binomial) distribution with
     parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  pascal_rnd (N, P, R, C)
 -- Function File:  pascal_rnd (N, P, SZ)
     Return an R by C matrix of random samples from the Pascal
     (negative binomial) distribution with parameters N and P.  Both N
     and P must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of N and P. Or if SZ is a vector, create a matrix of
     size SZ.

 -- Function File:  poisson_cdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Poisson distribution with parameter
     lambda.

 -- Function File:  poisson_inv (X, LAMBDA)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Poisson distribution with parameter LAMBDA.

 -- Function File:  poisson_pdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) at X of the poisson distribution with parameter LAMBDA.

 -- Function File:  poisson_rnd (LAMBDA, R, C)
     Return an R by C matrix of random samples from the Poisson
     distribution with parameter LAMBDA, which must be a scalar or of
     size R by C.

     If R and C are omitted, the size of the result matrix is the size
     of LAMBDA.

 -- Function File:  stdnormal_cdf (X)
     For each component of X, compute the CDF of the standard normal
     distribution at X.

 -- Function File:  stdnormal_inv (X)
     For each component of X, compute compute the quantile (the inverse
     of the CDF) at X of the standard normal distribution.

 -- Function File:  stdnormal_pdf (X)
     For each element of X, compute the probability density function
     (PDF) of the standard normal distribution at X.

 -- Function File:  stdnormal_rnd (R, C)
 -- Function File:  stdnormal_rnd (SZ)
     Return an R by C or `size (SZ)' matrix of random numbers from the
     standard normal distribution.

 -- Function File:  t_cdf (X, N)
     For each element of X, compute the CDF at X of the t (Student)
     distribution with N degrees of freedom, i.e., PROB (t(N) <= X).

 -- Function File:  t_inv (X, N)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the t (Student) distribution with parameter N.

 -- Function File:  t_pdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the T (Student) distribution with N degrees of
     freedom.

 -- Function File:  t_rnd (N, R, C)
 -- Function File:  t_rnd (N, SZ)
     Return an R by C matrix of random samples from the t (Student)
     distribution with N degrees of freedom.  N must be a scalar or of
     size R by C. Or if SZ is a vector create a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the size
     of N.

 -- Function File:  uniform_cdf (X, A, B)
     Return the CDF at X of the uniform distribution on [A, B], i.e.,
     PROB (uniform (A, B) <= x).

     Default values are A = 0, B = 1.

 -- Function File:  uniform_inv (X, A, B)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the uniform distribution on [A, B].

     Default values are A = 0, B = 1.

 -- Function File:  uniform_pdf (X, A, B)
     For each element of X, compute the PDF at X of the uniform
     distribution on [A, B].

     Default values are A = 0, B = 1.

 -- Function File:  uniform_rnd (A, B, R, C)
 -- Function File:  uniform_rnd (A, B, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the uniform distribution on [A, B].  Both A and B must be scalar
     or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  weibull_cdf (X, ALPHA, SIGMA)
     Compute the cumulative distribution function (CDF) at X of the
     Weibull distribution with shape parameter ALPHA and scale
     parameter SIGMA, which is

          1 - exp(-(x/sigma)^alpha)

     for X >= 0.

 -- Function File:  weibull_inv (X, LAMBDA, ALPHA)
     Compute the quantile (the inverse of the CDF) at X of the Weibull
     distribution with shape parameter ALPHA and scale parameter SIGMA.

 -- Function File:  weibull_pdf (X, ALPHA, SIGMA)
     Compute the probability density function (PDF) at X of the Weibull
     distribution with shape parameter ALPHA and scale parameter SIGMA
     which is given by

             alpha * sigma^(-alpha) * x^(alpha-1) * exp(-(x/sigma)^alpha)

     for X > 0.

 -- Function File:  weibull_rnd (ALPHA, SIGMA, R, C)
 -- Function File:  weibull_rnd (ALPHA, SIGMA, SZ)
     Return an R by C matrix of random samples from the Weibull
     distribution with parameters ALPHA and SIGMA which must be scalar
     or of size R by C. Or if SZ is a vector return a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of ALPHA and SIGMA.

 -- Function File:  wiener_rnd (T, D, N)
     Return a simulated realization of the D-dimensional Wiener Process
     on the interval [0, T].  If D is omitted, D = 1 is used. The first
     column of the return matrix contains time, the remaining columns
     contain the Wiener process.

     The optional parameter N gives the number of summands used for
     simulating the process over an interval of length 1.  If N is
     omitted, N = 1000 is used.


File: octave.info,  Node: Financial Functions,  Next: Sets,  Prev: Statistics,  Up: Top

26 Financial Functions
**********************

 -- Function File:  fv (R, N, P, L, METHOD)
     Return the future value at the end of period N of an investment
     which consists of N payments of P in each period, assuming an
     interest rate R.

     The optional argument L may be used to specify an additional
     lump-sum payment.

     The optional argument METHOD may be used ot specify whether the
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  fvl (R, N, L)
     Return the future value at the end of N periods of an initial lump
     sum investment L, given a per-period interest rate R.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  irr (P, I)
     Return the internal rate of return of a series of payments P from
     an initial investment I (i.e., the solution of `npv (r, p) = i'.
     If the second argument is omitted, a value of 0 is used.

 -- Function File:  nper (R, P, A, L, METHOD)
     Return the number of regular payments of P necessary to amortize A
     loan of amount A and interest R.

     The optional argument L may be used to specify an additional
     lump-sum payment of L made at the end of the amortization time.

     The optional argument METHOD may be used to specify whether
     payments are made at the end ("E", default) or at the beginning
     ("B") of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  npv (R, P, I)
     Returns the net present value of a series of irregular (i.e., not
     necessarily identical) payments P which occur at the ends of N
     consecutive periods.  R specifies the one-period interest rates and
     can either be a scalar (constant rates) or a vector of the same
     length as P.

     The optional argument I may be used to specify an initial
     investment.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  pmt (R, N, A, L, METHOD)
     Return the amount of periodic payment necessary to amortize a loan
     of amount a with interest rate R in N periods.

     The optional argument L may be used to specify a terminal lump-sum
     payment.

     The optional argument METHOD may be used to specify whether
     payments are made at the end ("E", default) or at the beginning
     ("B") of each period.

 -- Function File:  pv (R, N, P, L, METHOD)
     Returns the present value of an investment that will pay off P for
     N consecutive periods, assuming an interest R.

     The optional argument L may be used to specify an additional
     lump-sum payment made at the end of N periods.

     The optional argument METHOD may be used to specify whether
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  pvl (R, N, P)
     Return the present value of an investment that will pay off P in
     one lump sum at the end of N periods, given the interest rate R.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  rate (N, P, V, L, METHOD)
     Return the rate of return on an investment of present value V which
     pays P in N consecutive periods.

     The optional argument L may be used to specify an additional
     lump-sum payment made at the end of N periods.

     The optional string argument METHOD may be used to specify whether
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

 -- Function File:  vol (X, M, N)
     Return the volatility of each column of the input matrix X.  The
     number of data sets per period is given by M (e.g. the number of
     data per year if you want to compute the volatility per year).
     The optional parameter N gives the number of past periods used for
     computation, if it is omitted, a value of 1 is used.  If T is the
     number of rows of X, `vol' returns the volatility from `n*m' to T.


File: octave.info,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Financial Functions,  Up: Top

27 Sets
*******

Octave has a limited set of functions for managing sets of data, where a
set is defined as a collection unique elements.

 -- Function File:  create_set (X)
     Return a row vector containing the unique values in X, sorted in
     ascending order.  For example,

          create_set ([ 1, 2; 3, 4; 4, 2 ])
          => [ 1, 2, 3, 4 ]

 -- Function File:  union (X, Y)
     Return the set of elements that are in either of the sets X and Y.
     For example,

          union ([ 1, 2, 4 ], [ 2, 3, 5 ])
          => [ 1, 2, 3, 4, 5 ]

 -- Function File:  intersection (X, Y)
     Return the set of elements that are in both sets X and Y.  For
     example,

          intersection ([ 1, 2, 3 ], [ 2, 3, 5 ])
          => [ 2, 3 ]

 -- Function File:  complement (X, Y)
     Return the elements of set Y that are not in set X.  For example,

          complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
          => 5


File: octave.info,  Node: Polynomial Manipulations,  Next: Control Theory,  Prev: Sets,  Up: Top

28 Polynomial Manipulations
***************************

In Octave, a polynomial is represented by its coefficients (arranged in
descending order).  For example, a vector  $c$ of length  N

     p(x) = C(1) x^N + ... + C(N) x + C(N+1).

 -- Function File:  compan (C)
     Compute the companion matrix corresponding to polynomial
     coefficient vector C.

     The companion matrix is

               _                                                        _
              |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(N)/c(1)  -c(N+1)/c(1)  |
              |       1            0      ...       0             0      |
              |       0            1      ...       0             0      |
          A = |       .            .   .            .             .      |
              |       .            .       .        .             .      |
              |       .            .           .    .             .      |
              |_      0            0      ...       1             0     _|

     The eigenvalues of the companion matrix are equal to the roots of
     the polynomial.

 -- Function File:  conv (A, B)
     Convolve two vectors.

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

 -- Function File:  deconv (Y, A)
     Deconvolve two vectors.

     `[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.

 -- Function File:  poly (A)
     If A is a square N-by-N matrix, `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.

 -- Function File:  polyderiv (C)
     Return the coefficients of the derivative of the polynomial whose
     coefficients are given by vector C.

 -- Function File: [P, S] = polyfit (X, Y, N)
     Return the coefficients of a polynomial P(X) of degree N that
     minimizes `sumsq (p(x(i)) - y(i))',  to best fit the data in the
     least squares sense.

     The polynomial coefficients are returned in a row vector.

     If two output arguments are requested, the second is a structure
     containing the following fields:

    `R'
          The Cholesky factor of the Vandermonde matrix used to compute
          the polynomial coefficients.

    `X'
          The Vandermonde matrix used to compute the polynomial
          coefficients.

    `df'
          The degrees of freedom.

    `normr'
          The norm of the residuals.

    `yf'
          The values of the polynomial for each value of X.

 -- Function File:  polyinteg (C)
     Return the coefficients of the integral of the polynomial whose
     coefficients are represented by the vector C.

     The constant of integration is set to zero.

 -- Function File:  polyreduce (C)
     Reduces a polynomial coefficient vector to a minimum number of
     terms by stripping off any leading zeros.

 -- Function File:  polyval (C, X)
     Evaluate a polynomial.

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

 -- Function File:  polyvalm (C, X)
     Evaluate a polynomial in the matrix sense.

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

 -- Function File:  residue (B, A, TOL)
     If B and A are vectors of polynomial coefficients, then residue
     calculates the partial fraction expansion corresponding to the
     ratio of the two polynomials.  

     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  P (s) and Q(s)  we have:

           P(s)    M       r(m)         N
           ---- = SUM -------------  + SUM k(i)*s^(N-i)
           Q(s)   m=1 (s-p(m))^e(m)    i=1

     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

                  s^2 + s + 1       -2        7        3
             ------------------- = ----- + ------- + -----
             s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)

 -- Function File:  roots (V)
     For a vector V with N components, return the roots of the
     polynomial

          v(1) * z^(N-1) + ... + v(N-1) * z + v(N)

 -- Function File:  polyout (C, X)
     Write formatted polynomial
             c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
      and return it as a string or write it to the screen (if NARGOUT
     is zero).  X defaults to the string `"s"'.


File: octave.info,  Node: Control Theory,  Next: Signal Processing,  Prev: Polynomial Manipulations,  Up: Top

29 Control Theory
*****************

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
   * R. Bruce Tenison <btenison@dibbs.net>,

   * David C. Clem,

   * John E. Ingram <John.Ingram@sea.siemans.com>, and

   * Kristi McGowan.
   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 `DEMOcontrol';
beginning OCST users should start with this program.

 -- Function File:  DEMOcontrol
     Octave Control Systems Toolbox demo/tutorial program.  The demo
     allows the user to select among several categories of OCST
     function:
          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.

* Menu:

* sysstruct::
* sysinterface::
* sysdisp::
* blockdiag::
* numerical::
* sysprop::
* systime::
* sysfreq::
* cacsd::
* misc::


File: octave.info,  Node: sysstruct,  Next: sysinterface,  Up: Control Theory

29.1 System Data Structure
==========================

* Menu:

* sysstructvars::
* sysstructtf::
* sysstructzp::
* sysstructss::

   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 (*note sysinterface::).  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.

 -- Function File:  sysrepdemo
     Tutorial for the use of the system data structure functions.


File: octave.info,  Node: sysstructvars,  Next: sysstructtf,  Up: sysstruct

29.1.1 Variables common to all OCST system formats
--------------------------------------------------

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'.
N
NZ
     The respective number of continuous and discrete states in the
     system (scalar)

INNAME
OUTNAME
     list of name(s) of the system input, output signal(s). (list of
     strings)

SYS
     System status vector.  (vector)

     This vector indicates both what representation was used to
     initialize the system data structure (called the primary system
     type) and which other representations are currently up-to-date
     with the primary system type (*note structaccess::).

     The value of the first element of the vector indicates the primary
     system type.

    0
          for tf form (initialized with `tf2sys' or `fir2sys')

    1
          for zp form (initialized with `zp2sys')

    2
          for ss form (initialized with `ss2sys')

     The next three elements are boolean flags that indicate whether
     tf, zp, or ss, respectively, are "up to date" (whether it is safe
     to use the variables associated with these representations).
     These flags are changed when calls are made to the `sysupdate'
     command.

TSAM
     Discrete time sampling period  (nonnegative scalar).   TSAM is set
     to 0 for continuous time systems.

YD
     Discrete-time output list (vector)

     indicates which outputs are discrete time (i.e.,     produced by
     D/A converters) and which are continuous time.      yd(ii) = 0 if
     output ii is continuous, = 1 if discrete.

   The remaining variables of the  system data structure are only
present if the corresponding entry of the `sys' vector is true (=1).


File: octave.info,  Node: sysstructtf,  Next: sysstructzp,  Prev: sysstructvars,  Up: sysstruct

29.1.2 `tf' format variables
----------------------------

NUM
     numerator coefficients   (vector)

DEN
     denominator coefficients   (vector)



File: octave.info,  Node: sysstructzp,  Next: sysstructss,  Prev: sysstructtf,  Up: sysstruct

29.1.3 `zp' format variables
----------------------------

ZER
     system zeros   (vector)

POL
     system poles    (vector)

K
     leading coefficient   (scalar)



File: octave.info,  Node: sysstructss,  Prev: sysstructzp,  Up: sysstruct

29.1.4 `ss' format variables
----------------------------

A
B
C
D
     The usual state-space matrices. If a system has both
     continuous and discrete states, they are sorted so that
     continuous states come first, then discrete states

     *Note* some functions (e.g., `bode', `hinfsyn') will not accept
     systems with both discrete and continuous states/outputs

STNAME
     names of system states   (list of strings)



File: octave.info,  Node: sysinterface,  Next: sysdisp,  Prev: sysstruct,  Up: Control Theory

29.2 System Construction and Interface Functions
================================================

Construction and manipulations of the OCST system data structure (*note
sysstruct::) 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 *Note sysdisp::.

* Menu:

* fir2sys::
* ss2sys::
* tf2sys::
* zp2sys::
* structaccess::
* structintern::


File: octave.info,  Node: fir2sys,  Next: ss2sys,  Up: sysinterface

29.2.1 Finite impulse response system interface functions
---------------------------------------------------------

 -- Function File:  fir2sys (NUM, TSAM, INNAME, OUTNAME)
     construct a system data structure from FIR description

     *Inputs*
    NUM
          vector of coefficients [c0, c1, ..., cn] of the SISO FIR
          transfer function C(z) = c0 + c1*z^(-1) + c2*z^(-2) + ... +
          cn*z^(-n)

    TSAM
          sampling time (default: 1)

    INNAME
          name of input signal;  may be a string or a list with a
          single entry.

    OUTNAME
          name of output signal; may be a string or a list with a
          single entry.

     *Output*
    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

 -- Function File: [C, TSAM, INPUT, OUTPUT] = sys2fir (SYS)
     Extract FIR data from system data structure; see `fir2sys' for
     parameter descriptions.


File: octave.info,  Node: ss2sys,  Next: tf2sys,  Prev: fir2sys,  Up: sysinterface

29.2.2 State space system interface functions
---------------------------------------------

 -- Function File:  ss (A, B, C, D, TSAM, N, NZ, STNAME, INNAME,
          OUTNAME, OUTLIST)
     Create system structure from state-space data.   May be continous,
     discrete, or mixed (sampled data)

     *Inputs*
    A
    B
    C
    D
          usual state space matrices.

          default: D = zero matrix

    TSAM
          sampling rate.  Default: tsam = 0 (continuous system)

    N
    NZ
          number of continuous, discrete states in the system

          If TSAM is 0, n = `rows'(A), nz = 0.

          If TSAM is greater than zero, n = 0, nz = `rows'(A)

          see below for system partitioning

    STNAME
          cell array of strings of state signal names

          default (STNAME=[] on input): `x_n' for continuous states,
          `xd_n' for discrete states

    INNAME
          cell array of strings of input signal names

          default (INNAME = [] on input): `u_n'

    OUTNAME
          cell array of strings of input signal names

          default (OUTNAME = [] on input): `y_n'

    OUTLIST
          list of indices of outputs y that are sampled

          If TSAM is 0, outlist = [].

          If TSAM is greater than 0, outlist = 1:`rows'(C).

     Unlike states, discrete/continous outputs may appear in any order.

     `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: d/dt xc(t)     = acc*xc(t)      +
     acd*xd(k*tsam) + bc*u(t)

     xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)

     yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)

     yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)

     *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 = ss (a, b, c, [], 0, 3, 0, {"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.

 -- Function File: [A, B, C, D, TSAM, N, NZ, STNAME, INNAME, OUTNAME,
YD] = sys2ss (SYS)
     Extract state space representation from system data structure.

     *Input*
    SYS
          System data structure.

     *Outputs*
    A
    B
    C
    D
          State space matrices for SYS.

    TSAM
          Sampling time of SYS (0 if continuous).

    N
    NZ
          Number of continuous, discrete states (discrete states come
          last in state vector X).

    STNAME
    INNAME
    OUTNAME
          Signal names (lists of strings);  names of states, inputs,
          and outputs, respectively.

    YD
          Binary vector; YD(II) is 1 if output Y(II) is discrete
          (sampled); otherwise  YD(II) is 0.

     A warning massage is printed if the system is a mixed continuous
     and discrete system.

     *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


File: octave.info,  Node: tf2sys,  Next: zp2sys,  Prev: ss2sys,  Up: sysinterface

29.2.3 Transfer function system interface functions
---------------------------------------------------

 -- Function File:  tf2sys (NUM, DEN, TSAM, INNAME, OUTNAME)
     Build system data structure from transfer function format data.

     *Inputs*
    NUM
    DEN
          Coefficients of numerator/denominator polynomials.

    TSAM
          Sampling interval; default: 0 (continuous time).

    INNAME
    OUTNAME
          Input/output signal names; may be a string or cell array with
          a single string entry.

     *Output*
    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

 -- Function File: [NUM, DEN, TSAM, INNAME, OUTNAME] = sys2tf (SYS)
     Extract transfer function data from a system data structure.

     See `tf' for parameter descriptions.

     *Example*
          octave:1> sys=ss([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


File: octave.info,  Node: zp2sys,  Next: structaccess,  Prev: tf2sys,  Up: sysinterface

29.2.4 Zero-pole system interface functions
-------------------------------------------

 -- Function File:  zp2sys (ZER, POL, K, TSAM, INNAME, OUTNAME)
     Create system data structure from zero-pole data.

     *Inputs*
    ZER
          Vector of system zeros.

    POL
          Vector of system poles.

    K
          Scalar leading coefficient.

    TSAM
          Sampling period; default: 0 (continuous system).

    INNAME
    OUTNAME
          Input/output signal names (lists of strings).

     *Output*
    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)

 -- Function File: [ZER, POL, K, TSAM, INNAME, OUTNAME] = sys2zp (SYS)
     Extract zero/pole/leading coefficient information from a system
     data structure.

     See `zp' for parameter descriptions.

     *Example*
          octave:1> sys=ss([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


File: octave.info,  Node: structaccess,  Next: structintern,  Prev: zp2sys,  Up: sysinterface

29.2.5 Data structure access functions
--------------------------------------

 -- Function File:  syschnames (SYS, OPT, LIST, NAMES)
     Superseded by `syssetsignals'.

 -- Function File:  syschtsam (SYS, TSAM)
     This function changes the sampling time (tsam) of the system.
     Exits with an error if sys is purely continuous time.

 -- Function File: [N, NZ, M, P, YD] = sysdimensions (SYS, OPT)
     return the number of states, inputs, and/or outputs in the system
     SYS.

     *Inputs*
    SYS
          system data structure

    OPT
          String indicating which dimensions are desired.  Values:
         `"all"'
               (default) return all parameters as specified under
               Outputs below.

         `"cst"'
               return N= number of continuous states

         `"dst"'
               return N= number of discrete states

         `"in"'
               return N= number of inputs

         `"out"'
               return N= number of outputs

     *Outputs*
    N
          number of continuous states (or individual requested
          dimension as specified by OPT).

    NZ
          number of discrete states

    M
          number of system inputs

    P
          number of system outputs

    YD
          binary vector; YD(II) is nonzero if output II is discrete.
          yd(ii) = 0 if output II is continous

 -- Function File: [STNAME, INNAME, OUTNAME, YD] = sysgetsignals (SYS)
 -- Function File: SIGLIST = sysgetsignals (SYS, SIGID)
 -- Function File: SIGNAME = sysgetsignals (SYS, SIGID, SIGNUM, STRFLG)
     Get signal names from a system

     *Inputs*
    SYS
          system data structure for the state space system

    SIGID
          signal id.  String.  Must be one of
         `"in"'
               input signals

         `"out"'
               output signals

         `"st"'
               stage signals

         `"yd"'
               value of logical vector YD

    SIGNUM
          index(indices) or name(s) or signals; see `sysidx'

    STRFLG
          flag to return a string instead of a cell array;  Values:
         `0'
               (default) return a cell array (even if signum specifies
               an individual signal)

         `1'
               return a string.  Exits with an error if signum does not
               specify an individual signal.


     *Outputs*
    *If SIGID is not specified:

         STNAME
         INNAME
         OUTNAME
               signal names (cell array of strings);  names of states,
               inputs, and outputs, respectively.

         YD
               binary vector; YD(II) is nonzero if output II is
               discrete.

    *If SIGID is specified but SIGNUM is not specified:

         `sigid="in"'
               SIGLIST is set to the cell array of input names.

         `sigid="out"'
               SIGLIST is set to the cell array of output names.

         `sigid="st"'
               SIGLIST is set to the cell array of state names.

               stage signals

         `sigid="yd"'
               SIGLIST is set to logical vector indicating discrete
               outputs; SIGLIST(II) = 0 indicates that output II is
               continuous (unsampled), otherwise it is discrete.


    *If the first three input arguments are specified:
          SIGNAME is a cell array of the specified signal names (SIGID
          is `"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=ss(rand(4),rand(4,2),rand(3,4));
          octave># get all signal names
          octave> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys)
          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> # get only input signal names:
          octave> Ain = sysgetsignals(sys,"in")
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          octave> # get name of output 2 (in cell array):
          octave> Aout = sysgetsignals(sys,"out",2)
          Aout =
          (
            [1] = y_2
          )
          octave> # get name of output 2 (as string):
          octave> Aout = sysgetsignals(sys,"out",2,1)
          Aout = y_2

 -- Function File:  sysgettype (SYS)
     return the initial system type of the system

     *Input*
    SYS
          System data structure.

     *Output*
    SYSTYPE
          String indicating how the structure was initially
          constructed. Values: `"ss"', `"zp"', or `"tf"'.

     FIR initialized systems return `systype="tf"'.

 -- Function File:  syssetsignals (SYS, OPT, NAMES, SIG_IDX)
     change the names of selected inputs, outputs and states.

     *Inputs*
    SYS
          System data structure.

    OPT
          Change default name (output).

         `"out"'
               Change selected output names.

         `"in"'
               Change selected input names.

         `"st"'
               Change selected state names.

         `"yd"'
               Change selected outputs from discrete to continuous or
               from continuous to discrete.

    NAMES

         `opt = "out", "in", "st"'
               string or string array containing desired signal names
               or values.

         `opt = "yd"'
               To desired output continuous/discrete flag.  Set name to
               0 for continuous, or 1 for discrete.

    SIG_IDX
          indices or names of outputs, yd, inputs, or states whose
          respective names/values should be changed.

          Default: replace entire cell array of names/entire yd vector.

     *Outputs*
    RETSYS
          SYS with appropriate signal names changed (or YD values,
          where appropriate).

     *Example*
          octave:1> sys=ss([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

 -- Function File:  sysupdate (SYS, OPT)
     Update the internal representation of a system.

     *Inputs*
    SYS:
          system data structure

    OPT
          string:
         `"tf"'
               update transfer function form

         `"zp"'
               update zero-pole form

         `"ss"'
               update state space form

         `"all"'
               all of the above

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

 -- Function File: [SYSTYPE, NOUT, NIN, NCSTATES, NDSTATES] = minfo
          (INMAT)
     Determines the type of system matrix.  INMAT can be a varying, a
     system, a constant, and an empty matrix.

     *Outputs*
    SYSTYPE
          Can be one of: varying, system, constant, and empty.

    NOUT
          The number of outputs of the system.

    NIN
          The number of inputs of the system.

    NCSTATES
          The number of continuous states of the system.

    NDSTATES
          The number of discrete states of the system.

 -- Function File:  sysgettsam (SYS)
     Return the sampling time of the system SYS.


File: octave.info,  Node: structintern,  Prev: structaccess,  Up: sysinterface

29.2.6 Data structure internal functions
----------------------------------------


File: octave.info,  Node: sysdisp,  Next: blockdiag,  Prev: sysinterface,  Up: Control Theory

29.3 System display functions
=============================

 -- Function File:  sysout (SYS, OPT)
     print out a system data structure in desired format
    SYS
          system data structure

    OPT
          Display option
         `[]'
               primary system form (default)

         `"ss"'
               state space form

         `"tf"'
               transfer function form

         `"zp"'
               zero-pole form

         `"all"'
               all of the above

 -- Function File:  tfout (NUM, DENOM, X)
     Print formatted transfer function n(s)/d(s) to the screen.  X
     defaults to the string `"s"'

 -- Function File:  zpout (ZER, POL, K, X)
     print formatted zero-pole form to the screen.  X defaults to the
     string `"s"'


File: octave.info,  Node: blockdiag,  Next: numerical,  Prev: sysdisp,  Up: Control Theory

29.4 Block Diagram Manipulations
================================

*Note systime::.

   Unless otherwise noted, all parameters (input,output) are system
data structures.

 -- Function File:  bddemo (INPUTS)
     Octave Controls toolbox demo: Block Diagram Manipulations demo.

 -- Function File:  buildssic (CLST, ULST, OLST, ILST, S1, S2, S3, S4,
          S5, S6, S7, S8)
     Form an arbitrary complex (open or closed loop) system in
     state-space form from several systems. `buildssic' can easily
     (despite its 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 H-2 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:
    CLST
          connection list, describes the input signal of each system.
          The maximum number of rows of Clst is equal to the sum of all
          inputs of s1-s8.

          Example: `[1 2 -1; 2 1 0]' means that:  new input 1 is old
          input 1 + output 2 - output 1, and new input 2 is old input 2
          + output 1. The order of rows is arbitrary.

    ULST
          if not empty the old inputs in vector ULST will be appended
          to the outputs. You need this if you want to "pull out" the
          input of a system. Elements are input numbers of S1-S8.

    OLST
          output list, specifiy the outputs of the resulting systems.
          Elements are output numbers of S1-S8.  The numbers are
          allowed to be negative and may appear in any order. An empty
          matrix means all outputs.

    ILST
          input list, specifiy the inputs of the resulting systems.
          Elements are input numbers of S1-S8.  The numbers are allowed
          to be negative and may appear in any order. An empty matrix
          means all inputs.

     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);

    CLST
          1st row: connect input 1 (G) with output 2 (K).

          2nd row: connect input 2 (K) with negative output 1 (G).

    ULST
          Append input of 2 (K) to the number of outputs.

    OLST
          Outputs are output of 1 (G), 2 (K) and appended output 3
          (from ULST).

    ILST
          The only input is 2 (K).

     Here is a real example:
                                   +----+
              -------------------->| W1 |---> v1
          z   |                    +----+
          ----|-------------+
              |             |
              |    +---+    v      +----+
              *--->| G |--->O--*-->| W2 |---> v2
              |    +---+       |   +----+
              |                |
              |                v
             u                  y

          min || GW   ||
                   vz   infty

     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);')

 -- Function File: SYS = jet707 ()
     Creates a linearized state-space model of a Boeing 707-321 aircraft
     at V=80 m/s (M = 0.26, GA0 = -3 deg, ALPHA0 = 4 deg, KAPPA = 50
     deg).

     System inputs: (1) thrust and (2) elevator angle.

     System outputs:  (1) airspeed and (2) pitch angle.

     *Reference*: R. Brockhaus: `Flugregelung' (Flight Control),
     Springer, 1994.

 -- Function File:  ord2 (NFREQ, DAMP, GAIN)
     Creates a continuous 2nd order system with parameters:

     *Inputs*
    NFREQ
          natural frequency [Hz]. (not in rad/s)

    DAMP
          damping coefficient

    GAIN
          dc-gain This is steady state value only for damp > 0.  gain
          is assumed to be 1.0 if ommitted.

     *Output*
    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)

 -- Function File:  sysadd (GSYS, HSYS)
     returns SYS = GSYS + HSYS.
        * Exits with an error if GSYS and HSYS are not compatibly
          dimensioned.

        * Prints a warning message is system states have identical
          names; duplicate names are given a suffix to make them unique.

        * SYS input/output names are taken from GSYS.

                    ________
               ----|  gsys  |---
          u   |    ----------  +|
          -----                (_)----> y
              |     ________   +|
               ----|  hsys  |---
                    --------

 -- Function File: SYS = sysappend (SYST, B, C, D, OUTNAME, INNAME, YD)
     appends new inputs and/or outputs to a system

     *Inputs*
    SYST
          system data structure

    B
          matrix to be appended to sys "B" matrix (empty if none)

    C
          matrix to be appended to sys "C" matrix (empty if none)

    D
          revised sys d matrix (can be passed as [] if the revised d is
          all zeros)

    OUTNAME
          list of names for new outputs

    INNAME
          list of names for new inputs

    YD
          binary vector; yd(ii)=0 indicates a continuous output;
          yd(ii)=1 indicates a discrete output.

     *Outputs*
    SYS
                  sys.b := [syst.b , b]
                  sys.c := [syst.c  ]
                           [ c     ]
                  sys.d := [syst.d | D12 ]
                           [ D21   | D22 ]
          where D12, D21, and D22 are the appropriate dimensioned
          blocks of the input parameter D.
             * The leading block D11 of D is ignored.

             * If INNAME and OUTNAME are not given as arguments,
               the new inputs and outputs are be assigned default names.

             * YD is a binary vector of length rows(c) that indicates
                 continuous/sampled outputs.  Default value for YD is:
                  - SYS is continuous or mixed YD = `zeros(1,rows(c))'

                  - SYS is discrete YD = `ones(1,rows(c))'

 -- Function File: CLSYS = sysconnect (SYS, OUT_IDX, IN_IDX, ORDER, TOL)
     Close the loop from specified outputs to respective specified
     inputs

     *Inputs*
    SYS
          System data structure.

    OUT_IDX
    IN_IDX
          Names or indices of signals to connect (see `sysidx').  The
          output specified by out_idx(ii) is connected to the input
          specified by in_idx(ii).

    ORDER
          logical flag (default = 0)
         `0'
               Leave inputs and outputs in their original order.

         `1'
               Permute inputs and outputs to the order shown in the
               diagram below.

    TOL
          Tolerance for singularities in algebraic loops, default:
          200`eps'.

     *Outputs*
    CLSYS
          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.

 -- Function File: [CSYS, ACD, CCD] = syscont (SYS)
     Extract the purely continuous subsystem of an input system.

     *Input*
    SYS
          system data structure.

     *Outputs*
    CSYS
          is the purely continuous input/output connections of SYS

    ACD
    CCD
          connections from discrete states to continuous states,
          discrete states to continuous outputs, respectively.

          returns CSYS empty if no continuous/continous path exists

 -- Function File: [DSYS, ADC, CDC] = sysdisc (SYS)
     *Input*
    SYS
          System data structure.

     *Outputs*
    DSYS
          Purely discrete portion of sys (returned empty if there is no
          purely discrete path from inputs to outputs).

    ADC
    CDC
          Connections from continuous states to discrete states and
          discrete.  outputs, respectively.

 -- Function File: RETSYS = sysdup (ASYS, OUT_IDX, IN_IDX)
     Duplicate specified input/output connections of a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX
    IN_IDX
          indices or names of desired signals (see `sigidx').
          duplicates are made of `y(out_idx(ii))' and `u(in_idx(ii))'.

     *Output*
    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)

 -- Function File: SYS = sysgroup (ASYS, BSYS)
     Combines two systems into a single system.

     *Inputs*
    ASYS
    BSYS
          System data structures.

     *Output*
    SYS
          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.

 -- Function File: SYS = sysmult (ASYS, BSYS)
     Compute sys = Asys*Bsys (series connection):
          u   ----------     ----------
          --->|  Bsys  |---->|  Asys  |--->
              ----------     ----------
     A warning occurs if there is direct feed-through from an input
     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).

 -- Function File: RETSYS = sysprune (ASYS, OUT_IDX, IN_IDX)
     Extract specified inputs/outputs from a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX
    IN_IDX
          Indices or signal names of the outputs and inputs to be kept
          in the returned system; remaining connections are "pruned"
          off.  May select as [] (empty matrix) to specify all
          outputs/inputs.

               retsys = sysprune (Asys, [1:3,4], "u_1");
               retsys = sysprune (Asys, {"tx", "ty", "tz"}, 4);


     *Output*
    RETSYS
          Resulting system.

                     ____________________
          u1 ------->|                  |----> y1
           (in_idx)  |       Asys       | (out_idx)
          u2 ------->|                  |----| y2
            (deleted)-------------------- (deleted)

 -- Function File: PV = sysreorder (VLEN, LIST)
     *Inputs*
    VLEN
          Vector length.

    LIST
          A subset of `[1:vlen]'.

     *Output*
    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.

 -- Function File: RETSYS = sysscale (SYS, OUTSCALE, INSCALE, OUTNAME,
          INNAME)
     scale inputs/outputs of a system.

     *Inputs*
    SYS
          Structured system.

    OUTSCALE
    INSCALE
          Constant matrices of appropriate dimension.

    OUTNAME
    INNAME
          Lists of strings with the names of respectively outputs and
          inputs.

     *Output*
    RETSYS
          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.

 -- Function File: SYS = syssub (GSYS, HSYS)
     Return sys = Gsys - Hsys.

     *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  |---+
                   +--------+

 -- Function File:  ugain (N)
     Creates a system with unity gain, no states.  This trivial system
     is sometimes needed to create arbitrary complex systems from
     simple systems with `buildssic'.  Watch out if you are forming
     sampled systems since `ugain' does not contain a sampling period.

 -- Function File: W = wgt1o (VL, VH, FC)
     State space description of a first order weighting function.

     Weighting function are needed by the H-2/H-infinity design
     procedure.  These function are part of the augmented plant P (see
     `hinfdemo' for an application example).

     *Inputs*
    VL
          Gain at low frequencies.

    VH
          Gain at high frequencies.

    FC
          Corner frequency (in Hz, *not* in rad/sec)

     *Output*
    W
          Weighting function, given in form of a system data structure.

 -- Function File: KSYS = parallel (ASYS, BSYS)
     Forms the parallel connection of two systems.

                       --------------------
                       |      --------    |
              u  ----->|----> | asys |--->|----> y1
                  |    |      --------    |
                  |    |      --------    |
                  |--->|----> | bsys |--->|----> y2
                       |      --------    |
                       --------------------
                            ksys

 -- Function File: [RETSYS, NC, NO] = sysmin (SYS, FLG)
     Returns a minimal (or reduced order) system

     *Inputs*
    SYS
          System data structure

    FLG
          When equal to 0 (default value), returns minimal system, in
          which state names are lost; when equal to 1, returns system
          with physical states removed that are either uncontrollable or
          unobservable (cannot reduce further without discarding
          physical meaning of states).
     *Outputs*
    RETSYS
          Returned system.

    NC
          Number of controllable states in the returned system.

    NO
          Number of observable states in the returned system.

    CFLG
          `is_controllable(retsys)'.

    OFLG
          `is_observable(retsys)'.


File: octave.info,  Node: numerical,  Next: sysprop,  Prev: blockdiag,  Up: Control Theory

29.5 Numerical Functions
========================

 -- Function File: X = are (A, B, C, OPT)
     Solve the Algebraic Riccati Equation
          a' * x + x * a - x * b * x + c = 0

     *Inputs* for identically dimensioned square matrices
    A
          N by N matrix;

    B
          N by N matrix or N by M matrix; in the latter case B is
          replaced by b:=b*b';

    C
          N by N matrix or P by M matrix; in the latter case C is
          replaced by c:=c'*c;

    OPT
          (optional argument; default = `"B"'): String option passed to
          `balance' prior to ordered Schur decomposition.

     *Output*
    X
          solution of the ARE.

     *Method* Laub's Schur method (IEEE Transactions on Automatic
     Control, 1979) is applied to the appropriate Hamiltonian matrix.


 -- Function File: X = dare (A, B, Q, R, OPT)
     Return the solution, X of the discrete-time algebraic Riccati
     equation
          a' x a - x + a' x b (r + b' x b)^(-1) b' x a + q = 0
     *Inputs*
    A
          N by N matrix;

    B
          N by M matrix;

    Q
          N by N matrix, symmetric positive semidefinite, or a P by N
          matrix, In the latter case q:=q'*q is used;

    R
          M by M, symmetric positive definite (invertible);

    OPT
          (optional argument; default = `"B"'): String option passed to
          `balance' prior to ordered QZ decomposition.

     *Output*
    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.


 -- Function File: [TVALS, PLIST] = dre (SYS, Q, R, QF, T0, TF, PTOL,
          MAXITS)
     Solve the differential Riccati equation
            -d P/dt = A'P + P A - P B inv(R) B' P + Q
            P(tf) = Qf
     for the LTI system sys.  Solution of standard LTI state feedback
     optimization
            min int(t0, tf) ( x' Q x + u' R u ) dt + x(tf)' Qf x(tf)
     optimal input is
            u = - inv(R) B' P(t) x
     *Inputs*
    SYS
          continuous time system data structure

    Q
          state integral penalty

    R
          input integral penalty

    QF
          state terminal penalty

    T0
    TF
          limits on the integral

    PTOL
          tolerance (used to select time samples; see below); default =
          0.1

    MAXITS
          number of refinement iterations (default=10)
     *Outputs*
    TVALS
          time values at which P(T) is computed

    PLIST
          list values of P(T); PLIST { I } is P(TVALS(I))
     TVALS is selected so that:
          || Plist{i} - Plist{i-1} || < Ptol
     for every I between 2 and length(TVALS).

 -- Function File:  dgram (A, B)
     Return controllability gramian of discrete time system
            x(k+1) = a x(k) + b u(k)

     *Inputs*
    A
          N by N matrix

    B
          N by M matrix

     *Output*
    M
          N by N matrix, satisfies M (N by N) satisfies
                a m a' - m + b*b' = 0

 -- Function File:  dlyap (A, B)
     Solve the discrete-time Lyapunov equation

     *Inputs*
    A
          N by N matrix;

    B
          Matrix: N by N, N by M, or P by N.

     *Output*
    X
          matrix satisfying appropriate discrete time Lyapunov equation.

     Options:
        * B is square: solve `a x a' - x + b = 0'

        * B is not square: X satisfies either
               a x a' - x + b b' = 0
          or
               a' x a - x + b' b = 0,
          whichever is appropriate.

     *Method* Uses Schur decomposition method as in Kitagawa, `An
     Algorithm for Solving the Matrix Equation X = F X F' + 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).

 -- Function File:  gram (A, B)
     Return controllability gramian M of the continuous time system
     dx/dt = a x + b u.

     M satisfies a m + m a' + b b' = 0.

 -- Function File:  lyap (A, B, C)
 -- Function File:  lyap (A, B)
     Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart
     algorithm (Communications of the ACM, 1972).

     If A, B, and C are specified, then `lyap' returns the solution of
     the  Sylvester equation
              a x + x b + c = 0
     If only `(a, b)' are specified, then `lyap' returns the solution
     of the Lyapunov equation
              a' x + x a + b = 0
     If B is not square, then `lyap' returns the solution of either
              a' x + x a + b' b = 0
     or
              a x + x a' + b b' = 0
     whichever is appropriate.

     Solves by using the Bartels-Stewart algorithm (1972).

 -- Function File:  qzval (A, B)
     Compute generalized eigenvalues of the matrix pencil
          (A - lambda B).

     A and B must be real matrices.

     `qzval' is obsolete; use `qz' instead.

 -- Function File: Y = zgfmul (A, B, C, D, X)
     Compute product of ZGEP incidence matrix F with vector X.  Used by
     `zgepbal' (in `zgscal') as part of generalized conjugate gradient
     iteration.

 -- Function File:  zgfslv (N, M, P, B)
     Solve system of equations for dense zgep problem.

 -- Function File: ZZ = zginit (A, B, C, D)
     Construct right hand side vector ZZ for the zero-computation
     generalized eigenvalue problem balancing procedure.  Called by
     `zgepbal'.

 -- Function File:  zgreduce (SYS, MEPS)
     Implementation of procedure REDUCE in (Emami-Naeini and Van Dooren,
     Automatica, # 1982).

 -- Function File: [NONZ, ZER] = zgrownorm (MAT, MEPS)
     Return NONZ = number of rows of MAT whose two norm exceeds MEPS,
     and ZER = number of rows of mat whose two norm is less than MEPS.

 -- Function File: X = zgscal (F, Z, N, M, P)
     Generalized conjugate gradient iteration to solve zero-computation
     generalized eigenvalue problem balancing equation fx=z; called by
     `zgepbal'.

 -- Function File: [a, b] = zgsgiv (C, S, A, B)
     Apply givens rotation c,s to row vectors A, B.  No longer used in
     zero-balancing (__zgpbal__); kept for backward compatibility.

 -- Function File: X = zgshsr (Y)
     Apply householder vector based on e^(m) to column vector Y.
     Called by `zgfslv'.

   *References*
*ZGEP*
     Hodel, `Computation of Zeros with Balancing', 1992, Linear Algebra
     and its Applications

**Generalized CG**
     Golub and Van Loan, `Matrix Computations, 2nd ed' 1989.


File: octave.info,  Node: sysprop,  Next: systime,  Prev: numerical,  Up: Control Theory

29.6 System Analysis-Properties
===============================

 -- Function File:  analdemo ()
     Octave Controls toolbox demo: State Space analysis demo

 -- Function File: [N, M, P] = abcddim (A, B, C, D)
     Check for compatibility of the dimensions of the matrices defining
     the linear system [A, B, C, D] corresponding to

          dx/dt = a x + b u
          y = c x + d u

     or a similar discrete-time system.

     If the matrices are compatibly dimensioned, then `abcddim' returns

    N
          The number of system states.

    M
          The number of system inputs.

    P
          The number of system outputs.

     Otherwise `abcddim' returns N = M = P = -1.

     Note: n = 0 (pure gain block) is returned without warning.


 -- Function File:  ctrb (SYS, B)
 -- Function File:  ctrb (A, B)
     Build controllability matrix:
                       2       n-1
          Qs = [ B AB A B ... A   B ]

     of a system data structure or the pair (A, B).

     `ctrb' forms the controllability matrix.  The numerical properties
     of `is_controllable' are much better for controllability tests.

 -- Function File:  h2norm (SYS)
     Computes the H-2 norm of a system data structure (continuous time
     only).

     Reference: Doyle, Glover, Khargonekar, Francis, `State-Space
     Solutions to Standard' `H-2 and H-infinity' `Control Problems',
     IEEE TAC August 1989.

 -- Function File: [G, GMIN, GMAX] = hinfnorm (SYS, TOL, GMIN, GMAX,
          PTOL)
     Computes the H-infinity norm of a system data structure.

     *Inputs*
    SYS
          system data structure

    TOL
          H-infinity norm search tolerance (default: 0.001)

    GMIN
          minimum value for norm search (default: 1e-9)

    GMAX
          maximum value for norm search (default: 1e+9)

    PTOL
          pole tolerance:
             * if sys is continuous, poles with  |real(pole))| <
               ptol*||H||  (H is appropriate Hamiltonian) are
               considered to be on the imaginary axis.

             * if sys is discrete, poles with |abs(pole)-1| <
               ptol*||[s1,s2]|| (appropriate symplectic pencil) are
               considered to be on the unit circle.

             * Default value: 1e-9

     *Outputs*
    G
          Computed gain, within TOL of actual gain.  G is returned as
          Inf if the system is unstable.

    GMIN
    GMAX
          Actual system gain lies in the interval [GMIN, GMAX].

     References: Doyle, Glover, Khargonekar, Francis, `State-space
     solutions to standard' `H-2 and H-infinity' `control problems',
     IEEE TAC August 1989; Iglesias and Glover, `State-Space approach
     to discrete-time' `H-infinity' `control', Int. J. Control, vol 54,
     no. 5, 1991; Zhou, Doyle, Glover, `Robust and Optimal Control',
     Prentice-Hall, 1996.

 -- Function File:  obsv (SYS, C)
 -- Function File:  obsv (A, C)
     Build observability matrix:
               | C        |
               | CA       |
          Qb = | CA^2     |
               | ...      |
               | CA^(n-1) |
     of a system data structure or the pair (A, C).

     The numerical properties of `is_observable' are much better for
     observability tests.

 -- Function File: [ZER, POL] = pzmap (SYS)
     Plots the zeros and poles of a system in the complex plane.

     *Input*
    SYS
          System data structure.

     *Outputs*
    POL

    ZER
          if omitted, the poles and zeros are plotted on the screen.
          otherwise, POL and ZER are returned as the system poles and
          zeros (see `sys2zp' for a preferable function call).

 -- Function File: RETVAL = is_abcd (A, B, C, D)
     Returns RETVAL = 1 if the dimensions of A, B, C, D are compatible,
     otherwise RETVAL = 0 with an  appropriate diagnostic message
     printed to the screen.  The matrices B, C, or D may be omitted.

 -- Function File: [RETVAL, U] = is_controllable (SYS, TOL)
 -- Function File: [RETVAL, U] = is_controllable (A, B, TOL)
     Logical check for system controllability.

     *Inputs*
    SYS
          system data structure

    A
    B
          N by N, N by M matrices, respectively

    TOL
          optional roundoff paramter.  default value: `10*eps'

     *Outputs*
    RETVAL
          Logical flag; returns true (1) if the system SYS or the pair
          (A, B) is controllable, whichever was passed as input
          arguments.

    U
          U is an orthogonal basis of the controllable subspace.

     *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'.

 -- Function File: RETVAL = is_detectable (A, C, TOL, DFLG)
 -- Function File: RETVAL = is_detectable (SYS, TOL)
     Test for detactability (observability of unstable modes) of (A, C).

     Returns 1 if the system A or the pair (A, C) is detectable, 0 if
     not, and -1 if the system has unobservable modes at the imaginary
     axis (unit circle for discrete-time systems).

     *See* `is_stabilizable' for detailed description of arguments and
     computational method.


 -- Function File: [RETVAL, DGKF_STRUCT ] = is_dgkf (ASYS, NU, NY, TOL )
     Determine whether a continuous time state space system meets
     assumptions of DGKF algorithm.  Partitions system into:
          [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*
    ASYS
          system data structure

    NU
          number of controlled inputs

    NY
          number of measured outputs

    TOL
          threshold for 0; default: 200*`eps'.
     *Outputs*
    RETVAL
          true(1) if system passes check, false(0) otherwise

    DGKF_STRUCT
          data structure of `is_dgkf' results.  Entries:
         NW
         NZ
               dimensions of W, Z

         A
               system A matrix

         BW
               (N x NW) QW-transformed disturbance input matrix

         BU
               (N x NU) RU-transformed controlled input matrix;

               B = [Bw Bu]

         CZ
               (NZ x N) Qz-transformed error output matrix

         CY
               (NY x N) RY-transformed measured output matrix

               C = [Cz; Cy]

         DZU

         DYW
               off-diagonal blocks of transformed system D matrix that
               enter Z, Y from U, W respectively

         RU
               controlled input transformation matrix

         RY
               observed output transformation matrix

         DYU_NZ
               nonzero if the DYU block is nonzero.

         DYU
               untransformed DYU block

         DFLG
               nonzero if the system is discrete-time
     `is_dgkf' exits with an error if the system is mixed
     discrete/continuous.

     *References*
    *[1]*
          Doyle, Glover, Khargonekar, Francis, `State Space Solutions
          to Standard' `H-2 and H-infinity' `Control Problems', IEEE
          TAC August 1989.

    *[2]*
          Maciejowksi, J.M., `Multivariable Feedback Design',
          Addison-Wesley, 1989.

 -- Function File: DIGITAL = is_digital (SYS, EFLG)
     Return nonzero if system is digital.

     *Inputs*
    SYS
          System data structure.

    EFLG
          When equal to 0 (default value), exits with an error if the
          system is mixed (continuous and discrete components); when
          equal to 1, print a warning if the system is mixed
          (continuous and discrete); when equal to 2, operate silently.

     *Output*
    DIGITAL
          When equal to 0, the system is purely continuous; when equal
          to 1, the system is purely discrete; when equal to -1, the
          system is mixed continuous and discrete.
     Exits with an error if SYS is a mixed (continuous and discrete)
     system.

 -- Function File: [RETVAL, U] = is_observable (A, C, TOL)
 -- Function File: [RETVAL, U] = is_observable (SYS, TOL)
     Logical check for system observability.

     Default: tol = `tol = 10*norm(a,'fro')*eps'

     Returns 1 if the system SYS or the pair (A, C) is observable, 0 if
     not.

     See `is_controllable' for detailed description of arguments and
     default values.

 -- Function File:  is_sample (TS)
     Return true if TS is a valid sampling time (real, scalar, > 0).

 -- Function File:  is_siso (SYS)
     Returns nonzero if the system data structure SYS is single-input,
     single-output.

 -- Function File: RETVAL = is_stabilizable (SYS, TOL)
 -- Function File: RETVAL = is_stabilizable (A, B, TOL, DFLG)
     Logical check for system stabilizability (i.e., all unstable modes
     are controllable).  Returns 1 if the system is stabilizable, 0 if
     the the system is not stabilizable, -1 if the system has non
     stabilizable modes at the imaginary axis (unit circle for
     discrete-time systems.

     Test for stabilizability is performed via Hautus Lemma. If DFLG!=0
     assume that discrete-time matrices (a,b) are supplied.

 -- Function File:  is_signal_list (MYLIST)
     Return true if MYLIST is a list of individual strings.

 -- Function File:  is_stable (A, TOL, DFLG)
 -- Function File:  is_stable (SYS, TOL)
     Returns 1 if the matrix A or the system SYS is stable, or 0 if not.

     *Inputs*
    TOL
          is a roundoff parameter, set to 200*`eps' if omitted.

    DFLG
          Digital system flag (not required for system data structure):
         `DFLG != 0'
               stable if eig(a) is in the unit circle

         `DFLG == 0'
               stable if eig(a) is in the open LHP (default)


File: octave.info,  Node: systime,  Next: sysfreq,  Prev: sysprop,  Up: Control Theory

29.7 System Analysis-Time Domain
================================

 -- Function File:  c2d (SYS, OPT, T)
 -- Function File:  c2d (SYS, T)
     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.

     *Inputs*
    SYS
          system data structure (may have both continuous time and
          discrete time subsystems)

    OPT
          string argument; conversion option (optional argument; may be
          omitted as shown above)
         `"ex"'
               use the matrix exponential (default)

         `"bi"'
               use the bilinear transformation
                        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.)

         `"matched"'
               Use the matched pole/zero equivalent transformation
               (currently only works for purely continuous SISO
               systems).

    T
          sampling time; required if SYS is purely continuous.

          *Note_* if the second argument is not a string, `c2d()'
          assumes that the second argument is T and performs
          appropriate argument checks.

     *Output*
    DSYS
          Discrete time equivalent via zero-order hold, sample each T
          sec.

     This function adds the suffix  `_d' to the names of the new
     discrete states.

 -- Function File:  d2c (SYS, TOL)
 -- Function File:  d2c (SYS, OPT)
     Convert a discrete (sub)system into a purely continuous one.  The
     sampling time used is `sysgettsam(SYS)'.

     *Inputs*
    SYS
          system data structure with discrete components

    TOL
          Scalar value.  Tolerance for convergence of default `"log"'
          option (see below)

    OPT
          conversion option.  Choose from:
         `"log"'
               (default) Conversion is performed via a matrix logarithm.
               Due to some problems with this computation, it is
               followed by a steepest descent algorithm to identify
               continuous time A, B, to get a better fit to the
               original data.

               If called as `d2c (SYS, TOL)', with TOL positive scalar,
               the `"log"' option is used.  The default value for TOL
               is `1e-8'.

         `"bi"'
               Conversion is performed via bilinear transform z = (1 +
               s T / 2)/(1 - s T / 2) where T is the system sampling
               time (see `sysgettsam').

               FIXME: bilinear option exits with an error if SYS is not
               purely discrete
     *Output*
    CSYS
          continuous time system (same dimensions and signal names as
          in SYS).

 -- Function File: [DSYS, FIDX] = dmr2d (SYS, IDX, SPREFIX, TS2, CUFLG)
     convert a multirate digital system to a single rate digital system
     states specified by IDX, SPREFIX are sampled at TS2, all others
     are assumed sampled at TS1 = `sysgettsam (SYS)'.

     *Inputs*
    SYS
          discrete time system; `dmr2d' exits with an error if SYS is
          not discrete

    IDX
          indices or names of states with sampling time
          `sysgettsam(SYS)' (may be empty); see `cellidx'

    SPREFIX
          list of string prefixes of states with sampling time
          `sysgettsam(SYS)' (may be empty)

    TS2
          sampling time of states not specified by IDX, SPREFIX must be
          an integer multiple of `sysgettsam(SYS)'

    CUFLG
          "constant u flag" if CUFLG is nonzero then the system inputs
          are assumed to be constant over the revised sampling interval
          TS2.  Otherwise, since the inputs can change during the
          interval T in [k ts2, (k+1) ts2], an additional set of inputs
          is included in the revised B matrix so that these intersample
          inputs may be included in the single-rate system.  default
          CUFLG = 1.

     *Outputs*
    DSYS
          equivalent discrete time system with sampling time TS2.

          The sampling time of sys is updated to TS2.

          if CUFLG=0 then a set of additional inputs is added to the
          system with suffixes _d1, ..., _dn to indicate their delay
          from the starting time k TS2, i.e.  u = [u_1; u_1_d1; ...,
          u_1_dn] where u_1_dk is the input k*ts1 units of time after
          u_1 is sampled. (TS1 is the original sampling time of the
          discrete time system and TS2 = (n+1)*ts1)

    FIDX
          indices of "formerly fast" states specified by IDX and
          SPREFIX; these states are updated to the new (slower)
          sampling interval TS2.

     *WARNING* Not thoroughly tested yet; especially when CUFLG == 0.

 -- Function File:  damp (P, TSAM)
     Displays eigenvalues, natural frequencies and damping ratios of
     the eigenvalues of a matrix P or the A matrix of a system P,
     respectively.  If P is a system, TSAM must not be specified.  If P
     is a matrix and TSAM is specified, eigenvalues of P are assumed to
     be in Z-domain.

 -- Function File:  dcgain (SYS, TOL)
     Returns dc-gain matrix. If dc-gain is infinite an empty matrix is
     returned.  The argument TOL is an optional tolerance for the
     condition number of the A Matrix in SYS (default TOL = 1.0e-10)

 -- Function File: [Y, T] = impulse (SYS, INP, TSTOP, N)
     Impulse response for a linear system.  The system can be discrete
     or multivariable (or both).  If no output arguments are specified,
     `impulse' produces a plot or the impulse response data for system
     SYS.

     *Inputs*
    SYS
          System data structure.

    INP
          Index of input being excited

    TSTOP
          The argument TSTOP (scalar value) denotes the time when the
          simulation should end.

    N
          the number of data values.

          Both parameters TSTOP and N can be omitted and will be
          computed from the eigenvalues of the A Matrix.
     *Outputs*
    Y
          Values of the impulse response.

    T
          Times of the impulse response.

 -- Function File: [Y, T] = step (SYS, INP, TSTOP, N)
     Step response for a linear system.  The system can be discrete or
     multivariable (or both).  If no output arguments are specified,
     `step' produces a plot or the step response data for system SYS.

     *Inputs*
    SYS
          System data structure.

    INP
          Index of input being excited

    TSTOP
          The argument TSTOP (scalar value) denotes the time when the
          simulation should end.

    N
          the number of data values.

          Both parameters TSTOP and N can be omitted and will be
          computed from the eigenvalues of the A Matrix.
     *Outputs*
    Y
          Values of the step response.

    T
          Times of the step response.

     When invoked with the output parameter Y the plot is not displayed.


File: octave.info,  Node: sysfreq,  Next: cacsd,  Prev: systime,  Up: Control Theory

29.8 System Analysis-Frequency Domain
=====================================

*Demonstration/tutorial script*

 -- Function File:  frdemo ()
     Octave Control Toolbox demo: Frequency Response demo.

 -- Function File: [MAG, PHASE, W] = bode (SYS, W, OUT_IDX, IN_IDX)
     If no output arguments are given: produce Bode plots of a system;
     otherwise, compute the frequency response of a system data
     structure

     *Inputs*
    SYS
          a system data structure (must be either purely continuous or
          discrete; see is_digital)

    W
          frequency values for evaluation.

          if SYS is continuous, then bode evaluates G(jw) where G(s) is
          the system transfer function.

          if SYS is discrete, then bode evaluates G(`exp'(jwT)), where
             * T is the system sampling time

             * G(z) is the system transfer function.

          *Default* the default frequency range is selected as follows:
          (These steps are *not* performed if W is specified)
            1. via routine __bodquist__, isolate all poles and zeros
               away from W=0 (JW=0 or `exp'(jwT)=1) and select the
               frequency range based on the breakpoint locations of the
               frequencies.

            2. if SYS is discrete time, the frequency range is limited
                           to jwT in [0,2 pi /T]

            3. A "smoothing" routine is used to ensure that the plot
               phase does not change excessively from point to point
               and that singular points (e.g., crossovers from +/- 180)
               are accurately shown.


    OUT_IDX
    IN_IDX
          The names or indices of outputs and inputs to be used in the
          frequency response.  See `sysprune'.

          *Example*
               bode(sys,[],"y_3", {"u_1","u_4"});
     *Outputs*
    MAG
    PHASE
          the magnitude and phase of the frequency response G(jw) or
          G(`exp'(jwT)) at the selected frequency values.

    W
          the vector of frequency values used

       1. If no output arguments are given, e.g.,
               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 = []').

       2. If the requested plot is for an MIMO system, mag is set to
          ||G(jw)|| or ||G(`exp'(jwT))|| and phase information is not
          computed.

 -- Function File: [WMIN, WMAX] = bode_bounds (ZER, POL, DFLG, TSAM)
     Get default range of frequencies based on cutoff frequencies of
     system poles and zeros.  Frequency range is the interval [10^WMIN,
     10^WMAX]

     Used internally in `__freqresp__' (`bode', `nyquist')

 -- Function File:  freqchkw (W)
     Used by `__freqresp__' to check that input frequency vector W is
     valid.  Returns boolean value.

 -- Function File: OUT = ltifr (A, B, W)
 -- Function File: OUT = ltifr (SYS, W)
     Linear time invariant frequency response of single-input systems.

     *Inputs*
    A
    B
          coefficient matrices of dx/dt = A x + B u

    SYS
          system data structure

    W
          vector of frequencies
     *Output*
    OUT
          frequency response, that is:

                                     -1
                       G(s) = (jw I-A) B
     for complex frequencies s = jw.

 -- Function File: [REALP, IMAGP, W] = nyquist (SYS, W, OUT_IDX,
          IN_IDX, ATOL)
 -- Function File:  nyquist (SYS, W, OUT_IDX, IN_IDX, ATOL)
     Produce Nyquist plots of a system; if no output arguments are
     given, Nyquist plot is printed to the screen.

     Compute the frequency response of a system.

     *Inputs* (pass as empty to get default values)
    SYS
          system data structure (must be either purely continuous or
          discrete; see `is_digital')

    W
          frequency values for evaluation.  If sys is continuous, then
          bode evaluates G(JW); if sys is discrete, then bode evaluates
          G(exp(JWT)), where T is the system sampling time.

    DEFAULT
          the default frequency range is selected as follows: (These
          steps are *not* performed if W is specified)
            1. via routine `__bodquist__', isolate all poles and zeros
               away from W=0 (JW=0 or exp(JWT)=1) and select the
               frequency range based on the breakpoint locations of the
               frequencies.

            2. if SYS is discrete time, the frequency range is limited
               to JWT in [0,2p*pi]

            3. A "smoothing" routine is used to ensure that the plot
               phase does not change excessively from point to point
               and that singular points (e.g., crossovers from +/- 180)
               are accurately shown.

    ATOL
          for interactive nyquist plots: atol is a change-in-slope
          tolerance for the of asymptotes (default = 0; 1e-2 is a good
          choice).  This allows the user to "zoom in" on portions of
          the Nyquist plot too small to be seen with large asymptotes.
     *Outputs*
    REALP
    IMAGP
          the real and imaginary parts of the frequency response G(jw)
          or G(exp(jwT)) at the selected frequency values.

    W
          the vector of frequency values used

     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.

 -- Function File: [ZER, GAIN] = tzero (A, B, C, D, OPT)
 -- Function File: [ZER, GAIN] = tzero (SYS, OPT)
     Compute transmission zeros of a continuous system:
          .
          x = Ax + Bu
          y = Cx + Du
     or of a discrete one:
          x(k+1) = A x(k) + B u(k)
          y(k)   = C x(k) + D u(k)

     *Outputs*
    ZER
          transmission zeros of the system

    GAIN
          leading coefficient (pole-zero form) of SISO transfer function
          returns gain=0 if system is multivariable
     *References*
       1. Emami-Naeini and Van Dooren, Automatica, 1982.

       2. Hodel, `Computation of Zeros with Balancing', 1992 Lin. Alg.
          Appl.

 -- Function File: ZR = tzero2 (A, B, C, D, BAL)
     Compute the transmission zeros of A, B, C, D.

     BAL = balancing option (see balance); default is `"B"'.

     Needs to incorporate `mvzero' algorithm to isolate finite zeros;
     use `tzero' instead.


File: octave.info,  Node: cacsd,  Next: misc,  Prev: sysfreq,  Up: Control Theory

29.9 Controller Design
======================

 -- Function File:  dgkfdemo ()
     Octave Controls toolbox demo: H-2/H-infinity options demos.

 -- Function File:  hinfdemo ()
     H-infinity design demos for continuous SISO and MIMO systems and a
     discrete system.  The SISO system is difficult to control because
     it is non-minimum-phase and unstable. The second design example
     controls the `jet707' plant, the linearized state space model of a
     Boeing 707-321 aircraft at V=80 m/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
     discrete system is a stable and second order.

    SISO plant:
                               s - 2
                    G(s) = --------------
                           (s + 2)(s - 1)


                                             +----+
                        -------------------->| W1 |---> v1
                    z   |                    +----+
                    ----|-------------+
                        |             |
                        |    +---+    v   y  +----+
                      u *--->| G |--->O--*-->| W2 |---> v2
                        |    +---+       |   +----+
                        |                |
                        |    +---+       |
                        -----| K |<-------
                             +---+

               min || T   ||
                       vz   infty

          W1 und W2 are the robustness and performance weighting
          functions.

    MIMO plant:
          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                       y (to K)
                        (from controller K)

                                 +    +           +    +
                                 | z  |           | w  |
                                 |  1 |           |  1 |
                                 | z  | = [ P ] * | w  |
                                 |  2 |           |  2 |
                                 | y  |           | u  |
                                 +    +           +    +

    Discrete system:
          This is not a true discrete design. The design is carried out
          in continuous time while the effect of sampling is described
          by a bilinear transformation of the sampled system.  This
          method works quite well if the sampling period is "small"
          compared to the plant time constants.

    The continuous plant:
                                  1
                    G (s) = --------------
                     k      (s + 2)(s + 1)

          is discretised with a ZOH (Sampling period = TS = 1 second):

                              0.199788z + 0.073498
                    G(z) = --------------------------
                           (z - 0.36788)(z - 0.13534)


                                             +----+
                        -------------------->| W1 |---> v1
                    z   |                    +----+
                    ----|-------------+
                        |             |
                        |    +---+    v      +----+
                        *--->| G |--->O--*-->| W2 |---> v2
                        |    +---+       |   +----+
                        |                |
                        |    +---+       |
                        -----| K |<-------
                             +---+

               min || T   ||
                       vz   infty
          W1 and W2 are the robustness and performance weighting
          functions.

 -- Function File: [L, M, P, E] = dlqe (A, G, C, SIGW, SIGV, Z)
     Construct the linear quadratic estimator (Kalman filter) for the
     discrete time system

          x[k+1] = A x[k] + B u[k] + G w[k]
            y[k] = C x[k] + D u[k] + v[k]

     where W, V are zero-mean gaussian noise processes with respective
     intensities `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

          z[k|k] = z[k|k-1] + L (y[k] - C z[k|k-1] - D u[k])
          z[k+1|k] = A z[k|k] + B u[k]

     The following values are returned:

    L
          The observer gain, (A - ALC).  is stable.

    M
          The Riccati equation solution.

    P
          The estimate error covariance after the measurement update.

    E
          The closed loop poles of (A - ALC).

 -- Function File: [K, P, E] = dlqr (A, B, Q, R, Z)
     Construct the linear quadratic regulator for the discrete time
     system

          x[k+1] = A x[k] + B u[k]

     to minimize the cost functional

          J = Sum (x' Q x + u' R u)

     Z omitted or

          J = Sum (x' Q x + u' R u + 2 x' Z u)

     Z included.

     The following values are returned:

    K
          The state feedback gain, (A - BK) is stable.

    P
          The solution of algebraic Riccati equation.

    E
          The closed loop poles of (A - BK).

 -- Function File: [LP, LF, P, Z] = dkalman (A, G, C, QW, RV, S)
     Construct the linear quadratic estimator (Kalman predictor) for the
     discrete time system

          x[k+1] = A x[k] + B u[k] + G w[k]
            y[k] = C x[k] + D u[k] + v[k]

     where W, V are zero-mean gaussian noise processes with respective
     intensities `QW = cov (W, W)' and `RV = cov (V, V)'.

     If specified, S is `cov (W, V)'.  Otherwise `cov (W, V) = 0'.

     The observer structure is

          x[k+1|k] = A x[k|k-1] + B u[k] + LP (y[k] - C x[k|k-1] - D u[k])
          x[k|k] = x[k|k-1] + LF (y[k] - C x[k|k-1] - D u[k])

     The following values are returned:

    LP
          The predictor gain, (A - LP C) is stable.

    LF
          The filter gain.

    P
          The Riccati solution.

          P = E [(x - x[n|n-1])(x - x[n|n-1])']

    Z
          The updated error covariance matrix.

          Z = E [(x - x[n|n])(x - x[n|n])']

 -- Function File: [K, GAIN, KC, KF, PC, PF] =  h2syn (ASYS, NU, NY,
          TOL)
     Design H-2 optimal controller per procedure in Doyle, Glover,
     Khargonekar, Francis, `State-Space Solutions to Standard' `H-2 and
     H-infinity' `Control Problems', IEEE TAC August 1989.

     Discrete-time control per Zhou, Doyle, and Glover, `Robust and
     optimal control', Prentice-Hall, 1996.

     *Inputs*
    ASYS
          system data structure (see ss, sys2ss)
             * controller is implemented for continuous time systems

             * controller is *not* implemented for discrete time systems

    NU
          number of controlled inputs

    NY
          number of measured outputs

    TOL
          threshold for 0.  Default: 200*`eps'

     *Outputs*
    K
          system controller

    GAIN
          optimal closed loop gain

    KC
          full information control (packed)

    KF
          state estimator (packed)

    PC
          ARE solution matrix for regulator subproblem

    PF
          ARE solution matrix for filter subproblem

 -- Function File: K = hinf_ctr (DGS, F, H, Z, G)
     Called by `hinfsyn' to compute the H-infinity optimal controller.

     *Inputs*
    DGS
          data structure returned by `is_dgkf'

    F
    H
          feedback and filter gain (not partitioned)

    G
          final gamma value
     *Outputs*
    K
          controller (system data structure)

     Do not attempt to use this at home; no argument checking performed.

 -- Function File: [K, G, GW, XINF, YINF] = hinfsyn (ASYS, NU, NY,
          GMIN, GMAX, GTOL, PTOL, TOL)
     *Inputs* input system is passed as either
    ASYS
          system data structure (see `ss', `sys2ss')
             * controller is implemented for continuous time systems

             * controller is *not* implemented for discrete time
               systems  (see bilinear transforms in `c2d', `d2c')

    NU
          number of controlled inputs

    NY
          number of measured outputs

    GMIN
          initial lower bound on H-infinity optimal gain

    GMAX
          initial upper bound on H-infinity Optimal gain.

    GTOL
          Gain threshold.  Routine quits when GMAX/GMIN < 1+tol.

    PTOL
          poles with `abs(real(pole))' < ptol*||H|| (H is appropriate
          Hamiltonian) are considered to be on the imaginary axis.
          Default: 1e-9.

    TOL
          threshold for 0.  Default: 200*`eps'.

          GMAX, MIN, TOL, and TOL must all be postive scalars.
     *Outputs*
    K
          System controller.

    G
          Designed gain value.

    GW
          Closed loop system.

    XINF
          ARE solution matrix for regulator subproblem.

    YINF
          ARE solution matrix for filter subproblem.

     References:
       1. Doyle, Glover, Khargonekar, Francis, `State-Space Solutions
          to Standard' `H-2 and H-infinity' `Control Problems', IEEE
          TAC August 1989.

       2. Maciejowksi, J.M., `Multivariable feedback design',
          Addison-Wesley, 1989, ISBN 0-201-18243-2.

       3. Keith Glover and John C. Doyle, `State-space formulae for all
          stabilizing controllers that satisfy an' `H-infinity-norm'
          `bound and relations to risk sensitivity', Systems & Control
          Letters 11, Oct. 1988, pp 167-172.

 -- Function File: [RETVAL, PC, PF] = hinfsyn_chk (A, B1, B2, C1, C2,
          D12, D21, G, PTOL)
     Called by `hinfsyn' to see if gain G satisfies conditions in
     Theorem 3 of Doyle, Glover, Khargonekar, Francis, `State Space
     Solutions to Standard' `H-2 and H-infinity' `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:
    G
          candidate gain level

    PTOL
          as in `hinfsyn'

     *Outputs*
    RETVAL
          1 if g exceeds optimal Hinf closed loop gain, else 0

    PC
          solution of "regulator" H-infinity ARE

    PF
          solution of "filter" H-infinity ARE
     Do not attempt to use this at home; no argument checking performed.

 -- Function File: [XINF, X_HA_ERR] = hinfsyn_ric (A, BB, C1, D1DOT, R,
          PTOL)
     Forms
          xx = ([bb; -c1'*d1dot]/r) * [d1dot'*c1 bb'];
          Ha = [a 0*a; -c1'*c1 - a'] - xx;
     and solves associated Riccati equation.  The error code X_HA_ERR
     indicates one of the following conditions:
    0
          successful

    1
          XINF has imaginary eigenvalues

    2
          HX not Hamiltonian

    3
          XINF has infinite eigenvalues (numerical overflow)

    4
          XINF not symmetric

    5
          XINF not positive definite

    6
          R is singular

 -- Function File: [K, P, E] = lqe (A, G, C, SIGW, SIGV, Z)
     Construct the linear quadratic estimator (Kalman filter) for the
     continuous time system

          dx
          -- = a x + b u
          dt

          y = c x + d u

     where W and V are zero-mean gaussian noise processes with
     respective intensities

          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:

    K
          The observer gain, (A - KC) is stable.

    P
          The solution of algebraic Riccati equation.

    E
          The vector of closed loop poles of (A - KC).

 -- Function File: [K, Q1, P1, EE, ER] = lqg (SYS, SIGW, SIGV, Q, R,
          IN_IDX)
     Design a linear-quadratic-gaussian optimal controller for the
     system
          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*
    SYS
          system data structure

    SIGW
    SIGV
          intensities of independent Gaussian noise processes (as above)

    Q
    R
          state, control weighting respectively.  Control ARE is

    IN_IDX
          names or indices of controlled inputs (see `sysidx',
          `cellidx')

          default: last dim(R) inputs are assumed to be controlled
          inputs, all others are assumed to be noise inputs.
     *Outputs*
    K
          system data structure format LQG optimal controller (Obtain
          A, B, C matrices with `sys2ss', `sys2tf', or `sys2zp' as
          appropriate).

    P1
          Solution of control (state feedback) algebraic Riccati
          equation.

    Q1
          Solution of estimation algebraic Riccati equation.

    EE
          Estimator poles.

    ES
          Controller poles.

 -- Function File: [K, P, E] = lqr (A, B, Q, R, Z)
     construct the linear quadratic regulator for the continuous time
     system

          dx
          -- = A x + B u
          dt

     to minimize the cost functional

                infinity
                /
            J = |  x' Q x + u' R u
               /
              t=0

     Z omitted or

                infinity
                /
            J = |  x' Q x + u' R u + 2 x' Z u
               /
              t=0

     Z included.

     The following values are returned:

    K
          The state feedback gain, (A - BK) is stable and minimizes the
          cost functional

    P
          The stabilizing solution of appropriate algebraic Riccati
          equation.

    E
          The vector of the closed loop poles of (A - BK).

     *Reference* Anderson and Moore, `Optimal control: linear quadratic
     methods', Prentice-Hall, 1990, pp. 56-58.

 -- Function File: [Y, X] = lsim (SYS, U, T, X0)
     Produce output for a linear simulation of a system; produces a
     plot for the output of the system, SYS.

     U is an array that contains the system's inputs.  Each row in U
     corresponds to a different time step.  Each column 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 a plot is not displayed;
     however, the data is returned in Y (system output) and X (system
     states).

 -- Function File: K = place (SYS, P)
     Computes the matrix K such that if the state is feedback with gain
     K, then the eigenvalues  of the closed loop system (i.e. A-BK) are
     those specified in the vector P.

     Version: Beta (May-1997): If you have any comments, please let me
     know.  (see the file place.m for my address)


File: octave.info,  Node: misc,  Prev: cacsd,  Up: Control Theory

29.10 Miscellaneous Functions (Not yet properly filed/documented)
=================================================================

 -- Function File:  axis2dlim (AXDATA)
     Determine axis limits for 2-D data (column vectors); leaves a 10%
     margin around the plots.  Inserts margins of +/- 0.1 if data is
     one-dimensional (or a single point).

     *Input*
    AXDATA
          N by 2 matrix of data [X, Y].

     *Output*
    AXVEC
          Vector of axis limits appropriate for call to `axis' function.

 -- Function File:  moddemo (INPUTS)
     Octave Control toolbox demo: Model Manipulations demo.

 -- Function File:  prompt (STR)
     Prompt user to continue

     *Input*
    STR
          Input string. Its default value is:
               \n ---- Press a key to  continue ---

 -- Function File:  rldemo (INPUTS)
     Octave Control toolbox demo: Root Locus demo.

 -- Function File: [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
          Minimum value of K

    MAX_K
          Maximum value of K

    INCREMENT
          The increment used in computing gain values

     *Outputs*

     Plots the root locus to the screen.
    RLDATA
          Data points plotted: in column 1 real values, in column 2 the
          imaginary values.

    K
          Gains for real axis break points.

 -- Function File: [YY, IDX] = sortcom (XX[, OPT])
     Sort a complex vector.

     *Inputs*
    XX
          Complex vector

    OPT
          sorting option:
         `"re"'
               Real part (default);

         `"mag"'
               By magnitude;

         `"im"'
               By imaginary part.
          if OPT is not chosen as `"im"', then complex conjugate pairs
          are grouped together, a - jb followed by a + jb.

     *Outputs*
    YY
          Sorted values

    IDX
          Permutation vector: `yy = xx(idx)'

 -- Function File: [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.

 -- Function File: [POL, ZER, K] = ss2zp (A, B, C, D)
     Converts a state space representation to a set of poles and zeros;
     K is a gain associated with the zeros.

     Used internally in system data structure format manipulations.

 -- Function File:  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 (i.e. negative feedback).

 -- Function File: [A, B, C, D] = tf2ss (NUM, DEN)
     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)

     The vector DEN must contain only one row, whereas the vector NUM
     may contain as many rows as there are outputs Y of the system. The
     state space system matrices obtained from this function will be in
     controllable canonical form as described in `Modern Control
     Theory', (Brogan, 1991).

 -- Function File: [ZER, POL, K] = tf2zp (NUM, DEN)
     Converts transfer functions to poles-and-zero representations.

     Returns the zeros and poles of the SISO system defined by NUM/DEN.
     K is a gain associated with the system zeros.

 -- Function File: [A, B, C, D] = zp2ss (ZER, POL, K)
     Conversion from zero / pole to state space.

     *Inputs*
    ZER
    POL
          Vectors of (possibly) complex poles and zeros of a transfer
          function. Complex values must come in conjugate pairs (i.e.,
          x+jy in ZER means that x-jy is also in ZER).  The number of
          zeros must not exceed the number of poles.

    K
          Real scalar (leading coefficient).

     *Outputs*
    A
    B
    C
    D
          The state space system, in the form:
                    .
                    x = Ax + Bu
                    y = Cx + Du

 -- Function File: [NUM, DEN] = zp2tf (ZER, POL, K)
     Converts zeros / poles to a transfer function.

     *Inputs*
    ZER
    POL
          Vectors of (possibly complex) poles and zeros of a transfer
          function.  Complex values must appear in conjugate pairs.

    K
          Real scalar (leading coefficient).


File: octave.info,  Node: Signal Processing,  Next: Image Processing,  Prev: Control Theory,  Up: Top

30 Signal Processing
********************

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

 -- Function File:  detrend (X, P)
     If X is a vector, `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.

 -- Loadable Function:  fft (A, N, DIM)
     Compute the FFT of A using subroutines from FFTPACK. The FFT is
     calculated along the first non-singleton dimension of the array.
     Thus if A is a matrix, `fft (A)' 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, or an empty matrix
     to specify that its value should be ignored. If N is larger than
     the dimension along which the FFT is calculated, then A is resized
     and padded with zeros. Otherwise, ifN is smaller than the
     dimension along which the FFT is calculated, then A is truncated.

     If called with three agruments, DIM is an integer specifying the
     dimension of the matrix along which the FFT is performed

 -- Loadable Function:  ifft (A, N, DIM)
     Compute the inverse FFT of A using subroutines from FFTPACK. The
     inverse FFT is calculated along the first non-singleton dimension
     of the array. Thus if A is a matrix, `fft (A)' 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, or an empty matrix
     to specify that its value should be ignored. If N is larger than
     the dimension along which the inverse FFT is calculated, then A is
     resized and padded with zeros. Otherwise, ifN is smaller than the
     dimension along which the inverse FFT is calculated, then A is
     truncated.

     If called with three agruments, DIM is an integer specifying the
     dimension of the matrix along which the inverse FFT is performed

 -- Loadable Function:  fft2 (A, N, M)
     Compute the two dimensional FFT of A using subroutines from
     FFTPACK. 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.

     If A is a multi-dimensional matrix, each two-dimensional sub-matrix
     of A is treated seperately

 -- Loadable Function:  fft2 (A, N, M)
     Compute the inverse two dimensional FFT of A using subroutines from
     FFTPACK. 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.

     If A is a multi-dimensional matrix, each two-dimensional sub-matrix
     of A is treated seperately

 -- Loadable Function:  fftn (A, SIZE)
     Compute the N dimensional FFT of A using subroutines from FFTPACK.
     The optional vector argument SIZE may be used specify the
     dimensions of the array to be used. If an element of SIZE is
     smaller than the corresponding dimension, then the dimension is
     truncated prior to performing the FFT. Otherwise if an element of
     SIZE is larger than the corresponding dimension A is resized and
     padded with zeros.

 -- Loadable Function:  ifftn (A, SIZE)
     Compute the invesre N dimensional FFT of A using subroutines from
     FFTPACK. The optional vector argument SIZE may be used specify the
     dimensions of the array to be used. If an element of SIZE is
     smaller than the corresponding dimension, then the dimension is
     truncated prior to performing the inverse FFT. Otherwise if an
     element of SIZE is larger than the corresponding dimension A is
     resized and padded with zeros.

 -- Function File:  fftconv (A, B, N)
     Return the convolution of the vectors A and B, as a vector with
     length equal to the `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.

 -- Function File:  fftfilt (B, X, N)
     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.

     If X is a matrix, filter each column of the matrix.

 -- Loadable Function: y = filter (B, A, X)
 -- Loadable Function: [Y, SF] = filter (B, A, X, SI)
 -- Loadable Function: [Y, SF] = filter (B, A, X, [], DIM)
 -- Loadable Function: [Y, SF] = filter (B, A, X, SI, DIM)
     Return the solution to the following linear, time-invariant
     difference equation:

             N                   M
            SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k)      for 1<=n<=length(x)
            k=0                 k=0

     where  N=length(a)-1 and M=length(b)-1.  over the first
     non-singleton dimension of X or over DIM if supplied. An
     equivalent form of this equation is:

                      N                   M
            y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k)  for 1<=n<=length(x)
                     k=1                 k=0

     where  c = a/a(1) and d = b/a(1).

     If the fourth argument SI is provided, it 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
     supplied, the initial state vector is set to all zeros.

     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:

                       M
                      SUM d(k+1) z^(-k)
                      k=0
            H(z) = ----------------------
                         N
                    1 + SUM c(k+1) z(-k)
                        k=1

 -- Function File: [H, W] = freqz (B, A, N, "whole")
     Return the complex frequency response H of the rational IIR filter
     whose numerator and denominator coefficients are B and A,
     respectively.  The response is evaluated at N angular frequencies
     between 0 and  2*pi.

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

     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.

 -- Function File: H = freqz (B, A, W)
     Evaluate the response at the specific frequencies in the vector W.
     The values for W are measured in radians.

 -- Function File: [...] = freqz (..., FS)
     Return frequencies in Hz instead of radians assuming a sampling
     rate FS.  If you are evaluating the response at specific
     frequencies W, those frequencies should be requested in Hz rather
     than radians.

 -- Function File:  freqz (...)
     Plot the pass band, stop band and phase response of H rather than
     returning them.

 -- Function File: freqz_plot (W, H)
     Plot the pass band, stop band and phase response of H.

 -- Function File:  sinc (X)
     Return  sin(pi*x)/(pi*x).

 -- Function File: B = unwrap (A, TOL, DIM)
     Unwrap radian phases by adding multiples of 2*pi as appropriate to
     remove jumps greater than TOL.  TOL defaults to pi.

     Unwrap will unwrap along the first non-singleton dimension of A,
     unless the optional argument DIM is given, in which case the data
     will be unwrapped along this dimension

 -- Function File: [A, B] = arch_fit (Y, X, P, ITER, GAMMA, A0, B0)
     Fit an ARCH regression model to the time series Y using the
     scoring algorithm in Engle's original ARCH paper.  The model is

          y(t) = b(1) * x(t,1) + ... + b(k) * x(t,k) + e(t),
          h(t) = a(1) + a(2) * e(t-1)^2 + ... + a(p+1) * e(t-p)^2

     in which e(t) is N(0, h(t)), given a time-series vector Y up to
     time t-1 and a matrix of (ordinary) regressors X up to t.  The
     order of the regression of the residual variance is specified by P.

     If invoked as `arch_fit (Y, K, P)' with a positive integer K, fit
     an ARCH(K, P) process, i.e., do the above with the t-th row of X
     given by

          [1, y(t-1), ..., y(t-k)]

     Optionally, one can specify the number of iterations ITER, the
     updating factor GAMMA, and initial values a0 and b0 for the
     scoring algorithm.

 -- Function File:  arch_rnd (A, B, T)
     Simulate an ARCH sequence of length T with AR coefficients B and
     CH coefficients A.  I.e., the result y(t) follows the model

          y(t) = b(1) + b(2) * y(t-1) + ... + b(lb) * y(t-lb+1) + e(t),

     where e(t), given Y up to time t-1, is N(0, h(t)), with

          h(t) = a(1) + a(2) * e(t-1)^2 + ... + a(la) * e(t-la+1)^2

 -- Function File: [PVAL, LM] = arch_test (Y, X, P)
     For a linear regression model

          y = x * b + e

     perform a Lagrange Multiplier (LM) test of the null hypothesis of
     no conditional heteroscedascity against the alternative of CH(P).

     I.e., the model is

          y(t) = b(1) * x(t,1) + ... + b(k) * x(t,k) + e(t),

     given Y up to t-1 and X up to t, e(t) is N(0, h(t)) with

          h(t) = v + a(1) * e(t-1)^2 + ... + a(p) * e(t-p)^2,

     and the null is a(1) == ... == a(p) == 0.

     If the second argument is a scalar integer, k, perform the same
     test in a linear autoregression model of order k, i.e., with

          [1, y(t-1), ..., y(t-K)]

     as the t-th row of X.

     Under the null, LM approximately has a chisquare distribution with
     P degrees of freedom and PVAL is the p-value (1 minus the CDF of
     this distribution at LM) of the test.

     If no output argument is given, the p-value is displayed.

 -- Function File:  arma_rnd (A, B, V, T, N)
     Return a simulation of the ARMA model

          x(n) = a(1) * x(n-1) + ... + a(k) * x(n-k)
               + e(n) + b(1) * e(n-1) + ... + b(l) * e(n-l)

     in which K is the length of vector A, L is the length of vector B
     and E is gaussian white noise with variance V.  The function
     returns a vector of length T.

     The optional parameter N gives the number of dummy X(I) used for
     initialization, i.e., a sequence of length T+N is generated and
     X(N+1:T+N) is returned.  If N is omitted, N = 100 is used.

 -- Function File:  autocor (X, H)
     Return the autocorrelations from lag 0 to H of vector X.  If H is
     omitted, all autocorrelations are computed.  If X is a matrix, the
     autocorrelations of each column are computed.

 -- Function File:  autocov (X, H)
     Return the autocovariances from lag 0 to H of vector X.  If H is
     omitted, all autocovariances are computed.  If X is a matrix, the
     autocovariances of each column are computed.

 -- Function File:  autoreg_matrix (Y, K)
     Given a time series (vector) Y, return a matrix with ones in the
     first column and the first K lagged values of Y in the other
     columns.  I.e., for T > K, `[1, Y(T-1), ..., Y(T-K)]' is the t-th
     row of the result.  The resulting matrix may be used as a
     regressor matrix in autoregressions.

 -- Function File:  bartlett (M)
     Return the filter coefficients of a Bartlett (triangular) window of
     length M.

     For a definition of the Bartlett window, see e.g. A. V. Oppenheim &
     R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File:  blackman (M)
     Return the filter coefficients of a Blackman window of length M.

     For a definition of the  Blackman window, see e.g. A. V. Oppenheim
     & R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File: [D, DD] = diffpara (X, A, B)
     Return the estimator D for the differencing parameter of an
     integrated time series.

     The frequencies from [2*pi*a/t, 2*pi*b/T] are used for the
     estimation.  If B is omitted, the interval [2*pi/T, 2*pi*a/T] is
     used.  If both B and A are omitted then a = 0.5 * sqrt (T) and b =
     1.5 * sqrt (T) is used, where T is the sample size.  If X is a
     matrix, the differencing parameter of each column is estimated.

     The estimators for all frequencies in the intervals described
     above is returned in DD.  The value of D is simply the mean of DD.

     Reference: Brockwell, Peter J. & Davis, Richard A. Time Series:
     Theory and Methods Springer 1987.

 -- Function File:  durbinlevinson (C, OLDPHI, OLDV)
     Perform one step of the Durbin-Levinson algorithm.

     The vector C specifies the autocovariances `[gamma_0, ...,
     gamma_t]' from lag 0 to T, OLDPHI specifies the coefficients based
     on C(T-1) and OLDV specifies the corresponding error.

     If OLDPHI and OLDV are omitted, all steps from 1 to T of the
     algorithm are performed.

 -- Function File:  fftshift (V)
 -- Function File:  fftshift (V, DIM)
     Perform a shift of the vector V, for use with the `fft' and `ifft'
     functions, in order the move the frequency 0 to the center of the
     vector or matrix.

     If V is a vector of N elements corresponding to N time samples
     spaced of Dt each, then `fftshift (fft (V))' corresponds to
     frequencies

          f = ((1:N) - ceil(N/2)) / N / Dt

     If V is a matrix, the same holds for rows and columns. If V is an
     array, then the same holds along each dimension.

     The optional DIM argument can be used to limit the dimension along
     which the permutation occurs.

 -- Function File:  fractdiff (X, D)
     Compute the fractional differences (1-L)^d x where L denotes the
     lag-operator and d is greater than -1.

 -- Function File:  hamming (M)
     Return the filter coefficients of a Hamming window of length M.

     For a definition of the Hamming window, see e.g. A. V. Oppenheim &
     R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File:  hanning (M)
     Return the filter coefficients of a Hanning window of length M.

     For a definition of this window type, see e.g. A. V. Oppenheim &
     R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File:  hurst (X)
     Estimate the Hurst parameter of sample X via the rescaled range
     statistic.  If X is a matrix, the parameter is estimated for every
     single column.

 -- Function File:  periodogram (X)
     For a data matrix X from a sample of size N, return the
     periodogram.

 -- Function File:  rectangle_lw (N, B)
     Rectangular lag window. Subfunction used for spectral density
     estimation.

 -- Function File:  rectangle_sw (N, B)
     Rectangular spectral window.  Subfunction used for spectral density
     estimation.

 -- Function File:  sinetone (FREQ, RATE, SEC, AMPL)
     Return a sinetone of frequency FREQ with length of SEC seconds at
     sampling rate RATE and with amplitude AMPL.  The arguments FREQ
     and AMPL may be vectors of common size.

     Defaults are RATE = 8000, SEC = 1 and AMPL = 64.

 -- Function File:  sinewave (M, N, D)
     Return an M-element vector with I-th element given by `sin (2 * pi
     * (I+D-1) / N)'.

     The default value for D is 0 and the default value for N is M.

 -- Function File:  spectral_adf (C, WIN, B)
     Return the spectral density estimator given a vector of
     autocovariances C, window name WIN, and bandwidth, B.

     The window name, e.g., `"triangle"' or `"rectangle"' is used to
     search for a function called `WIN_sw'.

     If WIN is omitted, the triangle window is used.  If B is omitted,
     `1 / sqrt (length (X))' is used.

 -- Function File:  spectral_xdf (X, WIN, B)
     Return the spectral density estimator given a data vector X,
     window name WIN, and bandwidth, B.

     The window name, e.g., `"triangle"' or `"rectangle"' is used to
     search for a function called `WIN_sw'.

     If WIN is omitted, the triangle window is used.  If B is omitted,
     `1 / sqrt (length (X))' is used.

 -- Function File:  spencer (X)
     Return Spencer's 15 point moving average of every single column of
     X.

 -- Function File: [Y, C] = stft (X, WIN_SIZE, INC, NUM_COEF, W_TYPE)
     Compute the short-term Fourier transform of the vector X with
     NUM_COEF coefficients by applying a window of WIN_SIZE data points
     and an increment of INC points.

     Before computing the Fourier transform, one of the following
     windows is applied:

    hanning
          w_type = 1

    hamming
          w_type = 2

    rectangle
          w_type = 3

     The window names can be passed as strings or by the W_TYPE number.

     If not all arguments are specified, the following defaults are
     used: WIN_SIZE = 80, INC = 24, NUM_COEF = 64, and W_TYPE = 1.

     `Y = stft (X, ...)' returns the absolute values of the Fourier
     coefficients according to the NUM_COEF positive frequencies.

     `[Y, C] = stft (`x', ...)' returns the entire STFT-matrix Y and a
     3-element vector C containing the window size, increment, and
     window type, which is needed by the synthesis function.

 -- Function File:  synthesis (Y, C)
     Compute a signal from its short-time Fourier transform Y and a
     3-element vector C specifying window size, increment, and window
     type.

     The values Y and C can be derived by

          [Y, C] = stft (X , ...)

 -- Function File:  triangle_lw (N, B)
     Triangular lag window. Subfunction used for spectral density
     estimation.

 -- Function File:  triangle_sw (N, B)
     Triangular spectral window.  Subfunction used for spectral density
     estimation.

 -- Function File: [A, V] = yulewalker (C)
     Fit an AR (p)-model with Yule-Walker estimates given a vector C of
     autocovariances `[gamma_0, ..., gamma_p]'.

     Returns the AR coefficients, A, and the variance of white noise, V.


File: octave.info,  Node: Image Processing,  Next: Audio Processing,  Prev: Signal Processing,  Up: Top

31 Image Processing
*******************

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

 -- Function File:  colormap (MAP)
 -- Function File:  colormap ("default")
     Set the current colormap.

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

 -- Function File:  gray (N)
     Return a gray colormap with N entries corresponding to values from
     0 to N-1.  The argument N should be a scalar.  If it is omitted,
     64 is assumed.

 -- Function File: [IMG, MAP] = gray2ind ()
     Convert a gray scale intensity image to an Octave indexed image.

 -- Function File:  image (X, ZOOM)
 -- Function File:  image (X, Y, A, ZOOM)
     Display a matrix as a color image.  The elements of X are indices
     into the current colormap and should have values between 1 and the
     length of the colormap.  If ZOOM is omitted, the image will be
     scaled to fit within 600x350 (to a max of 4).

     It first tries to use `display' from `ImageMagick' then `xv' and
     then `xloadimage'.

     The axis values corresponding to the matrix elements are specified
     in X and Y. At present they are ignored.

 -- Function File:  imagesc (A)
 -- Function File:  imagesc (X, Y, A)
 -- Function File:  imagesc (..., ZOOM)
 -- Function File:  imagesc (..., LIMITS)
 -- Function File:  B =  imagesc (...)
     Display a scaled version of the matrix A as a color image.  The
     matrix is scaled so that its entries are indices into the current
     colormap.  The scaled matrix is returned.  If ZOOM is omitted, a
     comfortable size is chosen.  If LIMITS = [LO, HI] are given, then
     that range maps into the full range of the colormap rather than
     the minimum and maximum values of A.

     The axis values corresponding to the matrix elements are specified
     in X and Y, either as pairs giving the minimum and maximum values
     for the respective axes, or as values for each row and column of
     the matrix A.  At present they are ignored.

 -- Function File:  imshow (I)
 -- Function File:  imshow (X, MAP)
 -- Function File:  imshow (I, N)
 -- Function File:  imshow (R, G, B)
     Display an image.

     `imshow (X)' displays an image X.  The numerical class of the
     image determines its bit-depth: 1 for `logical', 8 for `uint8' and
     `logical', and 16 for `double' or `uint16'.  If X has dimensions
     MxNx3, the three matrices represent the red, green and blue
     components of the image.

     `imshow (X, MAP)' displays an indexed image using the specified
     colormap.

     `imshow (I, N)' displays a gray scale intensity image of N levels.

     `imshow (R, G, B)' displays an RGB image.

     The character string `"truesize"' can always be used as an
     optional final argument to prevent automatic zooming of the image.

 -- Function File:  ind2gray (X, MAP)
     Convert an Octave indexed image to a gray scale intensity image.
     If MAP is omitted, the current colormap is used to determine the
     intensities.

 -- Function File: [R, G, B] = ind2rgb (X, MAP)
     Convert an indexed image to red, green, and blue color components.
     If MAP is omitted, the current colormap is used for the conversion.

 -- Function File: [X, MAP] = loadimage (FILE)
     Load an image file and it's associated color map from the specified
     FILE.  The image must be stored in Octave's image format.

 -- Function File:  rgb2ntsc (RGB)
     Image format conversion.

 -- Function File:  ntsc2rgb (YIQ)
     Image format conversion.

 -- Function File:  RGB_MAP = hsv2rgb (HSV_MAP)
     Transform a colormap from the hsv space to the rgb space.

 -- Function File:  HSV_MAP = rgb2hsv (RGB_MAP)
     Transform a colormap from the rgb space to the hsv space.

     A color n the RGB space consists of the red, green and blue
     intensities.

     In the HSV space each color is represented by their hue, saturation
     and value (brightness).  Value gives the amount of light in the
     color.  Hue describes the dominant wavelegth.  Saturation is the
     amount of Hue mixed into the color.

 -- Function File:  ocean (N)
     Create color colormap.  The argument N should be a scalar.  If it
     is omitted, 64 is assumed.

 -- Function File: [X, MAP] = rgb2ind (R, G, B)
     Convert and RGB image to an Octave indexed image.

 -- Function File:  saveimage (FILE, X, FMT, MAP)
     Save the matrix X to FILE in image format FMT.  Valid values for
     FMT are

    `"img"'
          Octave's image format.  The current colormap is also saved in
          the file.

    `"ppm"'
          Portable pixmap format.

    `"ps"'
          PostScript format.  Note that images saved in PostScript
          format can not be read back into Octave with loadimage.

     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.

 -- Built-in Variable: IMAGEPATH
     A colon separated list of directories in which to search for image
     files.


File: octave.info,  Node: Audio Processing,  Next: Quaternions,  Prev: Image Processing,  Up: Top

32 Audio Processing
*******************

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

 -- Function File:  lin2mu (X, N)
     Converts audio data from linear to mu-law.  Mu-law values use 8-bit
     unsigned integers.  Linear values use N-bit signed integers or
     floating point values in the range -1<=X<=1 if N is 0.  If N is
     not specified it defaults to 0, 8 or 16 depending on the range
     values in X.

 -- Function File:  mu2lin (X, BPS)
     Converts audio data from linear to mu-law.  Mu-law values are 8-bit
     unsigned integers.  Linear values use N-bit signed integers or
     floating point values in the range -1<=y<=1 if N is 0.  If N is
     not specified it defaults to 8.

 -- Function File:  loadaudio (NAME, EXT, BPS)
     Loads audio data from the file `NAME.EXT' into the vector X.

     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.

 -- Function File:  saveaudio (NAME, X, EXT, BPS)
     Saves a vector X of audio data to the file `NAME.EXT'.  The
     optional parameters EXT and BPS determine the encoding and the
     number of bits per sample used in the audio file (see
     `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.

 -- Function File:  playaudio (NAME, EXT)
 -- Function File:  playaudio (X)
     Plays the audio file `NAME.EXT' or the audio data stored in the
     vector X.

 -- Function File:  record (SEC, SAMPLING_RATE)
     Records SEC seconds of audio input into the vector X.  The default
     value for SAMPLING_RATE is 8000 samples per second, or 8kHz.  The
     program waits until the user types <RET> and then immediately
     starts to record.

 -- Function File: setaudio ([W_TYPE [, VALUE]])
     Execute the shell command `mixer [W_TYPE [, VALUE]]'


File: octave.info,  Node: Quaternions,  Next: System Utilities,  Prev: Audio Processing,  Up: Top

33 Quaternions
**************

Quaternions are hypercomplex numbers used to represent spatial
rotations in three dimensions.  This set of routines provides a useful
basis for working with quaternions in Octave.  A tutorial is in the
Octave source, scripts/quaternion/quaternion.ps.

   These functions were written by A. S. Hodel, Associate Professor,
Auburn University.

 -- Function File: [A, B, C, D] = quaternion (w)
 -- Function File: [VV, THETA] = quaternion (w)
 -- Function File: W = quaternion (A, B, C, D)
 -- Function File: W = quaternion (VV, THETA)
     Construct or extract a quaternion

          w = a*i + b*j + c*k + d

     from given data.

 -- Function File:  qconj (Q)
     Conjugate of a quaternion.

          q = [w, x, y, z] = w*i + x*j + y*k + z
          qconj (q) = -w*i -x*j -y*k + z

 -- Function File:  qderiv (omega)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to
     a rotating frame.  If the rotating frame is rotating about the [x,
     y, z] axes at angular rates [wx, wy, wz], then the derivative of Q
     is given by

          Q' = qderivmat (omega) * Q

     If the passive convention is used (rotate the frame, not the
     vector), then

          Q' = -qderivmat (omega) * Q

 -- Function File:  qderivmat (OMEGA)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to
     a rotating frame.  If the rotating frame is rotating about the [x,
     y, z] axes at angular rates [wx, wy, wz], then the derivative of Q
     is given by

          Q' = qderivmat (omega) * Q

     If the passive convention is used (rotate the frame, not the
     vector), then

          Q' = -qderivmat (omega) * Q.

 -- Function File:  qinv (Q)
     Return the inverse of a quaternion.

          q = [w, x, y, z] = w*i + x*j + y*k + z
          qmult (q, qinv (q)) = 1 = [0 0 0 1]

 -- Function File:  qmult (A, B)
     Multiply two quaternions.

          [w, x, y, z] = w*i + x*j + y*k + z

     identities:

          i^2 = j^2 = k^2 = -1
          ij = k                 jk = i
          ki = j                 kj = -i
          ji = -k                ik = -j

 -- Function File:  qtrans (V, Q)
     Transform the unit quaternion V by the unit quaternion Q.  Returns
     `V = Q*V/Q'.

 -- Function File:  qtransv (V, Q)
     Transform the 3-D vector V by the unit quaternion Q.  Return a
     column vector.

          vi = (2*real(q)^2 - 1)*vb + 2*imag(q)*(imag(q)'*vb)
             + 2*real(q)*cross(imag(q),vb)

     Where imag(q) is a column vector of length 3.

 -- Function File:  qtransvmat (QIB)
     Construct a 3x3 transformation matrix from quaternion QIB that is
     equivalent to rotation of th radians about axis VV, where `[VV,
     TH] = quaternion (QIB)'.

 -- Function File:  qcoordinate_plot (QF, QB, QV)
     Plot in the current figure a set of coordinate axes as viewed from
     the orientation specified by quaternion QV.  Inertial axes are
     also plotted:

    QF
          Quaternion from reference (x,y,z) to inertial.

    QB
          Quaternion from reference to body.

    QV
          Quaternion from reference to view angle.


File: octave.info,  Node: System Utilities,  Next: Tips,  Prev: Quaternions,  Up: Top

34 System Utilities
*******************

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.

* Menu:

* Timing Utilities::
* Filesystem Utilities::
* Controlling Subprocesses::
* Process ID Information::
* Environment Variables::
* Current Working Directory::
* Password Database Functions::
* Group Database Functions::
* System Information::


File: octave.info,  Node: Timing Utilities,  Next: Filesystem Utilities,  Up: System Utilities

34.1 Timing Utilities
=====================

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'
     Microseconds after the second (0-999999).

`sec'
     Seconds after the minute (0-61).  This number can be 61 to account
     for leap seconds.

`min'
     Minutes after the hour (0-59).

`hour'
     Hours since midnight (0-23).

`mday'
     Day of the month (1-31).

`mon'
     Months since January (0-11).

`year'
     Years since 1900.

`wday'
     Days since Sunday (0-6).

`yday'
     Days since January 1 (0-365).

`isdst'
     Daylight Savings Time flag.

`zone'
     Time zone.

In the descriptions of the following functions, this structure is
referred to as a TM_STRUCT.

 -- Loadable Function:  time ()
     Return the current time as the number of seconds since the epoch.
     The epoch is referenced to 00:00:00 CUT (Coordinated Universal
     Time) 1 Jan 1970.  For example, on Monday February 17, 1997 at
     07:15:06 CUT, the value returned by `time' was 856163706.

 -- Function File:  ctime (T)
     Convert a value returned from `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\n"

 -- Loadable Function:  gmtime (T)
     Given a value returned from time (or any nonnegative integer),
     return a time structure corresponding to CUT.  For example,

          gmtime (time ())
               => {
                     usec = 0
                     year = 97
                     mon = 1
                     mday = 17
                     sec = 6
                     zone = CST
                     min = 15
                     wday = 1
                     hour = 7
                     isdst = 0
                     yday = 47
                   }

 -- Loadable Function:  localtime (T)
     Given a value returned from time (or any nonnegative integer),
     return a time structure corresponding to the local time zone.

          localtime (time ())
               => {
                     usec = 0
                     year = 97
                     mon = 1
                     mday = 17
                     sec = 6
                     zone = CST
                     min = 15
                     wday = 1
                     hour = 1
                     isdst = 0
                     yday = 47
                   }

 -- Loadable Function:  mktime (TM_STRUCT)
     Convert a time structure corresponding to the local time to the
     number of seconds since the epoch.  For example,

          mktime (localtime (time ())
               => 856163706

 -- Function File:  asctime (TM_STRUCT)
     Convert a time structure to a string using the following five-field
     format: Thu Mar 28 08:40:14 1996.  For example,

          asctime (localtime (time ())
          => "Mon Feb 17 01:15:06 1997\n"

     This is equivalent to `ctime (time ())'.

 -- Loadable Function:  strftime (TM_STRUCT)
     Format a time structure in a flexible way using `%' substitutions
     similar to those in `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:

    `%'
          % character.

    `n'
          Newline character.

    `t'
          Tab character.

     Numeric modifiers (a nonstandard extension):

    `- (dash)'
          Do not pad the field.

    `_ (underscore)'
          Pad the field with spaces.

     Time fields:

    `%H'
          Hour (00-23).

    `%I'
          Hour (01-12).

    `%k'
          Hour (0-23).

    `%l'
          Hour (1-12).

    `%M'
          Minute (00-59).

    `%p'
          Locale's AM or PM.

    `%r'
          Time, 12-hour (hh:mm:ss [AP]M).

    `%R'
          Time, 24-hour (hh:mm).

    `%s'
          Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard
          extension).

    `%S'
          Second (00-61).

    `%T'
          Time, 24-hour (hh:mm:ss).

    `%X'
          Locale's time representation (%H:%M:%S).

    `%Z'
          Time zone (EDT), or nothing if no time zone is determinable.

     Date fields:

    `%a'
          Locale's abbreviated weekday name (Sun-Sat).

    `%A'
          Locale's full weekday name, variable length (Sunday-Saturday).

    `%b'
          Locale's abbreviated month name (Jan-Dec).

    `%B'
          Locale's full month name, variable length (January-December).

    `%c'
          Locale's date and time (Sat Nov 04 12:02:33 EST 1989).

    `%C'
          Century (00-99).

    `%d'
          Day of month (01-31).

    `%e'
          Day of month ( 1-31).

    `%D'
          Date (mm/dd/yy).

    `%h'
          Same as %b.

    `%j'
          Day of year (001-366).

    `%m'
          Month (01-12).

    `%U'
          Week number of year with Sunday as first day of week (00-53).

    `%w'
          Day of week (0-6).

    `%W'
          Week number of year with Monday as first day of week (00-53).

    `%x'
          Locale's date representation (mm/dd/yy).

    `%y'
          Last two digits of year (00-99).

    `%Y'
          Year (1970-).

 -- Loadable Function: [TM_STRUCT, NCHARS] = strptime (STR, FMT)
     Convert the string STR to a time structure under the control of
     the format FMT.

   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.

 -- Function File:  clock ()
     Return a vector containing the current year, month (1-12), day
     (1-31), hour (0-23), minute (0-59) and second (0-61).  For example,

          clock ()
          => [ 1993, 8, 20, 4, 56, 1 ]

     The function clock is more accurate on systems that have the
     `gettimeofday' function.

 -- Function File:  date ()
     Return the date as a character string in the form DD-MMM-YY.  For
     example,

          date ()
          => "20-Aug-93"

 -- Function File:  etime (T1, T2)
     Return the difference (in seconds) between two time values
     returned from `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.

 -- Function File: [TOTAL, USER, SYSTEM] = cputime ();
     Return the CPU time used by your Octave session.  The first output
     is the total time spent executing your process and is equal to the
     sum of second and third outputs, which are the number of CPU
     seconds spent executing in user mode and the number of CPU seconds
     spent executing in system mode, respectively.  If your system does
     not have a way to report CPU time usage, `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.

 -- Function File:  is_leap_year (YEAR)
     Return 1 if the given year is a leap year and 0 otherwise.  If no
     arguments are provided, `is_leap_year' will use the current year.
     For example,

          is_leap_year (2000)
          => 1

 -- Function File:  tic ()
 -- Function File:  toc ()
     These functions set and check a wall-clock timer.  For example,

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

 -- Built-in Function:  pause (SECONDS)
     Suspend the execution of the program.  If invoked without any
     arguments, Octave waits until you type a character.  With a
     numeric argument, it pauses for the given number of seconds.  For
     example, the following statement prints a message and then waits 5
     seconds before clearing the screen.

          fprintf (stderr, "wait please...
          ");
          pause (5);
          clc;

 -- Built-in Function:  sleep (SECONDS)
     Suspend the execution of the program for the given number of
     seconds.

 -- Built-in Function:  usleep (MICROSECONDS)
     Suspend the execution of the program for the given number of
     microseconds.  On systems where it is not possible to sleep for
     periods of time less than one second, `usleep' will pause the
     execution for `round (MICROSECONDS / 1e6)' seconds.


File: octave.info,  Node: Filesystem Utilities,  Next: Controlling Subprocesses,  Prev: Timing Utilities,  Up: System Utilities

34.2 Filesystem Utilities
=========================

Octave includes the following functions for renaming and deleting files,
creating, deleting, and reading directories, and for getting information
about the status of files.

 -- Built-in Function: [ERR, MSG] = rename (OLD, NEW)
     Change the name of file OLD to NEW.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [ERR, MSG] = link (OLD, NEW)
     Create a new link (also known as a hard link) to an existing file.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [ERR, MSG] = symlink (OLD, NEW)
     Create a symbolic link NEW which contains the string OLD.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [RESULT, ERR, MSG] = readlink (SYMLINK)
     Read the value of the symbolic link SYMLINK.

     If successful, RESULT contains the contents of the symbolic link
     SYMLINK, ERR is 0 and MSG is an empty string.  Otherwise, ERR is
     nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [ERR, MSG] = unlink (FILE)
     Delete the file named FILE.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [FILES, ERR, MSG] = readdir (DIR)
     Return names of the files in the directory DIR as a cell array of
     strings.  If an error occurs, return an empty cell array in FILES.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [ERR, MSG] = mkdir (DIR)
     Create a directory named DIR.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [ERR, MSG] = rmdir (DIR)
     Remove the directory named DIR.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [ERR, MSG] = mkfifo (NAME, MODE)
     Create a FIFO special file named NAME with file mode MODE

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function:  umask (MASK)
     Set the permission mask for file creation.  The parameter MASK is
     an integer, interpreted as an octal number.  If successful,
     returns the previous value of the mask (as an integer to be
     interpreted as an octal number); otherwise an error message is
     printed.

 -- Built-in Function: [INFO, ERR, MSG] = stat (FILE)
 -- Built-in Function: [INFO, ERR, MSG] = lstat (FILE)
     Return a structure S containing the following information about
     FILE.

    `dev'
          ID of device containing a directory entry for this file.

    `ino'
          File number of the file.

    `modestr'
          File mode, as a string of ten letters or dashes as would be
          returned by `ls -l'.

    `nlink'
          Number of links.

    `uid'
          User ID of file's owner.

    `gid'
          Group ID of file's group.

    `rdev'
          ID of device for block or character special files.

    `size'
          Size in bytes.

    `atime'
          Time of last access in the same form as time values returned
          from `time'.  *Note Timing Utilities::.

    `mtime'
          Time of last modification in the same form as time values
          returned from `time'.  *Note Timing Utilities::.

    `ctime'
          Time of last file status change in the same form as time
          values returned from `time'.  *Note Timing Utilities::.

    `blksize'
          Size of blocks in the file.

    `blocks'
          Number of blocks allocated for file.

     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 =

 -- Built-in Function:  glob (PATTERN)
     Given an array of strings in PATTERN, return a cell array of file
     names that match any of them, or an empty cell array if no
     patterns match.  Tilde expansion is performed on each of the
     patterns before looking for matching file names.  For example,

          glob ("/vm*")
               => "/vmlinuz"

 -- Built-in Function:  fnmatch (PATTERN, STRING)
     Return 1 or zero for each element of STRING that matches any of
     the elements of the string array PATTERN, using the rules of
     filename pattern matching.  For example,

          fnmatch ("a*b", ["ab"; "axyzb"; "xyzab"])
               => [ 1; 1; 0 ]

 -- Built-in Function:  file_in_path (PATH, FILE)
 -- Built-in Function:  file_in_path (PATH, FILE, "all")
     Return the absolute name name of FILE if it can be found in PATH.
     The value of PATH should be a colon-separated list of directories
     in the format described for the built-in variable `LOADPATH'.  If
     no file is found, return an empty matrix.  For example,

          file_in_path (LOADPATH, "nargchk.m")
               => "/usr/local/share/octave/2.0/m/general/nargchk.m"

     If the second argument is a cell array of of strings, search each
     directory of the path for element of the cell array and return the
     first that matches.

     If the third optional argument `"all"' is supplied, return a cell
     array containing the list of all files that have the same name in
     the path.  If no files are found, return an empty cell array.


 -- Built-in Function:  tilde_expand (STRING)
     Performs tilde expansion on STRING.  If STRING begins with a tilde
     character, (`~'), all of the characters preceding the first slash
     (or all characters, if there is no slash) are treated as a
     possible user name, and the tilde and the following characters up
     to the slash are replaced by the home directory of the named user.
     If the tilde is followed immediately by a slash, the tilde is
     replaced by the home directory of the user running Octave.  For
     example,

          tilde_expand ("~joeuser/bin")
               => "/home/joeuser/bin"
          tilde_expand ("~/bin")
               => "/home/jwe/bin"


File: octave.info,  Node: Controlling Subprocesses,  Next: Process ID Information,  Prev: Filesystem Utilities,  Up: System Utilities

34.3 Controlling Subprocesses
=============================

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.

 -- Built-in Function:  system (STRING, RETURN_OUTPUT, TYPE)
     Execute a shell command specified by STRING.  The second argument
     is optional.  If TYPE is `"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,
     its 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
          ", 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'.

 -- Built-in Function: FID = popen (COMMAND, MODE)
     Start a process and create a pipe.  The name of the command to run
     is given by COMMAND.  The file identifier corresponding to the
     input or output stream of the process is returned in FID.  The
     argument MODE may be

    `"r"'
          The pipe will be connected to the standard output of the
          process, and open for reading.

    `"w"'
          The pipe will be connected to the standard input of the
          process, and open for writing.

     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

 -- Built-in Function:  pclose (FID)
     Close a file identifier that was opened by `popen'.  You may also
     use `fclose' for the same purpose.

 -- Function File: [IN, OUT, PID] = popen2 (COMMAND, ARGS)
     Start a subprocess with two-way communication.  The name of the
     process is given by COMMAND, and ARGS is an array of strings
     containing options for the command.  The file identifiers for the
     input and output streams of the subprocess are returned in IN and
     OUT.  If execution of the command is successful, PID contains the
     process ID of the subprocess.  Otherwise, PID is -1.

     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

 -- Built-in Variable: EXEC_PATH
     The variable `EXEC_PATH' is a colon separated list of directories
     to search when executing external programs.  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'.

 -- Built-in Function: [PID, MSG] = fork ()
     Create a copy of the current process.

     Fork can return one of the following values:

    > 0
          You are in the parent process.  The value returned from
          `fork' is the process id of the child process.  You should
          probably arrange to wait for any child processes to exit.

    0
          You are in the child process.  You can call `exec' to start
          another process.  If that fails, you should probably call
          `exit'.

    < 0
          The call to `fork' failed for some reason.  You must take
          evasive action.  A system dependent error message will be
          waiting in MSG.

 -- Built-in Function: [ERR, MSG] = exec (FILE, ARGS)
     Replace current process with a new process.  Calling `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.

 -- Built-in Function: [FILE_IDS, ERR, MSG] = pipe ()
     Create a pipe and return the vector FILE_IDS, which corresponding
     to the reading and writing ends of the pipe.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [FID, MSG] = dup2 (OLD, NEW)
     Duplicate a file descriptor.

     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.

 -- Built-in Function: [PID, MSG] = waitpid (PID, OPTIONS)
     Wait for process PID to terminate.  The PID argument can be:

    -1
          Wait for any child process.

    0
          Wait for any child process whose process group ID is equal to
          that of the Octave interpreter process.

    > 0
          Wait for termination of the child process with ID PID.

     The OPTIONS argument can be:

    0
          Wait until signal is received or a child process exits (this
          is the default if the OPTIONS argument is missing).

    1
          Do not hang if status is not immediately available.

    2
          Report the status of any child processes that are stopped,
          and whose status has not yet been reported since they stopped.

    3
          Implies both 1 and 2.

     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.

 -- Built-in Function: [ERR, MSG] = fcntl (FID, REQUEST, ARG)
     Change the properties of the open file FID.  The following values
     may be passed as REQUEST:

    `F_DUPFD'
          Return a duplicate file descriptor.

    `F_GETFD'
          Return the file descriptor flags for FID.

    `F_SETFD'
          Set the file descriptor flags for FID.

    `F_GETFL'
          Return the file status flags for FID.  The following codes
          may be returned (some of the flags may be undefined on some
          systems).

         `O_RDONLY'
               Open for reading only.

         `O_WRONLY'
               Open for writing only.

         `O_RDWR'
               Open for reading and writing.

         `O_APPEND'
               Append on each write.

         `O_CREAT'
               Create the file if it does not exist.

         `O_NONBLOCK'
               Nonblocking mode.

         `O_SYNC'
               Wait for writes to complete.

         `O_ASYNC'
               Asynchronous I/O.

    `F_SETFL'
          Set the file status flags for FID to the value specified by
          ARG.  The only flags that can be changed are `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.


File: octave.info,  Node: Process ID Information,  Next: Environment Variables,  Prev: Controlling Subprocesses,  Up: System Utilities

34.4 Process, Group, and User IDs
=================================

 -- Built-in Function: pgid = getpgrp ()
     Return the process group id of the current process.

 -- Built-in Function: pid = getpid ()
     Return the process id of the current process.

 -- Built-in Function: pid = getppid ()
     Return the process id of the parent process.

 -- Built-in Function: euid = geteuid ()
     Return the effective user id of the current process.

 -- Built-in Function: uid = getuid ()
     Return the real user id of the current process.

 -- Built-in Function: egid = getegid ()
     Return the effective group id of the current process.

 -- Built-in Function: gid = getgid ()
     Return the real group id of the current process.


File: octave.info,  Node: Environment Variables,  Next: Current Working Directory,  Prev: Process ID Information,  Up: System Utilities

34.5 Environment Variables
==========================

 -- Built-in Function:  getenv (VAR)
     Return the value of the environment variable VAR.  For example,

          getenv ("PATH")

     returns a string containing the value of your path.

 -- Built-in Function:  putenv (VAR, VALUE)
     Set the value of the environment variable VAR to VALUE.


File: octave.info,  Node: Current Working Directory,  Next: Password Database Functions,  Prev: Environment Variables,  Up: System Utilities

34.6 Current Working Directory
==============================

 -- Command: cd dir
 -- Command: chdir dir
     Change the current working directory to DIR.  If DIR is omitted,
     the current directory is changed to the users home directory.  For
     example,

          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.

 -- Command: ls options
     List directory contents.  For example,

          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.

 -- Built-in Function:  pwd ()
     Return the current working directory.


File: octave.info,  Node: Password Database Functions,  Next: Group Database Functions,  Prev: Current Working Directory,  Up: System Utilities

34.7 Password Database Functions
================================

Octave's password database functions return information in a structure
with the following fields.

`name'
     The user name.

`passwd'
     The encrypted password, if available.

`uid'
     The numeric user id.

`gid'
     The numeric group id.

`gecos'
     The GECOS field.

`dir'
     The home directory.

`shell'
     The initial shell.

   In the descriptions of the following functions, this data structure
is referred to as a PW_STRUCT.

 -- Loadable Function: PW_STRUCT =  getpwent ()
     Return a structure containing an entry from the password database,
     opening it if necessary. Once the end of the data has been reached,
     `getpwent' returns 0.

 -- Loadable Function: PW_STRUCT =  getpwuid (UID).
     Return a structure containing the first entry from the password
     database with the user ID UID.  If the user ID does not exist in
     the database, `getpwuid' returns 0.

 -- Loadable Function: PW_STRUCT =  getpwnam (NAME)
     Return a structure containing the first entry from the password
     database with the user name NAME.  If the user name does not exist
     in the database, `getpwname' returns 0.

 -- Loadable Function:  setpwent ()
     Return the internal pointer to the beginning of the password
     database.

 -- Loadable Function:  endpwent ()
     Close the password database.


File: octave.info,  Node: Group Database Functions,  Next: System Information,  Prev: Password Database Functions,  Up: System Utilities

34.8 Group Database Functions
=============================

Octave's group database functions return information in a structure
with the following fields.

`name'
     The user name.

`passwd'
     The encrypted password, if available.

`gid'
     The numeric group id.

`mem'
     The members of the group.

   In the descriptions of the following functions, this data structure
is referred to as a GRP_STRUCT.

 -- Loadable Function: GRP_STRUCT = getgrent ()
     Return an entry from the group database, opening it if necessary.
     Once the end of the data has been reached, `getgrent' returns 0.

 -- Loadable Function: GRP_STRUCT = getgrgid (GID).
     Return the first entry from the group database with the group ID
     GID.  If the group ID does not exist in the database, `getgrgid'
     returns 0.

 -- Loadable Function: GRP_STRUCT = getgrnam (NAME)
     Return the first entry from the group database with the group name
     NAME.  If the group name does not exist in the database,
     `getgrname' returns 0.

 -- Loadable Function:  setgrent ()
     Return the internal pointer to the beginning of the group database.

 -- Loadable Function:  endgrent ()
     Close the group database.


File: octave.info,  Node: System Information,  Prev: Group Database Functions,  Up: System Utilities

34.9 System Information
=======================

 -- Function File:  computer ()
     Print or return a string of the form CPU-VENDOR-OS that identifies
     the kind of computer Octave is running on.  If invoked with an
     output argument, the value is returned instead of printed.  For
     example,

          computer ()
          -| i586-pc-linux-gnu

          x = computer ()
          => x = "i586-pc-linux-gnu"

 -- Built-in Function:  isieee ()
     Return 1 if your computer claims to conform to the IEEE standard
     for floating point calculations.

 -- Built-in Variable: OCTAVE_VERSION
     The version number of Octave, as a string.

 -- Built-in Function:  octave_config_info (OPTION)
     Return a structure containing configuration and installation
     information for Octave.

     if OPTION is a string, return the configuration information for the
     specified option.


 -- Loadable Function:  getrusage ()
     Return a structure containing a number of statistics about the
     current Octave process.  Not all fields are available on all
     systems.  If it is not possible to get CPU time statistics, the
     CPU time slots are set to zero.  Other missing data are replaced
     by NaN.  Here is a list of all the possible fields that can be
     present in the structure returned by `getrusage':

    `idrss'
          Unshared data size.

    `inblock'
          Number of block input operations.

    `isrss'
          Unshared stack size.

    `ixrss'
          Shared memory size.

    `majflt'
          Number of major page faults.

    `maxrss'
          Maximum data size.

    `minflt'
          Number of minor page faults.

    `msgrcv'
          Number of messages received.

    `msgsnd'
          Number of messages sent.

    `nivcsw'
          Number of involuntary context switches.

    `nsignals'
          Number of signals received.

    `nswap'
          Number of swaps.

    `nvcsw'
          Number of voluntary context switches.

    `oublock'
          Number of block output operations.

    `stime'
          A structure containing the system CPU time used.  The
          structure has the elements `sec' (seconds) `usec'
          (microseconds).

    `utime'
          A structure containing the user CPU time used.  The structure
          has the elements `sec' (seconds) `usec' (microseconds).


File: octave.info,  Node: Tips,  Next: Trouble,  Prev: System Utilities,  Up: Top

Appendix A Tips and Standards
*****************************

This chapter describes no additional features of Octave.  Instead it
gives advice on making effective use of the features described in the
previous chapters.

* Menu:

* Style Tips::                  Writing clean and robust programs.
* Coding Tips::                 Making code run faster.
* Documentation Tips::          Writing readable documentation strings.
* Comment Tips::                Conventions for writing comments.
* Function Headers::            Standard headers for functions.


File: octave.info,  Node: Style Tips,  Next: Coding Tips,  Up: Tips

A.1 Writing Clean Octave Programs
=================================

Here are some tips for avoiding common errors in writing Octave code
intended for widespread use:

   * Since all global variables share the same name space, and all
     functions share another name space, you should choose a short word
     to distinguish your program from other Octave programs.  Then take
     care to begin the names of all global variables, constants, and
     functions with the chosen prefix.  This helps avoid name conflicts.

     If you write a function that you think ought to be added to Octave
     under a certain name, such as `fiddle_matrix', don't call it by
     that name in your program.  Call it `mylib_fiddle_matrix' in your
     program, and send mail to <maintainers@octave.org> 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.

   * When you encounter an error condition, call the function `error'
     (or `usage').  The `error' and `usage' functions do not return.
     *Note Errors::.

   * Please put a copyright notice on the file if you give copies to
     anyone.  Use the same lines that appear at the top of the function
     files distributed with Octave.  If you have not signed papers to
     assign the copyright to anyone else, then place your name in the
     copyright notice.


File: octave.info,  Node: Coding Tips,  Next: Documentation Tips,  Prev: Style Tips,  Up: Tips

A.2 Tips for Making Code Run Faster.
====================================

Here are some ways of improving the execution speed of Octave programs.

   * Avoid looping wherever possible.

   * Use iteration rather than recursion whenever possible.  Function
     calls are slow in Octave.

   * Avoid resizing matrices unnecessarily.  When building a single
     result matrix from a series of calculations, set the size of the
     result matrix first, then insert values into it.  Write

          result = zeros (big_n, big_m)
          for i = over:and_over
            r1 = ...
            r2 = ...
            result (r1, r2) = new_value ();
          endfor

     instead of

          result = [];
          for i = ever:and_ever
            result = [ result, new_value() ];
          endfor

   * Avoid calling `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.  *Note The try Statement::.

   * If you are calling lots of functions but none of them will need to
     change during your run, set the variable
     `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.


File: octave.info,  Node: Documentation Tips,  Next: Comment Tips,  Prev: Coding Tips,  Up: Tips

A.3 Tips for Documentation Strings
==================================

Here are some tips for the writing of documentation strings.

   * Every command, function, or variable intended for users to know
     about should have a documentation string.

   * An internal variable or subroutine of an Octave program might as
     well have a documentation string.

   * The first line of the documentation string should consist of one
     or two complete sentences that stand on their own as a summary.

     The documentation string can have additional lines that expand on
     the details of how to use the function or variable.  The
     additional lines should also be made up of complete sentences.

   * For consistency, phrase the verb in the first sentence of a
     documentation string as an infinitive with "to" omitted.  For
     instance, use "Return the frob of A and B." in preference to
     "Returns the frob of A and B."  Usually it looks good to do
     likewise for the rest of the first paragraph.  Subsequent
     paragraphs usually look better if they have proper subjects.

   * Write documentation strings in the active voice, not the passive,
     and in the present tense, not the future.  For instance, use
     "Return a list containing A and B." instead of "A list containing
     A and B will be returned."

   * Avoid using the word "cause" (or its equivalents) unnecessarily.
     Instead of, "Cause Octave to display text in boldface," write just
     "Display text in boldface."

   * Do not start or end a documentation string with whitespace.

   * Format the documentation string so that it fits in an Emacs window
     on an 80-column screen.  It is a good idea for most lines to be no
     wider than 60 characters.

     However, rather than simply filling the entire documentation
     string, you can make it much more readable by choosing line breaks
     with care.  Use blank lines between topics if the documentation
     string is long.

   * *Do not* indent subsequent lines of a documentation string so that
     the text is lined up in the source code with the text of the first
     line.  This looks nice in the source code, but looks bizarre when
     users view the documentation.  Remember that the indentation
     before the starting double-quote is not part of the string!

   * The documentation string for a variable that is a yes-or-no flag
     should start with words such as "Nonzero means...", to make it
     clear that all nonzero values are equivalent and indicate
     explicitly what zero and nonzero mean.

   * When a function's documentation string mentions the value of an
     argument of the function, use the argument name in capital letters
     as if it were a name for that value.  Thus, the documentation
     string of the operator `/' 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.


File: octave.info,  Node: Comment Tips,  Next: Function Headers,  Prev: Documentation Tips,  Up: Tips

A.4 Tips on Writing Comments
============================

Here are the conventions to follow when writing comments.

`#'
     Comments that start with a single sharp-sign, `#', should all be
     aligned to the same column on the right of the source code.  Such
     comments usually explain how the code on the same line does its
     job.  In the Emacs mode for Octave, the `M-;'
     (`indent-for-comment') command automatically inserts such a `#' in
     the right place, or aligns such a comment if it is already present.

`##'
     Comments that start with two semicolons, `##', should be aligned to
     the same level of indentation as the code.  Such comments usually
     describe the purpose of the following lines or the state of the
     program at that point.

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.  *Note Manipulating Comments: (emacs)Comments.


File: octave.info,  Node: Function Headers,  Prev: Comment Tips,  Up: Tips

A.5 Conventional Headers for Octave Functions
=============================================

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, Inc., 51 Franklin Street,
     ## Fifth Floor, Boston, MA 02110-1301, 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'
     This line states the name and net address of at least the principal
     author of the library.

          ## Author: John W. Eaton <jwe@bevo.che.wisc.edu>

`Maintainer'
     This line should contain a single name/address as in the Author
     line, or an address only, or the string `jwe'.  If there is no
     maintainer line, the person(s) in the Author field are presumed to
     be the maintainers.  The example above is mildly bogus because the
     maintainer line is redundant.

     The idea behind the `Author' and `Maintainer' lines is to make
     possible a function to "send mail to the maintainer" without
     having to mine the name out by hand.

     Be sure to surround the network address with `<...>' if you
     include the person's full name as well as the network address.

`Created'
     This optional line gives the original creation date of the file.
     For historical interest only.

`Version'
     If you wish to record version numbers for the individual Octave
     program, put them in this line.

`Adapted-By'
     In this header line, place the name of the person who adapted the
     library for installation (to make it fit the style conventions, for
     example).

`Keywords'
     This line lists keywords.  Eventually, it will be used by an
     apropos command to allow people will find your package when
     they're looking for things by topic area.  To separate the
     keywords, you can use spaces, commas, or both.

   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.


File: octave.info,  Node: Trouble,  Next: Installation,  Prev: Tips,  Up: Top

Appendix B Known Causes of Trouble
**********************************

   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.

* Menu:

* Actual Bugs::                 Bugs we will fix later.
* Reporting Bugs::
* Bug Criteria::
* Bug Lists::
* Bug Reporting::
* Sending Patches::
* Service::


File: octave.info,  Node: Actual Bugs,  Next: Reporting Bugs,  Up: Trouble

B.1 Actual Bugs We Haven't Fixed Yet
====================================

   * Output that comes directly from Fortran functions is not sent
     through the pager and may appear out of sequence with other output
     that is sent through the pager.  One way to avoid this is to force
     pending output to be flushed before calling a function that will
     produce output from within Fortran functions.  To do this, use the
     command

          fflush (stdout)

     Another possible workaround is to use the command

          page_screen_output = "false"

     to turn the pager off.

   * If you get messages like

          Input line too long

     when trying to plot many lines on one graph, you have probably
     generated a plot command that is too large 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.


File: octave.info,  Node: Reporting Bugs,  Next: Bug Criteria,  Prev: Actual Bugs,  Up: Trouble

B.2 Reporting Bugs
==================

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.  *Note 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.

* Menu:

* Bug Criteria::
* Where: Bug Lists.             Where to send your bug report.
* Reporting: Bug Reporting.     How to report a bug effectively.
* Patches: Sending Patches.     How to send a patch for Octave.


File: octave.info,  Node: Bug Criteria,  Next: Bug Lists,  Prev: Reporting Bugs,  Up: Trouble

B.3 Have You Found a Bug?
=========================

If you are not sure whether you have found a bug, here are some
guidelines:

   * If Octave gets a fatal signal, for any input whatever, that is a
     bug.  Reliable interpreters never crash.

   * If Octave produces incorrect results, for any input whatever, that
     is a bug.

   * Some output may appear to be incorrect when it is in fact due to a
     program whose behavior is undefined, which happened by chance to
     give the desired results on another system.  For example, the
     range operator may produce different results because of
     differences in the way floating point arithmetic is handled on
     various systems.

   * If Octave produces an error message for valid input, that is a bug.

   * If Octave does not produce an error message for invalid input,
     that is a bug.  However, you should note that your idea of
     "invalid input" might be my idea of "an extension" or "support for
     traditional practice".

   * If you are an experienced user of programs like Octave, your
     suggestions for improvement are welcome in any case.


File: octave.info,  Node: Bug Lists,  Next: Bug Reporting,  Prev: Bug Criteria,  Up: Trouble

B.4 Where to Report Bugs
========================

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

   *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


File: octave.info,  Node: Bug Reporting,  Next: Sending Patches,  Prev: Bug Lists,  Up: Trouble

B.5 How to Report Bugs
======================

Send bug reports for Octave to one of the addresses listed in *Note Bug
Lists::.

   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:

   * The version of Octave.  You can get this by noting the version
     number that is printed when Octave starts, or running it with the
     `-v' option.

   * A complete input file that will reproduce the bug.

     A single statement may not be enough of an example--the bug might
     depend on other details that are missing from the single statement
     where the error finally occurs.

   * The command arguments you gave Octave to execute that example and
     observe the bug.  To guarantee you won't omit something important,
     list all the options.

     If we were to try to guess the arguments, we would probably guess
     wrong and then we would not encounter the bug.

   * The type of machine you are using, and the operating system name
     and version number.

   * The command-line arguments you gave to the `configure' command when
     you installed the interpreter.

   * A complete list of any modifications you have made to the
     interpreter source.

     Be precise about these changes--show a context diff for them.

   * Details of any other deviations from the standard procedure for
     installing Octave.

   * A description of what behavior you observe that you believe is
     incorrect.  For example, "The interpreter gets a fatal signal,"
     or, "The output produced at line 208 is incorrect."

     Of course, if the bug is that the interpreter gets a fatal signal,
     then one can't miss it.  But if the bug is incorrect output, we
     might not notice unless it is glaringly wrong.

     Even if the problem you experience is a fatal signal, you should
     still say so explicitly.  Suppose something strange is going on,
     such as, your copy of the interpreter is out of synch, or you have
     encountered a bug in the C library on your system.  Your copy
     might crash and the copy here would not.  If you said to expect a
     crash, then when the interpreter here fails to crash, we would
     know that the bug was not happening.  If you don't say to expect a
     crash, then we would not know whether the bug was happening.  We
     would not be able to draw any conclusion from our observations.

     Often the observed symptom is incorrect output when your program
     is run.  Unfortunately, this is not enough information unless the
     program is short and simple.  It is very helpful if you can
     include an explanation of the expected output, and why the actual
     output is incorrect.

   * If you wish to suggest changes to the Octave source, send them as
     context diffs.  If you even discuss something in the Octave source,
     refer to it by context, not by line number, because the line
     numbers in the development sources probably won't match those in
     your sources.

   Here are some things that are not necessary:

   * A description of the envelope of the bug.

     Often people who encounter a bug spend a lot of time investigating
     which changes to the input file will make the bug go away and
     which changes will not affect it.  Such information is usually not
     necessary to enable us to fix bugs in Octave, but if you can find
     a simpler example to report _instead_ of the original one, that is
     a convenience.  Errors in the output will be easier to spot,
     running under the debugger will take less time, etc. Most Octave
     bugs involve just one function, so the most straightforward way to
     simplify an example is to delete all the function definitions
     except the one in which the bug occurs.

     However, simplification is not vital; if you don't want to do
     this, report the bug anyway and send the entire test case you used.

   * A patch for the bug.  Patches can be helpful, but if you find a
     bug, you should report it, even if you cannot send a fix for the
     problem.


File: octave.info,  Node: Sending Patches,  Next: Service,  Prev: Bug Reporting,  Up: Trouble

B.6 Sending Patches for Octave
==============================

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.

   * Send an explanation with your changes of what problem they fix or
     what improvement they bring about.  For a bug fix, just include a
     copy of the bug report, and explain why the change fixes the bug.

   * Always include a proper bug report for the problem you think you
     have fixed.  We need to convince ourselves that the change is
     right before installing it.  Even if it is right, we might have
     trouble judging it if we don't have a way to reproduce the problem.

   * Include all the comments that are appropriate to help people
     reading the source in the future understand why this change was
     needed.

   * Don't mix together changes made for different reasons.  Send them
     _individually_.

     If you make two changes for separate reasons, then we might not
     want to install them both.  We might want to install just one.

   * Use `diff -c' to make your diffs.  Diffs without context are hard
     for us to install reliably.  More than that, they make it hard for
     us to study the diffs to decide whether we want to install them.
     Unidiff format is better than contextless diffs, but not as easy
     to read as `-c' format.

     If you have GNU diff, use `diff -cp', which shows the name of the
     function that each change occurs in.

   * Write the change log entries for your changes.

     Read the `ChangeLog' file to see what sorts of information to put
     in, and to learn the style that we use.  The purpose of the change
     log is to show people where to find what was changed.  So you need
     to be specific about what functions you changed; in large
     functions, it's often helpful to indicate where within the
     function the change was made.

     On the other hand, once you have shown people where to find the
     change, you need not explain its purpose. Thus, if you add a new
     function, all you need to say about it is that it is new.  If you
     feel that the purpose needs explaining, it probably does--but the
     explanation will be much more useful if you put it in comments in
     the code.

     If you would like your name to appear in the header line for who
     made the change, send us the header line.


File: octave.info,  Node: Service,  Prev: Sending Patches,  Up: Trouble

B.7 How To Get Help with Octave
===============================

The mailing list <help@octave.org> 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*-request*@octave.org>.

   *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.org>.  *Note Bug Reporting::, for information that will
help you to submit a useful report.


File: octave.info,  Node: Installation,  Next: Emacs,  Prev: Trouble,  Up: Top

Appendix C Installing Octave
****************************

   Here is the procedure for installing Octave from scratch on a Unix
system.

   * Run the shell script `configure'.  This will determine the features
     your system has (or doesn't have) and create a file named
     `Makefile' from each of the files named `Makefile.in'.

     Here is a summary of the configure options that are most
     frequently used when building Octave:

    `--prefix=PREFIX'
          Install Octave in subdirectories below PREFIX.  The default
          value of PREFIX is `/usr/local'.

    `--srcdir=DIR'
          Look for Octave sources in the directory DIR.

    `--with-f2c'
          Use `f2c' even if a Fortran compiler is available.

    `--with-f77'
          Use `f77' to compile Fortran code.  You may also specify the
          name of the compiler to use as an optional argument.  For
          example, `--with-f77=g77' sets the name of the Fortran
          compiler to `g77'.

    `--enable-shared'
          Create shared libraries.  If you are planning to use
          `--enable-lite-kernel' 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'
          Use `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'
          Use `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'
          Compile smaller kernel.  This currently requires the dynamic
          linking functions `dlopen' or `shl_load' and friends so that
          Octave can load functions at run time that are not loaded at
          compile time.

    `--without-blas'
          Compile and use the generic BLAS and LAPACK versions included
          with Octave.  By default, configure first looks for BLAS and
          LAPACK matrix libraries on your system, including optimized
          BLAS implementations such as the free ATLAS 3.0, as well as
          vendor-tuned libraries.  (The use of an optimized BLAS will
          generally result in several-times faster matrix operations.)
          Only use this option if your system has BLAS/LAPACK libraries
          that cause problems for some reason.  You can also use
          `--with-blas=lib' to specify a particular BLAS library
          `-llib' that configure doesn't check for automatically.

    `--help'
          Print a summary of the options recognized by the configure
          script.

     See the file `INSTALL' for more information about the command line
     options used by configure.  That file also contains instructions
     for compiling in a directory other than where the source is
     located.

   * Run make.

     You will need a recent version of GNU Make.  Modifying Octave's
     makefiles to work with other make programs is probably not worth
     your time.  We recommend you get and compile GNU Make instead.

     For plotting, you will need to have gnuplot installed on your
     system.  Gnuplot is a command-driven interactive function plotting
     program.  Gnuplot is copyrighted, but freely distributable.  The
     `gnu' in gnuplot is a coincidence--it is not related to the GNU
     project or the FSF in any but the most peripheral sense.

     To compile Octave, you will need a recent version of GNU Make.  You
     will also need `g++' 2.7.2 or later.  Version 2.8.0 or `egcs'
     1.0.x should work.  Later versions may work, but C++ is still
     evolving, so don't be too surprised if you run into some trouble.

     It is no longer necessary to have `libg++', but you do need to have
     the GNU implementation of `libstdc++'.  If you are using `g++'
     2.7.2, `libstdc++' is distributed along with `libg++', but for
     later versions, `libstdc++' is distributed separately.  For
     `egcs', `libstdc++' is included with the compiler distribution.

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

   * If you encounter errors while compiling Octave, first check the
     list of known problems below to see if there is a workaround or
     solution for your problem.  If not, see *Note Trouble::, for
     information about how to report bugs.

   * Once you have successfully compiled Octave, run `make install'.

     This will install a copy of octave, its libraries, and its
     documentation in the destination directory.  As distributed,
     Octave is installed in the following directories.  In the table
     below, PREFIX defaults to `/usr/local', 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-unknown-gnu').

    `PREFIX/bin'
          Octave and other binaries that people will want to run
          directly.

    `PREFIX/lib'
          Libraries like libcruft.a and liboctave.a.

    `PREFIX/share'
          Architecture-independent data files.

    `PREFIX/include/octave'
          Include files distributed with Octave.

    `PREFIX/man/man1'
          Unix-style man pages describing Octave.

    `PREFIX/info'
          Info files describing Octave.

    `PREFIX/share/octave/VERSION/m'
          Function files distributed with Octave.  This includes the
          Octave version, so that multiple versions of Octave may be
          installed at the same time.

    `PREFIX/lib/octave/VERSION/exec/ARCH'
          Executables to be run by Octave rather than the user.

    `PREFIX/lib/octave/VERSION/oct/ARCH'
          Object files that will be dynamically loaded.

    `PREFIX/share/octave/VERSION/imagelib'
          Image files that are distributed with Octave.

* Menu:

* Installation Problems::


File: octave.info,  Node: Installation Problems,  Up: Installation

C.1 Installation Problems
=========================

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.

   * On some SCO systems, `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.

   * If `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.

   * Building `.oct' files doesn't work.

     You should probably have a shared version of `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'.

   * On some alpha systems there may be a problem with the `libdxml'
     library, resulting in floating point errors and/or segmentation
     faults in the linear algebra routines called by Octave.  If you
     encounter such problems, then you should modify the configure
     script so that `SPECIAL_MATH_LIB' is not set to `-ldxml'.

   * On FreeBSD systems Octave may hang while initializing some internal
     constants.  The fix appears to be to use

          options      GPL_MATH_EMULATE

     rather than

          options      MATH_EMULATE

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

   * If you encounter errors like

          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 (*)())1

     when it should really be something like:

          #define  SIG_IGN  (void (*)(int))1

     to 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-name

     The directory of `gcc' include files normally begins in the same
     directory that contains the file `libgcc.a'.

   * Some of the Fortran subroutines may fail to compile with older
     versions of the Sun Fortran compiler.  If you get errors like

          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 1

     when compiling the Fortran subroutines in the `libcruft'
     subdirectory, you should either upgrade your compiler or try
     compiling with optimization turned off.

   * On NeXT systems, if you get errors like this:

          /usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656
          /usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656

     when compiling `Array.cc' and `Matrix.cc', try recompiling these
     files without `-g'.

   * Some people have reported that calls to shell_cmd and the pager do
     not work on SunOS systems.  This is apparently due to having
     `G_HAVE_SYS_WAIT' defined to be 0 instead of 1 when compiling
     `libg++'.

   * On NeXT systems, linking to `libsys_s.a' may fail to resolve the
     following functions

          _tcgetattr
          _tcsetattr
          _tcflow

     which 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_NXBundle

     One 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!

   * If Octave crashes immediately with a floating point exception, it
     is likely that it is failing to initialize the IEEE floating point
     values for infinity and NaN.

     If your system actually does support IEEE arithmetic, you should
     be able to fix this problem by modifying the function
     `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.

   * After installing the binary distribution of Octave in an alternate
     directory, the Emacs command `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'.


File: octave.info,  Node: Emacs,  Next: Grammar,  Prev: Installation,  Up: Top

Appendix D Emacs Octave Support
*******************************

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.

* Menu:

* Installing EOS::
* Using Octave Mode::
* Running Octave From Within Emacs::
* Using the Emacs Info Reader for Octave::


File: octave.info,  Node: Installing EOS,  Next: Using Octave Mode,  Up: Emacs

D.1 Installing 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.


File: octave.info,  Node: Using Octave Mode,  Next: Running Octave From Within Emacs,  Prev: Installing EOS,  Up: Emacs

D.2 Using Octave Mode
=====================

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.

  1. To begin using Octave mode for all `.m' files you visit, add the
     following lines to a file loaded by Emacs at startup time,
     typically your `~/.emacs' file:

          (autoload 'octave-mode "octave-mod" nil t)
          (setq auto-mode-alist
                (cons '("\\.m$" . octave-mode) auto-mode-alist))

  2. Finally, to turn on the abbrevs, auto-fill and font-lock features
     automatically, also add the following lines to one of the Emacs
     startup files:
          (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.

`C-h m'
     Describe the features of Octave mode.

`LFD'
     Reindent the current Octave line, insert a newline and indent the
     new line (`octave-reindent-then-newline-and-indent').  An abbrev
     before point is expanded if `abbrev-mode' is non-`nil'.

`TAB'
     Indents current Octave line based on its contents and on previous
     lines (`indent-according-to-mode').

`;'
     Insert an "electric" semicolon (`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.

``'
     Start entering an abbreviation (`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.

`M-LFD'
     Break line at point and insert continuation marker and alignment
     (`octave-split-line').

`M-TAB'
     Perform completion on Octave symbol preceding point, comparing that
     symbol against Octave's reserved words and builtin variables
     (`octave-complete-symbol').

`M-C-a'
     Move backward to the beginning of a function
     (`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.

`M-C-e'
     Move forward to the end 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.

`M-C-h'
     Puts point at beginning and mark at the end of the current Octave
     function, i.e., the one containing point or following point
     (`octave-mark-defun').

`M-C-q'
     Properly indents the Octave function which contains point
     (`octave-indent-defun').

`M-;'
     If there is no comment already on this line, create a code-level
     comment (started by two comment characters) if the line is empty,
     or an in-line comment (started by one comment character) otherwise
     (`octave-indent-for-comment').  Point is left after the start of
     the comment which is properly aligned.

`C-c ;'
     Puts the comment character `#' (more precisely, the string value of
     `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.

`C-c :'
     Uncomments every line in the region (`octave-uncomment-region').

`C-c C-p'
     Move one line of Octave code backward, skipping empty and comment
     lines (`octave-previous-code-line').  With numeric prefix argument
     N, move that many code lines backward (forward if N is negative).

`C-c C-n'
     Move one line of Octave code forward, skipping empty and comment
     lines (`octave-next-code-line').  With numeric prefix argument N,
     move that many code lines forward (backward if N is negative).

`C-c C-a'
     Move to the `real' beginning of the current line
     (`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.

`C-c C-e'
     Move to the `real' end of the current line (`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.

`C-c M-C-n'
     Move forward across one balanced begin-end block of Octave code
     (`octave-forward-block').  With numeric prefix argument N, move
     forward across N such blocks (backward if N is negative).

`C-c M-C-p'
     Move back across one balanced begin-end block of Octave code
     (`octave-backward-block').  With numeric prefix argument N, move
     backward across N such blocks (forward if N is negative).

`C-c M-C-d'
     Move forward down one begin-end block level of Octave code
     (`octave-down-block').  With numeric prefix argument, do it that
     many times;  a negative argument means move backward, but still go
     down one level.

`C-c M-C-u'
     Move backward out of one begin-end block level of Octave code
     (`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.

`C-c M-C-h'
     Put point at the beginning of this block, mark at the end
     (`octave-mark-block').  The block marked is the one that contains
     point or follows point.

`C-c ]'
     Close the current block on a separate line (`octave-close-block').
     An error is signaled if no block to close is found.

`C-c f'
     Insert a function skeleton, prompting for the function's name,
     arguments and return values which have to be entered without parens
     (`octave-insert-defun').

`C-c C-h'
     Search the function, operator and variable indices of all info
     files with documentation for Octave for entries (`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'
     Non-`nil' means auto-indent the current line after a semicolon or
     space.  Default is `nil'.

`octave-auto-newline'
     Non-`nil' means auto-insert a newline and indent after semicolons
     are typed.  The default value is `nil'.

`octave-blink-matching-block'
     Non-`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'
     Extra indentation applied to statements in block structures.
     Default is 2.

`octave-continuation-offset'
     Extra indentation applied to Octave continuation lines.  Default
     is 4.

`octave-continuation-string'
     String used for Octave continuation lines.  Normally `\'.

`octave-mode-startup-message'
     If `t' (default), a startup message is displayed when Octave mode
     is called.


   If Font Lock mode is enabled, Octave mode will display
   * strings in `font-lock-string-face'

   * comments in `font-lock-comment-face'

   * the Octave reserved words (such as all block keywords) and the text
     functions (such as `cd' or `who') which are also reserved using
     `font-lock-keyword-face'

   * the builtin operators (`&&', `<>', ...) using
     `font-lock-reference-face'

   * the builtin variables (such as `warn_fortran_indexing', `NaN' or
     `LOADPATH') in `font-lock-variable-name-face'

   * and the function names in function declarations in
     `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'.  If 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.


File: octave.info,  Node: Running Octave From Within Emacs,  Next: Using the Emacs Info Reader for Octave,  Prev: Using Octave Mode,  Up: Emacs

D.3 Running Octave From Within Emacs
====================================

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.

`C-c i l'
     Send the current line to the inferior Octave process
     (`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.

`C-c i b'
     Send the current block to the inferior Octave process
     (`octave-send-block').

`C-c i f'
     Send the current function to the inferior Octave process
     (`octave-send-defun').

`C-c i r'
     Send the region to the inferior Octave process
     (`octave-send-region').

`C-c i s'
     Make sure that `inferior-octave-buffer' is displayed
     (`octave-show-process-buffer').

`C-c i h'
     Delete all windows that display the inferior Octave buffer
     (`octave-hide-process-buffer').

`C-c i k'
     Kill the inferior Octave process and its 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'
     Non-`nil' means echo input sent to the inferior Octave process.
     Default is `t'.

`octave-send-show-buffer'
     Non-`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.


File: octave.info,  Node: Using the Emacs Info Reader for Octave,  Prev: Running Octave From Within Emacs,  Up: Emacs

D.4 Using the Emacs Info Reader for Octave
==========================================

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.  A recent version of gnuserv is available from
`http://www.meltin.net/hacks/emacs/src/gnuserv-3.12.2.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').


File: octave.info,  Node: Grammar,  Next: Copying,  Prev: Emacs,  Up: Top

Appendix E Grammar
******************

Someday I hope to expand this to include a semi-formal description of
Octave's language.

* Menu:

* Keywords::


File: octave.info,  Node: Keywords,  Up: Grammar

E.1 Keywords
============

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


File: octave.info,  Node: Copying,  Next: Concept Index,  Prev: Grammar,  Up: Top

Appendix F GNU GENERAL PUBLIC LICENSE
*************************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

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

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY
 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS
Appendix: How to Apply These Terms to Your New Programs
=======================================================

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) YYYY  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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 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 Lesser General Public License instead of this License.


File: octave.info,  Node: Concept Index,  Next: Variable Index,  Prev: Copying,  Up: Top

Concept Index
*************

[index]
* Menu:

* #:                                     Comments.            (line   6)
* #!:                                    Executable Octave Programs.
                                                              (line   6)
* %:                                     Comments.            (line   6)
* --braindead:                           Command Line Options.
                                                              (line  86)
* --debug:                               Command Line Options.
                                                              (line  11)
* --echo-commands:                       Command Line Options.
                                                              (line  18)
* --exec-path PATH:                      Command Line Options.
                                                              (line  21)
* --help:                                Command Line Options.
                                                              (line  30)
* --info-file FILENAME:                  Command Line Options.
                                                              (line  33)
* --info-program PROGRAM:                Command Line Options.
                                                              (line  40)
* --interactive:                         Command Line Options.
                                                              (line  48)
* --no-init-file:                        Command Line Options.
                                                              (line  57)
* --no-line-editing:                     Command Line Options.
                                                              (line  60)
* --no-site-file:                        Command Line Options.
                                                              (line  63)
* --norc:                                Command Line Options.
                                                              (line  67)
* --path PATH:                           Command Line Options.
                                                              (line  73)
* --quiet:                               Command Line Options.
                                                              (line  82)
* --silent:                              Command Line Options.
                                                              (line  82)
* --traditional:                         Command Line Options.
                                                              (line  86)
* --verbose:                             Command Line Options.
                                                              (line 101)
* --version:                             Command Line Options.
                                                              (line 105)
* -?:                                    Command Line Options.
                                                              (line  30)
* -d:                                    Command Line Options.
                                                              (line  11)
* -f:                                    Command Line Options.
                                                              (line  67)
* -h:                                    Command Line Options.
                                                              (line  30)
* -i:                                    Command Line Options.
                                                              (line  48)
* -p PATH:                               Command Line Options.
                                                              (line  73)
* -q:                                    Command Line Options.
                                                              (line  82)
* -V:                                    Command Line Options.
                                                              (line 101)
* -v:                                    Command Line Options.
                                                              (line 105)
* -x:                                    Command Line Options.
                                                              (line  18)
* ... <1>:                               Variable-length Argument Lists.
                                                              (line   6)
* ...:                                   Variable-length Return Lists.
                                                              (line   6)
* ... continuation marker:               The try Statement.   (line  35)
* .octaverc:                             Startup Files.       (line  31)
* \ continuation marker:                 The try Statement.   (line  35)
* acknowledgements:                      Acknowledgements.    (line   6)
* addition:                              Arithmetic Ops.      (line   6)
* and operator:                          Boolean Expressions. (line   6)
* answers, incorrect <1>:                Bug Criteria.        (line  12)
* answers, incorrect:                    Bug Reporting.       (line  70)
* any key:                               Fonts.               (line  12)
* arguments in function call:            Calling Functions.   (line  15)
* arithmetic operators:                  Arithmetic Ops.      (line   6)
* assignment expressions:                Assignment Ops.      (line   6)
* assignment operators:                  Assignment Ops.      (line   6)
* body of a loop:                        The while Statement. (line   6)
* boolean expressions:                   Boolean Expressions. (line   6)
* boolean operators:                     Boolean Expressions. (line   6)
* break statement:                       The break Statement. (line   6)
* bug criteria:                          Bug Criteria.        (line   6)
* bug report mailing lists:              Bug Lists.           (line   6)
* bugs:                                  Reporting Bugs.      (line   6)
* bugs, investigating:                   Bug Reporting.       (line 102)
* bugs, known:                           Trouble.             (line   6)
* bugs, reporting <1>:                   Bug Reporting.       (line   6)
* bugs, reporting:                       Bug Lists.           (line   6)
* built-in data types:                   Built-in Data Types. (line   6)
* built-in function:                     A Sample Function Description.
                                                              (line  41)
* case statement:                        The switch Statement.
                                                              (line   6)
* catch:                                 The try Statement.   (line   6)
* cell arrays:                           Cell Arrays.         (line   6)
* character strings <1>:                 Strings.             (line   6)
* character strings:                     String Objects.      (line   6)
* Cholesky factorization:                Matrix Factorizations.
                                                              (line   7)
* clearing the screen:                   Cursor Motion.       (line  56)
* coding standards:                      Tips.                (line   6)
* command and ouput logs:                Diary and Echo Commands.
                                                              (line   6)
* command completion:                    Commands For Completion.
                                                              (line   6)
* command descriptions:                  A Sample Command Description.
                                                              (line   6)
* command echoing:                       Diary and Echo Commands.
                                                              (line   6)
* command history:                       Commands For History.
                                                              (line   6)
* command options:                       Command Line Options.
                                                              (line   6)
* command-line editing:                  Command Line Editing.
                                                              (line   6)
* comments:                              Comments.            (line   6)
* comparison expressions:                Comparison Ops.      (line   6)
* complex-conjugate transpose:           Arithmetic Ops.      (line   6)
* compounding, value of:                 Financial Functions. (line   6)
* containers:                            Containers.          (line   6)
* continuation lines:                    The try Statement.   (line  35)
* continue statement:                    The continue Statement.
                                                              (line   6)
* contributing to Octave:                How You Can Contribute to Octave.
                                                              (line   6)
* contributors:                          Preface.             (line   6)
* conversion specifications (printf):    Formatted Output.    (line  38)
* conversion specifications (scanf):     Formatted Input.     (line  67)
* copyright:                             Keywords.            (line  37)
* core dump:                             Bug Criteria.        (line   9)
* customizing the prompt:                Customizing the Prompt.
                                                              (line   6)
* DAE:                                   Differential Equations.
                                                              (line  14)
* data structures <1>:                   Data Structures.     (line   6)
* data structures:                       Data Structure Objects.
                                                              (line   6)
* data types:                            Data Types.          (line   6)
* data types, built-in:                  Built-in Data Types. (line   6)
* data types, user-defined:              User-defined Data Types.
                                                              (line   6)
* decrement operator:                    Assignment Ops.      (line 124)
* defining functions:                    Functions and Scripts.
                                                              (line   6)
* description format:                    Format of Descriptions.
                                                              (line   6)
* diary of commands and output:          Diary and Echo Commands.
                                                              (line   6)
* Differential Equations:                Differential Equations.
                                                              (line  14)
* diffs, submitting:                     Sending Patches.     (line   6)
* distribution of Octave:                Distribution.        (line   6)
* division:                              Arithmetic Ops.      (line   6)
* do-until statement:                    The do-until Statement.
                                                              (line   6)
* documentation notation:                Evaluation Notation. (line   6)
* documenting Octave programs:           Comments.            (line   6)
* dynamic linking:                       Dynamically Linked Functions.
                                                              (line   6)
* echoing executing commands:            Diary and Echo Commands.
                                                              (line   6)
* editing the command line:              Command Line Editing.
                                                              (line   6)
* element-by-element evaluation:         Element-by-element Boolean Operators.
                                                              (line   6)
* else statement:                        The if Statement.    (line   6)
* elseif statement:                      The if Statement.    (line   6)
* Emacs TAGS files:                      Using Octave Mode.   (line 259)
* end statement:                         Statements.          (line  16)
* end_try_catch:                         The try Statement.   (line   6)
* end_unwind_protect:                    The unwind_protect Statement.
                                                              (line   6)
* endfor statement:                      The for Statement.   (line   6)
* endfunction statement:                 Defining Functions.  (line   6)
* endif statement:                       The if Statement.    (line   6)
* endswitch statement:                   The switch Statement.
                                                              (line   6)
* endwhile statement:                    The while Statement. (line   6)
* equality operator:                     Comparison Ops.      (line   6)
* equality, tests for:                   Comparison Ops.      (line   6)
* equations, nonlinear:                  Nonlinear Equations. (line   6)
* erroneous messages:                    Bug Criteria.        (line  22)
* erroneous results <1>:                 Bug Criteria.        (line  12)
* erroneous results:                     Bug Reporting.       (line  70)
* error message notation:                Error Messages.      (line   6)
* error messages:                        Errors.              (line   6)
* error messages, incorrect:             Bug Criteria.        (line  22)
* escape sequence notation:              Strings.             (line  20)
* evaluation notation:                   Evaluation Notation. (line   6)
* executable scripts:                    Executable Octave Programs.
                                                              (line   6)
* execution speed:                       Coding Tips.         (line   6)
* exiting octave <1>:                    Quitting Octave.     (line   6)
* exiting octave:                        Running Octave.      (line  16)
* exponentiation:                        Arithmetic Ops.      (line   6)
* expression, range:                     Ranges.              (line   6)
* expressions:                           Expressions.         (line   6)
* expressions, assignment:               Assignment Ops.      (line   6)
* expressions, boolean:                  Boolean Expressions. (line   6)
* expressions, comparison:               Comparison Ops.      (line   6)
* expressions, logical:                  Boolean Expressions. (line   6)
* factorial function:                    Recursion.           (line   6)
* fatal signal:                          Bug Criteria.        (line   9)
* financial functions:                   Financial Functions. (line   6)
* flag character (printf):               Output Conversion Syntax.
                                                              (line  28)
* flag character (scanf):                Input Conversion Syntax.
                                                              (line  34)
* flying high and fast:                  Variables.           (line  14)
* fonts:                                 Fonts.               (line   6)
* for statement:                         The for Statement.   (line   6)
* Fordyce, A. P.:                        Evaluation.          (line  42)
* Frobenius norm:                        Basic Matrix Functions.
                                                              (line 104)
* function descriptions:                 A Sample Function Description.
                                                              (line   6)
* function file <1>:                     A Sample Function Description.
                                                              (line  51)
* function file:                         Function Files.      (line   6)
* function statement:                    Defining Functions.  (line   6)
* functions, user-defined:               Functions and Scripts.
                                                              (line   6)
* funding Octave development:            How You Can Contribute to Octave.
                                                              (line   6)
* getting a good job:                    Variables.           (line  14)
* global statement:                      Global Variables.    (line   6)
* global variables:                      Global Variables.    (line   6)
* grammar rules:                         Grammar.             (line   6)
* graphics:                              Two-Dimensional Plotting.
                                                              (line   8)
* greater than operator:                 Comparison Ops.      (line   6)
* handle, function handles:              Function Handles and Inline.
                                                              (line   6)
* header comments:                       Function Headers.    (line   6)
* help, on-line:                         Getting Help.        (line   6)
* help, where to find:                   Service.             (line   6)
* Hermitian operator:                    Arithmetic Ops.      (line   6)
* Hessenberg decomposition:              Matrix Factorizations.
                                                              (line  14)
* history:                               Preface.             (line   6)
* history of commands:                   Commands For History.
                                                              (line   6)
* if statement:                          The if Statement.    (line   6)
* improving Octave <1>:                  Bug Criteria.        (line  29)
* improving Octave:                      Sending Patches.     (line   6)
* incorrect error messages:              Bug Criteria.        (line  22)
* incorrect output <1>:                  Bug Criteria.        (line  12)
* incorrect output:                      Bug Reporting.       (line  70)
* incorrect results <1>:                 Bug Criteria.        (line  12)
* incorrect results:                     Bug Reporting.       (line  70)
* increment operator:                    Assignment Ops.      (line 124)
* infinity norm:                         Basic Matrix Functions.
                                                              (line 100)
* initialization:                        Startup Files.       (line   6)
* inline, inline functions:              Function Handles and Inline.
                                                              (line   6)
* input conversions, for scanf:          Table of Input Conversions.
                                                              (line   6)
* input history:                         Commands For History.
                                                              (line   6)
* installation trouble:                  Trouble.             (line   6)
* installing Octave:                     Installation.        (line   6)
* introduction:                          Introduction.        (line   6)
* invalid input:                         Bug Criteria.        (line  24)
* job hunting:                           Variables.           (line  14)
* keywords:                              Keywords.            (line   6)
* known causes of trouble:               Trouble.             (line   6)
* language definition:                   Grammar.             (line   6)
* less than operator:                    Comparison Ops.      (line   6)
* lists:                                 Lists.               (line   6)
* loadable function:                     A Sample Function Description.
                                                              (line  45)
* logging commands and output:           Diary and Echo Commands.
                                                              (line   6)
* logical expressions:                   Boolean Expressions. (line   6)
* logical operators:                     Boolean Expressions. (line   6)
* loop:                                  The while Statement. (line   6)
* looping over structure elements:       Looping Over Structure Elements.
                                                              (line   6)
* LP:                                    Optimization.        (line  13)
* LU decomposition:                      Matrix Factorizations.
                                                              (line  25)
* lvalue:                                Assignment Ops.      (line  33)
* mapping function:                      A Sample Function Description.
                                                              (line  55)
* matching failure, in scanf:            Formatted Input.     (line  72)
* matrices:                              Matrices.            (line   6)
* matrix multiplication:                 Arithmetic Ops.      (line   6)
* maximum field width (scanf):           Input Conversion Syntax.
                                                              (line  42)
* messages, error:                       Errors.              (line   6)
* minimum field width (printf):          Output Conversion Syntax.
                                                              (line  35)
* missing data:                          Missing Data.        (line   6)
* money:                                 Financial Functions. (line   6)
* multiplication:                        Arithmetic Ops.      (line   6)
* negation:                              Arithmetic Ops.      (line   6)
* NLP:                                   Optimization.        (line  13)
* nonlinear equations:                   Nonlinear Equations. (line   6)
* nonlinear programming:                 Optimization.        (line  13)
* not operator:                          Boolean Expressions. (line   6)
* numeric constant <1>:                  Numeric Data Types.  (line   6)
* numeric constant:                      Numeric Objects.     (line   6)
* numeric value <1>:                     Numeric Data Types.  (line   6)
* numeric value:                         Numeric Objects.     (line   6)
* Octave command options:                Command Line Options.
                                                              (line   6)
* ODE:                                   Differential Equations.
                                                              (line  14)
* on-line help:                          Getting Help.        (line   6)
* operator precedence:                   Operator Precedence. (line   6)
* operators, arithmetic:                 Arithmetic Ops.      (line   6)
* operators, assignment:                 Assignment Ops.      (line   6)
* operators, boolean:                    Boolean Expressions. (line   6)
* operators, decrement:                  Assignment Ops.      (line 124)
* operators, increment:                  Assignment Ops.      (line 124)
* operators, logical:                    Boolean Expressions. (line   6)
* operators, relational:                 Comparison Ops.      (line   6)
* optimization:                          Optimization.        (line  13)
* options, Octave command:               Command Line Options.
                                                              (line   6)
* or operator:                           Boolean Expressions. (line   6)
* oregonator:                            Ordinary Differential Equations.
                                                              (line 139)
* otags:                                 Using Octave Mode.   (line 259)
* otherwise statement:                   The switch Statement.
                                                              (line   6)
* output conversions, for printf:        Table of Output Conversions.
                                                              (line   6)
* partial fraction expansion:            Polynomial Manipulations.
                                                              (line 114)
* patches, submitting:                   Sending Patches.     (line   6)
* persistent statement:                  Persistent Variables.
                                                              (line   6)
* persistent variables:                  Persistent Variables.
                                                              (line   6)
* plotting:                              Two-Dimensional Plotting.
                                                              (line   8)
* precision (printf):                    Output Conversion Syntax.
                                                              (line  47)
* printing notation:                     Printing Notation.   (line   6)
* program, self contained:               Executable Octave Programs.
                                                              (line   6)
* programs:                              Comments.            (line   6)
* prompt customization:                  Customizing the Prompt.
                                                              (line   6)
* QP:                                    Optimization.        (line  13)
* QR factorization:                      Matrix Factorizations.
                                                              (line  52)
* quadratic programming:                 Optimization.        (line  13)
* quitting octave <1>:                   Quitting Octave.     (line   6)
* quitting octave:                       Running Octave.      (line  16)
* quotient:                              Arithmetic Ops.      (line   6)
* range expressions:                     Ranges.              (line   6)
* relational operators:                  Comparison Ops.      (line   6)
* reporting bugs <1>:                    Reporting Bugs.      (line   6)
* reporting bugs:                        Bug Lists.           (line   6)
* results, incorrect <1>:                Bug Reporting.       (line  70)
* results, incorrect:                    Bug Criteria.        (line  12)
* Schur decomposition:                   Matrix Factorizations.
                                                              (line 176)
* script files:                          Functions and Scripts.
                                                              (line   6)
* scripts:                               Executable Octave Programs.
                                                              (line   6)
* self contained programs:               Executable Octave Programs.
                                                              (line   6)
* short-circuit evaluation:              Short-circuit Boolean Operators.
                                                              (line   6)
* side effect:                           Assignment Ops.      (line  26)
* singular value decomposition:          Matrix Factorizations.
                                                              (line 200)
* speedups:                              Coding Tips.         (line   6)
* standards of coding style:             Tips.                (line   6)
* startup:                               Startup Files.       (line   6)
* startup files:                         Startup Files.       (line   9)
* statements:                            Statements.          (line   6)
* strings <1>:                           Strings.             (line   6)
* strings:                               String Objects.      (line   6)
* structure elements, looping over:      Looping Over Structure Elements.
                                                              (line   6)
* structures <1>:                        Data Structures.     (line   6)
* structures:                            Data Structure Objects.
                                                              (line   6)
* submitting diffs:                      Sending Patches.     (line   6)
* submitting patches:                    Sending Patches.     (line   6)
* subtraction:                           Arithmetic Ops.      (line   6)
* suggestions:                           Bug Criteria.        (line  29)
* switch statement:                      The switch Statement.
                                                              (line   6)
* TAGS:                                  Using Octave Mode.   (line 259)
* tests for equality:                    Comparison Ops.      (line   6)
* tips:                                  Tips.                (line   6)
* transpose:                             Arithmetic Ops.      (line   6)
* transpose, complex-conjugate:          Arithmetic Ops.      (line   6)
* troubleshooting:                       Trouble.             (line   6)
* try statement:                         The try Statement.   (line   6)
* unary minus:                           Arithmetic Ops.      (line   6)
* undefined behavior:                    Bug Criteria.        (line  15)
* undefined function value:              Bug Criteria.        (line  15)
* unwind_protect statement:              The unwind_protect Statement.
                                                              (line   6)
* unwind_protect_cleanup:                The unwind_protect Statement.
                                                              (line   6)
* use of comments:                       Comments.            (line   6)
* user-defined data types:               User-defined Data Types.
                                                              (line   6)
* user-defined functions:                Functions and Scripts.
                                                              (line   6)
* user-defined variables:                Variables.           (line   6)
* Utility Functions:                     Utility Functions.   (line 104)
* variable descriptions:                 A Sample Variable Description.
                                                              (line   6)
* variable-length argument lists:        Variable-length Argument Lists.
                                                              (line   6)
* variable-length return lists:          Variable-length Return Lists.
                                                              (line   6)
* variables, global:                     Global Variables.    (line   6)
* variables, persistent:                 Persistent Variables.
                                                              (line   6)
* variables, user-defined:               Variables.           (line   6)
* warranty:                              Keywords.            (line  37)
* while statement:                       The while Statement. (line   6)
* wrong answers <1>:                     Bug Reporting.       (line  70)
* wrong answers:                         Bug Criteria.        (line  12)
* ~/.octaverc:                           Startup Files.       (line  27)


File: octave.info,  Node: Variable Index,  Next: Function Index,  Prev: Concept Index,  Up: Top

Variable Index
**************

[index]
* Menu:

* ans:                                   Terminal Output.     (line  22)
* argv:                                  Command Line Options.
                                                              (line 115)
* automatic_replot:                      Summary of Built-in Variables.
                                                              (line  69)
* beep_on_error <1>:                     Error Handling.      (line  52)
* beep_on_error:                         Summary of Built-in Variables.
                                                              (line  74)
* completion_append_char <1>:            Commands For Completion.
                                                              (line  17)
* completion_append_char:                Summary of Built-in Variables.
                                                              (line  79)
* crash_dumps_octave_core <1>:           Simple File I/O.     (line 102)
* crash_dumps_octave_core:               Summary of Built-in Variables.
                                                              (line  89)
* debug_on_error:                        Debugging.           (line  58)
* debug_on_interrupt:                    Debugging.           (line  46)
* debug_on_warning:                      Debugging.           (line  53)
* DEFAULT_LOADPATH <1>:                  Summary of Built-in Variables.
                                                              (line  14)
* DEFAULT_LOADPATH:                      Function Files.      (line  55)
* default_save_format <1>:               Summary of Built-in Variables.
                                                              (line  84)
* default_save_format:                   Simple File I/O.     (line 121)
* do_what_i_mean_not_what_i_say:         A Sample Variable Description.
                                                              (line  17)
* e:                                     Mathematical Constants.
                                                              (line  35)
* echo_executing_commands:               Diary and Echo Commands.
                                                              (line  54)
* EDITOR <1>:                            Summary of Built-in Variables.
                                                              (line  19)
* EDITOR <2>:                            Defaults from the Environment.
                                                              (line  11)
* EDITOR:                                Commands For History.
                                                              (line 111)
* eps:                                   Mathematical Constants.
                                                              (line  39)
* EXEC_PATH <1>:                         Controlling Subprocesses.
                                                              (line 101)
* EXEC_PATH:                             Summary of Built-in Variables.
                                                              (line  24)
* F_DUPFD:                               Controlling Subprocesses.
                                                              (line 208)
* F_GETFD:                               Controlling Subprocesses.
                                                              (line 211)
* F_GETFL:                               Controlling Subprocesses.
                                                              (line 217)
* F_SETFD:                               Controlling Subprocesses.
                                                              (line 214)
* F_SETFL:                               Controlling Subprocesses.
                                                              (line 246)
* false:                                 Logical Values.      (line  10)
* fixed_point_format <1>:                Matrices.            (line 163)
* fixed_point_format:                    Summary of Built-in Variables.
                                                              (line  94)
* gnuplot_binary <1>:                    Interaction with gnuplot.
                                                              (line   7)
* gnuplot_binary:                        Summary of Built-in Variables.
                                                              (line  99)
* gnuplot_command_axes:                  Interaction with gnuplot.
                                                              (line  29)
* gnuplot_command_end:                   Interaction with gnuplot.
                                                              (line  33)
* gnuplot_command_plot:                  Interaction with gnuplot.
                                                              (line  19)
* gnuplot_command_replot:                Interaction with gnuplot.
                                                              (line  21)
* gnuplot_command_splot:                 Interaction with gnuplot.
                                                              (line  23)
* gnuplot_command_title:                 Interaction with gnuplot.
                                                              (line  31)
* gnuplot_command_using:                 Interaction with gnuplot.
                                                              (line  25)
* gnuplot_command_with:                  Interaction with gnuplot.
                                                              (line  27)
* gnuplot_has_frames:                    Interaction with gnuplot.
                                                              (line  11)
* history_file <1>:                      Summary of Built-in Variables.
                                                              (line 104)
* history_file:                          Commands For History.
                                                              (line 117)
* history_size <1>:                      Summary of Built-in Variables.
                                                              (line 109)
* history_size:                          Commands For History.
                                                              (line 122)
* i:                                     Mathematical Constants.
                                                              (line   9)
* I:                                     Mathematical Constants.
                                                              (line   7)
* ignore_function_time_stamp <1>:        Summary of Built-in Variables.
                                                              (line 114)
* ignore_function_time_stamp:            Function Files.      (line 106)
* IMAGEPATH:                             Image Processing.    (line 157)
* Inf:                                   Mathematical Constants.
                                                              (line  17)
* inf:                                   Mathematical Constants.
                                                              (line  18)
* INFO_FILE <1>:                         Summary of Built-in Variables.
                                                              (line  29)
* INFO_FILE:                             Getting Help.        (line  35)
* INFO_PROGRAM <1>:                      Getting Help.        (line  41)
* INFO_PROGRAM:                          Summary of Built-in Variables.
                                                              (line  34)
* J:                                     Mathematical Constants.
                                                              (line   8)
* j:                                     Mathematical Constants.
                                                              (line  10)
* LOADPATH <1>:                          Function Files.      (line  61)
* LOADPATH:                              Summary of Built-in Variables.
                                                              (line  40)
* MAKEINFO_PROGRAM:                      Getting Help.        (line  52)
* max_recursion_depth <1>:               Recursion.           (line  29)
* max_recursion_depth:                   Summary of Built-in Variables.
                                                              (line 119)
* NA:                                    Missing Data.        (line   7)
* NaN:                                   Mathematical Constants.
                                                              (line  22)
* nan:                                   Mathematical Constants.
                                                              (line  23)
* O_APPEND:                              Controlling Subprocesses.
                                                              (line 231)
* O_ASYNC:                               Controlling Subprocesses.
                                                              (line 243)
* O_CREAT:                               Controlling Subprocesses.
                                                              (line 234)
* O_NONBLOCK:                            Controlling Subprocesses.
                                                              (line 237)
* O_RDONLY:                              Controlling Subprocesses.
                                                              (line 222)
* O_RDWR:                                Controlling Subprocesses.
                                                              (line 228)
* O_SYNC:                                Controlling Subprocesses.
                                                              (line 240)
* O_WRONLY:                              Controlling Subprocesses.
                                                              (line 225)
* OCTAVE_EXEC_PATH:                      Defaults from the Environment.
                                                              (line  16)
* OCTAVE_HISTFILE:                       Defaults from the Environment.
                                                              (line  44)
* OCTAVE_HISTSIZE:                       Defaults from the Environment.
                                                              (line  39)
* OCTAVE_HOME:                           Summary of Built-in Variables.
                                                              (line  46)
* OCTAVE_INFO_FILE:                      Defaults from the Environment.
                                                              (line  27)
* OCTAVE_INFO_PROGRAM:                   Defaults from the Environment.
                                                              (line  33)
* OCTAVE_PATH:                           Defaults from the Environment.
                                                              (line  22)
* OCTAVE_VERSION:                        System Information.  (line  23)
* output_max_field_width <1>:            Matrices.            (line 114)
* output_max_field_width:                Summary of Built-in Variables.
                                                              (line 124)
* output_precision <1>:                  Summary of Built-in Variables.
                                                              (line 129)
* output_precision:                      Matrices.            (line 118)
* page_output_immediately:               Input and Output.    (line  55)
* page_screen_output <1>:                Summary of Built-in Variables.
                                                              (line 134)
* page_screen_output:                    Input and Output.    (line  48)
* PAGER <1>:                             Input and Output.    (line  39)
* PAGER:                                 Summary of Built-in Variables.
                                                              (line  49)
* pi:                                    Mathematical Constants.
                                                              (line  31)
* print_answer_id_name <1>:              Summary of Built-in Variables.
                                                              (line 139)
* print_answer_id_name:                  Terminal Output.     (line 199)
* print_empty_dimensions <1>:            Summary of Built-in Variables.
                                                              (line 144)
* print_empty_dimensions:                Empty Matrices.      (line  30)
* print_rhs_assign_val:                  Assignment Ops.      (line 120)
* program_invocation_name:               Command Line Options.
                                                              (line 129)
* program_name:                          Command Line Options.
                                                              (line 130)
* PS1 <1>:                               Customizing the Prompt.
                                                              (line  57)
* PS1:                                   Summary of Built-in Variables.
                                                              (line  54)
* PS2 <1>:                               Summary of Built-in Variables.
                                                              (line  59)
* PS2:                                   Customizing the Prompt.
                                                              (line  72)
* PS4 <1>:                               Summary of Built-in Variables.
                                                              (line  64)
* PS4:                                   Customizing the Prompt.
                                                              (line  79)
* realmax:                               Mathematical Constants.
                                                              (line  46)
* realmin:                               Mathematical Constants.
                                                              (line  52)
* return:                                Returning From a Function.
                                                              (line  38)
* return_last_computed_value:            Summary of Built-in Variables.
                                                              (line 149)
* save_header_format_string:             Simple File I/O.     (line 131)
* save_precision <1>:                    Summary of Built-in Variables.
                                                              (line 154)
* save_precision:                        Simple File I/O.     (line 127)
* saving_history <1>:                    Commands For History.
                                                              (line 127)
* saving_history:                        Summary of Built-in Variables.
                                                              (line 159)
* SEEK_CUR:                              File Positioning.    (line  27)
* SEEK_END:                              File Positioning.    (line  28)
* SEEK_SET:                              File Positioning.    (line  26)
* sighup_dumps_octave_core <1>:          Simple File I/O.     (line 109)
* sighup_dumps_octave_core:              Summary of Built-in Variables.
                                                              (line 164)
* sigterm_dumps_octave_core <1>:         Simple File I/O.     (line 115)
* sigterm_dumps_octave_core:             Summary of Built-in Variables.
                                                              (line 169)
* silent_functions <1>:                  Summary of Built-in Variables.
                                                              (line 174)
* silent_functions:                      Defining Functions.  (line 156)
* split_long_rows <1>:                   Summary of Built-in Variables.
                                                              (line 179)
* split_long_rows:                       Matrices.            (line 127)
* stderr:                                C-Style I/O Functions.
                                                              (line  29)
* stdin:                                 C-Style I/O Functions.
                                                              (line  20)
* stdout:                                C-Style I/O Functions.
                                                              (line  25)
* string_fill_char:                      Creating Strings.    (line  59)
* struct_levels_to_print <1>:            Data Structures.     (line  93)
* struct_levels_to_print:                Summary of Built-in Variables.
                                                              (line 184)
* suppress_verbose_help_message <1>:     Summary of Built-in Variables.
                                                              (line 189)
* suppress_verbose_help_message:         Getting Help.        (line  57)
* true:                                  Logical Values.      (line   7)
* variables_can_hide_functions:          Dynamically Linked Functions.
                                                              (line 158)
* warn_assign_as_truth_value <1>:        Summary of Built-in Variables.
                                                              (line 194)
* warn_assign_as_truth_value:            The if Statement.    (line 112)
* warn_comma_in_global_decl:             Summary of Built-in Variables.
                                                              (line 199)
* warn_divide_by_zero <1>:               Summary of Built-in Variables.
                                                              (line 204)
* warn_divide_by_zero:                   Arithmetic Ops.      (line 115)
* warn_empty_list_elements <1>:          Summary of Built-in Variables.
                                                              (line 209)
* warn_empty_list_elements:              Empty Matrices.      (line  45)
* warn_fortran_indexing <1>:             Summary of Built-in Variables.
                                                              (line 214)
* warn_fortran_indexing:                 Index Expressions.   (line  18)
* warn_function_name_clash <1>:          Summary of Built-in Variables.
                                                              (line 219)
* warn_function_name_clash:              Function Files.      (line 120)
* warn_future_time_stamp:                Function Files.      (line 127)
* warn_imag_to_real <1>:                 Special Utility Matrices.
                                                              (line 183)
* warn_imag_to_real:                     Summary of Built-in Variables.
                                                              (line 224)
* warn_missing_semicolon <1>:            Summary of Built-in Variables.
                                                              (line 229)
* warn_missing_semicolon:                Defining Functions.  (line 171)
* warn_neg_dim_as_zero <1>:              Summary of Built-in Variables.
                                                              (line 234)
* warn_neg_dim_as_zero:                  Special Utility Matrices.
                                                              (line 175)
* warn_num_to_str <1>:                   String Conversions.  (line 147)
* warn_num_to_str:                       Summary of Built-in Variables.
                                                              (line 239)
* warn_reload_forces_clear <1>:          Dynamically Linked Functions.
                                                              (line 151)
* warn_reload_forces_clear:              Summary of Built-in Variables.
                                                              (line 244)
* warn_resize_on_range_error <1>:        Summary of Built-in Variables.
                                                              (line 249)
* warn_resize_on_range_error:            Index Expressions.   (line  57)
* warn_separator_insert <1>:             Matrices.            (line 103)
* warn_separator_insert:                 Summary of Built-in Variables.
                                                              (line 254)
* warn_single_quote_string <1>:          Summary of Built-in Variables.
                                                              (line 259)
* warn_single_quote_string:              String Conversions.  (line 167)
* warn_str_to_num <1>:                   String Conversions.  (line 158)
* warn_str_to_num:                       Summary of Built-in Variables.
                                                              (line 264)
* warn_undefined_return_values <1>:      Summary of Built-in Variables.
                                                              (line 269)
* warn_undefined_return_values:          Multiple Return Values.
                                                              (line  95)
* warn_variable_switch_label <1>:        Summary of Built-in Variables.
                                                              (line 274)
* warn_variable_switch_label:            The switch Statement.
                                                              (line  70)
* whos_line_format:                      Status of Variables. (line  80)


File: octave.info,  Node: Function Index,  Next: Operator Index,  Prev: Variable Index,  Up: Top

Function Index
**************

[index]
* Menu:

* ( <1>:                                 Audio Processing.    (line  76)
* (:                                     Signal Processing.   (line 180)
* = <1>:                                 Signal Processing.   (line 300)
* =:                                     Rearranging Matrices.
                                                              (line 182)
* [:                                     Coordinate Transformations.
                                                              (line  19)
* abcddim:                               sysprop.             (line  10)
* abs:                                   Complex Arithmetic.  (line  13)
* acos:                                  Trigonometry.        (line  32)
* acosh:                                 Trigonometry.        (line  68)
* acot:                                  Trigonometry.        (line  44)
* acoth:                                 Trigonometry.        (line  80)
* acsc:                                  Trigonometry.        (line  41)
* acsch:                                 Trigonometry.        (line  77)
* airy:                                  Special Functions.   (line  59)
* all:                                   Finding Elements and Checking Conditions.
                                                              (line  29)
* analdemo:                              sysprop.             (line   7)
* angle:                                 Complex Arithmetic.  (line  22)
* anova:                                 Tests.               (line   7)
* any:                                   Finding Elements and Checking Conditions.
                                                              (line  12)
* append:                                Lists.               (line  13)
* arch_fit:                              Signal Processing.   (line 194)
* arch_rnd:                              Signal Processing.   (line 215)
* arch_test:                             Signal Processing.   (line 225)
* are:                                   numerical.           (line   7)
* arg:                                   Complex Arithmetic.  (line  21)
* argnames:                              Inline Functions.    (line  25)
* arma_rnd:                              Signal Processing.   (line 256)
* asctime:                               Timing Utilities.    (line 109)
* asec:                                  Trigonometry.        (line  38)
* asech:                                 Trigonometry.        (line  74)
* asin:                                  Trigonometry.        (line  29)
* asinh:                                 Trigonometry.        (line  65)
* atan:                                  Trigonometry.        (line  35)
* atan2:                                 Trigonometry.        (line  90)
* atanh:                                 Trigonometry.        (line  71)
* atexit:                                Quitting Octave.     (line  13)
* autocor:                               Signal Processing.   (line 270)
* autocov:                               Signal Processing.   (line 275)
* autoreg_matrix:                        Signal Processing.   (line 280)
* axis:                                  Two-Dimensional Plotting.
                                                              (line 178)
* axis2dlim:                             misc.                (line   7)
* balance:                               Basic Matrix Functions.
                                                              (line   7)
* bar:                                   Specialized Two-Dimensional Plots.
                                                              (line   7)
* bartlett:                              Signal Processing.   (line 287)
* bartlett_test:                         Tests.               (line  30)
* base2dec:                              String Conversions.  (line  74)
* bddemo:                                blockdiag.           (line  12)
* besselh:                               Special Functions.   (line  11)
* besseli:                               Special Functions.   (line   9)
* besselj:                               Special Functions.   (line   7)
* besselk:                               Special Functions.   (line  10)
* bessely:                               Special Functions.   (line   8)
* beta:                                  Special Functions.   (line  92)
* beta_cdf:                              Distributions.       (line   7)
* beta_inv:                              Distributions.       (line  12)
* beta_pdf:                              Distributions.       (line  16)
* beta_rnd:                              Distributions.       (line  20)
* betainc:                               Special Functions.   (line  97)
* bincoeff:                              Special Functions.   (line 109)
* binomial_cdf:                          Distributions.       (line  29)
* binomial_inv:                          Distributions.       (line  33)
* binomial_pdf:                          Distributions.       (line  37)
* binomial_rnd:                          Distributions.       (line  42)
* blackman:                              Signal Processing.   (line 294)
* blanks:                                Creating Strings.    (line   7)
* bode:                                  sysfreq.             (line  12)
* bode_bounds:                           sysfreq.             (line  77)
* bottom_title:                          Plot Annotations.    (line  23)
* bug_report <1>:                        Bug Lists.           (line   6)
* bug_report:                            Reporting Bugs.      (line  20)
* buildssic:                             blockdiag.           (line  16)
* c2d:                                   systime.             (line   7)
* cat:                                   Rearranging Matrices.
                                                              (line  87)
* cauchy_cdf:                            Distributions.       (line  50)
* cauchy_inv:                            Distributions.       (line  56)
* cauchy_pdf:                            Distributions.       (line  62)
* cauchy_rnd:                            Distributions.       (line  68)
* cd <1>:                                A Sample Command Description.
                                                              (line  13)
* cd:                                    Current Working Directory.
                                                              (line   7)
* ceil:                                  Utility Functions.   (line  12)
* cell:                                  Cell Arrays.         (line   7)
* cellstr:                               Cell Arrays.         (line  16)
* center:                                Basic Statistical Functions.
                                                              (line 311)
* char:                                  Creating Strings.    (line  12)
* chdir <1>:                             Current Working Directory.
                                                              (line   8)
* chdir:                                 A Sample Command Description.
                                                              (line  14)
* chisquare_cdf:                         Distributions.       (line  77)
* chisquare_inv:                         Distributions.       (line  82)
* chisquare_pdf:                         Distributions.       (line  86)
* chisquare_rnd:                         Distributions.       (line  90)
* chisquare_test_homogeneity:            Tests.               (line  44)
* chisquare_test_independence:           Tests.               (line  58)
* chol:                                  Matrix Factorizations.
                                                              (line   7)
* clc:                                   Cursor Motion.       (line  57)
* clear:                                 Status of Variables. (line   7)
* clearplot:                             Two-Dimensional Plotting.
                                                              (line 148)
* clg:                                   Two-Dimensional Plotting.
                                                              (line 149)
* clock:                                 Timing Utilities.    (line 260)
* cloglog:                               Basic Statistical Functions.
                                                              (line 306)
* closeplot:                             Two-Dimensional Plotting.
                                                              (line 163)
* colloc:                                Orthogonal Collocation.
                                                              (line   7)
* colormap:                              Image Processing.    (line  19)
* columns:                               Object Sizes.        (line  13)
* com2str:                               Creating Strings.    (line  39)
* common_size:                           Finding Elements and Checking Conditions.
                                                              (line 119)
* commutation_matrix:                    Special Functions.   (line 178)
* compan:                                Polynomial Manipulations.
                                                              (line  12)
* complement:                            Sets.                (line  31)
* completion_matches:                    Commands For Completion.
                                                              (line  22)
* computer:                              System Information.  (line   7)
* cond:                                  Basic Matrix Functions.
                                                              (line  44)
* conj:                                  Complex Arithmetic.  (line  31)
* contour:                               Specialized Two-Dimensional Plots.
                                                              (line  25)
* conv:                                  Polynomial Manipulations.
                                                              (line  30)
* cor:                                   Basic Statistical Functions.
                                                              (line 296)
* cor_test:                              Tests.               (line  69)
* corrcoef:                              Basic Statistical Functions.
                                                              (line  70)
* cos:                                   Trigonometry.        (line  14)
* cosh:                                  Trigonometry.        (line  50)
* cot:                                   Trigonometry.        (line  26)
* coth:                                  Trigonometry.        (line  62)
* cov:                                   Basic Statistical Functions.
                                                              (line  64)
* cputime:                               Timing Utilities.    (line 288)
* create_set:                            Sets.                (line  10)
* cross:                                 Special Functions.   (line 166)
* csc:                                   Trigonometry.        (line  23)
* csch:                                  Trigonometry.        (line  59)
* ctime:                                 Timing Utilities.    (line  55)
* ctrb:                                  sysprop.             (line  36)
* cumprod:                               Sums and Products.   (line  29)
* cumsum:                                Sums and Products.   (line  21)
* cut:                                   Basic Statistical Functions.
                                                              (line 283)
* d2c:                                   systime.             (line  56)
* damp:                                  systime.             (line 145)
* dare:                                  numerical.           (line  35)
* daspk:                                 Differential-Algebraic Equations.
                                                              (line  14)
* daspk_options:                         Differential-Algebraic Equations.
                                                              (line  76)
* dasrt:                                 Differential-Algebraic Equations.
                                                              (line 241)
* dasrt_options:                         Differential-Algebraic Equations.
                                                              (line 337)
* date:                                  Timing Utilities.    (line 270)
* dbclear:                               Debugging.           (line  20)
* dbstatus:                              Debugging.           (line  33)
* dbstop:                                Debugging.           (line   7)
* dbtype:                                Debugging.           (line  43)
* dbwhere:                               Debugging.           (line  40)
* dcgain:                                systime.             (line 152)
* deblank:                               Searching and Replacing.
                                                              (line   7)
* dec2base:                              String Conversions.  (line  55)
* dec2bin:                               String Conversions.  (line  17)
* dec2hex:                               String Conversions.  (line  30)
* deconv:                                Polynomial Manipulations.
                                                              (line  37)
* DEMOcontrol:                           Control Theory.      (line  25)
* det:                                   Basic Matrix Functions.
                                                              (line  49)
* detrend:                               Signal Processing.   (line  11)
* dgkfdemo:                              cacsd.               (line   7)
* dgram:                                 numerical.           (line 113)
* diag:                                  Special Utility Matrices.
                                                              (line 142)
* diary:                                 Diary and Echo Commands.
                                                              (line  11)
* diff:                                  Finding Elements and Checking Conditions.
                                                              (line  56)
* discrete_cdf:                          Distributions.       (line  99)
* discrete_inv:                          Distributions.       (line 104)
* discrete_pdf:                          Distributions.       (line 109)
* discrete_rnd:                          Distributions.       (line 116)
* disp:                                  Terminal Output.     (line  41)
* dkalman:                               cacsd.               (line 166)
* dlqe:                                  cacsd.               (line 108)
* dlqr:                                  cacsd.               (line 139)
* dlyap:                                 numerical.           (line 129)
* dmr2d:                                 systime.             (line  94)
* dmult:                                 Basic Matrix Functions.
                                                              (line  53)
* do_string_escapes:                     String Conversions.  (line 124)
* document:                              Status of Variables. (line 157)
* dot:                                   Basic Matrix Functions.
                                                              (line  57)
* dre:                                   numerical.           (line  71)
* dup2:                                  Controlling Subprocesses.
                                                              (line 164)
* duplication_matrix:                    Special Functions.   (line 188)
* durbinlevinson:                        Signal Processing.   (line 316)
* echo:                                  Diary and Echo Commands.
                                                              (line  31)
* edit_history:                          Commands For History.
                                                              (line  77)
* eig:                                   Basic Matrix Functions.
                                                              (line  64)
* empirical_cdf:                         Distributions.       (line 124)
* empirical_inv:                         Distributions.       (line 129)
* empirical_pdf:                         Distributions.       (line 134)
* empirical_rnd:                         Distributions.       (line 141)
* endgrent:                              Group Database Functions.
                                                              (line  42)
* endpwent:                              Password Database Functions.
                                                              (line  53)
* erf:                                   Special Functions.   (line 123)
* erfc:                                  Special Functions.   (line 132)
* erfinv:                                Special Functions.   (line 135)
* error:                                 Error Handling.      (line  12)
* errorbar:                              Specialized Two-Dimensional Plots.
                                                              (line  91)
* etime:                                 Timing Utilities.    (line 277)
* eval:                                  Evaluation.          (line  18)
* exec:                                  Controlling Subprocesses.
                                                              (line 144)
* exist:                                 Status of Variables. (line 126)
* exit:                                  Quitting Octave.     (line   7)
* exp:                                   Utility Functions.   (line  16)
* expm:                                  Functions of a Matrix.
                                                              (line   7)
* exponential_cdf:                       Distributions.       (line 148)
* exponential_inv:                       Distributions.       (line 155)
* exponential_pdf:                       Distributions.       (line 159)
* exponential_rnd:                       Distributions.       (line 163)
* eye:                                   Special Utility Matrices.
                                                              (line   7)
* f_cdf:                                 Distributions.       (line 172)
* f_inv:                                 Distributions.       (line 176)
* f_pdf:                                 Distributions.       (line 180)
* f_rnd:                                 Distributions.       (line 184)
* f_test_regression:                     Tests.               (line 111)
* fclose:                                Opening and Closing Files.
                                                              (line  88)
* fcntl:                                 Controlling Subprocesses.
                                                              (line 205)
* fdisp:                                 Terminal Output.     (line  31)
* feof:                                  EOF and Errors.      (line   7)
* ferror:                                EOF and Errors.      (line  13)
* feval:                                 Evaluation.          (line  24)
* fflush:                                Input and Output.    (line  61)
* fft:                                   Signal Processing.   (line  21)
* fft2:                                  Signal Processing.   (line  54)
* fftconv:                               Signal Processing.   (line  90)
* fftfilt:                               Signal Processing.   (line  99)
* fftn:                                  Signal Processing.   (line  72)
* fftshift:                              Signal Processing.   (line 326)
* fgetl:                                 Line-Oriented Input. (line   7)
* fgets:                                 Line-Oriented Input. (line  16)
* fieldnames:                            Data Structures.     (line 155)
* figure:                                Multiple Plot Windows.
                                                              (line   7)
* file_in_loadpath:                      Function Files.      (line  93)
* file_in_path:                          Filesystem Utilities.
                                                              (line 170)
* filter:                                Signal Processing.   (line 110)
* find:                                  Finding Elements and Checking Conditions.
                                                              (line  95)
* findstr:                               Searching and Replacing.
                                                              (line  11)
* finite:                                Finding Elements and Checking Conditions.
                                                              (line  88)
* fir2sys:                               fir2sys.             (line   7)
* fix:                                   Utility Functions.   (line  20)
* flipdim:                               Rearranging Matrices.
                                                              (line  30)
* fliplr:                                Rearranging Matrices.
                                                              (line   7)
* flipud:                                Rearranging Matrices.
                                                              (line  18)
* floor:                                 Utility Functions.   (line  24)
* fnmatch:                               Filesystem Utilities.
                                                              (line 162)
* foo:                                   A Sample Function Description.
                                                              (line  14)
* fopen:                                 Opening and Closing Files.
                                                              (line   9)
* fork:                                  Controlling Subprocesses.
                                                              (line 124)
* format:                                Terminal Output.     (line  54)
* formula:                               Inline Functions.    (line  29)
* fprintf:                               Formatted Output.    (line  20)
* fputs:                                 Simple Output.       (line   7)
* fractdiff:                             Signal Processing.   (line 344)
* frdemo:                                sysfreq.             (line   9)
* fread:                                 Binary I/O.          (line  14)
* freport:                               EOF and Errors.      (line  19)
* freqchkw:                              sysfreq.             (line  84)
* freqz:                                 Signal Processing.   (line 147)
* frewind:                               File Positioning.    (line  41)
* fscanf:                                Formatted Input.     (line  14)
* fseek:                                 File Positioning.    (line  14)
* fsolve:                                Nonlinear Equations. (line  14)
* fsolve_options:                        Nonlinear Equations. (line  31)
* ftell:                                 File Positioning.    (line  10)
* func2str:                              Function Handles.    (line  11)
* functions:                             Function Handles.    (line   7)
* fv:                                    Financial Functions. (line   7)
* fvl:                                   Financial Functions. (line  22)
* fwrite:                                Binary I/O.          (line 172)
* gamma:                                 Special Functions.   (line 138)
* gamma_cdf:                             Distributions.       (line 194)
* gamma_inv:                             Distributions.       (line 199)
* gamma_pdf:                             Distributions.       (line 203)
* gamma_rnd:                             Distributions.       (line 208)
* gammainc:                              Special Functions.   (line 147)
* gammaln:                               Special Functions.   (line 163)
* gcd:                                   Utility Functions.   (line  29)
* geometric_cdf:                         Distributions.       (line 216)
* geometric_inv:                         Distributions.       (line 220)
* geometric_pdf:                         Distributions.       (line 224)
* geometric_rnd:                         Distributions.       (line 229)
* getegid:                               Process ID Information.
                                                              (line  22)
* getenv:                                Environment Variables.
                                                              (line   7)
* geteuid:                               Process ID Information.
                                                              (line  16)
* getgid:                                Process ID Information.
                                                              (line  25)
* getgrent:                              Group Database Functions.
                                                              (line  25)
* getgrgid:                              Group Database Functions.
                                                              (line  29)
* getgrnam:                              Group Database Functions.
                                                              (line  34)
* getpgrp:                               Process ID Information.
                                                              (line   7)
* getpid:                                Process ID Information.
                                                              (line  10)
* getppid:                               Process ID Information.
                                                              (line  13)
* getpwent:                              Password Database Functions.
                                                              (line  34)
* getpwnam:                              Password Database Functions.
                                                              (line  44)
* getpwuid:                              Password Database Functions.
                                                              (line  39)
* getrusage:                             System Information.  (line  34)
* getuid:                                Process ID Information.
                                                              (line  19)
* givens:                                Basic Matrix Functions.
                                                              (line  71)
* glob:                                  Filesystem Utilities.
                                                              (line 153)
* gls:                                   Linear Least Squares.
                                                              (line   7)
* gmtime:                                Timing Utilities.    (line  64)
* gplot:                                 Low-Level plotting commands.
                                                              (line   7)
* gram:                                  numerical.           (line 162)
* gray:                                  Image Processing.    (line  33)
* gray2ind:                              Image Processing.    (line  38)
* grid:                                  Plot Annotations.    (line   7)
* gset:                                  Low-Level plotting commands.
                                                              (line 120)
* gshow:                                 Low-Level plotting commands.
                                                              (line 121)
* gsplot:                                Low-Level plotting commands.
                                                              (line  70)
* h2norm:                                sysprop.             (line  46)
* h2syn:                                 cacsd.               (line 202)
* hamming:                               Signal Processing.   (line 348)
* hankel:                                Famous Matrices.     (line   9)
* hanning:                               Signal Processing.   (line 354)
* help:                                  Getting Help.        (line  15)
* hess:                                  Matrix Factorizations.
                                                              (line  14)
* hex2dec:                               String Conversions.  (line  43)
* hilb:                                  Famous Matrices.     (line  22)
* hinf_ctr:                              cacsd.               (line 245)
* hinfdemo:                              cacsd.               (line  10)
* hinfnorm:                              sysprop.             (line  55)
* hinfsyn:                               cacsd.               (line 265)
* hinfsyn_chk:                           cacsd.               (line 328)
* hinfsyn_ric:                           cacsd.               (line 358)
* hist:                                  Specialized Two-Dimensional Plots.
                                                              (line  31)
* history:                               Commands For History.
                                                              (line  51)
* hold:                                  Two-Dimensional Plotting.
                                                              (line 132)
* home:                                  Cursor Motion.       (line  58)
* horzcat:                               Rearranging Matrices.
                                                              (line 120)
* hotelling_test:                        Tests.               (line 125)
* hotelling_test_2:                      Tests.               (line 140)
* housh:                                 Matrix Factorizations.
                                                              (line 247)
* HSV_MAP:                               Image Processing.    (line 115)
* hurst:                                 Signal Processing.   (line 360)
* hypergeometric_cdf:                    Distributions.       (line 237)
* hypergeometric_inv:                    Distributions.       (line 247)
* hypergeometric_pdf:                    Distributions.       (line 254)
* hypergeometric_rnd:                    Distributions.       (line 264)
* ifft:                                  Signal Processing.   (line  37)
* ifftn:                                 Signal Processing.   (line  81)
* imag:                                  Complex Arithmetic.  (line  34)
* image:                                 Image Processing.    (line  42)
* imagesc:                               Image Processing.    (line  57)
* impulse:                               systime.             (line 157)
* imshow:                                Image Processing.    (line  74)
* ind2gray:                              Image Processing.    (line  93)
* ind2rgb:                               Image Processing.    (line  98)
* index:                                 Searching and Replacing.
                                                              (line  22)
* inline:                                Inline Functions.    (line   8)
* input:                                 Terminal Input.      (line  12)
* int2str:                               Creating Strings.    (line  31)
* intersection:                          Sets.                (line  24)
* inv:                                   Basic Matrix Functions.
                                                              (line  82)
* inverse:                               Basic Matrix Functions.
                                                              (line  83)
* invhilb:                               Famous Matrices.     (line  28)
* ipermute:                              Rearranging Matrices.
                                                              (line 134)
* iqr:                                   Basic Statistical Functions.
                                                              (line 275)
* irr:                                   Financial Functions. (line  29)
* is_abcd:                               sysprop.             (line 127)
* is_controllable:                       sysprop.             (line 133)
* is_detectable:                         sysprop.             (line 164)
* is_dgkf:                               sysprop.             (line 176)
* is_digital:                            sysprop.             (line 261)
* is_duplicate_entry:                    Finding Elements and Checking Conditions.
                                                              (line  53)
* is_leap_year:                          Timing Utilities.    (line 299)
* is_nan_or_na:                          Missing Data.        (line  17)
* is_observable:                         sysprop.             (line 282)
* is_sample:                             sysprop.             (line 294)
* is_signal_list:                        sysprop.             (line 312)
* is_siso:                               sysprop.             (line 297)
* is_stabilizable:                       sysprop.             (line 301)
* is_stable:                             sysprop.             (line 316)
* isalnum:                               Character Class Functions.
                                                              (line  16)
* isalpha:                               Character Class Functions.
                                                              (line  20)
* isascii:                               Character Class Functions.
                                                              (line  25)
* isbool:                                Predicates for Numeric Objects.
                                                              (line  34)
* iscell:                                Cell Arrays.         (line  20)
* ischar:                                Creating Strings.    (line  78)
* iscntrl:                               Character Class Functions.
                                                              (line  29)
* iscomplex:                             Predicates for Numeric Objects.
                                                              (line  13)
* isdigit:                               Character Class Functions.
                                                              (line  32)
* isempty:                               Object Sizes.        (line  47)
* isfield:                               Data Structures.     (line 160)
* isglobal:                              Global Variables.    (line  64)
* isgraph:                               Character Class Functions.
                                                              (line  35)
* ishold:                                Two-Dimensional Plotting.
                                                              (line 144)
* isieee:                                System Information.  (line  19)
* isinf:                                 Finding Elements and Checking Conditions.
                                                              (line  74)
* isletter:                              Character Class Functions.
                                                              (line  21)
* islist:                                Lists.               (line  35)
* islower:                               Character Class Functions.
                                                              (line  38)
* ismatrix:                              Predicates for Numeric Objects.
                                                              (line  16)
* isna:                                  Missing Data.        (line  10)
* isnan:                                 Finding Elements and Checking Conditions.
                                                              (line  81)
* isnumeric:                             Predicates for Numeric Objects.
                                                              (line   7)
* isprint:                               Character Class Functions.
                                                              (line  41)
* ispunct:                               Character Class Functions.
                                                              (line  44)
* isreal:                                Predicates for Numeric Objects.
                                                              (line  10)
* isscalar:                              Predicates for Numeric Objects.
                                                              (line  22)
* isspace:                               Character Class Functions.
                                                              (line  47)
* issquare:                              Predicates for Numeric Objects.
                                                              (line  25)
* isstr:                                 Creating Strings.    (line  81)
* isstream:                              I/O Streams.         (line   7)
* isstruct:                              Data Structures.     (line 152)
* issymmetric:                           Predicates for Numeric Objects.
                                                              (line  29)
* isupper:                               Character Class Functions.
                                                              (line  51)
* isvector:                              Predicates for Numeric Objects.
                                                              (line  19)
* isxdigit:                              Character Class Functions.
                                                              (line  54)
* jet707:                                blockdiag.           (line 110)
* kbhit:                                 Terminal Input.      (line  67)
* kendall:                               Basic Statistical Functions.
                                                              (line 251)
* keyboard:                              Terminal Input.      (line  47)
* kolmogorov_smirnov_cdf:                Distributions.       (line 275)
* kolmogorov_smirnov_test:               Tests.               (line 160)
* kolmogorov_smirnov_test_2:             Tests.               (line 186)
* kron:                                  Functions of a Matrix.
                                                              (line  40)
* kruskal_wallis_test:                   Tests.               (line 210)
* krylov:                                Matrix Factorizations.
                                                              (line 255)
* kurtosis:                              Basic Statistical Functions.
                                                              (line  76)
* laplace_cdf:                           Distributions.       (line 286)
* laplace_inv:                           Distributions.       (line 290)
* laplace_pdf:                           Distributions.       (line 294)
* laplace_rnd:                           Distributions.       (line 298)
* lasterr:                               Error Handling.      (line  86)
* lastwarn:                              Error Handling.      (line  91)
* lcm:                                   Utility Functions.   (line  53)
* length:                                Object Sizes.        (line  19)
* lgamma:                                Special Functions.   (line 162)
* lin2mu:                                Audio Processing.    (line  28)
* link:                                  Filesystem Utilities.
                                                              (line  17)
* linspace:                              Special Utility Matrices.
                                                              (line 158)
* list:                                  Lists.               (line   7)
* load:                                  Simple File I/O.     (line 143)
* loadaudio:                             Audio Processing.    (line  41)
* loadimage:                             Image Processing.    (line 102)
* localtime:                             Timing Utilities.    (line  83)
* log:                                   Utility Functions.   (line  65)
* log10:                                 Utility Functions.   (line  69)
* log2:                                  Utility Functions.   (line  73)
* logistic_cdf:                          Distributions.       (line 303)
* logistic_inv:                          Distributions.       (line 307)
* logistic_pdf:                          Distributions.       (line 311)
* logistic_regression:                   Models.              (line   8)
* logistic_rnd:                          Distributions.       (line 315)
* logit:                                 Basic Statistical Functions.
                                                              (line 248)
* loglog:                                Specialized Two-Dimensional Plots.
                                                              (line  52)
* loglogerr:                             Specialized Two-Dimensional Plots.
                                                              (line 159)
* logm:                                  Functions of a Matrix.
                                                              (line  28)
* lognormal_cdf:                         Distributions.       (line 320)
* lognormal_inv:                         Distributions.       (line 329)
* lognormal_pdf:                         Distributions.       (line 337)
* lognormal_rnd:                         Distributions.       (line 346)
* logspace:                              Special Utility Matrices.
                                                              (line 167)
* lqe:                                   cacsd.               (line 385)
* lqg:                                   cacsd.               (line 418)
* lqr:                                   cacsd.               (line 464)
* ls:                                    Current Working Directory.
                                                              (line  19)
* lsim:                                  cacsd.               (line 506)
* lsode:                                 Ordinary Differential Equations.
                                                              (line  15)
* lsode_options:                         Ordinary Differential Equations.
                                                              (line  81)
* lstat:                                 Filesystem Utilities.
                                                              (line  75)
* ltifr:                                 sysfreq.             (line  89)
* lu:                                    Matrix Factorizations.
                                                              (line  25)
* lyap:                                  numerical.           (line 168)
* mahalanobis:                           Basic Statistical Functions.
                                                              (line  85)
* manova:                                Tests.               (line 225)
* max:                                   Utility Functions.   (line  77)
* mcnemar_test:                          Tests.               (line 239)
* mean:                                  Basic Statistical Functions.
                                                              (line   7)
* meansq:                                Basic Statistical Functions.
                                                              (line 242)
* median:                                Basic Statistical Functions.
                                                              (line  31)
* menu:                                  Terminal Input.      (line  39)
* mesh:                                  Three-Dimensional Plotting.
                                                              (line   9)
* meshdom:                               Three-Dimensional Plotting.
                                                              (line  22)
* meshgrid:                              Three-Dimensional Plotting.
                                                              (line  17)
* min:                                   Utility Functions.   (line 104)
* minfo:                                 structaccess.        (line 287)
* mkdir:                                 Filesystem Utilities.
                                                              (line  49)
* mkfifo:                                Filesystem Utilities.
                                                              (line  61)
* mkstemp:                               Temporary Files.     (line   7)
* mktime:                                Timing Utilities.    (line 102)
* mod:                                   Utility Functions.   (line 129)
* moddemo:                               misc.                (line  20)
* moment:                                Basic Statistical Functions.
                                                              (line 225)
* more:                                  Input and Output.    (line  34)
* mplot:                                 Multiple Plots on One Page.
                                                              (line  12)
* mu2lin:                                Audio Processing.    (line  35)
* multiplot:                             Multiple Plots on One Page.
                                                              (line  20)
* nargchk:                               Multiple Return Values.
                                                              (line 100)
* nargin:                                Defining Functions.  (line 148)
* nargout:                               Multiple Return Values.
                                                              (line  77)
* newtroot:                              Evaluation.          (line  42)
* nextpow2:                              Utility Functions.   (line 141)
* norm:                                  Basic Matrix Functions.
                                                              (line  88)
* normal_cdf:                            Distributions.       (line 355)
* normal_inv:                            Distributions.       (line 362)
* normal_pdf:                            Distributions.       (line 368)
* normal_rnd:                            Distributions.       (line 374)
* nper:                                  Financial Functions. (line  34)
* npv:                                   Financial Functions. (line  48)
* nth:                                   Lists.               (line  10)
* ntsc2rgb:                              Image Processing.    (line 109)
* null:                                  Basic Matrix Functions.
                                                              (line 118)
* num2str:                               Creating Strings.    (line  33)
* nyquist:                               sysfreq.             (line 112)
* obsv:                                  sysprop.             (line  99)
* ocean:                                 Image Processing.    (line 126)
* octave_config_info:                    System Information.  (line  26)
* ols:                                   Linear Least Squares.
                                                              (line  25)
* oneplot:                               Multiple Plots on One Page.
                                                              (line  27)
* ones:                                  Special Utility Matrices.
                                                              (line  38)
* ord2:                                  blockdiag.           (line 122)
* orth:                                  Basic Matrix Functions.
                                                              (line 127)
* parallel:                              blockdiag.           (line 478)
* pascal_cdf:                            Distributions.       (line 383)
* pascal_inv:                            Distributions.       (line 390)
* pascal_pdf:                            Distributions.       (line 397)
* pascal_rnd:                            Distributions.       (line 406)
* pause:                                 Timing Utilities.    (line 332)
* pclose:                                Controlling Subprocesses.
                                                              (line  75)
* periodogram:                           Signal Processing.   (line 365)
* permute:                               Rearranging Matrices.
                                                              (line 128)
* perror:                                Error Handling.      (line  98)
* pinv:                                  Basic Matrix Functions.
                                                              (line 136)
* pipe:                                  Controlling Subprocesses.
                                                              (line 157)
* place:                                 cacsd.               (line 521)
* playaudio:                             Audio Processing.    (line  65)
* plot:                                  Two-Dimensional Plotting.
                                                              (line   9)
* plot_border:                           Multiple Plots on One Page.
                                                              (line  30)
* pmt:                                   Financial Functions. (line  61)
* poisson_cdf:                           Distributions.       (line 415)
* poisson_inv:                           Distributions.       (line 420)
* poisson_pdf:                           Distributions.       (line 424)
* poisson_rnd:                           Distributions.       (line 428)
* polar:                                 Specialized Two-Dimensional Plots.
                                                              (line  57)
* poly:                                  Polynomial Manipulations.
                                                              (line  47)
* polyderiv:                             Polynomial Manipulations.
                                                              (line  53)
* polyfit:                               Polynomial Manipulations.
                                                              (line  57)
* polyinteg:                             Polynomial Manipulations.
                                                              (line  84)
* polyout:                               Polynomial Manipulations.
                                                              (line 161)
* polyreduce:                            Polynomial Manipulations.
                                                              (line  90)
* polyval:                               Polynomial Manipulations.
                                                              (line  94)
* polyvalm:                              Polynomial Manipulations.
                                                              (line 103)
* popen:                                 Controlling Subprocesses.
                                                              (line  51)
* popen2:                                Controlling Subprocesses.
                                                              (line  79)
* postpad:                               Rearranging Matrices.
                                                              (line 309)
* pow2:                                  Utility Functions.   (line 148)
* ppplot:                                Basic Statistical Functions.
                                                              (line 207)
* prepad:                                Rearranging Matrices.
                                                              (line 308)
* printf:                                Formatted Output.    (line  14)
* probit:                                Basic Statistical Functions.
                                                              (line 203)
* prod:                                  Sums and Products.   (line  14)
* prompt:                                misc.                (line  23)
* prop_test_2:                           Tests.               (line 254)
* purge_tmp_files:                       Two-Dimensional Plotting.
                                                              (line 167)
* putenv:                                Environment Variables.
                                                              (line  14)
* puts:                                  Simple Output.       (line  12)
* pv:                                    Financial Functions. (line  72)
* pvl:                                   Financial Functions. (line  86)
* pwd:                                   Current Working Directory.
                                                              (line  31)
* pzmap:                                 sysprop.             (line 112)
* qconj:                                 Quaternions.         (line  25)
* qcoordinate_plot:                      Quaternions.         (line  97)
* qderiv:                                Quaternions.         (line  31)
* qderivmat:                             Quaternions.         (line  46)
* qinv:                                  Quaternions.         (line  61)
* qmult:                                 Quaternions.         (line  67)
* qqplot:                                Basic Statistical Functions.
                                                              (line 183)
* qr:                                    Matrix Factorizations.
                                                              (line  52)
* qtrans:                                Quaternions.         (line  79)
* qtransv:                               Quaternions.         (line  83)
* qtransvmat:                            Quaternions.         (line  92)
* quad:                                  Functions of One Variable.
                                                              (line   7)
* quad_options:                          Functions of One Variable.
                                                              (line  39)
* quaternion:                            Quaternions.         (line  16)
* quit:                                  Quitting Octave.     (line   8)
* qz:                                    Matrix Factorizations.
                                                              (line 106)
* qzhess:                                Matrix Factorizations.
                                                              (line 158)
* qzval:                                 numerical.           (line 187)
* rand:                                  Special Utility Matrices.
                                                              (line  74)
* randn:                                 Special Utility Matrices.
                                                              (line  89)
* randperm:                              Special Utility Matrices.
                                                              (line 138)
* range:                                 Basic Statistical Functions.
                                                              (line 175)
* rank:                                  Basic Matrix Functions.
                                                              (line 146)
* ranks:                                 Basic Statistical Functions.
                                                              (line 166)
* rate:                                  Financial Functions. (line  93)
* read_readline_init_file:               Customizing readline.
                                                              (line   7)
* readdir:                               Filesystem Utilities.
                                                              (line  42)
* readlink:                              Filesystem Utilities.
                                                              (line  29)
* real:                                  Complex Arithmetic.  (line  37)
* record:                                Audio Processing.    (line  70)
* rectangle_lw:                          Signal Processing.   (line 369)
* rectangle_sw:                          Signal Processing.   (line 373)
* rehash:                                Function Files.      (line  89)
* rem:                                   Utility Functions.   (line 152)
* rename:                                Filesystem Utilities.
                                                              (line  11)
* replot:                                Low-Level plotting commands.
                                                              (line 122)
* repmat:                                Special Utility Matrices.
                                                              (line  67)
* reshape:                               Rearranging Matrices.
                                                              (line 142)
* residue:                               Polynomial Manipulations.
                                                              (line 112)
* reverse:                               Lists.               (line  25)
* rgb2ind:                               Image Processing.    (line 130)
* rgb2ntsc:                              Image Processing.    (line 106)
* RGB_MAP:                               Image Processing.    (line 112)
* rindex:                                Searching and Replacing.
                                                              (line  31)
* rldemo:                                misc.                (line  31)
* rlocus:                                misc.                (line  34)
* rmdir:                                 Filesystem Utilities.
                                                              (line  55)
* roots:                                 Polynomial Manipulations.
                                                              (line 155)
* rot90:                                 Rearranging Matrices.
                                                              (line  37)
* rotdim:                                Rearranging Matrices.
                                                              (line  61)
* round:                                 Utility Functions.   (line 160)
* rows:                                  Object Sizes.        (line  16)
* run_count:                             Basic Statistical Functions.
                                                              (line 161)
* run_history:                           Commands For History.
                                                              (line 106)
* run_test:                              Tests.               (line 273)
* save:                                  Simple File I/O.     (line  15)
* saveaudio:                             Audio Processing.    (line  51)
* saveimage:                             Image Processing.    (line 133)
* schur:                                 Matrix Factorizations.
                                                              (line 176)
* sec:                                   Trigonometry.        (line  20)
* sech:                                  Trigonometry.        (line  56)
* semilogx:                              Specialized Two-Dimensional Plots.
                                                              (line  63)
* semilogxerr:                           Specialized Two-Dimensional Plots.
                                                              (line 171)
* semilogy:                              Specialized Two-Dimensional Plots.
                                                              (line  68)
* semilogyerr:                           Specialized Two-Dimensional Plots.
                                                              (line 183)
* set:                                   Low-Level plotting commands.
                                                              (line 126)
* setgrent:                              Group Database Functions.
                                                              (line  39)
* setpwent:                              Password Database Functions.
                                                              (line  49)
* shg <1>:                               Low-Level plotting commands.
                                                              (line 162)
* shg:                                   Two-Dimensional Plotting.
                                                              (line 158)
* shift:                                 Rearranging Matrices.
                                                              (line 204)
* show:                                  Low-Level plotting commands.
                                                              (line 126)
* sign:                                  Utility Functions.   (line 164)
* sign_test:                             Tests.               (line 282)
* sin:                                   Trigonometry.        (line  11)
* sinc:                                  Signal Processing.   (line 183)
* sinetone:                              Signal Processing.   (line 377)
* sinewave:                              Signal Processing.   (line 384)
* sinh:                                  Trigonometry.        (line  47)
* size:                                  Object Sizes.        (line  24)
* skewness:                              Basic Statistical Functions.
                                                              (line  90)
* sleep:                                 Timing Utilities.    (line 344)
* sort:                                  Rearranging Matrices.
                                                              (line 212)
* sortcom:                               misc.                (line  65)
* source:                                Script Files.        (line  91)
* spearman:                              Basic Statistical Functions.
                                                              (line 144)
* spectral_adf:                          Signal Processing.   (line 390)
* spectral_xdf:                          Signal Processing.   (line 400)
* spencer:                               Signal Processing.   (line 410)
* splice:                                Lists.               (line  28)
* split:                                 Searching and Replacing.
                                                              (line  40)
* sprintf:                               Formatted Output.    (line  24)
* sqrt:                                  Utility Functions.   (line 173)
* sqrtm:                                 Functions of a Matrix.
                                                              (line  33)
* ss:                                    ss2sys.              (line   8)
* ss2tf:                                 misc.                (line  92)
* ss2zp:                                 misc.                (line 107)
* sscanf:                                Formatted Input.     (line  50)
* stairs:                                Specialized Two-Dimensional Plots.
                                                              (line  73)
* starp:                                 misc.                (line 113)
* stat:                                  Filesystem Utilities.
                                                              (line  74)
* statistics:                            Basic Statistical Functions.
                                                              (line 137)
* std:                                   Basic Statistical Functions.
                                                              (line  40)
* stdnormal_cdf:                         Distributions.       (line 436)
* stdnormal_inv:                         Distributions.       (line 440)
* stdnormal_pdf:                         Distributions.       (line 444)
* stdnormal_rnd:                         Distributions.       (line 449)
* step:                                  systime.             (line 186)
* str2func:                              Function Handles.    (line  15)
* str2mat:                               Creating Strings.    (line  70)
* str2num:                               String Conversions.  (line  98)
* strcat:                                Creating Strings.    (line  50)
* strcmp:                                Searching and Replacing.
                                                              (line  50)
* strerror:                              Error Handling.      (line 104)
* strftime:                              Timing Utilities.    (line 118)
* strjust:                               String Conversions.  (line  92)
* strptime:                              Timing Utilities.    (line 251)
* strrep:                                Searching and Replacing.
                                                              (line  59)
* studentize:                            Basic Statistical Functions.
                                                              (line 129)
* subplot:                               Multiple Plots on One Page.
                                                              (line  56)
* substr:                                Searching and Replacing.
                                                              (line  66)
* subwindow:                             Multiple Plots on One Page.
                                                              (line  93)
* sum:                                   Sums and Products.   (line   7)
* sumsq:                                 Sums and Products.   (line  37)
* svd:                                   Matrix Factorizations.
                                                              (line 200)
* syl:                                   Functions of a Matrix.
                                                              (line  53)
* sylvester_matrix:                      Famous Matrices.     (line  53)
* symlink:                               Filesystem Utilities.
                                                              (line  23)
* synthesis:                             Signal Processing.   (line 443)
* sys2fir:                               fir2sys.             (line  47)
* sys2ss:                                ss2sys.              (line 140)
* sys2tf:                                tf2sys.              (line  40)
* sys2zp:                                zp2sys.              (line  43)
* sysadd:                                blockdiag.           (line 148)
* sysappend:                             blockdiag.           (line 166)
* syschnames:                            structaccess.        (line   7)
* syschtsam:                             structaccess.        (line  10)
* sysconnect:                            blockdiag.           (line 213)
* syscont:                               blockdiag.           (line 260)
* sysdimensions:                         structaccess.        (line  14)
* sysdisc:                               blockdiag.           (line 278)
* sysdup:                                blockdiag.           (line 293)
* sysgetsignals:                         structaccess.        (line  59)
* sysgettsam:                            structaccess.        (line 307)
* sysgettype:                            structaccess.        (line 175)
* sysgroup:                              blockdiag.           (line 322)
* sysmin:                                blockdiag.           (line 491)
* sysmult:                               blockdiag.           (line 348)
* sysout:                                sysdisp.             (line   7)
* sysprune:                              blockdiag.           (line 358)
* sysreorder:                            blockdiag.           (line 386)
* sysrepdemo:                            sysstruct.           (line  31)
* sysscale:                              blockdiag.           (line 403)
* syssetsignals:                         structaccess.        (line 189)
* syssub:                                blockdiag.           (line 433)
* system:                                Controlling Subprocesses.
                                                              (line  17)
* sysupdate:                             structaccess.        (line 257)
* t_cdf:                                 Distributions.       (line 453)
* t_inv:                                 Distributions.       (line 457)
* t_pdf:                                 Distributions.       (line 461)
* t_rnd:                                 Distributions.       (line 466)
* t_test:                                Tests.               (line 302)
* t_test_2:                              Tests.               (line 320)
* t_test_regression:                     Tests.               (line 339)
* table:                                 Basic Statistical Functions.
                                                              (line 123)
* tan:                                   Trigonometry.        (line  17)
* tanh:                                  Trigonometry.        (line  53)
* tf2ss:                                 misc.                (line 137)
* tf2sys:                                tf2sys.              (line   7)
* tf2zp:                                 misc.                (line 154)
* tfout:                                 sysdisp.             (line  29)
* tic:                                   Timing Utilities.    (line 307)
* tilde_expand:                          Filesystem Utilities.
                                                              (line 189)
* time:                                  Timing Utilities.    (line  49)
* title:                                 Plot Annotations.    (line  12)
* tmpfile:                               Temporary Files.     (line  24)
* tmpnam:                                Temporary Files.     (line  34)
* toascii:                               String Conversions.  (line 101)
* toc:                                   Timing Utilities.    (line 308)
* toeplitz:                              Famous Matrices.     (line  56)
* tolower:                               String Conversions.  (line 108)
* top_title:                             Plot Annotations.    (line  22)
* toupper:                               String Conversions.  (line 116)
* trace:                                 Basic Matrix Functions.
                                                              (line 157)
* triangle_lw:                           Signal Processing.   (line 452)
* triangle_sw:                           Signal Processing.   (line 456)
* tril:                                  Rearranging Matrices.
                                                              (line 268)
* triu:                                  Rearranging Matrices.
                                                              (line 269)
* type:                                  Status of Variables. (line 160)
* typeinfo:                              Data Types.          (line  19)
* tzero:                                 sysfreq.             (line 168)
* tzero2:                                sysfreq.             (line 191)
* u_test:                                Tests.               (line 359)
* ugain:                                 blockdiag.           (line 451)
* umask:                                 Filesystem Utilities.
                                                              (line  67)
* undo_string_escapes:                   String Conversions.  (line 127)
* uniform_cdf:                           Distributions.       (line 475)
* uniform_inv:                           Distributions.       (line 481)
* uniform_pdf:                           Distributions.       (line 487)
* uniform_rnd:                           Distributions.       (line 493)
* union:                                 Sets.                (line  17)
* unlink:                                Filesystem Utilities.
                                                              (line  36)
* unwrap:                                Signal Processing.   (line 186)
* usage:                                 Error Handling.      (line  64)
* usleep:                                Timing Utilities.    (line 348)
* values:                                Basic Statistical Functions.
                                                              (line  99)
* vander:                                Famous Matrices.     (line  73)
* var:                                   Basic Statistical Functions.
                                                              (line 103)
* var_test:                              Tests.               (line 378)
* vec:                                   Rearranging Matrices.
                                                              (line 299)
* vech:                                  Rearranging Matrices.
                                                              (line 303)
* vertcat:                               Rearranging Matrices.
                                                              (line 124)
* vol:                                   Financial Functions. (line 104)
* waitpid:                               Controlling Subprocesses.
                                                              (line 171)
* warning:                               Error Handling.      (line  57)
* weibull_cdf:                           Distributions.       (line 502)
* weibull_inv:                           Distributions.       (line 511)
* weibull_pdf:                           Distributions.       (line 515)
* weibull_rnd:                           Distributions.       (line 525)
* welch_test:                            Tests.               (line 397)
* wgt1o:                                 blockdiag.           (line 457)
* which:                                 Status of Variables. (line 175)
* who:                                   Status of Variables. (line  44)
* whos:                                  Status of Variables. (line  77)
* wiener_rnd:                            Distributions.       (line 533)
* wilcoxon_test:                         Tests.               (line 416)
* xlabel:                                Plot Annotations.    (line  15)
* xor:                                   Finding Elements and Checking Conditions.
                                                              (line  48)
* ylabel:                                Plot Annotations.    (line  16)
* yulewalker:                            Signal Processing.   (line 460)
* z_test:                                Tests.               (line 434)
* z_test_2:                              Tests.               (line 452)
* zeros:                                 Special Utility Matrices.
                                                              (line  56)
* zgfmul:                                numerical.           (line 195)
* zgfslv:                                numerical.           (line 200)
* zginit:                                numerical.           (line 203)
* zgreduce:                              numerical.           (line 208)
* zgrownorm:                             numerical.           (line 212)
* zgscal:                                numerical.           (line 216)
* zgsgiv:                                numerical.           (line 221)
* zgshsr:                                numerical.           (line 225)
* zlabel:                                Plot Annotations.    (line  17)
* zp2ss:                                 misc.                (line 160)
* zp2sys:                                zp2sys.              (line   7)
* zp2tf:                                 misc.                (line 184)
* zpout:                                 sysdisp.             (line  33)


File: octave.info,  Node: Operator Index,  Prev: Function Index,  Up: Top

Operator Index
**************

[index]
* Menu:

* !:                                     Element-by-element Boolean Operators.
                                                               (line 37)
* !=:                                    Comparison Ops.       (line 39)
* " <1>:                                 Strings.              (line  6)
* ":                                     String Objects.       (line  6)
* &:                                     Element-by-element Boolean Operators.
                                                               (line 28)
* &&:                                    Short-circuit Boolean Operators.
                                                               (line 14)
* ' <1>:                                 Arithmetic Ops.       (line 85)
* ' <2>:                                 String Objects.       (line  6)
* ':                                     Strings.              (line  6)
* (:                                     Index Expressions.    (line  6)
* ):                                     Index Expressions.    (line  6)
* *:                                     Arithmetic Ops.       (line 26)
* **:                                    Arithmetic Ops.       (line 62)
* +:                                     Arithmetic Ops.       (line 82)
* ++:                                    Increment Ops.        (line 36)
* ,:                                     Matrices.             (line  6)
* -:                                     Arithmetic Ops.       (line 79)
* --:                                    Increment Ops.        (line 31)
* .':                                    Arithmetic Ops.       (line 92)
* .*:                                    Arithmetic Ops.       (line 30)
* .**:                                   Arithmetic Ops.       (line 75)
* .+:                                    Arithmetic Ops.       (line 15)
* ./:                                    Arithmetic Ops.       (line 44)
* .\:                                    Arithmetic Ops.       (line 57)
* .^:                                    Arithmetic Ops.       (line 75)
* /:                                     Arithmetic Ops.       (line 34)
* ;:                                     Matrices.             (line  6)
* <:                                     Comparison Ops.       (line 22)
* <=:                                    Comparison Ops.       (line 25)
* <>:                                    Comparison Ops.       (line 39)
* =:                                     Assignment Ops.       (line  6)
* ==:                                    Comparison Ops.       (line 28)
* >:                                     Comparison Ops.       (line 34)
* >=:                                    Comparison Ops.       (line 31)
* [:                                     Matrices.             (line  6)
* \:                                     Arithmetic Ops.       (line 47)
* ]:                                     Matrices.             (line  6)
* ^:                                     Arithmetic Ops.       (line 62)
* colon:                                 Ranges.               (line  6)
* |:                                     Element-by-element Boolean Operators.
                                                               (line 32)
* ||:                                    Short-circuit Boolean Operators.
                                                               (line 23)
* ~:                                     Element-by-element Boolean Operators.
                                                               (line 37)
* ~=:                                    Comparison Ops.       (line 39)



Tag Table:
Node: Top793
Node: Preface8002
Node: Acknowledgements10429
Node: How You Can Contribute to Octave17051
Node: Distribution17996
Node: Introduction19155
Node: Running Octave20063
Node: Simple Examples20885
Node: Conventions27866
Node: Fonts28238
Node: Evaluation Notation28791
Node: Printing Notation29784
Node: Error Messages30271
Node: Format of Descriptions30677
Node: A Sample Function Description31281
Node: A Sample Command Description33435
Node: A Sample Variable Description34251
Node: Getting Started35368
Node: Invoking Octave35876
Node: Command Line Options36699
Ref: doc-argv40242
Ref: doc-program_invocation_name40786
Node: Startup Files42053
Node: Quitting Octave44066
Ref: doc-quit44219
Ref: doc-atexit44464
Node: Getting Help44794
Ref: doc-help45424
Ref: doc-INFO_FILE46429
Ref: doc-INFO_PROGRAM46680
Ref: doc-MAKEINFO_PROGRAM47289
Ref: doc-suppress_verbose_help_message47524
Node: Command Line Editing47792
Node: Cursor Motion49371
Ref: doc-clc50752
Node: Killing and Yanking50898
Node: Commands For Text52601
Node: Commands For Completion53991
Ref: doc-completion_append_char54490
Ref: doc-completion_matches54719
Node: Commands For History55070
Ref: doc-history56781
Ref: doc-edit_history57702
Ref: doc-run_history59007
Ref: doc-EDITOR59202
Ref: doc-history_file59460
Ref: doc-history_size59699
Ref: doc-saving_history59921
Node: Customizing readline60120
Ref: doc-read_readline_init_file60316
Node: Customizing the Prompt60522
Ref: doc-PS161758
Ref: doc-PS262289
Ref: doc-PS462635
Node: Diary and Echo Commands62916
Ref: doc-diary63266
Ref: doc-echo63932
Ref: doc-echo_executing_commands64554
Node: Errors65119
Node: Executable Octave Programs67885
Ref: Executable Octave Programs-Footnote-170163
Node: Comments70297
Node: Data Types72093
Ref: doc-typeinfo72842
Node: Built-in Data Types73130
Node: Numeric Objects73779
Node: Missing Data74633
Ref: doc-NA74787
Ref: doc-isna74834
Ref: doc-is_nan_or_na75037
Node: String Objects75262
Node: Data Structure Objects75745
Node: User-defined Data Types76182
Node: Object Sizes76641
Ref: doc-columns77100
Ref: doc-rows77173
Ref: doc-length77240
Ref: doc-size77476
Ref: doc-isempty78206
Node: Numeric Data Types78381
Node: Matrices79832
Ref: doc-warn_separator_insert82299
Ref: doc-output_max_field_width82855
Ref: doc-output_precision83007
Ref: doc-split_long_rows83415
Ref: doc-fixed_point_format84913
Node: Empty Matrices85632
Ref: doc-print_empty_dimensions86631
Ref: doc-warn_empty_list_elements87095
Node: Ranges87547
Node: Logical Values89239
Ref: doc-true89401
Ref: doc-false89455
Node: Predicates for Numeric Objects89511
Ref: doc-isnumeric89690
Ref: doc-isreal89775
Ref: doc-iscomplex89866
Ref: doc-ismatrix89963
Ref: doc-isvector90055
Ref: doc-isscalar90143
Ref: doc-issquare90231
Ref: doc-issymmetric90353
Ref: doc-isbool90589
Node: Strings90667
Node: Creating Strings93513
Ref: doc-blanks93648
Ref: doc-char93714
Ref: doc-int2str94500
Ref: doc-com2str94834
Ref: doc-strcat95164
Ref: doc-string_fill_char95403
Ref: doc-str2mat95805
Ref: doc-ischar96166
Ref: doc-isstr96256
Node: Searching and Replacing96348
Ref: doc-deblank96524
Ref: doc-findstr96699
Ref: doc-index97153
Ref: doc-rindex97441
Ref: doc-split97730
Ref: doc-strcmp98034
Ref: doc-strrep98398
Ref: doc-substr98635
Node: String Conversions99145
Ref: doc-bin2dec99320
Ref: doc-dec2bin99637
Ref: doc-dec2hex100079
Ref: doc-hex2dec100494
Ref: doc-dec2base100853
Ref: doc-base2dec101470
Ref: doc-strjust102063
Ref: doc-str2num102386
Ref: doc-toascii102458
Ref: doc-tolower102630
Ref: doc-toupper102921
Ref: doc-do_string_escapes103214
Ref: doc-undo_string_escapes103332
Ref: doc-warn_num_to_str104102
Ref: doc-warn_str_to_num104543
Ref: doc-warn_single_quote_string104884
Node: Character Class Functions105025
Ref: doc-isalnum105585
Ref: doc-isalpha105724
Ref: doc-isascii105892
Ref: doc-iscntrl106010
Ref: doc-isdigit106084
Ref: doc-isgraph106174
Ref: doc-islower106280
Ref: doc-isprint106374
Ref: doc-ispunct106482
Ref: doc-isspace106560
Ref: doc-isupper106709
Ref: doc-isxdigit106783
Node: Data Structures106878
Ref: doc-struct_levels_to_print108705
Ref: doc-isstruct110222
Ref: doc-fieldnames110329
Ref: doc-isfield110544
Node: Containers110767
Node: Lists110924
Ref: doc-list111017
Ref: doc-nth111134
Ref: doc-append111211
Ref: doc-reverse111653
Ref: doc-splice111759
Ref: doc-islist112163
Node: Cell Arrays112235
Ref: doc-cell112340
Ref: doc-cellstr112799
Ref: doc-iscell112928
Node: I/O Streams113036
Ref: doc-isstream113153
Node: Variables113259
Node: Global Variables115371
Ref: doc-isglobal117005
Node: Persistent Variables117195
Node: Status of Variables118339
Ref: doc-clear118520
Ref: doc-who119966
Ref: doc-whos121191
Ref: doc-whos_line_format121244
Ref: doc-exist122661
Ref: doc-document123753
Ref: doc-type123856
Ref: doc-which124478
Node: Summary of Built-in Variables124635
Node: Defaults from the Environment129705
Node: Expressions130933
Node: Index Expressions131794
Ref: doc-warn_fortran_indexing132381
Ref: doc-warn_resize_on_range_error133597
Node: Calling Functions134667
Node: Call by Value137181
Node: Recursion139193
Ref: doc-max_recursion_depth140134
Ref: Recursion-Footnote-1140417
Ref: Recursion-Footnote-2140815
Node: Arithmetic Ops140976
Ref: doc-warn_divide_by_zero144263
Node: Comparison Ops144504
Node: Boolean Expressions145663
Node: Element-by-element Boolean Operators145914
Node: Short-circuit Boolean Operators148384
Node: Assignment Ops150934
Ref: doc-print_rhs_assign_val155054
Node: Increment Ops155301
Node: Operator Precedence157200
Node: Evaluation159241
Ref: doc-eval159891
Ref: doc-feval160174
Node: Statements162059
Node: The if Statement163575
Ref: doc-warn_assign_as_truth_value167083
Node: The switch Statement168380
Ref: doc-warn_variable_switch_label170611
Node: The while Statement170801
Node: The do-until Statement173077
Node: The for Statement174559
Node: Looping Over Structure Elements176797
Node: The break Statement178071
Node: The continue Statement179584
Node: The unwind_protect Statement180872
Node: The try Statement182319
Node: Continuation Lines183659
Node: Functions and Scripts185339
Node: Defining Functions186029
Ref: doc-nargin191262
Ref: doc-silent_functions191704
Ref: doc-warn_missing_semicolon192235
Node: Multiple Return Values192446
Ref: doc-nargout194875
Ref: doc-warn_undefined_return_values195470
Ref: doc-nargchk195722
Node: Variable-length Argument Lists196087
Node: Variable-length Return Lists196316
Node: Returning From a Function196544
Node: Function Files198128
Ref: doc-DEFAULT_LOADPATH200937
Ref: doc-LOADPATH201222
Ref: doc-rehash202623
Ref: doc-file_in_loadpath202713
Ref: doc-ignore_function_time_stamp203370
Ref: doc-warn_function_name_clash204222
Ref: doc-warn_future_time_stamp204620
Ref: Function Files-Footnote-1204857
Node: Script Files204923
Ref: doc-source208669
Node: Dynamically Linked Functions208878
Ref: doc-warn_reload_forces_clear214544
Ref: doc-variables_can_hide_functions214897
Node: Function Handles and Inline216251
Node: Function Handles216612
Ref: doc-functions216766
Ref: doc-func2str216901
Ref: doc-str2func217056
Node: Inline Functions217169
Ref: doc-inline217323
Ref: doc-argnames218173
Ref: doc-formula218330
Ref: doc-vectorize218500
Node: Organization of Functions218675
Node: Error Handling220394
Ref: doc-error220792
Ref: doc-beep_on_error222563
Ref: doc-warning222764
Ref: doc-usage223114
Ref: doc-lasterr223966
Ref: doc-lastwarn224159
Ref: doc-perror224472
Ref: doc-strerror224735
Node: Debugging225012
Ref: doc-dbstop225136
Ref: doc-dbclear225536
Ref: doc-dbstatus226014
Ref: doc-dbwhere226273
Ref: doc-dbtype226344
Ref: doc-debug_on_interrupt226420
Ref: doc-debug_on_warning226768
Ref: doc-debug_on_error226965
Node: Input and Output227276
Ref: doc-more228742
Ref: doc-PAGER228904
Ref: doc-page_screen_output229278
Ref: doc-page_output_immediately229665
Ref: doc-fflush229987
Node: Basic Input and Output230432
Node: Terminal Output230663
Ref: doc-ans231399
Ref: doc-fdisp231646
Ref: doc-disp231948
Ref: doc-format232319
Ref: doc-print_answer_id_name237494
Node: Terminal Input237728
Ref: doc-input238139
Ref: doc-menu239264
Ref: doc-keyboard239705
Ref: doc-kbhit240616
Node: Simple File I/O241039
Ref: doc-save241530
Ref: doc-crash_dumps_octave_core244726
Ref: doc-sighup_dumps_octave_core244999
Ref: doc-sigterm_dumps_octave_core245285
Ref: doc-default_save_format245575
Ref: doc-save_precision245866
Ref: doc-save_header_format_string246027
Ref: doc-load246598
Node: C-Style I/O Functions249922
Ref: doc-stdin250735
Ref: doc-stdout250916
Ref: doc-stderr251074
Node: Opening and Closing Files251804
Ref: doc-fopen251976
Ref: doc-fclose254969
Node: Simple Output255106
Ref: doc-fputs255282
Ref: doc-puts255441
Node: Line-Oriented Input255607
Ref: doc-fgetl255786
Ref: doc-fgets256169
Node: Formatted Output256552
Ref: doc-printf257067
Ref: doc-fprintf257271
Ref: doc-sprintf257445
Node: Output Conversion for Matrices259883
Node: Output Conversion Syntax260973
Node: Table of Output Conversions263941
Node: Integer Conversions266125
Node: Floating-Point Conversions268181
Node: Other Output Conversions271017
Node: Formatted Input272126
Ref: doc-fscanf272539
Ref: doc-sscanf273973
Node: Input Conversion Syntax275564
Node: Table of Input Conversions278054
Node: Numeric Input Conversions279893
Node: String Input Conversions280933
Node: Binary I/O281964
Ref: doc-fread282425
Ref: doc-fwrite286761
Node: Temporary Files287366
Ref: doc-mkstemp287530
Ref: doc-tmpfile288469
Ref: doc-tmpnam288905
Node: EOF and Errors289430
Ref: doc-feof289614
Ref: doc-ferror289920
Ref: doc-freport290200
Node: File Positioning290601
Ref: doc-ftell290859
Ref: doc-fseek291010
Ref: doc-SEEK_SET291567
Ref: doc-frewind291980
Node: Plotting292525
Node: Two-Dimensional Plotting293636
Ref: doc-plot293865
Ref: doc-hold298012
Ref: doc-ishold298535
Ref: doc-clearplot298708
Ref: doc-shg299151
Ref: doc-closeplot299260
Ref: doc-purge_tmp_files299403
Ref: doc-axis299883
Node: Specialized Two-Dimensional Plots302242
Ref: doc-bar302467
Ref: doc-contour302926
Ref: doc-hist303175
Ref: doc-loglog303948
Ref: doc-polar304151
Ref: doc-semilogx304336
Ref: doc-semilogy304545
Ref: doc-stairs304754
Ref: doc-errorbar305227
Ref: doc-loglogerr307291
Ref: doc-semilogxerr307755
Ref: doc-semilogyerr308220
Node: Three-Dimensional Plotting308685
Ref: doc-mesh308947
Ref: doc-meshgrid309301
Ref: doc-meshdom309588
Node: Plot Annotations309874
Ref: doc-grid310050
Ref: doc-title310253
Ref: doc-xlabel310322
Ref: doc-top_title310593
Node: Multiple Plots on One Page310744
Ref: doc-mplot311032
Ref: doc-multiplot311486
Ref: doc-oneplot311758
Ref: doc-plot_border311847
Ref: doc-subplot312365
Ref: doc-subwindow313609
Node: Multiple Plot Windows313878
Ref: doc-figure314070
Node: Low-Level plotting commands314330
Node: Interaction with gnuplot321522
Ref: doc-gnuplot_binary321692
Ref: doc-gnuplot_has_frames321852
Ref: doc-gnuplot_command_plot322277
Ref: doc-gnuplot_command_replot322322
Ref: doc-gnuplot_command_splot322369
Ref: doc-gnuplot_command_using322415
Ref: doc-gnuplot_command_with322461
Ref: doc-gnuplot_command_axes322506
Ref: doc-gnuplot_command_title322551
Ref: doc-gnuplot_command_end322597
Node: Matrix Manipulation322641
Node: Finding Elements and Checking Conditions323311
Ref: doc-any323764
Ref: doc-all324300
Ref: doc-xor325021
Ref: doc-is_duplicate_entry325244
Ref: doc-diff325360
Ref: doc-isinf326251
Ref: doc-isnan326444
Ref: doc-finite326639
Ref: doc-find326839
Ref: doc-common_size327654
Node: Rearranging Matrices328287
Ref: doc-fliplr328498
Ref: doc-flipud328790
Ref: doc-flipdim329149
Ref: doc-rot90329337
Ref: doc-rotdim330170
Ref: doc-cat331145
Ref: doc-horzcat331934
Ref: doc-vertcat332112
Ref: doc-permute332288
Ref: doc-ipermute332531
Ref: doc-reshape332718
Ref: doc-circshift333337
Ref: doc-shiftdim334078
Ref: doc-shift334914
Ref: doc-sort335205
Ref: doc-tril337212
Ref: doc-vec338204
Ref: doc-vech338331
Ref: doc-prepad338520
Ref: Rearranging Matrices-Footnote-1339112
Node: Special Utility Matrices339285
Ref: doc-eye339479
Ref: doc-ones340504
Ref: doc-zeros341085
Ref: doc-repmat341523
Ref: doc-rand341739
Ref: doc-randn342253
Ref: doc-randperm343803
Ref: doc-diag343928
Ref: doc-linspace344594
Ref: doc-logspace345053
Ref: doc-warn_neg_dim_as_zero345380
Ref: doc-warn_imag_to_real345573
Node: Famous Matrices345785
Ref: doc-hankel345985
Ref: doc-hilb346513
Ref: doc-invhilb346681
Ref: doc-sylvester_matrix347683
Ref: doc-toeplitz347776
Ref: doc-vander348449
Node: Arithmetic348836
Node: Utility Functions349271
Ref: doc-ceil349650
Ref: doc-exp349804
Ref: doc-fix349940
Ref: doc-floor350070
Ref: doc-gcd350229
Ref: doc-lcm351107
Ref: doc-log351403
Ref: doc-log10351560
Ref: doc-log2351652
Ref: doc-max351851
Ref: doc-min352764
Ref: doc-mod353678
Ref: doc-nextpow2354065
Ref: doc-pow2354238
Ref: doc-rem354420
Ref: doc-round354686
Ref: doc-sign354831
Ref: doc-sqrt355077
Node: Complex Arithmetic355268
Ref: doc-abs355708
Ref: doc-arg355873
Ref: doc-conj356090
Ref: doc-imag356195
Ref: doc-real356282
Node: Trigonometry356347
Ref: doc-sin356702
Ref: doc-cos356778
Ref: doc-tan356856
Ref: doc-sec356931
Ref: doc-csc357009
Ref: doc-cot357089
Ref: doc-asin357170
Ref: doc-acos357255
Ref: doc-atan357342
Ref: doc-asec357430
Ref: doc-acsc357517
Ref: doc-acot357606
Ref: doc-sinh357696
Ref: doc-cosh357792
Ref: doc-tanh357882
Ref: doc-sech357969
Ref: doc-csch358059
Ref: doc-coth358151
Ref: doc-asinh358244
Ref: doc-acosh358341
Ref: doc-atanh358440
Ref: doc-asech358540
Ref: doc-acsch358639
Ref: doc-acoth358740
Ref: doc-atan2359064
Node: Sums and Products359206
Ref: doc-sum359364
Ref: doc-prod359604
Ref: doc-cumsum359858
Ref: doc-cumprod360183
Ref: doc-sumsq360521
Node: Special Functions360958
Ref: doc-besselj361130
Ref: doc-airy362897
Ref: doc-beta364039
Ref: doc-betainc364170
Ref: doc-bincoeff364659
Ref: doc-erf364982
Ref: doc-erfc365241
Ref: doc-erfinv365337
Ref: doc-gamma365421
Ref: doc-gammainc365637
Ref: doc-lgamma366176
Ref: doc-cross366309
Ref: doc-commutation_matrix366728
Ref: doc-duplication_matrix367115
Node: Coordinate Transformations367447
Ref: doc-cart2pol367642
Ref: doc-pol2cart367955
Ref: doc-cart2sph368272
Ref: doc-sph2cart368573
Node: Mathematical Constants368870
Ref: doc-I369031
Ref: doc-Inf369462
Ref: doc-NaN369642
Ref: doc-pi370012
Ref: doc-e370161
Ref: doc-eps370286
Ref: doc-realmax370634
Ref: doc-realmin370886
Node: Linear Algebra371151
Node: Basic Matrix Functions371620
Ref: doc-balance371780
Ref: doc-cond373351
Ref: doc-det373555
Ref: doc-dmult373723
Ref: doc-dot373866
Ref: doc-eig374143
Ref: doc-givens374561
Ref: doc-inv374884
Ref: doc-norm375196
Ref: doc-null375854
Ref: doc-orth376162
Ref: doc-pinv376468
Ref: doc-rank376771
Ref: doc-trace377199
Node: Matrix Factorizations377277
Ref: doc-chol377465
Ref: doc-hess377615
Ref: doc-lu378194
Ref: doc-qr378749
Ref: doc-qz380051
Ref: doc-qzhess382053
Ref: doc-schur382771
Ref: doc-svd384218
Ref: doc-housh385273
Ref: doc-krylov385715
Node: Functions of a Matrix386680
Ref: doc-expm386837
Ref: doc-logm387725
Ref: doc-sqrtm387944
Ref: doc-kron388249
Ref: doc-syl388536
Node: Nonlinear Equations388817
Ref: doc-fsolve389119
Ref: doc-fsolve_options389733
Node: Quadrature391129
Node: Functions of One Variable391334
Ref: doc-quad391500
Ref: doc-quad_options392841
Node: Orthogonal Collocation394550
Ref: doc-colloc394710
Node: Differential Equations395722
Node: Ordinary Differential Equations396090
Ref: doc-lsode396429
Ref: doc-lsode_options398959
Node: Differential-Algebraic Equations402025
Ref: doc-daspk402393
Ref: doc-daspk_options404827
Ref: doc-dasrt411333
Ref: doc-dasrt_options415342
Node: Optimization417291
Node: Linear Programming417536
Node: Quadratic Programming417682
Node: Nonlinear Programming417864
Node: Linear Least Squares418048
Ref: doc-gls418200
Ref: doc-ols418802
Node: Statistics419582
Node: Basic Statistical Functions419948
Ref: doc-mean420103
Ref: doc-median420805
Ref: doc-std421141
Ref: doc-cov421933
Ref: doc-corrcoef422222
Ref: doc-kurtosis422527
Ref: doc-mahalanobis422888
Ref: doc-skewness423140
Ref: doc-values423487
Ref: doc-var423606
Ref: doc-table424230
Ref: doc-studentize424487
Ref: doc-statistics424773
Ref: doc-spearman425059
Ref: doc-run_count425685
Ref: doc-ranks425929
Ref: doc-range426214
Ref: doc-qqplot426536
Ref: doc-probit427351
Ref: doc-ppplot427493
Ref: doc-moment428240
Ref: doc-meansq428783
Ref: doc-logit429108
Ref: doc-kendall429210
Ref: doc-iqr430101
Ref: doc-cut430433
Ref: doc-cor430980
Ref: doc-cloglog431334
Ref: doc-center431460
Node: Tests431718
Ref: doc-anova431844
Ref: doc-bartlett_test432848
Ref: doc-chisquare_test_homogeneity433336
Ref: doc-chisquare_test_independence433955
Ref: doc-cor_test434411
Ref: doc-f_test_regression435815
Ref: doc-hotelling_test436329
Ref: doc-hotelling_test_2436897
Ref: doc-kolmogorov_smirnov_test437581
Ref: doc-kolmogorov_smirnov_test_2438832
Ref: doc-kruskal_wallis_test440004
Ref: doc-manova440618
Ref: doc-mcnemar_test441264
Ref: doc-prop_test_2441816
Ref: doc-run_test442684
Ref: doc-sign_test443019
Ref: doc-t_test443977
Ref: doc-t_test_2444829
Ref: doc-t_test_regression445715
Ref: doc-u_test446572
Ref: doc-var_test447466
Ref: doc-welch_test448354
Ref: doc-wilcoxon_test449254
Ref: doc-z_test450093
Ref: doc-z_test_2450944
Node: Models451828
Ref: doc-logistic_regression451942
Node: Distributions453624
Ref: doc-beta_cdf453738
Ref: doc-beta_inv453918
Ref: doc-beta_pdf454094
Ref: doc-beta_rnd454238
Ref: doc-binomial_cdf454590
Ref: doc-binomial_inv454742
Ref: doc-binomial_pdf454899
Ref: doc-binomial_rnd455082
Ref: doc-cauchy_cdf455448
Ref: doc-cauchy_inv455726
Ref: doc-cauchy_pdf455999
Ref: doc-cauchy_rnd456277
Ref: doc-chisquare_cdf456668
Ref: doc-chisquare_inv456861
Ref: doc-chisquare_pdf457044
Ref: doc-chisquare_rnd457228
Ref: doc-discrete_cdf457571
Ref: doc-discrete_inv457799
Ref: doc-discrete_pdf458017
Ref: doc-discrete_rnd458241
Ref: doc-empirical_cdf458679
Ref: doc-empirical_inv458890
Ref: doc-empirical_pdf459096
Ref: doc-empirical_rnd459303
Ref: doc-exponential_cdf459687
Ref: doc-exponential_inv459938
Ref: doc-exponential_pdf460126
Ref: doc-exponential_rnd460310
Ref: doc-f_cdf460705
Ref: doc-f_inv460879
Ref: doc-f_pdf461049
Ref: doc-f_rnd461226
Ref: doc-gamma_cdf461632
Ref: doc-gamma_inv461818
Ref: doc-gamma_pdf461996
Ref: doc-gamma_rnd462172
Ref: doc-geometric_cdf462528
Ref: doc-geometric_inv462672
Ref: doc-geometric_pdf462821
Ref: doc-geometric_rnd462996
Ref: doc-hypergeometric_cdf463357
Ref: doc-hypergeometric_inv463838
Ref: doc-hypergeometric_pdf464108
Ref: doc-hypergeometric_rnd464530
Ref: doc-kolmogorov_smirnov_cdf465056
Ref: doc-laplace_cdf465424
Ref: doc-laplace_inv465579
Ref: doc-laplace_pdf465729
Ref: doc-laplace_rnd465880
Ref: doc-logistic_cdf466086
Ref: doc-logistic_inv466210
Ref: doc-logistic_pdf466364
Ref: doc-logistic_rnd466488
Ref: doc-lognormal_cdf466696
Ref: doc-lognormal_inv467062
Ref: doc-lognormal_pdf467417
Ref: doc-lognormal_rnd467773
Ref: doc-normal_cdf468179
Ref: doc-normal_inv468409
Ref: doc-normal_pdf468629
Ref: doc-normal_rnd468850
Ref: doc-pascal_cdf469208
Ref: doc-pascal_inv469514
Ref: doc-pascal_pdf469825
Ref: doc-pascal_rnd470167
Ref: doc-poisson_cdf470584
Ref: doc-poisson_inv470774
Ref: doc-poisson_pdf470956
Ref: doc-poisson_rnd471137
Ref: doc-stdnormal_cdf471425
Ref: doc-stdnormal_inv471557
Ref: doc-stdnormal_pdf471727
Ref: doc-stdnormal_rnd471888
Ref: doc-t_cdf472075
Ref: doc-t_inv472246
Ref: doc-t_pdf472416
Ref: doc-t_rnd472599
Ref: doc-uniform_cdf472959
Ref: doc-uniform_inv473144
Ref: doc-uniform_pdf473349
Ref: doc-uniform_rnd473524
Ref: doc-weibull_cdf473872
Ref: doc-weibull_inv474140
Ref: doc-weibull_pdf474335
Ref: doc-weibull_rnd474644
Ref: doc-wiener_rnd475061
Node: Financial Functions475518
Ref: doc-fv475656
Ref: doc-fvl476207
Ref: doc-irr476461
Ref: doc-nper476696
Ref: doc-npv477239
Ref: doc-pmt477742
Ref: doc-pv478161
Ref: doc-pvl478703
Ref: doc-rate478966
Ref: doc-vol479416
Node: Sets479874
Ref: doc-create_set480118
Ref: doc-union480333
Ref: doc-intersection480532
Ref: doc-complement480728
Node: Polynomial Manipulations480902
Ref: doc-compan481239
Ref: doc-conv482083
Ref: doc-deconv482351
Ref: doc-poly482678
Ref: doc-polyderiv482984
Ref: doc-polyfit483131
Ref: doc-polyinteg483895
Ref: doc-polyreduce484100
Ref: doc-polyval484251
Ref: doc-polyvalm484498
Ref: doc-residue484816
Ref: doc-roots486599
Ref: doc-polyout486761
Node: Control Theory487002
Ref: doc-DEMOcontrol487830
Node: sysstruct488675
Ref: doc-sysrepdemo489829
Node: sysstructvars489927
Node: sysstructtf491900
Node: sysstructzp492149
Node: sysstructss492414
Node: sysinterface492923
Node: fir2sys493577
Ref: doc-fir2sys493765
Ref: doc-sys2fir494809
Node: ss2sys494967
Ref: doc-ss2sys495146
Ref: doc-sys2ss499015
Node: tf2sys500115
Ref: doc-tf2sys500305
Ref: doc-sys2tf501125
Node: zp2sys501495
Ref: doc-zp2sys501675
Ref: doc-sys2zp502445
Node: structaccess502866
Ref: doc-syschnames503042
Ref: doc-syschtsam503134
Ref: doc-sysdimensions503303
Ref: doc-sysgetsignals504331
Ref: doc-sysgettype507539
Ref: doc-syssetsignals507880
Ref: doc-sysupdate509653
Ref: doc-minfo510315
Ref: doc-sysgettsam510861
Node: structintern510948
Node: sysdisp511113
Ref: doc-sysout511271
Ref: doc-tfout511701
Ref: doc-zpout511845
Node: blockdiag511977
Ref: doc-bddemo512242
Ref: doc-buildssic512348
Ref: doc-jet707516143
Ref: doc-ord2516532
Ref: doc-sysadd517369
Ref: doc-sysappend517962
Ref: doc-sysconnect519413
Ref: doc-syscont520942
Ref: doc-sysdisc521421
Ref: doc-sysdup521810
Ref: doc-sysgroup522768
Ref: doc-sysmult523614
Ref: doc-sysprune524084
Ref: doc-sysreorder524931
Ref: doc-sysscale525299
Ref: doc-syssub526305
Ref: doc-ugain526876
Ref: doc-wgt1o527183
Ref: doc-parallel527728
Ref: doc-sysmin528230
Node: numerical529004
Ref: doc-are529149
Ref: doc-dare529906
Ref: doc-dre530899
Ref: doc-dgram531991
Ref: doc-dlyap532313
Ref: doc-gram533266
Ref: doc-lyap533432
Ref: doc-qzval534127
Ref: doc-zgfmul534327
Ref: doc-zgfslv534533
Ref: doc-zginit534629
Ref: doc-zgreduce534824
Ref: doc-zgrownorm534965
Ref: doc-zgscal535162
Ref: doc-zgsgiv535368
Ref: doc-zgshsr535555
Node: sysprop535883
Ref: doc-analdemo536040
Ref: doc-abcddim536134
Ref: doc-ctrb536734
Ref: doc-h2norm537104
Ref: doc-hinfnorm537384
Ref: doc-obsv538815
Ref: doc-pzmap539203
Ref: doc-is_abcd539603
Ref: doc-is_controllable539860
Ref: doc-is_detectable540847
Ref: doc-is_dgkf541327
Ref: doc-is_digital543593
Ref: doc-is_observable544326
Ref: doc-is_sample544713
Ref: doc-is_siso544818
Ref: doc-is_stabilizable544944
Ref: doc-is_signal_list545495
Ref: doc-is_stable545600
Node: systime546087
Ref: doc-c2d546244
Ref: doc-d2c547780
Ref: doc-dmr2d549107
Ref: doc-damp551106
Ref: doc-dcgain551442
Ref: doc-impulse551687
Ref: doc-step552465
Node: sysfreq553294
Ref: doc-frdemo553491
Ref: doc-bode553582
Ref: doc-bode_bounds555902
Ref: doc-freqchkw556187
Ref: doc-ltifr556327
Ref: doc-nyquist556819
Ref: doc-tzero559232
Ref: doc-tzero2559914
Node: cacsd560174
Ref: doc-dgkfdemo560306
Ref: doc-hinfdemo560404
Ref: doc-dlqe564573
Ref: doc-dlqr565434
Ref: doc-dkalman565979
Ref: doc-h2syn566922
Ref: doc-hinf_ctr567994
Ref: doc-hinfsyn568427
Ref: doc-hinfsyn_chk570250
Ref: doc-hinfsyn_ric571076
Ref: doc-lqe571682
Ref: doc-lqg572476
Ref: doc-lqr573784
Ref: doc-lsim574711
Ref: doc-place575400
Node: misc575743
Ref: doc-axis2dlim575945
Ref: doc-moddemo576330
Ref: doc-prompt576428
Ref: doc-rldemo576611
Ref: doc-rlocus576699
Ref: doc-sortcom577506
Ref: doc-ss2tf578049
Ref: doc-ss2zp578471
Ref: doc-starp578711
Ref: doc-tf2ss579676
Ref: doc-tf2zp580338
Ref: doc-zp2ss580583
Ref: doc-zp2tf581207
Node: Signal Processing581533
Ref: doc-detrend581845
Ref: doc-fft582213
Ref: doc-ifft583022
Ref: doc-fft2583885
Ref: doc-ifft2584301
Ref: doc-fftn584725
Ref: doc-ifftn585200
Ref: doc-fftconv585692
Ref: doc-fftfilt586139
Ref: doc-filter586451
Ref: doc-freqz588025
Ref: doc-freqz_plot589268
Ref: doc-sinc589366
Ref: doc-unwrap589427
Ref: doc-arch_fit589787
Ref: doc-arch_rnd590679
Ref: doc-arch_test591058
Ref: doc-arma_rnd592025
Ref: doc-autocor592605
Ref: doc-autocov592835
Ref: doc-autoreg_matrix593062
Ref: doc-bartlett593417
Ref: doc-blackman593668
Ref: doc-diffpara593902
Ref: doc-durbinlevinson594638
Ref: doc-fftshift595041
Ref: doc-fractdiff595708
Ref: doc-hamming595860
Ref: doc-hanning596090
Ref: doc-hurst596318
Ref: doc-periodogram596510
Ref: doc-rectangle_lw596626
Ref: doc-rectangle_sw596751
Ref: doc-sinetone596882
Ref: doc-sinewave597176
Ref: doc-spectral_adf597379
Ref: doc-spectral_xdf597769
Ref: doc-spencer598145
Ref: doc-stft598258
Ref: doc-synthesis599245
Ref: doc-triangle_lw599510
Ref: doc-triangle_sw599633
Ref: doc-yulewalker599762
Node: Image Processing600000
Ref: doc-colormap600765
Ref: doc-gray601355
Ref: doc-gray2ind601547
Ref: doc-image601662
Ref: doc-imagesc602217
Ref: doc-imshow603064
Ref: doc-ind2gray603874
Ref: doc-ind2rgb604071
Ref: doc-loadimage604265
Ref: doc-rgb2ntsc604449
Ref: doc-ntsc2rgb604515
Ref: doc-hsv2rgb604581
Ref: doc-rgb2hsv604693
Ref: doc-ocean605143
Ref: doc-rgb2ind605277
Ref: doc-saveimage605381
Ref: doc-IMAGEPATH606277
Node: Audio Processing606395
Ref: doc-lin2mu607663
Ref: doc-mu2lin607994
Ref: doc-loadaudio608278
Ref: doc-saveaudio608733
Ref: doc-playaudio609470
Ref: doc-record609631
Ref: doc-setaudio609913
Node: Quaternions610021
Ref: doc-quaternion610494
Ref: doc-qconj610782
Ref: doc-qderiv610936
Ref: doc-qderivmat611401
Ref: doc-qinv611870
Ref: doc-qmult612037
Ref: doc-qtrans612320
Ref: doc-qtransv612445
Ref: doc-qtransvmat612727
Ref: doc-qcoordinate_plot612935
Node: System Utilities613322
Node: Timing Utilities614044
Ref: doc-time615014
Ref: doc-ctime615317
Ref: doc-gmtime615669
Ref: doc-localtime616241
Ref: doc-mktime616821
Ref: doc-asctime617055
Ref: doc-strftime617351
Ref: doc-strptime620110
Ref: doc-clock620474
Ref: doc-date620801
Ref: doc-etime620959
Ref: doc-cputime621318
Ref: doc-is_leap_year622005
Ref: doc-tic622252
Ref: doc-pause623134
Ref: doc-sleep623585
Ref: doc-usleep623706
Node: Filesystem Utilities624012
Ref: doc-rename624370
Ref: doc-link624607
Ref: doc-symlink624873
Ref: doc-readlink625133
Ref: doc-unlink625452
Ref: doc-readdir625677
Ref: doc-mkdir626019
Ref: doc-rmdir626244
Ref: doc-mkfifo626471
Ref: doc-umask626732
Ref: doc-stat627053
Ref: doc-glob629299
Ref: doc-fnmatch629662
Ref: doc-file_in_path629977
Ref: doc-tilde_expand630855
Node: Controlling Subprocesses631548
Ref: doc-system632209
Ref: doc-popen633611
Ref: doc-pclose634499
Ref: doc-popen2634648
Ref: doc-EXEC_PATH635452
Ref: doc-fork636574
Ref: doc-exec637259
Ref: doc-pipe637762
Ref: doc-dup2638079
Ref: doc-waitpid638331
Ref: doc-fcntl639365
Node: Process ID Information640701
Ref: doc-getpgrp640908
Ref: doc-getpid641007
Ref: doc-getppid641098
Ref: doc-geteuid641189
Ref: doc-getuid641289
Ref: doc-getegid641382
Ref: doc-getgid641483
Node: Environment Variables641577
Ref: doc-getenv641771
Ref: doc-putenv641963
Node: Current Working Directory642069
Ref: doc-cd642276
Ref: doc-ls642672
Ref: doc-pwd643092
Node: Password Database Functions643167
Ref: doc-getpwent643827
Ref: doc-getpwuid644048
Ref: doc-getpwnam644281
Ref: doc-setpwent644520
Ref: doc-endpwent644638
Node: Group Database Functions644709
Ref: doc-getgrent645263
Ref: doc-getgrgid645453
Ref: doc-getgrnam645662
Ref: doc-setgrent645877
Ref: doc-endgrent645987
Node: System Information646055
Ref: doc-computer646208
Ref: doc-isieee646582
Ref: doc-OCTAVE_VERSION646725
Ref: doc-octave_config_info646812
Ref: doc-getrusage647058
Node: Tips648525
Node: Style Tips649165
Node: Coding Tips650902
Node: Documentation Tips652433
Node: Comment Tips655609
Node: Function Headers656763
Node: Trouble661372
Node: Actual Bugs662086
Node: Reporting Bugs664853
Node: Bug Criteria666218
Node: Bug Lists667443
Node: Bug Reporting668457
Node: Sending Patches673920
Node: Service676744
Node: Installation677463
Node: Installation Problems685629
Node: Emacs692825
Node: Installing EOS694037
Node: Using Octave Mode694757
Node: Running Octave From Within Emacs705733
Node: Using the Emacs Info Reader for Octave709983
Node: Grammar711515
Node: Keywords711744
Node: Copying713033
Node: Concept Index732234
Node: Variable Index762714
Node: Function Index783772
Node: Operator Index859669

End Tag Table
