Geek Gadgets 1/ADE-1.bin/ade-bin/info/octave.info-1

GNU Info File | 1996-10-12 | 49.3 KB | 1,341 lines

This is Info file octave.info, produced by Makeinfo-1.64 from the input
file octave.texi.

   Copyright (C) 1993, 1994, 1995 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,  Prev: (dir),  Up: (dir)



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

* Menu:

* Preface::
* Copying::
* Introduction::                A brief introduction to Octave.
* Invoking Octave::             Command options supported by Octave.
* Expressions::                 Expressions.
* Statements::                  Looping and program flow control.
* Functions and Scripts::
* Built-in Variables::          Descriptions of all built-in variables.
* Arithmetic::
* Linear Algebra::
* Polynomial Manipulations::
* Nonlinear Equations::
* Differential Equations::
* Optimization::
* Quadrature::
* Control Theory::
* Signal Processing::
* Sets::
* Statistics::
* Plotting::
* Image Processing::
* Input and Output::
* Special Matrices::
* Matrix Manipulation::
* String Functions::
* System Utilities::
* Command History Functions::
* Help::
* Programming Utilities::
* Amusements::
* Installation::                How to configure, compile and install Octave.
* Trouble::                     If you have trouble installing Octave.
* Command Line Editing::        Command history and editing.
* Using Info::
* 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.
* Readline Index::              An index for readline commands.
* Info Index::                  An index for info commands.

 -- The Detailed Node Listing --

A Brief Introduction to Octave

* Running Octave::
* Simple Examples::
* Executable Octave Programs::
* Comments::
* Errors::

Invoking Octave

* Command Line Options::
* Startup Files::

Expressions

* Constant Expressions::
* Matrices::
* Ranges::
* Variables::
* Index Expressions::
* Data Structures::
* Calling Functions::
* Global Variables::
* Keywords::
* Arithmetic Ops::
* Comparison Ops::
* Boolean Expressions::
* Assignment Ops::
* Increment Ops::
* Operator Precedence::

Constant Expressions

* Numeric Constants::
* String Constants::

Matrices

* Empty Matrices::

Calling Functions

* Call by Value::
* Recursion::

Boolean Expressions

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

Statements

* The if Statement::
* The while Statement::
* The for Statement::
* The break Statement::
* The continue Statement::
* The unwind_protect Statement::

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

Built-in Variables

* Predefined Constants::
* User Preferences::
* Other Built-in Variables::
* Summary of Preference Variables::

Arithmetic

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

Linear Algebra

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

Differential Equations

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

Optimization

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

Quadrature

* Functions of one Variable::
* Orthogonal Collocation::

Plotting

* Two-Dimensional Plotting::
* Three-Dimensional Plotting::
* Miscellaneous Plotting Functions::

Input and Output

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

C-Style I/O Functions

* Opening and Closing Files::
* Formatted Output::
* Output Conversion Syntax::
* Table of Output Conversions::
* Integer Conversions::
* Floating-Point Conversions::
* Other Output Conversions::
* Formatted Input::
* Input Conversion Syntax::
* Table of Input Conversions::
* Numeric Input Conversions::
* String Input Conversions::
* Binary I/O::
* Other I/O Functions::

Special Matrices

* Special Utility Matrices::
* Famous Matrices::

Matrix Manipulation

* Finding Elements and Checking Conditions::
* Rearranging Matrices::

System Utilities

* Timing Utilities::
* Interacting with the OS::
* System Information::
* Other Functions::

Programming Utilities

* Evaluating Strings as Commands::
* Miscellaneous Utilities::

Installing Octave

* Installation Problems::
* Binary Distributions::

Binary Distributions

* Installing Octave from a Binary Distribution::
* Creating a Binary Distribution::

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.

Command Line Editing

* Introduction and Notation::   Notation used in this text.
* Readline Interaction::        The minimum set of commands for editing a line.
* Readline Bare Essentials::
* Readline Movement Commands::
* Readline Killing Commands::
* Readline Arguments::
* Readline Init File::          Customizing Readline from a user's view.
* Readline Init Syntax::
* Readline Vi Mode::

Readline Interaction

* Readline Bare Essentials::    The least you need to know about Readline.
* Readline Movement Commands::  Moving about the input line.
* Readline Killing Commands::   How to delete text, and how to get it back!
* Readline Arguments::          Giving numeric arguments to commands.

Readline Init File

* Readline Init Syntax::        Syntax for the commands in `~/.inputrc'.
* Readline Vi Mode::            Switching to `vi' mode in Readline.

Readline Init Syntax

* Commands For Moving::         Moving about the line.
* Commands For History::        Getting at previous lines.
* Commands For Text::           Commands for changing text.
* Commands For Killing::        Commands for killing and yanking.
* Numeric Arguments::           Specifying numeric arguments, repeat counts.
* Commands For Completion::     Getting Readline to do the typing for you.
* Miscellaneous Commands::      Other miscellaneous commands.

Using Info

* Cursor Commands::
* Scrolling Commands::
* Node Commands::
* Searching Commands::
* Xref Commands::
* Window Commands::
* Printing Nodes::
* Other Info Commands::
* Info Variables::

Using Info

* Cursor Commands::        Commands which move the cursor within a node.
* Scrolling Commands::        Commands for moving the node around in a window.
* Node Commands::        Commands for selecting a new node.
* Searching Commands::        Commands for searching an info file.
* Xref Commands::        Commands for selecting cross references.
* Window Commands::        Commands which manipulate multiple windows.
* Printing Nodes::        How to print out the contents of a node.
* Other Info Commands::     A few commands that defy categories.
* Info Variables::        How to change the default behavior of Info.

Selecting Cross References

* Parts of an Xref::            What a cross reference is made of.
* Selecting Xrefs::             Commands for selecting menu or note items.

Manipulating Multiple Windows

* The Mode Line::               What appears in the mode line?
* Basic Windows::               Manipulating windows in Info.
* The Echo Area::               Used for displaying errors and reading input.


File: octave.info,  Node: Preface,  Next: Copying,  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 and John G. Ekerdt at the University of Texas.

   Clearly, Octave is now much more than just another `courseware'
package with limited utiltiy 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 is also currently used in several other undergraduate and
graduate courses in our department, 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.

   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.

   * Karl Berry ([e-mail]) wrote the `kpathsea' library that
     allows Octave to recursively search directory paths for function
     and script files.

   * Georg Beyerle ([e-mail]) contributed code to save
     values in MATLAB's `.mat'-file format, and has provided many
     useful bug reports and suggestions.

   * John Campbell ([e-mail]) wrote most of the file and
     C-style input and output functions.

   * Brian Fox ([e-mail]) wrote the `readline' library used
     for command history editing, and the portion of this manual that
     documents it.

   * A. Scottedward Hodel ([e-mail]) contributed a number
     of functions including `expm', `qzval', `qzhess', `syl', `lyap',
     and `balance'.

   * Kurt Hornik ([e-mail]) provided the `corrcoef',
     `cov', `kurtosis', `pinv', and `skewness' functions.

   * Phil Johnson ([e-mail]) has helped to make
     Linux releases available.

   * Friedrich Leisch ([e-mail]) provided the
     `mahalanobis' function.

   * Ken Neighbors ([e-mail]) has provided many useful
     bug reports and comments on MATLAB compatibility.

   * Rick Niles ([e-mail]) 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 ([e-mail]) provided the initial
     implementation of `fread', `fwrite', `feof', and `ferror'.

   * Tony Richardson ([e-mail]) wrote Octave's image
     processing functions as well as most of the original polynomial
     functions.

   * R. Bruce Tenison ([e-mail]) wrote the `hess'
     and `schur' functions.

   * Teresa Twaroch ([e-mail]) provided the functions
     `gls' and `ols'.

   * Fook Fah Yap ([e-mail]) 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:

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

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

   * 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, Associate Professor, Department of Chemical
     Engineering, The University of Texas at Austin.

   * Richard Stallman, for writing GNU.

   Portions of this document have been adapted from the `gawk',
`readline', `gcc', and C library manuals, published by the Free
Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

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


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

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     675 Mass Ave, Cambridge, MA 02139, 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 Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    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) 19YY  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: octave.info,  Node: Introduction,  Next: Invoking Octave,  Prev: Copying,  Up: Top

A Brief Introduction to Octave
******************************

   This manual documents how to run, install and port Octave, and how
to report bugs.

   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.

   This document corresponds to Octave version 1.1.1.

* Menu:

* Running Octave::
* Simple Examples::
* Executable Octave Programs::
* Comments::
* Errors::


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

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 the `CTRL' key 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: Executable Octave Programs,  Prev: Running Octave,  Up: Introduction

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

     set 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

     set term postscript
     set output "foo.ps"
     replot

This will work for other types of output devices as well.  Octave's
`set' 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

     set term postscript
     set 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 the
`CTRL' key 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 Appendix *Note Command Line Editing::.

Getting Help
------------

   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 carriage return to advance one
line, a space character to advance one page, and `q' to exit the pager.

Help via Info
.............

   The part of Octave's help facility that allows you to read the
complete text of the printed manual from within Octave uses a 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 Appendix *Note Using Info::.


File: octave.info,  Node: Executable Octave Programs,  Next: Comments,  Prev: Simple Examples,  Up: Introduction

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
many Unix systems (1) (and someday on GNU).

   For example, you could create a text file named `hello', containing
the following lines:

     #! /usr/local/bin/octave -qf

     # a sample Octave program
     printf ("Hello, world!\n");

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 (2) as if you
had typed:

     octave hello

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.

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

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

   (2)  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::.


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

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

       and so on...

     endfunction

   The `help' command (*note 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: Errors,  Prev: Comments,  Up: Introduction

Errors
======

   There are two classes of errors that Octave produces when it
encounters input that it is unable to understand, or when it is unable
to perform an action.

   A "parse error" occurs if Octave cannot understand something you
have typed.  For example, if you misspell a keyword,

     octave:13> functon y = f (x) y = x^2; endfunction

Octave will respond immediately with a message like this:

     parse error:

       functon y = f (x) y = x^2; endfunction
               ^

For most parse errors, Octave uses a caret (`^') to mark the point on
the line where it was unable to make sense of your input.  In this
case, Octave generated an error message because the keyword `function'
was misspelled.  Instead of seeing `function f', Octave saw two
consecutive variable names, which is invalid in this context.  It
marked the error at the `y' because the first name by itself was
accepted as valid input.

   Another class of error message occurs 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 expression 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 numbered beginning with the line containing the `function' keyword.
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, say `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: Invoking Octave,  Next: Expressions,  Prev: Introduction,  Up: Top

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 up 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,  Prev: Invoking Octave,  Up: Invoking Octave

Command Line Options
====================

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

`--help'
`-h'
`-?'
     Print short help message and exit.

`--ignore-init-file'
`--norc'
`-f'
     Don't read any of the system or user initialization files at
     startup.

`--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
     `INFO_FILE = "filename"' commands found in the system or user
     startup files.

`--interactive'
`-i'
     Force interactive behavior.

`--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 `LOADPATH =
     "path"' commands found in the system or user startup files.

`--silent'
`--quiet'
`-q'
     Don't print message at startup.

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

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

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

`FILE'
     Execute commands from FILE.